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.
Index
- NAME
-
- SYNOPSIS
-
- BACKGROUND
-
- CLIENT LISTS
-
- FUNCTIONS
-
- GLOBAL VARIABLES
-
- FILES
-
- AUTHORS
-
This document was created by
man2html,
using the manual pages.
Time: 20:00:25 GMT, January 29, 2002