1.1.1.1 Getting the source

Serveez can be found on https://ftp.gnu.org/gnu/serveez/, on one of the mirrors (https://www.gnu.org/prep/ftp.html) or at its original location http://www.lkcc.org/~ela/download/.

1.1.1.2 Requirements

Serveez needs GNU Guile (Ubiquitous Intelligent Language for Extensions). The current version of Serveez is known to work with Guile 1.3 and later. Guile can be downloaded at https://ftp.gnu.org/gnu/guile/.

When installing Guile, consider specifying to its configure script options along the lines of:

--enable-static --disable-shared
--disable-debug-freelist
--disable-debug-malloc
--disable-guile-debug
--disable-arrays --disable-posix
--enable-networking --disable-regex
--without-threads --enable-ltdl-convenience

This option set is tuned for Guile 1.4 and may or may not work for your particular installation; you may need to experiment a bit. Most important is that the program ‘guile-config’ be findable in a directory named in the PATH environment variable. If not, configuration will fail with message “Guile not found”.

1.1.1.3 Installation

Unpack the distribution tarball:

sleepless ~> gzip -cd serveez-0.3.1.tar.gz | tar xvf -

Change into the source directory:

sleepless ~> cd serveez-0.3.1

Configure the source package for your system:

Normally, this is done by running the configure script in the top-level directory. GNU Serveez needs a reasonably conformant C99 compiler to build. If the configure script is not able to automatically find and enable such a compiler, you can specify it directly using the ‘CC’ command-line option. For example:

sleepless ~> ./configure --prefix /gnu CC='/gnu/bin/gcc'

Note that in this example you can achieve the same results by making sure /gnu/bin is in the PATH env var.

In previous Serveez releases, the configure script had some builtin compiler flags for warnings and optimizations, conveniently exposed via command-line options. These are no longer available; instead, you can use CFLAGS for such purposes (see below). Here is a complete list of the configure script options. The list of known options can the obtained via ‘./configure --help’.

‘--enable-debug’

All of the debug messages (debug: some annoying crap text) can be suppressed by setting the debug level (-v). If you do not want these messages built in at all then disable this feature.

‘--enable-control-proto’

If you enable this feature the control protocol will be supported by Serveez. This protocol is for remote control of the server.

‘--enable-irc-proto’

Enabling this feature tells the software package to support the IRC (Internet Relay Chat) protocol.

‘--enable-irc-ts’

This feature is only available if you enabled the IRC protocol. If you enabled both of them then Serveez will support the so called TimeStamp protocol, which is an EFNet extension of the original IRC protocol. In order to connect to EFNet you MUST use this option.

‘--enable-http-proto’

When using Serveez as part of the textSure (C) chat system you will will have need of an additional web server. This option makes Serveez support a simple HTTP protocol.

‘--enable-flood’

If you enable this feature Serveez will support a simple built-in flood protection. It is always useful to protect the software from flood clients.

‘--with-mingw=DIR’

When compiling under M$-Windows the DIR argument specifies the path to the extra MinGW32 library and header files. If you want the final executable to use the Cygwin project’s cygwin1.dll instead, you have to disable this option by passing the configure script ‘--without-mingw’ or ‘--with-mingw=no’.

‘--enable-sntp-proto’

This option enables support for a simple network time protocol server.

‘--enable-poll’

If the target system supports poll and this feature is enabled the main file descriptor loop is done via poll. This helps to work around the (g)libc’s file descriptor limit. Otherwise Serveez always falls back to the select system call.

‘--enable-sendfile’

This option enables the use of the sendfile system call. Disabling it using ‘--disable-sendfile’ provides a work-around for bogus implementations of sendfile.

‘--enable-gnutella’

If you do *not* want the Gnutella spider client compiled in you need to *disable* this option.

‘--enable-crypt’

This option tells Serveez to process any passwords as crypted.

‘--enable-tunnel’

If you enable this feature the port forwarder will be included. This is useful if you plan to use Serveez as a gateway or firewall workaround.

‘--enable-fakeident’

By enabling this you will get a fake ident server included in the binary executable.

‘--enable-guile-server’

If you enable this feature the user is able to write servers using Guile.

‘--enable-passthrough’

This includes the program passthrough server in the Serveez binary. The server provides basic inetd functionality.

‘--enable-iflist’

If Serveez is unable to detect the correct list of local network interfaces (‘serveez -i’) you can disable this option and setup them manually in the configuration file.

‘--enable-heap-count’

This option depends on ‘--enable-debug’. With the debugging option disabled there is also no support for heap counters. The heap counters are used to detect memory leaks in Serveez.

‘--enable-libserveez-install’

This causes ‘make install’ to also copy libserveez and its header files to $(libdir) and $(includedir), respectively. While Serveez is in alpha (version less than ‘0.8.0’), this option is disabled by default.

For maximum flexibility and reproducibility, we recommend enabling warnings and optimizations specifying CFLAGS as a command-line option to the configure script. For reference, here is the collected set of flags built into previous Serveez releases:

(warnings)
  -W -fullwarn -pedantic -ansi
  -Wall -Wcast-align -Wstrict-prototypes
  -Wformat -Wno-unused -Wno-long-long

(optimizations)
  -O2 -fomit-frame-pointer -fstrength-reduce
  -funroll-loops -finline-functions
  -fexpensive-optimizations -fcaller-saves
  -frerun-loop-opt -foptimize-register-move
  -ffunction-cse -fpeephole -momit-leaf-frame-pointer
  -fschedule-insns2 -m486 -march=pentiumpro -O3

Note that not all flags may be compatible with your compiler or even each other. That’s one of the reasons we no longer take this approach. See Defining Variables in The Autoconf Manual.

sleepless ~/serveez-0.3.1> ./configure \
  CFLAGS='-g -O3 -Wall -Wextra'

Now compile the package:

sleepless ~/serveez-0.3.1> make

Install serveez:

You must have root privileges if you want to install the package in the standard location /usr/local or in any location that is only writable by root.

sleepless ~/serveez-0.3.1> make install

If you have problems building the package out of the box this is due to GNU libtool’s inability to handle dynamic linking in most cases. That is why we recommend to try to configure the package with ‘--disable-shared’.

1.5.1.1 Port configuration items

This table describes each configuration item for a port in Serveez. Note that not each item applies to every kind of port configuration.

proto (string)

This is the main configuration item for a port configuration setting up the type of port. Valid values are ‘tcp’, ‘udp’, ‘icmp’, ‘raw’ and ‘pipe’. This configuration item decides which of the remaining configuration items apply and which do not.

port (integer in the range 0..65535)

The port item determines the network port number on which TCP and UDP servers will listen. Thus it does not make sense for ICMP and named pipes. If you pass ‘0’ Serveez will determine a free port in the range between 1 and 65535.

recv (string or associative list)

This item describes the receiving (listening) end of a named pipe connection, i.e., the filename of a fifo node to which a client can connect by opening it for writing. Both the recv and send item apply to named pipes only. The value can either be an associative list or a simple filename. Using a simple filename leaves additional options to use default values. They deal mainly with file permissions and are described below.

send (string or associative list)

This item is the sending end of a named pipe connection. It is used to send data when the receiving (listening) end has detected a connection. The following table enumerates the additional options you can setup if you pass an associative list and not a simple filename.

name (string)

The filename of the named pipe. On Windows systems you can also specify the hostname on which the pipe should be created in the format ‘\\hostname\pipe\name’. By default (if you leave the leading ‘\\hostname\pipe\’ part) the pipe will be created on ‘\\.\pipe\name’ which refers to a pipe on the local machine.

permission (octal integer)

