The Common C library

by Denis BEURIVE

Introduction
Developper's documentation
How to compile the libraries ?
Libraries description

Introduction

This document describes the "Common C library". This library contains tools for:

String manipulation.
File manipulation.
Date manipulation.
SHA signature.
Simple directory management.
Simple signal management.

These tools have been tested, so you should use them instead of re-write them.

If you need to modify the source code of the libraries above-mentioned, please consult the following URL:

Developper's documentation

The previous URL points to an in depth documentation of the source codes.

For each function, you have:
- A description that tells you what the function actually does.
- The list of input parameters (with explanations and warnings).
- The meaning of the returned value(s) (if any).
- If necessary, a quick note that tells you how to use the function (you may need to free allocated memory for example).
- A simple exemple code to show you how to use the function.
For each macro, you have a quick explanation.
For each C structure, you have a quick description of each field.
For each global variable, you have:
- A quick description of the variable.
- An explanation that tells you why this variable must be global. The use of global variables should be forbidden, but in some cases you have no choice. It is the case if you use flex. We can ask flex to create C++ parsers (instead of C parsers). In this case you don't have to use global variables ... but this implies that you use C++ instead of C.

Please note that this library also contains sample codes that illustrates some basic features of the OS. Currently you can get:

A simple example that shows how to use pthreads (examples/threads/threads.c)
A simple example that shows how to use messages queue examples/IPCs/messsage_queue.c)

How to compile the libraries ?

This should be pretty simple. All you need to do is:

Edit the Makefile and set the variables "MAKE_TARGET" and "BUILD_TARGET" according to your system (SUN or LINUX).
Type "make clean".
Type "make all": This will build the libraries and the test programs.

Libraries description

String manipulation

This library contains functions used to manipulate strings of characters. To use this library in your code:

Includes the file "strings_utils.h".
Link your code with the file "libmy_strings.a" (-lmy_strings).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
make_one_line	This function takes a given string and replace all series of spaces by one space and all series of new lines by one new line.
s_split	Split a string. After you call s_split() you must call free_fields(). If you split "A;;;B;" using the character ";" as delimitor, then you get 2 and only 2 fields ("A" and "B").
s_split_exact	Split a string. After you call s_split() you must call free_fields(). If you split "A;;;B;" using the character ";" as delimitor, then you get 4 fields (with 2 empty fields).
free_fields	Free all memory that has been allocated within s_split().
get_end_of_string	Extract everything between the character '=' and the end of a string.
IP2hex	Convert a IP address into its hexadecimal representation.
post_chop	Delete spaces (or tabulations) at the end of a string.
pre_chop	Delete spaces (or tabulations) at the begining of a string.
chop	Delete spaces (or tabulations) at the begining and at the end of a string.
add_comment	Replace all charater 'new line' (that is '\n'), by the sequence '\n#'.
get_config_value	Extract a field's value from a configuration file (you specify a field delimitor such as ':').
replace_tag_by_integer	Replace a tag by an integer (you specify the tag to replace).
string2unsigned_int	Convert a string of characters into an 'unsigned int'.
string2int	Convert a string of characters into an 'int'.
is_integer	Test if a string of characters represents an interger.
is_ip_address	Test if a string of characters represents an IP address.
is_hexa	Test if a string of characters represents an hexadecimal value;
ip_address_to_num	Convert an IPV4 address into its numerical representation (for example 123.45.67.8 becomes four integers: 123, 45, 67 and 8).

Dynamic string manipulation

This library contains functions used to handle dynamic strings. By dynamic, we mean "dynamic memory management":. You can add characters to the string without thinking about memory management. To use this library in your code:

Includes the file "dstring.h".
Link your code with the files "libmy_dstring.a" (-lmy_dstring).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
dstring_init	Initialize a dynamic string. This function must be called first.
dstring_free	Free all memory allocated for a dynamic string.
dstring_add	Add characters (or bytes) to a dynamic string.
dstring_get_data	Extract data from a dynamic string.

Search / Replace API

This library contains functions used to replace tags by their values in a text. To use this library in your code:

