
(define-server! name arg)
Guile server definition.  Use two arguments:
First is a (unique) server name of the form "type-something" where
"type" is the shortname of a servertype.  Second is the optionhash that
is special for the server.  Uses library to configure the individual
options.  Emits error messages (to stderr).  Returns #t when server got
defined, #f in case of any error.

(define-port! name arg)
Port configuration definition.  Use two arguments:
First is a (unique) name for the port configuration.  Second is an
optionhash for various settings.  Returns #t when definition worked,
#f when it did not.  Emits error messages (to stderr).

(bind-server! port serve)
Generic port -> server(s) port binding ...

(serveez-interfaces arg)
Make the list of local interfaces accessible for Guile.  Returns the
local interfaces as a list of ip addresses in dotted decimal form.  If
another list is given in ARGS it should contain the new list of
local interfaces.

(serveez-loadpath arg)
Make the search path for the Serveez core library accessible for Guile.
Returns a list a each path as previously defined.  Can override the current
definition of this load path.  The load path is used to tell Serveez where
it can find additional server modules.

(serveez-port? name)
Returns `#t' if the given string NAME corresponds with a
registered port configuration, otherwise the procedure returns
`#f'.

(serveez-server? name)
Checks whether the given string NAME corresponds with an
instantiated server name and returns `#t' if so.

(serveez-servertype? name)
This procedure checks whether the given string NAME is a valid
server type prefix known in Serveez and returns `#t' if so.
Otherwise it returns `#f'.

(serveez-verbosity number)
Accessor for the 'verbosity' global setting.

(serveez-maxsockets number)
Accessor for the 'max sockets' global setting.

(serveez-passwd string)
Accessor for the 'password' global setting.

(serveez-load fil)
This procedure can be used as a replacement for `(primitive-load)'
in serveez configuration files.  It tries to locate the given filename
FILE in the paths returned by `(serveez-loadpath)'.  If
FILE cannot be loaded the procedure returns `#f'.

(serveez-nuke voi)
This procedure can be used to schedule Serveez for shutdown within Guile.
Serveez will shutdown all network connections and terminate after the next
event loop.  You should use this instead of issuing `(quit)'.

(serveez-exceptions enabl)
Controls the use of exceptions handlers for the Guile procedure calls
of Guile server callbacks.  If the optional argument ENABLE set to
`#t' exception handling is enabled and if set to `#f'
exception handling is disabled.  The procedure always returns the
current value of this behaviour.

(svz:sock:handle-request sock proc)
Set the `handle-request' member of the socket structure SOCK
to the Guile procedure PROC.  The procedure returns the previously
set handler if there is any.

(svz:sock:check-request sock proc)
Set the `check-request' member of the socket structure SOCK
to the Guile procedure PROC.  Returns the previously handler if
there is any.

(svz:sock:boundary sock boundar)
Setup the packet boundary of the socket SOCK.  The given string value
BOUNDARY can contain any kind of data.  If you pass an exact number
value the socket is setup to parse fixed sized packets.  In fact this
procedure sets the `check-request' callback of the given socket
structure SOCK to a predefined routine which runs the
`handle-request' callback of the same socket when it detected a
complete packet specified by BOUNDARY.  For instance you
can setup Serveez to pass your `handle-request' procedure text lines
by calling `(svz:sock:boundary sock "\\n")'.

