SECTION I: WELCOME

Welcome to the guessing game README!

First of all, Guess is written and distributed by Lim Ding Wen, 2014. I distribute the software AS IS and do not provide any warranty. However as it is under the GNU License, you may edit it and redistribute it to your will. (Basically I don't care what you do with this thing.) View the full license here: https://gnu.org/licenses/gpl.html

SECTION II: CONTENTS OF PACKAGE

Files included in this package: - guess (the binary) - guess.o (the object) - guess.asm (the source) - Makefile (the compilation procedure) - README (this)

SECTION III: HOW TO USE THE FILES

To run the program, type ./guess and press return. This will run the binary, guess. To edit the program source code, open guess.asm with your favourite text or code editor. You can also edit the README and the Makefile. guess and guess.o are not meant to be edited. They are generated by various compilation commands and procedures as stated in the Makefile.

To compile guess and guess.o:

Option 1: Use the Makefile
If you have "make" installed (or if not, go install it), then you can simply type "make" and press ENTER to run it when you are in this directory, in the terminal/console. "make" will run the Makefile for you and generate an executable.

Option 2: Compile it yourself
If you don't have "make" installed and you don't want to, then you can open up the Makefile. From there, copy and paste the commands (those that are indented) into the terminal/console while in this directory, and press ENTER to run it. copy-paste-run the commands starting with "nasm" first, then copy-paste-run the commands starting with "ld". When you are done, you can close the Makefile and see that you have created an executable.

If nothing works and you have no idea what to do, contact me with any one of the contact options at the very end of this README.

SECTION IV: SUPPORTED SYSTEMS

Guess is tested on Ubuntu Linux x86 32-bit. Guess, as distributed in this package, should run on any *nix varient that: - Runs on x86 and supports x86 32-bit. - Has an stdin, /dev/random and stdout file. - Supports syscalls 1, 3, 4, 5 and 6. - Calls syscalls by interuppting 0x80. - Returns syscall values by eax. - Accepts syscall values by the 32-bit registers. - Has a stack. - Supports the imul and idiv opcodes. - Is not currently being crushed by an elephant.

Although it may not run on systems that fufill these requirements, or, may run on systems that do not fufill these requirements, depending on various special reasons. I only provide this list as a guideline.

SECTION V: HOW TO PATCH FOR AN UNSUPPORTED SYSTEM
SECTION V.1: MAC OS X

Guess can be edited to run on any system. Here is a guideline for modifying guess to run on Mac OS X: - Mac OS X requires 1 pad on the stack when interupting the kernel. - Mac OS X accepts syscall values by the stack, ebx on the bottom. - Suggestion: modify the __syscall so that it pushes ebx, ecx and edx in order before calling __syscall. - It runs in the same way as Ubuntu, the tested system, in all other ways. - I have written a guide on how to hack guess to run on Mac OS X. View the other guide file, HACK_MACOSX, for instructions.

SECTION V.2: WINDOWS

- I'm not really sure. Try using mingw to run the guess binary. I for myself have no idea how to hack guess to run on Windows. Sorry.

SECTION VI: PROGRAM DESCRIPTION

You can use or copy etc. any of the functions or procedures in here, such as atoi or itoa, to your own will!

FUNCTIONS

_start: Start of program.

// You can use these inline code in your own programs for getting a random value into a range. _modup: Label for adding... _moddown: Label for subtracting... _modend: End modding; add or subtract to get into 1-100 range.

_loop: Loop for the entire prompting to toohigh/low.

// You can use these inline code in your own programs for turning a string into an integer. (atoi) _loopconvert: Loop for converting a to i. _loopconvert_nomul: Entry point for _loopconvert, where we don't mul first. _reenter: Jump here if there is any non-digit characters found.

// You can modify this area to add custom penalties etc. _toohigh: Too high! Write and go back to _loop. _toolow: Too low! Write and go back to _loop. _again: BUT before going back to _loop, check if you have lost. _lose: If you lost (ran out of tries), go here.

_convertok: When atoi finished, jump here and decide if too high/low or win. _exit: Jump here when you win or lose, to exit!

PROCEDURES

// You can use these procedures (all together, or they won't work) in your own programs to turn an integer into a string. Call it by either __itoa or __itoa_knowndigits. More details in the source. __itoa_init: Init function for itoa and itoaknowndigits. __itoa: Accepts eax. Is the jump-to point for itoa. __itoa_loop: Loop for finding out how many digits it has. __itoa_knowndigits: Accepts eax, ebx and ecx. Same as __itoa but lets you define how many digits it has. Also for optimization purposes. __itoa_loopend: When __itoa_loop ends. __itoa_loop2: Loop for converting i into a character and put into a. Also returns eax and ebx, preserving ecx and edx.

// You can use these procedures in your own programs to make syscall-ing cleaner by a bit. __exit to __close: Moves the appropiate syscall number into eax. __syscall: Interupts the kernel to execute syscall number in eax.

DATA

// How about changing this to a custom random file to hack the answer? The program reads 4 bytes directly from this, and then modulo it into 1-100. _dev_random: The /dev/random filepath.

// How about creating a super-crazy guessing game from 1 to 1000? Million? maxrand: Maximum random number (100). tries: Number of tries you have.

// How about making funny messages? *_len: Length of string by minusing addresses. prompt: Prompting user to input number. hello: Welcome message. reenter: Message when there is an unrecognized character.

toohigh: Message when it was too high. toolow: Message when it was too low.

youwin: Message when you win! youlose: Message when you lose. youlose2: Second part of youlose, after the number is shown.

goodbye: Message when program ends normally. _ok: Message when program ends normally with OK.

BSS

// Don't touch this unless you know what you are doing. This is for internal mathematical operations and storage use. randint: To store the random correct answer. downsize: Used to downsize a 32-bit register to a 8-bit, to store into a.

// Also for internal operations. _itoabuf: Used by itoa as a buffer to store the final a.

// Also for internal operations. Know what you are doing. inputbuf: Buffer used to store user input when prompted to input number. inputbuf_len: Length of buffer (to prevent overflow).

SECTION VII: FINAL WORDS

And with that, I wish you all the best in the guessing game, and of course, happy hacking, and have fun!

(Suggestion: Why not keep scores, and when you win with "x" amount of tries left, you gain "x" points. The player with the most score wins!)

• Lim Ding Wen, 2 December 2014

limdingwen@icloud.com Singapore 659442 http://tinyurl.com/limdingwen-website