su.docs 4.11 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2
/* -*- C -*- */

3
/**@MODULEPAGE "su" - OS Services and Utilities
Pekka Pessi's avatar
Pekka Pessi committed
4 5 6 7 8 9 10 11
 *
 * @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 <Pekka.Pessi@nokia.com>
 * 
12
 * @STATUS @SofiaSIP Core library
Pekka Pessi's avatar
Pekka Pessi committed
13 14 15 16 17 18 19
 * 
 * @LICENSE LGPL
 *
 * @section su_overview Overview
 *
 * The @b su module provides following interfaces for application programs:
 *
Pekka Pessi's avatar
Pekka Pessi committed
20 21 22 23 24 25 26 27 28 29
 * - <sofia-sip/su_types.h> - integral types
 * - <sofia-sip/su_alloc.h> - @ref su_alloc memory management
 * - <sofia-sip/su.h> - @ref su_socket 
 *   - <sofia-sip/su_localinfo.h> - get list of local IP addresses
 * - <sofia-sip/su_wait.h> - @ref su_wait 
 * - <sofia-sip/su_time.h> - @ref su_time
 * - <sofia-sip/su_log.h> - @ref su_log
 * - <sofia-sip/su_tag.h> - @ref su_tag
 * - <sofia-sip/su_md5.h> - @ref su_md5
 * - <sofia-sip/su_uniqueid.h> - @ref su_uniqueid Unique ID and random number generators
Pekka Pessi's avatar
Pekka Pessi committed
30 31
 *
 * The @b su library also contains some collection datatypes:
Pekka Pessi's avatar
Pekka Pessi committed
32 33 34 35
 * - <sofia-sip/htable.h> - @ref su_htable
 * - <sofia-sip/rbtree.h> - balanced red-black trees
 * - <sofia-sip/su_strlst.h> - @ref su_strlst list of strings
 * - <sofia-sip/su_vector.h> - @ref su_vector dynamic arrays of pointers
Pekka Pessi's avatar
Pekka Pessi committed
36 37
 *
 * There are also some convenience macros for unit test programs:
Pekka Pessi's avatar
Pekka Pessi committed
38
 * - sofia-sip/tstdef.h - macros for unit tests
Pekka Pessi's avatar
Pekka Pessi committed
39 40 41 42 43 44
 *
 * @author Pekka Pessi <Pekka.Pessi@nokia.com>
 * @author Jari Selin <Jari.Selin@nokia.com>
 *
 * @par SU Debug Log
 *
Pekka Pessi's avatar
Pekka Pessi committed
45
 * The debugging output from @b su module is controlled by #su_log_global
Pekka Pessi's avatar
Pekka Pessi committed
46 47 48 49 50 51 52 53 54 55 56 57
 * 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:
 *
Pekka Pessi's avatar
Pekka Pessi committed
58
 * - <sofia-sip/su_types.h> - basic integer types
Pekka Pessi's avatar
Pekka Pessi committed
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
 * - <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
 *
Pekka Pessi's avatar
Pekka Pessi committed
77
 *  @brief The <sofia-sip/su.h> contains the portable socket functions. 
Pekka Pessi's avatar
Pekka Pessi committed
78
 *
Pekka Pessi's avatar
Pekka Pessi committed
79
 *  The <sofia-sip/su.h> contains following functions, macros, and types:
Pekka Pessi's avatar
Pekka Pessi committed
80 81 82 83 84 85 86
 *    - 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
Pekka Pessi's avatar
Pekka Pessi committed
87
 *    - su_is_blocking(): checks if the previous call failed because it 
Pekka Pessi's avatar
Pekka Pessi committed
88 89 90 91 92 93 94 95 96
 *  	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
Pekka Pessi's avatar
Pekka Pessi committed
97 98
 *    - su_send(), su_sendto(): type-compatible send()
 *    - su_recv(), su_recvfrom(): type-compatible recv()
Pekka Pessi's avatar
Pekka Pessi committed
99 100 101 102 103 104 105 106 107
 *    - 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.
 *
108 109 110
 * The hash table interface and implementation is defined in
 * <sofia-sip/htable.h>. Example code and tests for the implementation is in
 * test_htable.c.
Pekka Pessi's avatar
Pekka Pessi committed
111
 */