Includes the file "replacer.h".
Link your code with the files "libfl.a", "libmy_replace.a", "libmy_dstring.a", "libmy_list.a", "libmy_hash_table.a" (-lfl -lmy_replace -lmy_dstring -lmy_list -lmy_hash_table).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function

Description

replace_tags

This function takes 4 arguments:

A text that contains tags that will be replaced by their values.
A list of tags (the function will search the tags in the text).
A list of values (tags will be replaced by their values).
the number of tags to search.

It will replace all the given tags by their values in the text.

Please note that this function is NOT REENTRANT (because it uses a flex parser) and it works in memory.

Example:

You define 3 tags:

TAG1
TAG2
TAG3

And their values:

TAG1=toto1
TAG2=toto2
TAG3=toto3

Now, assuming that you have the following text:

Test of ${TAG1}, ${TAG2} and ${TAG3} but not ${TAGN}

Then you get:

Test of toto1, toto2 and toto3 but not ${TAGN}

File manipulation

This library contains functions used to manipulate files. To use this library in your code:

Includes the file "files.h".
Link your code with the file "libmy_files.a" (-lmy_files).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
wait_for_file	Wait for a file to appear (it is possible to specify a stop file).
wait_for_multiple_file	Wait for a file (within a list of files) to appear (it is possible to specify a stop file).
read_file	Load the content of a file into memory.
set_timeout_file	Create a timeout file. This file contains the current number of seconds since Januray 1 1970 00:00:00. This function should be used with test_timeout_file().
test_timeout_file	Test if the time shift between the time value stored in a timeout file and the current time value is greater than a given value (called the timeout). This functon should be used with set_timeout_file().
basename	Get the base name of a file (remove all the directory path).

Date manipulation

This library contains functions used to manipulate dates. To use this library in your code:

Includes the file "date.h".
Link your code with the files "libmy_dates.a" and "libmy_strings.a" (-lmy_dates -lmy_strings).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
set_local_TZ_to_GMT	This function sets the local time zone to UTC. You should call this function before using any of the following library's functions.
load_timezones	Load time zones configuration file. You must do that before you can use the library.
tzcmp	Compare 2 timezone structures. You should not have to use this function.
tzfound	Find a time zone data structure in the time zone configuration file. You should not have to use this function.
get_day	Returns the index of the day (starting at 0, so the returned value is between 0 and 6). The first day (index 0) is 'Sunday'. You should not have to use this function.
get_month	Returns the index of the month (starting at 0, so the returned value is between 0 and 11). The first month (index 0) is 'january'. You should not have to use this function.
date2timestamp	Calculate the timestamp of a date (The number of seconds since the first of January 1970). The date must look something like "Tue Aug 28 01:02:24 MET DST 2001". The time zone and daylight saving tags must appear in the time zones configuration file.
test_tz_conf	Check that the configuration found in the time zones configuration file is correct. To do that you specify an external configuration file that contains well know couples (date, timestamps). The functions will calculate the timestamp associated with each date and it will compare it with the well known timestamps. If the time zones configuration appears to be wrong, this function can find the correct configuration.
print_tz_conf	Returns a zero terminated string of characters that represents that time zone configuration loaded from the time zone configuration file.
get_utc_timestamp	Returns the number of seconds since 00:00:00 UTC, January 1, 1970. Please note that this is equivalent to the C function "time", but the name is better.
dater()	Return the current date as Apache's standard (for example "2002-09-12 20:20:18").
get_tsm_date()	Return a TSM formated date from a given timestamp. For example: Timestamp = 1032256652 => "Tue Sep 17 11:57:32 MET 2002"

The basic way to initialize this library is:

Set the global variable time_shift to AUTOMATIC_TIME_SHIFT_COMPUTATION.
Call set_local_TZ_to_GMT() in order to set the process's local time configuration to UTC.
Call load_timezones() in order to load the time zone configuration file.
Call test_tz_conf() if you need to check your time zone configuration.

Then you can call date2timestamp().

The 2 configuration file for the library are:

The Time Zone configuration file (used by load_timezones()).
The Timestamps reference file (used by test_tz_conf()).

