su.docs

this is simple sip stack.

/* -*- C -*- */

/**@mainpage Sofia OS Services and Utility Library
 *
 * @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 <[e-mail]>
 * 
 * @STATUS 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_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 <[e-mail]>
 * @author Jari Selin <[e-mail]>
 *
 * @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:
 *
 * - <a href=su_types_h.html>su_types</a> - basic integer types
 * - <a href=group_su_socket.html>su_socket</a> - socket functions
 * - <a href=group_su_wait.html>su_wait</a> - synchronization functions
 * - <a href=group_su_time.html>su_time</a> - time functions
 * - <a href=group_su_alloc.html>su_alloc</a> - memory management functions
 * - <a href=group_su_log.html>su_log</a> - generic logging functions
 * - <a href=group_su_tag.html>su_tag</a> - tag list function
 * - <a href=group_su_md5.html>su_md5</a> - 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 <su.h> contains the portable socket functions. 
 *
 *  The <su.h> 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_log Logging Interface
 *
 * Generic logging interface.
 *
 * The @b su_log submodule contains a generic logging interface. The
 * interface provides means for redirecting the log and filtering log
 * messages based on message priority.
 */

/**@defgroup su_htable Hash tables
 *
 * Hash tables.
 *
 * The hash table interface and implementation is defined in htable.h.
 * Example code and tests for the implementation is in htable_test.c.
 */


/* <a name="su_wallclock"></a>
 * <h3>Function @c su_wallclock() - get current time</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_time.h&gt;
 * 
 * void su_wallclock(su_time_t *tv);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * Fills the @a tv with the current NTP timestamp.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c tv      <td>pointer to the timeval object
 * </table>
 * </blockquote>
 * 
 * <a name="su_now"></a>
 * <h3>Function @c su_now() - get current time</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_time.h&gt;
 * 
 * su_time_t su_now(void);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * Return the current NTP timestamp.
 * </blockquote>
 * 
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 * The structure containing the current NTP timestamp.
 * </blockquote>
 * 
 * <a name="su_time_print"></a>
 * <h3>Function @c su_time_print() - print an NTP timestamp</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_time.h&gt;
 * 
 * int su_time_print(char *s, int n, su_time_t const *tv);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 *  This function prints an NTP timestamp as a decimal number to the
 *  given buffer.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c char *s            <td>pointer to buffer
 *   <tr><td>@c int n              <td>buffer size
 *   <tr><td>@c su_time_t const tv <td>pointer to the timeval object
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 * The number of characters printed, excluding the final NUL.
 * </blockquote>
 * 
 * <a name="su_duration"></a>
 * <h3>Function @c su_duration() - return time difference in milliseconds</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_time.h&gt;
 * 
 * su_duration_t su_duration(su_time_t t1, su_time_t t2);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * 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.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c t1      <td>after time
 *   <tr><td>@c t2      <td>before time
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 * The duration in milliseconds between the two times.
 * </blockquote>
 * 
 * <a name="su_alloc.h"></a>
 * <h1>&lt;su_alloc.h&gt;</h1>
 * 
 * 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.
 * 
 * <ul>
 *   - 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
 * 
 * </ul>
 * 
 * 
 * The functions for implementing objects derived from @c su_home_t
 * are as follows:
 * <ul>
 *   - Function @c su_home_init()
 *       - initialize an @c su_home_t object
 * 
 *   - Function @c su_home_deinit()
 *        - free memory blocks from home
 * 
 * </ul>
 * 
 * <a name="su_home_create"></a>
 * <h3>Function @c su_home_create() - create an su_home_t object</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_alloc.h&gt;
 * 
 * su_home_t *su_home_create(void);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * 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 <dfn>su_home_destroy()</dfn>.
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 * This function returns a pointer to an @c su_home_t object, or
 * @c NULL upon an error.
 * </blockquote>
 * 
 * <a name="su_home_destroy"></a>
 * <h3>Function @c su_home_destroy() - free a home object</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_alloc.h&gt;
 * 
 * void su_home_destroy(su_home_t *h);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * The function @c su_home_destroy() frees a home object, and all
 * memory blocks associated with it.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c su_home_t *h <td>pointer to a home object
 * </table>
 * </blockquote>
 * 
 * <a name="su_alloc"></a>
 * <h3>Function @c su_alloc() - allocate a memory block</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_alloc.h&gt;
 * 
 * void *su_alloc(su_home_t *h, int  n);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * 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().
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c su_home_t *h <td>pointer to a home object
 *   <tr><td>@c int n      <td>size of the memory block to be allocated
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 * This function returns a pointer to the allocated memory block, or
 * @c NULL, if an error occurred.
 * </blockquote>
 * 
 * <a name="su_zalloc"></a>
 * <h3>Function @c su_zalloc() - allocate and zero a memory block</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_alloc.h&gt;
 * 
 * void *su_zalloc(su_home_t *h, int  n)
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * The function @c su_zalloc() allocates a memory block with a given
 * size and zeroes the allocated block.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c su_home_t *h <td>pointer to a home object
 *   <tr><td>@c int n      <td>size of the memory block to be allocated
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 * This function returns a pointer to the allocated memory block, or
 * @c NULL, if an error occurred.
 * </blockquote>
 * 
 * <a name="su_salloc"></a>
 * <h3>Function @c su_salloc() - allocate a structure</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_alloc.h&gt;
 * 
 * void *su_salloc(su_home_t *h, int  s);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * The function su_salloc() allocates a structure with a given size,
 * zeros it, and initializes the size field to the given size.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c su_home_t *h <td>pointer to a home object
 *   <tr><td>@c int n      <td>size of the structure to be allocated
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 * This function returns a pointer to the allocated memory block, or
 * @c NULL, if an error occurred.
 * </blockquote>
 * 
 * <a name="su_free"></a>
 * <h3>Function @c su_free() - free a memory block</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_alloc.h&gt;
 * 
 * void su_free(su_home_t *h, void *vb);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * The function @c su_free() frees a single memory block.
 * </blockquote>
 * 
 * <h4>Parameters</h4>
 * <blockquote>
 * <table cellpadding=3 cellspacing=0 border=1>
 *   <tr><td>@c su_home_t *h  <td>pointer to a home object
 *   <tr><td>@c void      *vb <td>pointer to the memory block to be freed
 * </table>
 * </blockquote>
 * 
 * <h4>Return Value</h4>
 * <blockquote>
 * </blockquote>
 * 
 * <a name="su_home_init"></a>
 * <h3>Function @c su_home_init() - initialize an @c su_home_t object</h3>
 * 
 * <h4>Synopsis</h4>
 * 
 * <blockquote><pre>
 * #include &lt;su_alloc.h&gt;
 * 
 * int su_home_init(su_home_t *h);
 * </pre></blockquote>
 * 
 * <h4>Description</h4>
 * <blockquote>
 * The function @c su_home_init() initializes an object derived from