/* -*- C -*- */ /**@MODULEPAGE "su" - OS Services and Utilities * * @section su_meta Module Information * * The @b su module contains a simple, portable socket/timing/synchronizing * library developed for Sofia communications software. * * @CONTACT Pekka Pessi * * @STATUS @SofiaSIP Core library * * @LICENSE LGPL * * @section su_overview Overview * * The @b su module provides following interfaces for application programs: * * - su_types.h - integral types * - su.h - @ref su_socket * - su_localinfo.h - get list of local IP addresses * - su_wait.h - @ref su_wait * - su_time.h - @ref su_time * - su_alloc.h - @ref su_alloc * - su_log.h - @ref su_log * - su_tag.h - @ref su_tag * - su_md5.h - @ref su_md5 * - su_uniqueid.h - @ref su_uniqueid * * The @b su library also contains some collection datatypes: * - htable.h - @ref su_htable * - rbtree.h - balanced red-black trees * - su_strlst.h - @ref su_strlst * - su_vector.h - @ref su_vector * * There are also some convenience macros for unit test programs: * - tstdef.h - macros for unit tests * * @author Pekka Pessi * @author Jari Selin * * @par SU Debug Log * * The debugging output from @b su module is controlled by #su_log_global * log object. The environment variable #SU_DEBUG sets the default log * level. */ /**@maindefgroup su OS Utilities * * The "su" module contains OS utilies for Sofia. * * The @b su is a simple, portable socket/timing/synchronizing library * developed for Sofia communications software. Currently, interface to * it consists of following parts: * * - su_types - basic integer types * - su_socket - socket functions * - su_wait - synchronization functions * - su_time - time functions * - su_alloc - memory management functions * - su_log - generic logging functions * - su_tag - tag list function * - su_md5 - MD5 hashing */ /**@defgroup su_programs Shell Programs * * The @b su module provides few shell utilities: * - @ref localinfo (localinfo.c) * - @ref addrinfo (addrinfo.c) */ /**@defgroup su_socket Socket Functions * * @brief The contains the portable socket functions. * * The contains following functions, macros, and types: * - su_init(): initializes sockets * - su_deinit(): deinitializes sockets * - su_socket(): creates a socket * - su_close(): closes a socket * - su_ioctl(): ioctl to a socket * - su_setreuseaddr(): set/reset reusing the addresses/ports for a socket * - su_setblocking(): enables/disables blocking * - su_isblocking(): checks if the previous call failed because it * would have blocked * - su_errno(): the latest socket error * - su_perror(): prints the latest socket error message to stderr * - su_strerror(): returns the given socket error message * - su_perror2(): prints the given socket error message to stderr * - su_soerror(): returns the error code associated with the socket * - su_getmsgsize(): return the number of bytes that can be recv()ed from * a socket * - su_getlocalip(): return an IP address belonging to the local host * - su_vsend(): scatter-gather send * - su_vrecv(): scatter-gather receive * - #su_iovec_t: structure holding scatter-gather IO vector */ /**@defgroup su_htable Hash tables * * Hash tables. * * The hash table interface and implementation is defined in * . Example code and tests for the implementation is in * test_htable.c. */ /* *

Function @c su_wallclock() - get current time

* *

Synopsis

* * 
 * #include <su_time.h>
 * 
 * void su_wallclock(su_time_t *tv);
 *
* *

Description

*
* Fills the @a tv with the current NTP timestamp. *
* *

Parameters

*
* *
@c tv pointer to the timeval object *
*
* * *

Function @c su_now() - get current time

* *

Synopsis

* * 
 * #include <su_time.h>
 * 
 * su_time_t su_now(void);
 *
* *

Description

*
* Return the current NTP timestamp. *
* * *

Return Value

*
* The structure containing the current NTP timestamp. *
* * *

Function @c su_time_print() - print an NTP timestamp

* *

Synopsis

* * 
 * #include <su_time.h>
 * 
 * int su_time_print(char *s, int n, su_time_t const *tv);
 *
* *

Description

*
* This function prints an NTP timestamp as a decimal number to the * given buffer. *
* *

Parameters

*
* *
@c char *s pointer to buffer *
@c int n buffer size *
@c su_time_t const tv pointer to the timeval object *
*
* *

Return Value

*
* The number of characters printed, excluding the final NUL. *
* * *

Function @c su_duration() - return time difference in milliseconds

* *

Synopsis

* * 
 * #include <su_time.h>
 * 
 * su_duration_t su_duration(su_time_t t1, su_time_t t2);
 *
* *

Description

*
* Calculates the duration in milliseconds from @a t2 to @a t1 in milliseconds. If the difference is bigger * than @c SU_MAX_DURATION, return @c SU_MAX_DURATION instead. *
* *

Parameters

*
* *
@c t1 after time *
@c t2 before time *
*
* *

Return Value

*
* The duration in milliseconds between the two times. *
* * *

<su_alloc.h>

* * This section describes memory management functions. * * * The * @c su_alloc library provides convenience functions for * memory management. The library defines an object @c su_home_t for * collecting multiple memory allocations under one handle. * *
    * - Function @c su_home_create() * - create an su_home_t object * * - Function @c su_home_destroy() * - free a home object * * - Function @c su_alloc() * - allocate a memory block * * - Function @c su_zalloc() * - allocate and zero a memory block * * - Function @c su_salloc() * - allocate a structure * * - Function @c su_free() * - free a memory block * *
* * * The functions for implementing objects derived from @c su_home_t * are as follows: *
    * - Function @c su_home_init() * - initialize an @c su_home_t object * * - Function @c su_home_deinit() * - free memory blocks from home * *
* * *

Function @c su_home_create() - create an su_home_t object

* *

Synopsis

* * 
 * #include <su_alloc.h>
 * 
 * su_home_t *su_home_create(void);
 *
* *

Description

*
* The function @c su_home_create() creates a home object used to * collect multiple memory allocations under one handle, so that they can be * freed by calling su_home_destroy(). *
* *

Return Value

*
* This function returns a pointer to an @c su_home_t object, or * @c NULL upon an error. *
* * *

Function @c su_home_destroy() - free a home object

* *

Synopsis

* * 
 * #include <su_alloc.h>
 * 
 * void su_home_destroy(su_home_t *h);
 *
* *

Description

*
* The function @c su_home_destroy() frees a home object, and all * memory blocks associated with it. *
* *

Parameters

*
* *
@c su_home_t *h pointer to a home object *
*
* * *

Function @c su_alloc() - allocate a memory block

* *

Synopsis

* * 
 * #include <su_alloc.h>
 * 
 * void *su_alloc(su_home_t *h, int  n);
 *
* *

Description

*
* The function @c su_alloc() allocates a memory block of a given size. * * * If @a h is @c NULL, this function behaves exactly like * @c malloc(). *
* *

Parameters

*
* *
@c su_home_t *h pointer to a home object *
@c int n size of the memory block to be allocated *
*
* *

Return Value

*
* This function returns a pointer to the allocated memory block, or * @c NULL, if an error occurred. *
* * *

Function @c su_zalloc() - allocate and zero a memory block

* *

Synopsis

* * 
 * #include <su_alloc.h>
 * 
 * void *su_zalloc(su_home_t *h, int  n)
 *
* *

Description

*
* The function @c su_zalloc() allocates a memory block with a given * size and zeroes the allocated block. *
* *

Parameters

*
* *
@c su_home_t *h pointer to a home object *
@c int n size of the memory block to be allocated *
*
* *

Return Value

*
* This function returns a pointer to the allocated memory block, or * @c NULL, if an error occurred. *
* * *

Function @c su_salloc() - allocate a structure

* *

Synopsis

* * 
 * #include <su_alloc.h>
 * 
 * void *su_salloc(su_home_t *h, int  s);
 *
* *

Description

*
* The function su_salloc() allocates a structure with a given size, * zeros it, and initializes the size field to the given size. *
* *

Parameters

*
* *
@c su_home_t *h pointer to a home object *
@c int n size of the structure to be allocated *
*
* *

Return Value

*
* This function returns a pointer to the allocated memory block, or * @c NULL, if an error occurred. *
* * *

Function @c su_free() - free a memory block

* *

Synopsis

* * 
 * #include <su_alloc.h>
 * 
 * void su_free(su_home_t *h, void *vb);
 *
* *

Description

*
* The function @c su_free() frees a single memory block. *
* *

Parameters

*
* *
@c su_home_t *h pointer to a home object *
@c void *vb pointer to the memory block to be freed *
*
* *

Return Value

*
*
* * *

Function @c su_home_init() - initialize an @c su_home_t object

* *

Synopsis

* * 
 * #include <su_alloc.h>
 * 
 * int su_home_init(su_home_t *h);
 *
* *

Description

*
* The function @c su_home_init() initializes an object derived from * @c su_home_t. It checks that the @a suh_size field is valid. *
* *

Parameters

*
* *
@c su_home_t *h pointer to a home object *
*
* *

Return Value

*
* The function @c su_home_init() returns @c 0 when * successful, or @c -1 upon an error. *
* *

Note

*
This is an internal function, and it is intended for * implementing the objects derived from @c su_home_t. *
* * *

Function @c su_home_deinit() - free memory blocks from home

* *

Synopsis

* * 
 * #include <su_alloc.h>
 * 
 * void su_home_deinit(su_home_t *h);
 *
* *

Description

*
* The function @c su_home_deinit() frees the memory blocks * associated with the home object. *
* *

Parameters

*
* *
@c su_home_t *h pointer to a home object *
*
* *

Note

*
This is an internal function, and it is intended for * implementing the objects derived from @c su_home_t. *
* * * *

<su_wait.h>

* * This section describes synchronization functionality. * The @c su_wait library provides portable synchronization * primitives needed for running communication software. * * Synchronization means that the program can stop waiting for events, * set callback functions for events, schedule timers, and set callback * functions for timers. In other words, it is an OS-independent * @c poll()/@c select()/@c WaitForMultipleObjects() * interface, spiced up with timer interface. * * The library provides three kinds of objects: root * objects (@c su_root_t), wait objects * (@c su_wait_t), and timer objects * (@c su_timer_t). * * *

Wait Objects

* * * Wait objects are used to signal I/O events to the process. * The events are as follows: * *
*
SU_WAIT_IN *
incoming data is available * *
SU_WAIT_OUT *
data can be output * *
SU_WAIT_ERR *
an error occurred * *
SU_WAIT_HUP *
the socket connection was closed * *
SU_WAIT_ACCEPT *
a listening socket accepted a new connection attempt *
* * * It is possible to combine several events with |, binary or operator. * * * Public API contains functions as follows: *
    * - su_wait_create() * - su_wait_destroy() * - su_wait() * - su_wait_events() *
* * * In Unix, the wait object is @c struct poll. The structure contains a file * handle, a mask describing expected events, and a mask containing the * occurred events after calling @c poll(), ie. @c su_wait(). * * * In Windows, the wait object is a @c HANDLE (a descriptor of a Windows * kernel entity). * * * *

Function @c su_wait_create()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * int su_wait_create(su_wait_t *newwait, su_socket_t socket, int events)
* *

Description

* *
* @c Su_wait_create() creates a new wait object for a * @a socket with given @a events. The new wait object is * assigned to the @a newwait parameter. *
* *

Parameters

* *
* *
@c newwaitthe newly created wait object *
@c socket socket descriptor *
@c events mask for events that can signal this wait object *
*
* *

Return Value

* *
* 0 if the call was successful, -1 otherwise. *
* * *

Function @c su_wait_destroy()

* *

Synopsis

* * 
 #include <su_wait.h>
 * 
 * int su_wait_destroy(su_wait_t *waitobj);
 *
* *

Description

*
Destroy a wait object. *
* * *

Parameters

* *
* *
@c waitobj pointer to wait object *
*
* *

Return Value

* *
* 0 when successful, -1 upon an error. *
* * *

Function @c su_wait()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * int su_wait(su_wait_t waits[], unsigned n, long timeout);
 *
* *

Description

*
Block until a event specified by wait objects or a timeout occurs. * * * In Unix, this is poll. * * * In Windows, this is WSAWaitForMultipleEvents *
* *

Parameters

*
* *
@c waits array of wait objects *
@c n number of wait objects in array waits *
@c timeout timeout in milliseocnds *
*
* *

Return Value

*
* Index of the signaled wait object, if any, SU_WAIT_TIMEOUT if timeout * occurred, and -1 upon an error. *
* * *

Function @c su_wait_events()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * int su_wait_events(su_wait_t *waitobj, su_socket_t s);
 *
* *

Description

*
Return an mask describing events occurred. *
* * *

Parameters

*
* *
@c waitobj pointer to wait object *
@c s socket *
*
* *

Return Value

*
Binary mask describing the events. *
* * *

Function @c su_wait_mask()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * int su_wait_mask(su_wait_t *waitobj, su_socket_t s, int events);
 *
* *

Description

*
* Sets the mask describing events that can signal the wait object. *
* *

Parameters

*
* *
@c waitobj pointer to wait object *
@c s socket *
@c events new event mask *
*
* *

Return Value

*
* 0 when successful, -1 upon an error. *
* * *

Root objects

* * * Root object is a structure containing a list of wait objects, * associated callback functions, and arguments to these functions. * It can also contain a list of timers, and a magic cookie (a pointer * defined by root object user.) * * * The public API contains following functions: *
    * - su_root_create() * - su_root_destroy() * - su_root_magic() * - su_root_register() * - su_root_unregister() * - su_root_run() * - su_root_break() * - su_root_step() *
* * These functions are intended for implementing su_root API: *
    * - su_root_init() * - su_root_deinit() * - su_root_query() * - su_root_event() *
* * *

Function @c su_root_create()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * su_root_t *su_root_create(su_root_magic_t *magic);
 *
* *

Description

*
Allocate and initialize an instance of su_root_t *
* * *

Parameters

*
* *
@c magic pointer to user data *
*
* *

Return Value

*
A pointer to allocated su_root_t instance, NULL on error. *
* * * *

Function @c su_root_destroy()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * void su_root_destroy(su_root_t *root);
 *
* *

Description

*
Deinitialize and free an instance of su_root_t *
* * *

Parameters

*
* *
@c root pointer to a root structure *
*
* * * *

Function @c su_root_magic()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * su_root_magic_t *su_root_magic(su_root_t *root);
 *
* *

Description

*
Return the user data pointer that was given input to su_root_create() or * * su_root_init(). *
* *

Parameters

*
* *
@c root pointer to a root object *
*
* *

Return Value

*
A pointer to user data *
* * * *

Function @c su_root_register()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * int su_root_register(su_root_t *root,
 * 		     su_wait_t *waits,
 * 		     su_wakeup_f callback,
 * 		     su_wakeup_arg_t arg,
 * 		     int priority);
 *
* *

Description

*
Register a su_wait_t object. The wait object, a callback function and * * a argument is stored to the root object. The callback function is called, * when the wait object is signaled. * * Please note if identical wait objects are inserted, only first one is * ever signalled. *
* *

Parameters

*
* *
@c root pointer to root object *
@c waits pointer to wait object *
@c callback callback function pointer *
@c arg argument given to callback function when it is invoked *
@c priority relative priority of the wait object * (0 is normal, 1 important, 2 realtime) *
*
* *

Return Value

*
Index of the wait object, or -1 upon an error. *
* * * *

Function @c su_root_unregister()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * int su_root_unregister(su_root_t *root,
 * 		       su_wait_t *wait,
 * 		       su_wakeup_f callback,
 * 		       su_wakeup_arg_t arg);
 *
* *

Description

*
UnRegisters a su_wait_t object. The wait object, a callback function and * * a argument are removed from the root object. The callback function is called, * when the wait object is signaled. *
* *

Parameters

*
* *
@c root pointer to root object *
@c waits pointer to wait object *
@c callback callback function pointer (may be NULL) *
@c arg argument given to callback function when it * is invoked (may be NULL) *
*
* *

Return Value

*
Index of the wait object, or -1 upon an error. *
* * * *

Function @c su_root_run()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * void su_root_run(su_root_t *root);
 *
* *

Description

*
This function waits for wait objects and the timers associated with * the root object. When any wait object is signaled or timer is * expired, it invokes the callbacks, and returns waiting. * * * This function returns when su_root_break() is called from a callback. *
* *

Parameters

*
* *
@c root pointer to root object *
*
* * * *

Function @c su_root_break()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * void su_root_break(su_root_t *root);
 *
* *

Description

*
If this function is used to terminate execution of su_root_run(). It * * can be called from a callback function. *
* *

Parameters

*
* *
@c root pointer to root object *
*
* * * *

Function @c su_root_step()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * su_duration_t su_root_step(su_root_t *root, su_duration_t tout);
 *
* *

Description

*
This function waits for wait objects and the timers associated with * the @a root object. When any wait object is signaled or timer is * expired, it invokes the callbacks, and returns. * * * This function returns when a callback has been invoked or @a tout * milliseconds is elapsed. *
* *

Parameters

*
* *
@c root pointer to root object *
@c tout timeout in milliseconds *
*
* *

Return Value

*
* Milliseconds to the next invocation of timer, or SU_WAIT_FOREVER if * there are no active timers. *
* * *

Timer objects

* * Timers are used to schedule some task to be executed at given time or * after a default interval. The default interval is specified when the * timer is created. We call timer activation "setting the timer", and * deactivation "resetting the timer" (as in SDL). When the given time has * arrived or the default interval has elapsed, the timer expires and * it is ready for execution. * * These functions are available for handling timers: * * - su_timer_create() * - su_timer_destroy() * - su_timer_set() * - su_timer_set_at() * - su_timer_reset() * - su_timer_run() * * *

Function @c su_timer_create()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * su_timer_t *su_timer_create(su_root_t *root, su_duration_t msec);
 *
* *

Description

* *
* Allocate and initialize an instance of su_timer_t. *
* *

Parameters

*
* *
@c root the root object with which the timer will be associated *
@c msec the default duration of the timer *
*
* *

Return Value

*
A pointer to allocated timer instance, NULL on error. *
* * * *

Function @c su_timer_destroy()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * void su_timer_destroy(su_timer_t *t);
 *
* *

Description

*
Deinitialize and free an instance of su_timer_t. *
* * *

Parameters

*
* *
@c t pointer to the timer object *
*
* * * *

Function @c su_timer_set()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * int su_timer_set(su_timer_t *t,
 * 		 su_timer_f wakeup,
 * 		 su_wakeup_arg_t arg);
 *
* *

Description

*
Sets the given timer to expire after the default duration. * * The timer must have an default duration. *
* *

Parameters

*
* *
@c t pointer to the timer object *
@c wakeup pointer to the wakeup function *
@c arg argument given to the wakeup function *
*
* *

Return Value

*
0 if successful, -1 otherwise. *
* * * *

Function @c su_timer_set_at()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * int su_timer_set_at(su_timer_t *t,
 * 		    su_timer_f wakeup,
 * 		    su_wakeup_arg_t arg,
 * 		    su_time_t when);
 *
* *

Description

*
Sets the timer to expire at given time. *
* * *

Parameters

*
* *
@c t pointer to the timer object *
@c wakeup pointer to the wakeup function *
@c arg argument given to the wakeup function *
@c when time structure defining the wakeup time *
*
* *

Return Value

*
0 if successful, -1 otherwise. *
* * * *

Function @c su_timer_reset()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * int su_timer_reset(su_timer_t *t);
 *
* *

Description

*
Resets the given timer. *
* * *

Parameters

*
* *
@c t pointer to the timer object *
*
* *

Return Value

*
0 if successful, -1 otherwise. *
* * *

Function @c su_timer_run()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * 
 * su_duration_t su_timer_run(su_timer_t ** const t0, su_duration_t tout);
 *
* *

Description

*
Expires and executes expired timers in queue. *
* * *

Parameters

*
* *
@c t0 pointer to the timer queue *
@c tout timeout in milliseconds *
*
* *

Return Value

*
* The duration in milliseconds before the next timer expires, or timeout (2**31 - 1 * ms), whichever is shorter. *
* * * * *

<su_wait_internal.h>

* * * This section contains the internal functions, that is, functions used to * implement objects in @c <su_wait.h>. * * *

Function @c su_root_init()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * #include <su_wait_internal.h>
 * 
 * int su_root_init(su_root_t *root, su_root_magic_t *magic);
 *
* *

Description

* *
* * Initialize an instance of @c su_root_t. The caller should allocate * the memory required for su_root_t, and set the sur_size to the size of the * allocated structure. * *
* *

Parameters

* *
* *
@c root pointer to a uninitialized root structure *
*
* *

Return Value

*
0 when call was successful, -1 otherwise. *
* * *

Note

*
* This is an internal function, and it is intended for implementing * the objects derived from @c su_root_t. *
* * * *

Function @c su_root_deinit()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * #include <su_wait_internal.h>
 * 
 * void su_root_deinit(su_root_t *root);
 *
* *

Description

*
Deinitialize an instance of su_root_t *
* * *

Parameters

*
* *
@c root pointer to a root structure *
*
* *

Note

*
This is an internal function, and it is intended for * implementing the objects derived from @c su_root_t. *
* * *

Function @c su_root_query()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * #include <su_wait_internal.h>
 * 
 * unsigned su_root_query(su_root_t *root, su_wait_t *waits, unsigned n_waits);
 *
* *

Description

*
Copies the su_wait_t objects from the root. The number of wait objects * * can be found out by calling su_root_query() with n_waits as zero. *
* *

Parameters

*
* *
@c waits pointer to array to which wait objects are copied *
@c root pointer to root object *
@c n_waits number of wait objects fitting in array waits *
*
* *

Return Value

*
Number of wait objects, or 0 upon an error. *
* * *

Note

*
This is an internal function, and it is intended for * implementing the objects derived from @c su_root_t. *
* * * *

Function @c su_root_event()

* *

Synopsis

* * 
 * #include <su_wait.h>
 * #include <su_wait_internal.h>
 * 
 * void su_root_event(su_root_t *root, su_wait_t *waitobj);
 *
* *

Description

*
Invokes the callback function associated with the wait object. * * * If waitobj is NULL, check if a wait object associated with root is * signaled, and its callback is invoked. *
* *

Parameters

*
* *
@c root pointer to root object *
@c waitobj pointer to wait object, or NULL *
*
* *

Note

*
This is an internal function, and it is intended for * implementing the objects derived from @c su_root_t. *
* */