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
SEE ALSO
libSocketUtilities(3), SockUGetNextConnection(3),
SockUGetNextCommand(3)
AUTHORS
Gilbert Soucy, Paul MacKenzie, Marc Bolduc (bolduc@cim.mcgill.ca)
Centre for Intelligent Machines
McGill University, Montreal, Quebec, Canada.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUE
-
- EXAMPLES
-
- GLOBAL VARIABLES
-
- FILES
-
- SEE ALSO
-
- AUTHORS
-
This document was created by
man2html,
using the manual pages.
Time: 16:41:40 GMT, February 05, 2002