The Time Zone configuration file contains information used by the program to calculate the timestamp (the number of seconds since 00:00:00 UTC, January 1, 1970). This file contains a set of timezone tags with their associated time shift from UTC (Please note that "UTC" and "GMT" is the same thing). The syntax is pretty simple. Each time zone is described by a single line:

<Time Zone's abbreviation>   [<Daylight Saving Tag>]   <Time Shift>

The following example shows a valid Time Zone configuration file:

MET    DST     -7200
MET            -3600
MET    SDT     -3600

This means that:

"UTC" = "MET DST" - 7200 (the represents the french summer time).
"UTC" = "MET"     - 3600 (the represents the french winter time).
"UTC" = "MET SDT" - 3600 (the represents the french winter time).

Please note that you can add as many time zone description as you want.

The Timestamps reference file is a set of couple <date> = <number>. For feach date you give the well known timestamp. This file is used when the program starts: it will check that its time zone configuration file is correct. The syntax of this file is pretty simple. Each timestamp is described by a single line:

<date> = <well known timestamp>

The following example shows a valid timestamp reference file configuration file:

# Summer time

Tue Aug 28 01:53:35 MET DST 2001 = 998956415
Tue Aug 28 03:53:35 MET DST 2001 = 998963615

# Winter time

Sat Dec 1  16:42:47 MET 2001     = 1007221367
Sat Dec 1  16:42:47 MET SDT 2001 = 1007221367