(svz:sock:floodprotect sock fla)
Set or unset the flood protection bit of the given socket SOCK.
Returns the previous value of this bit (#t or #f).  The FLAG
argument must be either boolean or an exact number and is optional.

(svz:sock:print sock buffe)
Write the string buffer BUFFER to the socket SOCK.  The
procedure accepts binary smobs too.  Return `#t' on success and
`#f' on failure.

(svz:sock:data sock dat)
Associate any kind of data (any Guile object) given in the argument
DATA with the socket SOCK.  The DATA argument is
optional.  The procedure always returns a previously stored value or an
empty list.

(svz:server:config-ref server ke)
This procedure returns the configuration item specified by KEY of
the given server instance SERVER.  You can pass this function a
socket too.  In this case the procedure will lookup the appropriate server
instance itself.  If the given string KEY is invalid (not defined
in the configuration alist in `(define-servertype!)') then it returns
an empty list.

(svz:server:state-ref server ke)
Returns the Guile object associated with the string value KEY which
needs to be set via `(svz:server:state-set!)' previously.  Otherwise
the return value is an empty list.  The given SERVER argument must be
either a valid `#<svz-server>' object or a `#<svz-socket>'.

(svz:server:state-set! server key valu)
Associates the Guile object VALUE with the string KEY.  The
given SERVER argument can be both, a `#<svz-server>' or a
`#<svz-socket>'.  Returns the previously associated object or an
empty list if there was no such association.  This procedure is useful
for server instance state savings.

(svz:server:state->hash serve)
Converts the SERVER instance's state into a Guile hash.
Returns an empty list if there is no such state yet.

(define-servertype! arg)
Guile server definition: This procedure takes one argument containing
the information about a new server type.  If everything works fine you
have a freshly registered server type afterwards.  Return `#t' on
success.

(binary? binar)
Smob test function: Returns `#t' if the given cell BINARY is
an instance of the binary smob type.

(string->binary strin)
Converts the given string cell STRING into a binary smob.  The data
pointer of the binary smob is marked as garbage which must be free()'d
in the sweep phase of the garbage collector.

(binary->string binar)
Converts the given binary smob BINARY into a string.  Returns the
string cell itself.

(binary-search binary needl)
This routine searches through the binary smob BINARY for the cell
NEEDLE.  The latter argument can be either an exact number, character,
string or another binary smob.  It returns `#f' if the needle could
not be found and a positive number indicates the position of the first
occurrence of NEEDLE in the binary smob BINARY.

(binary-reverse! binar)
Performs an in place reversal of the given binary smob BINARY
and returns it.

(binary-reverse binar)
Returns a new binary smob with the reverse byte order of the given
binary smob BINARY.

(binary-set! binary index valu)
Set the byte at position INDEX of the binary smob BINARY to
the value given in VALUE which can be either a character or an
exact number.

(binary-ref binary inde)
Obtain the byte at position INDEX of the binary smob
BINARY.

(binary-length binar)
Return the size in bytes of the binary smob BINARY.

(binary-concat! binary appen)
Append either the binary smob or string APPEND onto the binary
smob BINARY.  If BINARY has been a simple data pointer
reference it is then a standalone binary smob as returned by
`string->binary'.

(binary-subset binary start en)
Create a subset binary smob from the given binary smob BINARY.  The
range of this subset is specified by START and END both
inclusive (thus the resulting size is = END - START + 1).
With a single exception: If END is not given or specified with -1
the routine returns all data until the end of BINARY.

(binary->list binar)
Convert the given binary smob BINARY into a scheme list.  The list
is empty if the size of BINARY is zero.

(list->binary lis)
Convert the scheme list LIST into a binary smob.  Each of the
elements of LIST is checked for validity.  The elements can be
either exact numbers in a byte's range or characters.

(binary-long-ref binary index)
Returns the `long' value of the binary smob BINARY at the
array index INDEX.

(binary-long-set! binary index value)
Sets the `long' value of the binary smob BINARY at the array
index INDEX to the given value VALUE.  The procedure returns
the previous (overridden) value.

(binary-int-ref binary index)
Returns the `int' value of the binary smob BINARY at the
array index INDEX.

(binary-int-set! binary index value)
Sets the `int' value of the binary smob BINARY at the array
index INDEX to the given value VALUE.  The procedure returns
the previous (overridden) value.

(binary-short-ref binary index)
Returns the `short' value of the binary smob BINARY at the
array index INDEX.

(binary-short-set! binary index value)
Sets the `short' value of the binary smob BINARY at the array
index INDEX to the given value VALUE.  The procedure returns
the previous (overridden) value.

(binary-char-ref binary index)
Returns the `char' value of the binary smob BINARY at the
array index INDEX.

(binary-char-set! binary index value)
Sets the `char' value of the binary smob BINARY at the array
index INDEX to the given value VALUE.  The procedure returns
the previous (overridden) value.

(svz:sock:connect host proto por)
Establishes a network connection to the given HOST [ :PORT ].
If PROTO equals `PROTO_ICMP' the PORT argument is
ignored.  Valid identifiers for PROTO are `PROTO_TCP',
`PROTO_UDP' and `PROTO_ICMP'.  The HOST argument must be
either a string in dotted decimal form, a valid hostname or an exact number
in host byte order.  When giving a hostname this operation might be
blocking.  The PORT argument must be an exact number in the range from
0 to 65535, also in host byte order.  Returns a valid `#<svz-socket>'
or `#f' on failure.

(svz:inet-ntoa addres)
The `(svz:inet-ntoa)' function converts the Internet host address
ADDRESS given in network byte order to a string in standard
numbers-and-dots notation.

(svz:inet-aton addres)
Converts the Internet host address ADDRESS from the standard
numbers-and-dots notation into binary data in network byte order.
The `(svz:inet-aton)' function returns `#f' if the address is
invalid.

(svz:ntohl netlon)
The `(svz:ntohl)' function converts the 32 bit long integer
NETLONG from network byte order to host byte order.

(svz:htonl hostlon)
The `(svz:htonl)' function converts the 32 bit long integer
HOSTLONG from host byte order to network byte order.

(svz:ntohs netshor)
The `(svz:ntohs)' function converts the 16 bit short integer
NETSHORT from network byte order to host byte order.

(svz:htons hostshor)
The `(svz:htons)' function converts the 16 bit short integer
HOSTSHORT from host byte order to network byte order.

(svz:sock:receive-buffer soc)
Return the receive buffer of the socket SOCK as a binary smob.

(svz:sock:receive-buffer-size sock siz)
Returns the current receive buffers size and fill status in bytes of
the socket SOCK as a pair of exact numbers.  If the optional
argument SIZE is given the receive buffer will be set to the
specified size in bytes.

(svz:sock:send-buffer soc)
Return the send buffer of the socket SOCK as a binary smob.

(svz:sock:send-buffer-size sock siz)
This procedure returns the current send buffer size and fill status in
bytes of the socket SOCK as a pair of exact numbers.  If the
optional argument SIZE is given the send buffer will be set to
the specified size in bytes.

(svz:sock:receive-buffer-reduce sock lengt)
Dequeue LENGTH bytes from the receive buffer of the socket
SOCK which must be a valid `#<svz-socket>'.  If the user omits
the optional LENGTH argument, all of the data in the receive buffer
gets dequeued.  Returns the number of bytes actually shuffled away.

(svz:sock:remote-address sock addres)
This procedure returns the current remote address as a pair like
`(host . port)' with both entries in network byte order.  If you pass
the optional argument ADDRESS, you can set the remote address of
the socket SOCK.

(svz:sock:local-address sock addres)
This procedure returns the current local address as a pair like
`(host . port)' with both entries in network byte order.  If you pass
the optional argument ADDRESS, you can set the local address of
the socket SOCK.

(svz:sock:parent sock paren)
Return the given socket's SOCK parent and optionally set it to the
socket PARENT.  The procedure returns either a valid
`#<svz-socket>' object or an empty list.

(svz:sock:referrer sock referre)
Return the given socket's SOCK referrer and optionally set it to the
socket REFERRER.  The procedure returns either a valid
`#<svz-socket>' or an empty list.

(svz:sock:server sock serve)
This procedure returns the `#<svz-server>' object associated with the
given argument SOCK.  The optional argument SERVER can be used
to redefine this association and must be a valid `#<svz-server>'
object.  For a usual socket callback like `connect-socket' or
`handle-request', the association is already in place.  But for sockets
created by `(svz:sock:connect)', you can use it in order to make the
returned socket object part of a server.

(svz:sock:protocol soc)
Returns one of the `PROTO_TCP', `PROTO_UDP', `PROTO_ICMP',
`PROTO_RAW' or `PROTO_PIPE' constants indicating the type of
the socket structure SOCK.  If there is no protocol information
available the procedure returns `#f'.

(svz:sock:final-print soc)
This procedure schedules the socket SOCK for shutdown after all data
within the send buffer queue has been sent.  The user should issue this
procedure call right *before* the last call to `(svz:sock:print)'.

(svz:sock:no-delay sock enabl)
Turns the Nagle algorithm for the TCP socket SOCK on or off depending
on the optional ENABLE argument.  Returns the previous state of this
flag (`#f' if Nagle is active, `#t' otherwise).  By default this
flag is switched off.  This socket option is useful when dealing with small
packet transfer in order to disable unnecessary delays.

(svz:sock? soc)
Returns `#t' if the given cell SOCK is an instance of a valid
`#<svz-socket>', otherwise `#f'.

(svz:server? serve)
Returns `#t' if the given cell SERVER is an instance of a valid
`#<svz-server>', otherwise `#f'.

(svz:sock:disconnected sock proc)
Set the `disconnected-socket' member of the socket structure
SOCK to the Guile procedure PROC.  The given callback
runs whenever the socket is lost for some external reason.  The procedure
returns the previously set handler if there is one.

(svz:sock:kicked sock proc)
Sets the `kicked-socket' callback of the given socket structure
SOCK to the Guile procedure PROC and returns any previously
set procedure.  This callback gets called whenever the socket gets
closed by Serveez intentionally.

(svz:sock:trigger-condition sock proc)
This procedure sets the `trigger-condition' callback for the socket
structure SOCK to the Guile procedure PROC.  It returns the
previously set procedure if available.  The callback is run once every
server loop indicating whether the `trigger' callback should be
run or not.

(svz:sock:trigger sock proc)
Sets the `trigger' callback of the socket structure SOCK to
the Guile procedure PROC and returns any previously set procedure.
The callback is run when the `trigger-condition' callback returned
`#t'.

(svz:sock:idle sock proc)
This procedure sets the `idle' callback of the socket structure
SOCK to the Guile procedure PROC.  It returns any previously
set procedure.  The callback is run by the periodic task scheduler when the
`idle-counter' of the socket structure drops to zero.  If this counter
is not zero it gets decremented once a second.  The `idle'
callback can reset `idle-counter' to some value and thus can
re-schedule itself for a later task.

(svz:sock:check-oob-request sock proc)
With this procedure you can setup the `check-oob-request' callback
of the given socket structure SOCK.  The previous callback is
replaced by the PROC procedure and will be returned if there was
set any before.  The callback is run whenever urgent data (out-of-band)
has been detected on the socket.

(svz:sock:idle-counter sock counte)
This functions returns the socket structure SOCK's current
`idle-counter' value.  If the optional argument COUNTER is
given, the function sets the `idle-counter'.  Please have a look at the
`(svz:sock:idle)' procedure for the exact meaning of this value.

(svz:server:listeners serve)
Returns a list of listening `#<svz-socket>' smobs to which the
given server instance SERVER is currently bound, or an empty list
if there is no such binding yet.

(getrpc ar)
(getrpcent)
(getrpcbyname name)
(getrpcbynumber number)
Lookup a network rpc service by name or by service number, and
return a network rpc service object.  The `(getrpc)' procedure
will take either a rpc service name or number as its first argument;
if given no arguments, it behaves like `(getrpcent)'.

(setrpc stayope)
(setrpcent stayopen)
(endrpcent)
The `(setrpc)' procedure opens and rewinds the file `/etc/rpc'.
If the STAYOPEN flag is non-zero, the net data base will not be
closed after each call to `(getrpc)'.  If STAYOPEN is omitted,
this is equivalent to `(endrpcent)'.  Otherwise it is equivalent to
`(setrpcent stayopen)'.

(portmap-list addres)
This procedure returns a list of the current RPC program-to-port mappings
on the host located at IP address ADDRESS.  When you leave this
argument it defaults to the local machine's IP address.  This routine
can return an empty list indicating either there is no such list
available or an error occurred while fetching the list.

(portmap prognum versnum protocol por)
A user interface to the portmap service, which establishes a mapping
between the triple [PROGNUM,VERSNUM,PROTOCOL] and
PORT on the machine's portmap service.  The value of PROTOCOL
is most likely `IPPROTO_UDP' or `IPPROTO_TCP'.
If the user omits PROTOCOL and PORT, the procedure destroys
all mapping between the triple [PROGNUM,VERSNUM,*] and ports
on the machine's portmap service.

(svz:coserver:dns host callback ar)
This procedure enqueues the HOST string argument into the internal
DNS coserver queue.  When the coserver responds, the Guile procedure
CALLBACK is run as `(callback addr arg)'.  The ADDR
argument passed to the callback is a string representing the appropriate
IP address for the given hostname HOST.  If you omit the optional
argument ARG it is run as `(callback addr)' only.  The ARG
argument may be necessary if you need to have the callback procedure
in a certain context.

(svz:coserver:reverse-dns addr callback ar)
This Guile procedure enqueues the given ADDR argument which must be
an IP address in network byte order into the internal reverse DNS coserver
queue.  When the coserver responds, the Guile procedure CALLBACK is
run as `(callback host arg)' where HOST is the hostname of the
requested IP address ADDR.  The last argument ARG is
optional.

(svz:coserver:ident sock callback ar)
This procedure enqueues the given `#<svz-socket>' SOCK into the
internal ident coserver queue.  When the coserver responds, it runs the
Guile procedure CALLBACK as `(callback user arg)' where
USER is the corresponding username for the client connection
SOCK.  The ARG argument is optional.

(svz:sock:find iden)
The given argument IDENT must be a pair of numbers where the
car is a `#<svz-socket>''s identification number and the cdr the
version number.  The procedure returns either the identified
`#<svz-socket>' or `#f' if the given combination is not
valid anymore.

(svz:sock:ident soc)
This procedure returns a pair of numbers identifying the given
`#<svz-socket>' SOCK which can be passed to
`(svz:sock:find)'.  This may be necessary when you are passing
a `#<svz-socket>' through coserver callback arguments in order to
verify that the passed `#<svz-socket>' is still valid when the
coserver callback runs.

(svz:read-file port siz)
This procedure returns either a binary smob containing a data block read
from the open input port PORT with a maximum number of SIZE
bytes or the end-of-file object if the underlying ports end has been
reached.  The size of the returned binary smob may be less than the
requested size SIZE if it exceed the current size of the given port
PORT.  The procedure throws an exception if an error occurred while
reading from the port.

(svz:sock:send-oob sock oo)
This procedure expects a TCP `#<svz-socket>' in SOCK and an
exact number or single character in OOB.  The byte in OOB
is sent as urgent (out-of-band) data through the underlying TCP stream.
The procedure returns `#t' on successful completion and otherwise
(either it failed to send the byte or the passed socket is not a TCP
socket) `#f'.
