GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  LIBSERVEREVENTS (8)

NAME

libserverevents - Generic Event-Driven Server Library

CONTENTS

Synopsis
Description
     Usage
     Serv_init_func()
     Serv_set_name()
     Serv_set_call_and_response()
     Serv_open_callback()
     Serv_set_data()
     Serv_close_callback()
     Serv_read_callback()
     Serv_write_conn()
     Serv_write_callback()
     Serv_close_conn()
     Serv_set_periodic()
     Signals
     Access To Configuration Variables
     Configuration
     Command-line Options
Authors

SYNOPSIS

#include <libserverevents.h> -I/usr/local/include -L/usr/local/lib -lserverevents

DESCRIPTION

The Libserver package supplies 3 libraries that implement generic servers. The libraries perform network and concurrency tasks. You supply code to service connections. All 3 libraries service TCP or UNIX-domain connections. Separate libraries implement multi-process, multi-threaded, and event-driven servers. This manual documents the event-driven library. The other two libraries are described in the "libserver" manual.

Example echo servers are included in the libserver source distribution.

    USAGE

The library provides your server’s "main" function. You define 5 functions to match the following prototypes.
void serv_init_func();

void serv_open_callback( int fd ); void serv_close_callback( int fd, void *data );

void serv_read_callback( int fd, int len, char *buffer, void *data ); void serv_write_callback( int fd, void *data );

Do not define any other global symbol beginning with the five characters 'serv_’ because the library reserves that namespace.

    SERV_INIT_FUNC()

In serv_init_func() perform the initialization tasks your server needs to do once at server start-up.
void serv_init_func();

The library calls serv_init_func():

  • after changing to the directory specified by the -r command line option.
  • before attempting to change the server’s user and group to the values specified by the command line options. If the server starts as root serv_init_func() executes as root.
  • before the server becomes a daemon and starts listening for connections. The standard streams are connected to the terminal from which the server was started. Error and informative messages should be sent to the terminal.

    SERV_SET_NAME()

Call serv_set_name() inside serv_init_func() to set the server’s name.
void serv_set_name( char *name );

If not set the server’s name defaults to "server". The server’s name is used in two ways:

  • When the server is running, stderr is connected to /dev/null. Errors must be reported with syslog(3). The library calls openlog() with the server’s name as argument to ensure that log entries are identified by the server’s name.
  • The server’s pidfile is written to /var/run/ if the server is started as root. The filename is the server’s name with ".pid" appended to it. This file is used by rc.d scripts to stop the server. A sample script is included in the libserver distribution.

    SERV_SET_CALL_AND_RESPONSE()

Call-and-response behavior is enabled by default. If the protocol your server implements allows both connection endpoints to write simultaneously, call serv_set_call_and_response() in serv_init_func() with an argument of zero to turn off call-and-response behavior.
void serv_set_call_and_response( int on );

With call-and-response behavior enabled, read events are disabled when outgoing data is queued with serv_write_conn(). When the queue is exhausted, read events are enabled again. When call-and-response behavior is disabled, read events are enabled at all times.

    SERV_OPEN_CALLBACK()

serv_open_callback() is called when a new connection is received.
void serv_open_callback( int fd );

The function receives the file descriptor of the socket as argument. Do not read or write the file descriptor directly. It is meant to be used as a unique identifier for active connections if your code needs to store such an identifier. If you write a chat server, for example, you will use the identifiers of other connections to queue outgoing data for them with serv_write_conn().

If the protocol your server implements requires the server to speak first, send the initial data with serv_write_conn() in serv_open_callback().

    SERV_SET_DATA()

You can associate connection-specific data with connections with serv_set_data().
int serv_set_data( int fd, void *data );

Connection-specific data pointers are passed as the last argument to serv_read_callback(), serv_write_callback(), and serv_close_callback().

The data space must be malloc-ed and is freed by the library when the connection is closed. The function returns -1 if the file descriptor does not reference a connection and 0 otherwise.

    SERV_CLOSE_CALLBACK()

serv_close_callback() is called when a connection is closed.
void serv_close_callback( int fd, void *data );

The function’s second argument is the socket’s connection-specific data or NULL. The library frees outgoing queued data and connection-specific data when serv_close_callback() returns.

    SERV_READ_CALLBACK()

serv_read_callback() is called when data has been read from the client.
void serv_read_callback( int fd, int len, char *buffer, void *data );

The second argument is the length of the data in bytes. The length will never be greater than 32768 bytes. The third argument is a character pointer to the data. The fourth argument is the connection-specific data for the socket or NULL.

The buffer pointed to by the third argument is malloc-ed and must be freed before serv_read_callback() returns unless the buffer is passed to serv_write_conn().

    SERV_WRITE_CONN()

To write to the client, passed a malloc-ed buffer to serv_write_conn().
int serv_write_conn( int fd, int len, char *data );

The function’s second argument is the length of the outgoing data in bytes. The third argument is a character pointer to the outgoing data. The data space must be malloc-ed and is freed by the library when the data has been written.

serv_write_conn() does not write the data but queues it for delivery. When the socket is writeable, the library will send up to one complete queued buffer of data to the client, in discrete writes, until the outgoing queue is consumed. Writes are multiplexed with other events. To ensure smooth multiplexing, queue large data in chunks with separate calls to serv_write_conn().

When outgoing data is queued for a connection, read events for that connection are disabled until the queue has been exhausted.

serv_write_conn() returns:

  • -1 if the file descriptor does not reference a connection.
  • -2 if the queue could not be enlarged.
  • 0 on success.

If the function returns -2, the server cannot allocate memory. There is no point continuing to service this connection. Perform any clean up operations necessary, and call serv_close_conn() to drop the connection.

    SERV_WRITE_CALLBACK()