Please note that the time zone tags used in the date (here quot;MET DST", "MET" and "MET SDT") must appear in the valid Time Zone configuration file.

SHA signature

This library contains functions used to compute SHA signatures. To use this library in your code:

Includes the file "sha.h".
Link your code with the file "libmy_sha.a" (-lmy_sha).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
shahash_r	Calculate the SHA signature of a string.

Directory manipulation

This library contains functions used to manipulate directories. To use this library in your code:

Includes the file "my_dir.h".
Link your code with the file "libmy_dir.a" (-lmy_dir).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
read_directory	List all the entries of a given directory. After you called read_directory(), you must call free_file_list().
read_directory_only	List all sub-directories within a given directory (this is equivalent to read_directory(), except that it lists only the sub-directories.
free_file_list	After you called read_directory(), you must call free_file_list() in order to free the allocated memory.
base_dir_name	Given a file name, this function returns the directory path.

Simple signals manipulation

This library contains functions used to manipulate signals. To use this library in your code:

Includes the file "signals.h".
Link your code with the file "libmy_signals.a" (-lmy_signals).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
set_signal	Initialize the library (tells the library which signal you want to handle). You must call this function before any other library's functions.
block_all_signal	Block the signal.
retore_signal	Unblock the signal.
get_pending_signals	Check if there is a pending signal.
set_signal_handler	Set the signal handler.

File locking management

This library contains functions used to manipulate signals. To use this library in your code:

Includes the file "flock.h".
Link your code with the file "libmy_files.a" (-lmy_files).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
lock_file	Lock a file (given an integer as file descriptor).
unlock_file	Unlock a file (given an integer as file descriptor).
my_logger	Write data into the log file (the log file is locked).
append_file_with_lock	Append a file to another - The destination file is locked.

Timing functions (micro seconds)

This library contains functions used to measure elapsed time between two events. The result is given in mili seconds. To use this library in your code:

Includes the file "timing.h".
Link your code with the file "libmy_timing.a" (-lmy_timing).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
start_chrono	Start the stopwatch.
stop_chrono	Stop the stopwatch.
get_ms	Get the measured time in mili seconds.
set_one_shot_timer	Create a one shot timer (that raises SIGALRM) with micro seconds precision.
cancel_one_shot_timer	Cancel a one shot timer (previously created using set_one_shot_timer()).
pause_one_shot_timer	Stop the one shot timer, but keep the remaining time so you can restart the timer later (using restart_one_shot_timer()).
restart_one_shot_timer	Restart a previously stoped one shot timer (the timer must have been stoped using pause_one_shot_timer()).

Important remark: The one shot timer raises the signal SIGALRM. Keep in mind that the signal can be raised anytime. This means that you may have to mask/unmask the signal SIGALRM. Dealing with signals is not an easy task.

cgi toolkit

This library contains functions used to call or implement CGIs. To use this library in your code:

Includes the file "cgi.h".
Link your code with the file "libmy_cgi.a" (-lmy_cgi).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
url_escape	URL encode a string.
url_unescape	URL decode a string.
get_domain	Given an email address "login@domain", the function extracts the login and the domain.

Hashing toolkit

This library contains functions used to perform hashing operations on a string of characters. To use this library in your code:

Includes the file "hashfunc.h".
Link your code with the file "libmy_hashfunctions.a" (-lmy_hashfunctions).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
Hash1	Return an 'unsigned int' calculated from a string of characters.
Hash2	Return an 'unsigned int' calculated from a string of characters.
Hash3	Return an 'unsigned int' calculated from a string of characters.

Bits manipulation

This library contains functions used to perform basic bits manipulation. To use this library in your code:

Includes the file "bitmanip.h".
Link your code with the file "libmy_bitmanip.a" (-lmy_bitmanip).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
swap_short_2	Swap a 2 byte signed integer.
swap_u_short_2	Swap a 2 byte unsigned integer.
swap_int_4	Swap a 4 byte signed integer.
swap_u_int_4	Swap a 4 byte unsigned integer.
swap_long_4	Swap a 4 byte signed long integer
swap_u_long_4	Swap a 4 byte unsigned long integer.
swap_float_4	Swap a 4 byte floating point number.
swap_double_8	Swap a 8 byte double number.

TCP/IP connections

This library contains functions used to perform basic TCP/IP functionalities (using sockets). To use this library in your code:

Includes the file "my_sockets.h".
Link your code with the files "libmy_sockets.a", "libmy_signals.a" and "libmy_timing.a" (-lmy_sockets, -lmy_signals, -lmy_timing).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
open_tcp_connexion	Open a TCP connection (given a host name - or an IP address - and a port number). Please note that: You can specify a timeout in micro seconds. The function returns the ellapsed time (in milli seconds).
Get_Sock_Adress	Fill a sockaddr_in structure created from a host name and a port number. You should not have to call this function yourself.
read_from_socket	Extract data from an open socket descriptor.Please note that: You can specify a timeout in micro seconds. The function returns the ellapsed time (in milli seconds).
read_all_socket	Read the content of a socket until the connexion get closed by the remote peer. Please note that: You can specify a timeout in micro seconds. The function returns the ellapsed time (in milli seconds).
get_ip_addr	Get the IP address and port number associated with a given connection's end point.

Buffer implementations

This library implements basic buffer implementations. To use this library in your code:

Includes the file "buffers.h".
Link your code with the file "libmy_buffers.a" (-lmy_buffers).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
create_cyclic_buffer	Create a cyclic buffer.
destroy_cyclic_buffer	Destroy a cyclic buffer.
cyclic_buffer_add_element	Add a new element to a cyclic buffer.
rewind_cyclic_buffer	Reset the buffer's read pointer.
cyclic_buffer_get_element	Returns a pointer to the current element. You should call rewind_cyclic_buffer() before calling this function.
cyclic_buffer_get_start	Return the index of the first element in the cyclic buffer.
cyclic_buffer_get_stop	Return the index of the last element in the cyclic buffer..
cyclic_buffer_get_current_size	Return the current number of elements in the cyclic buffer..

Shared memory segments

This library implements basic shared memory segments toolkit. To use this library in your code:

Includes the file "my_shm.h".
Link your code with the file "libmy_shm.a" (-lmy_shm).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
change_shm_access_permission	By default, all newly created SHM will grant all access rights (Read/Write/Execute) to the process' user. Any other user has no rights at all. This is equivalent to chmod a-wxr file_name; chmod u+wxr file_name for a file. This function allows you to change this setting. Please note that you should call this function before you create the SHM. That is, before you call create_shared_memory_segment().
create_shared_memory_segment()	Create a SHM. You specify a well known IPC key if you've got one. Otherwise you can ask the kernel to find the first available key. Please note that if you plan to share the SHM between process (no fork) than you may use well known IPC keys.
get_shared_memory_segment_sys_id()	Get a previously created shared memory segment (created by another process).
set_auto_destroy()	The process that creates the SHM should call this function. This will set the SHM into auto destroy mode. The SHM will remain in memory until the last process detach it, then it will be destroyed by the system. Please note that when a process ends, all SHM are detached. You must call this function after attache_shared_memory_segment(). Note: When the process that created the SHM calls this function, no more process can get the SHM. The system considers that the SHM is ready to be destroyed (it will be destroyed on the last detachment) ... So no more process is allowed to get the SHM.
get_shared_memory_segment_id()	Return the system identifier of the shared memory segment.
get_shm_address()	Return the address used by the proccess to access the SHM. Please note that you should use this function after attache_shared_memory_segment().
attache_shared_memory_segment()	Attache the shared memory segment to the process' memory space.
get_shm_info()	Return a structure "struct shmid_ds" that contains information about the shared memory segment. Please look at the man page for the function "shmctl" for more details.
detache_shm()	Detach a previously attached (using attache_shared_memory_segment()) shared memory segment.

Note: In the library's sources, you will find a good example that shows how to use the SHM's API (plase look at the file "test_shm.c". It implements a basic productor/consumer system.

Semaphore toolkit

This library implements basic semaphore toolkit. To use this library in your code:

Includes the file "my_sem.h".
Link your code with the file "libmy_sem.a" (-lmy_shm).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
create_semaphore_set()	Create a set of semaphores. Please note that the semaphores are initialized with the value +1 (you can change that later using the functions set_semaphore_value() or set_semaphore_values()). Please note that the semaphores' are created with the persmission 700. In other words, the process' (UNIX) owner has all rights, and everybody else has no rigts. You can change the semaphores' permissions with the function change_sem_access_permission().
change_sem_access_permission()	Change the semaphores' permissions.
get_semaphore_set()	Get a previously create set of semaphores (using public IPC key).
set_semaphore_values()	Set the values of all the semaphores (you can however set distinct values for each semaphores).
set_semaphore_value()	Set the value of one semaphore (and only one, the other semaphores remain untouched).
take_sem()	Take a semaphore. This decremente the semaphore's value by 1. Please note that if the process exists (for any reasons - including segmentation fault or "kill"), then the operation is canceled. This means that the semaphore will be released.
release_sem()	Release a semaphore. This increments the semaphore's value by +1.
destroy_semaphore_set()	Destroy all the semaphores in the set of semaphores.

Note: In the library's sources, you will find a good example that shows how to use the semaphore's API (plase look at the file "test_shm.c". It implements a basic productor/consumer system.

Type sizes (OS specific)

When you compile the Common C Library, the file "includes/os_specific.h". This C header contains definitions for all the OS specific data sizes. The list includes:

This file looks like (the numerical values may change depending on the OS):

#define INT_SIZE 4 #define CHAR_SIZE 1 #define FLOAT_SIZE 4 #define DOUBLE_SIZE 8 #define SIGNED_INT_SIZE 4 #define SIGNED_CHAR_SIZE 1 #define UNSIGNED_INT_SIZE 4 #define UNSIGNED_CHAR_SIZE 1 #define SHORT_INT_SIZE 2 #define UNSIGNED_SHORT_INT_SIZE 2 #define SIGNED_SHORT_INT_SIZE 2 #define LONG_INT_SIZE 4 #define LONG_DOUBLE_SIZE 12 #define UNSIGNED_LONG_INT_SIZE 4 #define SIGNED_LONG_INT_SIZE 4 #define PTR_INT_SIZE 4 #define PTR_CHAR_SIZE 4 #define PTR_FLOAT_SIZE 4 #define PTR_DOUBLE_SIZE 4 #define PTR_SIGNED_INT_SIZE 4 #define PTR_SIGNED_CHAR_SIZE 4 #define PTR_UNSIGNED_INT_SIZE 4 #define PTR_UNSIGNED_CHAR_SIZE 4 #define PTR_SHORT_INT_SIZE 4 #define PTR_UNSIGNED_SHORT_INT_SIZE 4 #define PTR_SIGNED_SHORT_INT_SIZE 4 #define PTR_LONG_INT_SIZE 4 #define PTR_LONG_DOUBLE_SIZE 4 #define PTR_UNSIGNED_LONG_INT_SIZE 4 #define PTR_SIGNED_LONG_INT_SIZE 4

Simple math tools

This library implements basic math toolkit. To use this library in your code:

Includes the file "my_math.h".
Link your code with the file "libmy_math.a" (-lmy_math).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
round_to_multiple_of()	Given two integers N and p, the function returns the integer r such as: r is a multiple of p. "r = N + x" with x such as "0 <= x < N" For example, if N=2 and p=4, then r=4.

Linked lists (simple and double linked)

This library implements linked list utilities. To use the simple linked list API:

Includes the file "list.h".
Link your code with the file "libmy_list.a" (-lmy_list).

To use the double linked list API:

Includes the file "double_list.h".
Link your code with the file "libmy_double_list.a" (-lmy_double_list).

NOTE: You can not use simple and double linked list simultaneously (the API is the same).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
list_init()	Inatialize a linked list. This must be the first function called. The user must provide specific functions to: Delete the data structure stored in an element of the linked list. Compare two data structure.
list_destroy()	Free all memory allocated for the linked list.
list_ins_next()	Insert an element into the linked list (the insertion is done AFTER a given element).
list_rem_next()	Remove an element from the linked list (the destruction is done AFTER a given element).
list_find()	Finf an element into the linked list (given a data struture). The search can be done: From the beginning of the linked list. From a given element.
list_size()	This macro returns the number of elements in a linked list.
list_head()	This macro returns a pointer to the first element of a list.
list_tail()	This macro returns a pointer to the last element of a list.
list_is_head()	This macro returns tests if an element is the first element in a linked list. If the element is the first in the linked list, the macro returns 1. Otherwise it returns 0.
list_is_tail()	This macro returns tests if an element is the last element in a linked list. If the element is the last in the linked list, the macro returns 1. Otherwise it returns 0.
list_data()	This macro returns a pointer to the data section of a linked list.
list_next()	Given a element, this macro returns a pointer to the next element in the list.
list_prev() -- Double linked list ONLY	Given a element, this macro returns a pointer to the previous element in the list.

You should consult the test programs test_list.c and test_double_list.c (Cf CVS archive) for a full examples.

Hash table

This library implements hash table utilities. To use this library in your code:

Includes the file "chtbl.h".
Link your code with the files "libmy_list.a" and "libmy_hash_table.a" (-lmy_list -lmy_hash_table).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
chtbl_init()	Initialize the hash table. This should be the first function called. The user must provide: The number of linked list. The function used to hash the input key. The function used to compare two data stored into the hash table. The function used to free the memory associated with the user's data.
chtbl_destroy()	Free all memory associated with the hash table (including user's data).
chtbl_insert()	Insert an element into the hash table. Please note that the elmement is NOT copied into the hash table. The hash table contains a pointer to the user's data.
chtbl_remove()	Remove an entry from the hash table. Please note that this is the user's responsability to free the memory allocated for the user' data.
chtbl_lookup()	Lookup the hash table for a given entry.
chtbl_find()	Lookup ALL the hash table to find one element. You can use this function if the element you are searching is not defined by the hash table's key.
chtbl_next()	This function allows you to walk through a hash table. Each time you call it, the function returns a pointer to the next element in the hash.

You should consult the test program test_hash_table.c (Cf CVS archive) for a full example.

Stacks

This library implements stack utilities. To use this library in your code:

Includes the file "stack.h".
Link your code with the files "libmy_list.a" and "libmy_stack.a" (-lmy_list -lmy_stack).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
stack_init()	Initialize the stack. This should ne the first function called. The user must provide: Delete the data structure stored in an element of the linked list. Compare two data structure. This function is not used, but it is required because the stack is implemented on top of a linked list.
stack_push()	Put an element on top of the stack. Please note that the element's data is NOT copied into the stack (the stack's element only contains a pointer to the user's data).
stack_pop()	Extract the element on top of the stack. Please note that it is the user's responsability to free the memory allocated with the element's data.
stack_destroy()	Free all memory allocated for the stack (including element's datas).
stack_peek()	Return the data on top of the stack (but do not extract it).
stack_size()	This macro returns the number of elements in the stack.

You should consult the test program test_stack.c (Cf CVS archive) for a full example.

Array toolkit

This library implements basic tools for array manipulation. To use this library in your code:

Includes the file "array.h".
Link your code with the file "libmy_array.a" and "libmy_sort.a" (-lmy_array -lmy_sort).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
array_init()	This function initializes the array's plugin. The user must provide the following function (depending on the type of data stored into the array): copy_data: function used to copy the user's data. Please note that this function MUST take care of memory management (if necessary). remove_data: function used to free all memory (if necessary) and re-initialize (if necessary) user's data. This function could be set to NULL if no special operation is needed. compare: function used to compare 2 user's data. index: function used to calculate the address of an element in an array. init_data: function used to initialize data (if necessary). It is called whenever an element is allocated. This function should be called first.
array_free()	Free all memory allocated for an array structure (this does NOT include the user's data).
array_schedule_for_rem()	Schedule an element (designed by its index) for removing.
array_rem_all()	Remove all previously scheduled (for removing) elements.
array_init_element()	Initialize all elements in the array.
array_add()	Add an element to the array (at the end of the array).
array_rem()	Remove an element from the array.
array_insert()	Insert an element in the array.
array_find()	Search for an element of the array.

EXAMPLE: Look at the file tests/test_array.c (cf CVS archive) for a full example.

Sorting utilities

This library implements two sorting methods used to sort arrays. To use this library in your code:

Includes the file "sort.h".
Link your code with the file "libmy_sort.a" (-lmy_sort).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
issort()	Sort an array of STATIC elements using the insertion method (not suitable for a big number of elements). The user must provide the following functions: compare: function used to compare user data.
extended_issort()	If you need to sort special kind of elements (that need to be allocated), then you should use this function. The user must provide the following functions: compare: function used to compare user data. copy_data: function used to copy data. Please note that this function MUST take care of memory management. init_elem: function used to initialize data (if necessary). This function could be NULL if no initialazation is required. This function is called whenever a new element has been allocated.
gksort()	Sort an array of STATIC elements using the Quick Sort method (good for for a big number of elements). The user must provide the following functions: compare: function used to compare user data.
extended_issort()	If you need to sort special kind of elements (that need to be allocated), then you should use this function. The user must provide the following functions: compare: function used to compare user data. copy_data: function used to copy data. Please note that this function MUST take care of memory management. init_elem: function used to initialize data (if necessary). This function could be NULL if no initialazation is required. This function is called whenever a new element has been allocated.

EXAMPLE: Look at the files tests/test_sort.c and tests/test_ext_sort.c (cf CVS archive) for a full example.

Debug version of malloc library

This library implements debugging version of malloc (and free):

Includes the file "dmalloc.h".
Link your code with the file "libmy_dmalloc.a" and "libmy_files.a" (-lmy_dmalloc -lmy_files).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
dmalloc()	This function calls malloc() to allocate memory, but it allows you to write a message in a log file.
dfree()	This function calls free() to free previously allocated memory, but it allows you to write a message in a log file.

Command line parsing

This library implements easy to use command line parsing functions. To use this library:

Includes the file "option.h".
Link your code with the file "libmy_option.a" (-lmy_option).

The following table gives a quick overview of the library's functions. To have a complete description, please consult the Developper's documentation.

Function	Description
init_options()	Initialize the data structure that contains the definitions for all option. You must this function before any other functions.
parse_command_line()	Parse the command line. Once you called nit_options(), you should call parse_command_line().
get_argument()	Returns the argument associated with a given option.
is_argument_required()	Returns a bolean value that indicates if the specified option requires an argument.