
(instantiate-config-type! type name instance opts)
Instantiate a configurable type.  Takes four arguments: the name of
the configurable TYPE, the second is the type NAME in
the configurable type's domain, the third is the INSTANCE
name the newly instantiated type should get and the last is the
configuration alist for the new instance.  Emits error messages (to
stderr).  Returns `#t' when the instance was successfully
created, `#f' in case of any error.

(define-server! name args)
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 args)
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 server)
Generic port -> server(s) port binding ...

(serveez-interfaces args)
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 args)
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 file)
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)
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 enable)
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 boundary)
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 flag)
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 buffer)
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 data)
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 key)
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 key)
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 value)
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 server)
Converts the SERVER instance's state into a Guile hash.
Returns an empty list if there is no such state yet.

(define-servertype! args)
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? binary)
Smob test function: Returns `#t' if the given cell BINARY is
an instance of the binary smob type.

(string->binary string)
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 binary)
Converts the given binary smob BINARY into a string.  Returns the
string cell itself.

(binary-search binary needle)
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! binary)
Performs an in place reversal of the given binary smob BINARY
and returns it.

(binary-reverse binary)
Returns a new binary smob with the reverse byte order of the given
binary smob BINARY.

(binary-set! binary index value)
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 index)
Obtain the byte at position INDEX of the binary smob
BINARY.

(binary-length binary)
Return the size in bytes of the binary smob BINARY.

(binary-concat! binary append)
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 end)
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 binary)
Convert the given binary smob BINARY into a scheme list.  The list
is empty if the size of BINARY is zero.

(list->binary list)
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 port)
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 address)
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 address)
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 netlong)
The `(svz:ntohl)' function converts the 32 bit long integer
NETLONG from network byte order to host byte order.

(svz:htonl hostlong)
The `(svz:htonl)' function converts the 32 bit long integer
HOSTLONG from host byte order to network byte order.

(svz:ntohs netshort)
The `(svz:ntohs)' function converts the 16 bit short integer
NETSHORT from network byte order to host byte order.

(svz:htons hostshort)
The `(svz:htons)' function converts the 16 bit short integer
HOSTSHORT from host byte order to network byte order.

(svz:sock:receive-buffer sock)
Return the receive buffer of the socket SOCK as a binary smob.

(svz:sock:receive-buffer-size sock size)
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 sock)
Return the send buffer of the socket SOCK as a binary smob.

(svz:sock:send-buffer-size sock size)
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 length)
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 address)
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 address)
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 parent)
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 referrer)
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 server)
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 sock)
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 sock)
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 enable)
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? sock)
Returns `#t' if the given cell SOCK is an instance of a valid
`#<svz-socket>', otherwise `#f'.

(svz:server? server)
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 counter)
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 server)
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.

(svz:server:clients server)
Returns a list of `#<svz-socket>' client smobs associated with
the given server instance SERVER in arbitrary order, or an
empty list if there is no such client.

(getrpc arg)
(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 stayopen)
(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 address)
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 port)
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 arg)
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 arg)
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 arg)
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 ident)
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 sock)
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 size)
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 oob)
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'.
