src_baseop.txt

Base operations (baseop.c, baseop.h)
[NOTE: this file is not a Diff file!]

Task: provides basic, possibly reusable functionality, not specific to XOR-FD.

>>> baseop.c

--- void signals_setup()
	* assigns the function `signal_handler()' to the signals SIGHUP and SIGTERM

--- void signal_handler(int signal)
	* this is the function that treats the SIGHUP and SIGTERM signals
	* for SIGHUP, no action
	* for SIGTERM, set `_global_run_flag_' to `XORFD_ABORT' (this will cause the program to abort)
	* for SIGINT, same as SIGTERM
	* for SIGQUIT, same as SIGTERM

--- void print_usage(const char *program_filename, const char *message)
	* prints a predermined usage information text, prepending and appending `program_filename' and `message' respectively
	* `program_filename' and `message' are checked for sanity, and will be truncated if exceeding `DEFAULT_PROGRAM_FILENAME_SIZE' and `DEFAULT_MESSAGE_SIZE' respectively, or will be replaced by `DEFAULT_PROGRAM_FILENAME' and `DEFAULT_ERROR_MESSAGE' respectively if they're NULL or NIL ('\0')

--- unsigned char get_percentage(const off_t full, const off_t current)
	* returns percentage that `current' represents out of `full'
	* checks so that `full' is not 0 (zero) so as to prevent division by zero, in which case it will return a bogus value of 255
	* error correction is minimal, so the function can return values larger than 100, from 0 up to 255, for user awareness purposes

--- off_t get_file_size_tame(FILE *file)
	* uses file status functions to retrieve the size of `file'
	* it is "tame" because it does not try to close the `file' nor does it try to `exit()' upon encountering an error

--- off_t get_file_size(FILE *file)
	* uses file status functions to retrieve the size of `file'
	* it will print an error to stderr, attempt to close the `file' and `exit()' if an error is encountered

>>> baseop.h

--- XORFD_ABORT
	* a possible value for the global variable `_global_run_flag_'
	* `compute()' function is interrupted and program aborts if this value is set

--- XORFD_CONTINUE
	* this is the initial value of `_global_run_flag_'

--- FCLOSE_VERBOSE(file)
	* this macro expands to an if() structure which checks success for `fclose(file)', printing an error message to stderr if an error was encountered
