This is ./serveez-api.info, produced by makeinfo version 4.0 from
serveez-api.texi.

INFO-DIR-SECTION Serveez - A server framework.
START-INFO-DIR-ENTRY
* Serveez-API: (serveez-api).   Serveez Embedding Manual.
END-INFO-DIR-ENTRY


File: serveez-api.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

   This file documents how to embed Serveez into C programs and
describes all parts of the API it provides.

   It applies to version 0.1.4 of the Serveez package.

* Menu:

* Introduction::          About this manual
* Embedding Serveez::     How to embed Serveez into C programs
* Embedding API::         Description of functions and data in the library
* Index::                 Overall index


File: serveez-api.info,  Node: Introduction,  Next: Embedding Serveez,  Prev: Top,  Up: Top

Introduction
************

   The Serveez core library provides all of the functionality necessary
in order to write Internet protocol servers (currently TCP, UDP, ICMP
and RAW sockets), pipe servers (connection oriented via a pair of named
pipes) and coservers in a portable way. All of the included servers
coming with this package are based upon this library. It encapsulates
the native network and file system programming interface of different
Unices and Windows systems.

   The Serveez embedding manual and the API documentation will give the
reader an overview about how to use its core library.


File: serveez-api.info,  Node: Embedding Serveez,  Next: Embedding API,  Prev: Introduction,  Up: Top

Embedding Serveez
*****************

   This chapter deals with embedding the Serveez core library into
standalone C/C++ applications and using it in order to write additional
servers.

* Menu:

* Compiling and linking::      How to compile and link against the library
* A simple example::           A very small example showing the basics


File: serveez-api.info,  Node: Compiling and linking,  Next: A simple example,  Up: Embedding Serveez

Compiling and linking
=====================

   When you have installed a version of Serveez passing the `configure'
script the `$prefix' argument e.g. `./configure --prefix=/usr/local'
you will find the `libserveez' library in `/usr/local/lib' and the
include headers in `/usr/local/include'. If you want to compile a C
program using the Serveez API and link against the Serveez core library
`libserveez', which is `libserveez.so' at Unices and `libserveez.dll'
at Windows systems, you need to tell the compiler and linker where to
find the headers and libraries.

   Most C compilers you can use will understand the following command
line options for this purpose. The `-I' argument specifies the path to
additional include headers, the `-L' argument the path to additional
libraries and the `-l' argument the library itself to link against.

  $ cc svztest.c -I/usr/local/include -o svztest -L/usr/local/lib -lserveez

   In order to obtain the correct compiler and linker flag you can also
run the `serveez-config' script which gets installed with the Serveez
package.  The `serveez-config' script can be invoked with the following
set of option.

`-h, --help'
  Displays the usage information.

`-v, --version'
  Displays installed Serveez version.

`-l, --ldflags'
  Prints the linker flags (libraries to link with including path
  information).

`-c, --cflags'
  Prints the compiler flags to compile with.


File: serveez-api.info,  Node: A simple example,  Prev: Compiling and linking,  Up: Embedding Serveez

A simple example
================

   The following small example shows how to use the Serveez core
library to print the list of known network interface. As you will
notice there are three major steps to do: Include the library header
with `#include <libserveez.h>', initialize the library via `svz_boot()'
and finalize it via `svz_halt()'. In between these calls you can use
all of the API functions, variables and macros described in *Note
Embedding API::.

  #include <libserveez.h> /* Include the library header. */
  
  int
  main (int argc, char **argv)
  {
    svz_boot ();          /* Library initialization. */
    svz_interface_list ();
    svz_halt ();          /* Library finalization. */
    return 0;
  }


File: serveez-api.info,  Node: Embedding API,  Next: Index,  Prev: Embedding Serveez,  Up: Top

Embedding API
*************

   In this chapter the reader will find a short description of each
function, global variable and macro the core library of Serveez
provides. The API can either be used to implement a new server or
coserver module for use with Serveez or for supporting network and
server functionality within your own applications without caring about
the details and system programming.

   Most of the Serveez core library interface functionality should be
prefixed with `svz_'. Small symbols will refer to functions and
variables in most cases and big letter symbols refer to macros.

* Menu:

* Memory management::     How memory is managed in Serveez
* Data structures::       Data structure helpers
* Utility functions::     Miscellaneous helper functions
* Core functions::        Network core implementations
* Client connections::    Client connection functions
* Socket::                Socket management functions
* Coserver::              Coserver interface
* Codec::                 Codec interface
* Server types::          Server type implementations
* Server::                Server object functions
* Port configuration::    Port configuration functions
* Booting::               Configuration and boot functions
* Interface::             Network interface function implementation
* Windoze::               Windows port implementations


File: serveez-api.info,  Node: Memory management,  Next: Data structures,  Up: Embedding API

Memory management
=================

   The core library of Serveez is able to keep track of the memory an
application or part of a program consumes and also controls itself in
the same manner. When you are using this memory allocator interface you
can determine and afterwards remove memory leaks. This is a very
important feature if you consider servers being long term programs.

   The three allocator function pointers for `malloc()', `realloc()'
and `free()' make it possible to instruct Serveez to use different
kinds of memory, which might be necessary if you want the library to
work with shared memory arenas or any other underlying memory API.

 - Variable: svz_malloc_func_t svz_malloc_func
  Initial value: malloc
  The SVZ_MALLOC_FUNC variable is a function pointer for allocating
  dynamic memory.

 - Variable: svz_realloc_func_t svz_realloc_func
  Initial value: realloc
  This function pointer is called whenever the core library needs to
  reallocate (resize) a memory block.

 - Variable: svz_free_func_t svz_free_func
  Initial value: free
  In order to free a block of memory the core library calls this
  function pointer.

 - Function: void * svz_malloc (size_t SIZ)
  Allocate SIZE bytes of memory and return a pointer to this block.

 - Function: void * svz_calloc (size_t SIZ)
  Allocate SIZE bytes of memory and return a pointer to this block.
  The memory is cleared (filled with zeros).

 - Function: void * svz_realloc (void * PTR, size_t SIZ)
  Change the size of a `svz_malloc()''ed block of memory.  The SIZE
  argument is the new size of the block in bytes, The given variable
  PTR must be a pointer previously returned by `svz_malloc()' or `NULL'
  if you want to allocate a new block.

 - Function: void svz_free (void * PT)
  Free a block of `svz_malloc()''ed or `svz_realloc()''ed memory block.
  If PTR is a `NULL' pointer, no operation is performed.

 - Macro: svz_free_and_zero (var)
  Free the memory block pointed to by VAR and set it to `NULL'
  afterwards.  The argument VAR is passed to `svz_free()'.

 - Function: char * svz_strdup (char * SR)
  Duplicate the given string SRC if it is not `NULL' and has got a
  valid length (greater than zero).  Return the pointer to the copied
  character string.

 - Function: void * svz_pmalloc (size_t SIZ)
  Allocate a block of memory with the size SIZE permanently.  Memory
  allocated this way does not get into account of the libraries memory
  tracking.

 - Function: void * svz_prealloc (void * PTR, size_t SIZ)
  Resize the memory block pointed to by PTR to SIZE bytes.  This
  routine also allocates memory permanently.

 - Function: char * svz_pstrdup (char * SR)
  Duplicate the given character string SRC permanently.

 - Variable: unsigned int svz_allocated_bytes
  Initial value: 0
  The variable SVZ_ALLOCATED_BYTES holds the overall number of bytes
  allocated by the core library.

 - Variable: unsigned int svz_allocated_blocks
  Initial value: 0
  This variable holds the number of memory blocks reserved by the core
  library.

 - Function: void svz_heap (VOI)
  Print a list of non-released memory blocks.  This is for debugging
  only and should never occur in final software releases.  The function
  goes through the heap hash and states each blocks address, size and
  caller.


File: serveez-api.info,  Node: Data structures,  Next: Utility functions,  Prev: Memory management,  Up: Embedding API

Data structures
===============

   Since most servers need to store information about its clients or
want to keep track of data during runtime we implemented some of the
most useful data pools. The actual aim was to provide higher level data
structures which the programming language C does not support. Some of
the included servers which come with Serveez make extensive use of them.

* Menu:

* Array::                 A growable array implementation
* Hashtable::             Hashtable implementation
* Sparsevector::          Sparsevector implementation
* Vectorlist::            Vectorlist implementation


File: serveez-api.info,  Node: Array,  Next: Hashtable,  Up: Data structures

Array functions
---------------

   The array data structure is a simple array implementation. Each
array has got a size and capacity. The array indices range from zero to
the arrays size minus one. You can put any kind of data into this array
which fits into the size of a pointer. The array automatically grows if
necessary.

 - Function: svz_array_t * svz_array_create (unsigned long CAPACITY,
    svz_free_func_t DESTRO)
  Create a new array with the initial capacity CAPACITY and return a
  pointer to it.  If CAPACITY is zero it defaults to some value.  The
  DESTROY argument allows you to release dynamic allocated memory when
  calling `svz_array_clear()' and `svz_array_destroy()'.  If the array
  contains data allocated by `svz_malloc()' you need to set DESTROY to
  `svz_free()'.  For structured data you can pass a user defined
  routine which recurses into the structure.  If the array contains
  data which should not be released you must set DESTROY to `NULL'.

 - Function: void svz_array_clear (svz_array_t * ARRA)
  Delete all values within the array ARRAY and set its size to zero.
  The array ARRAY itself keeps valid.  Do not perform any operation if
  ARRAY is `NULL'.  If you passed a DESTROY function to
  `svz_array_create()' the routine calls this function passing each
  element of ARRAY to it.

 - Function: void svz_array_destroy (svz_array_t * ARRA)
  Completely destroy the array ARRAY.  The ARRAY handle is invalid
  afterwards.  The routine runs the DESTROY callback for each element
  of the array.

 - Function: svz_array_t * svz_array_destroy_zero (svz_array_t * ARRA)
  This function destroys the given array ARRAY if it holds no elements
  and returns NULL in this case.  Otherwise the function returns the
  given array.

 - Function: void * svz_array_get (svz_array_t * ARRAY, unsigned long
    INDE)
  Return the array element at the position INDEX of the array ARRAY if
  the index is within the array range.  Return `NULL' if not.

 - Function: void * svz_array_set (svz_array_t * ARRAY, unsigned long
    INDEX, void * VALU)
  Replace the array element at the position INDEX of the array ARRAY
  with the value VALUE and return the previous value at this index.
  Returns `NULL' and does not perform any operation if ARRAY is `NULL'
  or the INDEX is out of the array range.

 - Function: void svz_array_add (svz_array_t * ARRAY, void * VALU)
  Append the value VALUE at the end of the array ARRAY.  Does not
  perform any operation if ARRAY is `NULL'.

 - Function: void * svz_array_del (svz_array_t * ARRAY, unsigned long
    INDE)
  Remove the array element at the position INDEX of the array ARRAY.
  Return its previous value or `NULL' if the index is out of the arrays
  range.

 - Function: unsigned long svz_array_capacity (svz_array_t * ARRA)
  Return the given arrays ARRAY current capacity.

 - Function: unsigned long svz_array_size (svz_array_t * ARRA)
  Return the given arrays ARRAY current size.

 - Function: unsigned long svz_array_ins (svz_array_t * ARRAY, unsigned
    long INDEX, void * VALU)
  This routine inserts the given value VALUE at the position INDEX.
  The indices of all following values in the array ARRAY and the size
  of the array get automatically incremented.  Return the values index
  or (-1) if the index is out of array bounds.

 - Function: unsigned long svz_array_idx (svz_array_t * ARRAY, void *
    VALU)
  This function returns the index of the first occurrence of the value
  VALUE in the array ARRAY.  It returns (-1) if there is no such value
  stored within the array.

 - Function: unsigned long svz_array_contains (svz_array_t * ARRAY,
    void * VALU)
  Returns how often the given value VALUE is stored in the array ARRAY.
  Return zero if there is no such value.

 - Macro: svz_array_foreach (array, value, i)
  This is the iteration macro for the array implementation of the core
  library. ARRAY specifies the array to iterate, VALUE the pointer each
  element of the array gets assigned and I is the iteration variable.

 - Function: svz_array_t * svz_array_strdup (svz_array_t * ARRA)
  This function works something like `svz_array_dup()' but considers
  the values within the array ARRAY to be zero-terminated character
  strings and duplicates these via `svz_strdup()'.

 - Function: svz_array_t * svz_array_dup (svz_array_t * ARRA)
  This function replicates the given array ARRAY.  It returns `NULL' if
  there is nothing to do and an identical copy if the array otherwise.

 - Function: void ** svz_array_values (svz_array_t * ARRA)
  Create a `NULL' terminated C array containing the values of the given
  ARRAY.  If the given ARRAY is `NULL' then an empty C array is
  returned.  It is your responsibility to `svz_free()' the returned
  pointer.


File: serveez-api.info,  Node: Hashtable,  Next: Sparsevector,  Prev: Array,  Up: Data structures

Hashtable functions
-------------------

   A hashtable associates keys of arbitrary size and content with
values.  This data structure is also called associative array sometimes
because you use keys in order to access values instead of numbers. You
cannot store two values associated with the same key. The values can
have any simple C types like integers or pointers.

 - Function: svz_hash_t * svz_hash_create (int SIZE, svz_free_func_t
    DESTRO)
  Create a new hash table with an initial capacity SIZE.  Return a
  non-zero pointer to the newly created hash.  The size is calculated
  down to a binary value.  The DESTROY callback allows you to pass a
  element destruction callback called within `svz_hash_clear()' and
  `svz_hash_destroy()' for each value.  If no such operation should be
  performed the argument must be `NULL'.

 - Function: void svz_hash_destroy (svz_hash_t * HAS)
  Destroy the existing hash table HASH.  Therefore we `svz_free()' all
  keys within the hash, the hash table and the hash itself.  The values
  in the hash keep untouched if the element destruction callback passed
  to `svz_hash_create()' was `NULL', otherwise it is called for each
  value.  If HASH is `NULL' no operation is performed.

 - Function: void svz_hash_clear (svz_hash_t * HAS)
  Clear the hash table of a given hash HASH.  Afterwards it does not
  contains any key.  In contradiction to `svz_hash_destroy()' this
  functions does not destroy the hash itself, but shrinks it to a
  minimal size.

 - Function: void * svz_hash_delete (svz_hash_t * HASH, char * KE)
  Delete an existing hash entry accessed via a given key KEY form the
  hash table HASH.  Return NULL if the key has not been found within
  the hash, otherwise the previous value.

 - Function: void * svz_hash_put (svz_hash_t * HASH, char * KEY, void *
    VALU)
  This function adds a new element consisting of KEY and VALUE to an
  existing hash HASH.  If the hash is 75% filled it gets rehashed (size
  will be doubled).  When the key already exists then the value just
  gets replaced dropping and returning the old value.  Note: This is
  sometimes the source of memory leaks.

 - Function: void * svz_hash_get (svz_hash_t * HASH, char * KE)
  Hash table lookup.  Find a value for a given KEY in the hash table
  HASH.  Return NULL if the key has not been found within the hash
  table.

 - Function: void ** svz_hash_values (svz_hash_t * HAS)
  This function delivers all values within a hash table HASH.  It
  returns NULL if there were no values in the hash.  You MUST
  `svz_hash_xfree()' a non-NULL return value in order to prevent memory
  leaks.

 - Function: char ** svz_hash_keys (svz_hash_t * HAS)
  This function delivers all keys within a hash table HASH.  It returns
  NULL if there were no keys in the hash.  You MUST `svz_hash_xfree()'
  a non-NULL return value.

 - Function: int svz_hash_size (svz_hash_t * HAS)
  This routine delivers the number of keys in the hash table HASH.  If
  the given HASH is `NULL' it returns zero.

 - Function: int svz_hash_capacity (svz_hash_t * HAS)
  This function returns the current capacity of a given hash table HASH.

 - Function: char * svz_hash_contains (svz_hash_t * HASH, void * VALU)
  This function can be used to determine if some key points to the VALUE
  argument in the hash table HASH.  Returns the appropriate key or NULL.

 - Function: int svz_hash_exists (svz_hash_t * HASH, char * KE)
  Returns a non-zero value if the given `key' is stored within the hash
  table `hash'.  Otherwise the function returns zero.  This function is
  useful when you cannot tell whether the return value of
  `svz_hash_get()' (`== NULL') indicates a real value in the hash or a
  non-existing hash key.

 - Macro: svz_hash_foreach_key (hash, iterarray, i)
  Iterator macro for walking over the keys of a hash.  Use like:
      char **allkeys; int i;
      svz_hash_foreach_key (hash, allkeys, i) {
        printf ("%s => %p\n", allkeys[i], svz_hash_get (hash, allkeys[i]));
      }
  Be sure you pass real variables and no expressions to this macro !
  Warning: Relatively slow implementation, builds up temporary array.
  Do not `break' or `return' from inside the loop or your program
  starts leaking memory ! Loop has to end normally.

 - Macro: svz_hash_foreach_value (hash, iterarray, i)
  Iterator macro for walking over the values of a hash.  Use like:
      type_t **values; int i;
      svz_hash_foreach_value (hash, values, i) {
        process_value (values[i]);
      }
  Be sure you pass real variables and no expressions to this macro !
  Warning: Relatively slow implementation, builds up temporary array.
  Do not `break' or `return' from inside the loop or your program
  starts leaking memory ! Loop has to end normally.