This specifies the file permissions a named pipe should be created with. The given number is interpreted in a Unix’ish style (e.g., ‘#o0666’ is a permission field for reading and writing for the creating user, all users in the same group and all other users).

user (string)

The file owner (username) of the named pipe in textual form.

group (string)

The file owner group (groupname) of the named pipe in textual form. If this item is left it defaults to the file owner’s primary group.

uid (integer)

The file owner of the named pipe as a user id. You are meant to specify either the uid item or the user item. Serveez will complain about conflicting values.

gid (integer)

The file owner group of the named pipe as a group id. This item defaults to the file owner’s primary group id. You are meant to specify either the gid item or the group item. Serveez will croak about conflicting values.

ipaddr (string)

This configuration item specifies the IP address (either in dotted decimal form e.g., ‘192.168.2.1’ or as a device description which can be obtained via ‘serveez -i’) to which a server is bound to. The ‘*’ keyword for all known IP addresses and the ‘any’ keyword for any IP address are also valid values. The default value is ‘*’. The configuration item applies to network ports (TCP, UDP and ICMP) only.

device (string)

The device configuration item also refers to the IP address a server can be bound to. It overrides the ipaddr item. Valid values are network device descriptions (probably no aliases and no loopback devices). It applies to network ports (TCP, UDP and ICMP) only.

A note on device bindings: Device bindings are based on the SO_BINDTODEVICE socket layer option. This option is not available on all systems. We only tested it on GNU/Linux (2.2.18 and 2.4.17 as of this writing). Device bindings are very restrictive: only root can do it and only physical devices are possible. The loopback device cannot be used and no interface alias (i.e., ‘eth0:0’). A device binding can only be reached from the physical outside but it includes all aliases for the device. So if you bind to device ‘eth0’ even ‘eth0:0’ (and all other aliases) are used. The connection has to be made from a remote machine. The advantage of this kind of binding is that it survives changes of IP addresses. This is tested for ethernet networks (i.e., eth*) and isdn dialups (i.e., ippp*). It does not work for modem dialups (i.e., ppp*) (at least for Stefan’s PCMCIA modem). The problem seems to be the dialup logic actually destroying ppp*. Other opinions are welcome. Device bindings always win: If you bind to ‘*’ (or an individual IP address) and to the corresponding device, connections are made with the device binding. The order of the bind-server! statements do not matter. This feature is not thoroughly tested.

backlog (integer)

The backlog parameter defines the maximum length the queue of pending connections may grow to. If a connection request arrives with the queue full the client may receive an error. This parameter applies to TCP ports only.

type (integer in the range 0..255)

This item applies to ICMP ports only. It defines the message type identifier used to send ICMP packets (e.g., ‘8’ is an echo message i.e., PING).

send-buffer-size (integer)

The send-buffer-size configuration item defines the maximum number of bytes the send queue of a client is allowed to grow to. The item influences the “send buffer overrun error condition”. For packet oriented protocols (UDP and ICMP) you need to specify at least the maximum number of bytes a single packets can have. For UDP and ICMP this is 64 KByte. The value specified here is an initial value. It is used unless the server bound to this port changes it.

recv-buffer-size (integer)

The recv-buffer-size configuration item defines the maximum number of bytes the receive queue of a client is allowed to grow to. The item influences the “receive buffer underrun error condition”. The value specified here is an initial value. It is used unless the server bound to this port changes it.

connect-frequency (integer)

This item determines the maximum number of connections per second the port will accept. It is a kind of “hammer protection”. The item is evaluated for each remote client machine separately. It applies to TCP ports.

allow (list of strings)

Both the allow and deny lists are lists of IP addresses in dotted decimal form (e.g., ‘192.168.2.1’). The allow list defines the remote machines which are allowed to connect to the port. It applies to TCP ports.

deny (list of strings)

The deny list defines the remote machines which are not allowed to connect to the port. Each connection from one of these IP addresses will be refused and shut down immediately. It applies to TCP ports.

1.5.1.2 TCP port definition

Definition of a TCP port configuration with the name foo-tcp-port. The enhanced settings are all optional including the ipaddr property which defaults to ‘*’. The ipaddr item can contain any form of a dotted decimal internet address, a ‘*’, ‘any’ or an interface description which you can obtain by running ‘serveez -i’.

(define-port! 'foo-tcp-port '(
    ;; usual settings
    (proto  . tcp)              ;; protocol is tcp
    (port   . 42421)            ;; network port 42421
    (ipaddr . *)                ;; bind to all known interfaces
    (device . eth0)             ;; bind to network card

    ;; enhanced settings
    (backlog           . 5)     ;; enqueue max. 5 connections
    (connect-frequency . 1)     ;; allow 1 connect per second
    (send-buffer-size  . 1024)  ;; initial send buffer size in bytes
    (recv-buffer-size  . 1024)  ;; initial receive buffer size in bytes

    ;; allow connections from these ip addresses
    (allow             . (127.0.0.1 127.0.0.2))

    ;; refuse connections from this ip address
    (deny              . (192.168.2.7))
  ))

1.5.1.3 Pipe port definition

Definition of a pipe port configuration with the name foo-pipe-port. When bound to a server it creates the receiving end and listens on that. If some client accesses this named pipe the server opens the sending end which the client has to open for reading previously.

The only mandatory item is the file name of each pipe. If you want to specify a user creating the named pipe (file ownership) use either the user or the uid setting. Same goes for the items group and gid.

(define-port! 'foo-pipe-port `(
    (proto . pipe)                   ;; protocol is named pipe

    ;; specify the receiving endpoint
    (recv . ((name . ".foo-recv")    ;; name of the pipe
             (permissions . #o0666)  ;; create it with these permissions
             (user . "calvin")       ;; as user "calvin"
             (uid . 50)              ;; with the user id 50
             (group . "heros")       ;; which is in the group "heros"
             (gid . 100)))           ;; with the group id 100

    ;; specify the sending endpoint
    (send . ((name . ".foo-send")
             (permissions . #o0666)
             (user . "hobbes")
             (uid . 51)
             (group . "stuffed")
             (gid . 101)))
   ))

1.5.1.4 ICMP port definition

Define an ICMP port configuration which will accept connections from the network interface ‘127.0.0.1’ only and communicates via the message type 8 as described in the Tunnel Server chapter. The name of this port configuration is foo-icmp-port. When you are going to bind some server to this kind of port you have to ensure root (or Administrator under Windows) privileges.

(define-port! 'foo-icmp-port '((proto  . icmp)
                               (ipaddr . 127.0.0.1)
                               (type   . 8)))

1.5.1.5 UDP port definition

Simple definition of a UDP port configuration with the name foo-udp-port.

(define-port! 'foo-udp-port `((proto . udp)
                              (port  . 27952)))

1.5.4.1 output

Scheme Procedure: fs s [args…] ¶

Return a string made by applying simple-format #f to s and args. For example:

(fs "~A-~S" 'foo 42)
⇒ "foo-42"

Scheme Procedure: println [object…] ¶

Do display on each object. Then, output a newline.

Scheme Procedure: printsln spacer [object…] ¶

For each object, do display on it and on spacer, as well. Then, output a newline.

1.5.4.2 augmenting

Scheme Procedure: interface-add! interface ¶

Add interface to the list of known network interfaces. You can get the list of known interfaces by running the shell command ‘serveez -i’. The interface argument must be in dotted decimal form (e.g., ‘127.0.0.1’). Serveez provides this procedure for systems where it is unable to detect the list of network interface automatically.

Scheme Procedure: loadpath-add! [dir…] ¶

Append dir… to the server modules load path.

Scheme Procedure: serveez-load filename ¶

Try to load filename (via primitive-load). If filename is not absolute, search for it in the list of directories returned by serveez-loadpath. Return #t if successful, #f otherwise.

1.5.4.3 abstractions

Scheme Procedure: bind-servers! [args…] ¶

Bind all servers and ports in args to each other. This is a cross-product operation; given s servers, and p ports, s * p bindings will be created.

Scheme Procedure: create-tcp-port! basename port ¶

Define a new TCP port named by concatenating basename and port. Return the new name.

Scheme Procedure: bind-tcp-port-range! from to [servers…] ¶

Bind the list of servers to simple TCP port configurations whose network ports range between from and to both inclusive.

Scheme Procedure: create-udp-port! basename port ¶

Define a new UDP port named by concatenating basename and port. Return the new name.

Scheme Procedure: bind-udp-port-range! from to [servers…] ¶

Bind the list of servers to simple UDP port configurations whose network ports range between from and to both inclusive.

1.5.4.4 rpc

Scheme Procedure: getrpcent ¶

Return the next RPC entry as a vector of the form: #(name aliases program-number). name is a symbol, aliases is a list (possibly empty) of symbols, and program-number is an integer. If the list is exhausted, return #f.

Scheme Procedure: getrpcbyname name ¶

Return the RPC entry for name, a string. (FIXME: Should be able to handle a symbol, too.) If no such service exists, signal error.

Scheme Procedure: getrpcbynumber number ¶

Return the RPC entry for number, an integer. If no such service exists, signal error.

Scheme Procedure: setrpcent [stayopen] ¶

Open and rewind the file /etc/rpc. If optional arg stayopen (an integer) is non-zero, the database will not be closed after each call to getrpc (or its derivatives getrpcent, getrpcbyname, getrpcbynumber).

Scheme Procedure: endrpcent ¶

Close the file /etc/rpc.

1.5.4.5 misc

Scheme Procedure: serveez-verbosity [level] ¶

Return the verbosity level (an integer). Optional arg level means set it to that level, instead. This setting is overridden by the command-line ‘-v’ option.

Scheme Procedure: serveez-maxsockets [max] ¶

Return the maximum number of open sockets permitted (an integer). Optional arg max means set it to that number, instead. This setting is overridden by the command-line ‘-m’ option.

Scheme Procedure: serveez-passwd [pw] ¶

Return the control password (a string). Optional arg pw sets it to that, instead. This effectively does nothing if the control protocol is not enabled.

We now have a closer look at the internals of Serveez. If you are not interested in that have a look at the existing servers (See Existing servers.).

3.2.1.1 Prerequisites

In order to implement a server module you need an existing installation of Serveez. This can be achieved issuing the following commands:

$ ./configure --enable-shared --prefix=/usr/local
$ make
$ make install

After successful installation you are able to compile and link against the Serveez core API. The headers should be available in /usr/local/include and the library itself (libserveez.so or libserveez.dll) is located in /usr/local/lib if you passed the configure script ‘--prefix=/usr/local’.

3.2.1.2 Server definition

The interface mentioned in the introduction is defined via the extern declaration of the server type in the shared library of the server module. Imagine you want to implement a server type called ‘foo’. This requires the external symbol foo_server_definition in the shared library. You can achieve this inserting the following lines into your header file:

/* Either Unices.  */
extern svz_servertype_t foo_server_definition;

/* Or Windows.  */
__declspec (dllexport) extern svz_servertype_t foo_server_definition;

The data symbol foo_server_definition must be statically filled with the proper content (See Builtin servers.)

3.2.2.1 Underlying libserveez

Scheme Procedure: libserveez-features ¶

Return a list of symbols representing the features of the underlying libserveez. For details, See Library features.

3.2.2.2 Special Data Types

Serveez extends Guile by various new data types which represent internal data structures of Serveez’s core API.

• #<svz-servertype> represents a server type.
• #<svz-server> represents a server (an instance of a server type).
• #<svz-socket> represents a socket structure.

3.2.2.3 Passing Binary Data

The new binary data type (#<svz-binary>) provides access to any kind of unstructured data. It manages the data exchange between Guile and Serveez. There are some conversion procedures for strings and lists which help to process this binary data in a more complex (guile’ish) way.

Scheme Procedure: binary->string binary ¶

Convert the given binary smob binary into a string. Return the string itself.

Scheme Procedure: string->binary string ¶

Convert the given 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.

Scheme Procedure: binary? obj ¶

Return #t if obj is an instance of the binary smob type.

Scheme Procedure: 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.

Scheme Procedure: binary->list binary ¶

Convert the given binary smob binary into a scheme list. The list is empty if the size of binary is zero.

Scheme Procedure: binary-search binary needle ¶

Search through the binary smob binary for needle, which can be an exact number, character, string or another binary smob. Return #f if the needle could not be found, or a positive number indicating the position of the first occurrence of needle in the binary smob binary.

Scheme Procedure: 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.

Scheme Procedure: binary-ref binary index ¶

Obtain the byte at position index of the binary smob binary.

Scheme Procedure: binary-length binary ¶

Return the size in bytes of the binary smob binary.

Scheme Procedure: 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.

Scheme Procedure: 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, return all data until the end of binary.

Scheme Procedure: binary-reverse binary ¶

Return a new binary smob with the reverse byte order of the given binary smob binary.

Scheme Procedure: binary-reverse! binary ¶

Perform an in-place reversal of the given binary smob binary and return it.

Scheme Procedure: binary-long-ref binary index ¶

Return the long value of the binary smob binary at the array index index.

Scheme Procedure: binary-long-set! binary index value ¶

Set the long value of the binary smob binary at the array index index to the given value value. Return the previous (overridden) value.

Scheme Procedure: binary-int-ref binary index ¶

Return the int value of the binary smob binary at the array index index.

Scheme Procedure: binary-int-set! binary index value ¶

Set the int value of the binary smob binary at the array index index to the given value value. Return the previous (overridden) value.

Scheme Procedure: binary-short-ref binary index ¶

Return the short value of the binary smob binary at the array index index.

Scheme Procedure: binary-short-set! binary index value ¶

Set the short value of the binary smob binary at the array index index to the given value value. Return the previous (overridden) value.

Scheme Procedure: binary-char-ref binary index ¶

Return the char value of the binary smob binary at the array index index.

Scheme Procedure: binary-char-set! binary index value ¶

Set the char value of the binary smob binary at the array index index to the given value value. Return the previous (overridden) value.

3.2.2.4 Server Definition

In order to set up a new server type, you use the procedure define-servertype!. This procedure takes one argument which must be an associative list specifying the server type in detail. There are optional and mandatory elements you can set up in this alist.

The following example shows the overall syntax of this procedure:

(define-servertype! '(

  ;; Mandatory: server type prefix for later use in (define-server!)
  (prefix          . "foo")

  ;; Mandatory: server type description
  (description     . "guile foo server")

  ;; Mandatory for TCP and PIPE servers: protocol detection
  (detect-proto    . foo-detect-proto)

  ;; Optional: global server type initialisation
  (global-init     . foo-global-init)

  ;; Optional: server instance initialisation
  (init            . foo-init)

  ;; Optional: server instance finalisation
  (finalize        . foo-finalize)

  ;; Optional: global server type finalisation
  (global-finalize . foo-global-finalize)

  ;; Mandatory for TCP and PIPE servers: socket connection
  (connect-socket  . foo-connect-socket)

  ;; Optional: server instance info
  (info-server     . foo-info-server)

  ;; Optional: client info
  (info-client     . foo-info-client)

  ;; Optional: server instance reset callback
  (reset           . foo-reset)

  ;; Optional: server instance notifier
  (notify          . foo-notify)

  ;; Mandatory for UDP and ICMP servers: packet handler
  (handle-request  . foo-handle-request)

  ;; Mandatory: server type configuration (may be an empty list)
  (configuration   . (

    ;; The server configuration is an alist (associative list) again.
    ;; Each item consists of an item name and a list describing the
    ;; item itself.
    ;; Syntax: (key . (type defaultable default))
    (foo-integer       . (integer  #t 0))
    (foo-integer-array . (intarray #t (1 2 3 4 5)))
    (foo-string        . (string   #t "default-foo-string"))
    (foo-string-array  . (strarray #t ("guile" "foo" "server")))
    (foo-hash          . (hash     #t (("foo" . "bar"))))
    (foo-port          . (portcfg  #t foo-port))
    (foo-boolean       . (boolean  #t #t))
  ))))

Scheme Procedure: define-servertype! args ¶

Define a new server type based on args. (If everything works fine you have a freshly registered server type afterwards.) Return #t on success.

3.2.2.5 Predefined Procedures

The following subset of procedures may be used to implement a Guile server. They should be used within the callbacks defined in the define-servertype! procedure. Each of these callbacks gets passed the appropriate arguments needed to stuff into the following procedures. Please have a look at the example Guile servers for the details.

Scheme Procedure: svz:sock? sock ¶

Return #t if the given cell sock is an instance of a valid #<svz-socket>, otherwise #f.

Scheme Procedure: svz:sock:check-request sock [proc] ¶

Set the check-request member of the socket structure sock to proc. Return the previously handler if there is any.

Scheme Procedure: svz:sock:check-oob-request sock [proc] ¶

Set the check-oob-request callback of the given socket structure sock to proc, returning the previous callback (if there was any set before). The callback is run whenever urgent data (out-of-band) has been detected on the socket.

Scheme Procedure: svz:sock:send-oob sock oob ¶

Send byte oob as urgent (out-of-band) data through the underlying TCP stream of TCP sock. Return #t on successful completion and otherwise (either it failed to send the byte or the passed socket is not a TCP socket) #f.

Scheme Procedure: svz:sock:handle-request sock [proc] ¶

Set the handle-request member of the socket structure sock to proc. Return the previously set handler if there is any.

Scheme Procedure: 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 boundary is an exact number, set up the socket to parse fixed sized packets. More precisely, set the check-request callback of the given socket structure sock to an internal routine which runs the socket’s handle-request callback when it detects a complete packet specified by boundary.

For instance, you can arrange for Serveez to pass the handle-request procedure lines of text by calling (svz:sock:boundary sock "\n").

Scheme Procedure: svz:sock:floodprotect sock [flag] ¶

Set or unset the flood protection bit of the given socket sock. Return the previous value of this bit (#t or #f). The flag argument must be either boolean or an exact number and is optional.

Scheme Procedure: svz:sock:print sock buffer ¶

Write buffer (string or binary smob) to the socket sock. Return #t on success and #f on failure.

Scheme Procedure: svz:sock:final-print sock ¶

Schedule the socket sock for shutdown after all data within the send buffer queue has been sent. You should call this right before the last call to svz:sock:print.

Scheme Procedure: svz:sock:no-delay sock [enable] ¶

Turn the Nagle algorithm for the TCP socket sock on or off depending on the optional enable argument. Return 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.

Scheme Procedure: svz:sock:send-buffer sock ¶

Return the send buffer of the socket sock as a binary smob.

Scheme Procedure: svz:sock:send-buffer-size sock [size] ¶

Return 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, set the send buffer to the specified size in bytes.

Scheme Procedure: svz:sock:receive-buffer sock ¶

Return the receive buffer of the socket sock as a binary smob.

Scheme Procedure: svz:sock:receive-buffer-size sock [size] ¶

Return 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, set the receive buffer to the specified size in bytes.

Scheme Procedure: svz:sock:receive-buffer-reduce sock [length] ¶

Dequeue length bytes from the receive buffer of the socket sock, or all bytes if length is omitted. Return the number of bytes actually shuffled away.

Scheme Procedure: svz:sock:connect host proto [port] ¶

Establish 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 block. The port argument must be an exact number in the range from 0 to 65535, also in host byte order. Return a valid #<svz-socket> or #f on failure.

Scheme Procedure: svz:sock:disconnected sock [proc] ¶

Set the disconnected-socket member of the socket structure sock to proc. The given callback runs whenever the socket is lost for some external reason. Return the previously set handler if there is one.

Scheme Procedure: svz:sock:kicked sock [proc] ¶

Set the kicked-socket callback of the given socket structure sock to proc and return any previously set procedure. This callback gets called whenever the socket gets closed by Serveez intentionally.

Scheme Procedure: svz:sock:trigger sock [proc] ¶

Set the trigger callback of the socket structure sock to proc and return any previously set procedure. The callback is run when the trigger-condition callback returns #t.

Scheme Procedure: svz:sock:trigger-condition sock [proc] ¶

Set the trigger-condition callback for the socket structure sock to proc. Return the previously set procedure if available. The callback is run once every server loop indicating whether the trigger callback should be run or not.

Scheme Procedure: svz:sock:idle sock [proc] ¶

Set the idle callback of the socket structure sock to proc. Return 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.

Scheme Procedure: svz:sock:idle-counter sock [counter] ¶

Return the socket structure sock’s current idle-counter value. If the optional argument counter is given, the set the idle-counter. Please have a look at the svz:sock:idle procedure for the exact meaning of this value.

Scheme Procedure: svz:sock:parent sock [parent] ¶

Return the given socket’s sock parent and optionally set it to the socket parent. Return either a valid #<svz-socket> object or an empty list.

Scheme Procedure: svz:sock:referrer sock [referrer] ¶

Return the given socket’s sock referrer and optionally set it to the socket referrer. Return either a valid #<svz-socket> or an empty list.

Scheme Procedure: svz:sock:server sock [server] ¶

Return 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.

Scheme Procedure: svz:sock:local-address sock [address] ¶

Return 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.

Scheme Procedure: svz:sock:remote-address sock [address] ¶

Return 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.

Scheme Procedure: svz:sock:find ident ¶

Return the #<svz-socket> specified by ident, a pair of integers in the form (identification . version). If that socket no longer exists, return #f.

Scheme Procedure: svz:sock:ident sock ¶

Return 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.

Scheme Procedure: svz:sock:protocol sock ¶

Return 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, return #f.

Scheme Procedure: svz:read-file port size ¶

Return 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. Throw an exception if an error occurred while reading from the port.

Scheme Procedure: svz:server? server ¶

Return #t if the given cell server is an instance of a valid #<svz-server>, otherwise #f.

Scheme Procedure: svz:server:listeners server ¶

Return 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.

Scheme Procedure: svz:server:clients server ¶

Return 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.

Scheme Procedure: svz:server:config-ref server key ¶

Return the configuration item specified by key of the given server instance server. You can pass this procedure a socket, too, in which case the appropriate server instance is looked up. If the given string key is invalid (not defined in the configuration alist in define-servertype!), then return an empty list.

Scheme Procedure: serveez-port? name ¶

Return #t if the given string name corresponds with a registered port configuration, otherwise #f.

Scheme Procedure: serveez-server? name ¶

Check whether the given string name corresponds with an instantiated server name and return #t if so.

Scheme Procedure: serveez-servertype? name ¶

Check whether the given string name is a valid server type prefix known in Serveez and return #t if so. Otherwise return #f.

Scheme Procedure: serveez-exceptions [enable] ¶

Control the use of exception handlers for the Guile procedure calls of Guile server callbacks. If the optional argument enable is #t, enable exception handling; if #f, disable it. Return the current (boolean) setting.

Scheme Procedure: serveez-nuke [exit-value] ¶

Shutdown all network connections and terminate after the next event loop. You should use this instead of calling quit. Optional arg exit-value specifies an exit value for the serveez program. It is mapped to a number via scm_exit_value.

Scheme Procedure: serveez-loadpath [args] ¶

Make the search path for the Serveez core library accessible to Scheme. Return a list a each path as previously defined. If args is specified, override the current definition of this load path with it. The load path is used to tell Serveez where it can find additional server modules.

Scheme Procedure: serveez-interfaces [args] ¶

Make the list of local interfaces accessible to Scheme. Return the local interfaces as a list of ip addresses in dotted decimal form. If args are specified, they are added as additional local interfaces.

Scheme Procedure: getrpc [arg] ¶

Lookup a network rpc service arg (name or service number), and return a network rpc service object. If given no arguments, it behave like getrpcent.

Scheme Procedure: setrpc [stayopen] ¶

Open and rewind 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 calling endrpcent. Otherwise it is equivalent to calling setrpcent with arg 1.

Scheme Procedure: portmap prognum versnum [protocol [port]] ¶

Establish a (portmap service) 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 instead protocol and port are omitted, destroy all mapping between the triple [prognum,versnum,*] and ports on the machine’s portmap service.

Scheme Procedure: portmap-list [address] ¶

Return a list of the current RPC program-to-port mappings on the host located at IP address address, which defaults to the local machine’s IP address. Return an empty list if either there is no such list available or an error occurred while fetching the list.

Scheme Procedure: svz:coserver:dns host callback ¶

Enqueue the host string argument into the internal DNS coserver queue. When the coserver responds, the procedure callback is run as (callback addr). The addr argument passed to the callback is a string representing the appropriate IP address for the given hostname host.

Scheme Procedure: svz:coserver:reverse-dns addr callback ¶

Enqueue 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 procedure callback is run as (callback host) where host is the hostname of the requested IP address addr.

Scheme Procedure: svz:coserver:ident sock callback ¶

Enqueue the given #<svz-socket> sock into the internal ident coserver queue. When the coserver responds, it runs the procedure callback as (callback user), where user is the corresponding username for the client connection sock.

3.2.2.6 Callback Prototypes

The Guile interface of Serveez is completely callback driven. Callbacks can be set up in the associative list passed to define-servertype!, or by using the predefined procedures described in the previous section. Each of the callbacks is passed certain arguments and is meant to return specific values to indicate success or failure. This section describes each of these callbacks.

Scheme Procedure: global-init servertype ¶

This callback is invoked once for every type of server right after the define-servertype! statement. Here you can initialise resources shared between all instances of your server type. The callback is optional and can be set up in define-servertype!. It should return zero to indicate success and non-zero to indicate failure. If the global initialiser fails, Serveez will refuse to register the server type.

Scheme Procedure: global-finalize servertype ¶

If you want to free shared resources, which were possibly allocated within the global initialiser, you can do so here. The callback is invoked when Serveez shuts down (issued by serveez-nuke) or the server type gets unregistered for some reason. It should return zero to signal success. The callback can be set up in define-servertype! and is optional.

Scheme Procedure: init server ¶

Within this callback you can initialise everything you might need for a single instance of your server. The callback is invoked for each server instance which has been created by define-server! and should return zero to indicate success, otherwise Serveez rejects the server instance. The callback can be set up in define-servertype! and is optional.

Scheme Procedure: finalize server ¶

The server instance finaliser gets its instance representation passed as argument. You need to free all resources used by this server instance which might have been allocated within the server instance initialiser or consumed while running. You can set this callback in the define-servertype! statement. The callback is optional and should return zero to indicate success.

Scheme Procedure: detect-proto server socket ¶

Connection oriented protocols like TCP and PIPE allow more than one server to be listening on the same network port. Therefore, it is necessary to be able to detect the type of client connecting to a port.

This callback takes two arguments; the first is the server instance and the second is the client socket object containing the client connection information. You can set up this callback in the define-servertype! statement.

Serveez may invoke this callback several times as data becomes available from the client until one of the servers recognises it. The servers can retrieve the data received so far using the svz:sock:receive-buffer call.

To indicate successful client detection, you need to return a non-zero value. (Note that for historical reasons, this is inconsistent with other procedures which return zero on successful completion.) Once the server has indicated success, Serveez invokes any further callbacks for the connection only on that server.

If no server has recognised the client after the first 16 bytes, Serveez will close the connection. The connection will also be closed if the client has not sent enough data for a server to recognise it within 30 seconds of connecting.

If multiple servers are listening on the same network port, Serveez invokes this callback for each of them in an arbitrary order. Only one server at most should indicate successful detection.

This callback is mandatory for servers which get bound to connection oriented protocol (TCP and PIPE) port configurations by bind-server!.

Scheme Procedure: connect-socket server socket ¶

If the client detection signalled success, this callback is invoked to assign the client connection to a server instance. The arguments are the same as the detection callback. In this callback you can assign all the connection specific callbacks for your server and perform some initial tasks. Basically you should specify the handle-request and/or check-request callback. This can be achieved by calling svz:sock:handle-request and svz:sock:check-request. The connect-socket callback is also mandatory for connection oriented protocols and must be defined in define-servertype!. On success you should return zero, otherwise the connection will be shutdown by Serveez.

Scheme Procedure: info-server server ¶

This callback gets invoked when requested by the builtin Control Protocol Server. The callback is optional and can be set up in define-servertype!. The returned character string can be multiple lines separated by \r\n (but without a trailing separator). Usually you will return information about the server instance configuration and/or state.

Scheme Procedure: info-client server socket ¶

This callback is optional. You can set it up in the define-servertype! procedure. It is meant to provide socket structure specific information. (The socket structure is a client/child of the given server instance.) You need to return a single line character string without trailing newlines. The information provided can be requested by the builtin Control Protocol Server.

Scheme Procedure: notify server ¶

The server instance notifier callback will be invoked whenever there is idle time available. In practice, it is run approximately once a second. A server instance can use it to perform periodic tasks. The callback is optional and can be set up in define-servertype!.

Scheme Procedure: reset server ¶

This callback is invoked when the Serveez process receives a SIGHUP signal which can be issued via ‘killall -HUP serveez’ from user land. If the underlying operating system does not provide SIGHUP there is no use for this callback. It provides the possibility to perform asynchronous tasks scheduled from outside Serveez. You can optionally set it up in the define-servertype! procedure.

Scheme Procedure: handle-request socket binary size ¶

This callback is invoked whenever a complete packet has been detected in the receive buffer. The packet data is passed to the callback as a #<svz-binary>. The size argument is passed for convenience and specifies the length of the packet in bytes.

The detection, and therefore the invocation, can be made in one of two ways. When Serveez can determine itself when a packet is complete, the callback will be invoked directly. Serveez can make this determination for connections with packet oriented protocols such as UDP and ICMP, or if you tell Serveez how to parse the packet using svz:sock:boundary sock delimiter or svz:sock:boundary sock size and do not specify a check-request callback.

Whenever you specify a check-request callback to determine when a packet is complete, it becomes the responsiblity of that callback to invoke handle-request itself.

Serveez recognises two different return value meanings. For connection oriented protocols (TCP and PIPE), zero indicates success and non-zero failure; on failure, Serveez will shutdown the connection. For packet oriented protocols (UDP and ICMP), a non-zero return value indicates that your server was able to process the passed packet data, otherwise (zero return value) the packet can be passed to other servers listening on the same port configuration.

This callback must be specified in define-servertype! for packet oriented protocols (UDP and ICMP) but is optional otherwise. You can modify the callback by calling svz:sock:handle-request.

Scheme Procedure: check-request socket ¶

This callback is invoked whenever new data has arrived in the receive buffer. The receive buffer of the given #<svz-socket> can be obtained using svz:sock:receive-buffer. The callback is initially not set and can be set up with svz:sock:check-request. Its purpose is to check whether a complete request was received. If so, it should be handled (by running the handle-request callback) and removed from the receive buffer (using svz:sock:receive-buffer-reduce). The callback is for connection oriented protocols (TCP and PIPE) only. You should return zero to indicate success and non-zero to indicate failure. On failure Serveez shuts the connection down.

Scheme Procedure: disconnected socket ¶

The disconnected callback gets invoked whenever the socket is lost for some external reason and is going to be shutdown by Serveez. It can be set up with svz:sock:disconnected.

Scheme Procedure: kicked socket reason ¶

This callback gets invoked whenever the socket gets closed by Serveez intentionally. It can be set up with svz:sock:kicked. The reason argument can be either KICK_FLOOD, indicating the socket is a victim of the builtin flood protection, or KICK_QUEUE which indicates a send buffer overflow.

Scheme Procedure: idle socket ¶

The idle callback gets invoked from the periodic task scheduler, which maintains a idle-counter for each socket structure. This counter is decremented whenever Serveez becomes idle and the callback is invoked when it drops to zero. The idle callback can set its socket’s idle-counter to some value with the procedure svz:sock:idle-counter and thus re-schedule itself for a later task. You can set up this callback with svz:sock:idle.

Scheme Procedure: trigger-condition socket ¶

This callback is invoked once every server loop for the socket structure. If you return #f nothing else is happening. Otherwise the trigger callback will be invoked immediately. You can set up the callback using the procedure svz:sock:trigger-condition.

Scheme Procedure: trigger socket ¶

The trigger callback is invoked when the trigger-condition returns #t. The callback can be set up with the procedure svz:sock:trigger. Returning a non-zero value shuts the connection down. A zero return value indicates success. This callback can be used to perform connection related updates, e.g., you can ensure a certain send buffer fill.

Scheme Procedure: check-oob-request socket oob-byte ¶

This callback is invoked whenever urgent data (out-of-band) has been detected on a socket. Initially this event is ignored and the callback can be set up with the procedure svz:sock:check-oob-request. The oob-byte argument is a number containing the received out-of-band data byte ranging from 0 to 255. If the callback returns non-zero the connection will be shutdown. A zero return value indicates success. You can use svz:sock:send-oob to send a single out-of-band data byte.

Please note: The urgent data is not supported by all operating systems. Also it does not work for all types of network protocols. We verified it to be working for TCP streams on GNU/Linux 2.x.x and Windows 95; let us know if/how it works on other platforms.

3.2.3.1 Making and configuring preparations

Serveez is configured and built via automake and autoconf. That is why you are not supposed to write your own Makefiles but simplified Makefile.ams. Automake will automatically generate dependencies and compiler/linker command lines. Here are the steps you basically need to follow:

• Change to the src/ directory in the source tree.
• Edit the Makefile.am. Add your sub directory name and library name which you are going to create.
• Now create the sub directory and change into it.
• You need to create a new Makefile.am therein. If you want to have this file configured you need to add a further line to the AC_OUTPUT statement in configure.ac which is in the top level directory. You have to put at least the following into the newly created Makefile.am:

  noinst_LIBRARIES = libfoo.a
  libfoo_a_SOURCES = foo-proto.h foo-proto.c
  INCLUDES = $(SERVEEZ_CFLAGS) -I$(top_srcdir)/src
  CLEANFILES = *~
  MAINTAINERCLEANFILES = Makefile.in
  

• Just have a look at all the other server directories. For more information about automake read the info pages.

3.2.3.2 Server header file foo-proto.h

This file contains at least your server’s extern declaration of your server definition which must be available from the outside. The foo server implements all kinds of configuration items which can be integers, integer arrays, strings, string arrays, port configurations, booleans and hash maps. Every item of the server configuration can later be manipulated from the configuration file.

3.2.3.3 Server implementation file foo-proto.c

If you want to define default values for your configuration you have to define them somewhere and put them into the default configuration structure. This structure will be used to instantiate your server. For this example we simply called it simply foo_config.

In order to associate the configuration items in a server configuration to keywords within the configuration file you have to define an array of key-value-pairs. This is done in the foo_config_prototype field. There are several macros which make different associations. These are the SVZ_REGISTER_* macros which take three arguments. The first argument is the keyword which will occur in the configuration file, the second is the associated item in your default configuration structure and the last argument specifies if this item is defaultable or not.

3.2.3.4 Server definition

The server definition is in a way the ‘class’ of your server. Together with the default values (foo_config_prototype) it serves as a template for newly instantiated servers. The structure contains a long and a short description of your server. The short name is used as the prefix for all server instances of this specific type. The long description is used in the control protocol (See Control Protocol Server.). The server definition also contains the callbacks your server (mandatorily) provides.

3.2.3.5 Server callbacks

There are several callback routines, which get called in order to instantiate the server and for describing the actual behaviour of your server. Here are the description of all of these callbacks. Some of them have to be implemented. Others have reasonable default values.

global initializer (optional)

This callback is executed once for every type of server. Here you can initialize data or whatever is shared between all instances of your server. For instance the HTTP server initializes its file cache here.

global finalizer (optional)

If you want to free shared resources which were possibly allocated within the global initializer you can do so here. The foo server frees its default hash previously allocated in the global initializer.

instance initializer (mandatory)

Within this routine you can initialize everything you might need for one instance of your server. The foo server does not do anything in this callback.

instance finalizer (optional)

The server instance finalizer gets its instance representation as argument. You have to free all resources used by this server instance.

protocol detection (mandatory)

Because it is possible to have more than one server listening on one network port we need to detect the type of client which is connecting to this port. The foo server checks if the first five bytes the client was sending is identifying it as a foo client. This routine is getting two arguments where the first one is a pointer to this servers instance and the second is the client socket object containing all information of the client connection. This structure is described a bit later. Be patient. For successful client detection return non-zero value.

socket connection (mandatory)

If the client detection signaled success this routine is called to assign the client connection to the server instance. The arguments are just the same as in the detection routine. In this callback you can assign all the connection specific callbacks for your server and do some initial things. The foo server sets the check_request callback to the default svz_sock_check_request which is using the packet delimiter information to find whole packets. When a client sent such a packet the handle_request callback is executed. That is why the foo server assigns the handle_request method.

client info (optional)

If this callback is given the control protocol (See Control Protocol Server.) can give information about a specific client if requested with ‘stat id NUM’. The first argument given is the server instance and the second one the client’s socket structure. You have to return a static single line character string.

server info (optional)

This function is called when listing the server instances via ‘stat all’ from the control protocol (See Control Protocol Server.). The returned character string might be multilined separated by \r\n (no trailing separator). Usually you will return all the server configuration information.

notifier (optional)

If this callback is not NULL it is called whenever there is some time left. It gets the server instance itself as argument. Actually it gets called every second.

handle request (mandatory for UDP and ICMP servers)

The arguments to this callback are the client’s socket structure, the address of the packet data and its length. When implementing a UDP or ICMP server you need to return non-zero if your server could process the packet. Thus it is possible that there are multiple UDP servers on a single port.

3.2.3.6 Make your server available

You distribute your server by editing the cfgfile.c file in the src/ directory. There you have to include the servers header file and add the server definition by calling svz_servertype_add

3.2.3.7 More detailed description of the callback system and structures

The client connection information is stored within the svz_socket_t object. All of the client connection specific callbacks get this object as first argument. Following is a description of the most important elements of this object.

int id

The socket id is a unique id for a client connection.

int version

This item validates this socket structure. If you pass the id and version to a coserver you can check if the delivered socket structure is the original or not within the coserver callback.

int proto

The proto flag determines a server sockets protocol type which can be PROTO_PIPE, PROTO_TCP, PROTO_UDP, PROTO_ICMP or PROTO_RAW.

int flags

The flag field of the client connection contains informations about the state of this connection. See socket.h in the src/libserveez/ directory for more information. Basically this bitfield specifies how this object is handled by the main server loop.

int userflags

This bitfield could be used for protocol specific information. You can use it for any information.

char *boundary, int boundary_size

If you are going to write a packet oriented protocol server you can use the svz_sock_check_request method to parse packets. These two properties describe the packet delimiter.

char *send_buffer, int send_buffer_size, int send_buffer_fill

This is the outgoing data for a client connection object.

char *recv_buffer, int recv_buffer_size, int recv_buffer_fill

Within the receive buffer all incoming data for a connection object is stored. This buffer is at least used for the client detection callback.

int read_socket (svz_socket_t)

This callback gets called whenever data is available on the socket. Normally, this is set to a default function which reads all available data from the socket and feeds it to check_request, but specific sockets may need other policies.

int write_socket (svz_socket_t)

This routine is called when data is is valid in the output buffer and the socket gets available for writing. You normally leave this callback untouched. It simply writes as much data as possible to the socket and removes the data from the send buffer.

int disconnected_socket (svz_socket_t)

This gets called whenever the socket is lost for some external reason.

int connected_socket (svz_socket_t)

If some piece of code tries to connect to another host via svz_tcp_connect this connection might be established some time later. This callback gets called when the socket is finally connected.

int kicked_socket (svz_socket_t, int)

We call this whenever the socket gets closed by us. The second argument specifies a reason.

int check_request (svz_socket_t)

This gets called whenever data was read from the socket. Its purpose is to check whether a complete request was read, and if it was, it should be handled and removed from the input buffer.

int handle_request (svz_socket_t, char *, int)

This gets called when the check_request got a valid packet. The request arguments contains the actual packet and the second argument is the length of this packet including the packet delimiter.

int idle_func (svz_socket_t)

This callback gets called from the periodic task scheduler. Whenever idle_counter (see below) is non-zero, it is decremented and idle_func gets called when it drops to zero. idle_func can reset idle_counter to some value and thus can re-schedule itself for a later task.

int idle_counter

Counter for calls to idle_func.

void *data

Miscellaneous field. Listener keeps array of server instances here. This array is NULL terminated. Some servers store server specific information here.

void *cfg

When the final protocol detection has been done cfg should contain a pointer to the actual configuration hash map taken from the server instance object.

3.2.3.8 Using coservers

Coservers are designed to complete blocking tasks. Each coserver runs in its own thread/process. There are several coservers implemented: the dns, reverse dns and ident coserver. You need to implement the callback which gets called when a coserver completed its task. This routine must be a svz_coserver_handle_result_t. The first argument is the actual coserver result which might be NULL if the request could not be fulfilled and the latter two arguments are the arguments you specified yourself when issuing the request. To invoke a coserver you use one of the svz_coserver_* macros. The foo server uses the reverse dns coserver to identify the host name of the remote client.

3.4.1.1 General description

The integrated HTTP server was originally meant to be a simple but fast document server. But now it can even execute CGI scripts. The GET, HEAD and POST methods are fully functional. Additionally Serveez produces directory listings when no standard document file (e.g., index.html) has been found at the requested document node (directory). Furthermore it implements a file cache for speeding up repetitive HTTP request.

In comparison to other web server projects like Apache and Roxen this web server is really fast. Comparative benchmarks will follow. The benchmark system is a 233 MHz Mobile Pentium MMX. Both the server and the client (http_load - multiprocessing http test client) ran on the same computer.

Small files

The small-file test load consists of 1000 files, each 1KB long, requested randomly.

concurrent fetches   1   10   50  100  200  500  1000
hits/second        501  520  481  475  420  390   295

CGI

The CGI test load consists of a trivial “hello world” C program. I noticed GNU/Linux (2.2.17 in this case, probably others too) to throw “Resource temporarily unavailable” errors when forking very fast. This limits the test to about 200 concurrent fetches on the test system.

Large files

The large-file test load consists of 100 files, each 1MB long, requested randomly. Also, each connection is throttled to simulate a 33.6Kbps modem. Note that 1000 33.6Kbps connections is 3/4 of a T3. There was no problem to get 1000+ concurrent fetches.

3.4.1.2 Configuration

The following options can be set from the configuration file.

indexfile (string, default: index.html)

The indexfile parameter is the default file served by the HTTP server when the user does not specify a file but a document node (e.g., http://www.lkcc.org/).

docs (string, default: ../show)

The docs parameter is the document root where the server finds its web documents.

userdir (string, default: public_html)

Each ‘~user’ request gets converted into the given users home directory. The string will be appended to this directory. Its default value is ‘public_html’.

cgi-url (string, default: /cgi-bin)

This parameter is the first part of the URL the HTTP server identifies a CGI request. For instance if you specify here /cgi-bin and the user requests http://www.lkcc.org/cgi-bin/test.pl then the HTTP server tries to execute the program test.pl within the cgi-dir (see below) and pipes its output to the user.

cgi-dir (string, default: ./cgibin)

The cgi-dir is the CGI document root (on the server).

cgi-application (hash, default: empty)

Within the MinGW32 port you can use this hash to associate certain file suffices with applications on your computer (e.g., pl with perl). This is necessary because there is no possibility to check whether a file is executable on Win32.

cache-size (integer, default: 200 kb)

This specifies the size of the document cache in bytes for each cache entry.

cache-entries (integer, default: 64)

This parameter specifies the maximum number of HTTP file cache entries (files). When you instantiate more than one HTTP server the biggest value wins. The HTTP file cache is shared by all HTTP servers.
Please note: If your harddrive/filesystem combination proves to be faster than the HTTP file cache you should disable it by setting both cache-size and cache-entries to zero.

timeout (integer, default: 15)

The timeout value is the amount of time in seconds after which a keep-alive connection (this is a HTTP/1.1 feature) will be closed when it has been idle.

keepalive (integer, default: 10)

On one keep-alive connection can be served the number of keepalive documents at all. Then the connection will be closed. Both this and the timeout value are just to be on the safe side. They protect against idle and high traffic connections.

default-type (string, default: text/plain)

The default-type is the default content type the HTTP server assumes if it can not identify a served file by the types hash and the type-file (see below).

type-file (string, default: /etc/mime.types)

This should be a file like the /etc/mime.types on Unix systems. It associates file suffices with MIME types.

types (hash, default: empty)

If you want to specify special content types do it here. This parameter is a hash map associating file suffices with HTTP content types (MIME types).

admin (string, default: root@localhost)

Your address, where problems with the server should be e-mailed. This address appears on some server-generated pages, such as error documents.

host (string, default: localhost)

This is the host name of your web server. Sometimes the server has to send back its own name to the client. It will use this value. Be aware that you cannot invent such a name.

nslookup (boolean, default: false)

If this is true the HTTP server invokes a reverse DNS lookup for each client connection in order to replace the remote ip address with the remote host name in the access logfile.

ident (boolean, default: false)

If this is true the HTTP server processes identd requests for each client connection for logging purposes.

logfile (string, default: http-access.log)

The location of the access logfile. For each HTTP request a line gets appended to this file.

logformat (string, default: CLF)

The format of the access logfile. There are special placeholders for different kinds of logging information. The default log format is the Common Log Format (CLF). It contains a separate line for each request. A line is composed of several tokens separated by spaces.

CLF = host ident authuser date request status bytes

If a token does not have a value then it is represented by a hyphen (-). The meanings and values of these tokens are as follows:

%h (host)

The fully-qualified domain name of the client, or its IP number if the name is not available.

%i (ident)

This is the identity information reported by the client. Not active, so we will see a hyphen (-).

%u (authuser)

If the request was for an password protected document, then this is the userid used in the request.

%t (date)

The date and time of the request, in the following format:

date   = [day/month/year:hour:minute:second zone]
day    = 2*digit
month  = 3*letter
year   = 4*digit
hour   = 2*digit
minute = 2*digit
second = 2*digit
zone   = (`+' | `-') 4*digit

%R (request)

The request line from the client, enclosed in double quotes (").

%r (referrer)

Which document referred to this document.

%a (agent)

What kind of web browser did the remote client use.

%c (status)

The three digit status code returned to the client.

%l (bytes)

The number of bytes in the object returned to the client, not including any headers.

3.4.2.1 General description

Internet Relay Chat. The mother of all chat systems. The integrated IRC server is intended to be compatible with the EFNet. There are no good possibilities to test this in real life, so it is still under heavy construction. But it can be used as a standalone server anyway.

IRC itself is a teleconferencing system, which (through the use of the client-server model) is well-suited for running on many machines in a distributed fashion. A typical setup involves a single process (the server) forming a central point for clients (or other servers) to connect to, performing the required message delivery/multiplexing and other functions.

The server forms the backbone of IRC, providing a point for clients and servers to connect to. Clients connect to talk to each other. Servers connect to build up a network of servers. IRC server connections have to build up a spanning tree. Loops are not allowed. Each server acts as a central node for the rest of the network it sees.

3.4.2.2 Configuration

The following table shows the configuration keys provided. Most of the configuration items are similar to those of an Hybrid IRC server. They seem archaic at first sight but IRC operators are used to it. Refer to the Hybrid documentation for further information. It can be found on the EFNet web page.

MOTD-file (string, default: ../data/irc-MOTD.txt)

When a user initially joins it will get this file’s content as the message of the day comment. When changing on disk the server will notice that and reload the file automatically.

INFO-file (string, default: no file)

The INFO-files content gets displayed when the user issues the /INFO command.

tsdelta (integer, default: 0)

This value is the timestamp delta value to UTC (Coordinated Universal Time) in seconds.

channels-per-user (integer, default: 10)

Configures the maximum number of channels a single local user can join.

admininfo (string, no default)

Some administrative information delivered on the /ADMIN command.

M-line (string, no default, mandatory)

The TCP level configuration of this IRC server. The server info field is sometimes given to the client for informational use. The server will croak about if the settings do not correspond with the actual bindings. The format of this line is:

":" virtual hostname
":" optional bind address (real hostname)
":" server info: "World's best IRC server"
":" port

A-line (string, no default, mandatory)

The administrative info, printed by the /ADMIN command.

":" administrative info (department, university)
":" the server's geographical location
":" email address for a person responsible for the IRC server

Y-lines (string array, no default, suggested)

The connection classes. They are used in other parameters (e.g., I-lines). A Y-line describes a group of connections. You usually have at least two Y-lines: One for server connections and one for client connections. Format of each line is:

":" class number (higher numbers refer to a higher priority)
":" ping frequency (in seconds)
":" connect frequency in seconds for servers, 0 for
    client classes
":" maximum number of links in this class
":" send queue size

I-lines (string array, no default, mandatory)

Authorization of clients, wildcards permitted, a valid client is matched user@ip OR user@host.

":" user@ip, you can specify ‘NOMATCH’ here to force
    matching user@host
":" password (optional)
":" user@host
":" password (optional)
":" connection class number (YLine)

O-lines (string array, no default, optional)

Authorize operator, wildcards allowed.

":" user@host, user@ forces checking ident
":" password
":" nick

o-lines (string array, no default, optional)

Authorize local operator.

":" user@host, user@ forces checking ident
":" password
":" nick

C-lines (string array, no default, networked)

List of servers to connect to. Note: C and N lines can also use the user@ combination in order to check specific users (ident) starting servers. C and N lines are usually given in pairs.

":" host name
":" password
":" server name (virtual)
":" port (if not given we will not connect)
":" connection class number (YLine)

N-lines (string array, no default, networked)

Servers which may connect.

":" host name
":" password
":" server name (virtual host name)
":" password
":" how many components of your own server's name to strip
    off the front and be replaced with a ‘*’.
":" connection class number (YLine)

K-lines (string array, no default, optional)

Kill user, wildcards allowed.

":" host
":" time of day
":" user

3.4.3.1 General description

Serveez implements something like a telnet protocol for administrative purposes. You just need to start a telnet session like:

$ telnet www.lkcc.org 42420

After pressing RET you will be asked for a password which you might setup passing Serveez the -P argument. See Using Serveez. The next section describes the interactive commands available.

3.4.3.2 Using the Control Protocol

‘help’

This command will give you a very short help screen of all available commands.

‘quit’

This command closes the connection to Serveez.

‘restart ident’

Restarts the internal ident coserver. This is useful if you just want to start a new one if the old one died or is otherwise unusable.

‘restart dns’

Restarts the internal dns lookup server.

‘restart reverse dns’

Restarts the internal reverse dns lookup server.

‘killall’

This might be useful if Serveez seems to be unstable but you do not want to restart it. With ‘killall’ you disconnect all client network connections except the control protocol connections.

‘kill id NUM’

Disconnects a specific connection identified by its ID. These IDs will be stated when you type ‘stat con’ (see below).

‘stat’

General statistics about Serveez. This will show you some useful information about the computer Serveez is running on and about the state of Serveez in general.

‘stat coserver’

Statistics about all running coserver instances.

‘stat SERVER’

This command is for selecting certain server instances to be listed. SERVER is one of server names you specified in the configuration file.

‘stat id NUM’

Show statistics about a specific connection. This will give you all available information about every connection you specified. See Writing servers, for more information about how to provide these information.

‘stat con’

Connection statistics. This will give a list of all socket structures within Serveez. If you want more detailed information about specific connections, coservers or servers you need to request these information with ‘stat id NUM’ or ‘stat all’.

‘stat all’

Server and coserver instance statistics. This command lists all the information about instantiated servers and coservers. See Writing servers, for more information about how to provide these information.

‘stat cache’

HTTP cache statistics. This command produces an output something like the following where ‘File’ is the short name of the cache entry, ‘Size’ the cache size, ‘Usage’ the amount of connections currently using this entry, ‘Hits’ the amount of cache hits, ‘Recent’ the cache strategy flag (newer entries have larger numbers) and ‘Ready’ is the current state of the cache entry.

File                      Size  Usage  Hits Recent Ready
zlib-1.1.3-20000531.zip  45393      0     0      1 Yes
texinfo.tex             200531      0     0      2 Yes
shayne.txt                2534      0     1      1 Yes

Total : 248458 byte in 3 cache entries

‘kill cache’

Reinitialize the HTTP file cache. Flushes all files from the cache.

3.4.3.3 Configuration

There is nothing to be configured yet.

3.4.4.1 General description

The Foo Server is a simple example on how to write Internet protocol servers with Serveez. See Writing servers.

3.4.4.2 Configuration

There are all kinds of configuration items. They are used to explain the implementation of servers. A complete list will follow.

port (port configuration, default: tcp, 42421, *)

Sets up the TCP port and local address.

bar (integer, no default)

Some integer value. Printed as server information.

reply (string, default: Default reply)

Some string. Printed as server information.

messages (string array, default: ...)

Some string array which is actually a list of strings. Also printed as server information.

ports (integer array, default: 1, 2, 3, 4)

Some array of integer numbers. Printed as server information.

assoc (hash, default, default: ...)

An hash map associating keys with values. Printed as server information.

truth (boolean, default: true)

Some boolean value. Printed as server information.

3.4.5.1 General

The SNTP server can be queried with the ‘netdate’ command. It is used to synchronize time and dates between Internet hosts. The protocol is described in the ARPA Internet RFC 868. Thus it is not really an SNTP server as described by RFC 2030 (Simple Network Time Protocol (SNTP) Version 4 for IPv4, IPv6 and OSI). It is rather an excellent example on how to implement a UDP server in Serveez.

This protocol provides a site-independent, machine readable date and time. The Time service sends back time in seconds since midnight on January first 1900.

One motivation arises from the fact that not all systems have a date/time clock, and all are subject to occasional human or machine error. The use of time-servers makes it possible to quickly confirm or correct a system’s idea of the time, by making a brief poll of several independent sites on the network.

3.4.5.2 Configuration

The configuration of this server does not require any item.

3.4.6.1 What is it ?

The Gnutella net is a peer-to-peer network which is based on client programs only. There are no servers. The network itself is formed by client connections only. Generally the Gnutella network is for sharing files of any kind.

This Gnutella spider is for seeking the needle in the haystack. Once connected to the network it regularly tries to find certain files in there. It keeps track of all connected clients and tries to reconnect them if the current connections are lost.

Gnutella, however has nothing to do with the GNU project. The original client is just a free (as in free beer) piece of software. With Serveez you have a free (as in freedom) way to use it. Have a look at the Gnutella page for further information.

3.4.6.2 Configuration

The Gnutella spider knows the following configurations items.

net-url (string, default: gnutella-net)

If you want to see the host catcher list of this Gnutella spider you can connect to this port with any WWW browser at http://host:port/net-url. The host:port combinations depend on the bindings.

hosts (string array, no default)

This is the start of the haystack, the initial host list of the clients the spider tries to connect to. Each list item should be of the format ip:port (e.g., ‘146.145.85.34:6346’). You can also pass Internet host names. If the port information is left blank it defaults to 6346. If you need some entry point for the Gnutella network have a look at http://www.gnutellahosts.com/ or http://www.gnutellanet.com/.

search (string array, default: Puppe3000, Meret Becker)

This is the needle. Each search line is either a set of space delimited tokens where every token must match. Or a kind of wildcard expression including ‘?’ and ‘*’. Search lines are always matched case insensitive.

search-limit (integer, default: 30)

This limits how many results the Gnutella spider returns to other people searching your files. This is for protection against * search requests.

max-ttl (integer, default: 5)

Every Gnutella packet has got a TTL. This is the maximum TTL allowed for outgoing packets. When a packet comes in it gets its TTL value decremented and is forwarded to it destination. If however an incoming packet has a TTL larger than max-ttl the ttl value is set to max-ttl. This is necessary since most people use far too large TTL values.

ttl (integer, default: 5)

When creating a new Gnutella packet we use this as TTL. Please use a sane value. This ttl needs not to be as large as it is for IP packets. A value below 10 is more than enough. Have a look at the Gnutella page for a calculation of a ’sane value’.

download-path (string, default: /tmp)

This is where the spider saves needles in.

share-path (string, default: /tmp)

Here are all the files we share with others. The Gnutella spider will recurse into directories. So be careful with this option.

max-downloads (integer, default: 4)

Maximum number of concurrent downloads from the network.

max-uploads (integer, default: 4)

Maximum number of concurrent uploads to the network.

connection-speed (integer, default: 28)

This is what we send as our connection speed in KBit/s. We also use this value to throttle down the network transfer rate for file uploads.

min-speed (integer, default: 28)

Search for needles on hosts with a minimum speed. Set it to 0 if you do not care about that. This value is in KBit/s, too.

file-extensions (string array, default: empty list)

If we get replies on search queries we check if the file extension of this reply matches one of these extensions. Useful extensions are ‘mp3’ and ‘mpg’.

connections (integer, default: 4)

This is the number of concurrent connections the Gnutella spider tries to keep up to the network. The IP addresses and the port information is taken from the host catcher hash.

force-ip (string, default: not set)

You can force the Gnutella spider to send outgoing replies with this IP as host information. Must be in dotted decimals notation. This is useful if you are behind a masquerading gateway. You need to install some kind of port forwarder on the gateway so other people can reach you from the outside. Serveez is a good port forwarder.

force-port (integer, default: not set)

Force the Gnutella spider to send outgoing replies with the force-port as port information. See above for more information.

disable (boolean, default: false)

With this configuration option you can disable the bindings for a Gnutella server instance. This means that no remote client can connect without being told so (e.g., by push requests).

3.4.7.1 General description

The Tunnel server is for mapping one port configuration to another. So we should rather speak of a port forwarder. Two port forwarders can form a tunnel. Generally this means that you can setup Serveez to accept network or pipe connections in order to pass all transfer data on this line to another port configuration. This can be useful to work around gateways and firewalls. When instantiating an ICMP source or destination you must ensure root privileges for the application. On Windows NT and Windows 2000 you need to be either logged in as Administrator or have set the registry key HKLM\System\CurrentControlSet\Services\Afd\Parameters\DisableRawSecurity to 1 (DWORD). One of the given examples in serveez.cfg shows how you can setup a tunnel server for forwarding a pipe connection. Please keep in mind when forwarding a TCP or pipe connection over ICMP or UDP you loose reliability since the latter two are packet oriented rather than connection oriented. We are not willing to implement our own TCP stack to work on ICMP/UDP directly.

Forwarding between the same types of connection is always possible. When forwarding to an ICMP tunnel we use a special protocol which we will outline in the following section.

3.4.7.2 Extended ICMP protocol specification

Since ICMP (Internet Control Message Protocol) does have a fixed packet format we had to extend it in order to use it for our own purposes. The protocol field of the IP header contains a binary ‘1’ which is the identifier for ICMP (e.g., ‘6’ identifies TCP). When creating an ICMP socket the IP header is always generated by the kernel. This is the main difference to raw sockets where the IP header must be generated at userspace level.

When receiving an ICMP packet it also contains the IP header. When sending an ICMP packet you must not prepend this IP header. The kernel will do this itself. The IP header always follows the actual ICMP header followed by the ICMP packet data. Since this section does not cover raw sockets we leave the IP header structure out here.

The modified ICMP message format is as:

Each of these fields can be modified and processed by Serveez and do not get touched by the kernel at all. The ICMP socket implementation of Serveez differentiates two types of sockets: listening and connected ICMP sockets. This is non-standard because it actually makes no sense since there is no difference for the kernel. The introduction of these semantics allow Serveez to forward data between connection-oriented (TCP and named pipes) and packet-oriented (UDP and ICMP) protocols.

Message type

Valid message types are for instance ‘8’ for an echo message and ‘0’ for its echo reply. These two messages are used for the systems builtin ping services. Serveez uses its own message type identifier which is ‘42’ (ICMP_SERVEEZ) by default.

Message type sub code

Serveez also defines its own message type sub codes described in the following table.

Sub code	Constant identifier	Description
0	ICMP_SERVEEZ_DATA	packet contains data
1	ICMP_SERVEEZ_REQ	unused
2	ICMP_SERVEEZ_ACK	unused
3	ICMP_SERVEEZ_CLOSE	disconnection message
4	ICMP_SERVEEZ_CONNECT	connect message

Checksum

The checksum field of the ICMP header is used to check the ICMP headers and the payloads (packet data) validity. We are using the standard Internet Checksum algorithm described in RFC 1071. If the check failed we drop the packet.

Senders unique identifier

The senders identifier field is used to determine if a received packet has been sent by the sender itself and should therefore be dropped. This happens because each ICMP socket setup for receiving gets all sent ICMP packets system wide. Thus Serveez will even be notified if the kernel creates some echo reply or destination unreachable message due to a request completely outside the scope of Serveez.

Sequence number

Each connected ICMP socket increments its sequence number when sending a packet. Thus a connection message type packet of such a socket always has a zero sequence number. This field could (but is not yet) also be used to reorder ICMP packets or to detect missing packets.

Port number

The port field of the modified packet format helps Serveez to establish connected ICMP sockets. A simple packet filter detects if a received packet is kind of reply to a sockets sent packets by comparing this port number. The packet is dropped if the comparison fails and it is not a listening socket.

Except the data message type subcode all ICMP packets created and sent by Serveez have a zero payload. The connect message subcode identifies a new connection and the disconnection message subcode its shutdown without actually transmitting data. These two subcodes emulate a TCP connections connect, accept and shutdown system call.

3.4.7.3 Configuration

This might be the most easiest configuration to setup. You essentially need to define the source port configuration and the target port configuration. The serveez.cfg in the data/ directory shows two example configurations how to tunnel TCP connections over UDP and ICMP. The UDP tunnel accesses the standard HTTP port 80 and the ICMP tunnel accesses the standard Telnet port 23.

source (port configuration, no default)

The source port configuration. This is usually the same you bind the server to.

target (port configuration, no default)

The target port configuration.

3.4.8.1 General description

Most systems run the ’ident protocol’ on port 113. Internet hosts can connect to that port and find out what user is having a connection to the host. For example a webserver can query your username when you fetch a file (e.g., Serveez’ internal ident-coserver can do that). Most IRC servers protect themselves by allowing only users that have a valid ident response. Therefore mIRC (for windoze) has a built in ident server. This fake ident server can be used to ’fake’ a response. This is useful when you connect through a masquerading gateway and the gateway cannot handle ident requests correctly. (Or, of course, you are using windoze, need an ident response and do not have mIRC at hand.)

This server has two modes of operation. In one mode all requests get ‘ERROR : NO-USER’ as response. This is a valid but not very helpful response. The other mode makes the server send a valid and useful response. It contains a system type and a username. The system type is usually ’UNIX’. Others are valid but never used (at least i have never seen something else).

3.4.8.2 Configuration

This server is easy to configure.

systemtype (string, default: UNIX)

The system type to respond. The username field of the response has other meanings depending on this field, so do not make things up here. Read the RFC to learn more.

username (string, default: <NULL>)

If no username is set (which means this field does not appear in the configuration file) the server runs in the flag-all-requests-as-error mode. Use your favourite nickname here.

3.4.9.1 General description

The program passthrough server provides basic inetd functionality. Basically it can accept connections and pass this connection to the standard input (stdin) and standard output (stdout) handles of programs. Depending on the platform (operating system) the user is able to configure different methods how this can be achieved.

3.4.9.2 Configuration

This server has different types of configuration options specifying its behaviour. Some of them are mandatory and some are optional. The very least to configure is the program to be started when a new connection is made.

binary (string, no default)

This parameter specifies the program to execute when a new connection has been accepted. The parameter is mandatory and must be a fully qualified file name (including path).

directory (string, no default)

This will be the working directory of the executed program. If you omit this parameter the server uses the current directory (the directory is not changed).

user (string, no default)

If you omit this parameter no user or group will be set for the started program. Otherwise you need to specify this information in the format ‘user[.group]’. If the group is omitted the user’s primary group will be used.

argv (string array, no default)

This list of character strings is going to be the program’s argument list (command line). If the first list item (which is argv[0] and the program’s name) is left blank it defaults to the name specified in the binary parameter.

do-fork (boolean, default: true)

This flag specifies the method used to pass the connection to the program. If it is true the server uses the Unix’ish fork and exec method. Otherwise it will pass the data through a unnamed pair of sockets [ or two pairs of anonymous pipes ].

single-threaded (boolean, default: true)

This parameter applies to servers bound to UDP and ICMP port configurations only. For programs which process all incoming packets and eventually time out, the program is said to be ‘single-threaded’ and should use a true value here. If a program gets a packet and can receive further packets, it is said to be a ‘multi-threaded’ program, and should use a false value.

thread-frequency (integer, default: 40)

The optional thread-frequency parameter specifies the maximum number of program instances that may be spawned from the server within an interval of 60 seconds.

3.4.10.1 General description

The distributed Mandelbrot server is an Internet server completely written in Guile with the help of the API provided by the underlying Serveez application. The reader will not see any occurrence of the networking API of Guile.

It implements a protocol called ‘dnc’. ‘dnc’ - short for “Distributed Number Cruncher”. The Mandelbrot server manages the computation of a graphic visualization of the Mandelbrot set fractal. Each client can connect to the server and ask for something to calculate and is meant to send its result back to the server. Finally the server produces a bitmap in the XPM format and uses a specified viewer application to bring it onto your screen.

3.4.10.2 Configuration

The server can be setup to manage the calculation of the Mandelbrot set at various locations (rectangular region in the complex plane), in a specific pixel resolution and colour depth. Moreover you can define the name of the final output file and the viewer application the output file is displayed with.

start (string, default: -2.0-1.5i)

Specifies the upper left corner of the final bitmap in the complex plane.

end (string, default: +1.1+1.5i)

Specifies the lower right corner of the final bitmap in the complex plane.

x-res (integer, default: 320)

The real part pixel resolution.

y-res (integer, default: 240)

The imaginary part pixel resolution.

colors (integer, default: 256)

Number of maximum colours used in the bitmap. Also determines the maximum iteration depth.

outfile (string, default: mandel.xpm)

When the Mandel server has managed to calculate the whole bitmap it produces an output file in the XPM format. You can specify the name and location of this output file.

viewer (string, default: xv)

Here you can setup your favourite bitmap viewer application. It should be able to parse and display the XPM format.

5.2.3.1 Array

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

Function: svz_array_t * svz_array_create (size_t capacity, svz_free_func_t destroy) ¶

Create a new array with the initial capacity capacity and return a pointer to it. If capacity is zero it defaults to some value. If destroy is non-NULL, svz_array_destroy calls that function (typically used to free dynamically allocated memory). For example, if the array contains data allocated by svz_malloc, destroy should be specified as svz_free. If the array contains data which should not be released, destroy should be NULL.

Function: void svz_array_destroy (svz_array_t *array) ¶

Completely destroy the array array. The array handle is invalid afterwards. The routine runs the destroy callback for each element of the array.

Function: void * svz_array_get (svz_array_t *array, size_t index) ¶

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, size_t index, void *value) ¶

Replace the array element at the position index of the array array with the value value and return the previous value at this index. Return NULL and do nothing if array is NULL or the index is out of the array range.

Function: void svz_array_add (svz_array_t *array, void *value) ¶

Append the value value at the end of the array array. Do nothing if array is NULL.

Function: void * svz_array_del (svz_array_t *array, size_t index) ¶

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 array’s range.

Function: size_t svz_array_size (svz_array_t *array) ¶

Return the current size of array.

Macro: svz_array_foreach (array, value, i) ¶

Expand into a for-statement header, for iterating over array. On each cycle, value is assigned to successive elements of array, and i the element’s position.

5.2.3.2 Hashtable

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 (size_t size, svz_free_func_t destroy) ¶

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 specifies an element destruction callback for use by svz_hash_clear and svz_hash_destroy for each value. If no such operation should be performed the argument must be NULL.

Function: svz_hash_t * svz_hash_configure (svz_hash_t *hash, size_t (* keylen) (const char *) , unsigned long (* code) (const char *) , int (* equals) (const char *, const char *) ¶

Set the internal keylen, code and and equals functions for hash table hash. Return hash.

keylen takes const char *data and returns size_t, the number of bytes in data representing the key.

code takes const char *data and returns unsigned long.

equals takes const char *data1, const char *data2 and returns int, which should be non-zero if equal.

As a special case, a NULL value means don’t set that function, leaving it to its default value.

Function: void svz_hash_destroy (svz_hash_t *hash) ¶

Destroy the existing hash table hash, svz_freeing all keys within the hash, the hash table and the hash itself. If a non-NULL element destruction callback was specified to svz_hash_create, that function is called on each value.

Function: void * svz_hash_delete (svz_hash_t *hash, const char *key) ¶

Delete an existing entry accessed via a key from the hash table hash. Return NULL if there is no such key, otherwise the previous value.

Function: void * svz_hash_put (svz_hash_t *hash, const char *key, void *value) ¶

Add a new element consisting of key and value to hash. When key already exists, replace and return the old value. Note: This is sometimes the source of memory leaks.

Function: void * svz_hash_get (const svz_hash_t *hash, const char *key) ¶

Return the value associated with key in the hash table hash, or NULL if there is no such key.

Function: void svz_hash_foreach (svz_hash_do_t *func, svz_hash_t *hash, void *closure) ¶

Iterate func over each key/value pair in hash. func is called with three void * args: the key, the value and the opaque (to svz_hash_foreach) closure.

Function: size_t svz_hash_size (const svz_hash_t *hash) ¶

Return the number of keys in the hash table hash. If hash is NULL, return zero.

Function: char * svz_hash_contains (const svz_hash_t *hash, void *value) ¶

Return the key associated with value in the hash table hash, or NULL if there is no such value.

Function: int svz_hash_exists (const svz_hash_t *hash, char *key) ¶

Return non-zero if key is stored within the hash table hash, otherwise 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.

5.2.7.1 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 (svz_address_t *host, in_port_t port) ¶

Create a TCP connection to host host and set the socket descriptor in structure sock to the resulting socket. Return NULL on errors.

Function: int svz_tcp_read_socket (svz_socket_t *sock) ¶

Read all data from sock and call the check_request function for the socket, if set. Return -1 if the socket has died, zero otherwise.

This is the default function for reading from sock.

Function: int svz_tcp_send_oob (svz_socket_t *sock) ¶

If the underlying operating system supports urgent data (out-of-band) in TCP streams, try to send the byte in sock->oob through the socket structure sock as out-of-band data. Return zero on success and -1 otherwise (also if urgent data is not supported).

5.2.7.2 Pipe connections

The pipe implementation 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: svz_socket_t * svz_pipe_create (svz_t_handle recv_fd, svz_t_handle send_fd) ¶

Create a socket structure containing both the pipe descriptors recv_fd and send_fd. Return NULL on errors.

Function: int svz_pipe_create_pair (svz_t_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 *send) ¶

Create a pipe connection socket structure to the pair of named pipes recv and send. Return NULL on errors.

Function: int svz_invalid_handle_p (svz_t_handle handle) ¶

Return 1 if handle is invalid, otherwise 0.

Function: void svz_invalidate_handle (svz_t_handle *href) ¶

Invalidate the handle pointed at by href.

Function: int svz_closehandle (svz_t_handle handle) ¶

Close handle. Return 0 if successful, -1 otherwise.

5.2.7.3 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: svz_socket_t * svz_udp_connect (svz_address_t *host, in_port_t port) ¶

Create a UDP connection to host at port 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 of 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 length) ¶

Write buf into the send queue of the UDP socket sock. If length argument supersedes the maximum length for UDP messages it is split into smaller packets.

5.2.7.4 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: svz_socket_t * svz_icmp_connect (svz_address_t *host, in_port_t port, uint8_t type) ¶

Create 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, uint8_t type) ¶

“If you are calling this function we will send an empty ICMP packet signaling that this connection is going down soon.” [ttn sez: huh?]

Function: int svz_icmp_write (svz_socket_t *sock, char *buf, int length) ¶

Send buf with length length via this ICMP socket sock. If length supersedes the maximum ICMP message size the buffer is split into smaller packets.

5.2.7.5 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 zero (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.

[FIXME: All funcs internalized! Write something else here!]

5.2.7.6 Passthrough connections

The functions described in this section allow you to pass through client connections to the standard input (stdin) and standard output (stdout) of external programs. Some of the routines deal with the management of program environments. Basically, there are two methods for passing through 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 forkp, char *user) ¶

Start a new program bin, a fully qualified executable filename, passing the socket or pipe descriptor(s) in the socket structure sock to its stdin and stdout.

If dir is non-NULL, it specifies the working directory of the new process.

The program arguments and the environment of the new process are taken from argv and envp. Normally argv[0] should be set to the program’s name. If NULL, it defaults to bin.

The forkp argument is a flag that controls the passthrough method. If non-zero, pipe descriptors or the socket descriptor are passed to the child process directly through fork and exec. Otherwise, socket transactions are passed via a pair or pipes or sockets (depending on whether or not the system provides socketpair).

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.

Return the new process id on success, -1 on failure.

Please note: On M$-Windows platforms it is not possible to pass a socket connection to stdin/stdout of a child process. 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 they were self-created. After calling WSAStartup the child process can send and recv as usual.

Relatedly, Windoze does not use SIGCHLD to inform the parent when a child dies, so for that platform, you should use the next function (which is not otherwise available):

Function: int svz_mingw_child_dead_p (char *prefix, svz_t_handle *pid) ¶

Check child pointed at by pid by waiting a bit. If it is dead, close and invalidate its handle, and return 1. Otherwise, return 0. prefix is for error messages; it should be either the empty string, or a string ending in colon and space.

On non-Windoze, this is the function you want to use:

Function: int svz_most_recent_dead_child_p (svz_t_handle pid) ¶

Return 1 if a child process pid died recently, updating other internal state by side effect. Otherwise, return 0.

Function: void svz_envblock_setup (void) ¶

Set up internal tables for environment block wrangling.

This function must be called once after svz_boot so that subsequent functions (like svz_envblock_default) can work correctly.

Function: svz_envblock_t * svz_envblock_create (void) ¶

Create and return a fresh environment block, useful for passing to svz_envblock_default and svz_envblock_add. Its size is initially set to zero.

Function: int svz_envblock_default (svz_envblock_t *env) ¶

Fill environment block env with the environment variables from the current process, replacing its current contents (if any).

Function: int svz_envblock_add (svz_envblock_t *env, char *format, …) ¶

Insert a new environment variable into 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: void svz_envblock_destroy (svz_envblock_t *env) ¶

Destroy environment block env completely. Afterwards, env is invalid and should therefore not be further referenced.

Function: void * svz_envblock_get (svz_envblock_t *env) ¶

Convert environment block env into something which can be passed to execve (Unix) or CreateProcess (Windows). Additionally, under Windows, sort the environment block.

(Unfortunately the layout of environment blocks in Unices and Windows differ. On Unices you have a NULL terminated array of character strings (i.e., char **) 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 (i.e., char *). The end of the list is indicated by a further zero byte.)

5.2.11.1 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. These macros can be used to define such 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 () ¶

Indicate 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_CONFIG_DEFINE (description, config, prototypes) ¶

Expand to a data structure that properly associates the example configuration config with the name description and its configuration items prototypes, for use within a server type definition.

5.2.11.2 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.

Function: int svz_foreach_servertype (svz_servertype_do_t *func, void *closure) ¶

Call func for each servertype, passing additionally the second arg closure. If func returns a negative value, return immediately with that value (breaking out of the loop), otherwise, return 0.

Function: void svz_servertype_add (svz_servertype_t *server) ¶

Add the server type server to the currently registered servers.

Function: svz_servertype_t * svz_servertype_get (char *name, int dynamic) ¶

Find a servertype definition by its short name. If dynamic is set to non-zero, try to load a shared library that provides that servertype. Return NULL if no server with the given variable prefix name has been found.

Function: svz_servertype_t * svz_servertype_find (svz_server_t *server) ¶

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 a server type).

5.2.11.3 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 you notice misbehaviour of any sort.

Function: void svz_dynload_path_set (svz_array_t *paths) ¶

Set the additional search paths for the serveez library. The given array of strings gets svz_freed.

Function: svz_array_t * svz_dynload_path_get (void) ¶

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.

5.2.12.1 Server functionality

This 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.

Function: void svz_foreach_server (svz_server_do_t *func, void *closure) ¶

Call func for each server, passing additionally the second arg closure.

Function: svz_server_t * svz_server_find (void *cfg) ¶

Find a server instance by the given configuration structure cfg. Return NULL if there is no such configuration in any server instance.

Function: svz_array_t * svz_server_clients (svz_server_t *server) ¶

Return a list of clients (socket structures) which are associated with the given server instance server. If there is no such socket, return NULL. Caller should svz_array_destroy the returned array.

Function: svz_server_t * svz_server_get (char *name) ¶

Get the server instance with the given instance name name. Return NULL if there is no such server yet.

Function: int svz_updn_all_servers (int direction) ¶

If direction is non-zero, run the initializers of all servers, returning -1 if some server did not think it is a good idea to run. Otherwise, run the local finalizers for all server instances.

5.2.12.2 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: int svz_config_type_instantiate (char *type, char *name, char *instance, void *options, svz_config_accessor_t *accessor, size_t ebufsz, char *ebuf) ¶

Instantiate a configurable type. The type argument specifies the configurable type name, name the name of the type (in the domain of the configurable type) and instance the instance name of the type. Return zero on success, otherwise -1.

Function: void svz_config_free (svz_config_prototype_t *prototype, void *cfg) ¶

Release the configuration cfg of the given configuration prototype prototype. If cfg is NULL, do nothing.

Function: void * svz_collect (int type, size_t count, void *data) ¶

Create a collection of type, given the count items of data. Valid values of type are one of: SVZ_INTARRAY, SVZ_STRARRAY, SVZ_STRHASH. For a string hash, data should be alternating keys and values; the returned hash table will have count / 2 elements. The C type of data for an int array should be int[], and for string array or hash it should be char*[]. On error (either bad type or odd count for string hash), return NULL.

Here are some convenience macros for svz_collect:

Macro: SVZ_COLLECT_INTARRAY (cvar) ¶

Return an integer array svz_array_t * created from int cvar[].

Macro: SVZ_COLLECT_STRARRAY (cvar) ¶

Return a string array svz_array_t * created from char *cvar[].

Macro: SVZ_COLLECT_STRHASH (cvar) ¶

Return a string hash svz_hash_t * created from char *cvar[].

5.2.12.3 Bindings

The following functionality represents the relationship between port configurations as described in Port configurations 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 *port) ¶

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 ‘*’ (asterisk) since this gets expanded to the known list of interfaces.

Function: svz_array_t * svz_server_portcfgs (svz_server_t *server) ¶

Return an array of port configurations to which the server instance server is currently bound to, or NULL if there is no such binding. Caller should svz_array_destroy the returned array when done.

Function: svz_array_t * svz_server_listeners (svz_server_t *server) ¶

Return an array of listening socket structures to which the server instance server is currently bound to, or NULL if there is no such binding. Caller should svz_array_destroy the returned array when done.

Function: svz_array_t * svz_sock_servers (svz_socket_t *sock) ¶

Return the array of server instances bound to the listening sock, or NULL if there are no bindings. Caller should svz_array_destroy the returned array when done.

Function: int svz_binding_contains_server (svz_socket_t *sock, svz_server_t *server) ¶

Checks whether the server instance server is bound to the server socket structure sock. Return one if so, otherwise zero.

Function: size_t svz_pp_server_bindings (char *buf, size_t size, svz_server_t *server) ¶

Format a space-separated list of current port configuration bindings for server into buf, which has size bytes. The string is guaranteed to be nul-terminated. Return the length (at most size - 1) of the formatted string.

5.2.12.4 Server core

Variable: svz_t_handle svz_child_died ¶

Set to a non-zero value whenever the server receives a SIGCHLD signal.

Function: int svz_shutting_down_p (void) ¶

Return non-zero if the core is in the process of shutting down (typically as a result of a signal).

Function: int svz_foreach_socket (svz_socket_do_t *func, void *closure) ¶

Call func for each socket, passing additionally the second arg closure. If func returns a negative value, return immediately with that value (breaking out of the loop), otherwise, return 0.

Function: svz_socket_t * svz_sock_find (int id, int version) ¶

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 *sock) ¶

Mark socket sock as killed. That means that no further operations except disconnecting and freeing are allowed. All marked sockets will be deleted once the server loop is through.

Function: int svz_sock_enqueue (svz_socket_t *sock) ¶

Enqueue the socket sock into the list of sockets handled by the server loop.

Function: void svz_sock_setparent (svz_socket_t *child, svz_socket_t *parent) ¶

Set the child socket’s parent to 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 *child) ¶

Return the child socket’s 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 *referrer) ¶

Set the referring socket structure of sock to referrer. If referrer is NULL the reference will be invalidated.

This can be used to create some relationship between two socket structures.

Function: svz_socket_t * svz_sock_getreferrer (svz_socket_t *sock) ¶

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 *sock) ¶

Return the parent’s port configuration of sock, or NULL if the given socket has no parent, i.e. is a listener.

5.2.12.5 Server loop

This section 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 wait until the core library drops out of it. In the other mode, the caller tells the Serveez core library to scan (and process) its socket chain once and return immediately. Thus, caller is able to issue additional functionality in between each pass, useful if such functionality cannot be handled within the timers (notifiers) of servers and sockets.

Function: void svz_loop_pre (void) ¶

Initialize top-of-cycle state.

Call this function once before using svz_loop_one.

Function: void svz_loop_post (void) ¶

Clean up bottom-of-cycle state.

Call this function once after using svz_loop_one.

Function: void svz_loop (void) ¶

Loop, serving. In other words, handle all signals, incoming and outgoing connections and listening server sockets.

Function: void svz_loop_one (void) ¶

Handle all things once.

This function is called regularly by svz_loop.

5.2.12.6 Server sockets

This section deals with creating and handling listeners. These functions 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.

[FIXME: All funcs internalized! Write something else here!]

5.2.14.1 Runtime parameters

There are several runtime parameters indicating the abilities of the libserveez core API:

SVZ_RUNPARM_VERBOSITY

The log-level verbosity.

SVZ_RUNPARM_MAX_SOCKETS

Maxium number of clients allowed to connect.

These are manipulated by svz_runparm and two convenience macros, both of which accept nick, a C token without the prefix ‘SVZ_RUNPARM_’ (e.g., VERBOSITY).

Function: int svz_runparm (int a, int b) ¶

Set or get a runtime parameter. If a is -1, return the value of runtime parameter b. If a specifies a runtime parameter, set it to b and return 0. Otherwise, return -1.

Macro: SVZ_RUNPARM (nick) ¶

Return the value of runtime parameter nick.

Macro: SVZ_RUNPARM_X (nick, val) ¶

Set the runtime paramater nick to have value val, an integer.