Previous: C to Guile API, Up: Reference

### 4.15 C functions

This section lists all documented C functions in the program. It contains many references and is self-generated from C comments using gdoc by Simon Josefsson.

In order to reduce the number of pages of printed output, this complete reference is, by default, disabled in printable versions of the documentation (PostScript, PDF). This is both to make the manual more readable and to avoid wasting paper. Think about the environment.

It is however available in the HTML version of the documentation, which you can read online. The following adresses contain various view on the source code, giving informations on all the internal and public C interfaces:

- http://www.gnu.org/software/liquidwar6/manual/html_node/C-functions.html: the gdoc reference, generated from source code comments.
- http://www.gnu.org/software/liquidwar6/coverage/: the lcov output when running `./liquidwar6 --test`. It shows what functions are actually tested, and how many times they are called.
- http://www.gnu.org/software/liquidwar6/global/: the GNU global output gives complete cross-references, macros, headers, contants declaration. It's a very good place to start browsing the code.
- http://www.gnu.org/software/liquidwar6/cyclo/: the pmccabe output shows the cyclomatic complexity of functions. It enables the programmer to spots the “ugly” and dangerous parts of the program.

#### 4.15.1 libliquidwar6

— Function: void lw6_resize_callback (lw6gui_video_mode_t * video_mode)

> video_mode: the new video mode

> This callback is here because gfx needs to update the config when the screen is resized. But... we did not want to make gfx depend on cfg "directly". It's cleaner to pass parameters with Scheme, in the long run, it should make things easier. So this callback is the solution. Another side effect is that this way there's a tangible obvious trace of this updating of config status by the gfx module. Seeing it sticking out like a thumb isn't a bad thing.

> Return value: none

— Function: void lw6_release ()

> Functions which will call `quit`(), `free`(), `destroy`() on whatever smob object that has threads and/or requires hardware ressources. This is to be called before the Guile interpreter ends. This is because when it garbage collects objects at the end of the program, it has no idea of what order to use when freeing objects. So if an object which uses another one in a thread is freed after the other is freed, you get a (rather unexplainabled if not warned) segfault.

> Return value: none

— Function: void lw6_exit ()

> Will exit the program. If there are some display objects alive, that is if there's a display activated, it will find them and send a quit event, giving a chance to the to exit cleanly. If not, it will just call `exit`() directly.

> Return value: none

— Function: int lw6_fix_env (int argc, char * [] argv)

> argc: number of args as passed to main argv: array of strings as passed to main

> Fixes environment variables (path related) so that program can find its requirements. This must be called early in the program flow (else other calls might fail).

> Return value: 1 if success, 0 if failure

— Function: int lw6_register_funcs ()

> Register all the functions, make them callable from Guile. This is a very simple yet long and very usefull function, without it Guile has no knowledge of what LW6 is.

> Return value: 1 on success, 0 if failed.

— Function: extern void lw6_cns_handler (char * c_line)

> c_line: the line typed by the user

> This function will be called every time a message is typed on the console. It runs the given line in the current Guile environment.

> Return value: none

— Function: int lw6_init_global (int argc, char * [] argv)

> argc: number of args as passed to main argv: array of strings as passed to main

> Initializes global values to their defaults.

> Return value: 1 on success, 0 if failed

— Function: void lw6_quit_global ()

> argc: number of args as passed to main argv: array of strings as passed to main

> Frees global values. Will also garbage collect objects in case Guile failed to do it perfectly (or we failed to tell Guile how to do it).

> Return value: none.

— Function: int lw6_main (int argc, char * [] argv)

> argc: the argc parameter of the `main`() function, that is, the number of command-line args.

> argv: the argv parameter of the `main`() function, that is, an array containing pointers on command-line args.

> This function is directly called by `main`(). This means by linking against libliquidwar6 and calling it, you would have a program that is almost exactly the "official" upstream liquidwar6 binary, except you can tweak it and have all the power to call whatever other functions you like, embed it. In short, everything the binary does, you can do it in your own binarn, by linking against the library and calling this function.

> Return value: 1 if success, zero if failure. Note that this is the "standard" C / liquidwar6 way to proceed, but your `main`() function should return 0 if success, else an error code. Typical use is "return !lw6_main(argc, argv);".

— Function: int lw6_process_non_run_options (int argc, char * [] argv, int * run_game)

> argc: the number of command-line args, as passed to `main()`

> argv: an array of strings containing command-line args, as passed to `main()`

> run_game: a pointer to a boolean which will contain true (1) if the game must be launched, or false (0) if the option is such that game must be skipped. Example: –copyright, –help, ...

> Return value: non-zero if success, 0 if error. The error can be, for instance, the test suite returning "no, tests were not OK".

— Function: void lw6_print_help ()

> Displays a short help message.

> Return value: none

— Function: void lw6_print_version ()

> Displays the version of the game.

> Return value: none

— Function: void lw6_print_short_copyright ()

> Displays the copyright of the game (short version).

> Return value: none

— Function: void lw6_print_long_copyright ()

> Displays the copyright of the game (long version).

> Return value: none

— Function: void lw6_print_bench (float bench_result)

> Displays the program bench value.

> Return value: none

— Function: void lw6_print_pedigree ()

> Displays the program pedigree, think of this as version on steroids.

> Return value: none

— Function: void lw6_print_host ()

> Displays the host on which the program was compiled.

> Return value: none

— Function: void lw6_print_audit (int argc, char * [] argv)

> Displays various paths used by the game.

> Return value: none

— Function: void lw6_print_modules ()

> Displays the list of modules compiled with the game.

> Return value: none

— Function: void lw6_print_list_quick ()

> Displays the list of 'quick' options.

> Return value: none

— Function: void lw6_print_list_doc ()

> Displays the list of 'doc' options.

> Return value: none

— Function: void lw6_print_list_show ()

> Displays the list of 'show' options.

> Return value: none

— Function: void lw6_print_list_path ()

> Displays the list of 'path' options.

> Return value: none

— Function: void lw6_print_list_players ()

> Displays the list of 'players' options.

> Return value: none

— Function: void lw6_print_list_input ()

> Displays the list of 'input' options.

> Return value: none

— Function: void lw6_print_list_graphics ()

> Displays the list of 'graphics' options.

> Return value: none

— Function: void lw6_print_list_sound ()

> Displays the list of 'sound' options.

> Return value: none

— Function: void lw6_print_list_network ()

> Displays the list of 'network' options.

> Return value: none

— Function: void lw6_print_list_map ()

> Displays the list of 'map' options.

> Return value: none

— Function: void lw6_print_list_map_rules ()

> Displays the list of 'map rules' options.

> Return value: none

— Function: void lw6_print_list_map_hints ()

> Displays the list of 'map hints' options.

> Return value: none

— Function: void lw6_print_list_map_style ()

> Displays the list of 'amp style' options.

> Return value: none

— Function: void lw6_print_list_funcs ()

> Displays the list of 'funcs'.

> Return value: none

— Function: void lw6_print_list_hooks ()

> Displays the list of 'hooks'.

> Return value: none

— Function: void lw6_print_list_tuning ()

> Displays the list of 'tuning' options.

> Return value: none

— Function: void lw6_print_list_aliases ()

> Displays the list of options aliases.

> Return value: none

— Function: void lw6_print_list ()

> Displays the list of all known options.

> Return value: none

— Function: void lw6_print_about (char * keyword)

> Displays the about message for a keyword.

> Return value: none

— Function: void lw6_print_hello (int argc, char * [] argv)

> Displays 'hello' at the beginning of the program.

> Return value: none

— Function: void lw6_print_goodbye ()

> Displays 'goodbye', typically use at end of program to know it's over and everything went fine.

> Return value: none

— Function: SCM lw6_make_scm_dsp (lw6dsp_backend_t * c_dsp)

> c_dsp: the display object

> Creates an SCM 'dsp' object from C data.

> Return value: the SCM object

— Function: lw6dsp_backend_t * lw6_scm_to_dsp (SCM dsp)

> dsp: the dsp to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'dsp' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_dsp_smob (lw6_dsp_smob_t * dsp_smob)

> dsp_smob: the smob to free

> Frees a dsp smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_snd (lw6snd_backend_t * c_snd)

> c_snd: the sound object

> Creates an SCM 'snd' object from C data.

> Return value: the SCM object

— Function: lw6snd_backend_t * lw6_scm_to_snd (SCM snd)

> snd: the snd to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'snd' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_snd_smob (lw6_snd_smob_t * snd_smob)

> snd_smob: the smob to free

> Frees a snd smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_map (lw6map_level_t * c_map)

> c_map: the map object

> Creates an SCM 'map' object from C data.

> Return value: the SCM object

— Function: lw6map_level_t * lw6_scm_to_map (SCM map)

> map: the map to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'map' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_map_smob (lw6_map_smob_t * map_smob)

> map_smob: the smob to free

> Frees a map smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_menu (lw6gui_menu_t * c_menu)

> c_menu: the menu object

> Creates an SCM 'menu' object from C data.

> Return value: the SCM object

— Function: lw6gui_menu_t * lw6_scm_to_menu (SCM menu)

> menu: the menu to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'menu' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_menu_smob (lw6_menu_smob_t * menu_smob)

> menu_smob: the smob to free

> Frees a menu smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_game_struct (lw6ker_game_struct_t * c_game_struct, SCM map)

> c_game_struct: the game struct object

> map: the map (SCM object) referenced

> Creates an SCM 'game-struct' object from C data. Passing the map object enables the garbage collector not to free the map until the game struct is freed.

> Return value: the SCM object

— Function: lw6ker_game_struct_t * lw6_scm_to_game_struct (SCM game_struct)

> game_struct: the game_struct to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'game_struct' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_game_struct_smob (lw6_game_struct_smob_t * game_struct_smob)

> game_struct_smob: the smob to free

> Frees a game_struct smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_game_state (lw6ker_game_state_t * c_game_state, SCM game_struct)

> c_game_state: the game state object

> game_struct: the game struct (SCM object) referenced

> Creates an SCM 'game_state' object from C data. Passing game_struct enables the garbage collector not to free the game_struct until the game_state is freed.

> Return value: the SCM object

— Function: lw6ker_game_state_t * lw6_scm_to_game_state (SCM game_state)

> game_state: the game_state to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'game_state' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_game_state_smob (lw6_game_state_smob_t * game_state_smob)

> game_state_smob: the smob to free

> Frees a game_state smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_pilot (lw6pil_pilot_t * c_pilot)

> c_pilot: the pilot object

> Creates an SCM 'pilot' object from C data.

> Return value: the SCM object

— Function: lw6pil_pilot_t * lw6_scm_to_pilot (SCM pilot)

> pilot: the pilot to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'pilot' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_pilot_smob (lw6_pilot_smob_t * pilot_smob)

> pilot_smob: the smob to free

> Frees a pilot smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_bot (lw6bot_backend_t * c_bot, SCM game_state, SCM pilot)

> c_bot: the bot object

> game_state: the game state

> pilot: the pilot

> Creates an SCM 'bot' object from C data. Passing game_state and pilot enables the garbage collector not the free them until bot is freed.

> Return value: the SCM object

— Function: lw6bot_backend_t * lw6_scm_to_bot (SCM bot)

> bot: the bot to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'bot' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_bot_smob (lw6_bot_smob_t * bot_smob)

> bot_smob: the smob to free

> Frees a bot smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_look (lw6gui_look_t * c_look)

> c_look: the look object

> Creates an SCM 'look' object from C data.

> Return value: the SCM object

— Function: lw6gui_look_t * lw6_scm_to_look (SCM look)

> look: the look to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'look' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_look_smob (lw6_look_smob_t * look_smob)

> look_smob: the smob to free

> Frees a look smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_loader (lw6tsk_loader_t * c_loader)

> c_loader: the loader object

> Creates an SCM 'loader' object from C data.

> Return value: the SCM object

— Function: lw6tsk_loader_t * lw6_scm_to_loader (SCM loader)

> loader: the loader to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'loader' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_loader_smob (lw6_loader_smob_t * loader_smob)

> loader_smob: the smob to free

> Frees a loader smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_db (lw6p2p_db_t * c_db)

> c_db: the database object

> Creates an SCM 'db' object from C data.

> Return value: the SCM object

— Function: lw6p2p_db_t * lw6_scm_to_db (SCM db)

> db: the db to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'db' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_db_smob (lw6_db_smob_t * db_smob)

> db_smob: the smob to free

> Frees a db smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_node (lw6p2p_node_t * c_node, SCM db)

> c_node: the node object

> db: the db (SCM object) referenced

> Creates an SCM 'node' object from C data. Passing db enables the garbage collector not to free db until node is freed.

> Return value: the SCM object

— Function: lw6p2p_node_t * lw6_scm_to_node (SCM node)

> node: the node to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'node' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_node_smob (lw6_node_smob_t * node_smob)

> node_smob: the smob to free

> Frees a node smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: int lw6_register_smobs ()

> Register all smobs to Guile.

> Return value: 1 on success, 0 if failed.

— Function: int lw6_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the liquidwar6 core module test suite, this will mostly test how Guile script integration works, loading a sample script and running it. It does not launch all the other sub modules tests.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.2 libbot

— Function: int lw6bot_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `bot` module test suite. Will try several engines and query basic moves.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.3 libcfg

— Function: int lw6cfg_parse_command_line (void * context)

> context: opaque pointer on a context

> Overwrites any existing option with command line args

> Return value: 1 if success, 0 if error

— Function: int lw6cfg_defaults (void * context)

> context: opaque pointer on a context

> Sets all values to their defaults.

> Return value: 1 if success, 0 if error

— Function: int lw6cfg_merge_env (void * cfg_context)

> cfg_context: a context returned by `lw6cfg_init`

> Overwrites any existing vale in the config with environment variables prefixed by LW6_.

> Return value: 1 if successfull, 0 if error.

— Function: char * lw6cfg_format (char * key, char * value, lw6hlp_type_t type)

> key: the key of the value to format

> value: the value to format

> type: the type of the value to format

> Formats, converts, a given value to its cannonical representation. Booleans will be converted to true/false, strings containing integers will be stripped from junk, and so on. This is a performance killer but will ensure everything is correct.

> Return value: a newly allocated string, containing the same as the input, but reformatted the pedantic way.

— Function: char * lw6cfg_format_guess_type (char * key, char * value)

> key: the key of the value to format

> value: the value to format

> Formats, converts, a given value to its cannonical representation. Booleans will be converted to true/false, strings containing integers will be stripped from junk, and so on. This is a performance killer but will ensure everything is correct. This function will automatically guess the type of the value from its description in the help system.

> Return value: a newly allocated string, containing the same as the input, but reformatted the pedantic way.

— Function: int lw6cfg_load (void * cfg_context, char * filename)

> cfg_context: a context returned by `lw6cfg_init`

> filename: a file path, absolute or relative

> Loads the given config file, and stores its values into the current context. Parameters which are both in the config file and given as command line parameters, will be taken from the command-line.

> Return value: 1 if successfull, 0 if error.

— Function: int lw6cfg_save (void * cfg_context, char * filename)

> cfg_context: a context returned by `lw6cfg_init`

> filename: a file path, absolute or relative

> Save current options into the given config file. Before saving the file, all command line arguments will be read and will override current values. This means the saved file will contain values given as command line arguments.

> Return value: 1 if successfull, 0 if error.

— Function: void * lw6cfg_init (int argc, char * [] argv)

> argc: number of command line arguments, as given to `main`

> argv: a list of command line arguments, as given to `main`

> Initializes a config context object. This object is hidden behind an opaque void * pointer to avoid direct access to its elements.

> Return value: an opaque pointer, must be freed with `lw6cfg_quit`.

— Function: void lw6cfg_quit (void * cfg_context)

> cfg_context: a context returned by `lw6cfg_init`

> Frees a config cfg_context object. You must call this once you're done with the context.

> Return value: none.

— Function: void lw6cfg_reset (int argc, char * [] argv)

> argc: number of command line arguments, as given to `main`

> argv: a list of command line arguments, as given to `main`

> Overwrites the config file with defaults. Use this to get rid of old configurations.

— Function: int lw6cfg_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `cfg` module test suite.

> Return value: 1 if test is successfull, 0 on error.

— Function: char * lw6cfg_unified_get_value (int argc, char * [] argv, char * key)

> argc: number of command-line args, as passed to `main`

> argv: arry of command-line args, as passed to `main`

> key: the key to query

> Unified "value" getter, which gets informations from environment variables, command line, and config file. The rules is that the command-line argument always has the last word. It will override any other value. Follows environment variables, which will be used if no command-line argument is supplied. Note that these are "LW6_" prefixed and uppercased environment variables as opposed to lowercased and "dash-separated" keys. Finally, if there's no environment variable, nor any config-file corresponding entry, the value will be searched in the config file. If there's no information in the config file, NULL is returned.

> Return value: a string with the value. Can be NULL. Must be freed.

— Function: char * lw6cfg_unified_get_user_dir (int argc, char * [] argv)

> argc: number of command-line args, as passed to `main`

> argv: arry of command-line args, as passed to `main`

> Gets the user dir, taking all parameters in account, that's to say the "LW6_USER_DIR" env value, the "–user-dir" command-line paramater and the LW6DEF_USER_DIR config file entry.

> Return value: the directory path, might be NULL, must be freed.

— Function: char * lw6cfg_unified_get_log_file (int argc, char * [] argv)

> argc: number of command-line args, as passed to `main`

> argv: arry of command-line args, as passed to `main`

> Gets the log file, taking all parameters in account, that's to say the "LW6_LOG_FILE" env value, the "–log-file" command-line paramater and the LW6DEF_LOG_FILE config file entry.

> Return value: the directory path, might be NULL, must be freed.

— Function: char * lw6cfg_unified_get_music_path (int argc, char * [] argv)

> argc: number of command-line args, as passed to `main`

> argv: arry of command-line args, as passed to `main`

> Gets the user dir, taking all parameters in account, that's to say the "LW6_MUSIC_PATH" env value, the "–music-path" command-line paramater and the LW6DEF_MUSIC_PATH config file entry.

> Return value: the directory path, might be NULL, must be freed.

— Function: char * lw6cfg_unified_get_map_path (int argc, char * [] argv)

> argc: number of command-line args, as passed to `main`

> argv: arry of command-line args, as passed to `main`

> Gets the user dir, taking all parameters in account, that's to say the "LW6_MAP_PATH" env value, the "–map-path" command-line paramater and the LW6DEF_MAP_PATH config file entry.

> Return value: the directory path, might be NULL, must be freed.

#### 4.15.4 libcli

— Function: lw6cli_oob_t * lw6cli_oob_new (char * public_url, lw6cli_verify_callback_func_t verify_callback_func, void * verify_callback_data)

> public_url: the address of the distant server to test

> verify_callback_func: a function which will be called when a node has been verified

> verify_callback_data: additionnal data passed to the callback func

> Create a new OOB structure, copying required objects. We need to make copies for this is for usage in a separate thread. The thread member is not set here since the right way to do things is first to set up data then to fire the thread.

> Return value: new object

— Function: void lw6cli_oob_free (lw6cli_oob_t * oob)

> oob: the object to free

> Frees an OOB structure.

> Return value: none

— Function: int lw6cli_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `cli` module test suite.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.5 libcns

— Function: int lw6cns_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `cns` module test suite.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.6 libdsp

— Function: lw6dsp_backend_t * lw6dsp_create_backend (int argc, char * [] argv, char * gfx_backend_name)

> argc: argc as passed to `main`

> argv: argv as passed to `main`

> gfx_backend_name: the id/name of the gfx backend to use

> Creates a dsp_backend object. The created object won't be displaying things until `lw6dsp_init` is called. No thread is created, but the graphics backend is loaded into memory. If video mode is not available, it will appear later, when trying to start displaying things, this function only allocates memory and checks code is available in case of a dynamically loaded gfx backend.

> Return value: a newly allocated object.

