View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/sys/index.html.
sys_context: global system context
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.
sys_context: global system context
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.
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.
sys_context: global system context
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.
sys_context: global system context
argc: argc as passed to main
argv: argv as passed to main
Chooses between the two test modes "check" or "test" and also reports wether one should run "batch" or "interactive" tests. This is done by using the bit mask defined in LW6SYS_TEST_MODE_FULL_TEST and LW6SYS_TEST_MODE_INTERACTIVE.
Return value: a bit mask one can pass to test functions
sys_context: global system context
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.
sys_context: global system context
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
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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.
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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.
sys_context: global system context
skip: number of calls to skip
detailed: 0 for light output, 1 for complete, detailed messages
Returns the current backtrace as a comma separated list.
This can typically be used for debugging purposes. Not available
on some platforms, including mingw32, it requires backtrace_symbols
to be defined. Note that this function calls internal string functions
so it makes usage of the sys module in many ways, therefore should
be used only in other modules, it can’t be used for debugging of
internal memory functions for instance. To debug those, use
backtrace_symbols_fd directly (or maybe just gdb...). The skip
parameter allows you to skip caller’s stack, 0 will display
everything but lw6sys_backtrace itself.
Return value: dynamically allocated string
sys_context: global system context
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.
sys_context: global system context
Clears the memory bazooka.
Return value: none.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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
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.
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.
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.
Returns the id of the package. This is not an autotools standard
ID, in fact it’s just PACKAGE_TARNAME concatenated
with VERSION, that is liquidwar6-<version>.
Return value: a non-NULL string "liquidwar6-<version>", must not be freed.
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.
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).
Returns the program base version number. If version is X.Y.Z, this is X.Y, think of it as MAJOR.MINOR and globally determines the level of compatibility of the program. Two program exposing the same version should be network compatible and also be able to use the same ressource files (graphics, maps, sounds...) as well as being capable of using the same binary modules (graphics backends, bots and so on).
Return value: a non-NULL string, typically "0.1" (beta release) or "6.0" (stable). Must not be freed.
Returns the program major version number. If version is X.Y.Z, this is X. It’s mainly used to make the difference between alpha/beta releases (with "0" here) and stable releases using "6" as we are talking about LW6, after all.
Return value: a non-NULL string, typically "0" (beta release) or "6" (stable). Must not be freed.
Returns the program minor version number. If version is X.Y.Z, this is Y. This one should increase manually at each significant/public release of the game.
Return value: a non-NULL string like "42", which must not be freed.
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. If version is X.Y.Z, this is Z. Also called revision.
Return value: a non-NULL string like "666", which must not be freed.
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.
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.
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.
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.
Returns the URL for bugs, the bug reports page.
Return value: a non-NULL string, single line whithout ’\n’ at the end. Must not be freed.
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.
Returns __VERSION__ GCC preprocessor value, that is, the human readable version of the compiler.
Return value: a non-NULL string, must not be freed.
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.
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.
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.
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.
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.
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.
sys_context: global system context
Returns the endianness of the computer.
Return value: ’little’ (x86-like) or ’big’ (ppc-like), as a string. Must not be freed.
Returns the system pointer size, in bytes.
Return value: 4 for 32-bit, 8 for 64-bit.
Tells wether CPU belongs to x86 family or not.
Return value: 1 if x86, 0 if not
Tells wether CPU belongs to amd64 family or not.
Return value: 1 if amd64, 0 if not
Returns the OS this program is designed for. Usefull for bug reports.
Return value: a non-NULL string, must not be freed.
Tells wether the program was compiled for a GNU system, or not.
Return value: 1 if compiled on windows, 0 if not
Tells wether the program was compiled for a UNIX system, or not.
Return value: 1 if compiled on windows, 0 if not
Tells wether the program was compiled for Microsoft Windows, or not.
Return value: 1 if compiled on windows, 0 if not
Tells wether the program was compiled for Mac OS X, or not.
Return value: 1 if compiled on OS X, 0 if not
Tells wether the program was compiled for GP2X, or not.
Return value: 1 if compiled on OS X, 0 if not
sys_context: global system context
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. Note that the equivalent abs_srcdir function is somewhat more reliable.
Return value: a non-NULL string, must not be freed.
Returns top_srcdir as an absolute path, this is most of the time more usable than the relative path.
Return value: a non-NULL string, must not be freed.
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.
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.
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.
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.
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.
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.
Tells wether console is enabled or not.
Return value: "yes" or "no", must no be freed.
Tells wether gtk is enabled or not.
Return value: "yes" or "no", must no be freed.
Tells wether the graphical mod-gl1 backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the graphical mod-gles2 backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the graphical mod-soft backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the graphical mod-caca backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the audio mod-csound backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the audio mod-ogg backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the network mod-http backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled with openmp support.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled in optimize mode.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled in allinone mode.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled in fullstatic mode.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled with paranoid memory management.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled with suitable informations for gprof.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled with the ’-finstrument-fonctions’ GCC flag.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled for later use with Google Profiler support.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled with suitable informations for gcov.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled for later use with valgrind.
Return value: "yes" or "no", must no be freed.
sys_context: global system context
Returns the internal bin-id value, which does not mean anything but changes at each build.
Return value: an integer
sys_context: global system context
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.
sys_context: global system context
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 cache table. This is required because, internally, the object uses a hash. Note that this is an estimation only. You could theorically fit 1000000 objects in a 3-sized cache. Problem -> this is inefficient, you’d better use an assoc or a bigger cache. If you store 3 elements in a 1000000-sized cache, you’ll waste memory. It might be wise to use a prime number as the estimated size. 421 is prime ;)
Creates an empty cache. There’s a difference between NULL and an empty cache.
Return value: a pointer to the newly allocated cache table.
Must be freed with lw6sys_cache_free.
sys_context: global system context
cache: the cache to be freed.
The function will cascade delete all elements, using (if not NULL...) the callback passed when first creating the cache.
Return value: void
sys_context: global system context
data: data to free, this is normally an cache item
This is a wrapper, used as the actual free callback for the internal hash. What it does is that it just runs the real free callback (the one given by the user) on the member value. This indirection is required since we use the intermediate item object to store the timestamp along with the key and data.
Return value: none.
sys_context: global system context
cache: the cache to test
key: the key to search
Tells wether the key is present or not. If key is here but too old (expired) then will return 0 and key will be deleted on the fly.
Return value: non-zero if there’s an entry with the corresponding key.
sys_context: global system context
cache: the cache to query
key: the key of which we want the value
Gets the value corresponding to a given key. Note that the value might be NULL, even if the key exists. If the key has expired, NULL will be returned, and the entry deleted on the fly.
Return value: a void pointer to the data contained in the cache. 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 cache will actually free the data if needed.
cache: the cache to modify
key: the key we want to updated
value: the new value
Sets a value in a cache 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 cache of strings, key can disappear after calling this function, but not value. The function passed as free_func when creating the cache will be used to free stuff whenever needed (unset or free).
Return value: void
sys_context: global system context
cache: the cache concerned
key: the key to unset
Clears an entry in a cache table. The callback passed when creating the cache will be called if needed, to free the data automatically.
Return value: void
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
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.
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.
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.
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.
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.
color_f: the color to convert
Converts a color from floating point format to a single integer, where all fields (BGRA) 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.
color_f: the color to convert
Converts a color from floating point format to a single integer, where all fields (ARGB) 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.
color_f: the color to convert
Converts a color from floating point format to a single integer, where all fields (ABGR) 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.
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.
color_8: the color to convert
Converts a color from common "0 to 255" structured format to a single integer, where all fields (BGRA) 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.
color_8: the color to convert
Converts a color from common "0 to 255" structured format to a single integer, where all fields (ARGB) 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.
color_8: the color to convert
Converts a color from common "0 to 255" structured format to a single integer, where all fields (ABGR) 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.
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 (RGBA) to a floating point structure.
Return value: none.
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 (BGRA) to a floating point structure.
Return value: none.
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 (ARGB) to a floating point structure.
Return value: none.
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 (ABGR) to a floating point structure.
Return value: none.
color_i: the color to convert
Converts a color from a serialized integer format (RGBA) to a "0 to 255" based structure.
Return value: the converted color (structure).
color_i: the color to convert
Converts a color from a serialized integer format (BGRA) to a "0 to 255" based structure.
Return value: the converted color (structure).
color_i: the color to convert
Converts a color from a serialized integer format (ARGB) to a "0 to 255" based structure.
Return value: the converted color (structure).
color_i: the color to convert
Converts a color from a serialized integer format (ABGR) to a "0 to 255" based structure.
Return value: the converted color (structure).
sys_context: global system context
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).
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
color_hsv: the source color, in HSV format
invert_h: wether to invert the hue
invert_s: wether to invert the saturation
invert_v: wether to invert the value
Inverts an HSV color, calling it with 1,0,0 the color will become a color with opposite hue but same saturation and same value.
Return value: none.
color: the color to test
Tells wether a color is pure grey or not. This is interesting for such colors have no hue and sometimes need special handling.
Return value: 1 if grey, 0 if colored
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
color: the color to modify
Make a color "solid" that is make it not transparent at all.
Return value: none.
color: the color to modify
Make a color "solid" that is make it not transparent at all.
Return value: none.
Create a new global system context. This is normally called only once during a program execution and is wrapped in lw6sys_context_init.
Return value: newly allocated context
sys_context: global system context
Frees a global system context. Called only once during a program execution and is wrapped in lw6sys_context_quit.
Return value: none
sys_context: global system context
Performs all initializations required for lw6sys functions to behave correctly, this includes locale settings, timer initialization, memory management related stuff. This is wrapped into lw6sys_context_init.
Return value: none
sys_context: global system context
Performs all cleanup required after all lw6sys functions have been called. Once this has been called, do not call any function that requires a valid context, except maybe lw6sys_context_free. This is wrapped into lw6sys_context_quit.
Return value: 1 on success, 0 on failure. A failure can reveal a problem that occured way upstream, typically some memory not cleanly freed.
Create a new global system context, and initalizes it, so that it’s ready for general use.
Return value: newly allocated and valid context
sys_context: global system context
Performs all cleanup required after all lw6sys functions have been called, and frees the object.
Return value: 1 on success, 0 on failure. A failure can reveal a problem that occured way upstream, typically some memory not cleanly freed.
sys_context: global system context
str: string to convert
Just a plain wrapper on atoi, it’s here for API consistency.
Will check if str is NULL (and in this case return 0).
Return value: an integer.
sys_context: global system context
str: string to convert
Wrapper on atoll, it’s here for API consistency.
Will check if str is NULL (and in this case return 0).
Return value: a 64-bit integer.
sys_context: global system context
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. Will check if str is NULL (and in this case return 0).
Return value: an integer, 0 or 1.
sys_context: global system context
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.
Will check if str is NULL (and in this case return 0).
Return value: a float.
sys_context: global system context
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.
value: the integer to convert
Converts a 64-bit 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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
mode: mode passed to program (bit mask)
Run all registered suites and their tests, will interpret mode and call the right CUnit function (Batch, Console, NCurses...).
Return value: 1 if tests or OK, 0 if not.
sys_context: global system context
Clears the global CUnit related lock.
Return value: none.
sys_context: global system context
Locks a global CUnit related lock, this is to allow the use of test macro LW6SYS_TEST_ACK in multithreaded environment, as CUnit does not, by default garantee that concurrent accesses to its API will work. Just to be sure... we lock.
Return value: 1 if locked, 0 on failure.
sys_context: global system context
Unlocks the global CUnit related lock, this is to allow the use of test macro LW6SYS_TEST_ACK in multithreaded environment, as CUnit does not, by default garantee that concurrent accesses to its API will work. Just to be sure... we lock.
Return value: 1 if unlocked, 0 on failure.
sys_context: global system context
argc: argc as passed to main
argv: argv as passed to main
Get the default pid file, used to lock daemon and avoid 2 daemons running at the same time.
Return value: newly allocated string
sys_context: global system context
pid_file: the pid file used for the daemon
Calls fork internally to put the process in the program,
make it a daemon. Note this won’t work on all platforms,
for instance it won’t work on MS-Windows but this is rarely
an issue as MS-Windows users are rarely concerned with
detaching a program from a tty. Note that this isn’t a
wrapper on fork, the return value is different,
Return value: 1 on success, 0 on failure.
sys_context: global system context
pid_file: the pid file used for the daemon
Removes the daemon pid file. Can be called safely even if daemon wasn’t started.
Return value: 1 on success, 0 on failure
sys_context: global system context
Gets the debug mode.
sys_context: global system context
mode: the debug mode, 1 if set, 0 if not.
Sets the debug mode.
sys_context: global system context
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.
sys_context: global system context
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.
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.
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
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
sys_context: global system context
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
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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 an hexadecimal code which replaces them in URLs. 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.
sys_context: global system context
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 a double quote into its equivalent escaped char.
Return value: newly allocated string.
sys_context: global system context
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 an hexadecimal form which replaces them in URLs.
Return value: newly allocated string.
sys_context: global system context
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).
sys_context: global system context
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.
sys_context: global system context
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 (always fail)
sys_context: global system context
argc: number of args as passed to main
argv: array of args as passed to main
Restart the program with exactly the same arguments it was given the first time.
Return value: 1 on success, 0 on failure (always fail)
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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
sys_context: global system context
hash: the hash to test
key: the key to search
Tells wether the key is present or not.
Return value: non-zero if there’s an entry with the corresponding key.
sys_context: global system context
hash: the hash to query
key: the key of which we want the value
Gets the value corresponding to a given key. Not that the value can be NULL, even if the key exitsts.
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.
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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 sometimes be of little interest in this case. But the program won’t segfault.
Return value: the list of keys.
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
hexa_serializer: an hexa serializer object
Frees an hexa serializer object.
Return value: none.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
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
sys_context: global system context
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
sys_context: global system context
buf: binary buffer to convert
size: binary buffer length
str: the source string
Converts the stringified hexa representation of a string to
its source binary buffer. Buffer must be exactly strlen(str)/2
Return value: 1 on success
sys_context: global system context
buf: the buffer to stringify
size: the length of the buffer
Transforms a binary buffer into its hexa representation.
Return value: newly allocated string.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
Initializes the history system. Not initializing won’t cause any segfault, but data will be inconsistent.
Return value: none.
sys_context: global system context
msg: the message to register.
Registers a message in the history log, that is, adds it.
Return value: none.
sys_context: global system context
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.
sys_context: global system context
history: the data to free
Frees a pointer returned by lw6sys_history_get.
Return value: none.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
list: the list to delete.
Delete a list, this will cascade delete all the following items in the list.
Return value: none.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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).
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
list: a pointer to the list (pointer on pointer, read/write value)
Pops data to a list, in last-in first-out mode (AKA LIFO).
This is equivalent t lw6sys_list_push_front.
Return value: none.
sys_context: global system context
list: a pointer to the list (pointer on pointer, read/write value)
Pops the first element of a list, in last-in first-out mode (AKA LIFO).
This is equivalent to lw6sys_list_pop_front.
Return value: a pointer on the popped data, whatever you pushed.
sys_context: global system context
list: a pointer to the list (pointer on pointer, read/write value)
Pops data to a list, in first-in first-out mode (AKA FIFO).
This is equivalent t lw6sys_list_push_front.
Return value: none.
sys_context: global system context
list: a pointer to the list (pointer on pointer, read/write value)
Pops the first element of a list, in last-in first-out mode (AKA FIFO).
This is equivalent to lw6sys_list_pop_back.
It can be quite time-consuming on big lists.
Return value: a pointer on the popped data, whatever you pushed.
sys_context: global system context
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.
sys_context: global system context
free_func: a callback which will be called on data when freeing the list
Creates an empty reentrant list. This is different from a regular list in the sense that here the object is a holder with both a mutex and the list itself.
Return value: a pointer to the created object, may be NULL.
sys_context: global system context
list_r: the list to delete.
Delete a reentrant list, this will cascade delete all the items in the list.
Return value: none.
sys_context: global system context
list_r: the list we want informations about
Checks wether the reentrant list is empty or not. Note there’s a slight difference with basic lists, here it can’t / should not be NULL, as the list_r is really a list container.
Return value: 1 if empty, 0 if there is at list one item.
sys_context: global system context
list_r: the list we want informations about
Calculates the length of the reentrant 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).
sys_context: global system context
list_r: 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 reentrant list items.
This is a wrapper on lw6sys_list_map.
Return value: none.
sys_context: global system context
list_r: 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 reentrant list items.
Ths is a wrapper on lw6sys_list_filter.
Return value: none.
sys_context: global system context
list_r: a pointer to the list (pointer on pointer, read/write value)
data: the data to be pushed
Wapper on lw6sys_list_push_front, reentrant version.
Return value: none.
sys_context: global system context
Wrapper on lw6sys_list_pop_front, reentrant version.
Return value: a pointer on the popped data, whatever you pushed.
sys_context: global system context
list_r: a pointer to the list (pointer on pointer, read/write value)
data: the data to be pushed
Wapper on lw6sys_list_push_back, reentrant version.
Return value: none.
sys_context: global system context
Wrapper on lw6sys_list_pop_back, reentrant version.
Return value: a pointer on the popped data, whatever you pushed.
sys_context: global system context
list_r: a pointer to the list (pointer on pointer, read/write value)
data: the data to be pushed
Wapper on lw6sys_lifo_r_push_, reentrant version.
Return value: none.
sys_context: global system context
Wrapper on lw6sys_lifo_r_pop, reentrant version.
Return value: a pointer on the popped data, whatever you pushed.
sys_context: global system context
list_r: a pointer to the list (pointer on pointer, read/write value)
data: the data to be pushed
Wapper on lw6sys_fifo_r_push, reentrant version.
Return value: none.
sys_context: global system context
Wrapper on lw6sys_fifo_r_pop, reentrant version.
Return value: a pointer on the popped data, whatever you pushed.
sys_context: global system context
list_r: the reentrant list to duplicate
dup_func: the function which will be called to duplicate data
Duplicates a reentrant list.
This is a wrapper on lw6sys_list_dup, but is reentrant
and works on a list_r type.
Returned value: a newly allocated reentrant list.
sys_context: global system context
list_r: the reentrant list to transfer
Transfers the contents of a reentrant list to a regular list. Basically, this locks the list, extracts informations from it, then releases the lock and leaves the list_r empty. This is convenient in multithreaded contexts, typical pattern is a thread that pushes items, then another thread does massive transfers and processes each item separately with local pops on the regular list. This limits the amount of locking.
Returned value: a standard list, must be freed.
sys_context: global system context
list_r: the reentrant list where to put data
list: the list to get data from
Transfers the contents of a regular list to a reentrant list. Basically, this locks the list, then appends all contents from the source standard list, then releases the lock. The source list pointer is set to an empty list, if it’s NULL it means an error happened. This is convenient in multithreaded contexts, typical pattern is a thread that pushes items in a bulked mode, this has the advantage of less lock/unlock, plus the side effect of having more atomicity, one can indeed garantee that a whole packet of items are sent at once. There’s no garantee on the order, you’d better sort them afterwards if order does matter, by default the function does what is fastest/easiest to do.
Returned value: none, but check if *list is not null.
sys_context: global system context
errno_int: the error code, typically errno
Convenience fonction which returns the "macro" corresponding to an errno code. I find it easier to use this than bothering declaring a buffer for strerror_r... Besides LW6b has its own error messages. Wil never return NULL, if error does not exists just returns "?".
Return value: static string, must not be freed
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
timeout_sec: number of seconds to wait before alert dialogs disappear
By default, alert boxes will stay out forever unless one clicks on them, however, this parameter will force the dialog shutdown after some time. Mostly used for testing, to allow tests being blocked on a dialog.
Return value: 1 if timeout is supported on platform, 0 if not
sys_context: global system context
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__
func: the name of the function where this log line was called, on can use __FUNCTION__
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.
sys_context: global system context
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.
sys_context: global system context
Get the current log level.
sys_context: global system context
level: the log level, integer between 0 & 4. 4 is very verbose (debug), 0 displays errors only.
Set the current log level.
sys_context: global system context
Gets the current backtrace mode.
sys_context: global system context
backtrace_mode: the backtrace mode, LW6SYS_LOG_BACKTRACE_MODE_FULL or LW6SYS_LOG_BACKTRACE_MODE_FUNC.
Sets the current backtrace mode.
Return value : none
sys_context: global system context
Get the console output state. This is important, for instance to set the console "back in the state it was" after setting it on or off.
Return value: 1 if enabled, 0 if not.
sys_context: global system context
state: 1 to activate console output, 0 to disable it.
Enables or disables console output. By console output, we basically mean stderr (and possibly stdout). If console output is enabled (the default) all output is copied to stderr. If it’s disabled, only the log file will contain the information.
Return value: none.
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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.
sys_context: global system context
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
sys_context: global system context
lin_value: value on a linear scale
base: the base to use, 10 for decibel-like scale
Converts a linar-scale value to a logarithmic one. The scale is done so that base in linear mode is base in scaled mode, and it uses a log-base conversion, so that with a base 10 it behaves the way the decibel sound-volume unit works.
Return value: value on a logarithmic scale.
sys_context: global system context
base: the base to use, 10 for decibel-like scale
Converts a linar-scale value to a logarithmic one. The scale is done so that 10 in linear mode is 10 in scaled mode, and it uses a log-base conversion, so that with a base 10 it behaves the way the decibel sound-volume unit works.
Return value: value on a linear scale.
deg: angle in degrees
Converts an angle from degrees to radians.
Return value: angle in radians.
rad: angle in radians
Converts an angle from radians to degrees.
Return value: angle in degrees.
sys_context: global system context
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__
func: name of the caller function, use __FUNCTION__
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.
sys_context: global system context
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__
func: name of the caller function, use __FUNCTION__
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.
sys_context: global system context
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__
func: name of the caller function, use __FUNCTION__
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.
sys_context: global system context
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__
func: name of the caller function, use __FUNCTION__
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
Checks the endianess of the machine. PPC is big endian, for instance.
Return value: 1 if system is big endian, 0 if little endian.
sys_context: global system context
Checks the endianess of the machine. x86 is little endian, for instance.
Return value: 1 if system is little endian, 0 if big endian.
sys_context: global system context
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.
sys_context: global system context
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__
func: the name of the function where this log line was called, on can use __FUNCTION__
Creates a mutex object.
Return value: newly allocated pointer.
sys_context: global system context
mutex: the mutex to destroy.
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__
func: the name of the function where this log line was called, on can use __FUNCTION__
Destroys a mutex object.
Return value: none.
sys_context: global system context
mutex: the mutex to use
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__
func: the name of the function where this log line was called, on can use __FUNCTION__
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.
sys_context: global system context
mutex: the mutex to use
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__
func: the name of the function where this log line was called, on can use __FUNCTION__
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.
sys_context: global system context
mutex: the mutex to use
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__
func: the name of the function where this log line was called, on can use __FUNCTION__
Unlocks a mutex.
Return value: 1 if sucess, 0 if error.
sys_context: global system context
Returns how many mutexes have been locked since program start. Usefull for sanity checking when debugging.
Return value: number of calls to lock
Returns how many mutexes have been unlocked since program start. Usefull for sanity checking when debugging.
Return value: number of calls to unlock
sys_context: global system context
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 which returns always true, that is, something different than 0.
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.
sys_context: global system context
Wrapper on omp_get_num_procs the advantage of this is that
it’s always defined, wether OpenMP supported is compiled in
or not, will returned 1 if no OpenMP support.
Return value: number of procs
sys_context: global system context
Returns the current working directory (absolute path).
Return value: a newly allocated string.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
Returns the default prefix, could be /usr/local for instance.
Return value: a newly allocated string.
sys_context: global system context
Returns the default module directory (dynamically loaded libraries).
Return value: a newly allocated string.
sys_context: global system context
Returns the default data directory.
Return value: a newly allocated string.
sys_context: global system context
Returns the default music directory.
Return value: a newly allocated string.
sys_context: global system context
Returns the default music path, which can be composed of several directories.
Return value: a newly allocated string.
sys_context: global system context
Returns the default map directory.
Return value: a newly allocated string.
sys_context: global system context
Returns the default map path, which can be composed of several directories.
Return value: a newly allocated string.
sys_context: global system context
Returns the default script file.
Return value: a newly allocated string.
sys_context: global system context
Logs all default values to log file. Usefull for debugging, to know where the program is searching for its informations.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
dirname: the directory to test
Tests the existence of a directory on the filesystem, will also validate that it contains a README or readme.txt file.
Return value: 1 if OK, 0 if directory doesn’t exist.
sys_context: global system context
dirname: the directory to test
needle: string to search, can be NULL
Tests the existence of a directory on the filesystem, with a README or readme.txt file, which contains the string needle.
Return value: 1 if OK, 0 if directory doesn’t exist.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
path: a path
Returns the file name only, without heading directories.
Return value: file name, must be freed
sys_context: global system context
path: a path
Checks wether a path is relative or absolute.
Return value: 1 if relative, 0 if absolute.
sys_context: global system context
path: a path
Checks wether a path is "." or not. Will also trap "" and "./".
Return value: 1 if relative, 0 if absolute.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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).
sys_context: global system context
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).
sys_context: global system context
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.
sys_context: global system context
f: file to output content to
Prints a standard Liquid War compliant XML header in the given file.
Return value: none.
sys_context: global system context
f: file to output content to
Prints a standard Liquid War 6 compliant XML footer in the given file.
Return value: none.
sys_context: global system context
Tells wether functions related to fork and pids are likely to work allright or not. Typically, those functions will return false (0) systematically if called on a platform that does not support them fully. In practice this is only for a few tests, so it’s not that bad if it does not really work. Would be better if, but well, it’s OK.
Return value: 1 if supported, 0 if not.
sys_context: global system context
data: pointer on arbitrary data used by func
This is not a standard fork function, it will return to the caller (parent) with something >0 if a child has been created, or 0 if failed. On the child it will launch the callback func, run it and exit right away.
Return value: a process ID on success, 0 on failure.
sys_context: global system context
pid: pid to kill
Kills a process with the given PID. The kill will first use a signal 1 SIGTERM the a signal 9 SIGKILL. This is mostly for testing, the idea is to be sure to vaccum after we’re done. We use 64-bit for PIDs, yes, they are very likely 32 only, but had to choose (and pid_t is a pain because for logging one would needed to check the length before calling printf like functions...).
Return value: 1 on success, 0 if failed
sys_context: global system context
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
sys_context: global system context
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, does not touch the value.
Return value: none.
sys_context: global system context
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. This function won’t touch the value, one needs to call begin or update or end to do that.
Return value: none.
sys_context: global system context
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.
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
progress: the progress to update
Sets the progress to its min value, NULL values correctly handled.
Return value: none
sys_context: global system context
progress: the progress to update
Sets the progress to the average between min and max, NULL values correctly handled.
Return value: none
sys_context: global system context
progress: the progress to update
Sets the progress to its max value, NULL values correctly handled.
Return value: none
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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. Note that this function uses the global system context,
and can therefore be buggy when used in multithreaded / reentrant
mode. So in some cases, that is, with two different contexts, SDL
could be called twice. This is a limitation of current SDL implementations,
should it have a per-thread / per-handler context, the problem would
be solved. Fundamentally, the idea is that SDL does have a global static
state, you’ve been warned.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
shape: the dimensions to control
min: the minimum shape allowed
max: the maximum shape allowed
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.
sys_context: global system context
shape: the boundary box
pos: the position
Checks wether position is within the given boundary box.
Return value: 1 if OK, 0 if not.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
shape: the shape to query
Gives the volume (w * h * d) for a given shape.
Return value: the volume.
sys_context: global system context
shape: the shape to query
Gives the surface (w * h) for a given shape.
Return value: the surface.
sys_context: global system context
trap_errors: set to 1 if you want to trap SIGSEGV and SIGFPE
Set up our signal handlers. This will probably be overrided
later by other libs such as libSDL, but at least in pure server
mode it gives a way to treat SIGTERM the right way.
The callbacks will use the sys_context passed here, ignoring
whatever thread and/or whatever value for this context was used
when the error was detected. However, one needs at least one
context, for instance to log messages.
Return value: none.
sys_context: global system context
Restore default signal handlers for those modified by lw6sys_signal_custom.
Return value: none.
signum: SIGTERM
The own TERM signal handler, will basically call
the lw6sys_signal_send_quit function, which will
set a flag used later by lw6sys_signal_poll_quit.
Return value: none.
signum: SIGINT
The own INT signal handler, will basically call
the lw6sys_signal_send_quit function, which will
set a flag used later by lw6sys_signal_poll_quit.
Return value: none.
signum: SIGTERM
The own HUP signal handler, will basically do something that shows the program is alive, typically display a NOTICE message.
Return value: none.
signum: SIGTERM
The own SEGV signal handler, will display a backtrace and exit.
Return value: none.
signum: SIGTERM
The own FPE signal handler, will display a backtrace and exit.
Return value: none.
sys_context: global system context
Sets the quit flag to 1, so that lw6sys_signal_poll_quit returns
true, that is, tells the polling loop to stop.
Return value: none.
sys_context: global system context
Tests wether we need to stop right now.
Return value: 1 if we need to stop now, 0 if program can continue.
sys_context: global system context
func_data: function specific data
ptr_a: pointer to an int item
ptr_b: pointer to an int item
A typicall sort callback function, can be passed to lw6sys_sort
to sort a list of integers.
Return value: -1 if ptr_a < ptr_b , 0 if ptr_a == ptr_b,
1 if ptr_a > ptr_b
sys_context: global system context
func_data: function specific data
ptr_a: pointer to an int item
ptr_b: pointer to an 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 ptr_a < ptr_b , 0 if ptr_a == ptr_b,
-1 if ptr_a > ptr_b
sys_context: global system context
func_data: function specific data
ptr_a: pointer to a float item
ptr_b: pointer to a 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 ptr_a < ptr_b , 0 if ptr_a == ptr_b,
1 if ptr_a > ptr_b
sys_context: global system context
func_data: function specific data
ptr_a: pointer to a float item
ptr_b: pointer to a 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 ptr_a < ptr_b , 0 if ptr_a == ptr_b,
-1 if ptr_a > ptr_b
sys_context: global system context
func_data: function specific data
ptr_a: pointer to a string item
ptr_b: pointer to a 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 ptr_a < ptr_b , 0 if ptr_a == ptr_b,
1 if ptr_a > ptr_b
sys_context: global system context
func_data: function specific data
ptr_a: pointer to a string item
ptr_b: pointer to a 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 ptr_a < ptr_b , 0 if ptr_a == ptr_b,
-1 if ptr_a > ptr_b
sys_context: global system context
list: the list to sort, might be modified by the function
sort_func: the callback function used to sort
func_data: function specific data
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.
sys_context: global system context
Creates a spinlock object.
Return value: newly allocated pointer.
sys_context: global system context
spinlock: the spinlock to destroy.
Destroys a spinlock object.
Return value: none.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
spinlock: the spinlock to use
Unlocks a spinlock.
Return value: 1 if sucess, 0 if error.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
buf: a buffer of len+1 chars
len: the max length of string
fmt: a format string, like the one you would pass to printf
...: optional arguments, like the ones you would pass to printf
Almost like snprintf except that it will *always* append a char 0 (’\0’) at the end of the string. Therefore buf must be of size len+1.
Return value: 1 if success, 0 if failed.
sys_context: global system context
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.
sys_context: global system context
str: the string to test
Tests wether a string is NULL or empty (string with 0 chars "").
Return value: 1 if NULL or empty, 0 if contains something.
sys_context: global system context
str: the string to test
Returns always a non-NULL string, if string is NULL, returns ""
The argument str is not passed as const else this function
would equate to a disguised cast from const to non-const.
Return value: source string or "" if it was NULL
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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.
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
str: a pointer to the string we want to modify
Reformats a string, that is, insert newline characters in the
right places to that it fits in a given number of columns.
This function will modify the buffer so str must be writeable.
Will not handle strings which already contain newline
characters perfectly.
Return value: none
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
list: list of strings to join
glue: string to add in-between
Companion function of lw6sys_str_split which will do
the contrary and join the string. Here we use a string
as the glue/separator, more flexible than a simple char
in this case.
Return value: dynamically allocated string
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
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
sys_context: global system context
str: the string to truncate
len: the new length
middle: the string to add in the middle
Truncates a string to the max given length, by truncating the middle of the string, and putting the string middle at this place. Calling it with "abcdefghijk",5,"X" will give "abXjk".
Return value: none, str pointed data modified in-place
sys_context: global system context
len: the length of the random string to generate.
Generates a random string, this is usefull for testing.
Return value: newly allocated string
sys_context: global system context
len: the length of the random string to generate.
Generates a random string, this is usefull for testing. This version only generates words with alpha-numerical content (letters and digits plus spaces).
Return value: newly allocated string
sys_context: global system context
len: the length of the random string to generate.
Generates a random string, this is usefull for testing. This version generates on single word with alpha-numerical content (letters and digits but no spaces).
Return value: newly allocated string
sys_context: global system context
buf: the buffer to test
len: the length of the buffer
Tests wether a buffer is likely to contain a string. This is not a bulletproof function, just a simple heuristic based estimator.
Return value: 1 if probably binary, 0 if probably text
sys_context: global system context
f: file to get input from, typically stdin
Will read file/stream and return it as a string. This is not
for serious stream operation since it will return only when
stream is closed, and read all file into memory before doing anything.
It’s also limited in size since it uses a fixed length buffer,
so this is just for quick testing, typically used by command line switches
which are used to test encoding/decoding functions. Do not use it
to read a filesystem file, lw6sys_read_file_content is much better.
Return value: newly allocated string.
sys_context: global system context
f: file to receive the string
str: the string to output
Here only for API consistency, will just put string to file (just a simple fprint).
Return value: none.
test_and_set: pointer to the value used to test and set
Low level function which performs an atomic exchange to implement a spinlock. This one is just a wrapper to help debugging asm calls.
Return value: 1 when lock is acquired.
test_and_set: pointer to the value used to test and set
Low level function which performs an atomic exchange to implement a spinlock. This one is just a wrapper to help debugging asm calls.
Return value: 1 when lock is acquired.
sys_context: global system context
mode: test mode (bitmask)
Registers all tests for the libsys module.
Return value: 1 if test is successfull, 0 on error.
sys_context: global system context
mode: test mode (bitmask)
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.
sys_context: global system context
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 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... Moreover, it should be
run at the beginning of the program, running it afterwards could
give unpredictable results. So it’s safer to use it outside the
CUnit standard mechanisms.
Return value: 1 if test is successfull, 0 on error.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
thread_handler: thread to work on
Waits until the callback of the thread is done, this does not necessarly mean it’s freed, in fact it’s not at this stage, the join callback can still be yet to call, but at least the main stuff is done.
Return value: 1 if done, 0 on error
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
Utility function used to check how many threads where created and joined.
Return value: how many threads were created.
sys_context: global system context
Utility function used to check how many threads where created and joined.
Return value: how many threads were joined.
sys_context: global system context
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...).
sys_context: global system context
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.
sys_context: global system context
Returns the number of milliseconds since program was started. Milliseconds are often referred to as ’ticks’.
Return value: the number of milliseconds (64-bit)
sys_context: global system context
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.
sys_context: global system context
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).
sys_context: global system context
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.
sys_context: global system context
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 usleep or 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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
Global initializations required to handle time properly.
sys_context: global system context
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.
sys_context: global system context
Gives the date in a format which is compatible with Apache CLF Common Log Format.
Return value: newly allocated string.
sys_context: global system context
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
sys_context: global system context
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.
sys_context: global system context
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
sys_context: global system context
url: the url struct to free
Frees a URL struct and all its members.
Return value: none.
sys_context: global system context
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.
sys_context: global system context
url: the URL to check
Checks wether an URL is in its canonized form.
Return value: 1 if OK (canonized form), 0 if not
sys_context: global system context
version_a: 1st version to compare
version_b: 2nd version to compare
Compares two versions and tells wether they are compatible or not. Actually, it only checks that MAJOR.MINOR is the same in both cases. As a side not, it’s not case sensitive. In most LW6 relevant cases, it’s a moot issue since MAJOR.MINOR is a number, but well, just in case.
Return value: 1 if compatible, 0 if not
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
sys_context: global system context
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.
Assoc is a basic key/pair structure where key is a string. Use it for basic associations, it’s not fast when there are many keys, in that case, prefer a hash.
Type: char *
Definition: char* lw6sys_assoc_s::key
The key, a 0 terminated standard C string.
Type: void *
Definition: void* lw6sys_assoc_s::value
The value, pointer to arbitrary data.
Type: lw6sys_free_func_t
Definition: lw6sys_free_func_t lw6sys_assoc_s::free_func
This function will be called whenever the element is deleted. You can set it to NULL in that case no callback will be called on deletion.
Type: lw6sys_assoc_p
Definition: lw6sys_assoc_p lw6sys_assoc_s::next_item
Pointer on the next item, will be NULL on last element, there’s a difference between a NULL pointer and a valid assoc with only one item being EOL.
Cache item is the object used to hold data within hash, to implement cache features. It basically stores a pointer to the actual data, and a timestamp which marks the expiration time. In practice, a cache is just an hash which contains this kind of data.
Type: int64_t
Definition: int64_t lw6sys_cache_item_s::expiration_timestamp
Expiration time, after this time, key is considered invalid.
Type: lw6sys_free_func_t
Definition: lw6sys_free_func_t lw6sys_cache_item_s::real_free_func
OK, now this requires some explanation : to use standard hash / assoc function we need the cache hash to behave like a real hash. So the trick is to store within the data structure the pointer on the real free callback. This way the special cache_free callback will have a way to call the genuine free function before destroying the cache container. This duplicates the pointer, but avoids code duplication. In practice caches shouldn’t be that big anyway, so it won’t eat up all your memory anyway.
Type: void *
Definition: void* lw6sys_cache_item_s::value
The actual value.
Cache is an object based on which works pretty much the same but adds the possiblity to give an expiration time to a key. Any key with an expiration time in the past will be removed on query and appear as non-existing to callers.
Type: int
Definition: int lw6sys_cache_s::delay_msec
Delay in milliseconds before a key expires.
Type: lw6sys_free_func_t
Definition: lw6sys_free_func_t lw6sys_cache_s::real_free_func
The real free_func to call on objects.
Type: lw6sys_hash_t *
Definition: lw6sys_hash_t* lw6sys_cache_s::data
The actual data.
Used to store colors when representing them in RGBA mode with integers ranging from 0 to 255.
Type: u_int8_t
Definition: u_int8_t lw6sys_color_8_s::r
Red [0 ... 255].
Type: u_int8_t
Definition: u_int8_t lw6sys_color_8_s::g
Green [0 ... 255].
Type: u_int8_t
Definition: u_int8_t lw6sys_color_8_s::b
Blue [0 ... 255].
Type: u_int8_t
Definition: u_int8_t lw6sys_color_8_s::a
Alpha [0 ... 255]. 255 is opaque, 0 is transparent.
Used to store colors when representing them in RGBA mode with floats ranging from 0.0f to 1.0f.
Type: float
Definition: float lw6sys_color_f_s::r
Red [0 ... 1.0f].
Type: float
Definition: float lw6sys_color_f_s::g
Green [0 ... 1.0f].
Type: float
Definition: float lw6sys_color_f_s::b
Blue [0 ... 1.0f].
Type: float
Definition: float lw6sys_color_f_s::a
Alpha [0 ... 1.0f]. 1.0f is opaque, 0.0f is transparent.
Used to store colors when representing them in HSV mode with floats ranging from 0.0f to 1.0f. An alpha channel has been added so this is more HSVA than HSV.
Type: float
Definition: float lw6sys_color_hsv_s::h
Hue [0 ... 360.0f]. 0.0f is red, 120.0f is green, 240.0f is blue.
Type: float
Definition: float lw6sys_color_hsv_s::s
Saturation [0 ... 1.0f].
Type: float
Definition: float lw6sys_color_hsv_s::v
Value [0 ... 1.0f].
Type: float
Definition: float lw6sys_color_hsv_s::a
Alpha [0 ... 1.0f]. 1.0f is opaque, 0.0f is transparent.
Global context, used by pretty much any function, this is used to avoid storing global static variables, and allow all code to be used in a multithreaded context. In practice some libraries the program relies on might still use globals but at least the limitation is not induced by Liquid War 6 itself. Note that this structure is a wrapper over the internal structure which contains the real members, the first two members need be the same as it is casted internally.
Type: u_int32_t
Definition: u_int32_t lw6sys_context_s::id
The id of the object, this is non-zero and unique within one run session, incremented at each object creation.
Hash is a basic hash structure, relying on assoc for implementation. Actually, what it does is storing an array of assoc, the number of assoc elements is given at construction. Then when accessing a member, a quick checksum is made from the key, which enables finding out which assoc must be queried. If the hash is properly sized, then once one has found the right assoc, finding the right key is fast, since there are only a few of them in each assoc, and it avoids scanning for for all keys, which is the very purpose of the hash.
Type: int
Definition: int lw6sys_hash_s::size
Number of assoc used for this hash, passed at construction.
Type: lw6sys_assoc_t **
Definition: lw6sys_assoc_t** lw6sys_hash_s::entries
Array of assoc holding the actual data.
Type: lw6sys_free_func_t
Definition: lw6sys_free_func_t lw6sys_hash_s::free_func
This function will be called whenever the element is deleted. You can set it to NULL in that case no callback will be called on deletion.
The hexa (for hexadecimal) serializer is a tool used to simplify serialization processes, you can just push/pop basic data types on it, it will concatenate the string, allocate memory, do all this dirty stuff without requiring you to plan the size of the buffer, among other things.
Type: char *
Definition: char* lw6sys_hexa_serializer_s::buf
Data buffer.
Type: int
Definition: int lw6sys_hexa_serializer_s::buf_size
Size of data buffer, in bytes.
Type: int
Definition: int lw6sys_hexa_serializer_s::pos
Current position within the buffer, this is, typically, the place where data will be appended at the next push call, or where it will be fetched from at the next pop call.
List_r is a list system based on list plus a mutex that ensures you can safely call functions on it, without worrying about concurrency. All functions with list_r_ in in their name do lock the list_r before using it, and release it afterwards. Else, the API is pretty much the same, except some functions that take a ** with a list take a simple * with a list_r.
Type: lw6sys_mutex_t *
Definition: lw6sys_mutex_t* lw6sys_list_r_s::mutex
Mutex used to avoid multiple accesses. Locked / unlocked on each member function call except new and free.
Type: lw6sys_list_t *
Definition: lw6sys_list_t* lw6sys_list_r_s::list
List containing the data. Basically, the list_r is just a wrapper on this, bundled with the mutex.
Type: lw6sys_free_func_t
Definition: lw6sys_free_func_t lw6sys_list_r_s::free_func
This function will be called whenever the element is deleted. You can set it to NULL in that case no callback will be called on deletion.
List is a basic list system, with a void * pointer to hold arbitrary data and a callback function for deletion. Provides basic functions to push, pop, walk, any array-like call will of course be very slow. As of current implementation, front operations are fast, but back operations are slow.
Type: void *
Definition: void* lw6sys_list_s::data
Opaque pointer on element data.
Type: lw6sys_free_func_t
Definition: lw6sys_free_func_t lw6sys_list_s::free_func
This function will be called whenever the element is deleted. You can set it to NULL in that case no callback will be called on deletion.
Type: lw6sys_list_p
Definition: lw6sys_list_p lw6sys_list_s::next_item
Pointer on the next item, will be NULL on last element, there’s a difference between a NULL pointer and a valid list with only one item being EOL. Other way to state it: NULL and empty list are two different things.
Structure used to store informations about a module. This describes the module, its author license, this is both a legal check and a technical check, to maximize the chances the code we’re running is the right one, and to trace it.
Type: char *
Definition: char* lw6sys_module_pedigree_s::id
Module id, for instance, could be "gl1".
Type: char *
Definition: char* lw6sys_module_pedigree_s::category
Module category, for instance, could be "gfx".
Type: char *
Definition: char* lw6sys_module_pedigree_s::name
Module name, readable (displayable) name.
Type: char *
Definition: char* lw6sys_module_pedigree_s::readme
Module readme text.
Type: char *
Definition: char* lw6sys_module_pedigree_s::version
Module version.
Type: char *
Definition: char* lw6sys_module_pedigree_s::copyright
Module (short) copyright information.
Type: char *
Definition: char* lw6sys_module_pedigree_s::license
Module (short) license.
Type: char *
Definition: char* lw6sys_module_pedigree_s::date
Date of module compilation.
Type: char *
Definition: char* lw6sys_module_pedigree_s::time
Time of module compilation.
Mutex is our own wrapper on the pthread mutex object. Why not use the pthread mutex directly? For debugging, this allows us to place and instrument hooks if needed.
Type: u_int32_t
Definition: u_int32_t lw6sys_mutex_s::id
The id of the object, this is non-zero and unique within one run session, incremented at each object creation.
Structure used to store progress information. The idea is that is that must be usable in polling mode or in multithreaded mode, and we must be able to truncate a progress indicator into several stages. So this structure contains a range start, a range end, and its value between those two, which is meant to be written by the code executing the operation and read by the caller/rendering thread.
Type: float
Definition: float lw6sys_progress_s::min
Where the progress operation starts.
Type: float
Definition: float lw6sys_progress_s::max
Where the progress operation ends.
Type: float *
Definition: volatile float* lw6sys_progress_s::value
Somewhere between min and max.
Spinlock is our own wrapper on a spinlock based mutex. Why not use the pthread spinlock directly? For debugging, this allows us to place and instrument hooks if needed. Additionnally, some implementations of pthread do not provide spinlock and in that case we provide our own alternative.
Type: u_int32_t
Definition: u_int32_t lw6sys_spinlock_s::id
The id of the object, this is non-zero and unique within one run session, incremented at each object creation.
Thread handler is our own wrapper on the pthread object. Why not use the pthread handler directly? Basically to store basic flags and context data (void * pointer on our thread data for instance) along with the handler. This is merely for debugging and convenience. Internally this will be casted to _lw6sys_thread_handler_t.
Type: u_int32_t
Definition: u_int32_t lw6sys_thread_handler_s::id
The id of the object, this is non-zero and unique within one run session, incremented at each object creation.
Describes an URL, with its elements splitted, this is just to be able to use half-parsed URLs and avoid redoing this parsing everytime.
Type: int
Definition: int lw6sys_url_s::use_ssl
1 if in https, 0 if in http.
Type: char *
Definition: char* lw6sys_url_s::host
Host name.
Type: int
Definition: int lw6sys_url_s::port
IP port.
Type: char *
Definition: char* lw6sys_url_s::uri
URI, that is, everything after the port.
Contains the shape of a 3D box. There are 3 differences with its "XYZ" equivalent. First, sometimes w*h*d reads better than x,y,z. Then, xyz is signed, whd is unsigned. Finally, these are real int32 values, they are not 14-bit limited. It does not really cost any memory for it’s usually used as a single "shape" attribute for a whole map. At the same time, it’s very often used as a test value in loops, so it’s interesting to have it in a value that’s easy to optimize for the compiler (exactly one register...)
Type: u_int32_t
Definition: u_int32_t lw6sys_whd_s::w
Width.
Type: u_int32_t
Definition: u_int32_t lw6sys_whd_s::h
Height.
Type: u_int32_t
Definition: u_int32_t lw6sys_whd_s::d
Depth.
All-in 32 bit 3D position, to save memory.It’s a deliberate choice in Liquid War to handle "limited size" levels. In fact 14 bits still allows 8000x8000 maps, which are at least 100 times too slow to play now (2008). Should we follow Moore’s law we’d have at least 6 years until those are playable, and well, until then, let’s wait. The point is that storing this information (x*y) on 4 bytes might be very important in some cases, since it can reduce memory footprint on structs which are stored in numerous quantities, and therefore maximize chances that we use level 1 & 2 caches and other nice things which happen when memory consumption is not too high.Point is: why use INT32 and then limit it to 14 bits instead of using an INT16 or short in the first place? Answer: it’s easier to handle INT32 all the time in the rest of the code. Compiler and CPU might even handle that better than short. Then, and only when data will be read/written in the struct will it be truncated. Typical example is: we want to multiplicate y by w (which is a width). Result is beyond INT16/short scope but we want to handle it! Casting everything to INT32/int is a pain. With this int y:14 trick, we use y as a "full-featured" INT32/int and well, when it will be read/written we’ll loose values over 8191, but we simply do not care.
Type: int32_t
Definition: int32_t lw6sys_xyz_s::x
X position, from -8192 to +8191.
Type: int32_t
Definition: int32_t lw6sys_xyz_s::y
Y position, from -8192 to +8191.
Type: int32_t
Definition: int32_t lw6sys_xyz_s::z
Z position, from -8 to +7.