serv_write_callback() is called when a connection’s outgoing data queue is exhausted.
void serv_write_callback( int fd, void *data );

The function’s second argument is the socket’s connection-specific data or NULL.

When writing data from another source to a client, you may not want to queue all the outgoing data at once because you do not know the size of the data in advance, and you want to limit memory or CPU usage. Use serv_write_callback() to queue new data for a connection after its outgoing queue has been consumed.

    SERV_CLOSE_CONN()

To close a connection, invoke serv_close_conn().
int serv_close_conn( int fd, int force );

serv_close_conn() closes a connection immediately if the second "force" argument is non-zero. If "force" is zero, the connection is closed when the outgoing queue has been written to the client. In that situation, further incoming data is not read from the client. serv_close_callback() is called when the socket is closed.

If a client closes its connection, the library calls serv_close_callback().

    SERV_SET_PERIODIC()

You can install a function to be invoked periodically with:
void serv_set_periodic( void (*)(), int );

The function pointed to by first argument is called when the number of seconds specified by the second argument have elapsed and then again repeatedly when that number of seconds has elapsed since the last call.

To timeout idle connections, maintain a timestamp for each connection that you update when the client is active and install a periodic function to close expired connections with serv_close_conn().

    SIGNALS

The library needs to catch SIGTERM, so do not change the disposition of that signal.

Upon receipt of SIGBUS or SIGSEGV, libserver restarts the server with a call to execv(3). If you want to do something else, install your own handler.

If your server starts as root and changes user and group, the library will be unable to restart if your server is not executable by the user or group.

The library will be unable to perform the operations that require root privileges after restart unless you manually turn on the setuid bit of the server (chmod u=+s).

    ACCESS TO CONFIGURATION VARIABLES

You can examine the following configuration variables from your code, but you must not modify them. See the CONFIGURATION section for more information.
char *serv_config_file;
char *serv_root_dir;
char *serv_interface;
char *serv_port;
char *serv_user;
char *serv_group;

serv_config_file
  points to the value passed to the -f option. Defaults to NULL.
serv_root_dir points to the value passed to the -r option. Defaults to NULL.
serv_interface points to the value passed to the -i option. Defaults to "".
serv_port points to the value passed as argument to the -p option. Defaults to "1966".
serv_user points to the value passed as argument to the -u option. Defaults to "nobody".
serv_group points to the value passed as argument to the -g option. Defaults to "nobody".

    CONFIGURATION

The library writes its pidfile into /var/run/ if is started as root. The library is stopped with SIGTERM. The library does graceful stops. The library does not exit until all established connections have closed naturally. If you want to kill a server outright, send it a SIGKILL. A sample control script is provided in the server distribution. To use the script, you must replace all occurrences of "server" with the value you pass to serv_set_name(). The script must be renamed as the value you passed to serv_set_name() and installed in /usr/local/etc/rc.d.

Two variables must be added to /etc/rc.conf to use the script. Substitute your server’s name for "server":

server_enable="YES"
server_flags="-u www -g www -r /usr/local/server"

If the "enable" variable is set to "YES", the server is started at system start. Use the following rc commands:

/usr/local/etc/rc.d/server start
/usr/local/etc/rc.d/server stop
/usr/local/etc/rc.d/server restart
/usr/local/etc/rc.d/server status

If you do not want the server started on system start, then set

libserver_enable="NO"

and use the following commands:

/usr/local/etc/rc.d/server forcestart
/usr/local/etc/rc.d/server forcestop
/usr/local/etc/rc.d/server forcerestart
/usr/local/etc/rc.d/server forcestatus

    COMMAND-LINE OPTIONS

The following command line options are recognized by libserver servers. All of these are optional.
-r User the -r option to specify the server root directory. Libserver chdir(2)s there.
-l By default, the library listens on all TCP interfaces it can find capable of IPv4 or IPv6. The -l option instructs the library to listen on a UNIX-domain socket instead. Specify the path to the socket as argument. The server creates the socket when it starts, unlinking it first if it already exists in the filesystem. The owner and group of the socket are changed to the values of the -u and -g options. The permisssions of the socket are set to srwxrwx---. You cannot specify the -l option together with the -p or -i options.
-p The -p option specifies the port to listen on. This defaults to 1966. To bind to a port lower than 1024, the server must be started as root.
-i By default, libserver accepts connections on all interfaces it can find capable of IPv4 or IPv6. The -i option limits libserver to accepting connections from a specified interface. Pass the IP address of the desired interface as argument.
-q The -q option specifies the backlog of client connections queued by the OS kernel for the server to subsequently service. This value defaults to 1024. Note that the kernel actually uses a queue of 1.5 times the size of the specified value. Connections arriving when the queue is full are dropped by the kernel. Libserver does not let you set this value to less than 1024.
-u
-g
  The -u and the -g options are used to specify the user and group for the server. Both values default to "nobody". For libserver to change user, it must be started as root.

Libserver restarts servers on receipt of SIGSEGV or SIGBUS.

If your server starts as root and changes user and group, the library will be unable to restart if your server is not executable by the user or group.

The library will be unable to perform the operations that require root privileges after restart unless you manually turn on the setuid bit of the server (chmod +s).

-x The -x option prevents libserver from becoming a daemon and writing its pidfile to /var/run/. Libserver runs in the foreground. Stderr is connected to the terminal so that diagnostic output can be sent there.
-f The -f option takes a filename as argument. Libserver assigns the filename to the global character pointer serv_config_file. This enables code in serv_init_func() to access a configuration file.

AUTHORS


.An James Bailie Aq jimmy@mammothcheese.ca
http://www.mammothcheese.ca
Search for    or go to Top of page |  Section 8 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.