— Function: void lw6dsp_destroy_backend (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend object to free

> Frees all ressources used by a dsp_backend object. Note that you must call this on a inactive 'stopped' dsp_backend object.

> Return value: none.

— Function: char * lw6dsp_repr (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the object to represent

> Gives a short human-readable description of the object.

> Return value: a newly allocated string, must be freed.

— Function: int lw6dsp_init (lw6dsp_backend_t * dsp_backend, lw6dsp_param_t * param, lw6gui_resize_callback_func_t resize_callback)

> dsp_backend: the dsp_backend to start

> param: parameters to pass to the display funcs

> resize_callback: a function which will be called when there's a resize event

> Starts a dsp_backend object, that is, fire a separate thread and start rendering. This will set up a video mode, so it's very likely to fail if for some reason the video context isn't right, for instance if you try to set up graphical stuff but only have console access.

> Return value: 1 if success, 0 if error.

— Function: void lw6dsp_quit (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to stop

> Stops a dsp_backend, that is, cancel rendering and unset the video mode, hardware shouldn't be used any more after this call.

> Return value: none.

— Function: int lw6dsp_update (lw6dsp_backend_t * dsp_backend, lw6dsp_param_t * param)

> dsp_backend: the dsp_backend to update

> param: parameters to pass to the dsp_backend funcs

> Passes a new set of parameters to the display function. This is in fact the only way to pass informations to the dsp_backend object once it's been started. This function will acquire a mutex, copy parameters, then give control back to the main thread while display keeps on going with new parameters in the background. It will get input informations. You really must call it often otherwise the screen won't get updated, or, at least, it will always display the same informations. It should be reasonnable to call this 10 or 20 times per second, the display itself can be faster, run at 60 or 100 fps to show smooth animation (eye candy).

> Return value: 1 if success, 0 if error.

— Function: int lw6dsp_get_nb_frames (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to query

> Returns the number of frames displayed since the display was started.

> Return value: the number of frames displayed.

— Function: int lw6dsp_get_last_frame_rendering_time (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to query

> Returns the rendering time of the last frame. Gives clues about performance.

> Return value: the number of milliseconds it took to draw screen

— Function: int lw6dsp_get_instant_fps (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to query

> Returns the current frames per sec display rate. This is the instant value, it changes very often even if display seems smooth.

> Return value: the current instant display rate.

— Function: int lw6dsp_get_average_fps (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to query

> Returns the current frames per sec display rate. This is not absolutely accurate but fits for displaying info to the player, it's an average.

> Return value: the current averaged display rate.

— Function: int lw6dsp_get_video_mode (lw6dsp_backend_t * dsp_backend, lw6gui_video_mode_t * video_mode)

> dsp_backend: the dsp_backend to query

> video_mode: a structure which will contain the results

> Returns the current video mode, the one obtained by the driver. This function is also a way to know wether display is running correcly or not, by testing its return value.

> Return value: 1 if ok, 0 if failure (mode not set)

— Function: int lw6dsp_get_fullscreen_modes (lw6dsp_backend_t * dsp_backend, lw6gui_fullscreen_modes_t * fullscreen_modes)

> dsp_backend: the dsp_backend to query

> fullscreen_modes: a structure which will contain the results

> Returns the current available fullscreen modes. Note that this one will only work if display is started, unlike `lw6gfx_get_fullscreen_modes` which is used internally. The reason is that in this dsp module context, we need the thread to be launched, and the thread does start/stop display on its own.

> Return value: 1 if ok, 0 if failure (mode not set)

— Function: void lw6dsp_param_zero (lw6dsp_param_t * param)

> param: the structure to initialize

> Fills a display param struct with zeros, this is mandatory before any use. Think of it as a raw memset.

> Return value: none.

— Function: int lw6dsp_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the test suite for the dsp module. In check (0) mode, won't test much to avoid failure because of missing graphical environment.

> Return value: 1 if OK, 0 if error.

#### 4.15.7 libdyn

— Function: lw6dyn_dl_handle_t * lw6dyn_dlopen_backend_so (char * so_file)

> Opens a .so file directly, using a valid (full) path name.

> Return value: a handle to the module, once it's opened. You might still need to call a module specific `init`() function, but it's another story.

— Function: lw6dyn_dl_handle_t * lw6dyn_dlopen_backend (int argc, char * [] argv, char * top_level_lib, char * backend_name)

> argc: the number of command-line arguments as passed to `main`

> top_level_lib: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category.

> Opens a .so file corresponding to the given backend, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories.

> Return value: a handle to the module, once it's opened. You might still need to call a module specific `init`() function, but it's another story.

— Function: int lw6dyn_dlclose_backend (lw6dyn_dl_handle_t * handle)

> handle: the backend to close.

> Closes an opened backend. Note that you must call any backend specific clear, destroy, deinit, exit, function before.

> Return value: 1 if success, 0 on error.

— Function: void * lw6dyn_dlsym (lw6dyn_dl_handle_t * handle, char * func_name)

> handle: the backend concerned

> func_name: the function name, as a NULL terminated string

> Finds a C function in the given backend.

> Return value: a pointer to the function, NULL if not found.

— Function: lw6sys_assoc_t * lw6dyn_list_backends (int argc, char * [] argv, char * top_level_lib)

> argc: the number of command line args, as passed to main

> argv: the commind line args, as passed to main

> top_level_lib: the library category to query (gfx, snd, cli, srv ...)

> Returns an assoc which lists all the available modules. The key of the assoc entries in the module internal name such as 'gl' and the value associated is a NULL terminated string describing the module, for instance 'OpenGL'.

> Return value: an assoc object containing key/label pairs.

— Function: char * lw6dyn_path_find_backend (int argc, char * [] argv, char * top_level_lib, char * backend_name)

> argc: the number of command-line arguments as passed to `main`

> top_level_lib: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category.

> backend_name: the actual name of the backend, this is the name of the .so file, between "libmod_" and ".so". For instance, to find "libmod_gl.so", the right argument is "gl".

> Get the full path to a .so file corresponding to the given backend, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories.

> Return value: the full path of the .so file, needs to be freed.

— Function: int lw6dyn_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `dyn` module test suite, testing most (if not all...) functions. Will try to load libraries and query them for standard LW6-expected functions.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.8 libgfx

— Function: int lw6gfx_init (lw6gfx_backend_t * backend, lw6gui_video_mode_t * video_mode, lw6gui_resize_callback_func_t resize_callback)

> backend: the graphical backend to use

> video_mode: the video mode to use at start up

> resize_callback: a callback function which will be called at each resize event

> Sets up the graphical backend for good, initializing a video mode and allocating ressources. This call can typically fail if there's no device available, if the user doesn't have enough rights to access the hardware, and so on.

> Return value: 1 on success, 0 if not

— Function: void lw6gfx_quit (lw6gfx_backend_t * backend)

> backend: the backend to free

> Uninitializes the backend, that is, exits the graphical mode. All threads that use graphics must be closed when this is called.

> Return value: none.

— Function: char * lw6gfx_repr (lw6gfx_backend_t * backend)

> backend: the backend to represent

> Returns a readable version of the backend object.

> Return value: a newly allocated pointer.

— Function: int lw6gfx_set_video_mode (lw6gfx_backend_t * backend, lw6gui_video_mode_t * video_mode)

> backend: the backend to use

> video_mode: the new video mode

> This function changes the video mode. Note that the first time you set up the graphical environment you must call `lw6gfx_init` but to change the current mode, use this function. It should reload backend data automatically if needed (textures for instance). Note that before giving up and failing this function will try alternate video modes, and you're not garanteed to have the right mode after the call, even if it returns true. To check this, use `lw6gfx_get_video_mode`.

> Return value: 1 on success, 0 on failure;

— Function: int lw6gfx_get_video_mode (lw6gfx_backend_t * backend, lw6gui_video_mode_t * video_mode)

> backend: the backend to use

> video_mode: the current video mode (will be overwritten, out parameter)

> This function returns the current video mode.

> Return value: 1 on success, 0 on failure;

— Function: int lw6gfx_get_fullscreen_modes (lw6gfx_backend_t * backend, lw6gui_fullscreen_modes_t * fullscreen_modes)

> backend: the backend to use

> fullscreen_modes: the available fullscreen modes (will be overwritten, out parameter)

> This function returns the current video mode.

> Return value: 1 on success, 0 on failure;

— Function: lw6gui_input_t * lw6gfx_pump_events (lw6gfx_backend_t * backend)

> backend: the backend to use

> This function "pumps" events, that is gets pending events, puts them in queues, maintains internal states up to date. You really must call this very often or no input will be processed at all.

> Return value: a pointer on the internal input state, musn't be freed.

— Function: int lw6gfx_display (lw6gfx_backend_t * backend, int mask, lw6gui_look_t * look, lw6map_level_t * level, lw6ker_game_struct_t * game_struct, lw6ker_game_state_t * game_state, lw6pil_local_cursors_t * local_cursors, lw6gui_menu_t * menu, float progress, float fps, float mps, char ** log_list, int capture, int gfx_debug, int debug_team_id, int debug_layer_id)

> backend: the graphical backend to use

> mask: display flag, tells what to display

> look: the look, the skin, contains display options

> level: the level to display

> game_struct: the game_struct associated with the level

> game_state: the game_state associated with the level

> local_cursors: the cursor to center the focus on

> menu: the menu to display

> progress: the value of the progress indicator

> fps: the number of frames per second to display

> mps: the number of moves per second to display

> log_list: log messages to display

> capture: wether to enable capture mode or not

> gfx_debug: wether to enable gfx debugging tools

> debug_team_id: for debug display, team to display informations about

> debug_layer_id: for debug display, layer to display

> This is the major drawing function, the one that encapsulates all others. As the program uses a separate thread to display things, we just pass this function many parameters, and let it do its job alone. So many parameters might sometimes be useless. It also allows the graphics backend decide wether menus and hud and background should interact. Or not.

> Return value: 1 on success, 0 on failure.

— Function: int lw6gfx_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `gfx` module test suite. In check-only mode, this function won't test many things, for it requires a graphical mode to be available to perform the complete test.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.9 libglb

— Function: char * lw6glb_base64_encode_bin (char * buf, int size)

> buf: the data to encode

> size: the size of data to encode

> Encodes data into base64. Memory allocation is done automatically.

> Return value: newly allocated string.

— Function: char * lw6glb_base64_decode_bin (int * size, char * base64_str)

> size: the size of the decoded data

> base64_str: the string to decode

> Decodes data from base64. Memory allocation is done automatically. Note that this function only works for strings, other data might not be handled correctly.

> Return value: newly allocated pointer, NULL on error.

— Function: char * lw6glb_base64_encode_str (char * str)

> str: the string to encode

> Encodes a string into base64.

> Return value: newly allocated string.

— Function: char * lw6glb_base64_decode_str (char * str)

> str: the string to decode

> Deodes a string from base64.

> Return value: newly allocated string, NULL on error.

— Function: int lw6glb_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `glb` module test suite.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.10 libgui

— Function: void lw6gui_button_register_down (lw6gui_button_t * button, int64_t timestamp)

> button: the button to update

> timestamp: the current ticks (milliseconds)

> Registers a "down" (press) event on a button.

> Return value: none.

— Function: void lw6gui_button_register_up (lw6gui_button_t * button)

> button: the button to update

> Registers a "up" (release) event on a button.

> Return value: none.

— Function: int lw6gui_button_is_pressed (lw6gui_button_t * button)

> button: the button to query

> Tells wether a button is pressed or not.

> Return value: 1 if pressed, 0 if not.

— Function: int lw6gui_button_pop_press (lw6gui_button_t * button)

> button: the button to query

> Tells how many times the button has been pressed. Typical usage: the button is pressed, released, pressed, released several times. Then, after all this, you want to know how many times it has been pressed. Querying its state with `lw6gui_button_is_pressed` won't tell you much but this `pop_press` function will return 1 for each press there's been.

> Return value: 1 if there's a press event in the queue, 0 if empty.

— Function: void lw6gui_button_update_repeat (lw6gui_button_t * button, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> button: the button to update

> repeat_settings: the repeat settings (delay + interval)

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for a button, must be called regularly, as often as possible.

> Return value: none.

— Function: int lw6gui_button_sync (lw6gui_button_t * dst, lw6gui_button_t * src)

> dst: the target button object

> src: the source button object

> Synchronizes two button objects. This is typically used to pass data from one thread to another. This is not a simple copy, it will handle data such as "when was it pressed last" it an intelligent manner, popping src data to put it in dst, and clearing src.

> Return value: 1 if success, O if failure.

— Function: int lw6gui_coord_calc_xy (float * dst_x, float * dst_y, float dst_x0, float dst_y0, float dst_w, float dst_h, float src_x, float src_y, float src_x0, float src_y0, float src_w, float src_h)

> dst_x: the x coord to return

> dst_y: the y coord to return

> dst_x0: the x coord of point 0 in destination coord system

> dst_y0: the y coord of point 0 in destination coord system

> dst_w: the width of the area in destination coord system

> dst_h: the width of the area in destination coord system

> src_x: the x coord in source coord system

> src_y: the y coord in source coord system

> src_x0: the x coord of point 0 in source coord system

> src_y0: the y coord of point 0 in source coord system

> src_w: the width of the area in source coord system

> src_h: the width of the area in source coord system

> Registers a "down" (press) event on a button.

> Return value: none.

— Function: int lw6gui_input_init (lw6gui_input_t * input)

> input: the input struct to initialise

> Initialises an input structure, don't use twice, it won't free a previous init.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_input_quit (lw6gui_input_t * input)

> input: the input struct to uninitialise

> Unitialises an input structure, need to call it to free event queue.

> Return value: a pointer to the newly allocated object.

— Function: lw6gui_input_t * lw6gui_input_new ()

> Creates an input structure, which can be used to handle input state & buffer.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_input_free (lw6gui_input_t * input)

> input: the input object to free.

> Deletes an input structure.

> Return value: none.

— Function: int lw6gui_input_reset (lw6gui_input_t * input)

> input: the input struct to reset

> Resets an input structure. Must have been initialized before. It will empty all queues and mark everything as unpressed.

> Return value: 1 on success, 0 if failure.

— Function: void lw6gui_input_update_repeat (lw6gui_input_t * input, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> input: the input to update

> repeat_settings: the repeat settings (delay + interval)

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for an input, must be called regularly, as often as possible.

> Return value: none.

— Function: void lw6gui_input_register_change (lw6gui_input_t * input)

> input: the input to update

> Tells an input object that one of its descendants has been modified. This will affect the return value of `lw6gui_input_need_sync`

> Return value: none.

— Function: int lw6gui_input_need_sync (lw6gui_input_t * input)

> input: the input to test

> Tests wether an input object contains was modified and needs synchronisation.

> Return value: 1 if sync is need, 0 if not.

— Function: int lw6gui_input_sync (lw6gui_input_t * dst, lw6gui_input_t * src)

> dst: the target input object

> src: the source input object

> Synchronizes two input objects. This is typically used to pass data from one thread to another. This is not a copy, it will brute-force copy the static data such as mouse position, but anything like a queue will be treated in a "empty source and fill target with data" scheme. So source will be affected by this, the key buffer will be emptied, and so on. And if there are key in the target buffer, they won't be overwritten but kept in front of the FIFO list.

> Return value: 1 if success, O if failure.

— Function: int lw6gui_input_poll_quit (lw6gui_input_t * input)

> input: the input to query

> Asks the display manager wether a quit event (usually CTRL-C or click on close button) has been detected.

> Return value: 1 if quit was receivedm 0 if not

— Function: void lw6gui_input_send_quit (lw6gui_input_t * input)

> input: the input to send an event to

> Artificially send a QUIT event (equivalent of CTRL-C or click on close button). This allow a uniform treatment of game stopping.

> Return value: none

— Function: int lw6gui_joystick_check_index (int i)

> i: index to check

> Checks wether the index is correct. Does not mean the joystick exists, it's just to avoid out of bounds errors.

> Return value: 1 if within range, 0 if not.

— Function: void lw6gui_joystick_update_axis_x (lw6gui_joystick_t * joystick, int x, int limit, int64_t timestamp)

> joystick: joystick to update

> x: x-axis position, as returned by the driver

> limit: the limit, under this, buttons are considered unpressed.

> timestamp: current ticks (timestamp in ms)

> Updates the x axis of a joystick, this will convert an information of analog type such as "joystick is here" to a pad-like information such as "pressed in that direction".

> Return value: 1 if within range, 0 if not.

— Function: void lw6gui_joystick_update_axis_y (lw6gui_joystick_t * joystick, int y, int limit, int64_t timestamp)

> joystick: joystick to update

> limit: the limit, under this, buttons are considered unpressed.

> timestamp: current ticks (timestamp in ms)

> Updates the y axis of a joystick, this will convert an information of analog type such as "joystick is here" to a pad-like information such as "pressed in that direction".

> Return value: 1 if within range, 0 if not.

— Function: void lw6gui_joystick_update_repeat (lw6gui_joystick_t * joystick, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> joystick: the joystick to update

> repeat_settings: the repeat settings (delay + interval)

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for a joystick, must be called regularly, as often as possible.

> Return value: none.

— Function: int lw6gui_joystick_sync (lw6gui_joystick_t * dst, lw6gui_joystick_t * src)

> dst: the target joystick object

> src: the source joystick object

> Synchronizes two joystick objects. This is typically used to pass data from one thread to another.

> Return value: 1 if success, O if failure.

— Function: void lw6gui_joystick_get_move_pad (lw6gui_joystick_t * joystick, lw6gui_move_pad_t * move_pad)

> joystick: the joystick to query

> move_pad: the structure which will contain the results

> Returns the state of the joystick in a uniform, non-device specific structure containing only the up/down/left/right information.

> Return value: none, the value are stored in `move_pad`.

— Function: int lw6gui_keyboard_check_keysym (int keysym)

> keysym: the keysym to check

> Tells wether the keysym is valid or not.

> Return value: 1 if valid, 0 if not

— Function: lw6gui_keypress_t * lw6gui_keyboard_pop_keypress (lw6gui_keyboard_t * keyboard)

> keyboard: the keyboard structure which stores keyboard state

> Pops (in FIFO mode) a keypress stored in the keyboard buffer. You must free the obtained keypress object after you're done with it.

> Return value: a newly allocated pointer, or NULL if no keypress pending.

— Function: int lw6gui_keyboard_is_pressed (lw6gui_keyboard_t * keyboard, int keysym)

> keyboard: the keyboard structure which stores keyboard state

> Tells wether a key is pressed or not. The function will test out of bound values.

> Return value: 1 if pressed, 0 if not.

— Function: int lw6gui_keyboard_register_key_down (lw6gui_keyboard_t * keyboard, int keysym, int unicode, char * label, int64_t timestamp)

> keyboard: the keyboard structure which will store the keypress

> keysym: the keysym for the keypress

> unicode: the ASCII/unicode code for the keypress

> label: the label for the keypress

> timestamp: the current ticks (timestamp in ms)

> Registers a keypress event, that is, puts it in the event queue. This function does not take an `lw6gui_keypress_t` structure but separated args, this is because it will construct the object internally. You may free `label` after calling this, an internal copy will be done. This function will also maintain the array of key states up to date.

> Return value: 1 if success, O if failure.

— Function: int lw6gui_keyboard_register_key_up (lw6gui_keyboard_t * keyboard, int keysym)

> keyboard: the keyboard structure which will store the keypress

> keysym: the keysym for the keypress

> Registers a key release event.

> Return value: 1 if success, O if failure.

— Function: void lw6gui_keyboard_update_repeat (lw6gui_keyboard_t * keyboard, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> keyboard: the keyboard to update

> repeat_settings: the repeat settings (delay + interval)

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for a keyboard, must be called regularly, as often as possible.

> Return value: none.

— Function: int lw6gui_keyboard_sync (lw6gui_keyboard_t * dst, lw6gui_keyboard_t * src)

> dst: the target keyboard object

> src: the source keyboard object

> Synchronizes two keyboard objects. This is typically used to pass data from one thread to another. Will pop the src queue to fill the dst queue.

> Return value: 1 if success, O if failure.

— Function: void lw6gui_keyboard_get_move_pad (lw6gui_keyboard_t * keyboard, lw6gui_move_pad_t * move_pad)

> keyboard: the keyboard to query

> move_pad: the structure which will contain the results

> Returns the state of the keyboard in a uniform, non-device specific structure containing only the up/down/left/right information.

> Return value: none, the value are stored in `move_pad`.

— Function: lw6gui_keypress_t * lw6gui_keypress_new (int keysym, int unicode, char * label)

> keysym: the keysym to use

> unicode: the unicode value for this keysym

> label: the label (optional, might be NULL)

> Creates a keypress structure, the only reason for needing a contructor is that the label field needs be duplicated.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_keypress_free (lw6gui_keypress_t * keypress)

> keypress: the keypress object to free.

> Deletes a keypress structure.

> Return value: none.

— Function: char * lw6gui_keypress_repr (lw6gui_keypress_t * keypress)

> keypress: the keypress to work on

> Returns a human-readable representation of the keypress.

> Return value: a newly allocated string

— Function: lw6gui_menu_t * lw6gui_menu_new (char * title, char * esc, int enable_esc)

> title: the string to be displayed, what the user sees. Can be freed after the call is done, function will make a copy internally.

> esc: the label to be displayed in the ESC button

> enable_esc: wether to enable the escape button.

> Constructs a new menu object. Note that you can always call other functions to modify it afterwards.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_menu_free (lw6gui_menu_t * menu)

> menu: a pointer to the menu.

> Frees the menu, checking if things are OK before doing so.

> Return value: none.

— Function: int lw6gui_menu_memory_footprint (lw6gui_menu_t * menu)

> menu: a pointer to the menu.

> Gets the memory occupied by the menu. Could be usefull to help a garbage collector taking decisions or reporting erros, for instance.

> Return value: the number of bytes used.

— Function: char * lw6gui_menu_repr (lw6gui_menu_t * menu)

> menu: a pointer to the menu.

> Constructs a readable description of the object. Usefull for debugging, or to introspect things using scripts, at run-time. Does not necessarly describe all the informations about the object, but helps knowing what it is.

> Return value: a string describing the object, must be freed.

— Function: void lw6gui_menu_set_title (lw6gui_menu_t * menu, char * title)

> menu: a pointer to the menu.

> title: the new title, you can free it after calling the function, an internal copy will be made.

> Change the title of the menu. That is to say, its title. Use this function to change the title, don't try to access the struct directly. The idea is to have safe memory management.

> Return value: none

— Function: lw6gui_menuitem_t * lw6gui_menu_get_item (lw6gui_menu_t * menu, int position)

> menu: the menu we want to query

> position: the order of the item we want

> Gets the menu item at the given position. First item is 0, last is N-1. Returns a pointer on the real object, not a copy.

> Return value: a pointer to a menu item, NULL if out of range.

— Function: int lw6gui_menu_select (lw6gui_menu_t * menu, int position, int allow_scroll, int64_t now)

> menu: the menu we want to modify

> position: the position of the item we want to select

> allow_scroll: wether scrolling should be allowed when displaying it

> now: the current time, as a timestamp.

> Selects the item at the given position. Use this function to be sure that only one item is selected, and all other states are consistent. Timestamp is needed for the sake of eye-candy.

> Return value: 1 if success, 0 if failure (out of range).

— Function: void lw6gui_menu_select_esc (lw6gui_menu_t * menu, int state, int64_t now)

> menu: the menu we want to modify

> state: 1 to select, 0 to unselect

> now: the current time, as a timestamp.

> Selects the escape item, this does not affect other items, it's mostly. to handle eye candy.

> Return value: none.

— Function: void lw6gui_menu_enable_esc (lw6gui_menu_t * menu, int state, int64_t now)

> menu: the menu we want to modify

> state: 1 to enable, 0 to disable

> now: the current time, as a timestamp.

> Enables the escape item, this does not affect other items, it's mostly. to handle eye candy.

> Return value: none.

— Function: int lw6gui_menu_scroll_up (lw6gui_menu_t * menu)

> menu: the menu to scroll

> Scrolls a menu up, used as a callback for mouse wheel up for instance. The idea is just to decrement the first displayed item index.

> Return value: 1 if OK, 0 if failed (out of range).

— Function: int lw6gui_menu_scroll_down (lw6gui_menu_t * menu)

> menu: the menu to scroll

> Scrolls a menu down, used as a callback for mouse wheel down for instance. The idea is just to increment the first displayed item index.

> Return value: 1 if OK, 0 if failed (out of range).

— Function: void lw6gui_menu_center (lw6gui_menu_t * menu, int position, int max_displayed_items)

> menu: the menu to center

> position: the position of the menuitem to be put in the center

> max_displayed_items: the maximum number of items displayed

> Centers the menu on a given menuitem. Typically used when pushing a menu with a menuitem selected 'anywhere' in the list.

> Return value: none.

— Function: int lw6gui_menu_insert (lw6gui_menu_t * menu, lw6gui_menuitem_t * menuitem, int position, int64_t now)

> menu: the menu we want to modify

> menuitem: the item to insert

> position: the position the new item will occupy ("insert before" mode)

> now: the current time, as a timestamp.

> Inserts the given item in the menu. All items starting at the insert position will be "pushed" (that is, their position incremented by 1). Once the menuitem is inserted, the menu object will take care of memory management and automatically free it when needed.

> Return value: 1 if success, 0 if failure (memory problem, out of range).

— Function: int lw6gui_menu_append (lw6gui_menu_t * menu, lw6gui_menuitem_t * menuitem, int64_t now)

> menu: the menu we want to modify

> menuitem: the item to insert

> now: the current time, as a timestamp.

> Appends the given item to the menu. Once the menuitem is appended, the menu object will take care of memory management and automatically free it when needed.

> Return value: 1 if success, 0 if failure (memory problem).

— Function: int lw6gui_menu_remove (lw6gui_menu_t * menu, int position, int64_t now)

> menu: the menu we want to modify

> position: the item to insert

> now: the current time, as a timestamp.

> Removes an item from the menu. It will automatically be freed.

> Return value: 1 if success, 0 if failure (out of range).

— Function: void lw6gui_menu_update_display_range (lw6gui_menu_t * menu, int max_displayed_items)

> menu: the menu concerned

> max_displayed_items: the maximum number of items to display at once

> Updates the display range. The reason for having this is that the first item, that is, how far we scroll in a very long menu, depends on the previous position. Plus you have to handle limit cases (begin/end). Thus, this function, which will automatically pick-up a suitable position. Of course, `first_item_displayed` is not necessarly equal to `selected_item`.

> Return value: none.

— Function: int lw6gui_menu_insert_for_id_use (lw6gui_menu_t * menu, char * label, int value, int enabled, int selected, int colored, int position, int64_t now)

> menu: the menu to work on

> label: the label of the menuitem to append

> value: the value of the menuitem to append

> enabled: wether the inserted menuitem should be enabled

> selected: wether the inserted menuitem should be selected

> colored: wether the inserted menuitem should use value as its color

> now: current time (timestamp)

> Inserts a menu item at the given position. The idea is that the menu item object is automatically constructed on the fly, and an id is returned, which can be passed to '_using_id' menu-related functions. This is typically for using in scripts. The idea is that the script just keeps a copy of the id returned, and can this way operate directly on the menuitem without keeping a pointer, a smob or anything internally. From the C point of view, having a real C structure enables persistent data from one display to the other, and this is nice and conveninent. I acknowledge the prototype is scary.

> Return value: 0 if error, or else an id which will later be used with '_using_id' functions.

— Function: int lw6gui_menu_append_for_id_use (lw6gui_menu_t * menu, char * label, int value, int enabled, int selected, int colored, int64_t now)

> menu: the menu to work on

> label: the label of the menuitem to append

> value: the value of the menuitem to append

> enabled: wether the appended menuitem should be enabled

> selected: wether the appended menuitem should be selected

> colored: wether the appended menuitem should use value as its color

> now: current time (timestamp)

> Appends a menuitem using the same logic as `lw6gui_menu_insert_for_id_use` that is to say a parameter is returned which can later be used to directly operate on a given menuitem, without having its pointer, and even if its position changes.

> Return value: 0 if error, or else an id which will later be used with '_using_id' functions.

— Function: int lw6gui_menu_remove_using_id (lw6gui_menu_t * menu, int menuitem_id, int64_t now)

> menu: the menu to work on

> menuitem_id: the id of the menuitem to remove

> now: current time (timestamp)

> Deletes the menuitem with the given id. Very important: the id is not the position. Id are arbitrary numbers that stick to menuitems, but they are not directly linked with the position. This function is practical to use if, for some reason, you don't have the pointer on the menuitem.

> Return value: 1 if success, 0 if failure (out of range).

— Function: void lw6gui_menu_sync_using_id (lw6gui_menu_t * menu, int menuitem_id, char * label, int value, int enabled, int selected, int colored, int64_t now)

> menu: the menu to work on

> menuitem_id: the id of the menuitem to synchronize

> now: current time (timestamp)

> Updates the menuitem with the given id. Very important: the id is not the position. Id are arbitrary numbers that stick to menuitems, but they are not directly linked with the position. This function is practical to use if, for some reason, you don't have the pointer on the menuitem. In practice, it's heavily used in the game to transmit informations from the scripts to the core C engine. Additionnaly, this function will automatically synchronize the `selected_item` field of the menu struct.

> Return value: 1 if success, 0 if failure (out of range).

— Function: int lw6gui_menu_is_same (lw6gui_menu_t * menu_a, lw6gui_menu_t * menu_b)

> menu_a: first item to compare

> menu_b: second item to compare

> Compares two menus.

> Return value: 1 if they are the same, 0 if not

— Function: lw6gui_menu_t * lw6gui_menu_dup (lw6gui_menu_t * menu)

> menu: the menu to duplicate

> Duplicates a menu structure.

> Return value: a pointer to the new menu.

— Function: int lw6gui_menu_sync (lw6gui_menu_t * dst, lw6gui_menu_t * src)

> dst: the target menu

> src: the source menu

> Synchronizes two menus, this supposes that they represent the same menu, but simply in a different state. This function does not really copy src to dst, it has a special behavior, indeed everything is copied from src to dst, except the `first_item_displayed` and `nb_items_displayed` which are taken from dst and copied to src. This is because in practise, those values are updated in the display loop/thread, which is the one which uses the target. This is not very orthodox, but should work.

> Return value: 1 if success, 0 if failure

— Function: lw6gui_menuitem_t * lw6gui_menuitem_new (char * label, int value, int enabled, int selected, int colored)

> label: the string to be displayed, what the user sees. Can be freed after the call is done, function will make a copy internally.

> value: the value. No GUI function uses this, this is the "real" value associated to the item.

> enabled: wether the menu item can be selected, used, and so on

> selected: wether the menu item is the item selected among all menu items.

> colored: wetherr the menu item must, when drawn, be colored according to its value.

> Constructs a new menuitem object. Note that you can always call other functions to modify these values afterwards, this might change rendering since `lw6gui_menuitem_set_value` or `lw6gui_menuitem_set_label` will, for instance, modify the "when was that item last modified" information.

> Return value: a pointer to the newly allocated object.

— Function: void lw6gui_menuitem_free (lw6gui_menuitem_t * menuitem)

> menuitem: a pointer to the menuitem.

> Frees the menuitem, checking if things are OK before doing so.

> Return value: none.

— Function: int lw6gui_menuitem_memory_footprint (lw6gui_menuitem_t * menuitem)

> menuitem: a pointer to the menuitem.

> Gets the memory occupied by the menuitem. Could be usefull to help a garbage collector taking decisions or reporting erros, for instance.

> Return value: the number of bytes used.

— Function: char * lw6gui_menuitem_repr (lw6gui_menuitem_t * menuitem)

> menuitem: a pointer to the menuitem.

> Constructs a readable description of the object. Usefull for debugging, or to introspect things using scripts, at run-time. Does not necessarly describe all the informations about the object, but helps knowing what it is.

> Return value: a string describing the object, must be freed.

— Function: void lw6gui_menuitem_set_label (lw6gui_menuitem_t * menuitem, char * label, int64_t now)

> menuitem: a pointer to the menuitem.

> label: the new label, you can free it after calling the function, an internal copy will be made.

> now: the current time, as a timestamp.

> Change the label of the menu item. That is to say, what the user sees. Use this function to change the menuitem value, don't try to access the struct directly. The idea is 1) to have safe memory management and 2) to keep the `last_change` member up to date. It can be later used for eye-candy effects.

> Return value: none

— Function: void lw6gui_menuitem_set_value (lw6gui_menuitem_t * menuitem, int value, int64_t now)

> menuitem: a pointer to the menuitem.

> now: the current time, as a timestamp.

> Changes the value of a menuitem. This is the internal value, not what the user sees. Use this function to change the menuitem value, don't try to access the struct directly. The idea is to keep the `last_change` member up to date. It can be later used for eye-candy effects.

> Return value: none

— Function: void lw6gui_menuitem_select (lw6gui_menuitem_t * menuitem, int state, int64_t now)

> menuitem: a pointer to the menuitem.

> state: 1 to select, 0 to unselect

> now: the current time, as a timestamp.

> Switches the menuitem to (un)selected state. Use this function, don't try to modify the struct members directly. The idea is to have the `last_select` parameter up to date. It can be later used for eye-candy effects.

> Return value: none

— Function: void lw6gui_menuitem_enable (lw6gui_menuitem_t * menuitem, int state, int64_t now)

> menuitem: a pointer to the menuitem.

> state: 1 to enable, 0 to disable

> now: the current time, as a timestamp.

> Switches the menuitem to enabled/disabled state. Use this function, don't try to modify the struct members directly. The idea is to have the `last_select` parameter up to date. It can be later used for eye-candy effects.

> Return value: none

— Function: u_int32_t lw6gui_menuitem_checksum (lw6gui_menuitem_t * menuitem, lw6gui_look_t * look)

> menuitem: the menuitem we want to identify

> Returns a checksum which can be used to know, for instance, wether the menuitem has changed or not, and if we should redraw it.

> Return value: a checksum.

— Function: int lw6gui_menuitem_is_same (lw6gui_menuitem_t * menuitem_a, lw6gui_menuitem_t * menuitem_b)

> menuitem_a: first item to compare

> menuitem_b: second item to compare

> Compares two menuitems.

> Return value: 1 if they are the same, 0 if not

— Function: lw6gui_menuitem_t * lw6gui_menuitem_dup (lw6gui_menuitem_t * menuitem)

> menuitem: the menuitem to duplicate

> The menuitem to duplicate.

> Return value: a pointer to the duplicted menuitem.

— Function: int lw6gui_menuitem_sync (lw6gui_menuitem_t * dst, lw6gui_menuitem_t * src)

> dst: the target menuitem

> src: the source menuitem

> Synchronizes two menuitems, this supposes that they represent the same item, but simply in a different state.

> Return value: 1 if success, 0 if failure

— Function: void lw6gui_mouse_register_move (lw6gui_mouse_t * mouse, int x, int y, int64_t timestamp)

> mouse: the mouse object to work on

> x: the x position

> y: the y position

> timestamp: current timestamp

> Registers a mouse move event.

> Return value: note.

— Function: int lw6gui_mouse_poll_move (lw6gui_mouse_t * mouse, int * x, int * y)

> mouse: the mouse object to poll

> x: pointer to the x position (can be NULL), will be updated even if no move

> y: pointer to the y position (can be NULL), will be updated even if no move

> Asks wether the mouse has moved or not.

> Return value: 1 if mouse was moved since last call, 0 if not.

— Function: void lw6gui_mouse_update_repeat (lw6gui_mouse_t * mouse, lw6gui_repeat_settings_t * repeat_settings, int64_t timestamp)

> mouse: the mouse to update

> repeat_settings: the repeat settings (delay + interval)

> timestamp: the current ticks (milliseconds)

> Updates the repeat informations for a mouse, must be called regularly, as often as possible.

> Return value: none.

— Function: int lw6gui_mouse_sync (lw6gui_mouse_t * dst, lw6gui_mouse_t * src)

> dst: the target mouse object

> src: the source mouse object

> Synchronizes two mouse objects. This is typically used to pass data from one thread to another. Will handle "mouse move" attribute and clear it in src if needed while setting it in dst.

> Return value: 1 if success, O if failure.

— Function: void lw6gui_smoother_init (lw6gui_smoother_t * smoother, float value, int duration)

> smoother: the structure to initialize

> value: the value to use for now

> duration: the duration of a standard move, in ticks (msec)

> Initializes a smoother object, with a default value. The important point is the duration which will condition all the behavior of the object.

> Return value: none.

— Function: void lw6gui_smoother_immediate_force (lw6gui_smoother_t * smoother, float value)

> smoother: the structure to use

> value: the target value

> Forces a smoother object to immediately point on a value.

> Return value: none.

— Function: void lw6gui_smoother_set_target (lw6gui_smoother_t * smoother, float value, int64_t now)

> smoother: the structure to use

> value: the target value

> now: the current timestamp

> Sets a new target, will automatically calculate current speed to smooth the next returned values.

> Return value: none.

— Function: float lw6gui_smoother_get_value (lw6gui_smoother_t * smoother, int64_t now)

> smoother: the structure to use

> now: the current timestamp

> Returns the current value of the smoother.

> Return value: a float.

— Function: int lw6gui_test (int mode)

> mode: 0 for check only, 1 for full test

> Run tests in the gui module.

> Return value: 1 if successfull, 0 if failed.

— Function: int lw6gui_video_mode_find_closest (lw6gui_video_mode_t * closest, lw6gui_video_mode_t * wished, lw6sys_list_t * available)

> closest: the closest video_mode found

> wished: the wished video_mode

> available: a list of available video_modes (list of lw6gui_video_mode_t *)

> Finds the closest video_mode available, this is just a small utility to cope with different screen shapes and avoid requesting 640x480 when it's just not available but there's a 640x400 instead.

> Return value: 1 if the wished video_mode exists in available list and was found, else 0 if the wished video_mode doesn't exist and an approximative match was picked.

— Function: int lw6gui_video_mode_is_same (lw6gui_video_mode_t * mode_a, lw6gui_video_mode_t * mode_b)

> mode_a: first mode to compare

> mode_b: second mode to compare

> Compares two video modes, to know if they're the same.

> Return value: 1 if equal, 0 if not.

— Function: int lw6gui_video_mode_sync_ratio (lw6gui_video_mode_t * dst, lw6gui_video_mode_t * src)

> dst: the target video mode

> src: the source video mode

> Applies the ratio of src to dst, for instance if src is 16/9, then dst will be made 16/9 too, trying to keep the same surface.

> Return value: 1 on success, 0 on failure

— Function: int lw6gui_viewport_init (lw6gui_viewport_t * viewport, int screen_w, int screen_h, float drawable_x1, float drawable_y1, float drawable_x2, float drawable_y2, float center_x, float center_y, int map_w, int map_h, int x_polarity, int y_polarity, int x_wrap, int y_wrap, int keep_ratio, float global_zoom)

> viewport: the viewport to initalize

> screen_w: screen width

> screen_h: screen height

> drawable_x1: viewport min x

> drawable_y1: viewport min y

> drawable_x2: viewport max x

> drawable_y2: viewport max y

> center_x: center of display (in map coordinates)

> center_y: center of display (in map coordinates)

> map_w: map width (shape)

> map_h: map height (shape)

> x_polarity: x polarity

> y_polarity: y polarity

> x_wrap: wether to wrap horizontally

> y_wrap: wether to wrap vertically

> keep_ratio: wether to adapt to viewport shape or keep original

> global_zoom: global zoom is style_zoom * dynamic_zoom

> Initializes all the (jumbo?) viewport structure which will contain valuable informations for a simple "flat" display. Special renderers might not find usefull some fields and handle wrapping and zooming their own way, but this offers a basic skeleton.

> Return value: 1 if ok, 0 on failure

— Function: void lw6gui_viewport_map_to_screen (lw6gui_viewport_t * viewport, float * screen_x, float * screen_y, float map_x, float map_y, int clip)

> viewport: the viewport to use

> screen_x: the x coord on the screen

> screen_y: the y coord on the screen

> map_x: the x coord in map coordinates

> map_y: the y coord in map coordinates

> clip: wether to clip returned values

> Translates from map coords to screen coords. Returned values might be outside screen boundaries if clip is 0. If screen coords are outside drawable area anc clip is 1, then they will be clipped.

> Return value: NULL

— Function: void lw6gui_viewport_screen_to_map (lw6gui_viewport_t * viewport, float * map_x, float * map_y, float screen_x, float screen_y, int wrap)

> viewport: the viewport to use

> map_x: the x coord in map coordinates

> map_y: the y coord in map coordinates

> screen_x: the x coord on the screen

> screen_y: the y coord on the screen

> wrap: wether to use polarity informations to wrap coords.

> Translates from screen coords to map coords. If wrap is set, it will interpret coords the way `lw6map_coords_fix_xy` would, only it can still be formally outside map boundaries for it can return a value exactly equal to w,h while in interger mode it would be w-1,h-1.

> Return value: NULL

— Function: void lw6gui_zone_init_x1y1x2y2 (lw6gui_zone_t * zone, float x1, float y1, float x2, float y2)

> zone: the structure to initialize

> x1: x for top left corner

> y1: y for top left corner

> x2: x for bottom right corner

> y2: y for bottom right corner

> Initializes a zone structure, will calculate w & h.

> Return value: none.

— Function: void lw6gui_zone_init_xywh (lw6gui_zone_t * zone, float x, float y, float w, float h)

> zone: the structure to initialize

> x: x for top left corner

> y: y for top left corner

> w: width

> h: height

> Initializes a zone structure, will calculate x2 & y2.

> Return value: none.

— Function: void lw6gui_zone_clip (lw6gui_zone_t * dst, lw6gui_zone_t * src, lw6gui_zone_t * clip)

> dst: the structure which will contain the result

> src: the source zone

> clip: the clipping zone (boundaries)

> Clips a zone (think of rectangle clips).

> Return value: none.

#### 4.15.11 libhlp

— Function: int lw6hlp_is_documented (char * keyword)

> keyword: the keyword we want to check out

> Checks wether a given keyword is documented or not.

> Return value: 1 if documented, 0 if not.

— Function: char * lw6hlp_about (lw6hlp_type_t * type, char ** default_value, int * min_value, int * max_value, char * keyword)

> type: the type of the data associated to the keyword, will be written

> default_value: the default value for the keyword, will be written

> min_value: the min value for the keyword, will be written

> max_value: the max value for the keyword, will be written

> keyword: the keyword we want help about

> Returns the documentation string associated to a keyword. The keyword might be a command-line option, a Guile function, an XML file entry. Raises a warning if the keyword is undocumented, but never returns NULL, you can use the returned value without checking it. String is localized if a translation is available. It's safe to call this function with type or other parameters being NULL.

> Return value: a help string, never NULL, must not be freed. Additionnally, type will be updated.

— Function: lw6hlp_type_t lw6hlp_get_type (char * keyword)

> keyword: the keyword we want the type of

> Returns the type of a keyword. Calls lw6hlp_about internally.

> Return value: the type, might be LW6HLP_TYPE_VOID.

— Function: char * lw6hlp_get_default_value (char * keyword)

> keyword: the keyword we want the default for

> Returns the default value for a keyword. Note that it can be NULL! The returned value is always a string, it's suitable to store in the config file, it's the value a user would pass on a command line, the one he wants documented.

> Return value: a pointer, which can be NULL, must not be freed.

— Function: int lw6hlp_get_min_value (char * keyword)

> keyword: the keyword we want the min for

> Returns the min value for a keyword. Wether this is relevant for a given keyword does not affect the fact that you can call this function. A min and max of zero means min and max make no sense.

> Return value: the value (integer)

— Function: int lw6hlp_get_max_value (char * keyword)

> keyword: the keyword we want the max for

> Returns the max value for a keyword. Wether this is relevant for a given keyword does not affect the fact that you can call this function. A min and max of zero means min and max make no sense.

> Return value: the value (integer)

— Function: char * lw6hlp_get_credits (int id)

> id: the id of the credits line to return

> Returns a "credit line", that is a short sentence, about 30 to 50 chars, saying who developped the game, created graphics, giving important URLs, and so on. One can pass an arbitraty high `id`, no risk.

> Return value: the string, must be freed.

— Function: int lw6hlp_match (char * keyword1, char * keyword2)

> keyword1: the 1st keyword

> keyword2: the 2nd keyword

> Checks wether a keyword matches another. Not only a string comparison, will also try and guess if the error is only about dash "-" replaced by underscode "_", for instance.

> Return value: 1 if matches, 0 if different.

— Function: lw6sys_list_t * lw6hlp_list ()

> Returns a list of all available keywords.

> Return value: a list containing all the keywords. Strings are not dynamically allocated, you can't modify them.

— Function: void lw6hlp_print_keyword (lw6sys_list_t ** list, FILE * f)

> list: a pointer to a list of keywords

> f: the file to print the content to

> Prints all the keywords from the list. One keyword per line.

> Return value: none.

— Function: void lw6hlp_print_content (lw6sys_list_t ** list, FILE * f)

> list: a pointer to a list of keywords

> f: the file to print the content to

> Prints all the keywords from the list, with the associated keyword help, to the given file. Output is formatted to fit on the standard terminal/console.

> Return value: none.

— Function: void lw6hlp_print_about (char * keyword, FILE * f)

> keyword: the keyword to print help about

> f: the file to print the content to

> Displays the help about a keyword, to a file, directly. It's formatted for the purpose of the –about=<value> option.

> Return value: none

— Function: int lw6hlp_reference_init ()

> Initializes the help reference, this must be called before any call to lw6hlp_about or such help related functions.

> Return value: 1 on success, 0 if failed

— Function: void lw6hlp_reference_quit ()

> Un-initializes the help reference, this must be called at the end of the program.

> Return value: 1 on success, 0 if failed

— Function: int lw6hlp_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `hlp` module test suite.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.12 libimg

— Function: int lw6img_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `img` module test suite.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.13 libker

— Function: int lw6ker_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `ker` module test suite. Will perform deep checksums and *really* check many things. If this passes, the algorithm is fine. What could make it fail is a serious bug and/or some weird combination of endianess, byte alignment...

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.14 libldr

— Function: int lw6ldr_body_read (lw6map_body_t * body, char * dirname, lw6map_param_t * param, lw6ldr_hints_t * hints, int display_w, int display_h, float ratio, int bench_value, int magic_number, lw6sys_progress_t * progress)

> body: the body to read, must point to allocated memory

> dirname: the directory of the map

> param: map parameters

> hints: map hints

> display_w: the display width

> display_h: the display height

> ratio: wished map ratio

> bench_value: the bench value (depends on computer capacity)

> magic_number: arbitrary constant

> progress: structure to transmit loading progress

> Reads the map body, that is, all the layers.

> Return value: 1 if OK, 0 if failed.

— Function: void lw6ldr_auto_colors (lw6map_style_t * style, lw6ldr_hints_t * hints)

> style: the style structure to process.

> hints: additionnal hints to know what to set automatically

> Deduces all colors from background color, if needed. The function will check color_auto parameters and replace all other colors by base and alternate colors if needed. Note that the background color itself is not changed by this function. Background can only be guessed from texture.

> Return value: none.

— Function: void lw6ldr_free_entry (lw6ldr_entry_t * entry)

> entry: the entry to free

> Frees a map entry.

> Return value: none.

— Function: lw6sys_list_t * lw6ldr_get_entries (char * map_path, char * relative_path)

> map_path: the map_path environment config variable, delimited path list

> relative_path: the relative path to use to find the map directory

> Lists all maps in a given directory. Returns a list of lw6ldr_entry_t which can contain both directories with subdirs and actual maps. Maps are sorted before being returned, first directories, then maps, sorted in alphabetical order.

> Return value: a list of dynamically allocated lw6ldr_entry_t.

— Function: void lw6ldr_for_all_entries (char * map_path, char * relative_path, int recursive, lw6sys_list_callback_func_t callback_func, void * func_data)

> map_path: the map_path environment config variable, delimited path list

> relative_path: the relative path to use to find the map directory

> recursive: if non-zero, map search will recurse in subdirs

> callback_func: the function which will be called on each entry

> func_data: an extra pointer to pass data to callback_func

> Executes a given function on all maps in a given place, typically used in test programs.

> Return value: none.

— Function: int lw6ldr_grease_apply (lw6map_layer_t * layer, lw6map_rules_t * rules, lw6ldr_hints_t * hints, lw6sys_progress_t * progress)

> layer: the layer on which to apply the grease

> rules: map rules

> hints: map hints

> progress: structure to transmit loading progress

> Reads the map body, that is, all the layers.

> Return value: 1 if OK, 0 if failed.

— Function: int lw6ldr_hints_read (lw6ldr_hints_t * hints, char * dirname)

> dirname: the directory of the map

> Read the hints (hints.xml) of a map. Pointer to hints must be valid, and values already initialized, either zeroed or filled in with defaults or custom values.

> Return value: 1 if success, 0 if failed.

— Function: int lw6ldr_hints_set (lw6ldr_hints_t * hints, char * key, char * value)

> hints: the hints to modify

> key: the key to modify

> value: the value to affect to the key, as a string

> Sets one single parameter in a hints structure. Value must always be passed as a string, will be converted to the right type automatically when storing it in the structure.

> Return value: 1 if success, 0 if failed. Note that while 0 really means there's a problem, some affectations can fail and return 1, needs to be worked on.

— Function: int lw6ldr_hints_update (lw6ldr_hints_t * hints, lw6sys_assoc_t * values)

> hints: the hints struct to fill with values (read/write parameter)

> values: an assoc containing strings with the new values

> Overrides hints with values. Pointer to hints must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing hints.

> Return value: 1 if success, 0 if failed.

— Function: int lw6ldr_meta_layer_read (lw6map_meta_layer_t * meta_layer, char * filename, int target_w, int target_h, int analog)

> meta_layer: the meta layer to read

> filename: the file to open

> target_w: the wanted width

> target_h: the wanted height

> analog: wether to use analog info (0-255) or boolean (0-1)

> Reads a meta-layer from the disj, resampling is done according to the given parameters.

> Return value: 1 on success, 0 on failure

— Function: int lw6ldr_meta_layer_read_if_exists (lw6map_meta_layer_t * meta_layer, char * dirname, char * file_only, int target_w, int target_h, int analog)

> meta_layer: the meta layer to read

> dirname: the map directory

> file_only: the meta-layer file name only (without the path)

> target_w: the wanted width

> target_h: the wanted height

> analog: wether to use analog info (0-255) or boolean (0-1)

> Reads a meta-layer from the disj, resampling is done according to the given parameters. This function is different from `lw6ldr_meta_layer_read` for it will 1) concatenate `dirname` and `file_only` and 2) return OK (1) if file does not exist.

> Return value: 1 on success, 0 on failure

— Function: int lw6ldr_param_read (lw6map_param_t * param, char * dirname)

> param: the parameter struct to fill with values (read/write parameter)

> dirname: the directory of the map

> Read the parameters associated to a map. Pointer to param must be valid, and values already initialized, either zeroed or filled in with defaults or custom values.

> Return value: 1 if success, 0 if failed.

— Function: int lw6ldr_param_update (lw6map_param_t * param, lw6sys_assoc_t * values)

> param: the parameter struct to fill with values (read/write parameter)

> values: an assoc containing strings with the new values

> Overrides param with values. Pointer to param must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing param.

> Return value: 1 if success, 0 if failed.

— Function: void lw6ldr_print_example_rules_xml (FILE * f)

> f: file to output content to

> Print to a file a typical map rules.xml file.

> Return value: none.

— Function: void lw6ldr_print_example_hints_xml (FILE * f)

> f: file to output content to

> Print to a file a typical map hints.xml file.

> Return value: none.

— Function: void lw6ldr_print_example_style_xml (FILE * f)

> f: file to output content to

> Print to a file a typical map style.xml file.

> Return value: none.

— Function: int lw6ldr_print_examples (char * user_dir)

> user_dir: the user directory or at least, a writable one

> Writes all example XML files in 'user_dir/example/', will create the directory if needed.

> Return value: 1 if success, 0 if failed.

— Function: lw6map_level_t * lw6ldr_read (char * dirname, lw6sys_assoc_t * default_param, lw6sys_assoc_t * forced_param, int display_w, int display_h, int bench_value, int magic_number, lw6sys_progress_t * progress)

> dirname: the directory containing the map

> default_param: default parameters, as strings

> forced_param: forced parameters, as strings

> display_w: the width of the display output (resolution)

> display_h: the height of the display output (resolution)

> bench_value: the bench value (depends on computer capacity)

> magic_number: arbitrary constant

> progress: information used to handle the progress bar

> Loads a map from dist. The default_param and forced_param can contain values corresponding to rules.xml and style.xml entries. Parameters are read in 4 steps. 1st, a default value is picked by the program. 2nd, any value in `default_param` replaces previous values. 3rd, any value in rules.xml or style.xml replaces previous values. 4th, any value in `forced_param` replaces previous values. In practice, the `default_param` allows the user to set defaults which can still be overwritten by the map, while `forced_param` is a definitive 'ignore what is is defined in the map' way of doing things. See also `lw6ldr_read_relative`.

> Return value: 1 if success, 0 if failed.

— Function: lw6map_level_t * lw6ldr_read_relative (char * map_path, char * relative_path, lw6sys_assoc_t * default_param, lw6sys_assoc_t * forced_param, int display_w, int display_h, int bench_value, int magic_number, lw6sys_progress_t * progress)

> map_path: a collection of paths where to find maps

> relative_path: something which will be appended to a `map_path` member

> default_param: default parameters, as strings

> forced_param: forced parameters, as strings

> display_w: the width of the display output (resolution)

> display_h: the height of the display output (resolution)

> bench_value: the bench value (depends on computer capacity)

> magic_number: arbitrary constant

> progress: information used to handle the progress bar

> Reads a map from disk, using the map-path value, which is a collection of paths defined by the command-line, the environment variables, and the config file. `default_param` and `forced_param` work as in the function `lw6ldr_read`.

> Return value: 1 if success, 0 if failure.

— Function: int lw6ldr_rules_read (lw6map_rules_t * rules, char * dirname)

> dirname: the directory of the map

> Read the rules (rules.xml) of a map. Pointer to rules must be valid, and values already initialized, either zeroed or filled in with defaults or custom values.

> Return value: 1 if success, 0 if failed.

— Function: int lw6ldr_rules_update (lw6map_rules_t * rules, lw6sys_assoc_t * values)

> rules: the rules struct to fill with values (read/write parameter)

> values: an assoc containing strings with the new values

> Overrides rules with values. Pointer to rules must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing rules.

> Return value: 1 if success, 0 if failed.

— Function: int lw6ldr_style_read (lw6map_style_t * style, char * dirname)

> dirname: the directory of the map

> Read the style (style.xml) of a map. Pointer to style must be valid, and values already initialized, either zeroed or filled in with defaults or custom values.

> Return value: 1 if success, 0 if failed.

— Function: int lw6ldr_style_set (lw6map_style_t * style, char * key, char * value)

> style: the style to modify

> key: the key to modify

> value: the value to affect to the key, as a string

> Sets one single parameter in a style structure. Value must always be passed as a string, will be converted to the right type automatically when storing it in the structure.

> Return value: 1 if success, 0 if failed. Note that while 0 really means there's a problem, some affectations can fail and return 1, needs to be worked on.

— Function: int lw6ldr_style_update (lw6map_style_t * style, lw6sys_assoc_t * values)

> style: the style struct to fill with values (read/write parameter)

> values: an assoc containing strings with the new values

> Overrides style with values. Pointer to style must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing style.

> Return value: 1 if success, 0 if failed.

— Function: int lw6ldr_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `ldr` module test suite.

> Return value: 1 if test is successfull, 0 on error.

— Function: int lw6ldr_use_update (lw6ldr_use_t * use, lw6sys_assoc_t * values)

> use: the use struct to fill with values (read/write parameter)

> values: an assoc containing strings with the new values

> Overrides use with values. Pointer to use must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing use.

> Return value: 1 if success, 0 if failed.

#### 4.15.15 libmap

— Function: void lw6map_body_builtin_custom (lw6map_body_t * body, int w, int h, int d, int noise_percent, lw6map_rules_t * rules)

> body: the body to initialize

> w: the width

> h: the height

> d: the depth

> noise_percent: the noise level to fill meta layers with

> rules: the map rules

> Sets up a default body structure.

> Return value: none

— Function: void lw6map_body_clear (lw6map_body_t * body)

> body: the structure to clear

> Clears a body structure.

> Return value: none.

— Function: void lw6map_body_fix_checksum (lw6map_body_t * body)

> body: the structure to update

> Updates (calculates) the checksum of a map body structure.

> Return value: none.

— Function: int lw6map_body_check_and_fix_holes (lw6map_body_t * body, lw6map_rules_t * rules)

> body: the structure to update

> rules: the game rules

> This (fundamental) function ensures that all playable areas in a map are connected. If isolated zones are found out, then they are marked as walls and not used any more.

> Return value: none.

— Function: int lw6map_body_coord_from_texture (lw6map_level_t * level, int * body_x, int * body_y, int texture_x, int texture_y)

> level: the level to work on

> body_x: the body (logical) x coord

> body_y: the body (logical) y coord

> texture_x: the texture x coord

> texture_y: the texture y coord

> Gets body (logical) coords from texture position.

> Return value: 1 on success, 0 on failure (out of bounds)

— Function: u_int8_t lw6map_body_get_with_texture_coord (lw6map_level_t * level, int texture_x, int texture_y, int z)

> level: the level to work on

> texture_x: the texture x coord

> texture_y: the texture y coord

> z: the z position (depth related)

> Tells wether a given map position is free or not, but using texture coords.

> Return value: 1 if position is playable, 0 if not (wall)

— Function: void lw6map_color_invert (lw6map_color_couple_t * color)

> color: the color to invert

> Inverts a color couple, that is, replace fg by bg and vice-versa.

> Return value: none.

— Function: int lw6map_color_is_same (lw6map_color_couple_t * color1, lw6map_color_couple_t * color2)

> color1: 1st color to compare

> color2: 2nd color to compare

> Compares two colors.

> Return value: 1 if equal, 0 if not.

— Function: char * lw6map_team_color_index_to_key (int index)

> index: index of the color between 0 & 9

> Transforms a team color index into its readable string form, which can be used in config files for instance.

> Return value: a string, must *not* be freed.

— Function: int lw6map_team_color_key_to_index (char * key)

> key: key of the color, for instance "red"

> The index of the color, between 0 & 9

> Return value: an integer.

— Function: lw6map_level_t * lw6map_dup (lw6map_level_t * source, lw6sys_progress_t * progress)

> source: the map to copy

> progress: to show advancement

> Performs a deep copy of the map, all elements are newly allocated and source can safely be destroyed after it's been duplicated.

> Return value: a newly allocated map, may be NULL.

— Function: char * lw6map_to_hexa (lw6map_level_t * level)

> Converts a map to something that is later readable by `lw6map_from_hexa` to reproduce the exact same map. Just a serializer.

> Return value: a newly allocated pointer, NULL if conversion failed.

— Function: lw6map_level_t * lw6map_from_hexa (char * hexa)

> hexa: an hexadecimal ASCII string, created by `lw6map_to_hexa`

> Constructs a map from an hexadecimal string generated by `lw6map_to_hexa`. Just an un-serializer.

> Return value: a new map, might be NULL if string isn't correct.

— Function: void lw6map_layer_builtin_custom (lw6map_layer_t * layer, int w, int h)

> layer: the layer to init

> w: width

> h: height

> Creates a default layer. This is mostly for testing purposes, the default layer is not empty, it contains a simplified map of the world.

> Return value: none

— Function: void lw6map_layer_clear (lw6map_layer_t * layer)

> layer: the layer to init

> Clears a layer struct. This means freeing the pointer if it's non NULL and setting everything to 0.

> Return value: none

— Function: lw6map_level_t * lw6map_new ()

> Creates a new empty map. This object is perfectly unusable as is, since it has a 0x0 size, and many things set to "NULL". Still, it's used internally and is the canonical way to create the object, it ensures later calls that set up default parameters, for instance, will succeed.

> Return value: a newly allocated pointer.

— Function: lw6map_level_t * lw6map_builtin_defaults ()

> Creates a map, set to defaults. This is usefull mostly for testing. This builtin map has walls, paths, it's playable.

> Return value: a newly allocated map.

— Function: lw6map_level_t * lw6map_builtin_custom (int w, int h, int d, int noise_percent)

> w: the width of the map

> h: the height of the map

> d: the depth (number of layers) of the map

> noise_percent: percentage of noise to use for metalayers

> Creates a map, set to defaults. This is usefull mostly for testing. This one, unlike `lw6map_builtin_defaults` will let you give a width, height and a depth.

> Return value: a newly allocated map.

— Function: void lw6map_free (lw6map_level_t * level)

> Frees a map and releases all its internal ressources.

> Return value: none.

— Function: int lw6map_memory_footprint (lw6map_level_t * level)

> Reports how many bytes the map needs, in memory. Note that this is not contiguous memory, it involves a bunch of pointers, and possibly much more...

— Function: char * lw6map_repr (lw6map_level_t * level)

> Returns a string describing the map. This is a very short description, use it for logs, and to debug stuff. By no means it's a complete exhaustive description. Still, the string returned should be unique.

> Return value: a dynamically allocated string.

— Function: int lw6map_is_same (lw6map_level_t * level_a, lw6map_level_t * level_b)

> level_a: the first level to compare

> level_b: the other level to compare

> Compares two level structs, the idea is to compare the content, not only the pointers and level ids.

> Return value: 1 if they're the same, 0 if not.

— Function: int lw6map_local_info_set_music_dir (lw6map_local_info_t * local_info, char * music_dir)

> local_info: the structure to modify

> music_dir: the new music_dir value

> Sets the music_dir value, in a 'safe' manner, freeing any previous value and performing a string duplication.

> Return value: 1 on success, 0 on failure.

— Function: void lw6map_local_info_clear (lw6map_local_info_t * local_info)

> local_info: the structure to clear

> Clears the local_info structure, before destroying a level for instance.

> Return value: none

— Function: void lw6map_meta_layer_set (lw6map_meta_layer_t * meta_layer, int x, int y, u_int8_t value)

> meta_layer: the meta_layer structure

> x: x coord

> y: y coord

> value: the value to set at this place

> Simple setter for the meta_layer struct.

> Return value: none

— Function: u_int8_t lw6map_meta_layer_get (lw6map_meta_layer_t * meta_layer, int x, int y)

> meta_layer: the meta_layer structure

> x: x coord

> y: y coord

> Simple getter for the meta_layer struct.

> Return value: the value at this place

— Function: void lw6map_meta_layer_clear (lw6map_meta_layer_t * meta_layer)

> meta_layer: the meta_layer to clear

> Clears a meta_layer struct. This means freeing the pointer if it's non NULL and setting everything to 0.

> Return value: none

— Function: int lw6map_meta_layer_builtin_custom (lw6map_meta_layer_t * meta_layer, int w, int h, int analog, int noise_percent, int seed)

> meta_layer: the object to init

> w: width

> h: height

> analog: wether to use analog mode (0-255) or boolean (0-1)

> noise_percent: the quantity of noise to initialise the layer with

> seed: a pseudo-random seed to feed the pseudo-random generator

> Builds a custom metalyer, suitable for tests or demo, letting the choice of its size and the noise to fill it with. If noise is 100 then metalayer is "full". If noise is 0, then meta layer is empty.

> Return value: 1 if OK, 0 on failure.

— Function: void lw6map_param_defaults (lw6map_param_t * param)

> param: the param struct to modify

> Sets a param structure to its default value, note that current structured must be zeroed or correctly initialized.

> Return value: none

— Function: void lw6map_param_clear (lw6map_param_t * param)

> param: the param struct to modify

> Resets a param structure to nothing. Note that current structured must be zeroed or correctly initialized. The idea is just to free member pointers before calling free.

> Return value: none

— Function: void lw6map_param_copy (lw6map_param_t * dst, lw6map_param_t * src)

> dst: the destination param struct

> src: the source param struct

> Copies parameters. Both structures must be zeroed or correctly initialized.

> Return value: none

— Function: int lw6map_param_set (lw6map_param_t * param, char * key, char * value)

> param: the param struct to modify

> key: the name of the parameter to modify

> value: the value of the parameter to modify

> Sets an entry in a param struct. All values must be submitted as strings, internally, the function will call atoi to convert to integers if needed, for instance. It will also dispatch automatically between rules and style.

> Return value: 1 if parameter successfully set, 0 on error.

— Function: int lw6map_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `map` module test suite.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.16 libmsg

— Function: char * lw6msg_oob_generate_info (lw6nod_info_t * info)

> info: the node to generate info about

> Generates a standard response to the INFO question for OOB (out of band) messages. The same message is sent, be it on http or tcp or udp, so it's factorized here. Function will lock the info object when needed.

> Return value: newly allocated string.

— Function: char * lw6msg_oob_generate_list (lw6nod_info_t * info)

> info: the node to generate info about

> Generates a standard response to the LIST question for OOB (out of band) messages. The same message is sent, be it on http or tcp or udp, so it's factorized here. Function will lock the info object when needed.

> Return value: newly allocated string.

— Function: char * lw6msg_oob_generate_pong (lw6nod_info_t * info)

> info: the node to generate info about

> Generates a standard response to the PING question for OOB (out of band) messages. The same message is sent, be it on http or tcp or udp, so it's factorized here. Function will lock the info object when needed.

> Return value: newly allocated string.

— Function: char * lw6msg_oob_generate_request (char * command, char * remote_url, char * password, char * local_url)

> command: the command to send (PING, INFO, LIST)

> remote_url: the remote URL (used to seed password)

> password: the password, can be NULL or ""

> local_url: the public URL to send along with the message, can be NULL or ""

> Generates a simple clear text OOB request, with a password if needed.

> Return value: a newly allocated string

— Function: int lw6msg_oob_analyse_request (int * syntax_ok, char ** command, int * password_ok, char ** remote_url, char * request, char * local_url, char * password)

> syntax_ok: will contain 1 if syntax is OK, 0 if not

> command: the command (out param, needs *not* to be freed)

> password_ok: will contain 1 if password is OK, 0 if not

> remote_url: the URL detected, if provided (out param, does needs to be freed)

> request: the request to analyse

> local_url: the local url (used to seed password)

> password: the password to check against

> Analyses a simple OOB message of the form COMMAND <passwd> <url>.

> Return value: 1 if OK, 0 if not. If 0, check the value of password_ok.

— Function: char * lw6msg_oob_analyse_pong (char * text)

> text: the text of the message to parse

> Analyses a PONG message and gets the public_url from it, if it exists.

> Return value: newly allocated string containing public_url if OK, NULL on error.

— Function: int lw6msg_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `nod` module test suite.

> Return value: 1 if test is successfull, 0 on error.

— Function: int lw6msg_utils_parse_key_value_to_ptr (char ** key, char ** value, char * line)

> key: will contain the key detected

> value: will contain the value detected

> line: the line to analyse

> Analyses a trivial "KEY value" line and returns the key and the value in the passed pointers.

> Return value: 1 if line OK (and in this case `key` and `value` are set), 0 if not.

— Function: int lw6msg_utils_parse_key_value_to_assoc (lw6sys_assoc_t ** assoc, char * line)

> assoc: an assoc object which will contain the result

> line: the line to analyse

> Analyses a trivial "KEY value" line and sets the `assoc` parameter according to detected values. Note that `assoc` must be set to contain string, and free them automatically with `lw6sys_free_callback` for instance.

> Return value: 1 if line OK (and in this case `assoc` is updated), 0 if not.

— Function: char * lw6msg_utils_get_assoc_str_with_default (lw6sys_assoc_t * assoc, char * key, char * default_value)

> assoc: the string assoc to query

> key: the key to find in the assoc

> default_value: the default value to return

> Queries a string assoc for a given value, and if not available, returns default value. Not that default value (nor the assoc value) is copied, so you must take care all remain valid until usage of returned value is over.

> Return value: a string, must not be freed.

— Function: int lw6msg_utils_get_assoc_int_with_default (lw6sys_assoc_t * assoc, char * key, int default_value)

> assoc: the string assoc to query

> key: the key to find in the assoc

> default_value: the default value to return

> Queries a string assoc for a given value, and if not available, returns default value. Not that default value (nor the assoc value) is copied, so you must take care all remain valid until usage of returned value is over. This one will returned an int converted with `lw6sys_atoi`.

> Return value: a string, must not be freed.

#### 4.15.17 libnet

— Function: int lw6net_dns_is_ip (char * ip)

> ip: the string to check

> Tests if a given string is a valid IP (IPV4). Test is only syntaxic, it's just to know if we're likely to need to query the DNS, it does not mean the IP is *really* valid.

> Return value: 1 if it's an IP, O if not.

— Function: char * lw6net_dns_gethostbyname (char * name)

> name: name of the host

> A wrapper over the standard gethostbyname function, will even accept an IP as an input (in this case, will copy it...) and allocate a new string for the result.

> Return value: an IP if success, 0 on error.

— Function: int lw6net_last_error ()

> Reports the last network error. This is basically a debug function, designed mostly for Microsoft Winsock API, but can be safely called on any platform.

> Return value: the last error code, has no universal meaning, depends on the platform you're working on.

— Function: char * lw6net_if_guess_local ()

> Guess the local IP address. This is not fool-proof, and it probably cannot be as we can't handle all user-specific configs involving multiple IP addresses, virtual private networks, and so on. But this is just to provide a default public IP address when starting a network game, saavy users can always specify the right interface/address if needed. Will return NULL if interface can't be guessed.

> Return value: the IP as a string, dynamically allocated

— Function: char * lw6net_if_guess_public_url (char * bind_ip, int bind_port)

> bind_ip: the IP address used to bind on

> bind_port: the IP port used to bind on

> Guess the server public url, based on `lw6net_if_guess_local` which tries to find a valid local IP address which is not loopback. This is only in case `bind_ip` is 0.0.0.0 (listen on all addresses) else it will just use `bind_ip` as you would expect. Function isn't foolproof, that's why one can override its default with a user settings.

> Return value: the IP as a string, dynamically allocated

— Function: char * lw6net_recv_line_tcp (int sock)

> sock: the socket descriptor

> Receives a line terminated by LF ("\n", chr(10)) or CR/LF ("\r\n", chr(10)chr(13)) on a TCP socket, that is, stream oriented. If there's no complete line available, function returns immediately with NULL. Same if socket is closed, broken, whatever. Only if there's something consistent will the function return non-NULL.

> Return value: a dynamically allocated string with the content received. The tailing (CR)/LF is stripped.

— Function: int lw6net_send_line_tcp (int sock, char * line)

> sock: the socket descriptor

> line: the line to be sent, without the "\n" at the end

> Sends a line terminated by LF ("\n", chr(10)) on a TCP socket, that is, stream oriented. The "\n" is automatically added, do not bother sending it.

> Return value: non-zero if success

— Function: char * lw6net_recv_line_udp (int sock, char ** incoming_ip, int * incoming_port)

> sock: the socket descriptor

> incoming_ip: the IP address of the sender (returned)

> incoming_port: the IP port of the sender (returned)

> Receives a line terminated by LF ("\n", chr(10)) or CR/LF ("\r\n", chr(10)chr(13)) on a UDP socket, that is, datagram oriented. If there's no complete line available, function returns immediately with NULL. Same if socket is closed, broken, whatever. Only if there's something consistent will the function return non-NULL. By-value parameters allow the caller to know where the data come from.

> Return value: a dynamically allocated string with the content received. The tailing (CR)/LF is stripped.

— Function: lw6sys_list_t * lw6net_recv_lines_udp (int sock, char ** incoming_ip, int * incoming_port)

> sock: the socket descriptor

> incoming_ip: the IP address of the sender (returned)

> incoming_port: the IP port of the sender (returned)

> Receives several lines terminated by LF ("\n", chr(10)) or CR/LF ("\r\n", chr(10)chr(13)) on a UDP socket, that is, datagram oriented. If there's no complete line available, function returns immediately with NULL. Same if socket is closed, broken, whatever. Only if there's something consistent will the function return non-NULL. By-value parameters allow the caller to know where the data come from. This variant of `lw6net_recv_line_tcp` will return a list of lines, this is mandatory since in UDP we can't call recv several times.

> Return value: a list of dynamically allocated strings. The tailing (CR)/LF is stripped from strings.

— Function: int lw6net_send_line_udp (int sock, char * line, char * ip, int port)

> sock: the socket descriptor

> line: the line to be sent, without the "\n" at the end

> ip: the IP address of the target

> port: the IP port of the target

> Sends a line terminated by LF ("\n", chr(10)) on a UDP socket, that is, datagram oriented. The "\n" is automatically added, do not bother sending it.

> Return value: the number of bytes sent, 0 if failure

— Function: int lw6net_init (int argc, char * [] argv)

> Initializes the low-level network API, you must call this before calling any other network related function, for it allocates a dynamic context which is in turn used by every function.

> Return value: non-zero if success

— Function: void lw6net_quit ()

> Frees memory, joins active threads, and releases everything set up by network code.

> Return value: void

— Function: int lw6net_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `net` module test suite. This one could fail if some sockets are already bound, for instance. It's still run even in check-only (mode=0) mode.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.18 libnod

— Function: void lw6nod_dyn_info_free (lw6nod_dyn_info_t * dyn_info)

> dyn_info: the dyn info struct to free

> Frees a dyn info object, to be used after a call to `lw6nod_info_dup_dyn` for instance.

> Return value: none

— Function: lw6nod_info_t * lw6nod_info_new (u_int64_t id, char * url, char * title, char * description, char * password, int bench, int idle_screenshot_size, void * idle_screenshot_data)

> id: the node id

> url: the node public url

> title: the node title

> description: the node description

> password: the node password

> bench: the node bench

> idle_screenshot_size: the size (bytes) of the image to display when game is idle

> idle_screenshot_data: the data (jpeg) of the image to display when game is idle

> Creates a node info object. The arguments correspond to the immutable node attributes, other properties such as how many players are connected or set in other functions like `lw6nod_info_update` which can be called later.

> Return value: newly allocated object, NULL on error.

— Function: void lw6nod_info_free (lw6nod_info_t * info)

> info: the node info to free

> Frees a node info object.

> Return value: none

— Function: int lw6nod_info_lock (lw6nod_info_t * info)

> info: the node info to lock

> Locks a node info object, this is usefull for some members, typically list of servers, can be accessed by separated threads, one reading, many writing, and these objects (chained lists) certainly do not want to be modified while being read.

> Return value: 1 if ok, 0 if not.

— Function: int lw6nod_info_unlock (lw6nod_info_t * info)

> info: the node info to unlock

> Unlocks a node info object, this is the compation of the `lw6nod_info_lock` function.

> Return value: 1 if ok, 0 if not.

— Function: void lw6nod_info_idle (lw6nod_info_t * info)

> info: the node info to modify

> Clears a node info object and sets all its variable attributes to NULL/default values. This is what we want when the node is idle, not playing.

> Return value: none.

— Function: int lw6nod_info_update (lw6nod_info_t * info, char * level, int required_bench, int nb_colors, int max_nb_colors, int nb_cursors, int max_nb_cursors, int nb_nodes, int max_nb_nodes, int game_screenshot_size, void * game_screenshot_data)

> info: the node info to update

> level: the name of the current level (map)

> required_bench: the bench required to connect

> nb_colors: number of colors playing

> max_nb_colors: max number of colors allowed

> nb_cursors: number of cursors playing

> max_nb_cursors: max number of cursors allowed

> nb_nodes: number of nodes playing

> max_nb_nodes: max number of nodes allowed

> game_screenshot_size: size of screenshot (bytes)

> game_screenshot_data: screenshot data (byte buffer, contains JPEG)

> Set a node info object variable attributes. Call this whenever the node has changed some parameter. Not too often for it's not needed and some operations such as modying the screenshot, can be time consuming.

> Return value: 1 if OK, 0 if error.

— Function: lw6nod_dyn_info_t * lw6nod_info_dup_dyn (lw6nod_info_t * info)

> info: the node info containing the dyn info to duplicate

> Extracts the dynamic part of an info struct and duplicates it, this is to avoid protection fault error when concurrent threads access this info.

> Return value: newly allocated object, must be freed.

— Function: lw6sys_hash_t * lw6nod_info_new_discovered_nodes ()

> Creates a new hash, to be used as a discovered nodes list. Using this function has the advantage of setting the hash options to their defaults. We use a hash to avoid having uselessly long lists containing always the same node due to multiple detections.

> Return value: an empty hash

— Function: int lw6nod_info_add_discovered_node (lw6nod_info_t * info, char * public_url)

> info: the node info to update

> public_url: the address of the discovered node

> Registers a new server, and queues it as something that should be checked later because it's interesting. We can't insert in the database all the servers we suspect to exist so network threads should use this, then main thread will process discovered servers afterwards. This is also a good way to avoid trivial DOS attacks.

> Return value: 1 if OK, O if error.

— Function: lw6sys_list_t * lw6nod_info_pop_discovered_nodes (lw6nod_info_t * info)

> info: the node info to query

> Returns a list of all discovered nodes (their public URL) and empties the current queue as well.

> Return value: a list of dynamically allocated strings.

— Function: lw6sys_list_t * lw6nod_info_new_verified_nodes ()

> Creates a new list, to be filled with nodes and typically passed to `lw6nod_info_set_verified_nodes`. Using this function has the advantage of setting the listh options to their defaults.

> Return value: an empty list

— Function: int lw6nod_info_set_verified_nodes (lw6nod_info_t * info, lw6sys_list_t * list)

> info: the node info to modify

> list: the list of verified nodes, will be freed by this function

> Sets the list of verified nodes, that is, the list of nodes we are sure to exist, this is typically the list we will display later on a web page. We can't directly display any discovered node, one needs to filter them through main thread. Something very important about this function is that `list` will be freed by function, that is, if you call this, then you can (you should) forget your object, it will disappear any time soon.

> Return value: 1 if OK, 0 on error.

— Function: void lw6nod_info_map_verified_nodes (lw6nod_info_t * info, lw6sys_list_callback_func_t func, void * func_data)

> info: the node info concerned

> func: the function to apply

> func_data: arbitrary pointer holding data to pass to function

> Calls `lw6sys_hash_map` with `func` on every member of the list of verified nodes. The reason there's a function for this is that it is very important that list object is locked when doing this. This function does perform a lock/unlock so it is safe.

> Return value: none.

— Function: int lw6nod_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `nod` module test suite.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.19 libp2p

— Function: lw6p2p_db_t * lw6p2p_db_open (int argc, char * [] argv, char * name)

> argc: number of args, as passed to `main`

> argv: args array, as passed to `main`

> name: the database name

> Creates a new database object. Normally there's only one object like this at a given time, it can be shared among various nodes. The database name is appended to user directory path, this allows different databases to be created, in theory.

> Return value: a pointer on the newly created object.

— Function: void lw6p2p_db_close (lw6p2p_db_t * db)

> db: the db to close

> Closes a db object, memory ressources will be freed.

> Return value: none.

— Function: char * lw6p2p_db_repr (lw6p2p_db_t * db)

> db: the db to work on

> Gives a readable representation of the db

> Return value: a dynamically allocated string

— Function: int lw6p2p_db_reset (int argc, char * [] argv, char * name)

> argc: number of args, as passed to `main`

> argv: args array, as passed to `main`

> name: the database name

> Clears the database. Simply removes the db file, in fact. Do not call while database is used...

> Return value: 1 on success, 0 if failed.

— Function: char * lw6p2p_db_default_name ()

> Returns the default database name, should be p2p.db (this is a relative path, not an absolute path, will be appended to user dir).

> Return value: the default database name, need not (must not) be freed.

— Function: int _lw6p2p_db_now (_lw6p2p_db_t * db)

> db: the db object concerned (used to calculate time origin)

> Returns a timestamp suitable for db usage. The reason we don't use regular timestamps is that they are 1) too accurate (msec is useless for what's involved here) and 2) too big and likely to be negative in signed mode even if converted to seconds.

> Return value: a timestamp, 0 means "beginning of program" (think of it as uptime)

— Function: lw6p2p_node_t * lw6p2p_node_new (int argc, char * [] argv, lw6p2p_db_t * db, char * client_backends, char * server_backends, char * bind_ip, int bind_port, u_int64_t node_id, char * public_url, char * password, char * title, char * description, int bench, char * known_nodes)

> argc: number of args, as passed to `main`

> argv: args array, as passed to `main`

> db: the database to use

> client_backends: the list of client backends to use

> server_backends: the list of server backends to use

> bind_ip: the IP address to bind on

> bind_port: the IP port to listen on

> node_id: the server unique ID

> public_url: the public URL we want to show

> password: the password to use

> title: the title of the node

> description: the description of the node

> bench: the bench of the node (its power)

> known_nodes: list of already known nodes

> Creates a new "pear to pear" node. This will fire the server and allow client access, on demand. A lot of stuff can be done in the background once this is called.

> Return value: a pointer on the newly created objects.

— Function: void lw6p2p_node_free (lw6p2p_node_t * node)

> node: the node to free

> Frees a node object, all network communications will be shut.

> Return value: none.

— Function: char * lw6p2p_node_repr (lw6p2p_node_t * node)

> node: the node to work on

> Gives a readable representation of the node

> Return value: a dynamically allocated string

— Function: int lw6p2p_node_poll (lw6p2p_node_t * node)

> node: the node to poll

> Polls a p2p node. This must be called on a regular basis, else network communication is stalled.

> Return value: 1 on success, 0 on error.

— Function: void lw6p2p_node_close (lw6p2p_node_t * node)

> node: the node to close

> Closes a p2p node. Closing is necessary in some contexts, for instance scheme/smob instanciation when you want to release the object ressources (sockets, ports, threads...) *before* it is deleted by, for instance, a garbage collector.

> Return value: 1 on success, 0 on error.

— Function: int lw6p2p_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `p2p` module test suite. This test can fail if one cannot bind on some network port, in a general manner it is dependent on the network environment, so it's better if there's some sort of human control on it.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.20 libpil

— Function: int lw6pil_bench (float * bench_result, lw6sys_progress_t * progress)

> bench_result: pointer to float, will contain the bench result

> progress: to inform the caller of the process advancement

> Runs a standard, normalized bench on a default map. Results can be interpreted as an estimated speed/power of your computer.

> Return value: 1 on success, 0 if failure

— Function: void lw6pil_coords_fix (lw6map_rules_t * rules, lw6sys_whd_t * shape, float * x, float * y, float * z)

> rules: the set of rules to use (defines polarity)

> shape: the shape of the map (logical part)

> x: the x coord to fix

> y: the y coord to fix

> z: the z coord to fix

> Similar to `lw6map_coords_fix` but using floats, this function can be used to check cursor position boundaries. Any float pointer can be NULL.

> Return value: none.

— Function: void lw6pil_local_cursors_reset (lw6pil_local_cursors_t * local_cursors)

> Resets a local cursors struct. Note that this need not be called very often, in fact the local cursors can cope with "dead" cursors easily. In practise, in a local game, there are only 4 of them, great maximum.

> Return value: none.

— Function: lw6pil_local_cursor_t * lw6pil_local_cursors_get_cursor (lw6pil_local_cursors_t * local_cursors, u_int16_t cursor_id)

> cursor_id: the id of the cursor to query

> Returns a pointer on the cursor with the given id.

> Return value: a pointer (must *not* be freed) which is NULL is cursor does not exist.

— Function: int lw6pil_local_cursors_get_info (lw6pil_local_cursors_t * local_cursors, int * x, int * y, int * mouse_controlled, u_int16_t cursor_id)

> x: a pointer to the x position, may be NULL

> y: a pointer to the y position, may be NULL

> mouse_controlled: a pointer to the mouse_controlled flag, may be NULL

> cursor_id: the id of the cursor to query

> Gets the x,y position of the cursor, and tells if it's mouse controlled.

> Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

— Function: int lw6pil_local_cursors_set_xy (lw6pil_local_cursors_t * local_cursors, u_int16_t cursor_id, int x, int y)

> cursor_id: the id of the cursor to modify

> x: the x position

> y: the y position

> Sets the position of a cursor in the local cursors struct. If cursor does not exists, it's appended to the list.

> Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

— Function: int lw6pil_local_cursors_set_mouse_controlled (lw6pil_local_cursors_t * local_cursors, u_int16_t cursor_id, int mouse_controlled)

> cursor_id: the id of the cursor to modify

> mouse_controlled: the mouse_controlled attribute

> Sets which cursor is mouse controlled. If mouse_controlled is 1, the flag is set for this cursor and cleared for all others. If set to 0, only this cursor's flag is cleared.

> Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

— Function: int lw6pil_local_cursors_get_main_info (lw6pil_local_cursors_t * local_cursors, u_int16_t * cursor_id, int * x, int * y, int * mouse_controlled)

> cursor_id: the id of the main cursor, may be NULL

> x: a pointer to the x position, may be NULL

> y: a pointer to the y position, may be NULL

> mouse_controlled: a pointer to the mouse_controlled flag, may be NULL

> Gets the x,y position of the main cursor, and tells if it's mouse controlled.

> Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

— Function: int lw6pil_local_cursors_set_main (lw6pil_local_cursors_t * local_cursors, u_int16_t cursor_id)

> cursor_id: the id of the cursor to be labelled as main cursor

> Sets the main cursor attribute, the main cursor is later used, for instance, to decide how to display the map (centered on it, for instance).

> Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

— Function: lw6pil_pilot_t * lw6pil_pilot_new (lw6ker_game_state_t * game_state, int64_t timestamp, lw6sys_progress_t * progress)

> game_state: the game state we're going to work on

> timestamp: the current ticks (1000 ticks per sec, used to calibrate)

> progress: object used to show the advancement of the process

> Initializes a 'pilot' object, this object is responsible for interpreting messages, transform them into low-level 'ker' module function calls, and handle all the thread-spooky stuff.

> Return value: a working pilot object. May be NULL on memory failure.

— Function: void lw6pil_pilot_free (lw6pil_pilot_t * pilot)

> pilot: the object to free.

> Frees a 'pilot' object, note that this might involve joining some threads, so it can 'take some time'.

> Return value: none.

— Function: int lw6pil_pilot_send_command (lw6pil_pilot_t * pilot, char * command_text, int verified)

> pilot: the object to send commands to.

> command_text: the text of the command, as received form network

> verified: wether we're sure this message is valid.

> Sends a command and handles it internally.

> Return value: 1 if OK, 0 if not.

— Function: int lw6pil_pilot_local_command (lw6pil_pilot_t * pilot, char * command_text)

> pilot: the object to apply the local command on

> command_text: the command text

> This function is used to fix the annoying fact that by only sending commands a limited number of times per sec to the game state, the display always reflect an outdated position for cursors. But players do not want to see this, they want to see the cursor in the right place. So what we do is that the pilot can process "local" commands which have absolutely no effect on the game but simply update a local cursor state, only used for display. It's here in the pil module for it's where the command interpreting code is, and the fact that there's this lag is directly linked with the pilot way of doing things.

> Return value: 1 on success, 0 on failure.

— Function: int lw6pil_pilot_commit (lw6pil_pilot_t * pilot)

> pilot: the object to commit.

> Commits all commands sent and actually send them to the corresponding threads. This commit system allows better performance by sending, for instance, all the commands for a given round together.

> Return value: none.

— Function: int lw6pil_pilot_make_backup (lw6pil_pilot_t * pilot)

> pilot: the object to perform the backup on

> Makes a new backup in the pilot, that is, copy 'reference' to 'backup'.

> Return value: 1 if OK, 0 if not.

— Function: int lw6pil_pilot_can_sync (lw6ker_game_state_t * target, lw6pil_pilot_t * pilot)

> target: the target game_state we would sync on

> pilot: the object to perform the backup on

> Tests wether sync functions are callable with a given game state. It verifies if the internal game_state and the target look the same.

> Return value: 1 if sync functions can be called, 0 if not.

— Function: int lw6pil_pilot_sync_from_backup (lw6ker_game_state_t * target, lw6pil_pilot_t * pilot)

> target: the game_state structure which will get the informations.

> pilot: the object to get informations from.

> Gets the backup from the pilot object. This is the last snapshot taken by `make_backup` or, by default, the game_state the pilot was constructed with.

> Return value: 1 if OK, 0 if not.

— Function: int lw6pil_pilot_sync_from_reference (lw6ker_game_state_t * target, lw6pil_pilot_t * pilot)

> target: the game_state structure which will get the informations.

> pilot: the object to get informations from.

> Gets the latest reference game_state, that is, a stable snapshot of the game, with no inconsistency, a game position that exists and that we can rely on. Note that getting this can take time since a global mutex is required, and computations must end before you get the data.

> Return value: 1 if OK, 0 if not.

— Function: int lw6pil_pilot_sync_from_draft (lw6ker_game_state_t * target, lw6pil_pilot_t * pilot, int dirty_read)

> target: the game_state structure which will get the informations.

> pilot: the object to get informations from.

> dirty_read: wether to allow dirty read or not

> Gets the informations from the pilot object, not being worried about game consistency, this one will just return the latest version available. It might even be in an inconsistent state, the position could reflect a position which will never exist. Still, the data returned will not correspond to a half-spread or half-moved game_state if dirty_read is set to 0. In this case the data has at least some basic consistency and getting this does require some mutex lock, however wait time should be fairly small (max. a round). But, in a general manner, this function is only used for display, and we do not care much if there's a small glitch, we prefer fast & smooth display.

> Return value: 1 if OK, 0 if not.

— Function: lw6ker_game_state_t * lw6pil_pilot_dirty_read (lw6pil_pilot_t * pilot)

> pilot: the object to get informations from.

> Returns a direct access to the most up-to-date game_state, without locking anything whatsoever. This is clearly to implement a dirty read mode as the name of the function suggests.

> Return value: 1 if OK, 0 if not.

— Function: char * lw6pil_pilot_repr (lw6pil_pilot_t * pilot)

> Returns a string describing the pilot. This is a very short description, use it for logs, and to debug stuff. By no means it's a complete exhaustive description. Still, the string returned should be unique.

> Return value: a dynamically allocated string.

— Function: void lw6pil_pilot_calibrate (lw6pil_pilot_t * pilot, int64_t timestamp, int round)

> pilot: the object to calibrate

> timestamp: the current ticks setting (1000 ticks per second)

> round: the round expected to be returned with this ticks value

> Calibrates the pilot, that is, initializes it so that subsequent calls to `lw6pil_pilot_get_round` return consistent values.

> Return value: none.

— Function: void lw6pil_pilot_speed_up (lw6pil_pilot_t * pilot, int round_inc)

> pilot: the pilot to speed up

> round_inc: the number of rounds

> Re-calibrates the pilot so that it speeds up a bit. This will basically increase next_round by round_inc.

> Return value: none.

— Function: void lw6pil_pilot_slow_down (lw6pil_pilot_t * pilot, int round_dec)

> pilot: the pilot to speed up

> round_dec: the number of rounds

> Re-calibrates the pilot so that it slows down a bit. This will basically decrease next_round by round_inc.

> Return value: none.

— Function: int lw6pil_pilot_get_next_round (lw6pil_pilot_t * pilot, int64_t timestamp)

> pilot: the object to query

> timestamp: the current ticks setting (1000 ticks per second)

> Returns the round one should use to generate new events/commands at a given time (given in ticks).

> Return value: none.

— Function: int lw6pil_pilot_get_last_commit_round (lw6pil_pilot_t * pilot)

> pilot: the object to query

> Returns the round of the last commit (reference game_state) for this object.

> Return value: the commit round (reference object)

— Function: int lw6pil_pilot_get_reference_target_round (lw6pil_pilot_t * pilot)

> pilot: the object to query

> Returns the round which is targetted in the reference game_state, this is 'how far computation will go in the reference game_state if no new commands are issued'. Note that there can always be some commands which are not yet processed, so you should not rely on this too heavily, however it gives a good idea of how things are going.

> Return value: the target round (reference object)

— Function: int lw6pil_pilot_get_reference_current_round (lw6pil_pilot_t * pilot)

> pilot: the object to query

> Returns the current round in the reference game_state. There's no lock on this call so don't rely on this too heavily, it just gives you an idea of wether the pilot is very late on its objectives or just on time.

> Return value: the current round (reference object)

— Function: int lw6pil_pilot_get_max_round (lw6pil_pilot_t * pilot)

> pilot: the object to query

> Returns the max current round in the reference or draft game states. No lock on this call so don't rely on this too heavily, it just gives you an idea of computation state.

> Return value: the current round (reference object)

— Function: int lw6pil_pilot_is_over (lw6pil_pilot_t * pilot)

> pilot: the object to query

> Tells wether the game is over or not.

> Return value: 1 if over, 0 if not

— Function: int lw6pil_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `pil` module test suite.

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.21 libsnd

— Function: int lw6snd_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `snd` module test suite. If run in check mode (0), won't really perform the test, since it could fail because of hardware problems, context, permissions...

> Return value: 1 if test is successfull, 0 on error.

#### 4.15.22 libsrv

— Function: lw6srv_oob_t * lw6srv_oob_new (char * remote_ip, int remote_port, int sock, char * first_line)

> remote_ip: remote IP address

> remote_port: remote port

> sock: the socket handler (either TCP or UDP)

> first_line: the first line of data (can be NULL)

> Create a new OOB structure, copying required objects. We need to make copies for this is for usage in a separate thread. The thread member is not set here since the right way to do things is first to set up data then to fire the thread.

> Return value: new object

— Function: void lw6srv_oob_free (lw6srv_oob_t * oob)

> oob: the object to free

> Frees an OOB structure.

> Return value: none

— Function: lw6srv_tcp_accepter_t * lw6srv_tcp_accepter_new (char * client_ip, int client_port, int sock)

> client_ip: the client ip, will be freed when accepter is freed, do not copy it

> client_port: the client port

> sock: the socket used

> Creates a tcp_accepter object.

> Return value: none

— Function: void lw6srv_tcp_accepter_free (lw6srv_tcp_accepter_t * tcp_accepter)

> tcp_accepter: the object to free

> Frees a tcp_accepter object.

> Return value: none

— Function: int lw6srv_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `srv` module test suite.

> Return value: 1 if test is successfull, 0 on error.

— Function: lw6srv_udp_buffer_t * lw6srv_udp_buffer_new (char * client_ip, int client_port, char * line)

> client_ip: the client ip, will be freed when object is freed, do not free it

> client_port: the client port

> line: the line received, will be freed when object is freed, do not free it

> Creates an udp_buffer object.

> Return value: none

— Function: void lw6srv_udp_buffer_free (lw6srv_udp_buffer_t * udp_buffer)

> udp_buffer: the object to free

> Frees a udp_buffer object.

> Return value: none

#### 4.15.23 libsys

— Function: int lw6sys_arg_match (char * keyword, char * argv_string)

> keyword: the option to match, without the prefix "-" or "–"

> argv_string: the argv value, for instance argv[1]

> This is an utility function which allow the program to handle options in a uniform manner. Key comparison is insensitive, that is, –option and –OPTION are equivalent. Besides, -option and –OPTION are equivalent too. Liquid War 6 documentation mentions options in lowercase with a double dash (–option) by default, but it's a fact, the program supports variants. This is just for convenience, the philosophy behind this behavior is "be as permissive as possible when interpreting input, and as strict as possible when generating output". In fact, it's even said that Liquid War 6 will accept the argument without any prefix dash as being valid... This is to say running "liquidwar6 –option" is the same as running "liquidwar6 option". But, this is a secret 8-)

> Return value: non zero if it matches, 0 if it doesn't.

— Function: int lw6sys_arg_exists (int argc, char * [] argv, char * keyword)

> argc: the number of arguments, as passed to `main`

> argv: an array of arguments, as passed to `main`

> keyword: the keyword to match

> Parses all command-line arguments, searching for one precise "–key[=...]" entry.

> Return value: 1 if key is present, 0 if not.

— Function: char * lw6sys_arg_get_value (int argc, char * [] argv, char * keyword)

> argc: the number of arguments, as passed to `main`

> argv: an array of arguments, as passed to `main`

> keyword: the keyword to match

> Parses all command-line arguments, searching for one precise "–key=value" pair, and returns the value.

> Return value: a pointer to the value. May be NULL. Must be freed.

— Function: char * lw6sys_arg_get_value_with_env (int argc, char * [] argv, char * keyword)

> argc: the number of arguments, as passed to `main`

> argv: an array of arguments, as passed to `main`

> keyword: the keyword to match

> Parses all command-line arguments, searching for one precise "–key=value" pair, and returns the value. If a corresponding environment variable is available, but no command-line parameter was passed, the environment variable is intepreted. Such environment variables are uppercased, prefixed by "LW6_" and "_" replaces "-". The environment variable will be overriden if the command-line parameter is present.

> Return value: a pointer to the value. May be NULL. Must be freed.

— Function: int lw6sys_arg_test_mode (int argc, char * [] argv)

> argc: argc as passed to main

> argv: argv as passed to main

> Chooses between the two test modes "check" or "test". Check (value 0) is a lighter test which should never fail even if some special hardware or environment is missing. Test (value 1) is a more complete test which does things which *can* require some special conditions. Function will log and be verbose is syntax is not correct.

> Return value: 1 if complete test must be run, 0 is only check

— Function: lw6sys_assoc_t * lw6sys_assoc_new (lw6sys_free_func_t free_func)

> free_func: optional callback used to free memory when stored date is a pointer. Can be NULL when one stores non dynamically allocated data, such as an integer or a static array.

> Creates an empty assoc. There's a difference between NULL and an empty assoc. The empty assoc would (in Scheme) be '() whereas NULL corresponds to undefined "is not a assoc and will generate errors if you ever call assoc functions on it". Such created assoc are not performant hash tables but slowish "strcmp me for each key" associative arrays, the key being a "char *" string and the value a "void *" pointer.

> Return value: a pointer to the newly allocated associative array. Must be freed with `lw6sys_assoc_free`.

— Function: void lw6sys_assoc_free (lw6sys_assoc_t * assoc)

> assoc: the assoc to be freed.

> The function will cascade delete all elements, using (if not NULL...) the callback passed when first creating the assoc.

> Return value: void

— Function: int lw6sys_assoc_has_key (lw6sys_assoc_t * assoc, char * key)

> assoc: the assoc to test

> key: the key to search

> Not a very fast function, since on a "big" assoc, strcmp will be called internally until the key is found.

> Return value: non-zero if there's an entry with the corresponding key.

— Function: void * lw6sys_assoc_get (lw6sys_assoc_t * assoc, char * key)

> assoc: the assoc to query

> key: the key of which we want the value

> Return value: a void pointer to the data contained in the assoc. Note that the pointer on the actual data is returned, that is, if it's static data, you must not try to free it... As long as memory management is concerned, destroying the assoc will actually free the data if needed.

— Function: void lw6sys_assoc_set (lw6sys_assoc_t ** assoc, char * key, void * value)

> assoc: the assoc to modify

> key: the key we want to updated

> value: the new value

> Sets a value in an associative array. The key pointer need not be persistent, it can be freed after affectation. In fact a new string will be created internally. This is not true for the value, it's hard to find way to copy "any object". So if you want an associative array of strings, key can disappear after calling this function, but not value. The function passed as free_func when creating the assoc will be used to free stuff whenever needed (unset or free).

> Return value: void

— Function: void lw6sys_assoc_unset (lw6sys_assoc_t * assoc, char * key)

> assoc: the assoc concerned

> key: the key to unset

> Clears an entry in an associative array. The callback passed when creating the assoc will be called if needed, to free the data automatically.

> Return value: void

— Function: lw6sys_list_t * lw6sys_assoc_keys (lw6sys_assoc_t * assoc)

> assoc: the assoc to work on

> Returns a list containing all the keys of the assoc. The list must be free with lw6sys_list_free by the caller. This list copies all the keys of the assoc, so it is safe to use it once the assoc is deleted. However the keys will of course be of little interest in this case. But the program won't segfault.

> Return value: the list of keys.

— Function: void lw6sys_assoc_map (lw6sys_assoc_t * assoc, lw6sys_assoc_callback_func_t func, void * func_data)

> assoc: the assoc to work on

> func: a callback to call on each entry

> func_data: a pointer on some data which will be passed to the callback

> Executes a function on all assoc items. The func_data parameter allows you to pass extra values to the function, such as a file handler or any variable which can not be inferred from list item values, and you of course do not want to make global...

> Return value: void

— Function: void lw6sys_assoc_sort_and_map (lw6sys_assoc_t * assoc, lw6sys_assoc_callback_func_t func, void * func_data)

> assoc: the assoc to work on

> func: a callback to call on each entry, may be NULL

> func_data: a pointer on some data which will be passed to the callback

> Executes a function on all assoc items, like `lw6sys_assoc_sort_and_map` but befor doing so, sorts all entries in alphabetical order.

> Return value: void

— Function: lw6sys_assoc_t * lw6sys_assoc_dup (lw6sys_assoc_t * assoc, lw6sys_dup_func_t dup_func)

> assoc: the assoc to duplicate, can be NULL

> dup_func: the function which will be called to duplicate data

> Duplicates an assoc. All keys will be copied so that if the first assoc is deleted, the duplicated one is fine. Additionnaly, dup_func will be called with all data fields. If dup_func is NULL, then data values will simply be copied. This is likely to be usefull when data is not dynamically allocated.

> Returned value: a newly allocated assoc.

— Function: int lw6sys_default_memory_bazooka ()

> Will set up a default memory bazooka, a slow yet convenient tool to track down and hopefully kill memory leaks. Named bazooka after a night wasted to track down an unfoundable leak... BAZOOOOOOKA!!!

> Return value: 1 if success, 0 if failed.

— Function: void lw6sys_clear_memory_bazooka ()

> Clears the memory bazooka.

> Return value: none.

— Function: int lw6sys_set_memory_bazooka_size (int size)

> size: number of items (calls to malloc) to keep

> Resizes, the memory bazooka. What's this? It's an inelegant yet efficient tool to track down memory leak. Memory bazooka will keep track of every call to malloc, keeping a trace of what has been malloced, where it has been called (from which file, which line), how much memory was allocated, it will even show you what's at the address in a 0-terminated string-friendly fashion. Of course this slows down the program, so in production, you might set this to 0, but for debugging, a million bazooka is worth the megabytes and CPU cycles it wastes.

> Return value: 1 if success, 0 if failure.

— Function: int lw6sys_get_memory_bazooka_size ()

> The companion of `lw6sys_set_memory_bazooka_size`. This function will return how many calls to malloc can be traced. A return value of 0 indicates that feature is disabled.

> Return value: size of the bazooka array.

— Function: int lw6sys_set_memory_bazooka_eraser (int state)

> state: the state of the eraser

> Sets the memory bazooka eraser state. Note that to really work, it requires the memory bazooka to be "big enough".

> Return value: 1 if activated, 0 if not. Note that the main reason for it not to be activated is if the memory bazooka has zero size.

— Function: int lw6sys_get_memory_bazooka_malloc_count ()

> Provided you have always called the `LW6SYS_MALLOC` an `LW6SYS_CALLOC` to allocate memory, this function will tell you how many times `malloc` has been called.

> Return value: the number of calls to `lw6sys_malloc` or `lw6sys_calloc` since program was started.

— Function: int lw6sys_get_memory_bazooka_free_count ()

> Provided you have always called the `LW6SYS_FREE` macro to free memory, this function will tell you how many times `free` has been called.

> Return value: the number of calls to `lw6sys_free` since program was started.

— Function: int lw6sys_get_memory_bazooka_malloc_current_count ()

> Provided you have always called the `LW6SYS_MALLOC` an `LW6SYS_CALLOC` to allocate memory, this function will tell you the current number of pointer returned by `LW6SYS_MALLOC` an `LW6SYS_CALLOC`, currently alive on the heap.

> Return value: the number of calls to `lw6sys_malloc` or `lw6sys_calloc` since program was started.

— Function: int lw6sys_get_memory_bazooka_malloc_max_count ()

> Provided you have always called the `LW6SYS_MALLOC` an `LW6SYS_CALLOC` to allocate memory, this function will tell you the maximum of pointers returned by `malloc` that were present at the same time on the heap.

> Return value: the number of calls to `lw6sys_malloc` or `lw6sys_calloc` since program was started.

— Function: int lw6sys_get_memory_bazooka_malloc_megabytes ()

> Provided you have always called the `LW6SYS_MALLOC` an `LW6SYS_CALLOC` to allocate memory, this function will tell you how many bytes `malloc` has reserved.

> Return value: the number of calls to `lw6sys_malloc` or `lw6sys_calloc` since program was started.

— Function: int lw6sys_get_memory_bazooka_free_megabytes ()

> Provided you have always called the `LW6SYS_FREE` macro to free memory, this function will tell you how many bytes `free` has freed.

> Return value: the number of calls to `lw6sys_free` since program was started.

— Function: int lw6sys_get_memory_bazooka_malloc_current_bytes ()

> Provided you have always called the `LW6SYS_MALLOC` an `LW6SYS_CALLOC` to allocate memory, this function will tell you the current number of bytes returned by `LW6SYS_MALLOC` an `LW6SYS_CALLOC`, currently alive on the heap.

> Return value: the number of calls to `lw6sys_malloc` or `lw6sys_calloc` since program was started.

— Function: int lw6sys_get_memory_bazooka_malloc_max_bytes ()

> Provided you have always called the `LW6SYS_MALLOC` an `LW6SYS_CALLOC` to allocate memory, this function will tell you the maximum bytes returned by `malloc` that were present at the same time on the heap.

> Return value: the number of calls to `lw6sys_malloc` or `lw6sys_calloc` since program was started.

— Function: int lw6sys_is_memory_bazooka_trustable ()

> Returns true if memory bazooka data are perfectly trustable, that is, it has never been resetted or resized.

> Return value: 1 if trustable, 0 if not.

— Function: int lw6sys_memory_bazooka_report ()

> Reports memory bazooka diagnostics on the console. Carefull, this one is not reentrant, call at the end of your program when all threads are joined.

> Return value: 1 if no allocated stuff left, 0 if there are still malloc'ed stuff

— Function: char * lw6sys_build_get_package_tarname ()

> Returns the name of the package. This is the `PACKAGE_TARNAME` constant defined by the GNU Autoconf ./configure script. While it's always possible to use the defined constant directly, using this function will return the value defined when compiling the binary, not the one you're using when compiling another program relying on Liquid War as a library.

> Return value: a non-NULL string "liquidwar6", must not be freed.

— Function: char * lw6sys_build_get_package_name ()

> Returns the name of the package, in a user friendly form, which can include spaces, for instance. This is the `PACKAGE_NAME` constant defined by the GNU Autoconf ./configure script. While it's always possible to use the defined constant directly, using this function will return the value defined when compiling the binary, not the one you're using when compiling another program relying on Liquid War as a library.

> Return value: a non-NULL string "Liquid War 6", must not be freed.

— Function: char * lw6sys_build_get_package_string ()

> Returns the description of the package. This is the `PACKAGE_STRING` constant defined by the GNU Autoconf ./configure script. It's the concatenation of `PACKAGE_NAME` and `VERSION`. While it's always possible to use the defined constant directly, using this function will return the value defined when compiling the binary, not the one you're using when compiling another program relying on Liquid War as a library.

> Return value: a non-NULL string "Liquid War 6 <version>", must not be freed.

— Function: char * lw6sys_build_get_version ()

> Returns the version of the program. This is the `VERSION` constant defined by the GNU Autoconf ./configure script. Same as `PACKAGE_VERSION`. Note that while using a function to get `PACKAGE_TARNAME` might seem useless, having both ways to get the version, that is, a function and a constant, is very usefull. Think, for instance, that a dynamically loaded shared library might need to check its own version against the version of the core program.

> Return value: a non-NULL string, which must not be freed.

— Function: char * lw6sys_build_get_codename ()

> Returns the the program codename. This is the little name of the version. It's been decided that all LW6 releases would take the name of a famous general, warrior, whatever. For instance, it could be "Napoleon".

> Return value: a non-NULL string, traditionnally the name of a famous general, someone which has been involved in war. Must not be freed (I mean, the string, not the general).

— Function: char * lw6sys_build_get_stamp ()

> Returns the program stamp. This is like a serial number. It's is not the same as the version. The version is meant to be set to something readable. This is just a cryptic thing, incremented at each ./configure or each developper's "I feel like it needs to be incremented". The idea is just to keep (one more...) track of which source code is build. Ideally, this would be plugged to the source revision control system but this has some drawbacks, including that it would require it to modify files before commiting them, which is not safe, and almost impossible if you sign archives. One more point: this is a string. It's true the return value is actually a string containing the representation of an integer, but because all other build parameters are strings, and because we don't know what the future reserves, it's a string.

> Return value: a non-NULL string like "42", which must not be freed.

— Function: char * lw6sys_build_get_md5sum ()

> Returns an md5 checkum which is caculated from C (.c and .h) source files. This is complementary with the build stamp. By default the stamp will be enough to check what has been compiled, but one can always imagine a case where Bob compiles something a little different than Alice, with the same stamp, incremented by 1 from a common source tree. They apply their own patches, for instance. This md5sum double-checks that two binaries have been built from the same sources. Note that this is not the md5 checksum of the generated binary. Nor does it include any information about scheme scripts and data.

> Return value: a non-NULL string, which must not be freed.

— Function: char * lw6sys_build_get_copyright ()

> Returns a (very) short copyright information about the program.

> Return value: a non-NULL string, single line whithout '\n' at the end. Must not be freed.

— Function: char * lw6sys_build_get_license ()

> Returns the license for the program (GNU GPL v3 or later).

> Return value: a non-NULL string, single line whithout '\n' at the end. Must not be freed.

— Function: char * lw6sys_build_get_url ()

> Returns the URL of the game, its homepage.

> Return value: a non-NULL string, single line whithout '\n' at the end. Must not be freed.

— Function: char * lw6sys_build_get_configure_args ()

> Returns the arguments passed to the GNU Autoconf ./configure script when buildling the game. Very usefull to know how the binary was generated, that is, what kind of optimizations are peculiar settings it uses.

> Return value: a non-NULL string, which, passed to ./configure again, would hopefully generate the same binary. Must not be freed.

— Function: char * lw6sys_build_get_gcc_version ()

> Returns __VERSION__ GCC preprocessor value, that is, the human readable version of the compiler.

> Return value: a non-NULL string, must not be freed.

— Function: char * lw6sys_build_get_cflags ()

> Returns the arguments which would allow another program to use liquidwar6 as a library. Typically, pass this to gcc when compiling your sources. Basically contains "-I" switches which tell where the headers are.

> Return value: a non-NULL string, which must not be freed.

— Function: char * lw6sys_build_get_ldflags ()

> Returns the arguments which would allow another program to link against liquidwar6. Pass this to gcc or libtool when compiling your program. Basically contains a "-L" option which says where the library is. Note that this will only allow you to link against the main libliquidwar6 library, but not the dynamically loaded modules.

> Return value: a non-NULL string, which must not be freed.

— Function: char * lw6sys_build_get_hostname ()

> Returns the value return by the standard shell `hostname` command on the machine where the game has been built. Usefull to track binaries and know where do they come from.

> Return value: a non-NULL string, must not be freed.

— Function: char * lw6sys_build_get_date ()

> Returns the compilation date. While this information can easily be obtained with the C `__DATE__` macro, having this function is convenient for it returns a value which is the same for the whole program, and does not possibly change in every file.

> Return value: a non-NULL string, must not be freed.

— Function: char * lw6sys_build_get_time ()

> Returns the compilation date. While this information can easily be obtained with the C `__TIME__` macro, having this function is convenient for it returns a value which is the same for the whole program, and does not possibly change in every file.

> Return value: a non-NULL string, must not be freed.

— Function: char * lw6sys_build_get_host_cpu ()

> Returns the CPU this program is designed for. Convenient on i386 compatible CPUs to know which flavor (i386, i586...) the binary is made for.

> Return value: a non-NULL string, must not be freed.

— Function: char * lw6sys_build_get_endianness ()

> Returns the endianness of the computer.

> Return value: 'little' (x86-like) or 'big' (ppc-like), as a string. Must not be freed.

— Function: int lw6sys_build_get_pointer_size ()

> Returns the system pointer size, in bytes.

> Return value: 4 for 32-bit, 8 for 64-bit.

— Function: int lw6sys_build_is_x86 ()

> Tells wether CPU belongs to x86 family or not.

> Return value: 1 if x86, 0 if not

— Function: char * lw6sys_build_get_host_os ()

> Returns the OS this program is designed for. Usefull for bug reports.

> Return value: a non-NULL string, must not be freed.

— Function: int lw6sys_build_is_ms_windows ()

> Tells wether the program was compiled for Microsoft Windows, or not.

> Return value: 1 if compiled on windows, 0 if not

— Function: int lw6sys_build_is_mac_os_x ()

> Tells wether the program was compiled for Mac OS X, or not.

> Return value: 1 if compiled on OS X, 0 if not

— Function: int lw6sys_build_is_gp2x ()

> Tells wether the program was compiled for GP2X, or not.

> Return value: 1 if compiled on OS X, 0 if not

— Function: char * lw6sys_build_get_top_srcdir ()

> Returns the top source directory, when the game was built. This can seem useless and non relevant on the end-user's machine, but... it's a must-have for developpers and packagers. Without this, binaries would never find their associated data, especially when building outside the source tree. Or, testing the game would be impossible without installing it, given the fact that most of the code is in scripts that are stored in /usr/local by default, this would be painfull. So this function is here to help finding data within the source tree when the game is not installed yet. Note that the function is rather clever, since it will automatically try to remove useless '../' sequences at the beginning of a possibly relative path.

> Return value: a non-NULL string, must not be freed.

— Function: char * lw6sys_build_get_prefix ()

> Returns the `prefix` value as given to the GNU Autoconf ./configure script. Used to deduce the path to other directories and files.

> Return value: a non-NULL string, "/usr/local" by default. Must not be freed.

— Function: char * lw6sys_build_get_datadir ()

> Returns the `datadir` value defined by the GNU Autoconf ./configure script. This is not the value which can be overriden by the Liquid War 6 specific. "–data-dir" option. `datadir` is usually something like "/usr/local/share" while the actual Liquid War 6 defined data dir is a more profound path which includes the name of the package, its version, and so on.

> Return value: a non-NULL string, "/usr/local/share" by default. Must not be freed.

— Function: char * lw6sys_build_get_libdir ()

> Returns the `libdir` value defined by the GNU Autoconf ./configure script. This is not the value which can be overriden by the Liquid War 6 specific. "–mod-dir" option. `libdir` is usually something like "/usr/local/lib" while the actual Liquid War 6 defined module dir is a more profound path which includes the name of the package, its version, and so on.

> Return value: a non-NULL string, "/usr/local/lib" by default. Must not be freed.

— Function: char * lw6sys_build_get_includedir ()

> Returns the `includedir` value defined by the GNU Autoconf ./configure script. As for other options, it's interesting to have this value, this enables the program to inform people who want to hack the game of the place headers are supposed to be installed.

> Return value: a non-NULL string, "/usr/local/include" by default. Must not be freed.

— Function: char * lw6sys_build_get_localedir ()

> Returns the `localedir` value defined by the GNU Autoconf ./configure script. Used as an argument for gettext / libintl functions.

> Return value: a non-NULL string, "/usr/local/share/locale" by default. Must not be freed.

— Function: char * lw6sys_build_get_docdir ()

> Returns the `docdir` value defined by the GNU Autoconf ./configure script. Used to write consistent XML file headers.

> Return value: a non-NULL string, "/usr/local/share/doc/liquidwar6" by default. Must not be freed.

— Function: char * lw6sys_build_get_enable_console ()

> Tells wether console is enabled or not.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_gtk ()

> Tells wether gtk is enabled or not.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_mod_gl ()

> Tells wether the graphical mod-gl backend was compiled.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_mod_csound ()

> Tells wether the audio mod-csound backend was compiled.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_mod_ogg ()

> Tells wether the audio mod-ogg backend was compiled.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_mod_http ()

> Tells wether the network mod-http backend was compiled.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_optimize ()

> Tells wether the game was compiled in optimize mode.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_allinone ()

> Tells wether the game was compiled in allinone mode.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_fullstatic ()

> Tells wether the game was compiled in fullstatic mode.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_paranoid ()

> Tells wether the game was compiled with paranoid memory management.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_gprof ()

> Tells wether the game was compiled with suitable informations for gprof.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_instrument ()

> Tells wether the game was compiled with the '-finstrument-fonctions' GCC flag.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_profiler ()

> Tells wether the game was compiled for later use with Google Profiler support.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_gcov ()

> Tells wether the game was compiled with suitable informations for gcov.

> Return value: "yes" or "no", must no be freed.

— Function: char * lw6sys_build_get_enable_valgrind ()

> Tells wether the game was compiled for later use with valgrind.

> Return value: "yes" or "no", must no be freed.

— Function: int lw6sys_build_get_bin_id ()

> Returns the internal bin-id value, which does not mean anything but changes at each build.

> Return value: an integer

— Function: void lw6sys_build_log_all ()

> Dumps in the log file the whole program pedigree, host, modules, that is, what are the values of all the build options. Usefull for bug reports.

> Return value: none.

— Function: u_int32_t lw6sys_checksum (unsigned char * data, int len)

> data: the data to process

> len: the length, in bytes, of the data to process

> Creates a checksum from a byte array. This could be mapped on any standard CRC-32 and/or MD5 algorithm, but licence issues for those are such a headache that for the sake of simplicity, it's wrapped here. In LW6 context, we do not really really fear any attack for these checksums are used internally to track bugs and check, for instance, that two game states are actually the same on two distant computers in a network game. Data encryption and security of network links is another debate. Additionnally, this function returns an integer, easier to handle in standard C than any malloc'ed stuff.

> Return value: the checksum, as an integer.

— Function: u_int32_t lw6sys_checksum_str (char * value)

> value: the string to process

> Creates a checksum from a string. This is a convenience function to save the programmer the hassle of calling strlen before any checksum calculation.

> Return value: the checksum, as an integer.

— Function: u_int32_t lw6sys_checksum_int32 (u_int32_t value)

> value: the integer to process

> Creates a checksum from an integer. This is a convenience function to save the programmer the hassle of passing a pointer to the integer with the size of it each time there's a checksum to do. Additionnally, with this one you can pass an int8 or an int16, and function will work just the same indenpendantly of endianness.

> Return value: the checksum, as an integer.

— Function: u_int32_t lw6sys_checksum_int64 (u_int64_t value)

> value: the integer to process

> Creates a checksum from an integer. This is a convenience function to save the programmer the hassle of passing a pointer to the integer with the size of it each time there's a checksum to do. This function handles 64-bit long long integers..

> Return value: the checksum, as an integer.

— Function: u_int32_t lw6sys_checksum_whd (lw6sys_whd_t * whd)

> whd: a pointer to the wh struct to be processed

> Creates a checksum from the given structure. Convenience function to save the hassle of passing a pointer to and the size of the `lw6sys_wh_t` struct each time, knowing that there are very often checksums calculated on it. Also avoids endianess issues.

> Return value: the checksum, as an integer.

— Function: u_int32_t lw6sys_checksum_xyz (lw6sys_xyz_t * xyz)

> xyz: a pointer to the xy struct to be processed

> Creates a checksum from the given structure. Convenience function to save the hassle of passing a pointer to and the size of the `lw6sys_xy_t` struct each time, knowing that there are very often checksums calculated on it. Also avoids endianess issues.

> Return value: the checksum, as an integer.

— Function: void lw6sys_checksum_update (u_int32_t * checksum, unsigned char * data, int len)

> checksum: a pointer to the previous checksum

> data: the data to process

> len: the length, in bytes, of the data to process

> Creates a checksum from the given data. The difference with `lw6sys_checksum` is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.

> Return value: none.

— Function: void lw6sys_checksum_update_str (u_int32_t * checksum, char * value)

> checksum: a pointer to the previous checksum

> value: the string to process

> Creates a checksum from the given string. The difference with `lw6sys_checksum_str` is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.

> Return value: none.

— Function: void lw6sys_checksum_update_int32 (u_int32_t * checksum, int32_t value)

> checksum: a pointer to the previous checksum

> value: the integer to process

> Creates a checksum from the given integer. The difference with `lw6sys_checksum_int32` is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.

> Return value: none.

— Function: void lw6sys_checksum_update_int64 (u_int32_t * checksum, int64_t value)

> checksum: a pointer to the previous checksum

> value: the integer to process

> Creates a checksum from the given integer. The difference with `lw6sys_checksum_int64` is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.

> Return value: none.

— Function: void lw6sys_checksum_update_whd (u_int32_t * checksum, lw6sys_whd_t * whd)

> checksum: a pointer to the previous checksum

> whd: a pointer to the wh struct to be processed

> Creates a checksum from the given structure. The difference with `lw6sys_checksum_whd` is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.

> Return value: none.

— Function: void lw6sys_checksum_update_xyz (u_int32_t * checksum, lw6sys_xyz_t * xyz)

> checksum: a pointer to the previous checksum

> xyz: a pointer to the xy struct to be processed

> Creates a checksum from the given structure. The difference with `lw6sys_checksum_xyz` is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.

> Return value: none.

— Function: u_int8_t lw6sys_color_float2char (float f)

> f: the value to convert, from 0.0f to 1.0f

> Converts a floating point value between 0.0f and 1.0f to its 8-bit equivalent between 0 and 255. Usefull in color conversion.

> Return value: an integer between 0 and 255.

— Function: float lw6sys_color_char2float (u_int8_t i)

> i: the value to convert, from 0 to 255

> Converts an 8-bit value between 0 and 255 to its floating-point equivalent between 0.0f and 1.0f. Usefull in color conversion.

> Return value: a float between 0.0f and 1.0f.

— Function: lw6sys_color_8_t lw6sys_color_f_to_8 (lw6sys_color_f_t * color_f)

> color_f: the color to convert

> Converts a color from floating point format to the integer "0 to 255" common format. All fields (RGBA) are converted.

> Return value: the color in 8-bit format.

— Function: void lw6sys_color_8_to_f (lw6sys_color_f_t * color_f, lw6sys_color_8_t color_8)

> color_f: the converted color (pointer must point to writable memory)

> color_8: the color to convert

> Converts a color from the integer "0 to 255" common format to floating point format. All fields (RGBA) are converted.

> Return value: none.

— Function: u_int32_t lw6sys_color_f_to_i (lw6sys_color_f_t * color_f)

> color_f: the color to convert

> Converts a color from floating point format to a single integer, where all fields (RGBA) are serialized. This serialization is endianess independant. Could be used directly by low-level libraries such as SDL.

> Return value: the color serialized in an integer.

— Function: u_int32_t lw6sys_color_8_to_i (lw6sys_color_8_t color_8)

> color_8: the color to convert

> Converts a color from common "0 to 255" structured format to a single integer, where all fields (RGBA) are serialized. This serialization is endianess independant. Could be used directly by low-level libraries such as SDL.

> Return value: the color serialized in an integer.

— Function: void lw6sys_color_i_to_f (lw6sys_color_f_t * color_f, u_int32_t color_i)

> color_f: the converted color (point must point to writable memory)

> color_i: the color to convert

> Converts a color from a serialized integer format to a floating point structure.

> Return value: none.

— Function: lw6sys_color_8_t lw6sys_color_i_to_8 (u_int32_t color_i)

> color_i: the color to convert

> Converts a color from a serialized integer format to a "0 to 255" based structure.

> Return value: the converted color (structure).

— Function: lw6sys_color_8_t lw6sys_color_a_to_8 (char * ascii)

> ascii: the color to convert

> Converts a color from a human readable string to a "0 to 255" based structure. The string must be of the form "#RRGGBBAA" or "#RGB", in a general manner any HTML-valid value should work.

> Return value: the converted color (structure).

— Function: void lw6sys_color_a_to_f (lw6sys_color_f_t * color_f, char * ascii)

> color_f: the converted color (pointer must point to writable memory)

> ascii: the color to convert

> Converts a color from a human readable string to a float based structure. The string must be of the form "#RRGGBBAA" or "#RGB", in a general manner any HTML-valid value should work.

> Return value: none.

— Function: char * lw6sys_color_8_to_a (lw6sys_color_8_t color_8)

> color_8: the color to convert

> Converts a color from a "0 - 255" integer based structure to its readable form "#RRGGBBAA". If alpha is 255 (0xFF), that is, if it's opaque, then the "AA" part is ommitted.

> Return value: a newly allocated string.

— Function: void lw6sys_color_rgb_to_hsv (lw6sys_color_hsv_t * color_hsv, lw6sys_color_8_t color_8)

> color_hsv: the target color, in HSV format

> color_8: the source color, in RGB 256 format

> Converts from HSV to RGB. Usefull for color manipulation, since most colors are stored in RGB but HSV is convenient for transformation. Alpha layer is kept as is.

> Return value: none.

— Function: lw6sys_color_8_t lw6sys_color_hsv_to_rgb (lw6sys_color_hsv_t * color_hsv)

> color_hsv: the source color, in HSV format

> Converts from RGB to HSV. Usefull to make colors transformed in HSV format usable again by all display routines, which consume RGB. Alpha layer is kept as is.

> Return value: the RGB color.

— Function: lw6sys_color_8_t lw6sys_color_average (int size, lw6sys_color_8_t * colors)

> size: number of the color array (number of items)

> colors: the colors to compute

> Tries to find out the "average" color from an array of colors. The algorithm is far from perfect, but should output a color which reflects the colors passed in.

> Return value: the (inexact) average color.

— Function: lw6sys_color_8_t lw6sys_color_ponderate (lw6sys_color_8_t color1, lw6sys_color_8_t color2, float coeff)

> color1: first color

> color2: second color

> coeff: the ponderation coefficient

> Tries to find a color between the two colors passed as an argument. The coefficient can be used, to set the relative weight of each color. Using 0 will return color1, 1 will return color2 and 0.5 will make an average between the two colors. Any value between 0 and 1 can be used.

> Return value: the (inexact) ponderated color.

— Function: float lw6sys_color_distance (lw6sys_color_8_t color1, lw6sys_color_8_t color2)

> color1: first color

> color2: second color

> Calculates the distance between two colors. The unit is arbitrary, a big value means "colors are different", 0 means they are the same. A distance of 1 corresponds to colors which have barely anything in common, but the result can still be greater than 1. Alpha layer is not taken in account.

> Return value: the distance.

— Function: int lw6sys_color_is_same (lw6sys_color_8_t color1, lw6sys_color_8_t color2)

> color1: the first color to compare

> color2: the second color to compare

> Compares two colors.

> Return value: 1 if they are the same, 0 if not.

— Function: void lw6sys_color_8_solid (lw6sys_color_8_t * color)

> color: the color to modify

> Make a color "solid" that is make it not transparent at all.

> Return value: none.

— Function: void lw6sys_color_f_solid (lw6sys_color_f_t * color)

> color: the color to modify

> Make a color "solid" that is make it not transparent at all.

> Return value: none.

— Function: int lw6sys_atoi (char * str)

> str: string to convert

> Just a plain wrapper on `atoi`, it's here for API consistency.

> Return value: an integer.

— Function: int lw6sys_atob (char * str)

> str: string to convert

> Transform a string into a boolean value. Accepts "0"/"1" in input, but also y/n, yes/no, true/false, on/off.

> Return value: an integer, 0 or 1.

— Function: float lw6sys_atof (char * str)

> str: string to convert

> A wrapper on `atof`, makes sure the locale used is C (default) and won't change the decimal separator whatsoever. Usefull for serialization for instance.

> Return value: a float.

— Function: char * lw6sys_itoa (int value)

> value: the integer to convert

> Converts an integer to a string, the advantage of this function is it allocates memory, and does the dirty job.

> Return value: a newly allocated pointer, must be freed, may be NULL.

— Function: char * lw6sys_btoa (int value)

> value: the boolean to convert

> Converts a boolean to a string, the advantage of this function is it allocates memory, and does the dirty job.

> Return value: a newly allocated pointer, must be freed, may be NULL.

— Function: char * lw6sys_ftoa (float value)

> value: the float to convert

> Converts a float to a string, the advantage of this function is it allocates memory, and does the dirty job.

> Return value: a newly allocated pointer, must be freed, may be NULL.

— Function: int lw6sys_debug_get ()

> Gets the debug mode.

— Function: void lw6sys_debug_set (int mode)

> mode: the debug mode, 1 if set, 0 if not.

> Sets the debug mode.

— Function: void lw6sys_dump_clear (char * user_dir)

> user_dir: the user directory, where user can write data.

> Clears the dump file. That is, resets it to a "0 byte" file.

> Return value: none.

— Function: int lw6sys_dump (char * user_dir, char * content)

> user_dir: the user directory, where user can write data.

> content: the content to be written in the dump file.

> Writes the dump file onto the disk. The dump is used for special error messages which do not really fit in the standard log, and require a special treatment. In pratice, it's used to log fatal script (Guile) errors.

> Return value: 1 if success, 0 if failure.

— Function: char lw6sys_env_separator_char ()

> Gets the ENV separator, that is, for instance, the character used to separate paths in environment variables. Typically, this would be ":" on GNU and ";" on Microsft platforms.

> Return value: the ascii character code.

— Function: char * lw6sys_env_separator_str ()

> Gets the ENV separator, that is, for instance, the character used to separate paths in environment variables. Typically, this would be ":" on GNU and ";" on Microsft platforms.

> Return value: a pointer to a single 0-terminated character string which contains the character. Must not be freed.

— Function: char * lw6sys_env_concat (char * value1, char * value2)

> value1: the left part to be concatenated

> value2: the right part to be concatenated

> Concatenates two values and puts the ENV separator, as returned by `lw6sys_env_separator_char` between them.

> Return value: the concatenated string, must be freed.

— Function: int lw6sys_env_exists_prefixed (char * keyword)

> keyword: the keyword to be searched in the environment variables.

> Searches environment variables for the given keyword. The keyword will be fixed so that all dashes "-" characters are replaced by underscores "_" characters. Characters will be changed to uppercase. Any non alphanumeric character will be replaced by "_". Finally, an "LW6_" prefix will be added. That is to say, calling this function with "my-param" will search for the "LW6_MY_PARAM" environment variable.

> Return value: 1 if the environment variable exists, 0 if not.

— Function: char * lw6sys_getenv (char * key)

> key: the environment variable to get.

> Searches environment variables for the given value. This is a wrapper over the standard C getenv, the difference is it will return a dynamically allocated pointer, and on some platforms will query specific OS functions.

> Return value: the value for the given keyword. May be NULL. Must be freed.

— Function: char * lw6sys_getenv_prefixed (char * keyword)

> keyword: the keyword to be searched in the environment variables.

> Searches environment variables for the given value. The keyword will be fixed so that all dashes "-" characters are replaced by underscores "_" characters. Characters will be changed to uppercase. Any non alphanumeric character will be replaced by "_". Finally, an "LW6_" prefix will be added. That is to say, calling this function with "my-param" will search for the "LW6_MY_PARAM" environment variable.

> Return value: the value for the given keyword. May be NULL. Must be freed.

— Function: int lw6sys_setenv (char * keyword, char * value)

> keyword: the environment variable to set

> value: the value of the environment variable to set

> Sets the environment variable to a given value. If value is NULL, variable is unset. Note that unlike lw6sys_getenv_prefixed, this function does not transform the keyword into "LW6_..." before setting the value, so it's your responsability to call "lw6sys_keyword_as_env" if needed.

> Return value: 1 if success, 0 if failed

— Function: int lw6sys_setenv_prefixed (char * keyword, char * value)

> keyword: the keyword to be searched in the environment variables.

> value: the value of the environment variable to set

> Sets the environment variable to the given value. The keyword will be fixed so that all dashes "-" characters are replaced by underscores "_" characters. Characters will be changed to uppercase. Any non alphanumeric character will be replaced by "_". Finally, an "LW6_" prefix will be added. That is to say, calling this function with "my-param" will set the "LW6_MY_PARAM" environment variable.

> Return value: 1 if success, 0 if failure

— Function: lw6sys_list_t * lw6sys_env_split (char * value)

> value: the value, a list of item separated by... the separator

> Splits the environment value into a list of strings containing each element. All strings are dynamically allocated, but they will be freed automatically when the list is freed.

> Return value: a list of strings.

— Function: char * lw6sys_get_home ()

> Gets the home directory of the user. Used internally to calculate the `user`-dir value. Note that Liquid War 6, by default, never stores files under '$HOME', instead it put things in '$HOME/.liquidwar6', that is 'user-dir'. If the environment variable 'HOME' is not set, will return '.'.

> Return value: a newly allocated pointer, must be freed.

— Function: char * lw6sys_get_username ()

> Gets the name of the current user. Difference with the standard function `getlogin` is that this function will returned a dynamically allocated pointer, and provide a default value if it's undefined. Also, if will look at the content of the 'LOGNAME' environment variable if needed, and will even provide a default value.

> Return value: a newly allocated pointer, must be freed.

— Function: char * lw6sys_get_hostname ()

> Gets the name of the current host. The name of the computer. Might not work perfectly, this function is just used to provide default values for player names and such things.

> Return value: a newly allocated pointer, must be freed.

— Function: char * lw6sys_escape_http_uri (char * src)

> src: the string to escape

> Transforms a string so that it does not contain any non-valid URL chars, it will mostly convert chars over 128 into their XY form where XY is the hexadecimal code. Note that this function is non really standard compliant for it won't encode '%' but keep it the same. This is to allow using it several times on the same string and avoid double-triple encoding of '%'. In practice it's not recommended to have public_url for nodes with '%' in them, and the program will never generate such url when guessing urls.

> Return value: newly allocated string.

— Function: char * lw6sys_escape_html_attribute (char * src)

> src: the string to escape

> Transforms a string so that it can fit in a html field, this is typically for alt="" or title="" fields so it will convert " into `quot`;.

> Return value: newly allocated string.

— Function: char * lw6sys_escape_sql_value (char * src)

> src: the string to escape

> Transforms a string so that it can fit as an SQL parameter, it will get rid URL chars, it will mostly convert chars over 128 into their XY form where XY is the hexadecimal code.

> Return value: newly allocated string.

— Function: char * lw6sys_exec_find_myself (int argc, char * [] argv)

> argc: number of args as passed to main

> argv: array of args as passed to main

> Finds the path of the program currently run, this is typically to pass it to `lw6sys_exec_again` and run it again.

> Return value: the path (newly allocated string).

— Function: int lw6sys_is_executed_again (int argc, char * [] argv)

> argc: number of args as passed to main

> argv: array of args as passed to main

> Tells wether the program is already executed by itself by `lw6sys_exec_again` function. Based on environment and command switches.

> Return value: 1 if executed again, 0 if not.

— Function: int lw6sys_exec_again (int argc, char * [] argv)

> argc: number of args as passed to main

> argv: array of args as passed to main

> Runs the program from itsef, that is fires a new program (the same running) and ends up the current one. This is used to fix some environment variable issues. If LW6_EXECUTED_AGAIN (environment variable) is set, will not run the program so this is not really like `exec` as in the C standard library, this function will actually return and be successfull even if no other process was started. It's just designed to bootstrap/launch the process once.

> Return value: 1 on success, 0 on failure.

— Function: int lw6sys_clear_file (char * filename)

> filename: absolute or relative filename

> Clears a file, that is, make it a 0 byte file, empty, ready to be filled if needed. If this function is called successfully, program can reasonnably assume file will be writable during its execution.

> Return value: 1 if success, 0 if failure.

— Function: char * lw6sys_read_file_content (char * filename)

> filename: absolute or relative filename

> Reads the content of a file, and returns it as a string. Note that content might or might not be ascii or binary, the function will however put a tailing 0 character at the end so that low-level standard C functions do not segfault when used with the returned value.

> Return value: a newly allocated pointer, must be freed.

— Function: void * lw6sys_read_file_content_bin (int * filesize, char * filename)

> filesize: will contain the file size, in bytes

> filename: absolute or relative filename

> Reads the content of a file, and returns it as a binary buffer. Even if not ascii or binary, the function will however put a tailing 0 character at the end so that low-level standard C functions do not segfault when used with the returned value. This 0 character is not included in `filesize` so if there are 4 bytes in the file the 5 bytes will be allocated, this is just for string functions not to explode if called by accident. The `filesize` can be NULL, in that case function is just like the `lw6sys_read_file_content` function.

> Return value: a newly allocated pointer, must be freed.

— Function: int lw6sys_write_file_content (char * filename, char * content)

> filename: absolute or relative filename

> content: the content to be written.

> Writes the content into the file. Content is assumed to be a string, function will segfault if it's not correctly 0 terminated as in C string convention. So this function will not allow you to write down arbitrary binary data, however LW6 uses mostly text files to store information, and opaque binary data usage is not recommended.

— Function: lw6sys_hash_t * lw6sys_hash_new (lw6sys_free_func_t free_func, int size)

> free_func: optional callback used to free memory when stored date is a pointer. Can be NULL when one stores non dynamically allocated data, such as an integer or a static array.

> size: the estimated size of the hash table. Note that this is an estimation only. You could theorically fit 1000000 objects in a 3-sized hash. Problem -> this is inefficient, you'd better use an assoc or a bigger hash. If you store 3 elements in a 1000000-sized hash, you'll waste memory. It might be wise to use a prime number as the estimated size. 421 is prime ;)

> Creates an empty hash. There's a difference between NULL and an empty hash.

> Return value: a pointer to the newly allocated hash table. Must be freed with `lw6sys_hash_free`.

— Function: void lw6sys_hash_free (lw6sys_hash_t * hash)

> hash: the hash to be freed.

> The function will cascade delete all elements, using (if not NULL...) the callback passed when first creating the hash.

> Return value: void

— Function: int lw6sys_hash_has_key (lw6sys_hash_t * hash, char * key)

> hash: the hash to test

> key: the key to search

> Not a very fast function, since on a "big" hash, strcmp will be called internally until the key is found.

> Return value: non-zero if there's an entry with the corresponding key.

— Function: void * lw6sys_hash_get (lw6sys_hash_t * hash, char * key)

> hash: the hash to query

> key: the key of which we want the value

> Return value: a void pointer to the data contained in the hash. Note that the pointer on the actual data is returned, that is, if it's static data, you must not try to free it... As long as memory management is concerned, destroying the hash will actually free the data if needed.

— Function: void lw6sys_hash_set (lw6sys_hash_t * hash, char * key, void * value)

> hash: the hash to modify

> key: the key we want to updated

> value: the new value

> Sets a value in a hash table. The key pointer need not be persistent, it can be freed after affectation. In fact a new string will be created internally. This is not true for the value, it's hard to find way to copy "any object". So if you want a hash table of strings, key can disappear after calling this function, but not value. The function passed as free_func when creating the hash will be used to free stuff whenever needed (unset or free).

> Return value: void

— Function: void lw6sys_hash_unset (lw6sys_hash_t * hash, char * key)

> hash: the hash concerned

> key: the key to unset

> Clears an entry in a hash table. The callback passed when creating the hash will be called if needed, to free the data automatically.

> Return value: void

— Function: lw6sys_list_t * lw6sys_hash_keys (lw6sys_hash_t * hash)

> hash: the hash to work on

> Returns a list containing all the keys of the hash. The list must be free with lw6sys_list_free by the caller. This list copies all the keys of the hash, so it is safe to use it once the hash is deleted. However the keys will of course be of little interest in this case. But the program won't segfault.

> Return value: the list of keys.

— Function: void lw6sys_hash_map (lw6sys_hash_t * hash, lw6sys_assoc_callback_func_t func, void * func_data)

> hash: the hash to work on

> func: a callback to call on each entry

> func_data: a pointer on some data which will be passed to the callback

> Executes a function on all hash items. The func_data parameter allows you to pass extra values to the function, such as a file handler or any variable which can not be inferred from list item values, and you of course do not want to make global...

> Return value: void

— Function: void lw6sys_hash_sort_and_map (lw6sys_hash_t * hash, lw6sys_assoc_callback_func_t func, void * func_data)

> hash: the hash to work on

> func: a callback to call on each entry, may be NULL

> func_data: a pointer on some data which will be passed to the callback

> Executes a function on all hash items, like `lw6sys_hash_sort_and_map` but befor doing so, sorts all entries in alphabetical order.

> Return value: void

— Function: lw6sys_hash_t * lw6sys_hash_dup (lw6sys_hash_t * hash, lw6sys_dup_func_t dup_func)

> hash: the hash to duplicate, can be NULL

> dup_func: the function which will be called to duplicate data

> Duplicates an hash. All keys will be copied so that if the first hash is deleted, the duplicated one is fine. Additionnaly, dup_func will be called with all data fields. If dup_func is NULL, then data values will simply be copied. This is likely to be usefull when data is not dynamically allocated.

> Returned value: a newly allocated hash.

— Function: lw6sys_hexa_serializer_t * lw6sys_hexa_serializer_new (char * hexa_string)

> hexa_string: an initialization string, can be NULL.

> Creates an hexa serializer object. It can be initialized or not, if an initialization string is provided it must of course be valid hexadecimal ascii code, and all serialized content will simply be appended to it.

> Return value: a newly allocated object.

— Function: void lw6sys_hexa_serializer_free (lw6sys_hexa_serializer_t * hexa_serializer)

> hexa_serializer: an hexa serializer object

> Frees an hexa serializer object.

> Return value: none.

— Function: void lw6sys_hexa_serializer_rewind (lw6sys_hexa_serializer_t * hexa_serializer)

> hexa_serializer: an hexa serializer object

> Rewinds the serializer pointer, that is, make it point to start. Usefull before calling pop functions, when one wants to be sure to get the first object.

> Return value: none.

— Function: int lw6sys_hexa_serializer_eof (lw6sys_hexa_serializer_t * hexa_serializer)

> hexa_serializer: an hexa serializer object

> Tests wether we're at EOF. Usefull when one wants to know if there's still some data or if all objects have been correctly popped.

> Return value: 1 if at end of file, 0 if not.

— Function: char * lw6sys_hexa_serializer_as_string (lw6sys_hexa_serializer_t * hexa_serializer)

> hexa_serializer: an hexa serializer object

> Exports the current content of the serializer as a string. String can then safely be sent on the network, for instance. String is copied from internal value, so it's safe to use it after serializer has been freed or modified.

> Return value: a newly allocated string, must be freed.

— Function: int lw6sys_hexa_serializer_push_int64 (lw6sys_hexa_serializer_t * hexa_serializer, int64_t value)

> hexa_serializer: an hexa serializer object

> value: value to push

> Pushes a 64 bit integer in the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_push_int32 (lw6sys_hexa_serializer_t * hexa_serializer, int32_t value)

> hexa_serializer: an hexa serializer object

> value: value to push

> Pushes a 32 bit integer in the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_push_int16 (lw6sys_hexa_serializer_t * hexa_serializer, int16_t value)

> hexa_serializer: an hexa serializer object

> value: value to push

> Pushes a 16 bit integer in the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_push_int8 (lw6sys_hexa_serializer_t * hexa_serializer, int8_t value)

> hexa_serializer: an hexa serializer object

> value: value to push

> Pushes an 8 bit integer in the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_push_float (lw6sys_hexa_serializer_t * hexa_serializer, float value)

> hexa_serializer: an hexa serializer object

> value: value to push

> Pushes a floating point value in the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_push_str (lw6sys_hexa_serializer_t * hexa_serializer, char * value)

> hexa_serializer: an hexa serializer object

> value: value to push

> Pushes a string in the serializer object. Note that the string is not directly copied in the serializer, instead all its characters are converted to their ASCII equivalent, then appended.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_push_xyz (lw6sys_hexa_serializer_t * hexa_serializer, lw6sys_xyz_t value)

> hexa_serializer: an hexa serializer object

> value: value to push

> Pushes a lw6sys_xyz_t structure in the serializer object. Calling this avoids calling push for 2 integers separately.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_push_whd (lw6sys_hexa_serializer_t * hexa_serializer, lw6sys_whd_t value)

> hexa_serializer: an hexa serializer object

> value: value to push

> Pushes a lw6sys_whd_t structure in the serializer object. Calling this avoids calling push for 2 integers separately.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_push_color (lw6sys_hexa_serializer_t * hexa_serializer, lw6sys_color_8_t value)

> hexa_serializer: an hexa serializer object

> value: value to push

> Pushes a color structure in the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_pop_int64 (lw6sys_hexa_serializer_t * hexa_serializer, int64_t * value)

> hexa_serializer: an hexa serializer object

> value: value to pop (returned value)

> Pops a 64 bit integer from the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_pop_int32 (lw6sys_hexa_serializer_t * hexa_serializer, int32_t * value)

> hexa_serializer: an hexa serializer object

> value: value to pop (returned value)

> Pops a 32 bit integer from the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_pop_int16 (lw6sys_hexa_serializer_t * hexa_serializer, int16_t * value)

> hexa_serializer: an hexa serializer object

> value: value to pop (returned value)

> Pops a 16 bit integer from the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_pop_int8 (lw6sys_hexa_serializer_t * hexa_serializer, int8_t * value)

> hexa_serializer: an hexa serializer object

> value: value to pop (returned value)

> Pops an 8 bit integer from the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_pop_float (lw6sys_hexa_serializer_t * hexa_serializer, float * value)

> hexa_serializer: an hexa serializer object

> value: value to pop (returned value)

> Pops a floating point value from the serializer object.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_pop_str (lw6sys_hexa_serializer_t * hexa_serializer, char ** value)

> hexa_serializer: an hexa serializer object

> value: value to pop (returned value)

> Pops a string from the serializer object. The returned value is a newly allocated pointer, which must be freed, you don't need to provide a buffer, just a valid pointer on a NULL pointer.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_pop_xyz (lw6sys_hexa_serializer_t * hexa_serializer, lw6sys_xyz_t * value)

> hexa_serializer: an hexa serializer object

> value: value to pop (returned value)

> Pops a lw6sys_xyz_t structure from the serializer object. Avoids calling two integer pops.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_pop_whd (lw6sys_hexa_serializer_t * hexa_serializer, lw6sys_whd_t * value)

> hexa_serializer: an hexa serializer object

> value: value to pop (returned value)

> Pops a lw6sys_whd_t structure from the serializer object. Avoids calling two integer pops.

> Return value: 1 if success, 0 if failure

— Function: int lw6sys_hexa_serializer_pop_color (lw6sys_hexa_serializer_t * hexa_serializer, lw6sys_color_8_t * value)

> hexa_serializer: an hexa serializer object

> value: value to pop (returned value)

> Pops a color from the serializer object.

> Return value: 1 if success, 0 if failure

— Function: void * lw6sys_hexa_str_to_ptr (char * str)

> str: the string containing an hexa representation of pointer

> Transforms a string into a pointer, this is typically used to store pointers in temporary agnostic storage such as a database. Beware not to use that to exchange data with other computers and/or use it for persistent data. This is a high-risk function as it lets you do real dirty stuff but it really does save time compared to using a key returned by the database engine and then search this key in a user-space hash table. Direct pointer access is definitely faster.

> Return value: the pointer, or NULL is str is invalid.

— Function: char * lw6sys_hexa_ptr_to_str (void * ptr)

> ptr: pointer to convert into string representation

> Transforms a pointer into a string, this is typically used to store pointers in temporary agnostic storage such as a database. Beware not to use that to exchange data with other computers and/or use it for persistent data. This is a high-risk function as it lets you do real dirty stuff but it really does save time compared to using a key returned by the database engine and then search this key in a user-space hash table. Direct pointer access is definitely faster.

> Return value: the string, can be NULL on errror, must be freed.

— Function: void lw6sys_history_init ()

> Initializes the history system. Not initializing won't cause any segfault, but data will be inconsistent.

> Return value: none.

— Function: void lw6sys_history_register (char * msg)

> msg: the message to register.

> Registers a message in the history log, that is, adds it.

> Return value: none.

— Function: char_ptr_t * lw6sys_history_get (int64_t timeout)

> timeout: the message age limit.

> Get all the messages that are younger than timeout (in seconds).

> Return value: a pointer on string pointers. May be NULL. Last pointer is NULL too, that's how you know the array is over.

— Function: void lw6sys_history_free (char ** history)

> history: the data to free

> Frees a pointer returned by `lw6sys_history_get`.

> Return value: none.

— Function: char * lw6sys_locale_to_utf8 (char * string)

> string: the string to convert

> Used to force strings into UTF-8 mode, this is basically to match the TTF font settings used when displaying stuff on OpenGL. Indeed, in this case, the standard _ gettext function won't work, we need to force UTF-8 mode. If the locale is UTF-8, then function does nothing, but at least it's transparent usage won't hurt.

> Returned value: a newly allocated string, always in UTF-8 no matter what the locale is.

— Function: u_int16_t lw6sys_generate_id_16 ()

> Long 16-bit ID generator, calls the random function internally. As usual, those are not perfect random numbers, however the function implementation emphasizes more on 'real randomness' rather than relying on performance. Generating twice the same number should be fairly rare.

— Function: u_int32_t lw6sys_generate_id_32 ()

> Long 32-bit ID generator, calls the random function internally. As usual, those are not perfect random numbers, however the function implementation emphasizes more on 'real randomness' rather than relying on performance. Generating twice the same number should be fairly rare.

— Function: u_int64_t lw6sys_generate_id_64 ()

> Long 64-bit ID generator, calls the random function internally. As usual, those are not perfect random numbers, however the function implementation emphasizes more on 'real randomness' rather than relying on performance. Generating twice the same number should be fairly rare.

— Function: int lw6sys_check_id_16 (u_int16_t id_16)

> id_16: the id to check

> Checks wether the given id is a valid 16-bit id.

> Return value: 1 if OK, 0 if not a valid id.

— Function: int lw6sys_check_id_32 (u_int32_t id_32)

> id_32: the id to check

> Checks wether the given id is a valid 32-bit id.

> Return value: 1 if OK, 0 if not a valid id.

— Function: int lw6sys_check_id_64 (u_int64_t id_64)

> id_64: the id to check

> Checks wether the given id is a valid 64-bit id.

> Return value: 1 if OK, 0 if not a valid id.

— Function: int lw6sys_check_id (u_int64_t id)

> id: the id to check

> Checks wether the given id is a valid id (16, 32 or 64-bit).

> Return value: 1 if OK, 0 if not a valid id.

— Function: char * lw6sys_id_ltoa (u_int64_t id)

> id: the id to convert

> Transform an id into its string representation. Error checking is done, if the id is invalid, returned value is NULL. All ids (16, 32 and 64-bit) are handled.

> Return value: a newly allocated string, might be NULL.

— Function: u_int64_t lw6sys_id_atol (char * id)

> id: the id to convert

> Transform an id into a long integer. Error checking is done, if the id is invalid, returned value is 0. All ids (16, 32 and 64-bit) are handled.

> Return value: the id as a long integer, 0 if incorrect source id.

— Function: char * lw6sys_keyword_as_key (char * keyword)

> keyword: the keyword to transform

> Transforms a keyword into a "key", that is, removes all heading dashes, switches to lowercase, and other stuff. This is used internally to match options and config file parameters, for instance.

> Return value: a newly allocated pointer, must be freed.

— Function: char * lw6sys_keyword_as_arg (char * keyword)

> keyword: the keyword to transform

> Transforms a keyword into a command-line parameter to be matched. Does the same as `lw6sys_keyword_as_key`, and adds a "–" prefix.

> Return value: a newly allocated pointer, must be freed.

— Function: char * lw6sys_keyword_as_env (char * keyword)

> keyword: the keyword to transform

> Transforms a keyword into the corresponding environment variable name. It will uppercase the name, replace "-" by "_", and add a "LW6_" prefix. "my-param" will become "LW6_MY_PARAM".

> Return value: a newly allocated pointer, must be freed.

— Function: char * lw6sys_keyword_as_xml (char * keyword)

> keyword: the keyword to transform

> Transforms a keyword into the corresponding config file entry. In practice, just the same as `lw6sys_keyword_as_key`.

> Return value: a newly allocated pointer, must be freed.

— Function: lw6sys_list_t * lw6sys_list_new (lw6sys_free_func_t free_func)

> free_func: a callback which will be called on data when freeing the list

> Creates an empty list. There's a difference between NULL and an empty list. The empty list would (in Scheme) be '() whereas NULL corresponds to undefined "is not a list and will generate errors if you ever call list functions on it".

> Return value: a pointer to the created object, may be NULL.

— Function: void lw6sys_list_free (lw6sys_list_t * list)

> list: the list to delete.

> Delete a list, this will cascade delete all the following items in the list.

> Return value: none.

— Function: lw6sys_list_t * lw6sys_list_next (lw6sys_list_t * list)

> list: the current position in the list

> It's safer to call this rather than dig right into the internals of the list.

> Return value: a new position in the list, may be NULL.

— Function: int lw6sys_list_is_empty (lw6sys_list_t * list)

> list: the list we want informations about

> Checks wether the list is empty or not. Note that being empty and being NULL is not the same. An empty list is a valid pointer on a list where there's no item, a NULL pointer is not a list at all. Do *NOT* call this function on NULL.

> Return value: 1 if empty, 0 if there is at list one item.

— Function: int lw6sys_list_length (lw6sys_list_t * list)

> list: the list we want informations about

> Calculates the length of the list. This is a performance killer for lists are inadapted to this. But it can still be usefull.

> Return value: the number of elements, 0 is none (empty list).

— Function: void lw6sys_list_map (lw6sys_list_t * list, lw6sys_list_callback_func_t func, void * func_data)

> list: the list where elements will be taken

> func: the function which will be executed

> func_data: additionnal data to be passed to `func`

> Executes a function on all list items. The `func_data` parameter allows you to pass extra values to the function, such as a file handler or any variable which can not be inferred from list item values, and you of course do not want to make global... Not as convenient as a real "for each" construct as can be found in any modern langage, but does the job. No return value, if you really want one, pass a structure in `func_data` and modify something in it on success, failure, whatever.

> Return value: none.

— Function: void lw6sys_list_filter (lw6sys_list_t ** list, lw6sys_list_filter_func_t func, void * func_data)

> list: the list where elements will be taken

> func: the function which will be executed

> func_data: additionnal data to be passed to `func`

> Executes a function on all list items and keeps only those for which the function returned non zero (true). The `func_data` parameter allows you to pass extra values to the function, such as a file handler or any variable which can not be inferred from list item values, and you of course do not want to make global...

> Return value: none.

— Function: void lw6sys_list_push_front (lw6sys_list_t ** list, void * data)

> list: a pointer to the list (pointer on pointer, read/write value)

> data: the data to be pushed

> Pushes data on the list. The `free_func` function is copied from the previous element. The pointer on the list is changed "in place" (in/out). Note that if there's a `malloc` problem it might end-up being NULL... This should be rare but it *can* happen. You cannot push something else than a pointer, pushing an int is a very bad idea. Push a pointer on the integer, and ensure it's always there, or `malloc` it and pass `lw6sys_free_callback` when creating the list. If you think you can cast an integer into a pointer, think 64-bit machines...

> Return value: none.

— Function: void * lw6sys_list_pop_front (lw6sys_list_t ** list)

> list: a pointer to the list (pointer on pointer, read/write value)

> Pops data from the list, the returned value is what was passed to list_push. The pointer on the list is changed "in place" (in/out). When data is popped, that needs some freeing (i.e. free_func was not NULL when creating the list) then it's the responsibility of the caller to free it when popping it. One popped it's not freed, but it's out of the list scope. Of course the lw6sys_list_t is freed, but not the data. If you happen to store non-NULL data in your list, you can call this function without bothering calling `lw6sys_list_is_empty` and assume that when you get NULL, there's no data left. At this stage, the list won't exist anymore BTW, you won't even need to free it. The idea is: popping a list which has no elements left (empty list) destroys the list and returns NULL.

> Return value: a pointer on the popped data, whatever you pushed.

— Function: void lw6sys_list_push_back (lw6sys_list_t ** list, void * data)

> list: a pointer to the list (pointer on pointer, read/write value)

> data: the data to be pushed

> Pushes data on the list. The `free_func` function is copied from the previous element. The pointer on the list is changed "in place" (in/out). Note that if there's a `malloc` problem it might end-up being NULL... This should be rare but it *can* happen. You cannot push something else than a pointer, pushing an int is a very bad idea. Push a pointer on the integer, and ensure it's always there, or `malloc` it and pass `lw6sys_free_callback` when creating the list. If you think you can cast an integer into a pointer, think 64-bit machines...

> Return value: none.

— Function: void * lw6sys_list_pop_back (lw6sys_list_t ** list)

> list: a pointer to the list (pointer on pointer, read/write value)

> Pops data from the list, the returned value is what was passed to list_push. The pointer on the list is changed "in place" (in/out). When data is popped, that needs some freeing (i.e. free_func was not NULL when creating the list) then it's the responsibility of the caller to free it when popping it. One popped it's not freed, but it's out of the list scope. Of course the lw6sys_list_t is freed, but not the data. If you happen to store non-NULL data in your list, you can call this function without bothering calling `lw6sys_list_is_empty` and assume that when you get NULL, there's no data left. At this stage, the list won't exist anymore BTW, you won't even need to free it. The idea is: popping a list which has no elements left (empty list) destroys the list and returns NULL.

> Return value: a pointer on the popped data, whatever you pushed.

— Function: lw6sys_list_t * lw6sys_list_dup (lw6sys_list_t * list, lw6sys_dup_func_t dup_func)

> list: the list to duplicate, can be NULL

> dup_func: the function which will be called to duplicate data

> Duplicates a list. All data will be copied so that if the first list is deleted, the duplicated one is fine. Addtionnally, dup_func will be called to filter all data, and possibly allocated new pointers if needed, for instance. If dup_func is NULL, then data values will simply be copied. This is likely to be usefull when data is not dynamically allocated.

> Returned value: a newly allocated list.

— Function: void lw6sys_log_set_file (char * filename)

> filename: the name of the log file.

> Sets up the log file. Until you call this function, messages all logged to the default log file, as returned by the `lw6sys_get_default_log_file` function.

> Return value: void

— Function: void lw6sys_log_clear (char * filename)

> filename: the name of the log file.

> Clears the log file, this function would typically be called at the beginning of the program. If filename is NULL, then the default log file is cleared.

> Return value: void

— Function: void lw6sys_log (int level_id, char * file, int line, char * fmt, ...)

> level_id: the log level to use. Possible values are, by order, LW6SYS_LOG_ERROR_ID (0), LW6SYS_LOG_WARNING_ID (1), LW6SYS_LOG_NOTICE_ID (2), LW6SYS_LOG_INFO_ID (3), LW6SYS_LOG_DEBUG_ID (4) and LW6SYS_LOG_TMP_ID (5).

> file: the name of the source file where the function is called, one can use __FILE__

> line: the line in the source file where the function is called, one can use __LINE__

> fmt: a printf-like format string ...: printf-like arguments, corresponding to `fmt`.

> This function is usually called with the first three arguments packed into a single macro. For instance the `LW6SYS_LOG_WARNING` macro expands and fills the first 3 args, so there's no need to type __FILE__ and __LINE__ again and again. Note that this function will reset errno. The idea is to call it whenever there's something to do with errno (if you deal with errno, it's a good habit to log it) then errno is cleared so that it won't interfere with next log messages.

— Function: void lw6sys_log_critical (char * fmt, ...)

> fmt: a printf-like format string ...: printf-like arguments, corresponding to `fmt`.

> This function is a special log function which will dump informations on the console only, without opening any log file whatsoever. The idea is that it's a "never fail" function. Additionnally, it will never return but quit the program. This can be used as an ultimate emergency function, use it when the program won't run for sure, and displaying an immediate error message is the only issue.

— Function: int lw6sys_log_get_level ()
— Function: void lw6sys_log_set_level (int level)

> level: the log level, integer between 0 & 4. 4 is very verbose (debug), 0 displays errors only.

— Function: void lw6sys_math_poly_wy1y2s1 (float * y, float * s, float x, float w, float y1, float y2, float s1)

> y: the return value (position, may be NULL)

> s: the return value (speed, may be NULL)

> x: the x parameter, the value to iterate on

> w: the width, that is, the x value after which output is constant

> y1: the initial value, when v is s1 and x=0

> y2: the target value, when v=0 and x>=w

> s1: the initial speed, that is dy/dx at x=0

> A function which can be used to implement smooth moving. It will extrapolate, for values of x>=0, an y position with a continuous derivate (dy/dx is continuous, function is 2nd order polynom) and which ends up at x=w with a constant value, that is dy/dx=v=0. Typically an item set with an initial speed of v with this function

— Function: float lw6sys_math_angle_360 (int x, int y)

> x: x coordinate

> y: y coordinate

> This is a wrapper over the standard `atan` function which will handle internally the special x == 0 case and the various positive/negative values of `x` and `y`.

> Return value: the angle, in degrees

— Function: float lw6sys_math_heartbeat (int64_t x, int period, float y1, float y2)

> x: the parameter (typically a timestamp)

> period: the period (typically something like 1000 milliseconds)

> y1: the low value (heart at rest)

> y2: the high value (when bumping)

> A heartbeat function, typically usefull to power up eye-candy, but it could do something else.

— Function: int lw6sys_math_blink (int64_t x, int period)

> x: the parameter (typically a timestamp)

> period: the period (typically something like 1000 milliseconds)

> This function will alternatively return 1 or 0, usefull to handle blinking for instance.

> Return value: 0 or 1

— Function: void * lw6sys_malloc (int size, char * file, int line)

> size: number of bytes to allocate.

> file: name of the file calling the function, use `__FILE__`

> line: line in the file calling the function, use `__LINE__`

> This is a wrapper over the standard `malloc` function. Additionnally it will keep track of the call with an internal program-wide counter, thus enabling memory leak checks. You should not use this function directly but use the macro `LW6SYS_MALLOC` which has the same syntax, without the last two parameters, which are automatically provided by macro expansion.

> Return value: the newly allocated pointer. Data is not initialized.

— Function: void * lw6sys_calloc (int size, char * file, int line)

> size: number of bytes to allocate.

> file: name of the file calling the function, use `__FILE__`

> line: line in the file calling the function, use `__LINE__`

> This is a wrapper over the standard `calloc` function. Additionnally it will keep track of the call with an internal program-wide counter, thus enabling memory leak checks. You should not use this function directly but use the macro `LW6SYS_CALLOC` which has the same syntax, without the last two parameters, which are automatically provided by macro expansion.

> Return value: the newly allocated pointer. Data is filled with zeros.

— Function: void * lw6sys_realloc (void * ptr, int size, char * file, int line)

> ptr: the pointer to reallocate.

> size: number of bytes to allocate.

> file: name of the file calling the function, use `__FILE__`

> line: line in the file calling the function, use `__LINE__`

> This is a wrapper over the standard `realloc` function. You should not use this function directly but use the macro `LW6SYS_REALLOC` which has the same syntax, without the last two parameters, which are automatically provided by macro expansion.

> Return value: the newly allocated pointer.

— Function: void lw6sys_free (void * ptr, char * file, int line)

> ptr: the pointer to free.

> file: name of the file calling the function, use `__FILE__`

> line: line in the file calling the function, use `__LINE__`

> This is a wrapper over the standard `free` function. Additionnally it will keep track of the call with an internal program-wide counter, thus enabling memory leak checks. You should not use this function directly but use the macro `LW6SYS_FREE` which has the same syntax, without the last two parameters, which are automatically provided by macro expansion.

> Return value: none.

— Function: void lw6sys_free_callback (void * ptr)

> ptr: the pointer to free.

> This is a callback to be used when the `lw6sys_free` does not fit. A good example is a list, which, to free its elements, requires you to provide a callback that only takes 1 arg, the pointer to free. Problem, `lw6sys_free` takes 3 args. And the `LW6SYS_FREE` macro is not usable in such a context. And you can't use standard `free` either for it would mess up the `malloc` / `free` automatical count which is so convenient to track memory leaks. So this callback is here, it's only drawback is that in case of an error, the error will not be reported with the real file and line parameters. It's still better than nothing.

> Return value: none.

— Function: int lw6sys_megabytes_available ()

> Gives a raw approximation of available memory, in megabytes. Value is to be taken with distance, but it can give good hints when system is running short of ressources.

> Return value: number of megabytes (physical memory) available.

— Function: int lw6sys_is_big_endian ()

> Checks the endianess of the machine. PPC is big endian, for instance.

> Return value: 1 if system is big endian, 0 if little endian.

— Function: int lw6sys_is_little_endian ()

> Checks the endianess of the machine. x86 is little endian, for instance.

> Return value: 1 if system is little endian, 0 if big endian.

— Function: int lw6sys_check_types_size ()

> Checks of common types and usefull structures, this is a debugging function which helps finding compiler strange behaviors and programmer's bad intuitions.

> Return value: 1 if everything is OK, 0 if error.

— Function: void * lw6sys_mutex_create ()

> Creates a mutex object.

> Return value: newly allocated pointer.

— Function: void lw6sys_mutex_destroy (void * mutex)

> mutex: the mutex to destroy.

> Destroys a mutex object.

> Return value: none.

— Function: int lw6sys_mutex_lock (void * mutex)

> mutex: the mutex to use

> Locks the mutex. Note that this should never fail unless there's a serious initialization problem, instead, function will wait forever until mutex is released.

> Return value: 1 if success, 0 if failure.

— Function: int lw6sys_mutex_trylock (void * mutex)

> mutex: the mutex to use

> Tries to locks the mutex. That is, tells wether mutex can be locked immediately or not. Note that this does not mean there's 100% chance next call to lock will terminated immediately, since lock can still be acquired by another thread.

> Return value: 1 if mutex unlocked, 0 if locked or error.

— Function: int lw6sys_mutex_unlock (void * mutex)

> mutex: the mutex to use

> Unlocks a mutex.

> Return value: 1 if sucess, 0 if error.

— Function: int lw6sys_get_mutex_lock_count ()

> Returns how many mutexes have been locked since program start. Usefull for sanity checking when debugging.

> Return value: number of calls to lock

— Function: int lw6sys_get_mutex_unlock_count ()

> Returns how many mutexes have been unlocked since program start. Usefull for sanity checking when debugging.

> Return value: number of calls to unlock

— Function: int lw6sys_check_mutex_count ()

> Checks wether unlock has been called as many times as lock. Usefull for sanity checking when debugging.

> Return value: 1 if OK, 0 if inconsistency.

— Function: int lw6sys_true ()

> Function which returns always true, that is, something different than 0.

— Function: int lw6sys_false ()

> Function which returns always false, that is, 0. This can seem totally useless but it does have some utility. It's used for instance to "fool" the compiler and force it to compile and link functions in binaries, so that, afterwards, dynamically loaded .so files can find in the main binary some functions which would otherwise be stripped during the final link.

— Function: char * lw6sys_get_default_user_dir ()

> Returns the default user directory. Note that this value is not static, it can depend, for instance, of the environment variable `HOME`.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_config_file ()

> Returns the default config file. Note that this value is not static, it can depend, for instance, of the environment variable `HOME`.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_log_file ()

> Returns the default log file. Note that this value is not static, it can depend, for instance, of the environment variable `HOME`.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_prefix ()

> Returns the default prefix, could be /usr/local for instance.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_mod_dir ()

> Returns the default module directory (dynamically loaded libraries).

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_data_dir ()

> Returns the default data directory.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_music_dir ()

> Returns the default music directory.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_music_path ()

> Returns the default music path, which can be composed of several directories.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_map_dir ()

> Returns the default map directory.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_map_path ()

> Returns the default map path, which can be composed of several directories.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_default_script_file ()

> Returns the default script file.

> Return value: a newly allocated string.

— Function: void lw6sys_options_log_defaults ()

> Logs all default values to log file. Usefull for debugging, to know where the program is searching for its informations.

— Function: char * lw6sys_get_cwd ()

> Returns the current working directory (absolute path).

> Return value: a newly allocated string.

— Function: char * lw6sys_get_run_dir (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the binary directory, that is, the directory the binary is stored in. This is calculated dynamically, by interpreting command-line arguments.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_user_dir (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the user dir, taking in account command-line and environment variables. However config file content has no impact on the result.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_config_file (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the config file, taking in account command-line and environment variables. However config file content has no impact on the result.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_log_file (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the log file, taking in account command-line and environment variables. However config file content has no impact on the result.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_prefix (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the prefix, taking in account command-line and environment variables. However config file content has no impact on the result.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_mod_dir (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the mod dir (modules, shared .so), taking in account command-line and environment variables. However config file content has no impact on the result.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_data_dir (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the data dir, taking in account command-line and environment variables. However config file content has no impact on the result.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_music_dir (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the music dir, taking in account command-line and environment variables. However config file content has no impact on the result.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_music_path (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the music path, taking in account command-line and environment variables. However config file content has no impact on the result. Music path can contain several directories.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_map_dir (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the map dir, taking in account command-line and environment variables. However config file content has no impact on the result.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_map_path (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the map path, taking in account command-line and environment variables. However config file content has no impact on the result. Map path can contain several directories.

> Return value: a newly allocated string.

— Function: char * lw6sys_get_script_file (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Returns the script file, taking in account command-line and environment variables. However config file content has no impact on the result.

> Return value: a newly allocated string.

— Function: void lw6sys_options_log (int argc, char * [] argv)

> argc: argc, number of arguments, as given to `main`

> argv: argv, pointer to arguments, as given to `main`

> Logs all the main options values which are not config-file dependant but depend on built-in defaults, command-line arguments and environment variables. Usefull to debug and know where the program is searching for things.

— Function: char * lw6sys_password_checksum (char * seed, char * password)

> seed: a seed to blur the password, can be NULL

> password: the password, can be NULL

> Calculates the checksum of a password, and returns it as a string, ready to be sent on the network. If password is empty or NULL, then an empty (but not NULL unless internal error) string will be returned. All LW6 protocols should send these checksums instead of real passwords, then on server side value can be checked against both real password and its checksum. The seed is here so that eavesdropper can't reuse the checksum to connect on random sessions. Seed can typically be the node 'public_url' value.

> Return value: a dynamically allocated string

— Function: int lw6sys_password_verify (char * seed, char * password_here, char * password_received)

> seed: a seed to blur the password, can be NULL

> password_here: the local password, can be NULL

> password_received: the password received from network, can be NULL

> Tells wether a password received over the network is valid. The `password_here` argument (the local password) will be checksumed so that `password_received` is checked against both clear and checksumed values, so it can be in any form.

> Return value: 1 if OK, passwords are the same, 0 if not.

— Function: int lw6sys_file_exists (char * filename)

> filename: the file to test

> Tests the existence of a file on the filesystem. File is considered to exists if it's at least readable.

> Return value: 1 if OK, 0 if file doesn't exist or can't be read.

— Function: int lw6sys_dir_exists (char * dirname)

> dirname: the directory to test

> Tests the existence of a directory on the filesystem.

> Return value: 1 if OK, 0 if directory doesn't exist.

— Function: int lw6sys_create_dir (char * dirname)

> dirname: the directory to create

> Creates a directory, performing sanity checks such as verifying the directory really exists after being created.

> Return value: 1 if OK, 0 if error.

— Function: int lw6sys_create_dir_silent (char * dirname)

> dirname: the directory to create

> Creates a directory like `lw6sys_create_dir` but this function is silent in the sense that it won't log any error. Usefull to create the log directory itself, for instance, and avoid infinite loops on error.

> Return value: 1 if OK, 0 if error.

— Function: char * lw6sys_path_add_slash (char * path)

> path: a path

> Adds a slash, or in a general manner, a directory separator, at the end of a path, if needed. So /foo/bar will become /foo/bar/ but /bar/foo/ will remain /bar/foo/.

> Return value: a newly allocated string, must be freed.

— Function: char * lw6sys_path_strip_slash (char * path)

> path: a path

> Strips the slash, or in a general manner, the directory separator, at the end of a path, if needed. So /foo/bar/ will become /foo/bar but /bar/foo will remain /bar/foo.

> Return value: a newly allocated string, must be freed.

— Function: char * lw6sys_path_concat (char * path1, char * path2)

> path1: left part of the path

> path2: right part of the path

> Concatenates 2 parts of a path. Function will try to avoid stupid "double-slash" when concatenating /foo/ with /bar/ and conversely insert a directory separator when concatenating /foo with bar/.

> Return value: a newly allocated string, must be freed.

— Function: lw6sys_list_t * lw6sys_path_split (char * path)

> path: a path

> Splits a path into all its parts. For instance /boo/bar/foo2/bar2 returns a 4 elements list. This is more than a plain split, for heading and tailing slashes will be ignored, and various path separators will be interpreted (depends on platform).

> Return value: a list containing 0-terminated strings.

— Function: int lw6sys_path_is_relative (char * path)

> path: a path

> Checks wether a path is relative or absolute.

> Return value: 1 if relative, 0 if absolute.

— Function: int lw6sys_path_is_cwd (char * path)

> path: a path

> Checks wether a path is "." or not. Will also trap "" and "./".

> Return value: 1 if relative, 0 if absolute.

— Function: char * lw6sys_path_parent (char * path)

> path: a path

> Returns the parent path. That will return /foo when given /foo/bar in input.

> Return value: a newly allocated string, must be freed.

— Function: char * lw6sys_path_unparent (char * path)

> path: a path

> Given the ../foo/bar path, will return foo/bar. Usefull to get rid of heading ../ when a path is known to start with it.

> Return value: a newly allocated string, must be freed.

— Function: char * lw6sys_path_unparent_no_malloc (char * path)

> path: a path

> Given the ../foo/bar path, will return foo/bar. Usefull to get rid of heading ../ when a path is known to start with it. This is different from `lw6sys_path_unparent` just because the result is not dynamically allocated and copied from source.

> Return value: a pointer which points somewhere within the string passed as an argument.

— Function: lw6sys_list_t * lw6sys_dir_list (char * dir, lw6sys_dir_list_filter_func_t filter_func, void * func_data, int * n)

> dir: the path of the directory to list

> filter_func: a function which will filter entries, can be NULL

> func_data: additionnal data passed to filter_func

> n: will contain the number of items found

> This list a directory. The filter will be passed the file path as an argument. If it returns 1, the file is kept, if it returns 0 it's suppressed from the list.

> Return value: a list containing strings (file paths).

— Function: lw6sys_list_t * lw6sys_path_list (char * path, lw6sys_dir_list_filter_func_t filter_func, void * func_data, int * n)

> path: the path of the path to list

> filter_func: a function which will filter entries, can be NULL

> func_data: additionnal data passed to filter_func

> n: will contain the number of items found

> This list a directory. By path we mean here a list of separated directories, separated by : for instance. The filter will be passed the file path as an argument. If it returns 1, the file is kept, if it returns 0 it's suppressed from the list. It's like performing a call to `lw6sys_dir_list` on each of the path members.

> Return value: a list containing strings (file paths).

— Function: char * lw6sys_find_in_dir_and_path (char * dir, char * path, char * file)

> dir: a directory, when to search the file first

> path: the path to search too, a separated list of dirs

> file: the filename to search for

> Tries to find a file in the given paths. The function is typically used to find music files. First it tries to find the file in dir, then it tries to find it in each dir of path. `file` must be only a file name and not contain any directory. The function will use the filename only anyway.

> Return value: the full path of the found file.

— Function: void lw6sys_print_xml_header (FILE * f, char * comment)

> f: file to output content to

> Prints a standard Liquid War compliant XML header in the given file.

> Return value: none.

— Function: void lw6sys_print_xml_footer (FILE * f)

> f: file to output content to

> Prints a standard Liquid War 6 compliant XML footer in the given file.

> Return value: none.

— Function: int lw6sys_profiler_check (int verbose)

> verbose: wether to display informations on the console

> Checks wether Google Profiler support has been built, and if it's set, outputs the log file. If CPUPROFILE is defined but binary has no support for it, will display a warning message.

> Return value: 1 if google profile enabled and activated, 0 if not

— Function: void lw6sys_progress_default (lw6sys_progress_t * progress, float * value)

> progress: the progress struct to initialize

> value: the value to point to

> Sets a progress struct to default values, that is, ranging from 0.0f to 1.0f.

> Return value: none.

— Function: void lw6sys_progress_update (lw6sys_progress_t * progress, int min, int max, int value)

> progress: the progress struct to update

> min: the min value

> max: the max value

> value: the current value

> Updates a progress struct. This is typically the function used by a callback to show the progress of a process. Note that this is note an initializer. Rather, the progress struct was initialized before, and this call is done in a loop with min being 0, max being the last value in the loop, and value the current index in the loop. NULL pointers correctly handled internally, so call this with any parameters, it's safe.

> Return value: none.

— Function: void lw6sys_progress_split (lw6sys_progress_t * progress1, lw6sys_progress_t * progress2, lw6sys_progress_t * progress_src)

> progress1: the first part of the splitted progress progress2: the second part of the splitted progress progress_src: the progress to split

> Utility function to split a progress struct, that is, if a progress was ranging from a to b, make 2 progress structs, ranging from a to c and from c to b, c being between a and b.

> Return value: none

— Function: void lw6sys_progress_split_here (lw6sys_progress_t * progress1, lw6sys_progress_t * progress2, lw6sys_progress_t * progress_src, float here)

> progress1: the first part of the splitted progress progress2: the second part of the splitted progress progress_src: the progress to split here: where to split

> Utility function to split a progress struct, that is, if a progress was ranging from a to b, make 2 progress structs, ranging from a to c and from c to b, c being between a and b. The here value controls what c is. If here=0, then c=a. If here=1, then c=b.

> Return value: none

— Function: void lw6sys_progress_split3 (lw6sys_progress_t * progress1, lw6sys_progress_t * progress2, lw6sys_progress_t * progress3, lw6sys_progress_t * progress_src)

> progress1: the first part of the splitted progress progress2: the second part of the splitted progress progress3: the third part of the splitted progress progress_src: the progress to split

> Utility function to split a progress struct, this one will split it into 3 equal parts.

> Return value: none

— Function: void lw6sys_progress_split4 (lw6sys_progress_t * progress1, lw6sys_progress_t * progress2, lw6sys_progress_t * progress3, lw6sys_progress_t * progress4, lw6sys_progress_t * progress_src)

> progress1: the first part of the splitted progress progress2: the second part of the splitted progress progress3: the third part of the splitted progress progress4: the fourth part of the splitted progress progress_src: the progress to split

> Utility function to split a progress struct, this one will split it into 4 equal parts.

> Return value: none

— Function: void lw6sys_progress_split5 (lw6sys_progress_t * progress1, lw6sys_progress_t * progress2, lw6sys_progress_t * progress3, lw6sys_progress_t * progress4, lw6sys_progress_t * progress5, lw6sys_progress_t * progress_src)

> progress1: the first part of the splitted progress progress2: the second part of the splitted progress progress3: the third part of the splitted progress progress4: the fourth part of the splitted progress progress5: the fourth part of the splitted progress progress_src: the progress to split

> Utility function to split a progress struct, this one will split it into 5 equal parts.

> Return value: none

— Function: void lw6sys_progress_begin (lw6sys_progress_t * progress)

> progress: the progress to update

> Sets the progress to its min value, NULL values correctly handled.

> Return value: none

— Function: void lw6sys_progress_half (lw6sys_progress_t * progress)

> progress: the progress to update

> Sets the progress to the average between min and max, NULL values correctly handled.

> Return value: none

— Function: void lw6sys_progress_end (lw6sys_progress_t * progress)

> progress: the progress to update

> Sets the progress to its max value, NULL values correctly handled.

> Return value: none

— Function: u_int32_t lw6sys_random (u_int32_t range)

> range: the high limit for random generated numbers. If you want random numbers between 0 and 5, set this to 6.

> Wrapper over standard random function. This one is thread safe. This idea is not to provide cryptographic-proof random numbers, rather generate sequences which are random enough to generate unique server ids and such things. The function is initialized on its first call, and results depend on timestamp, host name, user name, and memory available.

— Function: float lw6sys_random_float (float min, float max)

> min: the min value, as a float

> max: the max value, as a float

> Returns a random float number between min & max. Can be equal to min or max.

— Function: int lw6sys_sdl_register ()

> Function used to avoid initializing SDL several times in a program. AFAIK Allegro has a `was_init` function, but SDL doesn't. With this function - which every LW6 sub-module should use - one can know globally, for the whole program, wether SDL has been initialized or not.

— Function: int lw6sys_sdl_unregister ()

> Call this whenever you are done with SDL and exit it, so that the `lw6sys_sdl_register` function works correctly.

> Return value: 1 if SDL needs to be unregistered, that is, if it has already been initialized, else 0.

— Function: void lw6sys_serialize_int64 (unsigned char * data, int64_t value)

> data: pointer to the data, must contain at least 8 bytes of writable space

> value: the integer to serialize

> Serializes a 64-bit integer in a byte buffer. Result is not dependant on machine endianess. Typically used for checksums or high-level serializations.

— Function: int64_t lw6sys_unserialize_int64 (unsigned char * data)

> data: pointer to the data, must contain at least 8 bytes

> Recovers a 64-bit integer from a byte buffer created, for instance, with `lw6sys_serialize_int64`.

— Function: void lw6sys_serialize_int32 (unsigned char * data, int32_t value)

> data: pointer to the data, must contain at least 4 bytes of writable space

> value: the integer to serialize

> Serializes a 32-bit integer in a byte buffer. Result is not dependant on machine endianess. Typically used for checksums or high-level serializations.

— Function: int32_t lw6sys_unserialize_int32 (unsigned char * data)

> data: pointer to the data, must contain at least 4 bytes

> Recovers a 32-bit integer from a byte buffer created, for instance, with `lw6sys_serialize_int32`.

— Function: void lw6sys_serialize_int16 (unsigned char * data, int16_t value)

> data: pointer to the data, must contain at least 2 bytes of writable space

> value: the integer to serialize

> Serializes a 16-bit integer in a byte buffer. Result is not dependant on machine endianess. Typically used for checksums or high-level serializations.

— Function: int16_t lw6sys_unserialize_int16 (unsigned char * data)

> data: pointer to the data, must contain at least 2 bytes

> Recovers a 16-bit integer from a byte buffer created, for instance, with `lw6sys_serialize_int16`.

— Function: int lw6sys_shape_check_min_max_whd (lw6sys_whd_t * shape, int min_wh, int max_wh, int max_d)

> shape: the dimensions to control

> min_wh: the min value for w and h

> max_wh: the max value for w and h

> max_d: the max value for d

> Will check wether the given shape respects some basic constraints, being not to small and not too big.

> Return value: 1 if OK, 0 if not.

— Function: int lw6sys_shape_check_pos (lw6sys_whd_t * shape, lw6sys_xyz_t * pos)

> shape: the boundary box

> pos: the position

> Checks wether position is within the given boundary box.

> Return value: 1 if OK, 0 if not.

— Function: int lw6sys_shape_is_same (lw6sys_whd_t * shape_a, lw6sys_whd_t * shape_b)

> shape_a: the first shape to compare

> shape_b: the other shape to compare

> Compares two shapes.

> Return value: 1 if same, 0 if not.

— Function: int lw6sys_shape_is_same_xy (lw6sys_whd_t * shape_a, lw6sys_whd_t * shape_b)

> shape_a: the first shape to compare

> shape_b: the other shape to compare

> Compares two shapes, but ignores the z (d) parameter.

> Return value: 1 if same_xy, 0 if not.

— Function: int lw6sys_sort_int_callback (lw6sys_list_t ** list_a, lw6sys_list_t ** list_b)

> list_a: pointer to a list of int item

> list_b: pointer to a list of int item

> A typicall sort callback function, can be passed to `lw6sys_sort` to sort a list of integers.

> Return value: -1 if `list_a` < `list_b` , 0 if `list_a` == `list_b`, 1 if `list_a` > `list_b`

— Function: int lw6sys_sort_int_desc_callback (lw6sys_list_t ** list_a, lw6sys_list_t ** list_b)

> list_a: pointer to a list of int item

> list_b: pointer to a list of int item

> A typicall sort callback function, can be passed to `lw6sys_sort` to sort a list of integers. This one will sort in reverse mode.

> Return value: 1 if `list_a` < `list_b` , 0 if `list_a` == `list_b`, -1 if `list_a` > `list_b`

— Function: int lw6sys_sort_float_callback (lw6sys_list_t ** list_a, lw6sys_list_t ** list_b)

> list_a: pointer to a list of float item

> list_b: pointer to a list of float item

> A typicall sort callback function, can be passed to `lw6sys_sort` to sort a list of floating point numbers.

> Return value: -1 if `list_a` < `list_b` , 0 if `list_a` == `list_b`, 1 if `list_a` > `list_b`

— Function: int lw6sys_sort_float_desc_callback (lw6sys_list_t ** list_a, lw6sys_list_t ** list_b)

> list_a: pointer to a list of float item

> list_b: pointer to a list of float item

> A typicall sort callback function, can be passed to `lw6sys_sort` to sort a list of floating point numbers. This one will sort in reverse mode.

> Return value: 1 if `list_a` < `list_b` , 0 if `list_a` == `list_b`, -1 if `list_a` > `list_b`

— Function: int lw6sys_sort_str_callback (lw6sys_list_t ** list_a, lw6sys_list_t ** list_b)

> list_a: pointer to a list of string item

> list_b: pointer to a list of string item

> A typicall sort callback function, can be passed to `lw6sys_sort` to sort a list of 0-terminated strings.

> Return value: -1 if `list_a` < `list_b` , 0 if `list_a` == `list_b`, 1 if `list_a` > `list_b`

— Function: int lw6sys_sort_str_desc_callback (lw6sys_list_t ** list_a, lw6sys_list_t ** list_b)

> list_a: pointer to a list of string item

> list_b: pointer to a list of string item

> A typicall sort callback function, can be passed to `lw6sys_sort` to sort a list of 0-terminated strings. This one will sort in reverse mode.

> Return value: 1 if `list_a` < `list_b` , 0 if `list_a` == `list_b`, -1 if `list_a` > `list_b`

— Function: void lw6sys_sort (lw6sys_list_t ** list, lw6sys_sort_callback_func_t sort_func)

> list: the list to sort, might be modified by the function

> sort_func: the callback function used to sort

> A general sorting function. Internally, will use the glibc `qsort` function, but this one is adapted to the LW6 specific data structures, more exactly, the `lw6sys_list` structure. Several default sort callbacks are defined, but one is free to use any callback, provided it has the right prototype.

— Function: void * lw6sys_spinlock_create ()

> Creates a spinlock object.

> Return value: newly allocated pointer.

— Function: void lw6sys_spinlock_destroy (void * spinlock)

> spinlock: the spinlock to destroy.

> Destroys a spinlock object.

> Return value: none.

— Function: int lw6sys_spinlock_lock (void * spinlock)

> spinlock: the spinlock to use

> Locks the spinlock. Note that this should never fail unless there's a serious initialization problem, instead, function will wait forever until spinlock is released.

> Return value: 1 if success, 0 if failure.

— Function: int lw6sys_spinlock_trylock (void * spinlock)

> spinlock: the spinlock to use

> Tries to locks the spinlock. That is, tells wether spinlock can be locked immediately or not. Note that this does not mean there's 100% chance next call to lock will terminated immediately, since lock can still be acquired by another thread.

> Return value: 1 if spinlock unlocked, 0 if locked or error.

— Function: int lw6sys_spinlock_unlock (void * spinlock)

> spinlock: the spinlock to use

> Unlocks a spinlock.

> Return value: 1 if sucess, 0 if error.

— Function: char * lw6sys_str_copy (char * src)

> src: the string to copy

> Duplicate a string, creating a new pointer on it, which must be freed afterwards. The main difference with `strdup` is that here we use the LW6SYS_MALLOC macro to track down possible memory leaks.

> Return value: a newly allocated pointer, must be freed.

— Function: char * lw6sys_str_concat (char * str1, char * str2)

> str1: the left part to be concatenated

> str2: the right part to be concatenated

> Concatenate 2 strings, and put the result in a newly allocated string. Unlike `strcat` which uses the same pointer.

> Return value: a newly allocated pointer, must be freed.

— Function: char * lw6sys_new_sprintf (char * fmt, ...)

> fmt: a format string, like the one you would pass to `printf` ...: optional arguments, like the ones you would pass to `printf`

> An sprintf like function, except it allocates a new string automatically, with "enough space". This is not a highly optimized function, it will allocate plenty of memory, possibly several times, and thus consume time and resources. But it has the great advantage of freeing the programmer of the dirty work of guessing "how log will the sprintf'ed string be?" before even generating it. So it's a time saver for the programmer. Additionnally, helps avoiding memory leaks and buffer overflows.

> Return value: a new allocated string, must be freed.

— Function: int lw6sys_str_is_blank (char * str)

> str: the string to test

> Tests wether a string is blank, that is, if it's composed of space, tabs, or carriage returns only.

> Return value: 1 if blank, 0 if not.

— Function: int lw6sys_str_is_same (char * str_a, char * str_b)

> str_a: 1st string to compare, can be NULL

> str_b: 2nd string to compare, can be NULL

> Compares two strings for equality. Difference with strcmp is that this one won't check for alphabetical order and return -1 or +1, but will check for NULL args. of space, tabs, or carriage returns only.

> Return value: 1 if same, 0 if not.

— Function: int lw6sys_str_is_same_no_case (char * str_a, char * str_b)

> str_a: 1st string to compare, can be NULL

> str_b: 2nd string to compare, can be NULL

> Compares two strings for equality. Difference with strcmp is that this one won't check for alphabetical order and return -1 or +1, but will check for NULL args. of space, tabs, or carriage returns only. This function is not case sensitive.

> Return value: 1 if same, 0 if not.

— Function: int lw6sys_str_starts_with (char * str, char * beginning)

> str: the string to analyse

> beginning: the pattern to search

> Tells wether string starts with a given beginning.

> Return value: 1 if `str` starts with `beginning`, 0 if not

— Function: int lw6sys_str_starts_with_no_case (char * str, char * beginning)

> str: the string to analyse

> beginning: the pattern to search

> Tells wether string starts with a given beginning. This function is not case sensitive.

> Return value: 1 if `str` starts with `beginning`, 0 if not

— Function: int lw6sys_skip_blanks (char ** str_ptr)

> str_ptr: a pointer to a string pointer (read/write parameter).

> Skips blanks at the beginning of a string. The passed parameter is modifed in place. Usefull for parsing.

> Return value: 1 if blanks were found, else 0.

— Function: void lw6sys_str_cleanup (char * str)

> str: a pointer to the string, which will be modified in-place.

> Used to clean up some strings, for instance if they come from the network, we don't necessarly want system chars to be displayed on the console. Basically it removes all characters with an ASCII code inferior to 32, that is, all system characters. This way, there won't be any tab, linefeed, or any of such characters left.

> Return value: none.

— Function: void lw6sys_str_cleanup_ascii7 (char * str)

> str: a pointer to the string, which will be modified in-place.

> Used to clean up some strings, for instance if they come from the network, we don't necessarly want system chars to be displayed on the console. Basically it removes all characters with an ASCII code inferior to 32, that is, all system characters. This way, there won't be any tab, linefeed, or any of such characters left. This function will even remove any character above ASCII 127.

> Return value: none.

— Function: char * lw6sys_str_reformat (char * str, char * prefix, int nb_columns)

> str: a pointer to the string we want to modify

> prefix: a prefix to put before each line

> Reformats a string, that is, insert newline characters in the right places to that it fits in a given number of columns. A prefix is appended at the beginning of each line. Will not handle strings which already contain newline characters perfectly.

> Return value: a newly allocated string, must be freed.

— Function: char * lw6sys_eol ()

> Returns the value of EOL, that is, the "end of line" sequence. Will simply return "\n" on UNIX and "\r\n" on Microsoft platforms. Note that while this is convenient to write config and example files, for instance, it's a bad idea to use this to generate network messages, because this kind of message needs to be platform independant. Thus any network protocol oriented string would use chr(10) and char(13) directly.

> Return value: the EOL string, must not be freed.

— Function: lw6sys_list_t * lw6sys_str_split (char * str, char c)

> str: a string

> c: the delimiter to split with

> Splits a string, for instance 'foo,bar' splited with 'o' will return 'f', ” and ',bar'.

> Return value: a list containing 0-terminated strings.

— Function: lw6sys_list_t * lw6sys_str_split_no_0 (char * str, char c)

> str: a string

> c: the delimiter to split with

> Splits a string, ignoring empty '0-length' members. For instance 'foo,bar' splited with 'o' will return 'f' and ',bar'.

> Return value: a list containing 0-terminated strings.

— Function: lw6sys_list_t * lw6sys_str_split_config_item (char * str)

> str: a string

> Splits a string, ignoring empty '0-length' members, and using the comma ',' as a separator. This is typically usefull for config elements such as backend lists. Only paths need another separator (platform-dependant).

> Return value: a list containing 0-terminated strings.

— Function: void lw6sys_str_toupper (char * str)

> str: the string to modify

> Transforms a string to upper case, the pointer must point to modifiable data.

> Return value: none, `str` pointed data modified in-place

— Function: void lw6sys_str_tolower (char * str)

> str: the string to modify

> Transforms a string to lower case, the pointer must point to modifiable data.

> Return value: none, `str` pointed data modified in-place

— Function: void lw6sys_str_truncate (char * str, int len)

> str: the string to truncate

> len: the new length

> Truncates a string to the max given length. If truncated to 3, "abcdef" becomes "abc".

> Return value: none, `str` pointed data modified in-place

— Function: int lw6sys_test_exec (int argc, char * [] argv, int mode)

> argc: number of args as passed to main

> argv: array of args as passed to main

> mode: 0 for check only, 1 for full test

> Runs the `sys` module test suite which is specific to exec functions, these ones require `argc` and `argv` to be correctly set so the extra argument justifies putting it outside `lw6sys_test`. Additionnally, it's not fool proof...

> Return value: 1 if test is successfull, 0 on error.

— Function: int lw6sys_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `sys` module test suite, testing most (if not all...) functions. Note that some tests perform file system operations and might therefore fail on a read-only filesystem, or if user permissions are not sufficient.

> Return value: 1 if test is successfull, 0 on error.

— Function: void * lw6sys_thread_create (lw6sys_thread_callback_func_t callback_func, lw6sys_thread_callback_func_t callback_join, void * callback_data)

> callback_func: the main callback, the function that will run the thread

> callback_join: function which will be called when joining, at the end

> callback_data: data which will be passed to the callback

> Creates a thread. All threads must be joined. This is because we really do not want the game to leak, and detached threads are typically the kind of thing that leaves stuff in the heap. Note that callback_func is just something which will be called when joining it can be NULL. The idea is to put in it free & delete functions, which you can't call before joining when you want the main thread to get the results of the callback_func.

> Return value: an opaque pointer on the thread. Can be NULL if failed.

— Function: int lw6sys_thread_is_callback_done (void * thread_handler)

> thread_handler: thread to work on

> Tells wether the callback is done, that is to say, wether the results are available, and we can join.

> Return value: 1 if done, else 0.

— Function: int lw6sys_thread_get_id (void * thread_handler)

> thread_handler: thread to query

> Returns the id of the thread, this is an internal value, unique for each process, which can help identifying the thread.

> Return value: the id, should be >0.

— Function: void * lw6sys_thread_get_data (void * thread_handler)

> thread_handler: thread to query

> Returns the data associated to the thread, that is, the pointer which was passed to the callback function.

> Return value: a pointer.

— Function: void lw6sys_thread_join (void * thread_handler)

> thread_handler: thread to end

> Joins the thread, that's to say wait until the thread is over, and destroys the ressources associated to it. Note that if the thread is looping forever, this function will just wait forever. This is the only way to end a thread.

> Return value: none.

— Function: int lw6sys_get_thread_create_count ()

> Utility function used to check how many threads where created and joined.

> Return value: how many threads were created.

— Function: int lw6sys_get_thread_join_count ()

> Utility function used to check how many threads where created and joined.

> Return value: how many threads were joined.

— Function: int lw6sys_check_thread_count ()

> Utility function used to check how many threads where created and joined. This one will compare the results of `lw6sys_get_thread_create_count` and `lw6sys_get_thread_join_count`.

> Return value: 1 if both are equals, 0 if not (error...).

— Function: int64_t lw6sys_get_timestamp ()

> Returns a 64-bit timestamp, for general purpose. The unit is milliseconds, should return the number of milliseconds since EPOCH. Don't use this for accurate date handling, but rather to technical stamp events.

> Return value: the timestamp.

— Function: int64_t lw6sys_get_uptime ()

> Returns the number of milliseconds since program was started. Milliseconds are often referred to as 'ticks'.

> Return value: the number of milliseconds (64-bit)

— Function: int32_t lw6sys_get_cycle ()

> Returns a 32-bit timestamp, which is likely to "loop" and have twice the same value during a single program execution. The idea here is just to provide a 32-bit value, not too big, for animation purposes. The idea is that with 64-bit values, numbers are too big and if the goal is just to animate a cursor or spin a sphere, one does not care if every ten hours there's a display glitch because value became zero again. Besides, those values are often used for their "rest" in a module operation, to translate textures for instance, and having too big numbers causes floating point imprecisions. In fact those values or even only 20-bit. The function is based on `lw6sys_get_uptime`() so it will return 0 at game startup.

> Return value: the cycle value, a 20-bit integer.

— Function: void lw6sys_timer_update (int64_t * timestamp, int64_t * uptime, int32_t * cycle)

> timestamp: the timestamp in msec since EPOCH (output), can be NULL

> uptime: the uptime in msec since startup (output), can be NULL

> cycle: a 20-bit value for animation purpose.

> Returns timestamp & uptime with only one system call.

> Return value: none (parameters modified).

— Function: void lw6sys_sleep (float seconds)

> seconds: the number of seconds to wait, fractions allowed

> Will sleep for the given amount of seconds. Same as `lw6sys_delay` only input is provided as a floating number of seconds instead of ticks.

— Function: void lw6sys_delay (int msec)

> msec: the number of milliseconds (ticks) to wait

> Will sleep for the given amount of seconds. Provides accurate timing and has "about-millisecond" precision, since it uses `select` internally. Might however be interrupted in some cases, so consider function can always return quicker than specified. A common usage of this function is polling loops, where you don't care if 2 polls are very close, but simply want to avoid polling continuously, therefore consumming 100% of the CPU for nothing.

— Function: void lw6sys_idle ()

> Will sleep for a minimal amount of time, just giving the OS a chance to let other threads/processes execute themselves. This can make a big difference in polling loops between a process that eats 100% CPU and a process that has a very moderate load. of ticks.

— Function: void lw6sys_snooze ()

> Will sleep for some time, like `lw6sys_idle`, except it's a "longer" time, use this when you don't really care about reactivity but are more concerned about saving CPU, not running uselessly the same polling code.

— Function: void lw6sys_time_init ()

> Global initializations required to handle time properly.

— Function: char * lw6sys_date_rfc1123 (int seconds_from_now)

> seconds_from_now: an offset to add to current time

> Gives the date according to RFC1123, this is typically usefull for HTTP protocol.

> Return value: newly allocated string.

— Function: char * lw6sys_date_clf ()

> Gives the date in a format which is compatible with Apache CLF Common Log Format.

> Return value: newly allocated string.

— Function: char * lw6sys_readable_uptime (int64_t timestamp_delta)

> timestamp_delta: the duration to show, in msec

> Returns a readable form of an uptime, typically 1d 12:34:06 for one day, 12 hours, 34 min, 6 sec or 7:03:45 for 7 hours, 3 minutes 45 sec.

> Return value: newly allocated string

— Function: extern char * lw6sys_url_http_from_ip_port (char * ip, int port)

> ip: IP address

> port: IP port

> Returns an http URL pointing to ip: port that is, adds a heading http:// and a trailing /, and treats port 80 as default. This is used to create public_url in net modules.

> Return value: a newly allocated string, NULL on error.

— Function: lw6sys_url_t * lw6sys_url_parse (char * url)

> url: the URL to parse

> Parses a URL, this is not a complete RFC compliant parser, it's only used to transform URLs into their 'canonical' form as well as getting basic info such as on which port one should connect.

> Return value: a newly allocated struct, NULL on error

— Function: void lw6sys_url_free (lw6sys_url_t * url)

> url: the url struct to free

> Frees a URL struct and all its members.

> Return value: none.

— Function: char * lw6sys_url_canonize (char * url)

> url: the url to check & transform

> Checks if a given URL is correct and, if it is, transforms it into its canonical form. This is mostly to get rid of typesettings error, add a tailing /, transform all domain into lowercase, among other things. A canonized url passed into this function should come out exactly the same.

> Return value: a newly allocated string.

— Function: int lw6sys_url_is_canonized (char * url)

> url: the URL to check

> Checks wether an URL is in its canonized form.

> Return value: 1 if OK (canonized form), 0 if not

— Function: int lw6sys_vthread_run (lw6sys_thread_callback_func_t callback_func, lw6sys_thread_callback_func_t callback_join, void * callback_data)

> callback_func: the main callback, the function that will run the thread

> callback_join: function which will be called when joining, at the end

> callback_data: data which will be passed to the callback

> This function is similar to `lw6sys_thread_create`, but it's dedicated to creating a unique (one per process only) thread, which, in turn, will be able to run commands in the main thread itself. This is a hack to allow apparently spawned child threads to be actually handled by main. This is because some libraries, which LW6 uses in threads, need to be actually called in the main thread. SDL, for instance. Note that after running this you loose control on the main thread, this one will only wait for possible commands from the spawned thread, typically sent with the `lw6sys_vthread_create` function.

> Return value: 1 on success, 0 on failure.

— Function: int lw6sys_vthread_is_running ()

> Returns true if `lw6sys_vthread_run` has been called. Note that this is not bullet proof, it will return true in a correct manner only if you call it from the vthread itself. In practise this shouldn't be a problem, the idea is just to write portable code for the main control thread and be able to decide on the fly wether to create a thread we should prefer the `lw6sys_thread_create` or its equivalent the `lw6sys_vthread_create` function.

> Return value: 1 on success, 0 on failure.

— Function: int lw6sys_vthread_create (lw6sys_thread_callback_func_t callback_func, lw6sys_thread_callback_func_t callback_join, void * callback_data)

> callback_func: the main callback, the function that will run the thread

> callback_join: function which will be called when joining, at the end

> callback_data: data which will be passed to the callback

> The equivalent of `lw6sys_thread_create` but for the vthread infrastructure. The idea is to pretend firing a spawned thread, but in fact it's the main thread that runs the code. This function must imperatively be called within the `lw6sys_vthread_run` function, else it will fail or be buggy.

> Return value: 1 on success, 0 on failure.

— Function: void lw6sys_vthread_join ()

> The equivalent of `lw6sys_thread_join` but for the vthread infrastructure. The idea is to pretend firing a spawned thread, but in fact it's the main thread that runs the code. This function must imperatively be called within the `lw6sys_vthread_run` function, else it will fail or be buggy.

> Return value: none.

#### 4.15.24 libtsk

— Function: lw6tsk_loader_t * lw6tsk_loader_new (float sleep, float * progress)

> sleep: how many seconds to wait between every poll

> Creates a new loader. This object is used to do some reputed slow calculus in the background, in a separated thread. Typical example is map loading. This is a high-level objects which encapsulates threads and other wizardry.

> Return value: a pointer to the loader, NULL if failed.

— Function: void lw6tsk_loader_free (lw6tsk_loader_t * loader)

> loader: the loader to free.

> Deletes a loader. Will automatically stop the child thread, free data, and so on.

> Return value: none.

— Function: char * lw6tsk_loader_repr (lw6tsk_loader_t * loader)

> loader: the loader to represent.

> Creates a string which briefly describes the loader.

> Return value: a dynamically allocated pointer, must be freed.

— Function: int lw6tsk_loader_get_stage (lw6tsk_loader_t * loader)

> loader: the loader to query.

> Returns the current stage of the loader.

> Return value: 0 if idle, 1 if loading the map from disk, 2 if build dynamic stuff such as game_state.

— Function: int lw6tsk_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `tsk` module test suite.

> Return value: 1 if test is successfull, 0 on error.