Content-type: text/html Manpage of SOCKUNEWSOCKET

SOCKUNEWSOCKET

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

NAME

SockUNewSocket - set up a newsocket connection

SYNOPSIS

#include <SocketUtilities.h>

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

extern int  sockUOfd;               /* default = 1 */
extern int  sockUHandleCmd;         /* default = 1 */
extern int  sockUWaitEol;           /* default = 1 */
extern int  sockUReturnEmptyLine; /* default = 1 */

DESCRIPTION

SockUNewSocket() is called to set up a new socket as either a SERVER or a CLIENT. As described in libSocketUtilities(3), a server usually listens to the socket for incoming data (which they may ignore or answer), and clients send data to a server asynchronously (and may expect an answer).

The arguments are:

fd: If a socket connection was successfully obtained, then this parameter will return the file descriptor referring to this socket.
host: In CLIENT mode, this string specifies the host on which the server is running. If the server is not running, no socket connection can be made, and SockUNewSocket() will fail. In SERVER mode, this parameter should be a NULL string, and any non-NULL value will be ignored (all servers open sockets on the host on which they are running).
service: This string specifies the socket port number to use: in SERVER mode, a socket on this port will be initiated; in CLIENT mode, it will try to connect to the server that is already running on this port. In SERVER mode only, a value of "0" can be used to select the next available port (in case a specific number is not important). In either mode, a string containing a server application name can be used, providing that this application is listed in /etc/services with an associated TCP socket number. For example, the application ptud is listed in /etc/services as using socket port 5062, and so the service string could be "ptud" which means that port 5062 will be used.
queue: This parameter, valid only in SERVER mode, specifies how large the backlog of client connection requests may grow. Calls to SockUGetNextConnection() accept only one connection at a time, so if queue has a value of 3, and 4 clients try to connect before the server calls SockUGetNextConnection(), then the 4th connection request will be ignored. In client mode, a value of -1 should be used.
mode: This parameter should be either SERVER or CLIENT, depending on the mode required.
verbose: A non-zero value of this parameter means that detailed information about the socket connection will be printed on stderr if problems are encountered.

RETURN VALUE

The function returns 0 on failure, 1 on success in CLIENT mode, and the port number used on success in SERVER mode.

EXAMPLES

SERVER mode:

/* open a socket that will listen for connections, with
   a connection request buffer of size 3 */
int  fd, port, verbose=0;
port = SockUNewSocket(&fd,NULL,"4321",3,SERVER,verbose);

/* use a default socket number from /etc/services */
int  fd, port, verbose=0;
port = SockUNewSocket(&fd,NULL,"quadrisd",1,SERVER,verbose);
/* if successful, port will be returned as 5071 
   from /etc/services */

CLIENT mode:

/* open a socket connected to a server on socket 65002 
   on host Invader */
int  success;
success = SockUNewSocket(&fd,"invader","65002",-1,CLIENT);

GLOBAL VARIABLES

There are 4 global variables that affect a new socket connection: sockUOfd, sockUHandleCmd, sockUWaitEol, and sockUReturnEmptyLine Each one affects only new socket connections, ie changing their values will not affect previously opened sockets. Of course, those sockets could be changed by directly modifying the appropriate connection list structure. In more detail, the globals are:

sockUOfd: tells a server to calculate 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 calculate file pointers.
sockUHandleCmd: when its value is 1 (default), this global 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 just return, indicating 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.
sockUWaitEol: by default (value = 1) this global 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 anything is read, and will not wait for newline.

Setting sockUReturnEmptyLine to 1 tells SockUGetNextCommand() to return an empty string if only an end of line separator is read. This is useful in command line programs where prompts are printed. Setting this variable to 0 makes SockUGetNextCommand() block until a non-empty string is entered.

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: 16:41:40 GMT, February 05, 2002