File: serveez-api.info,  Node: Sparsevector,  Next: Vectorlist,  Prev: Hashtable,  Up: Data structures

Sparsevector functions
----------------------

   A sparse vector is a kind of data array which grows and shrinks on
demand.  It unifies the advantages of chained lists (less memory usage
than simple arrays) and arrays (faster access to specific elements).
This implementation can handle gaps in between the array elements.

 - Function: svz_spvec_t * svz_spvec_create (VOI)
  Construct an empty sparse vector without initial capacity.  Return the
  newly created sparse vector.

 - Function: void svz_spvec_destroy (svz_spvec_t * SPVE)
  Destroy the given sparse vector SPVEC completely.  The argument
  cannot be used afterwards because it is invalid.

 - Function: void svz_spvec_add (svz_spvec_t * SPVEC, void * VALU)
  Appends the specified element VALUE at the end of the sparse vector
  SPVEC.

 - Function: void svz_spvec_clear (svz_spvec_t * SPVE)
  Removes all of the elements from the sparse vector SPVEC.  The sparse
  vector will be as clean as created with `svz_spvec_create()' then.

 - Function: unsigned long svz_spvec_contains (svz_spvec_t * SPVEC,
    void * VALU)
  Returns non-zero if the sparse vector SPVEC contains the specified
  element VALUE.

 - Function: void * svz_spvec_get (svz_spvec_t * SPVEC, unsigned long
    INDE)
  Returns the element at the specified position INDEX in the sparse
  vector SPVEC or `NULL' if there is no such element.

 - Function: unsigned long svz_spvec_index (svz_spvec_t * SPVEC, void *
    VALU)
  Searches for the first occurrence of the given argument VALUE.
  Return -1 if the value VALUE could not be found in the sparse vector
  SPVEC.

 - Function: void * svz_spvec_delete (svz_spvec_t * SPVEC, unsigned
    long INDE)
  Removes the element at the specified position INDEX in the sparse
  vector SPVEC and returns its previous value.

 - Function: unsigned long svz_spvec_delete_range (svz_spvec_t * SPVEC,
    unsigned long FROM, unsigned long T)
  Removes all of the elements whose index is between FROM (inclusive)
  and TO (exclusive) from the sparse vector SPVEC.  Returns the amount
  of actually deleted elements.

 - Function: void * svz_spvec_set (svz_spvec_t * SPVEC, unsigned long
    INDEX, void * VALU)
  Replaces the element at the specified position INDEX in the sparse
  vector SPVEC by the specified element VALUE and return its previous
  value.

 - Function: void * svz_spvec_unset (svz_spvec_t * SPVEC, unsigned long
    INDE)
  Delete the element at the given position INDEX from the sparse vector
  SPVEC but leave all following elements untouched (unlike
  `svz_spvec_delete()').  Return its previous value if there is one
  otherwise return `NULL'.

 - Function: unsigned long svz_spvec_size (svz_spvec_t * SPVE)
  Returns the number of elements in the sparse vector SPVEC.

 - Function: unsigned long svz_spvec_length (svz_spvec_t * SPVE)
  Returns the index of the last element of the sparse vector SPVEC plus
  one.

 - Function: void svz_spvec_insert (svz_spvec_t * SPVEC, unsigned long
    INDEX, void * VALU)
  Inserts the specified element VALUE at the given position INDEX in
  the sparse vector SPVEC.

 - Function: void ** svz_spvec_values (svz_spvec_t * SPVE)
  Delivers all values within the given sparse vector SPVEC in a single
  linear chunk.  You have to `svz_free()' it after usage.

 - Function: void svz_spvec_pack (svz_spvec_t * SPVE)
  Rearranges the given sparse vector SPVEC.  After that there are no
  more gaps within the sparse vector.  The index - value relationship
  gets totally lost by this operation.


File: serveez-api.info,  Node: Vectorlist,  Prev: Sparsevector,  Up: Data structures

Vectorlist functions
--------------------

   A vector list is an array of memory chunks with a fixed size. It
holds copies of the values you added to the vector list. When deleting
or inserting an element the indices of the following elements get
either decremented or incremented. This data structure is especially
useful if you actually want to forget about the pointers you put into
it for it saves copies and not the pointers itself.

 - Function: svz_vector_t * svz_vector_create (unsigned long SIZ)
  Create a new vector list without elements.  Each element will have
  the given size SIZE in bytes.

 - Function: void svz_vector_destroy (svz_vector_t * VE)
  Destroy a given vector list VEC.  This pointer is invalid afterwards.
  The routine `svz_free()'s all elements.

 - Function: unsigned long svz_vector_clear (svz_vector_t * VE)
  Delete all elements of the given vector list VEC.  What you will have
  then is an empty vector list.  Returns the previous length.

 - Function: unsigned long svz_vector_add (svz_vector_t * VEC, void *
    VALU)
  Add an element to the end of the given vector list VEC.  Return the
  position the element got. VALUE is a pointer to a chunk of the vector
  lists chunk size.

 - Function: void * svz_vector_get (svz_vector_t * VEC, unsigned long
    INDE)
  Get an vector list element of the vector list VEC at the given
  position INDEX.  Return `NULL' if the index is out of range.

 - Function: void * svz_vector_set (svz_vector_t * VEC, unsigned long
    INDEX, void * VALU)
  Overwrite the element at index INDEX in the vector list VEC with the
  given value VALUE.  Return `NULL' if the index is out of range or the
  pointer to the new element.

 - Function: unsigned long svz_vector_del (svz_vector_t * VEC, unsigned
    long INDE)
  Delete the element of the vector VEC at the position INDEX.  Return
  -1 if the given index is out of range otherwise the new length of the
  vector list.

 - Function: unsigned long svz_vector_ins (svz_vector_t * VEC, unsigned
    long INDEX, void * VALU)
  Insert the given element VALUE into the vector list VEC at the
  position INDEX.  Return the new length of the vector list or -1 if
  the index is out of range.

 - Function: unsigned long svz_vector_idx (svz_vector_t * VEC, void *
    VALU)
  Find the given value VALUE in the vector list VEC.  Return -1 if
  there is no such element or the index of the element.

 - Function: unsigned long svz_vector_contains (svz_vector_t * VEC,
    void * VALU)
  Return how often the vector list VEC contains the element given in
  VALUE.

 - Function: unsigned long svz_vector_length (svz_vector_t * VE)
  Return the current length of the vector list VEC.

 - Macro: svz_vector_foreach (vector, value, i)
  Iteration macro for the vector list VECTOR.  Each of its values gets
  assigned to VALUE.  The iteration variable I runs from 0 to the
  size-1 of the vector list.


File: serveez-api.info,  Node: Utility functions,  Next: Core functions,  Prev: Data structures,  Up: Embedding API

Utility functions
=================

   Within this section you will find some miscellaneous functionality
and left overs of the C API.

 - Function: void svz_log (int LEVEL, const char * FORMAT, ..)
  Print a message to the log system. LEVEL specifies the prefix.

 - Function: void svz_log_setfile (FILE * FIL)
  Set the file stream FILE to the log file all messages are printed to.
  Could also be `stdout' or `stderr'.

 - Variable: int svz_os_version
  Initial value: 0
  This variable contains the the runtime detected Win32 version.  Its
  value is setup in `svz_version()' and can be `Win32s' for Windows 3.x,
  `Win95' for Windows 95, `Win98' for Windows 98, `WinNT3x' for Windows
  NT 3.x, `WinNT4x' for Windows NT 4.x, `Win2k' for Windows 2000,
  `WinXP' for Windows XP and `WinME' for Windows ME.

   *Please note*: This variable is only available on Windows version of
this API.

 - Variable: int svz_errno
  Initial value: 0
  This variable contains the last system or network error occurred if
  it was detected and printed.  Needed for the "Resource unavailable"
  error condition.

 - Macro: SVZ_INT16 (p)
  Convert the byte array pointed to by P to a signed 16 bit integer.

 - Macro: SVZ_INT32 (p)
  Convert the byte array pointed to by P to a signed 32 bit integer.
  This is needed on aligned architectures where a plain type cast ends
  up in a fatal bus error.

 - Macro: SVZ_INT64 (p)
  Convert the byte array pointed to by P to a signed 64 bit integer.

 - Macro: SVZ_UINT16 (p)
  Convert the byte array pointed to by P to an unsigned 16 bit integer.

 - Macro: SVZ_UINT32 (p)
  Convert the byte array pointed to by P to an unsigned 32 bit integer.

 - Macro: SVZ_UINT64 (p)
  Convert the byte array pointed to by P to an unsigned 64 bit integer.

 - Macro: SVZ_NUM2PTR (n)
  Converts the integer value N into a pointer platform independently.
  Both of the `SVZ_NUM2PTR()' and `SVZ_PTR2NUM()' macros rely on the
  `(unsigned long)' having the same size as `(void *)'.

 - Macro: SVZ_PTR2NUM (p)
  Convert the pointer P into a integer value platform independently.

 - Function: int svz_hexdump (FILE * OUT, char * ACTION, int FROM, char
    * BUFFER, int LEN, int MA)
  Dump a BUFFER with the length LEN to the file stream OUT.  You can
  specify a description in ACTION.  The hexadecimal text representation
  of the given buffer will be either cut at LEN or MAX. FROM is a
  numerical identifier of the buffers creator.

 - Function: char * svz_itoa (unsigned INT)
  Converts an unsigned integer to its decimal string representation
  returning a pointer to an internal buffer, so copy the result.

 - Function: unsigned int svz_atoi (char * ST)
  Converts a given string STR in decimal format to an unsigned integer.
  Stops conversion on any invalid characters.

 - Function: char * svz_getcwd (VOI)
  Returns the current working directory.  The returned pointer needs to
  be `svz_free()''ed after usage.

 - Function: int svz_strcasecmp (const char * STR1, const char * STR)
  This is the system dependent case insensitive string compare.  It
  compares the strings STR1 and STR2 and returns zero if both strings
  are equal.

 - Function: int svz_strncasecmp (const char * STR1, const char * STR2,
    unsigned INT)
  The `svz_strncasecmp()' function compares the two strings STR1 and
  STR2, ignoring the case of the characters.  It returns an integer
  less than, equal to, or greater than zero if STR1 is found,
  respectively, to be less than, to match, or be greater than STR2.  It
  only compares the first N characters of STR1.

 - Function: int svz_openfiles (int MAX_SOCKET)
  This routine checks for the current and maximum limit of open files
  of the current process.  The function heavily depends on the
  underlying platform.  It tries to set the limit to the given
  MAX_SOCKETS amount.

 - Function: char * svz_time (LONG)
  Transform the given binary data T (UTC time) to an ASCII time text
  representation without any trailing characters.

 - Function: char * svz_uptime (long DIF)
  Create some kind of uptime string.  It tells how long the core library
  has been running.

 - Function: char * svz_tolower (char * ST)
  Convert the given string STR to lower case text representation.

 - Function: char * svz_sys_version (VOI)
  This routine is for detecting the operating system version of Win32
  and all Unices at runtime.  You should call it at least once at
  startup.  It saves its result in the variable `svz_os_version' and
  prints an appropriate message.

 - Function: char * svz_hstrerror (VOI)
  This is the `hstrerror()' wrapper function, depending on the
  configuration file `config.h'.

 - Function: char * svz_syserror (int N)
  Routine which forms a valid error message under Win32.  It might
  either use the `GetLastError()' or `WSAGetLastError()' in order to
  get a valid error code.

 - Function: int svz_snprintf (char * STR, unsigned int N, const char *
    FMT, ..)
  Implementation of the `snprintf()' if it is not defined.  It uses the
  `vsnprintf()' function therefore which will fall back to `vsprintf()'
  if `vsnprintf()' does not exist.


File: serveez-api.info,  Node: Core functions,  Next: Client connections,  Prev: Utility functions,  Up: Embedding API

Networking and other low level functions
========================================

   The following chapter deals with the basic networking and file
systems functions. It encapsulates systems calls in a portable manner.
These functions should behave identical on Windows and Unices.

 - Function: char * svz_inet_ntoa (unsigned long I)
  Converts the given ip address IP to the dotted decimal
  representation.  The string is a statically allocated buffer, please
  copy the result.  The given ip address MUST be in network byte order.

 - Function: int svz_inet_aton (char * STR, struct sockaddr_in * ADD)
  Converts the Internet host address STR from the standard
  numbers-and-dots notation into binary data and stores it in the
  structure that ADDR points to. `svz_inet_aton()' returns zero if the
  address is valid, nonzero if not.  This function handles an ip
  address of "*" special and sets `INADDR_ANY' for it.

 - Function: int svz_socket_connect (SOCKET SOCKFD, unsigned long HOST,
    unsigned short POR)
  Connect the given socket descriptor SOCKFD to the host HOST at the
  network port PORT.  Return non-zero on errors.

 - Function: SOCKET svz_socket_create (int PROT)
  Create a new non-blocking socket which does not get inherited on
  `exec()'.  The protocol is specified by PROTO.  Return the socket
  descriptor or -1 on errors.

 - Function: int svz_socket_create_pair (int PROTO, SOCKET DESC [2)
  This function creates an unnamed pair of connected sockets with the
  specified protocol PROTO.  The descriptors used in referencing the
  new sockets are returned in desc[0] and desc[1].  The two sockets are
  indistinguishable.  Also make both of them non-blocking and
  non-inheritable.  Returns -1 on failure, otherwise zero.

 - Function: int svz_socket_type (SOCKET FD, int * TYP)
  Saves the socket type (like `SOCK_STREAM', `SOCK_DGRAM', etc.)  of
  the socket FD in the buffer pointed to by TYPE.  Returns zero on
  success.

 - Function: int svz_fd_cloexec (int F)
  Set the close-on-exec flag of the given file descriptor FD and return
  zero on success.  Otherwise return non-zero.

 - Function: int svz_fd_nonblock (int F)
  Set the given file descriptor to nonblocking I/O.  This heavily
  differs in Win32 and Unix.  The given file descriptor FD must be a
  socket descriptor under Win32, otherwise the function fails.  Return
  zero on success, otherwise non-zero.

 - Function: int svz_fd_block (int F)
  Set the given file descriptor to blocking I/O.  This routine is the
  counter part to `svz_fd_nonblock()'.

 - Function: int svz_tcp_cork (SOCKET FD, int SE)
  Enable or disable the `TCP_CORK' socket option of the given socket
  descriptor FD.  This is useful for performance reasons when using
  `sendfile()' with any prepending or trailing data not inside the file
  to transmit.  The function return zero on success, otherwise non-zero.

 - Function: int svz_tcp_nodelay (SOCKET FD, int SET, int * OL)
  Enable or disable the `TCP_NODELAY' setting for the given socket
  descriptor FD depending on the flag SET.  In fact its turns the Nagle
  algorithm on or off.  This means that packets are always sent as soon
  as possible and no unnecessary delays are introduced.  The function
  saves the old setting if OLD is not `NULL'.  Returns zero on success,
  otherwise non-zero.

 - Function: int svz_sendfile (int OUT_FD, int IN_FD, off_t * OFFSET,
    unsigned int COUN)
  This function transmits data between one file descriptor and another
  where IN_FD is the source and OUT_FD the destination.  The OFFSET
  argument is a pointer to a variable holding the input file pointer
  position from which reading starts.  When this routine returns, the
  OFFSET variable will be set to the offset of the byte following the
  last byte that was read. COUNT is the number of bytes to copy between
  file descriptors.  Returns the number of bytes actually read/written
  or -1 on errors.

 - Function: int svz_open (const char * FILE, int FLAGS, unsigned int
    MOD)
  Open the filename FILE and convert it into a file handle.  The given
  FLAGS specify the access mode and the MODE argument the permissions
  if the `O_CREAT' flag is set.

 - Function: int svz_close (int F)
  Close the given file handle FD.  Return -1 on errors.

 - Function: int svz_fstat (int FD, struct stat * BU)
  Return information about the specified file associated with the file
  descriptor FD returned by `svz_open()'.  Stores available information
  in the stat buffer BUF.

 - Function: FILE * svz_fopen (const char * FILE, const char * MOD)
  Open the file whose name is the string pointed to by FILE and
  associates a stream with it.

 - Function: int svz_fclose (FILE * )
  Dissociates the named stream F from its underlying file.

 - Function: char * svz_file_path (char * PATH, char * FIL)
  Constructs a fully qualified file name form PATH and FILE.  If PATH
  is omitted (`NULL') the function returns FILE only.  If FILE is
  `NULL' a null pointer is returned.  Please remember to `svz_free()'
  the returned pointer.

 - Function: int svz_file_check (char * FIL)
  Checks for the existence of the given file system node FILE and
  return zero on success.  Otherwise the function returns non-zero.


File: serveez-api.info,  Node: Client connections,  Next: Socket,  Prev: Core functions,  Up: Embedding API

Client connections
==================

   Serveez tries to handle all kinds of Internet protocols like TCP
(connection oriented), UDP, ICMP and RAW (packet oriented) and
communication across named pipes (also connection oriented) in the same
way. Therefore it uses a structure called `svz_socket_t' which is the
abstraction of any kind of communication endpoint (can be client or
server or both together).

* Menu:

* TCP sockets::                   TCP socket functions
* Pipe connections::              Named and anonymous pipe functions
* UDP sockets::                   UDP socket functions
* ICMP sockets::                  ICMP socket functions
* Raw sockets::                   Raw socket functions
* Passthrough connections::       Passthrough connections to child processes


File: serveez-api.info,  Node: TCP sockets,  Next: Pipe connections,  Up: Client connections

TCP sockets
-----------

   TCP sockets provide a reliable, stream oriented, full duplex
connection between two sockets on top of the Internet Protocol (IP).
TCP guarantees that the data arrives in order and retransmits lost
packets. It generates and checks a per packet checksum to catch
transmission errors. TCP does not preserve record boundaries.

 - Function: svz_socket_t * svz_tcp_connect (unsigned long HOST,
    unsigned short POR)
  Create a TCP connection to host HOST and set the socket descriptor in
  structure SOCK to the resulting socket.  Return a zero value on
  errors.

 - Function: int svz_tcp_default_connect (svz_socket_t * SOC)
  The default routine for connecting a socket SOCK.  When we get
  `select()'ed or `poll()'ed via the WRITE_SET we simply check for
  network errors,

 - Function: int svz_tcp_read_socket (svz_socket_t * SOC)
  Default function for reading from the socket SOCK.  This function
  only reads all data from the socket and calls the `check_request()'
  function for the socket, if set.  Returns -1 if the socket has died,
  returns zero otherwise.

 - Function: int svz_tcp_write_socket (svz_socket_t * SOC)
  Default function for writing to the socket SOCK.  Simply flushes the
  output buffer to the network.  Write as much as possible into the
  socket SOCK.  Writing is performed non-blocking, so only as much as
  fits into the network buffer will be written on each call.

 - Function: int svz_tcp_recv_oob (svz_socket_t * SOC)
  This function is the default `read_socket_oob()' callback for TCP
  sockets.  It stores the received out-of-band data (a single byte
  only) in `sock->oob' and runs the `check_request_oob()' callback if
  it is set properly.  Returns -1 on failure and zero otherwise.  The
  function does not do anything if the underlying operating system does
  not support urgent data and simply returns -1.

 - Function: int svz_tcp_send_oob (svz_socket_t * SOC)
  If the underlying operating system supports urgent data (out-of-band)
  in TCP streams this function tries to send the byte in `sock->oob'
  through the socket structure SOCK as out-of-band data.  The function
  returns zero on success and -1 otherwise (also if urgent data is not
  supported).


File: serveez-api.info,  Node: Pipe connections,  Next: UDP sockets,  Prev: TCP sockets,  Up: Client connections

Pipe connections
----------------

   The pipe implementations supports both named and anonymous pipes.
Pipe servers are implemented as listeners on a file system FIFO on
Unices or "Named Pipes" on Windows (can be shared over a Windows
network).

   A FIFO special file is similar to a pipe, except that it is created
in a different way. Instead of being an anonymous communications
channel, a FIFO special file is entered into the file system.

   Once you have created a FIFO special file in this way, any process
can open it for reading or writing, in the same way as an ordinary
file. However, it has to be open at both ends simultaneously before you
can proceed to do any input or output operations on it.

 - Function: int svz_pipe_startup (VOI)
  Startup the pipe interface of the core API of serveez.  Returns zero
  on success.  Gets called from `svz_boot()' once.  Do not use.

 - Function: int svz_pipe_cleanup (VOI)
  Cleanup the pipe interface of the core API of serveez.  Returns zero
  on success.  Gets called from `svz_halt()' once.  Do not use.

 - Function: svz_pipe_t * svz_pipe_alloc (VOI)
  Return a newly allocated and setup to some defaults pipe structure.

 - Function: void svz_pipe_destroy (svz_pipe_t * PIP)
  Destroy the given pipe structure PIPE.

 - Function: int svz_pipe_valid (svz_socket_t * SOC)
  This function is for checking if a given socket structure contains a
  valid pipe socket (checking both pipes).  Return non-zero on errors.

 - Function: int svz_pipe_read_socket (svz_socket_t * SOC)
  The `svz_pipe_read_socket()' function reads as much data as available
  on a readable pipe descriptor or handle on Win32.  Return a non-zero
  value on errors.

 - Function: int svz_pipe_write_socket (svz_socket_t * SOC)
  This `svz_pipe_write_socket()' function writes as much data as
  possible into a writable pipe descriptor.  It returns a non-zero value
  on errors.

 - Function: int svz_pipe_disconnect (svz_socket_t * SOC)
  This function is the default disconnection routine for pipe socket
  structures.  Return non-zero on errors.

 - Function: svz_socket_t * svz_pipe_create (HANDLE RECV_FD, HANDLE
    SEND_F)
  Create a socket structure containing both the pipe descriptors
  RECV_FD and SEND_FD.  Return `NULL' on errors.

 - Function: int svz_pipe_create_pair (HANDLE PIPE_DESC [2)
  Create a (non blocking) pair of pipes.  This differs in Win32 and
  Unices.  Return a non-zero value on errors.

 - Function: svz_socket_t * svz_pipe_connect (svz_pipe_t * RECV,
    svz_pipe_t * SEN)
  This routine creates a pipe connection socket structure to a pair of
  named pipes.  Return `NULL' on errors.

 - Function: int svz_pipe_listener (svz_socket_t * SOCK, svz_pipe_t *
    RECV, svz_pipe_t * SEN)
  Prepare the server socket structure SOCK for listening on the
  receiving pipe of RECV.  Open the reading end of such a connection.
  Return either zero or non-zero on errors.

 - Function: int svz_pipe_check_user (svz_pipe_t * PIP)
  Check the consistency of the "user" - "user id" pair in the given pipe
  structure PIPE.  Return zero if it is ok.

 - Function: int svz_pipe_check_group (svz_pipe_t * PIP)
  Check the consistency of the "group" - "group id" pair in the
  structure PIPE.  Return zero if it is valid.


File: serveez-api.info,  Node: UDP sockets,  Next: ICMP sockets,  Prev: Pipe connections,  Up: Client connections

UDP sockets
-----------

   The UDP sockets implement a connectionless, unreliable datagram
packet service. Packets may be reordered or duplicated before they
arrive. UDP generates and checks checksums to catch transmission errors.

 - Function: int svz_udp_read_socket (svz_socket_t * SOC)
  This routine is the default reader for UDP sockets.  Whenever the
  socket descriptor is `select()''ed for reading it is called by
  default and reads as much data as possible (whole packets only) and
  saves the sender into the `sock->remote_addr' field.  The packet load
  is written into `sock->recv_buffer'.

 - Function: int svz_udp_lazy_read_socket (svz_socket_t * SOC)
  This routine is the default reader for UDP server sockets.  It
  allocates necessary buffers (that's why it's called lazy) and reverts
  to the default `svz_udp_read_socket()'.

 - Function: int svz_udp_write_socket (svz_socket_t * SOC)
  The `svz_udp_write_socket()' callback should be called whenever the
  UDP socket descriptor is ready for sending.  It sends a single packet
  within the `sock->send_buffer' to the destination address specified
  by `sock->remote_addr' and `sock->remote_port'.

 - Function: int svz_udp_check_request (svz_socket_t * SOC)
  This is the default `check_request()' routine for UDP servers.
  Whenever new data arrived at an UDP server socket we call this
  function to process the packet data.  Any given `handle_request()'
  callback MUST return zero if it successfully processed the data and
  non-zero if it could not.

 - Function: svz_socket_t * svz_udp_connect (unsigned long HOST,
    unsigned short POR)
  Create a UDP connection to HOST and set the socket descriptor in
  structure SOCK to the resulting socket.  Return a `NULL' value on
  errors.  This function can be used for port bouncing.  If you assign
  the `handle_request' callback to something server specific and the
  CFG field to the server's configuration to the returned socket
  structure this socket is able to handle a dedicated UDP connection to
  some other UDP server.

 - Function: int svz_udp_write (svz_socket_t * SOCK, char * BUF, int
    LENGT)
  Write the given BUF into the send queue of the UDP socket.  If the
  length argument supersedes the maximum length for UDP messages it is
  split into smaller packets.

 - Function: int svz_udp_printf (svz_socket_t * SOCK, const char * FMT,
    ..)
  Print a formatted string on the UDP socket SOCK. FMT is the
  printf()-style format string, which describes how to format the
  optional arguments.  See the printf(3) manual page for details.  The
  destination address and port is saved for sending.  This you might
  specify them in `sock->remote_addr' and `sock->remote_port'.


File: serveez-api.info,  Node: ICMP sockets,  Next: Raw sockets,  Prev: UDP sockets,  Up: Client connections

ICMP sockets
------------

   The ICMP socket implementation is currently used in the tunnel
server which comes with the Serveez package. It implements a user
protocol receiving and sending ICMP packets by opening a raw socket
with the protocol IPPROTO_ICMP.

   The types of ICMP packets passed to the socket can be filtered using
the ICMP_FILTER socket option (or by software as done here). ICMP
packets are always processed by the kernel too, even when passed to a
user socket.

 - Function: void svz_icmp_startup (VOI)
  Load the `ICMP.DLL' library into process address space and get all
  necessary function pointers.

 - Function: void svz_icmp_cleanup (VOI)
  Shutdown the ping service.

 - Function: int svz_icmp_read_socket (svz_socket_t * SOC)
  Default reader for ICMP sockets.  The sender is stored within
  `sock->remote_addr' and `sock->remote_port' afterwards.

 - Function: int svz_icmp_lazy_read_socket (svz_socket_t * SOC)
  Default reader for ICMP server sockets.  Allocates necessary buffers
  and reverts to `svz_icmp_read_socket()'.

 - Function: int svz_icmp_write_socket (svz_socket_t * SOC)
  The default ICMP write callback is called whenever the socket
  descriptor has been `select()''ed or `poll()''ed to be ready for
  sending.

 - Function: int svz_icmp_check_request (svz_socket_t * SOC)
  Default `check_request()' callback for ICMP sockets.

 - Function: svz_socket_t * svz_icmp_connect (unsigned long HOST,
    unsigned short PORT, unsigned char TYP)
  This function creates an ICMP socket for receiving and sending.
  Return `NULL' on errors, otherwise an enqueued socket structure.

 - Function: int svz_icmp_send_control (svz_socket_t * SOCK,
    svz_uint8_t TYP)
  If you are calling this function we will send an empty ICMP packet
  signaling that this connection is going down soon.

 - Function: int svz_icmp_write (svz_socket_t * SOCK, char * BUF, int
    LENGT)
  Send a given buffer BUF with length LENGTH via this ICMP socket.  If
  the length argument supersedes the maximum ICMP message size the
  buffer is split into smaller packets.

 - Function: int svz_icmp_printf (svz_socket_t * SOCK, const char *
    FMT, ..)
  Put a formatted string to the icmp socket SOCK.  Packet length and
  destination address are additionally saved to the send buffer.  The
  destination is taken from `sock->remote_addr'.  Furthermore a valid
  icmp header is stored in front of the actual packet data.


File: serveez-api.info,  Node: Raw sockets,  Next: Passthrough connections,  Prev: ICMP sockets,  Up: Client connections

Raw sockets
-----------

   A raw socket receives or sends the raw datagram not including link
level headers. It is currently used by the ICMP socket implementation of
the core library. The IPv4 layer generates an IP header when sending a
packet unless the IP_HDRINCL socket option is enabled on the socket.
When it is enabled, the packet must contain an IP header. For receiving
the IP header is always included in the packet.

   Only processes with an effective userid of 0 (Administrator or root)
or the CAP_NET_RAW capability are allowed to open raw sockets. All
packets or errors matching the protocol number specified for the raw
socket are passed to this socket. A protocol of IPPROTO_RAW implies
enabled IP_HDRINCL and receives all IP protocols. Sending is not
allowed.

 - Function: svz_ip_header_t * svz_raw_get_ip_header (svz_uint8_t * DAT)
  Get IP header from plain data.

 - Function: svz_uint8_t * svz_raw_put_ip_header (svz_ip_header_t * HD)
  Put IP header to plain data.  This is currently not in use but can be
  used when creating raw sockets with setsockopt (SOL_IP, IP_HDRINCL).

 - Function: unsigned short svz_raw_ip_checksum (svz_uint8_t * DATA,
    int LE)
  Recalculate any IP checksum.

 - Function: int svz_raw_check_ip_header (svz_uint8_t * DATA, int LE)
  Checking the IP header only.  Return the length of the header if it
  is valid, otherwise -1.


File: serveez-api.info,  Node: Passthrough connections,  Prev: Raw sockets,  Up: Client connections

Passthrough connections
-----------------------

   The function subset described in the following section allows the
user to passthrough client connections to the standard input (stdin)
and standard output (stdout) handles of external programs.  Some of the
routines deal with the management of program environments.  Basically
there are two methods how to passthrough a duplex connection: the
Unix'ish `fork()' and `exec()' method and the shuffle method where the
main process keeps control over the communication on the original
duplex connection and passes this data through two pairs of pipes or
yet another socket connection to the child process.  All of the three
method are implemented calling them `SVZ_PROCESS_FORK',
`SVZ_PROCESS_SHUFFLE_PIPE' and `SVZ_PROCESS_SHUFFLE_SOCK'.

 - Function: int svz_sock_process (svz_socket_t * SOCK, char * BIN,
    char * DIR, char ** ARGV, svz_envblock_t * ENVP, int FLAG, char *
    USE)
  This routine starts a new program specified by BIN passing the socket
  or pipe descriptor(s) in the socket structure SOCK to its stdin and
  stdout.  The BIN argument has to contain a fully qualified executable
  file name and the DIR argument contains the working directory of the
  new process.  The directory is not changed when this argument is
  `NULL'.  The program arguments and the environment of the new process
  can be passed in ARGV and ENVP.  Please note that `argv[0]' has to be
  set to the program's name, otherwise it defaults to BIN if it
  contains `NULL'.  The FLAG argument specifies the method used to
  passthrough the connection.  It can be either `SVZ_PROCESS_FORK' (in
  order to pass the pipe descriptors or the socket descriptor directly
  through `fork()' and `exec()') or `SVZ_PROCESS_SHUFFLE_PIPE' /
  `SVZ_PROCESS_SHUFFLE_SOCK' (in order to pass the socket transactions
  via a pair of pipes or sockets).  You can pass the user and group
  identifications in the format `user[.group]' (group is optional), as
  `SVZ_PROCESS_NONE' or `SVZ_PROCESS_OWNER' in the USER argument.  This
  specifies the permissions of the new child process.  If
  `SVZ_PROCESS_OWNER' is passed the permissions are set to the
  executable file BIN owner; `SVZ_PROCESS_NONE' does not change user or
  group.  The function returns -1 on failure and otherwise the new
  process's pid.

 - Function: int svz_process_disconnect (svz_socket_t * SOC)
  Disconnection routine for the socket connection SOCK which is
  connected with a process's stdin/stdout via the referring passthrough
  socket structure which gets also scheduled for shutdown if possible.

 - Function: int svz_process_disconnect_passthrough (svz_socket_t * SOC)
  Disconnection routine for the passthrough socket structure SOCK
  connected with a process's stdin/stdout.  Schedules the referring
  socket connection for shutdown if necessary and possible.

 - Function: int svz_process_check_request (svz_socket_t * SOC)
  Check request routine for the original passthrough connection SOCK.
  Sets the send buffer fill counter of the referring socket structure
  which is the passthrough connection in order to schedule it for
  sending.

 - Function: int svz_process_idle (svz_socket_t * SOC)
  Idle function for the passthrough shuffle connection SOCK.  The
  routine checks whether the spawned child process is still valid.  If
  not it schedules the connection for shutdown.  The routine schedules
  itself once a second.

 - Function: int svz_process_send_pipe (svz_socket_t * SOC)
  This is the shuffle pipe writer (reading end of a process's stdin).
  It writes as much data as possible from the send buffer which is the
  receive buffer of the referring socket structure.  Returns non-zero
  on errors.

 - Function: int svz_process_recv_pipe (svz_socket_t * SOC)
  This is the shuffle pipe reader (writing end of a process's stdout).
  It reads as much data as possible into its receive buffer which is
  the send buffer of the connection this passthrough pipe socket
  structure stems from.

 - Function: int svz_process_send_socket (svz_socket_t * SOC)
  This is the shuffle socket pair writer which is directly connected
  with the reading end of the child process.  It writes as much data as
  possible from its send buffer which is the receive buffer of the
  original passthrough connection.

 - Function: int svz_process_recv_socket (svz_socket_t * SOC)
  This is the shuffle socket pair reader which is directly connected
  with the writing end of the child process.  It reads as much data as
  possible into its receive buffer which is the send buffer of the
  original passthrough connection.

 - Function: int svz_process_create_child (svz_process_t * PRO)
  Spawns a new child process.  The given PROC argument contains all
  information necessary to set a working directory, assign a new user
  defined stdin and stdout of the new process, to set up a process
  environment, pass a command line to the new process and to specify a
  user and group identification the child process should have.  The
  routine returns -1 on failure, otherwise the new child program's
  process id.

   *Please note*: On M$-Windows platforms it is not possible to pass a
socket connection to a child process's stdin/stdout.  That is why this
function creates an inheritable version of the socket and puts the
socket handle number into the environment variables `SEND_HANDLE' and
`RECV_HANDLE'.  A spawned child process can use these handles as if
these were created by itself.  After calling `WSAStartup()' the child
process can `send()' and `recv()' as usual.

 - Function: int svz_process_shuffle (svz_process_t * PRO)
  Creates two pairs of pipes in order to passthrough the transactions of
  the a socket structure.  The function create a new socket structure
  and sets it up for handling the transactions automatically.  The given
  argument PROC contains the information inherited from
  `svz_sock_process()'.  The function returns -1 on failure and the new
  child's process id otherwise.

 - Function: int svz_process_fork (svz_process_t * PRO)
  Fork the current process and execute a new child program.  The given
  argument PROC contains the information inherited from
  `svz_sock_process()'.  The routine passes the socket or pipe
  descriptors of the original passthrough socket structure to stdin and
  stdout of the child.  The caller is responsible for shutting down the
  original socket structure.  Returns -1 on errors and the child's
  process id on success.

 - Function: int svz_process_check_executable (char * FILE, char ** AP)
  Check if the given FILE is an executable (script or binary program).
  If it is script the routine returns an application able to execute
  the script in APP.  Returns zero on success, non-zero otherwise.

 - Function: int svz_process_split_usergroup (char * STR, char ** USER,
    char ** GROU)
  Splits the given character string STR in the format `user[.group]'
  into a user name and a group name and stores pointers to it in USER
  and GROUP.  If the group has been omitted in the format string then
  GROUP is `NULL' afterwards.  The function returns zero on success, or
  non-zero if the given arguments have been invalid.

 - Function: int svz_process_check_access (char * FILE, char * USE)
  Try setting the user and group for the current process specified by
  the given executable file FILE and the USER argument.  If USER equals
  `SVZ_PROCESS_NONE' no user or group is set.  When you pass
  `SVZ_PROCESS_OWNER' in the USER argument the FILE's owner will be
  set.  Otherwise USER specifies the user and group identification in
  the format `user[.group]'.  If you omit the group information the
  routine uses the primary group of the user.  Returns zero on success,
  non-zero otherwise.

 - Function: svz_envblock_t * svz_envblock_create (VOI)
  Create a fresh environment block.  The returned pointer can be used
  to pass it to `svz_envblock_default()' and `svz_envblock_add()'.  Its
  size is initially set to zero.

 - Function: int svz_envblock_default (svz_envblock_t * EN)
  Fill the given environment block ENV with the current process's
  environment variables.  If the environment ENV contained any
  information before these will be overridden.

 - Function: int svz_envblock_add (svz_envblock_t * ENV, char * FORMAT,
    ..)
  Insert a new environment variable into the given environment block
  ENV.  The FORMAT argument is a printf()-style format string
  describing how to format the optional arguments.  You specify
  environment variables in the `VAR=VALUE' format.

 - Function: int svz_envblock_free (svz_envblock_t * EN)
  This function releases all environment variables currently stored in
  the given environment block ENV.  The block will be as clean as
  returned by `svz_envblock_create()' afterwards.

 - Function: void svz_envblock_destroy (svz_envblock_t * EN)
  Destroys the given environment block ENV completely.  The ENV
  argument is invalid afterwards and should therefore not be referenced
  then.

 - Function: svz_envp_t svz_envblock_get (svz_envblock_t * EN)
  Unfortunately the layout of environment blocks in Unices and Windows
  differ.  On Unices you have a NULL terminated array of character
  strings and on Windows systems you have a simple character string
  containing the environment variables in the format VAR=VALUE each
  separated by a zero byte.  The end of the list is indicated by a
  further zero byte.  The following routine converts the given
  environment block ENV into something which can be passed to `exeve()'
  (Unix) or `CreateProcess()' (Windows).  The routine additionally
  sorts the environment block on Windows systems since it is using
  sorted environments.

 - Macro: svz_envblock_setup ()
  This macro must be called once after `svz_boot()' for setting up the
  `svz_environ' variable.  It simply passes the `environ' variable of
  the calling application to the underlying Serveez core API.  This is
  necessary to make the `svz_envblock_default()' function working
  correctly.

 - Variable: char * * svz_environ
  Initial value: NULL
  This variable is meant to hold the `environ' variable of the
  application using the Serveez core API.  It must be setup via the
  macro `svz_envblock_setup()'.


File: serveez-api.info,  Node: Socket,  Next: Coserver,  Prev: Client connections,  Up: Embedding API

Socket management
=================

   The function subset described in the following section deals with the
creation, destruction and other simple operations on socket structures
called `svz_socket_t'. See for the details at the description of each
function which kind of socket it can handle and what they are for.

 - Variable: int svz_sock_connections
  Initial value: 0
  Count the number of currently connected sockets.

 - Function: int svz_sock_valid (svz_socket_t * SOC)
  Check if a given socket is still valid.  Return non-zero if it is not.

 - Function: svz_socket_t * svz_sock_alloc (VOI)
  Allocate a structure of type `svz_socket_t' and initialize its data
  fields.  Assign some of the default callbacks for TCP connections.

 - Function: int svz_sock_free (svz_socket_t * SOC)
  Free the socket structure SOCK.  Return a non-zero value on error.

 - Function: svz_socket_t * svz_sock_create (int F)
  Create a socket structure from the file descriptor FD.  Set the
  socket descriptor to non-blocking I/O.  Return `NULL' on errors.

 - Function: int svz_sock_disconnect (svz_socket_t * SOC)
  Disconnect the socket SOCK from the network and calls the disconnect
  function for the socket if set.  Return a non-zero value on errors.

 - Function: int svz_sock_write (svz_socket_t * SOCK, char * BUF, int
    LE)
  Write LEN bytes from the memory location pointed to by BUF to the
  output buffer of the socket SOCK.  Also try to flush the buffer to
  the socket of SOCK if possible.  Return a non-zero value on error,
  which normally means a buffer overflow.

 - Function: int svz_sock_printf (svz_socket_t * SOCK, const char *
    FMT, ..)
  Print a formatted string on the socket SOCK. FMT is the
  printf()-style format string, which describes how to format the
  optional arguments.  See the printf(3) manual page for details.

 - Function: int svz_sock_resize_buffers (svz_socket_t * SOCK, int
    SEND_BUF_SIZE, int RECV_BUF_SIZ)
  Resize the send and receive buffers for the socket SOCK.
  SEND_BUF_SIZE is the new size for the send buffer, RECV_BUF_SIZE for
  the receive buffer.  Note that data may be lost when the buffers
  shrink.  For a new buffer size of 0 the buffer is freed and the
  pointer set to NULL.

 - Function: int svz_sock_intern_connection_info (svz_socket_t * SOC)
  Get local and remote addresses and ports of socket SOCK and save them
  into the socket structure.

 - Function: int svz_sock_local_info (svz_socket_t * SOCK, unsigned
    long * ADDR, unsigned short * POR)
  This function returns the local network address and port for the given
  client socket structure SOCK.  It returns non-zero if there no
  connection established.

 - Function: int svz_sock_error_info (svz_socket_t * SOC)
  Get and clear the pending socket error of a given socket.  Print the
  result to the log file.

 - Function: int svz_sock_unique_id (svz_socket_t * SOC)
  Calculate unique socket structure id and assign a version for a given
  SOCK.  The version is for validating socket structures.  It is
  currently used in the coserver callbacks.

 - Function: int svz_sock_detect_proto (svz_socket_t * SOC)
  This routine gets called whenever data is read from a client socket
  accepted by any connection oriented protocol layer (TCP or PIPE).  We
  try to detect the data streams protocol here.

 - Function: int svz_sock_check_request (svz_socket_t * SOC)
  This function simply checks for the kind of packet delimiter within
  the given socket structure and and assigns one of the default
  `check_request()' routines (one or more byte delimiters or a fixed
  size).  Afterwards this routine will never ever be called again
  because the callback gets overwritten here.

 - Function: int svz_sock_idle_protect (svz_socket_t * SOC)
  Default idle function.  This routine simply checks for "dead"
  (non-receiving) sockets (connection oriented protocols only) and
  rejects them by return a non-zero value.

 - Function: int svz_sock_flood_protect (svz_socket_t * SOCK, int
    NUM_REA)
  This routine can be called if flood protection is wished for socket
  readers.  Return non-zero if the socket should be kicked because of
  flood.

 - Macro: svz_sock_reduce_recv (sock, len)
  Shorten the receive buffer of SOCK by LEN bytes.

 - Macro: svz_sock_reduce_send (sock, len)
  Reduce the send buffer of SOCK by LEN bytes.


File: serveez-api.info,  Node: Coserver,  Next: Codec,  Prev: Socket,  Up: Embedding API

Coserver functions
==================

   The following section describes the internal coserver interface of
serveez.  Coservers are helper processes meant to perform blocking
tasks. This is going to be necessary because serveez itself is single
threaded. Each coserver is connected via a pair of pipes to the main
thread of serveez communicating over a simple text line protocol. Each
request/response is separated by a newline character.

   If the user wants to use these processes you need to start the
coserver interface by calling `svz_coserver_init()' once before
entering the main server loop and shut it down afterwards by calling
`svz_coserver_finalize()'.

 - Variable: svz_coservertype_t svz_coservertypes
  This static array contains the coserver structure for each type of
  internal coserver the core library provides.

 - Variable: svz_array_t * svz_coservers
  Initial value: NULL
  Internal coserver instances.

 - Function: void svz_coserver_check (VOI)
  Call this routine whenever there is time, e.g. within the timeout of
  the `select()' statement.  Indeed I built it in the
  `svz_periodic_tasks()' statement.  Under Wind32 the routine checks if
  there was any response from an active coserver.  Moreover it keeps
  the coserver threads/processes alive.  If one of the coservers dies
  due to buffer overrun or might be overloaded this function starts a
  new one.

 - Function: int svz_coserver_init (VOI)
  Global coserver initialization.  Here you should start all the
  internal coservers you want to use later.

 - Function: int svz_coserver_finalize (VOI)
  Global coserver finalization.

 - Function: void svz_coserver_destroy (int TYP)
  Destroy specific coservers with the type TYPE.  This works for Win32
  and Unices.  All instances of this coserver type will be stopped.

 - Function: void svz_coserver_create (int TYP)
  Create a single coserver with the given type TYPE.

 - Function: void svz_coserver_send_request (int TYPE, char * REQUEST,
    svz_coserver_handle_result_t HANDLE_RESULT, SVZ_COSERVER_ARGS_)
  Invoke a REQUEST for one of the running internal coservers with type
  TYPE. HANDLE_RESULT and ARG specify what should happen if the
  coserver delivers a result.

 - Function: void svz_coserver_rdns_invoke (unsigned long IP,
    svz_coserver_handle_result_t CB, SVZ_COSERVER_ARGS_)
  This is a wrapper function for the reverse DNS lookup coserver.

 - Macro: svz_coserver_rdns (ip, cb, arg0, arg1)
  This macro is considered to be the usual way to make a request to the
  reverse DNS coserver.  It calls `svz_coserver_rdns_invoke()'
  therefore.  If the given IP has been resolved by the coserver to a
  valid computer name the callback CB gets invoked with the additional
  arguments passed to this macro.

 - Function: void svz_coserver_dns_invoke (char * HOST,
    svz_coserver_handle_result_t CB, SVZ_COSERVER_ARGS_)
  Wrapper for the DNS coserver.

 - Macro: svz_coserver_dns (host, cb, arg0, arg1)
  This macro is the usual way to make use of the internal DNS coserver.
  When the given computer name HOST has been resolved to a valid ip
  address the function CB will be called with the additional arguments
  ARG0 and ARG1.

 - Function: void svz_coserver_ident_invoke (svz_socket_t * SOCK,
    svz_coserver_handle_result_t CB, SVZ_COSERVER_ARGS_)
  Wrapper for the ident coserver.

 - Macro: svz_coserver_ident (sock, cb, arg0, arg1)
  This macro uses the internal ident coserver in order to identify the
  connection of the given socket structure SOCK.  The function CB will
  be called when the coserver successfully delivers the identified user
  on the other end of the connection.  Both the arguments ARG0 and ARG1
  are passed to CB.


File: serveez-api.info,  Node: Codec,  Next: Server types,  Prev: Coserver,  Up: Embedding API

Codec functions
===============

   The codec interface of the serveez core API supplies routines for
setting up socket structures to perform encoding or decoding of its
receive or send buffers. It is a transparent layer of buffer
transition. The interface itself tries to unify different types of
codecs. In order to add a new codec the programmer needs to write some
wrapper functions around the actual implementation to fulfil certain
entry and exit semantics of this interface.

 - Function: void svz_codec_list (VOI)
  Prints the text representation of the list of known codecs registered
  within the core library.  This includes all encoder and decoder once
  ran through `svz_codec_register()'.

 - Function: svz_codec_t * svz_codec_get (char * DESCRIPTION, int TYP)
  Find an appropriate codec for the given DESCRIPTION and TYPE which
  can be either `SVZ_CODEC_ENCODER' or `SVZ_CODEC_DECODER'.  The
  function returns `NULL' if there is no such codec registered.

 - Function: int svz_codec_init (VOI)
  This routine is called by `svz_boot()' and registers the builtin
  codecs.

 - Function: int svz_codec_finalize (VOI)
  This routine is called by `svz_halt()' and destroys the list of known
  codecs.

 - Function: void svz_codec_ratio (svz_codec_t * CODEC,
    svz_codec_data_t * DAT)
  Print a text representation of a codec's current ratio in percent if
  possible.

 - Function: int svz_codec_register (svz_codec_t * CODE)
  Register the given codec CODEC.  Does not register invalid or
  duplicate codecs.  Returns zero on success, non-zero otherwise.

 - Function: int svz_codec_unregister (svz_codec_t * CODE)
  Removes the given codec CODEC from the list of known codecs.  Returns
  zero if the codec could be successfully removed, non-zero otherwise.

 - Function: int svz_codec_sock_receive_setup (svz_socket_t * SOCK,
    svz_codec_t * CODE)
  Setup the given socket structure SOCK to decode or encode its receive
  data via the codec CODEC.  Therefore you must have setup the
  `check_request' method previously.  The function returns zero on
  success, non-zero otherwise.

 - Function: int svz_codec_sock_receive (svz_socket_t * SOC)
  This routine is the new `check_request' callback for reading codecs.
  It is applied in the above `svz_codec_sock_receive_setup()' function.
  Usually it gets called whenever there is data in the receive buffer.
  It lets the current receive buffer be the input of the codec.  The
  output buffer of the codec gets the new receive buffer buffer of the
  socket structure SOCK.  The old `check_request' callback of SOCK gets
  called afterwards.  When leaving this functions the receive buffer
  gets restored again with the bytes snipped consumed by the codec
  itself.

 - Function: int svz_codec_sock_send_setup (svz_socket_t * SOCK,
    svz_codec_t * CODE)
  Setup the socket structure SOCK for encoding or decoding its send
  buffer via the given codec CODEC.  Therefore you previously need to
  assign the `write_socket' member of SOCK properly.  The function
  returns zero on success, non-zero otherwise.

 - Function: int svz_codec_sock_send (svz_socket_t * SOC)
  This is a codec socket structures SOCK new `write_socket' callback
  which is called whenever there is data within the send buffer
  available and SOCK is scheduled for writing.  It uses the current
  send buffer as input buffer for the codec.  The output buffer of the
  codec is used to invoke the `write_socket' callback saved within
  `svz_codec_sock_send_setup()'.  After this the send buffer is
  restored again without the bytes consumed by the codec.

 - Function: int svz_codec_sock_disconnect (svz_socket_t * SOC)
  This callback is used as the `disconnected_socket' callback of the
  socket structure SOCK.  It tries to release the resources of both the
  receiving and sending codec of SOCK.  The routine is called by
  default if the codec socket structure SOCK gets disconnected for some
  external reason.

 - Function: svz_codec_t * svz_codec_sock_detect (svz_socket_t * SOC)
  This routine can be used to detect a codec on the receive buffer of
  the given socket structure SOCK.  It returns a valid codec or `NULL'
  if no codec could be detected.


File: serveez-api.info,  Node: Server types,  Next: Server,  Prev: Codec,  Up: Embedding API

Server type functions
=====================

   As already noted in the main serveez manual a server type is the
main specification of the abilities and configuration items of a server
which can be instantiated. It is represented by the C structure
`svz_servertype_t' in serveez. It contains server specific members like
its name, different callbacks, a single default configuration and a
list of configuration items which determines what can be configured.

* Menu:

* Server setup::              Setting up a server type
* General server type::       Server type implementation
* Dynamic server::            Dynamic server type loading


File: serveez-api.info,  Node: Server setup,  Next: General server type,  Up: Server types

Macros for setting up a new server type
---------------------------------------

   When specifying a server type you also need to define configuration
items for it. These items refer to addresses in the example
configuration of the server type. The following macros can be used to
determine these items.

 - Macro: SVZ_REGISTER_INT (name, item, defaultable)
  Register a simple integer.  C-type: `int'.  The given NAME specifies
  the symbolic name of the integer and ITEM the integer itself (not its
  address).  The DEFAULTABLE argument can be either
  `SVZ_ITEM_DEFAULTABLE' or `SVZ_ITEM_NOTDEFAULTABLE'.

 - Macro: SVZ_REGISTER_BOOL (name, item, defaultable)
  Register a boolean value.  C-type: `int'.

 - Macro: SVZ_REGISTER_INTARRAY (name, item, defaultable)
  Register an array of integers.  C-type: `svz_array_t *'.

 - Macro: SVZ_REGISTER_STR (name, item, defaultable)
  Register a simple character string.  C-type: `char *'.

 - Macro: SVZ_REGISTER_STRARRAY (name, item, defaultable)
  Register a string array.  C-type: `svz_array_t *'.

 - Macro: SVZ_REGISTER_HASH (name, item, defaultable)
  Register a hash table associating strings with strings only.  C-type:
  `svz_hash_t *'.

 - Macro: SVZ_REGISTER_PORTCFG (name, item, defaultable)
  Register a port configuration.  C-type: `svz_portcfg_t *'.

 - Macro: SVZ_REGISTER_END ()
  This macro indicates the end of the list of configuration items.  It
  is the only mandatory item you need to specify in an example server
  type configuration.

 - Macro: SVZ_DEFINE_CONFIG (config, prototypes)
  Macro for defining the example server configuration CONFIG and its
  configuration items PROTOTYPES within a server type definition.


File: serveez-api.info,  Node: General server type,  Next: Dynamic server,  Prev: Server setup,  Up: Server types

General server type functionality
---------------------------------

   The following set of functions are used to manage the list of known
server types in the serveez core library. Serveez itself uses some of
these functions to register its builtin server types.

 - Variable: svz_array_t * svz_servertypes
  Initial value: NULL
  The list of registered server.  Feel free to add yours.

 - Function: void svz_servertype_add (svz_servertype_t * SERVE)
  Add the server type SERVER to the currently registered servers.

 - Function: void svz_servertype_del (unsigned long INDE)
  Delete the server type with the index INDEX from the list of known
  server types and run its global finalizer if necessary.  Moreover we
  remove and finalize each server instance of this server type.

 - Function: svz_servertype_t * svz_servertype_get (char * NAME, int
    DYNAMI)
  Find a servertype definition by its short name.  If DYNAMIC is set to
  non-zero an attempt is made to load a shared library that provides
  that servertype.  Returns `NULL' if no server with the given variable
  prefix NAME has been found.

 - Function: svz_servertype_t * svz_servertype_find (svz_server_t *
    SERVE)
  Find a given server instances SERVER server type.  Return `NULL' if
  there is no such server type (which should never occur since a server
  is a child of an server type.

 - Function: void svz_servertype_finalize (VOI)
  Run the global finalizers of each server type and delete all server
  types.

 - Function: void svz_servertype_print (VOI)
  Debug helper function to traverse all currently known server types.


File: serveez-api.info,  Node: Dynamic server,  Prev: General server type,  Up: Server types

Dynamic server loading
----------------------

   The core API of serveez is able to register server types dynamically
at runtime. It uses the dynamic linker capabilities of the underlying
operating system to load shared libraries (or DLLs on Win32). This has
been successfully tested on Windows and GNU/Linux. Other systems are
supported but yet untested. Please tell us if noticing any misbehaviour.

 - Function: void svz_dynload_init (VOI)
  Initialize the shared library interface of the core library.

 - Function: void svz_dynload_finalize (VOI)
  Finalize the shared library interface of the core library.  Unload
  all libraries no matter if referenced or not.

 - Function: svz_servertype_t * svz_servertype_load (char * DESCRIPTIO)
  Load an additional server definition from a shared library.  The given
  descriptive name DESCRIPTION must be part of the library's name.

 - Function: int svz_servertype_unload (char * DESCRIPTIO)
  Unload a server definition from a shared library.  The given
  descriptive name DESCRIPTION must be part of the library's name.
  Return the remaining reference count or -1 on errors.

 - Function: void svz_dynload_path_set (svz_array_t * PATH)
  Set the additional search paths for the serveez library.  The given
  array of strings gets `svz_free()'d.

 - Function: svz_array_t * svz_dynload_path_get (VOI)
  Create an array of strings containing each an additional search path.
  The loadpath is hold in the environment variable `SERVEEZ_LOAD_PATH'
  which can be set from outside the library or modified using
  `svz_dynload_path_set()'.  The returned array needs to be destroyed
  after usage.


File: serveez-api.info,  Node: Server,  Next: Port configuration,  Prev: Server types,  Up: Embedding API

Server functions
================

   A server in serveez is an instantiated (configured) server type. It
is merely a copy of a specific server type with a unique server name.
It is represented by the C structure `svz_server_t' in the core library.

* Menu:

* General server::        General server instance implementations
* Server configuration::  Server instance configuration
* Server binding::        Server instance bindings
* Server core::           Core functionality for servers
* Server loop::           Server loop implementation
* Server socket::         Using and creating server sockets


File: serveez-api.info,  Node: General server,  Next: Server configuration,  Up: Server

General functionality
---------------------

   The following section contains functions dealing with the list of
known servers in the core library of serveez, also with the basics like
creation and destruction of such servers.

 - Variable: svz_hash_t * svz_servers
  Initial value: NULL
  This is the list of actually instantiated servers.  The hash table
  associates the servers' names with the server instances.

 - Function: svz_server_t * svz_server_find (void * CF)
  Find a server instance by the given configuration structure CFG.
  Return `NULL' if there is no such configuration in any server
  instance.

 - Function: svz_server_t * svz_server_add (svz_server_t * SERVE)
  Add the server instance SERVER to the list of instantiated servers.
  Returns the previous value of that server if any or `NULL' otherwise.

 - Function: svz_server_t * svz_server_get (char * NAM)
  Get the server instance with the given instance name NAME.  Return
  `NULL' if there is no such server yet.

 - Function: void svz_server_del (char * NAM)
  Remove the server instance identified by the name NAME.

 - Function: int svz_server_init (svz_server_t * SERVE)
  This function runs the server initilizer of the given server instance
  SERVER and returns zero on success.  Otherwise it emits an error
  message and returns non-zero.

 - Function: void svz_server_finalize (svz_server_t * SERVE)
  This function runs the finalizer callback for the given server
  instance SERVER, removes all bindings and frees all resources
  allocated by the server instance.

 - Function: svz_server_t * svz_server_instantiate (svz_servertype_t *
    STYPE, char * NAM)
  Create a new server instance of the server type STYPE with the
  instance name NAME.

 - Function: void svz_server_notifiers (VOI)
  Run all the server instances's notify routines.  This should be
  regularly called within the `svz_periodic_tasks()' function.

 - Function: void svz_server_reset (VOI)
  Runs each server instance's reset callback.  The callbacks are run
  when a `SIGHUP' signal has been detected by the internal signal
  handler of the core library.

 - Function: int svz_server_init_all (VOI)
  Run the initializers of all servers, return -1 if some server did not
  think it is a good idea to run.

 - Function: int svz_server_finalize_all (VOI)
  Run the local finalizers for all server instances.

 - Function: void svz_server_free (svz_server_t * SERVE)
  Completely destroy the given server instance SERVER.  This especially
  means to go through each item of the server instances configuration.


File: serveez-api.info,  Node: Server configuration,  Next: Server binding,  Prev: General server,  Up: Server

Configuration
-------------

   These functions provide an interface for configuring a server. They
are used to create and modify the default configuration of a server
type in order to create a server configuration.

 - Function: void * svz_server_configure (svz_servertype_t * SERVER,
    char * NAME, void * ARG, svz_server_config_t * CONFIGUR)
  This function configures a server instance by modifying its default
  configuration by the CONFIGURE callbacks.  Therefore you need to pass
  the type of server in SERVER, the NAME of the server instance and the
  (optional) modifier callback structure CONFIGURE.  The ARG argument
  is passed to each of the callbacks (e.g. specifying a scheme cell).
  The function returns either a valid server instance configuration or
  `NULL' on errors.

 - Function: void svz_config_free (svz_servertype_t * SERVER, void * CF)
  Release the configuration CFG of the given server type SERVER.  If
  the servers configuration equals `NULL' no operation is performed.

 - Function: svz_array_t * svz_config_intarray_create (int * INTARRA)
  Create an array (`svz_array_t') of integers.  The given integer array
  INTARRAY is a list of integers where its first element which is
  `intarray[0]' contains the actual length of the given array.

 - Function: void svz_config_intarray_destroy (svz_array_t * INTARRA)
  Destroy the given integer array INTARRAY.  This function is the
  counter part of `svz_config_intarray_create()'.

 - Function: svz_array_t * svz_config_intarray_dup (svz_array_t *
    INTARRA)
  Make a plain copy of the given integer array INTARRAY.  If this value
  is `NULL' no operation is performed and the return value is `NULL'
  too.

 - Function: svz_array_t * svz_config_strarray_create (char ** STRARRA)
  Create an array of strings.  The given list of strings STRARRAY must
  be `NULL' terminated in order to indicate its end.

 - Function: void svz_config_strarray_destroy (svz_array_t * STRARRA)
  Destroy the given string array STRARRAY.

 - Function: svz_array_t * svz_config_strarray_dup (svz_array_t *
    STRARRA)
  Duplicate the given array of strings STRARRAY.  Return `NULL' if
  STRARRAY equals `NULL'.

 - Function: svz_hash_t * svz_config_hash_create (char ** STRARRA)
  Create a hash table from the given array of strings STRARRAY which
  must be `NULL' terminated in order to indicate the end of the list.
  The array consists of pairs of strings where the first one specifies a
  key and the following the associated string value.  This function is
  useful when creating default values for server type configurations.

 - Function: void svz_config_hash_destroy (svz_hash_t * STRHAS)
  This function is the counter part of `svz_config_hash_create()'.  It
  destroys the given hash table STRHASH assuming it is a hash
  associating strings with strings.

 - Function: svz_hash_t * svz_config_hash_dup (svz_hash_t * STRHAS)
  Duplicate the given hash table STRHASH assuming it is a hash
  associating strings with strings.  Return `NULL' if STRHASH is `NULL'
  too.


File: serveez-api.info,  Node: Server binding,  Next: Server core,  Prev: Server configuration,  Up: Server

Bindings
--------

   The following functionality represents the relationship between port
configurations as described in *Note Port configuration:: and server
instances. When binding a server to a specific port configuration the
core library creates listeners as needed by itself.

 - Function: int svz_server_bind (svz_server_t * SERVER, svz_portcfg_t
    * POR)
  Bind the server instance SERVER to the port configuration PORT if
  possible.  Return non-zero on errors otherwise zero.  It might occur
  that a single server is bound to more than one network port if e.g.
  the TCP/IP address is specified by "*" since this gets expanded to
  the known list of interfaces.

 - Function: void svz_server_unbind (svz_server_t * SERVE)
  Remove the given server instance SERVER entirely from the list of
  enqueued sockets.  This means to delete it from each server socket on
  the one hand and to shutdown every child client spawned from this
  server on the other hand.

 - Function: svz_array_t * svz_server_portcfgs (svz_server_t * SERVE)
  Return an array of port configurations to which the given server
  instance SERVER is currently bound to or `NULL' if there is no such
  binding.  The caller is responsible for freeing the returned array by
  running `svz_array_destroy()'.

 - Function: char * svz_server_bindings (svz_server_t * SERVE)
  Return a static text representation of the server instance's SERVER
  current port configuration bindings.

 - Function: svz_array_t * svz_server_listeners (svz_server_t * SERVE)
  Return an array of listening socket structures to which the given
  server instance SERVER is currently bound to or `NULL' if there is no
  such binding.  The calling function is reponsible for destroying the
  returned array via `svz_array_destroy()'.

 - Function: int svz_server_single_listener (svz_server_t * SERVER,
    svz_socket_t * SOC)
  This function checks if the given server instance SERVER is bound to
  the listening socket structure SOCK and returns non-zero if it is the
  only server instance bound to this socket.  Otherwise the routine
  returns zero.

 - Function: int svz_sock_add_server (svz_socket_t * SOCK, svz_server_t
    * SERVER, svz_portcfg_t * POR)
  This function attaches the given server instance SERVER to the
  listening socket structure SOCK.  It returns zero on success and
  non-zero if the server is already bound to the socket.

 - Function: int svz_sock_del_server (svz_socket_t * SOCK, svz_server_t
    * SERVE)
  Removes the server instance SERVER from the listening socket
  structure SOCK and returns the remaining number of servers bound to
  the socket structure.

 - Function: svz_socket_t * svz_sock_find_portcfg (svz_portcfg_t * POR)
  Returns a socket structure representing a listening server socket with
  the port configuration PORT.  If there is no such socket with this
  kind of port configuration yet then `NULL' is returned.

 - Function: svz_array_t * svz_sock_find_portcfgs (svz_portcfg_t * POR)
  This functions goes through the list of listening server socket
  structures and returns an array of matching socket structures for the
  given port configuration PORT.  The caller is responsible for freeing
  the array by running `svz_array_destroy()'.  If there are no such
  listening server socket structures `NULL' is returned.

 - Function: svz_socket_t * svz_sock_bind_port (svz_portcfg_t * POR)
  Creates and returns a listening server socket structure.  The kind of
  listener which gets created depends on the given port configuration
  PORT which must be a duplicated copy of one out of the list of known
  port configurations.  On success the function enqueues the returned
  socket structure and assigns the port configuration.  Initially there
  are no bindings.  In case of an error the given port configuration is
  freed and `NULL' is returned.

 - Function: svz_array_t * svz_sock_bindings (svz_socket_t * SOC)
  Returns the binding array of the listening server socket structure
  SOCK or `NULL' if there are no such bindings.

 - Function: svz_array_t * svz_sock_servers (svz_socket_t * SOC)
  Returns the array of server instances bound to the listening socket
  structure SOCK or `NULL' if there are no bindings.  The caller is
  responsible for freeing the returned array by running
  `svz_array_destroy()'.

 - Function: svz_binding_t * svz_binding_create (svz_server_t * SERVER,
    svz_portcfg_t * POR)
  Creates a bind structure.  The binding contains the given server
  instance SERVER and the port configuration PORT.  The caller is
  responsible for freeing the returned pointer.

 - Function: void svz_binding_destroy (svz_binding_t * BINDIN)
  Destroys the given binding BINDING.  This includes the explicit
  destruction of the port configuration.  If BINDING is `NULL' no
  operation is performed.

 - Function: int svz_binding_contains (svz_array_t * BINDINGS,
    svz_binding_t * BINDIN)
  This function checks whether the server instance binding BINDING is
  part of one of the bindings in the array BINDINGS and returns
  non-zero if so.  Otherwise zero is returned.

 - Function: svz_array_t * svz_binding_join (svz_array_t * BINDINGS,
    svz_socket_t * SOC)
  This function adds the bindings stored in the listening server socket
  structure SOCK to the binding array BINDINGS and returns the
  resulting array.  If BINDINGS is `NULL' a new array is created.  If
  the socket structure SOCK is not a listening server socket structure
  no operation is performed.

 - Function: svz_binding_t * svz_binding_find (svz_socket_t * SOCK,
    svz_server_t * SERVER, svz_portcfg_t * POR)
  Goes through the listening server sockets SOCK bindings and checks
  whether it contains the given binding consisting of SERVER and PORT.
  If there is no such binding yet `NULL' is returned otherwise the
  appropriate binding.

 - Function: svz_array_t * svz_binding_find_server (svz_socket_t *
    SOCK, svz_server_t * SERVE)
  Searches through the bindings of the given listening server socket
  structure SOCK and checks whether the server instance SERVER is bound
  to this socket structure.  The function returns these binding and
  returns `NULL' otherwise.  The caller is responsible for freeing the
  returned array.

 - Function: int svz_binding_contains_server (svz_socket_t * SOCK,
    svz_server_t * SERVE)
  This function checks whether the given server instance SERVER is
  bound to the server socket structure SOCK.  Returns zero if not and
  non-zero otherwise.

 - Function: svz_array_t * svz_binding_filter_pipe (svz_socket_t * SOC)
  This is the accept filter for the listening server socket structures
  SOCK with pipe port configurations.  It returns all bindings.  The
  caller is responsible for freeing the returned array by running
  `svz_array_destroy()'.

 - Function: svz_array_t * svz_binding_filter_net (svz_socket_t * SOCK,
    unsigned long ADDR, unsigned short POR)
  This is the accept filter for the listening server socket structures
  SOCK with network port configurations.  It returns the bindings
  allowed to be accepted.  The caller is responsible for freeing the
  returned array by running `svz_array_destroy()'.  Which of the
  bindings are allowed depends on the network interface address ADDR
  and the network port PORT.

 - Function: svz_array_t * svz_binding_filter (svz_socket_t * SOC)
  This is the main filter routine running either
  `svz_binding_filter_net()' or `svz_binding_filter_pipe()' depending
  on the type of port configuration the given socket SOCK contains.


File: serveez-api.info,  Node: Server core,  Next: Server loop,  Prev: Server binding,  Up: Server

Server core
-----------

 - Variable: int svz_nuke_happened
  Initial value: 0
  When SVZ_NUKE_HAPPENED is set to a non-zero value, the server will
  terminate its main loop.

 - Variable: HANDLE svz_child_died
  SVZ_CHILD_DIED is set to a non-zero value whenever the server
  receives a SIGCHLD signal.

 - Variable: long svz_notify
  This holds the time on which the next call to `svz_periodic_tasks()'
  should occur.

 - Function: void svz_executable (char * FIL)
  Set the name of the executable file which uses the core library.  This
  is usually `argv[0]'.

 - Function: int svz_periodic_tasks (VOI)
  This routine gets called once a second and is supposed to perform any
  task that has to get scheduled periodically.  It checks all sockets'
  timers and calls their timer functions when necessary.

 - Variable: svz_socket_t * svz_sock_root
  Initial value: NULL
  SVZ_SOCK_ROOT is the pointer to the head of the list of sockets,
  which are handled by the server loop.

 - Variable: svz_socket_t * svz_sock_last
  Initial value: NULL
  SVZ_SOCK_LAST always points to the last structure in the socket queue
  and is NULL when the queue is empty.

 - Function: svz_socket_t * svz_sock_find (int ID, int VERSIO)
  Return the socket structure for the socket id ID and the version
  VERSION or `NULL' if no such socket exists.  If VERSION is -1 it is
  not checked.

 - Function: int svz_sock_schedule_for_shutdown (svz_socket_t * SOC)
  Mark socket SOCK as killed.  That means that no operations except
  disconnecting and freeing are allowed anymore.  All marked sockets
  will be deleted once the server loop is through.

 - Function: int svz_sock_enqueue (svz_socket_t * SOC)
  Enqueue the socket SOCK into the list of sockets handled by the
  server loop.

 - Function: int svz_sock_dequeue (svz_socket_t * SOC)
  Remove the socket SOCK from the list of sockets handled by the server
  loop.

 - Function: int svz_sock_shutdown (svz_socket_t * SOC)
  Do everything to shut down the socket SOCK.  The socket structure
  gets removed from the socket queue, the file descriptor is closed and
  all memory used by the socket gets freed.  Note that this function
  calls the SOCK's disconnect handler if defined.

 - Function: void svz_sock_shutdown_all (VOI)
  Shutdown all sockets within the socket list no matter if it was
  scheduled for shutdown or not.

 - Function: void svz_sock_setparent (svz_socket_t * CHILD,
    svz_socket_t * PAREN)
  Set the sockets CHILD parent to the given socket structure PARENT.
  This should be called whenever a listener accepts a connection and
  creates a new child socket.

 - Function: svz_socket_t * svz_sock_getparent (svz_socket_t * CHIL)
  Return the sockets CHILD parent socket structure or `NULL' if this
  socket does not exist anymore.  This might happen if a listener dies
  for some reason.

 - Function: void svz_sock_setreferrer (svz_socket_t * SOCK,
    svz_socket_t * REFERRE)
  Set the referring socket structure of SOCK to the given socket
  REFERRER.  This can be used to create some relationship between two
  socket structures.  If REFERRER is `NULL' the reference will be
  invalidated.

 - Function: svz_socket_t * svz_sock_getreferrer (svz_socket_t * SOC)
  Get the referrer of the socket structure SOCK.  Return `NULL' if
  there is no such socket.

 - Function: svz_portcfg_t * svz_sock_portcfg (svz_socket_t * SOC)
  Return the parents port configuration of the socket structure SOCK or
  `NULL' if the given socket has no parent, i.e. is a listener.

 - Macro: svz_sock_foreach (sock)
  Go through each socket structure in the chained list.

 - Macro: svz_sock_foreach_listener (sock)
  Goes through the chained list of socket structures and filters each
  listener.

 - Function: int svz_sock_check_frequency (svz_socket_t * PARENT,
    svz_socket_t * CHIL)
  This routine checks the connection frequency of the socket structure
  CHILD for the port configuration of the listener socket structure
  PARENT.  Returns zero if the connection frequency is valid, otherwise
  non-zero.

 - Function: int svz_sock_check_access (svz_socket_t * PARENT,
    svz_socket_t * CHIL)
  This function returns zero if the CHILD socket is allowed to connect
  to the port configuration of the PARENT socket structure which needs
  to be a listener therefore.

 - Function: void svz_sock_table_create (VOI)
  Create the socket lookup table initially.  Must be called from
  `svz_boot()'.

 - Function: void svz_sock_table_destroy (VOI)
  Destroy the socket lookup table finally.  Must be called from
  `svz_halt()'.

 - Function: void svz_sock_check_bogus (VOI)
  Goes through all socket and shuts invalid ones down.

 - Function: void svz_sock_check_children (VOI)
  Goes through the list of socket structures and checks whether each
  `pid' stored in a socket structure has died.  If so, the `child_died'
  callback is called.  If this callback returned non-zero the
  appropriate socket structure gets scheduled for shutdown.

 - Function: int svz_sock_child_died (svz_socket_t * SOC)
  This routine checks whether the child process specified by the `pid'
  handle stored in the socket structure SOCK is still alive.  It
  returns zero if so, otherwise (when the child process died) non-zero.
  This routine is called from `svz_sock_check_children()'.

 - Function: void svz_signal_up (VOI)
  Setup signaling for the core library.

 - Function: void svz_signal_dn (VOI)
  Deinstall signaling for the core library.

 - Function: RETSIGTYPE svz_signal_handler (int SI)
  Handle some signals to handle server resets (SIGHUP), to ignore
  broken pipes (SIGPIPE) and to exit gracefully if requested by the
  user (SIGINT, SIGTERM).

 - Function: void svz_strsignal_init (VOI)
  Prepare library so that `svz_strsignal()' works.  Called from
  `svz_boot()'.

 - Function: void svz_strsignal_destroy (VOI)
  The function `svz_strsignal()' does not work afterwards anymore.
  Called from `svz_halt()'.

 - Function: char * svz_strsignal (int SI)
  Resolve the given signal number to form a describing string.  This
  function is reentrant, use it from the signal handler.  It does not
  return NULL.  The returned pointer is shared amongst all users.  For
  unknown signals (which is not supposed to happen) the returned string
  points to a statically allocated buffer (which destroys the
  reentrance, of course) [who cares :-].


File: serveez-api.info,  Node: Server loop,  Next: Server socket,  Prev: Server core,  Up: Server

Server loop
-----------

   This paragraph describes the main server loop functionality. There
two modes of operation. The default mode as used in serveez is to jump
into the loop and waiting until the core library drops out of it. The
user can also tell the serveez core library to pass its socket chain
once and return immediately. Thus you are able to issue additional
functionality in between each pass if you cannot handle this within the
timers (notifiers) of servers and sockets.

 - Function: int svz_check_sockets (VOI)
  Check the server and client sockets for incoming connections and
  data, and process outgoing data.

 - Function: void svz_loop_pre (VOI)
  Call this function once before using `svz_loop_one()'.

 - Function: void svz_loop_post (VOI)
  Call this function once after using `svz_loop_one()'.

 - Function: void svz_loop (VOI)
  Main server loop.  Handle all signals, incoming and outgoing
  connections and listening server sockets.

 - Function: void svz_loop_one (VOI)
  This routine handles all things once and is called regularly in the
  below `svz_loop()' routine.


File: serveez-api.info,  Node: Server socket,  Prev: Server loop,  Up: Server

Server sockets
--------------

   The next section deals with creating and handling listeners. The
functions below provide the default routines invoked when accepting a
new connection on a listener. This is necessary for connection oriented
protocols (TCP and named pipes) only.

 - Function: svz_socket_t * svz_server_create (svz_portcfg_t * POR)
  Create a listening server socket (network or pipe). PORT is the port
  configuration to bind the server socket to.  Return a `NULL' pointer
  on errors.

 - Function: int svz_tcp_accept (svz_socket_t * SERVER_SOC)
  Something happened on the a server socket, most probably a client
  connection which we will normally accept.  This is the default
  callback for `read_socket' for listening tcp sockets.

 - Function: int svz_pipe_accept (svz_socket_t * SERVER_SOC)
  Check if client pipe is connected.  This is the default callback for
  `idle_func' for listening pipe sockets.


File: serveez-api.info,  Node: Port configuration,  Next: Booting,  Prev: Server,  Up: Embedding API

Port configurations
===================

   A port configuration is a structure defining a network or file system
configuration. Depending on the type of a server it can be bound to one
or more port configurations. There are two major types of port
configurations: connection and packet oriented protocol port
configurations.  TCP and PIPE configurations are connection oriented
and ICMP, UDP and RAW configurations are packet oriented.

   Serveez holds a list of port configurations. Each configuration is
identified by its name. When you bind a server to a port configuration
it does not get bound to a certain name but to its content. If there
are two or more port configuration specifying the same network or file
system configuration just a single one gets actually used.

 - Function: svz_portcfg_t * svz_portcfg_create (VOI)
  Create a new blank port configuration.

 - Function: int svz_portcfg_equal (svz_portcfg_t * A, svz_portcfg_t * )
  Check if two given port configurations structures are equal i.e.
  specifying the same network port or pipe files.  Returns
  `PORTCFG_EQUAL' if A and B are identical, `PORTCFG_MATCH' if the
  network address ofeither port configurations contains the other
  (INADDR_ANY match) and otherwise `PORTCFG_NOMATCH' or possibly
  `PORTCFG_CONFLICT'.

 - Function: svz_portcfg_t * svz_portcfg_add (char * NAME,
    svz_portcfg_t * POR)
  Add the given port configuration PORT associated with the name NAME
  to the list of known port configurations.  Return `NULL' on errors.
  If the return port configuration equals the given port configuration
  the given one has been successfully added.

 - Function: svz_portcfg_t * svz_portcfg_del (char * NAM)
  Remove the named port configuration identified by NAME from the list
  of known port configurations.  Return `NULL' on errors or otherwise
  the port configuration associated with NAME.

 - Function: svz_portcfg_t * svz_portcfg_get (char * NAM)
  Return the port configuration associated with the given name NAME.
  This function returns `NULL' on errors.

 - Function: void svz_portcfg_destroy (svz_portcfg_t * POR)
  This function makes the given port configuration PORT completely
  unusable.  No operation is performed if PORT is `NULL'.  If the port
  configuration is part of the list of known port configurations it it
  thrown out of them.

 - Function: void svz_portcfg_free (svz_portcfg_t * POR)
  This function frees all resources allocated by the given port
  configuration PORT.

 - Function: void svz_portcfg_finalize (VOI)
  Delete the list of known port configurations.  This routine should
  definitely called from the core library's finalizer.

 - Function: int svz_portcfg_mkaddr (svz_portcfg_t * THI)
  Construct the `sockaddr_in' fields from the `ipaddr' field.  Returns
  zero if it worked.  If it does not work the `ipaddr' field did not
  consist of an ip address in dotted decimal form.

 - Function: void svz_portcfg_prepare (svz_portcfg_t * POR)
  Prepare the given port configuration PORT.  Fill in default values
  for yet undefined variables.

 - Function: void svz_portcfg_print (svz_portcfg_t * THIS, FILE * )
  Debug helper: Emit a printable representation of the the given port
  configuration to the given FILE stream F.

 - Function: char * svz_portcfg_text (svz_portcfg_t * POR)
  This function returns a simple text representation of the given port
  configuration PORT.  The returned character string is statically
  allocated.  Thus you cannot use it twice in argument lists.

 - Function: svz_portcfg_t * svz_portcfg_dup (svz_portcfg_t * POR)
  Make a copy of the given port configuration PORT.  This function is
  used in `svz_portcfg_expand()'.

 - Function: svz_array_t * svz_portcfg_expand (svz_portcfg_t * THI)
  Expand the given port configuration THIS if it is a network port
  configuration and if the network ip address is `INADDR_ANY'.  Return
  an array of port configurations which are copies of the given.

 - Macro: svz_portcfg_addr (port)
  Return the pointer of the `sockaddr_in' structure of the given port
  configuration PORT if it is a network port configuration.  Otherwise
  return `NULL'.

 - Macro: svz_portcfg_port (port)
  Return the UDP or TCP port of the given port configuration or zero if
  it neither TCP nor UDP.

 - Macro: svz_portcfg_ipaddr (port)
  Return the pointer to the ip address `ipaddr' of the given port
  configuration PORT if it is a network port configuration.  Otherwise
  return `NULL'.

 - Macro: svz_portcfg_device (port)
  This macro returns the network device name stored in the given port
  configuration PORT if it is a network port configuration.  The
  returned pointer can be `NULL' if there is no such device set or if
  the port configuration is not a network port configuration.

 - Function: int svz_portcfg_set_ipaddr (svz_portcfg_t * THIS, char *
    IPADD)
  This function can be used to set the character string representation
  of a the port configuration THIS in dotted decimal form (IPADDR).
  Returns zero on success, non-zero otherwise.

 - Function: void svz_portcfg_destroy_accepted (svz_portcfg_t * POR)
  Destroy the list of connections for each ip address ever connected to
  the given port configuration PORT.

 - Function: void svz_portcfg_destroy_access (svz_portcfg_t * POR)
  Destroy the deny and allowed access list of the given port
  configuration PORT.


File: serveez-api.info,  Node: Booting,  Next: Interface,  Prev: Port configuration,  Up: Embedding API

Boot functions
==============

   This section contains the description of some runtime checkable flags
indicating the abilities of the running serveez core API and the
underlying operating system. It also describes the most important
functions `svz_boot()' and `svz_halt()' which must be the first and the
last call to the core API.

 - Variable: svz_config_t svz_config
  Initial value: { NULL, 0, 0, 0 }
  The configuration structure of the core library.

 - Variable: char * svz_library
  Initial value: "serveez"
  The symbolic name of the core library.

 - Variable: char * svz_version
  Initial value: __serveez_version
  The version of the core library.

 - Variable: char * svz_build
  Initial value: __serveez_timestamp
  Timestamp when core library has been build.

 - Variable: int svz_have_debug
  Initial value: 1
  Runtime flag if this is the debug version or not.

 - Variable: int svz_have_Win32
  Initial value: 1
  Runtime flag if this is Win32 or not.

 - Variable: int svz_have_floodprotect
  Initial value: 1
  Runtime checkable flags for configuration language and code if flood
  protection has been enabled or not.

 - Function: int svz_net_startup (VOI)
  This routine has to be called once before you could use any of the
  serveez core library functions.

 - Function: int svz_net_cleanup (VOI)
  Shutdown the serveez core library.

 - Function: void svz_init_config (VOI)
  Initialization of the configuration.

 - Function: void svz_boot (VOI)
  Initialization of the core library.

 - Function: void svz_halt (VOI)
  Finalization of the core library.


File: serveez-api.info,  Node: Interface,  Next: Windoze,  Prev: Booting,  Up: Embedding API

Network interface functions
===========================

   The network interface functions of the serveez core API allow the
access to the network devices on your system. The system administrator
can setup these devices to be bound to different Internet addresses and
thereby split the network configuration into different "domains". Thus
the system is able to separate traffic of different networks. If setup
correctly serveez can follow these rules.

 - Variable: svz_vector_t * svz_interfaces
  Initial value: NULL
  The available interface list.

 - Function: void svz_interface_list (VOI)
  Print the text representation of all the network interfaces.

 - Function: void svz_interface_collect (VOI)
  Collect all available network interfaces and put them into the list
  SVZ_INTERFACES.  This is useful in order to `bind()' server sockets
  to specific network interfaces.  Thus you can make certain services
  accessible from "outside" or "inside" a network installation only.

 - Function: int svz_interface_free (VOI)
  Free the network interface list.

 - Function: int svz_interface_add (int INDEX, char * DESC, unsigned
    long ADDR, int DETECTE)
  Add a network interface to the current list of known interfaces.  Drop
  duplicate entries.  The given arguments INDEX specifies the network
  interface index number, DESC an interface desription, ADDR the IP
  address in network byte order and the DETECTED flag if the given
  network interface has been detected by Serveez itself or not.

 - Function: svz_interface_t * svz_interface_get (unsigned long ADD)
  This function returns the interface structure for the given IP address
  ADDR if any.  Returns `NULL' otherwise.

 - Function: svz_interface_t * svz_interface_search (char * DES)
  The following function returns a network interface structure for a
  given interface name (e.g. eth0).  If no such interface exists it
  returns `NULL'.

 - Function: void svz_interface_check (VOI)
  This function checks for network interface changes.  It emits
  messages for new and removed interfaces.  Software interfaces which
  have not been detected by Serveez stay untouched.  If Serveez
  receives a `SIGHUP' signal the signal handler runs it once.

 - Macro: svz_interface_foreach (ifc, i)
  Iteration macro for the list of known network interfaces.  If any
  each interface gets assigned to IFC.  The variable I is the iteration
  variable.


File: serveez-api.info,  Node: Windoze,  Prev: Interface,  Up: Embedding API

Useful Windows functions
========================

   Serveez is meant to run on Windows systems as well (with some
restrictions of course). The following functions come up with the
Windows implementation of the serveez core API only. They allow access
to the Windows registry database and some other useful things.

 - Function: int svz_windoze_start_daemon (char * PRO)
  Start the windows daemon thread and detach from the current console.

 - Function: int svz_windoze_stop_daemon (VOI)
  Stop the windows daemon thread.

 - Function: WCHAR * svz_windoze_asc2uni (CHAR * AS)
  Convert an ASCII string into a UNICODE string.

 - Function: CHAR * svz_windoze_uni2asc (WCHAR * UNICOD)
  Convert a UNICODE string into an ASCII string.

 - Function: unsigned svz_windoze_get_reg_unsigned (HKEY KEY, char *
    SUBKEY, char * SUBSUBKEY, unsigned DE)
  Read an unsigned integer value from the Windows Registry Database.

 - Function: void svz_windoze_set_reg_unsigned (HKEY KEY, char *
    SUBKEY, char * SUBSUBKEY, unsigned VALU)
  Write an unsigned integer value to the Windows Registry Database.

 - Function: char * svz_windoze_get_reg_string (HKEY KEY, char *
    SUBKEY, char * SUBSUBKEY, char * DE)
  Read a string value from the Windows Registry Database.

 - Function: void svz_windoze_set_reg_string (HKEY KEY, char * SUBKEY,
    char * SUBSUBKEY, char * VALU)
  Write a string value to the Windows Registry Database.


File: serveez-api.info,  Node: Index,  Prev: Embedding API,  Up: Top

Index
*****

* Menu:

* Function index::            All functions and macros of the C API
* Variable index::            All variables in the C API


File: serveez-api.info,  Node: Function index,  Next: Variable index,  Up: Index

Function index
==============

* Menu:

* svz_array_add:                         Array.
* svz_array_capacity:                    Array.
* svz_array_clear:                       Array.
* svz_array_contains:                    Array.
* svz_array_create:                      Array.
* svz_array_del:                         Array.
* svz_array_destroy:                     Array.
* svz_array_destroy_zero:                Array.
* svz_array_dup:                         Array.
* svz_array_foreach:                     Array.
* svz_array_get:                         Array.
* svz_array_idx:                         Array.
* svz_array_ins:                         Array.
* svz_array_set:                         Array.
* svz_array_size:                        Array.
* svz_array_strdup:                      Array.
* svz_array_values:                      Array.
* svz_atoi:                              Utility functions.
* svz_binding_contains:                  Server binding.
* svz_binding_contains_server:           Server binding.
* svz_binding_create:                    Server binding.
* svz_binding_destroy:                   Server binding.
* svz_binding_filter:                    Server binding.
* svz_binding_filter_net:                Server binding.
* svz_binding_filter_pipe:               Server binding.
* svz_binding_find:                      Server binding.
* svz_binding_find_server:               Server binding.
* svz_binding_join:                      Server binding.
* svz_boot:                              Booting.
* svz_calloc:                            Memory management.
* svz_check_sockets:                     Server loop.
* svz_close:                             Core functions.
* svz_codec_finalize:                    Codec.
* svz_codec_get:                         Codec.
* svz_codec_init:                        Codec.
* svz_codec_list:                        Codec.
* svz_codec_ratio:                       Codec.
* svz_codec_register:                    Codec.
* svz_codec_sock_detect:                 Codec.
* svz_codec_sock_disconnect:             Codec.
* svz_codec_sock_receive:                Codec.
* svz_codec_sock_receive_setup:          Codec.
* svz_codec_sock_send:                   Codec.
* svz_codec_sock_send_setup:             Codec.
* svz_codec_unregister:                  Codec.
* svz_config_free:                       Server configuration.
* svz_config_hash_create:                Server configuration.
* svz_config_hash_destroy:               Server configuration.
* svz_config_hash_dup:                   Server configuration.
* svz_config_intarray_create:            Server configuration.
* svz_config_intarray_destroy:           Server configuration.
* svz_config_intarray_dup:               Server configuration.
* svz_config_strarray_create:            Server configuration.
* svz_config_strarray_destroy:           Server configuration.
* svz_config_strarray_dup:               Server configuration.
* svz_coserver_check:                    Coserver.
* svz_coserver_create:                   Coserver.
* svz_coserver_destroy:                  Coserver.
* svz_coserver_dns:                      Coserver.
* svz_coserver_dns_invoke:               Coserver.
* svz_coserver_finalize:                 Coserver.
* svz_coserver_ident:                    Coserver.
* svz_coserver_ident_invoke:             Coserver.
* svz_coserver_init:                     Coserver.
* svz_coserver_rdns:                     Coserver.
* svz_coserver_rdns_invoke:              Coserver.
* svz_coserver_send_request:             Coserver.
* SVZ_DEFINE_CONFIG:                     Server setup.
* svz_dynload_finalize:                  Dynamic server.
* svz_dynload_init:                      Dynamic server.
* svz_dynload_path_get:                  Dynamic server.
* svz_dynload_path_set:                  Dynamic server.
* svz_envblock_add:                      Passthrough connections.
* svz_envblock_create:                   Passthrough connections.
* svz_envblock_default:                  Passthrough connections.
* svz_envblock_destroy:                  Passthrough connections.
* svz_envblock_free:                     Passthrough connections.
* svz_envblock_get:                      Passthrough connections.
* svz_envblock_setup:                    Passthrough connections.
* svz_executable:                        Server core.
* svz_fclose:                            Core functions.
* svz_fd_block:                          Core functions.
* svz_fd_cloexec:                        Core functions.
* svz_fd_nonblock:                       Core functions.
* svz_file_check:                        Core functions.
* svz_file_path:                         Core functions.
* svz_fopen:                             Core functions.
* svz_free:                              Memory management.
* svz_free_and_zero:                     Memory management.
* svz_fstat:                             Core functions.
* svz_getcwd:                            Utility functions.
* svz_halt:                              Booting.
* svz_hash_capacity:                     Hashtable.
* svz_hash_clear:                        Hashtable.
* svz_hash_contains:                     Hashtable.
* svz_hash_create:                       Hashtable.
* svz_hash_delete:                       Hashtable.
* svz_hash_destroy:                      Hashtable.
* svz_hash_exists:                       Hashtable.
* svz_hash_foreach_key:                  Hashtable.
* svz_hash_foreach_value:                Hashtable.
* svz_hash_get:                          Hashtable.
* svz_hash_keys:                         Hashtable.
* svz_hash_put:                          Hashtable.
* svz_hash_size:                         Hashtable.
* svz_hash_values:                       Hashtable.
* svz_heap:                              Memory management.
* svz_hexdump:                           Utility functions.
* svz_hstrerror:                         Utility functions.
* svz_icmp_check_request:                ICMP sockets.
* svz_icmp_cleanup:                      ICMP sockets.
* svz_icmp_connect:                      ICMP sockets.
* svz_icmp_lazy_read_socket:             ICMP sockets.
* svz_icmp_printf:                       ICMP sockets.
* svz_icmp_read_socket:                  ICMP sockets.
* svz_icmp_send_control:                 ICMP sockets.
* svz_icmp_startup:                      ICMP sockets.
* svz_icmp_write:                        ICMP sockets.
* svz_icmp_write_socket:                 ICMP sockets.
* svz_inet_aton:                         Core functions.
* svz_inet_ntoa:                         Core functions.
* svz_init_config:                       Booting.
* SVZ_INT16:                             Utility functions.
* SVZ_INT32:                             Utility functions.
* SVZ_INT64:                             Utility functions.
* svz_interface_add:                     Interface.
* svz_interface_check:                   Interface.
* svz_interface_collect:                 Interface.
* svz_interface_foreach:                 Interface.
* svz_interface_free:                    Interface.
* svz_interface_get:                     Interface.
* svz_interface_list:                    Interface.
* svz_interface_search:                  Interface.
* svz_itoa:                              Utility functions.
* svz_log:                               Utility functions.
* svz_log_setfile:                       Utility functions.
* svz_loop:                              Server loop.
* svz_loop_one:                          Server loop.
* svz_loop_post:                         Server loop.
* svz_loop_pre:                          Server loop.
* svz_malloc:                            Memory management.
* svz_net_cleanup:                       Booting.
* svz_net_startup:                       Booting.
* SVZ_NUM2PTR:                           Utility functions.
* svz_open:                              Core functions.
* svz_openfiles:                         Utility functions.
* svz_periodic_tasks:                    Server core.
* svz_pipe_accept:                       Server socket.
* svz_pipe_alloc:                        Pipe connections.
* svz_pipe_check_group:                  Pipe connections.
* svz_pipe_check_user:                   Pipe connections.
* svz_pipe_cleanup:                      Pipe connections.
* svz_pipe_connect:                      Pipe connections.
* svz_pipe_create:                       Pipe connections.
* svz_pipe_create_pair:                  Pipe connections.
* svz_pipe_destroy:                      Pipe connections.
* svz_pipe_disconnect:                   Pipe connections.
* svz_pipe_listener:                     Pipe connections.
* svz_pipe_read_socket:                  Pipe connections.
* svz_pipe_startup:                      Pipe connections.
* svz_pipe_valid:                        Pipe connections.
* svz_pipe_write_socket:                 Pipe connections.
* svz_pmalloc:                           Memory management.
* svz_portcfg_add:                       Port configuration.
* svz_portcfg_addr:                      Port configuration.
* svz_portcfg_create:                    Port configuration.
* svz_portcfg_del:                       Port configuration.
* svz_portcfg_destroy:                   Port configuration.
* svz_portcfg_destroy_accepted:          Port configuration.
* svz_portcfg_destroy_access:            Port configuration.
* svz_portcfg_device:                    Port configuration.
* svz_portcfg_dup:                       Port configuration.
* svz_portcfg_equal:                     Port configuration.
* svz_portcfg_expand:                    Port configuration.
* svz_portcfg_finalize:                  Port configuration.
* svz_portcfg_free:                      Port configuration.
* svz_portcfg_get:                       Port configuration.
* svz_portcfg_ipaddr:                    Port configuration.
* svz_portcfg_mkaddr:                    Port configuration.
* svz_portcfg_port:                      Port configuration.
* svz_portcfg_prepare:                   Port configuration.
* svz_portcfg_print:                     Port configuration.
* svz_portcfg_set_ipaddr:                Port configuration.
* svz_portcfg_text:                      Port configuration.
* svz_prealloc:                          Memory management.
* svz_process_check_access:              Passthrough connections.
* svz_process_check_executable:          Passthrough connections.
* svz_process_check_request:             Passthrough connections.
* svz_process_create_child:              Passthrough connections.
* svz_process_disconnect:                Passthrough connections.
* svz_process_disconnect_passthrough:    Passthrough connections.
* svz_process_fork:                      Passthrough connections.
* svz_process_idle:                      Passthrough connections.
* svz_process_recv_pipe:                 Passthrough connections.
* svz_process_recv_socket:               Passthrough connections.
* svz_process_send_pipe:                 Passthrough connections.
* svz_process_send_socket:               Passthrough connections.
* svz_process_shuffle:                   Passthrough connections.
* svz_process_split_usergroup:           Passthrough connections.
* svz_pstrdup:                           Memory management.
* SVZ_PTR2NUM:                           Utility functions.
* svz_raw_check_ip_header:               Raw sockets.
* svz_raw_get_ip_header:                 Raw sockets.
* svz_raw_ip_checksum:                   Raw sockets.
* svz_raw_put_ip_header:                 Raw sockets.
* svz_realloc:                           Memory management.
* SVZ_REGISTER_BOOL:                     Server setup.
* SVZ_REGISTER_END:                      Server setup.
* SVZ_REGISTER_HASH:                     Server setup.
* SVZ_REGISTER_INT:                      Server setup.
* SVZ_REGISTER_INTARRAY:                 Server setup.
* SVZ_REGISTER_PORTCFG:                  Server setup.
* SVZ_REGISTER_STR:                      Server setup.
* SVZ_REGISTER_STRARRAY:                 Server setup.
* svz_sendfile:                          Core functions.
* svz_server_add:                        General server.
* svz_server_bind:                       Server binding.
* svz_server_bindings:                   Server binding.
* svz_server_configure:                  Server configuration.
* svz_server_create:                     Server socket.
* svz_server_del:                        General server.
* svz_server_finalize:                   General server.
* svz_server_finalize_all:               General server.
* svz_server_find:                       General server.
* svz_server_free:                       General server.
* svz_server_get:                        General server.
* svz_server_init:                       General server.
* svz_server_init_all:                   General server.
* svz_server_instantiate:                General server.
* svz_server_listeners:                  Server binding.
* svz_server_notifiers:                  General server.
* svz_server_portcfgs:                   Server binding.
* svz_server_reset:                      General server.
* svz_server_single_listener:            Server binding.
* svz_server_unbind:                     Server binding.
* svz_servertype_add:                    General server type.
* svz_servertype_del:                    General server type.
* svz_servertype_finalize:               General server type.
* svz_servertype_find:                   General server type.
* svz_servertype_get:                    General server type.
* svz_servertype_load:                   Dynamic server.
* svz_servertype_print:                  General server type.
* svz_servertype_unload:                 Dynamic server.
* svz_signal_dn:                         Server core.
* svz_signal_handler:                    Server core.
* svz_signal_up:                         Server core.
* svz_snprintf:                          Utility functions.
* svz_sock_add_server:                   Server binding.
* svz_sock_alloc:                        Socket.
* svz_sock_bind_port:                    Server binding.
* svz_sock_bindings:                     Server binding.
* svz_sock_check_access:                 Server core.
* svz_sock_check_bogus:                  Server core.
* svz_sock_check_children:               Server core.
* svz_sock_check_frequency:              Server core.
* svz_sock_check_request:                Socket.
* svz_sock_child_died:                   Server core.
* svz_sock_create:                       Socket.
* svz_sock_del_server:                   Server binding.
* svz_sock_dequeue:                      Server core.
* svz_sock_detect_proto:                 Socket.
* svz_sock_disconnect:                   Socket.
* svz_sock_enqueue:                      Server core.
* svz_sock_error_info:                   Socket.
* svz_sock_find:                         Server core.
* svz_sock_find_portcfg:                 Server binding.
* svz_sock_find_portcfgs:                Server binding.
* svz_sock_flood_protect:                Socket.
* svz_sock_foreach:                      Server core.
* svz_sock_foreach_listener:             Server core.
* svz_sock_free:                         Socket.
* svz_sock_getparent:                    Server core.
* svz_sock_getreferrer:                  Server core.
* svz_sock_idle_protect:                 Socket.
* svz_sock_intern_connection_info:       Socket.
* svz_sock_local_info:                   Socket.
* svz_sock_portcfg:                      Server core.
* svz_sock_printf:                       Socket.
* svz_sock_process:                      Passthrough connections.
* svz_sock_reduce_recv:                  Socket.
* svz_sock_reduce_send:                  Socket.
* svz_sock_resize_buffers:               Socket.
* svz_sock_schedule_for_shutdown:        Server core.
* svz_sock_servers:                      Server binding.
* svz_sock_setparent:                    Server core.
* svz_sock_setreferrer:                  Server core.
* svz_sock_shutdown:                     Server core.
* svz_sock_shutdown_all:                 Server core.
* svz_sock_table_create:                 Server core.
* svz_sock_table_destroy:                Server core.
* svz_sock_unique_id:                    Socket.
* svz_sock_valid:                        Socket.
* svz_sock_write:                        Socket.
* svz_socket_connect:                    Core functions.
* svz_socket_create:                     Core functions.
* svz_socket_create_pair:                Core functions.
* svz_socket_type:                       Core functions.
* svz_spvec_add:                         Sparsevector.
* svz_spvec_clear:                       Sparsevector.
* svz_spvec_contains:                    Sparsevector.
* svz_spvec_create:                      Sparsevector.
* svz_spvec_delete:                      Sparsevector.
* svz_spvec_delete_range:                Sparsevector.
* svz_spvec_destroy:                     Sparsevector.
* svz_spvec_get:                         Sparsevector.
* svz_spvec_index:                       Sparsevector.
* svz_spvec_insert:                      Sparsevector.
* svz_spvec_length:                      Sparsevector.
* svz_spvec_pack:                        Sparsevector.
* svz_spvec_set:                         Sparsevector.
* svz_spvec_size:                        Sparsevector.
* svz_spvec_unset:                       Sparsevector.
* svz_spvec_values:                      Sparsevector.
* svz_strcasecmp:                        Utility functions.
* svz_strdup:                            Memory management.
* svz_strncasecmp:                       Utility functions.
* svz_strsignal:                         Server core.
* svz_strsignal_destroy:                 Server core.
* svz_strsignal_init:                    Server core.
* svz_sys_version:                       Utility functions.
* svz_syserror:                          Utility functions.
* svz_tcp_accept:                        Server socket.
* svz_tcp_connect:                       TCP sockets.
* svz_tcp_cork:                          Core functions.
* svz_tcp_default_connect:               TCP sockets.
* svz_tcp_nodelay:                       Core functions.
* svz_tcp_read_socket:                   TCP sockets.
* svz_tcp_recv_oob:                      TCP sockets.
* svz_tcp_send_oob:                      TCP sockets.
* svz_tcp_write_socket:                  TCP sockets.
* svz_time:                              Utility functions.
* svz_tolower:                           Utility functions.
* svz_udp_check_request:                 UDP sockets.
* svz_udp_connect:                       UDP sockets.
* svz_udp_lazy_read_socket:              UDP sockets.
* svz_udp_printf:                        UDP sockets.
* svz_udp_read_socket:                   UDP sockets.
* svz_udp_write:                         UDP sockets.
* svz_udp_write_socket:                  UDP sockets.
* SVZ_UINT16:                            Utility functions.
* SVZ_UINT32:                            Utility functions.
* SVZ_UINT64:                            Utility functions.
* svz_uptime:                            Utility functions.
* svz_vector_add:                        Vectorlist.
* svz_vector_clear:                      Vectorlist.
* svz_vector_contains:                   Vectorlist.
* svz_vector_create:                     Vectorlist.
* svz_vector_del:                        Vectorlist.
* svz_vector_destroy:                    Vectorlist.
* svz_vector_foreach:                    Vectorlist.
* svz_vector_get:                        Vectorlist.
* svz_vector_idx:                        Vectorlist.
* svz_vector_ins:                        Vectorlist.
* svz_vector_length:                     Vectorlist.
* svz_vector_set:                        Vectorlist.
* svz_windoze_asc2uni:                   Windoze.
* svz_windoze_get_reg_string:            Windoze.
* svz_windoze_get_reg_unsigned:          Windoze.
* svz_windoze_set_reg_string:            Windoze.
* svz_windoze_set_reg_unsigned:          Windoze.
* svz_windoze_start_daemon:              Windoze.
* svz_windoze_stop_daemon:               Windoze.
* svz_windoze_uni2asc:                   Windoze.


File: serveez-api.info,  Node: Variable index,  Prev: Function index,  Up: Index

Variable index
==============

* Menu:

* svz_allocated_blocks:                  Memory management.
* svz_allocated_bytes:                   Memory management.
* svz_build:                             Booting.
* svz_child_died:                        Server core.
* svz_config:                            Booting.
* svz_coservers:                         Coserver.
* svz_coservertypes:                     Coserver.
* svz_environ:                           Passthrough connections.
* svz_errno:                             Utility functions.
* svz_free_func:                         Memory management.
* svz_have_debug:                        Booting.
* svz_have_floodprotect:                 Booting.
* svz_have_Win32:                        Booting.
* svz_interfaces:                        Interface.
* svz_library:                           Booting.
* svz_malloc_func:                       Memory management.
* svz_notify:                            Server core.
* svz_nuke_happened:                     Server core.
* svz_os_version:                        Utility functions.
* svz_realloc_func:                      Memory management.
* svz_servers:                           General server.
* svz_servertypes:                       General server type.
* svz_sock_connections:                  Socket.
* svz_sock_last:                         Server core.
* svz_sock_root:                         Server core.
* svz_version:                           Booting.



Tag Table:
Node: Top231
Node: Introduction713
Node: Embedding Serveez1413
Node: Compiling and linking1860
Node: A simple example3379
Node: Embedding API4204
Node: Memory management5669
Node: Data structures9056
Node: Array9790
Node: Hashtable14631
Node: Sparsevector19500
Node: Vectorlist23130
Node: Utility functions26128
Node: Core functions31373
Node: Client connections36728
Node: TCP sockets37623
Node: Pipe connections39951
Node: UDP sockets43335
Node: ICMP sockets46171
Node: Raw sockets48719
Node: Passthrough connections50226
Node: Socket60586
Node: Coserver65050
Node: Codec68845
Node: Server types73146
Node: Server setup73881
Node: General server type75668
Node: Dynamic server77391
Node: Server79132
Node: General server79844
Node: Server configuration82506
Node: Server binding85662
Node: Server core93313
Node: Server loop99798
Node: Server socket101000
Node: Port configuration102010
Node: Booting107490
Node: Interface109180
Node: Windoze111684
Node: Index113190
Node: Function index113410
Node: Variable index133776

End Tag Table
