Content-type: text/html Manpage of SOCKETUTILITIES

SOCKETUTILITIES

Section: CIM Mobile Robotics Group (3)
Updated: Sept 1995
Index Return to Main Contents

NAME

libSocketUtilities - A socket utility library for client/server applications.

SYNOPSIS

#include <SocketUtilities.h>

int SockUNewSocket(int *fd, char *host, char *service,
                   int queue, int mode, int verbose);

int SockUGetNextConnection(int fdconection, 
                           SockUConnection **links, 
                           struct timeval *timeout, 
                           int verbose);

int SockUGetNextCommand(char *cmd, int *fd, FILE **fp, 
                        SockUConnection **links,
                        struct timeval *timeout);

int SockUAddConnection(SockUConnection **links, int fd);

int SockURemoveConnection(SockUConnection **links, int fd);

int SockUCloseAllConnections(SockUConnection **links);

void SockUTimestampConnection(SockUConnection *conn);

int SockUKillStaleConnections(SockUConnection **links,
                              int stale_delay);

int SockULockConnection(SockUConnection *conn);
int SockUUnlockConnection(SockUConnection *conn);

extern struct timezone  sockUtz;
extern int              sockUOfd;
extern int              sockUHandleCmd;
extern int              sockUWaitEol;
extern int              sockUReturnEmptyLine;

BACKGROUND

This library provides socket communication utilities for client/server applications, such as daemons and their clients. Basically, a server is a process that accepts socket connection requests from other processes, listens to that socket for data, and (most often) responds to whatever process sent that data. A client application is any process that needs some information from the server, so it must connect to it, request something from the server by sending it a command or some data, and then read the response sent back from the server.

For example, imagine there is a program that handles the complicated process of acquiring 3D range data from some sensor (a stereo camera, laser range-finder, etc). One way to acquire data would be for each application that needs 3D data to acquire it by itself, whether by including the sensor source code directly or by linking some library to the application. In the client/server approach, one process (the server) would be dedicated to acquiring 3D data, and any application (a client) that needs data would just send a "give me some data" command to the server, and the server would go about the data acquisition and send it back to the client. This removes from the client low level detail about how the data is acquired, and allows the client to focus on its task without worrying about every last data acquisition detail.

The other advantage of the client/server approach is in a multi-client environment. If there is only one range sensor (as in the example above), then having each application independently trying to compete for access to the sensor may cause some problems (imagine two different programs telling the sensor to scan two different areas at the same time!). With a server controlling access to data from the sensor, these problems will not arise, as the server can ignore requests from some clients until it has finished the data requests from others.

CLIENT LISTS

An application acting as a server keeps track of the clients to which it is connected via a linked list of SockUConnection structures, each of which is defined in SocketUtilities.h as follows:

typedef struct _connection {
  int                fd;
  FILE               *fp;
  int                handle_cmd;
  int                wait_eol;
  char               buffer[BUF_SIZE];
  int                size;
  char               line[LINE_SIZE];
  int                line_available;
  struct timeval     last_operation;
  struct _connection *next;
  int                return_empty_line;
#ifdef _REENTRANT
  pthread_mutex_t    lock_m;    
#endif
} SockUConnection;

Basically, each node contains the file descriptor of the client, a file pointer to write to the client, line and command buffers, 2 behaviour flags and a time-stamp. The user need not access any of the information stored in these fields, except when debugging a server or matching the behaviour of an already-connected client to one of the global variables (described below).

FUNCTIONS

The libSocketUtilities library is made up of 8 functions and 4 global variables. All function calls are prefixed with "SockU". They are summarized below, and each has its own man page:

SockUNewSocket(): initializes a socket connection, and sets up the calling program as a server or a client. This is the only function call required by a client application: reading and writing by a client must be handled in the client code, and not by this library.
SockUGetNextConnection(): tells a server to listen for new socket connections from clients. A user-supplied timeout allows the user to return after a time if no connection requests are pending.
SockUGetNextCommand(): tells a server to listen to all client connections for incoming commands. If any of the clients sent a command to the server, this function returns the file descriptor of the client and a file pointer to which data may be written back to the client. A timeout value is also used to put an upper bound on the amount of time the function will listen for commands before returning.
SockUAddConnection(): tells a server to add a specific client connection to its list of connections instead of waiting for a client to request a connection.
SockURemoveConnection(): will close a specific client connection and remove it from a server's list of connections.
SockUCloseAllConnections(): closes all client connections and removes them from a server's list of connections.
SockUTimestampConnection(): updates the time stamp of a specified client connection within a server's list of connections. This function is called automatically by SockUGetNextCommand() and so the server code need not call it if SockUGetNextCommand() is used to obtain data from clients. This time stamp is most frequently used to indicate the time of the client's last communication with the server.
SockUKillStaleConnections(): closes all client connections that have been inactive for a specified number of seconds (as judged by the connections' timestamps).
SockU[Lock,Unlock]Connection(): locks the mutex on the connection. This only works if your code and the library are both compiled with _REENTRANT defined. DON'T TRY TO MIX REENTRANT AND NON-REENTRANT CODE.

GLOBAL VARIABLES

The libSocketUtilities library contains 5 global variables, prefixed with "sockU". They are summarized below:

sockUtz: is a global variable that specifies the time zone to be used in any gettimeofday() function call. By default it uses the time zone Montreal is in, ie Eastern Standard Time. If any system time checks are to be compared to client time stamps, then this variable must be used.

The remaining 4 global variables affect how SockUGetNextCommand() deals with data coming in from client connections. They affect new clients only, ie changing the values of any of them will not affect existing connections. Of course, the fields in existing client connection structures may be modified directly if existing clients need to be changed.

sockUOfd: is a global variable that tells a server to obtain the file pointer in addition to the file descriptor of new client connections when its value is 1 (the default). A value of 0 tells the server not to obtain file pointers. If a client connection was opened without a file pointer but later requires one, one can be obtained with fdopen(3) and stored in the fp field of the client's SockUConnection structure.
sockUHandleCmd: is a global variable that, when its value is 1 (default), will tell SockUGetNextCommand() to listen for and extract commands, and return them as they appear on the various client connections. A value of 0 means that the command will not be extracted, but rather SockUGetNextCommand() will return saying that something is ready to be read on such-and-such a client connection, and the user must provide code in the server program to extract it. The value of this variable is written to the client's handle_cmd field when it is first connected. To change an already-opened client from one that returns commands to one that doesn't (and vice versa), modify this field directly, as sockUHandleCmd affects only new connections.
sockUWaitEol: is a global variable that by default (value = 1) is set to tell SockUGetNextCommand() to wait for a newline character at the end of a command sent from a client to a server before returning that command (assuming it returns a command, ie sockUHandleCmd = 1). A value of 0 means that SockUGetNextCommand() will return as soon as something is read, and will not wait for newline. If the newline buffering mode of an already connected client needs to be changed, then the wait_eol field of that client's SockUConnection structure should be modified directly.
sockUReturnEmptyLine: is a global variable that by default (value = 1) is set to tell SockUGetNextCommand() to return an empty string if only an end of line separator is entered. This is useful for command line programs which print a cursor.

FILES

/local/mrl/include/SocketUtilities.h: header file
/local/mrl/lib/libSocketUtilities.a: library object code

AUTHORS


Gilbert Soucy, Paul MacKenzie, Marc Bolduc (bolduc@cim.mcgill.ca)
Centre for Intelligent Machines
McGill University, Montreal, Quebec, Canada.

This document was created by man2html, using the manual pages.
Time: 20:00:25 GMT, January 29, 2002