Compaq C
Compaq C
Run-Time Library Reference Manual for
OpenVMS Systems
setservent
Opens and rewinds the network services database file.
Format
#include <netdb.h>
void setservent (int stay_open);
Arguments
stay_open
Specifies a value used to indicate when to close the network services
database file:
- 0 (zero) to close the network services database file after each
call to the
getservent
routine.
- nonzero to keep the network services database file open after each
call to
getservent
.
Description
The
setservent
routine opens the network services database file and resets the file
marker to the beginning of the file.
Passing a nonzero value to the stay_open parameter keeps the
connection open until you call the
endservent
, or
exit
routine.
See also
endservent
,
exit
, and
getservent
in this section.
setsockopt
Sets options on a socket.
Format
#include <socket.h>
int setsockopt (int s, int level, int
optname, char *optval, int optlen);
(_DECC_V4_SOURCE)
int setsockopt (int s, int level, int
optname, const void *optval, size_t optlen);
(NOT _DECC_V4_SOURCE)
Arguments
s
A socket descriptor created by
socket
.
level
The protocol level for which the socket options are to be modified. It
may have one of the following values:
|
SOL_SOCKET
|
Set the options at the socket level.
|
|
p
|
Any protocol number. Set the options for protocol level p. See the
<in.h>
header file for the various IPPROTO values.
|
optname
Is interpreted by the protocol specified in level. Options at
each protocol level are documented with the protocol.
The following options are available at the socket level:
SO_REUSEADDR indicates the rules used in validating addresses supplied
in a
bind
call should allow reuse of local addresses.
SO_KEEPALIVE keeps connections alive by enabling the periodic
transmission of messages on a connected socket. Should the connected
party fail to respond to these messages, the connection is considered
broken and processes using the socket are notified through an EPIPE
error.
SO_DONTROUTE indicates that outgoing messages should bypass the
standard routing facilities. Instead, messages are directed to the
appropriate network interface according to the network portion of the
destination address.
SO_LINGER delays the internal socket deletion portion of
close
until either the data has been transmitted, or the device times out
(approximately eight minutes).
SO_BROADCAST is used to enable or disable broadcasting on the socket.
optval
Points to a buffer containing the parameters of the specified option.
All socket level options other than SO_LINGER take an integer parameter
that should be nonzero if the option is to be enabled, or zero if it is
to be disabled.
SO_LINGER uses a
linger
structure parameter defined in the
<socket.h>
file. This structure specifies the desired state of the option and the
linger interval. The option value for the SO_LINGER command is the
address of a
linger
structure. See the
<socket.h>
header file for a description of the
linger
structure.
If the socket promises reliable delivery of data and
l_onoff
is nonzero, the system will block the process on the
close
attempt until it is able to transmit the data or until it decides it is
unable to deliver the information. A timeout period, called the linger
interval, is specified in
l_linger
.
If
l_onoff
is set to 0 and a
close
is issued, the system will process the close in a manner that allows
the process to continue as quickly as possible.
optlen
An integer containing the size of the buffer pointed to by
optval.
Description
This routine manipulates options associated with a socket. Options may
exist at multiple protocol levels; they are always present at the
uppermost socket level.
When manipulating socket options, the level at which the option resides
and the name of the option must be specified. To manipulate options at
the socket level, specify level as
SOL_SOCKET
. To manipulate options at any other level, the protocol number of the
appropriate protocol controlling the option must be supplied. For
example, to indicate an option is to be interpreted by the TCP
protocol, level should be set to the protocol number
(IPPROTO_TCP) of TCP. See
<in.h>
for the various IPPROTO values.
Return Values
|
0
|
Indicates success.
|
|
--1
|
Indicates an error;
errno
is set to one of the following:
- EBADF -- The descriptor is invalid.
- ENOTSOCK -- The socket descriptor references a file, not a socket.
- ENOTCONN -- The socket is not connected.
- ENOPROTOOPT -- The option is unknown.
- EFAULT -- The
optname parameter is not a valid part of the user address
space.
|
shutdown
Shuts down all or part of a bidirectional connection on a socket. It
can disallow further receives, further sends, or both.
Format
#include <socket.h>
int shutdown (int s, int how);
Arguments
s
A socket descriptor that is in a connected state as a result of a
previous call to either
connect
or
accept
.
how
How the socket is to be shut down. Use one of the following values:
|
0
|
Disallows further calls to
recv
on the socket.
|
|
1
|
Disallows further calls to
send
on the socket.
|
|
2
|
Disallows further calls to both
send
and
recv
.
|
Description
This routine allows communications on a socket to be shut down one
piece at a time rather than all at once. It can be used to create
unidirectional connections rather than the normal bidirectional
(full-duplex) connections.
See also
connect
and
socket
in this section.
Return Values
|
0
|
Indicates success.
|
|
--1
|
Indicates an error;
errno
is set to one of the following:
- EBADF -- The socket descriptor is invalid.
- ENOTSOCK -- The descriptor references a file, not a socket.
- ENOTCONN -- The specified socket is not connected.
|
socket
Creates an endpoint for communication by returning a special kind of
file descriptor called a socket descriptor, which is associated with a
TCP/IP Services for OpenVMS Socket Device Channel.
Format
#include <socket.h>
int socket (int af, int type, int protocol);
Arguments
af
The address format to be used in later references to the socket.
Addresses specified in subsequent operations using the socket are
interpreted according to this format. Currently, only AF_INET (Internet
style) addresses are supported.
type
The semantics of communication. The type may be SOCK_STREAM,
SOCK_DGRAM, or SOCK_RAW.
SOCK_STREAM type sockets provide sequenced, reliable, two-way
connection based byte streams with an available out-of-band data
transmission mechanism.
SOCK_DGRAM sockets support datagrams (connectionless, unreliable data
transmission mechanism).
SOCK_RAW sockets provide access to internal network interfaces, and are
available only to users with SYSPRV privilege.
protocol
The protocol to be used with the socket. Normally only a single
protocol exists to support a particular socket type using a given
address format. However, it is possible that many protocols may exist,
in which case a particular protocol must be specified with this
argument. The protocol number to use is particular to the communication
domain in which communication is to take place.
Description
This routine provides the primary mechanism for creating sockets. The
type and protocol of the socket affect the way the socket behaves and
how it can be used.
The operation of sockets is controlled by socket-level options, defined
in the file
<socket.h>
. The
setsockopt
and
getsockopt
calls are used to set and get options. Options other than SO_LINGER
take an integer parameter that should be nonzero if the option is to be
enabled, or 0 if it is to be disabled. SO_LINGER uses a
linger
structure parameter defined in
<socket.h>
. The members of this structure specify the desired state of the option
and the linger interval in the following manner:
SO_REUSEADDR indicates that the rules used in validating addresses
supplied in a
bind
call should allow reuse of local addresses.
SO_KEEPALIVE keeps connections alive by enabling the periodic
transmission of messages on a connected socket. Should the connected
party fail to respond to these messages, the connection is considered
broken and processes using the socket are notified through the error
code SS$_LINKDISCON.
SO_DONTROUTE indicates that outgoing messages should bypass the
standard routing facilities. Instead, messages are directed to the
appropriate network interface according to the network portion of the
destination address.
SO_LINGER lingers on close if data is present. It controls the actions
taken when unsent messages are queued on the socket and a
close
is performed. When using the
setsockopt
to set the linger values, the option value for the SO_LINGER command is
the address of a linger structure:
struct linger {
int l_onoff; /* option on/off */
int l_linger; /* linger time */
};
|
If the socket promises reliable delivery of data and
l_onoff
is nonzero, the system will block the process on the attempt until it
is able to transmit the data or until it decides it is unable to
deliver the information. A timeout period, called the linger interval,
is specified in
l_linger
. If
l_onoff
is set to 0 and a close is issued, the system will process the close in
a manner that allows the process to continue as quickly as possible.
SO_BROADCAST is used to enable or disable broadcasting on the socket.
See also
accept
,
bind
,
connect
,
getsockname
,
getsockopt
,
listen
,
read
,
recv
,
recvfrom
,
recvmgs
,
select
,
send
,
sendmsg
,
sendto
,
shutdown
, and
write
in this appendix.
Return Values
|
x
|
A file descriptor that refers to the socket descriptor.
|
|
--1
|
Indicates an error;
errno
is set to one of the following:
- EAFNOSUPPORT -- The specified address family is not supported in
this version of the system.
- ESOCKTNOSUPPORT -- The specified socket type is not supported in
this address family.
- EPROTONOSUPPORT -- The specified protocol is not supported.
- EPROTOTYPE -- Request for a type of socket for which there is no
supporting protocol.
- EMFILE -- The per-process descriptor table is full.
- ENOBUFS -- No buffer space is available. The socket cannot be
created.
|
decc$socket_fd
Returns the socket descriptor associated with a Socket Device Channel
for direct use with the Compaq C RTL.
Format
#include <socket.h>
int decc$socket_fd (int channel);
Arguments
channel
A valid Socket Device Channel.
Description
The
decc$socket_fd
routine associates a valid socket channel with a Compaq C RTL
file descriptor, and returns the file descriptor. The file descriptor
can then be used with one of the Compaq C routines that take a
file descriptor or socket descriptor as an input parameter.
Return Values
|
x
|
The socket descriptor.
|
|
--1
|
Indicates an error; the socket descriptor cannot be allocated.
|
vaxc$get_sdc
Returns the Socket Device Channel (SDC) associated with a socket
descriptor for direct use with the TCP/IP Services for OpenVMS product.
Format
#include <socket.h>
short int vaxc$get_sdc (int s);
Argument
s
A socket descriptor.
Description
This routine returns the SDC associated with a socket. C socket
descriptors are normally used either as file descriptors or with one of
the routines that takes an explicit socket descriptor as its argument.
C sockets are implemented using TCP/IP Services for OpenVMS Socket Device Channels.
This routine returns the SDC used by a given socket descriptor so that
you can use the TCP/IP Services for OpenVMS's facilities directly by means of
various I/O system services ($QIO).
Return Values
|
0
|
Indicates that
s is not an open socket descriptor.
|
|
x
|
The SDC number.
|
write
Writes a buffer of data to a socket or file.
Format
#include <unixio.h>
int write (int d, void *buffer, int nbytes);
Arguments
d
A descriptor that must refer to a socket or file.
buffer
The address of contiguous storage from which the output data is taken.
nbytes
The maximum number of bytes involved in the write operation.
Description
This routine attempts to write a buffer of data to a socket or file.
See also
socket
in this section.
Return Values
|
x
|
The number of bytes written to the socket or file.
|
|
0
|
Indicates an error.
|
|
--1
|
Indicates an error;
errno
is set to one of the following:
- EBADF -- The
d argument is not a valid descriptor open for writing.
- EPIPE -- An attempt was made to write to a socket that is not open
for reading by any process.
- EFAULT - Part of the array pointed to by
iov
or data to be written to the file points outside the process's
allocated address space.
- EWOULDBLOCK -- The
NBIO
(nonblocking) flag is set for the socket descriptor and the process
would be delayed in the write operation.
- EINVAL -- The
nbytes argument is negative.
|
A.9 Programming Examples
This section provides Compaq C socket communications programming
examples.
Example A-1 is an example of a TCP/IP Server.
| Example A-1 TCP/IP Server |
/*====================================================================
*
* Copyright (C) 2001 by
* Compaq Computer Corporation
*
* This software is furnished under a license and may be used and copied
* only in accordance with the terms of such license and with the
* inclusion of the above copyright notice. This software or any other
* copies thereof may not be provided or otherwise made available to any
* other person. No title to and ownership of the software is hereby
* transferred.
*
* The information in this software is subject to change without notice
* and should not be construed as a commitment by Compaq Computer
* Corporation.
*
* Compaq assumes no responsibility for the use or reliability of its
* software on equipment that is not supplied by Compaq.
*
*
*
* FACILITY:
* INSTALL
*
*
* ABSTRACT:
* This is an example of a TCP/IP server using the IPC
* socket interface.
*
*
* ENVIRONMENT:
* UCX V1.2 or higher, VMS V5.2 or higher
*
* This example is portable to ULTRIX. The include
* files are conditionally defined for both systems, and
* "perror" is used for error reporting.
* BUILD INSTRUCTIONS:
*
* To link in VAXC/VMS you must have the following
* entries in your .opt file:
* sys$library:ucx$ipc.olb/lib
* sys$share:vaxcrtl.exe/share
*
* For Compaq C or Compaq C++, compile /PREFIX=ALL and link via
* $ link UCX$TCP_SERVER_IPC
*
* To build this example program, use commands of the following form:
*
* using the Compaq C compiler:
*
* $ cc/prefix=all UCX$TCP_SERVER_IPC.C
* $ link UCX$TCP_SERVER_IPC
*
* using the Compaq C++ compiler:
*
* $ cxx/prefix=all/define=VMS UCX$TCP_SERVER_IPC.C
* $ link UCX$TCP_SERVER_IPC
*
* using the VAX C compiler:
*
* $ cc /vaxc UCX$TCP_SERVER_IPC.C
* $ link UCX$TCP_SERVER_IPC, -
* SYS$LIBRARY:UCX$IPC/LIB, -
* SYS$INPUT/OPTIONS
* SYS$SHARE:UCX$IPC_SHR/SHARE
* SYS$SHARE:VAXCRTL.EXE/SHARE
*
* AUTHORS:
* UCX Developer
*
* CREATION DATE: May 23, 1989
*
* MODIFICATION HISTORY:
*
* 16 May 1996 Joseph J. Vlcek
* Make compatible with the Compaq C and Compaq C++ compilers.
* Add directions on how to build this example modules.
*
*/
/*
*
* INCLUDE FILES
*
*/
#ifdef VMS
#include <descrip.h> /* VMS descriptor stuff */
#include <in.h> /* internet system Constants and structures. */
#include <inet.h> /* Network address info. */
#include <iodef.h> /* I/O FUNCTION CODE DEFS */
#include <lib$routines.h> /* LIB$ RTL-routine signatures. */
#include <netdb.h> /* Network database library info. */
#include <signal.h> /* UNIX style Signal Value Definitions */
#include <socket.h> /* TCP/IP socket definitions. */
#include <ssdef.h> /* SS$_<xyz> sys ser return statistics */
#include <starlet.h> /* Sys ser calls */
#include <stdio.h> /* UNIX 'Standard I/O' Definitions */
#include <stdlib.h> /* General Utilities */
#include <string.h> /* String handling function definitions */
#include <ucx$inetdef.h> /* UCX network definitions */
#include <unixio.h> /* Prototypes for UNIX emulation functions */
#else
#include <errno.h>
#include <sys/types.h>
#include <stdio.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>
#include <arpa/inet.h>
#include <sys/uio.h>
#endif
/*
* Functional Description
*
* This example creates a socket of type SOCK_STREAM (TCP),
* binds and listens on the socket, receives a message,
* and closes the connection.
* Error messages are printed to the screen.
*
* IPC calls used:
* accept
* bind
* close
* gethostbyname
* listen
* recv
* shutdown
* socket
*
*
* Formal Parameters
* The server program expects one parameter:
* portnumber ... port number where it will listen
*
*
* Routine Value
*
* Status
*/
/*--------------------------------------------------------------------*/
cleanup( int how_many, int sock1, int sock2 )
{
int retval;
/*
* Shutdown and close sock1 completely.
*/
retval = shutdown(sock1,2);
if (retval == -1)
perror ("shutdown");
retval = close (sock1);
if (retval)
perror ("close");
/*
* If given, shutdown and close sock2.
*/
if (how_many == 2)
{
retval = shutdown(sock2,2);
if (retval == -1)
perror ("shutdown");
retval = close (sock2);
if (retval)
perror ("close");
}
exit( 1 );
} /* end cleanup*/
/*--------------------------------------------------------------------*/
main( int argc, char **argv )
{
int sock_2, sock_3; /* sockets */
static char message[BUFSIZ];
static struct sockaddr_in sock2_name; /* Address struct for socket2.*/
static struct sockaddr_in retsock2_name; /* Address struct for socket2.*/
struct hostent hostentstruct; /* Storage for hostent data. */
struct hostent *hostentptr; /* Pointer to hostent data. */
static char hostname[256]; /* Name of local host. */
int flag;
int retval; /* helpful for debugging */
int namelength;
/*
* Check input parameters.
*/
if (argc != 2 )
{
printf("Usage: server portnumber.\n");
exit( 1 );
}
/*
* Open socket 2: AF_INET, SOCK_STREAM.
*/
if ((sock_2 = socket (AF_INET, SOCK_STREAM, 0)) == -1)
{
perror( "socket");
exit( 1 );
}
/*
* Get the host local name.
*/
retval = gethostname(hostname,sizeof hostname);
if (retval)
{
perror ("gethostname");
cleanup (1, sock_2, 0);
}
/*
* Get pointer to network data structure for socket 2.
*/
if ((hostentptr = gethostbyname (hostname)) == NULL)
{
perror( "gethostbyname");
cleanup(1, sock_2, 0);
}
/*
* Copy hostent data to safe storage.
*/
hostentstruct = *hostentptr;
/*
* Fill in the name & address structure for socket 2.
*/
sock2_name.sin_family = hostentstruct.h_addrtype;
sock2_name.sin_port = htons(atoi(argv[1]));
sock2_name.sin_addr = * ((struct in_addr *) hostentstruct.h_addr);
/*
* Bind name to socket 2.
*/
retval = bind ( sock_2,
(struct sockaddr*)&sock2_name,
sizeof sock2_name );
if (retval)
{
perror("bind");
cleanup(1, sock_2, 0);
}
/*
* Listen on socket 2 for connections.
*/
retval = listen (sock_2, 5);
if (retval)
{
perror("listen");
cleanup(1, sock_2, 0);
}
/*
* Accept connection from socket 2:
* accepted connection will be on socket 3.
*/
namelength = sizeof (sock2_name);
sock_3 = accept (sock_2, (struct sockaddr*)&sock2_name, &namelength);
if (sock_3 == -1)
{
perror ("accept");
cleanup( 2, sock_2, sock_3);
}
/*
* Receive message from socket 1.
*/
flag = 0; /* maybe 0 or MSG_OOB or MSG_PEEK */
retval = recv(sock_3, message, sizeof (message), flag);
if (retval == -1)
{
perror ("receive");
cleanup( 2, sock_2, sock_3);
}
else
printf (" %s\n", message);
/*
* Call cleanup to shutdown and close sockets.
*/
cleanup(2, sock_2, sock_3);
} /* end main */
|
Example A-2 is an example of a TCP/IP Client.
| Example A-2 TCP/IP Client |
/*====================================================================
*
* Copyright (C) 2001 by
* Compaq Computer Corporation
*
* This software is furnished under a license and may be used and copied
* only in accordance with the terms of such license and with the
* inclusion of the above copyright notice. This software or any other
* copies thereof may not be provided or otherwise made available to any
* other person. No title to and ownership of the software is hereby
* transferred.
*
* The information in this software is subject to change without notice
* and should not be construed as a commitment by Compaq Computer
* Corporation.
*
* Compaq assumes no responsibility for the use or reliability of its
* software on equipment that is not supplied by Compaq.
*
*
*
* FACILITY:
* INSTALL
*
*
* ABSTRACT:
* This is an example of a TCP/IP client using the IPC
* socket interface.
*
*
* ENVIRONMENT:
* UCX V1.2 or higher, VMS V5.2 or higher
*
* This example is portable to ULTRIX. The include
* files are conditionally defined for both systems, and
* "perror" is used for error reporting.
* BUILD INSTRUCTIONS:
*
* To link in VAXC/VMS you must have the following
* entries in your .opt file:
* sys$library:ucx$ipc.olb/lib
* sys$share:vaxcrtl.exe/share
*
* For Compaq C or Compaq C++, compile /PREFIX=ALL and link via
* $ link UCX$TCP_CLIENT_IPC
*
* To build this example program, use commands of the following form:
*
* using the Compaq C compiler:
*
* $ cc/prefix=all UCX$TCP_CLIENT_IPC.C
* $ link UCX$TCP_CLIENT_IPC
*
* using the Compaq C++ compiler:
*
* $ cxx/prefix=all/define=VMS UCX$TCP_CLIENT_IPC.C
* $ link UCX$TCP_CLIENT_IPC
*
* using the VAX C compiler:
*
* $ cc /vaxc UCX$TCP_CLIENT_IPC.C
* $ link UCX$TCP_CLIENT_IPC, -
* SYS$LIBRARY:UCX$IPC/LIB, -
* SYS$INPUT/OPTIONS
* SYS$SHARE:UCX$IPC_SHR/SHARE
*
* AUTHORS:
* UCX Developer
*
* CREATION DATE: May 23, 1989
*
* MODIFICATION HISTORY:
*
* 16 May 1996 Joseph J. Vlcek
* Make compatible with the Compaq C and Compaq C++ compilers.
* Add directions on how to build this example modules.
*
*/
/*
*
* INCLUDE FILES
*
*/
#if defined(VMS) || defined(__VMS)
#include <stdlib.h>
#include <unixio.h>
#include <errno.h>
#include <types.h>
#include <stdio.h>
#include <socket.h>
#include <in.h>
#include <netdb.h> /* change hostent to comply with BSD 4.3*/
#include <inet.h>
#include <ucx$inetdef.h> /* INET symbol definitions */
#else
#include <errno.h>
#include <sys/types.h>
#include <stdio.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>
#include <arpa/inet.h>
#include <sys/uio.h>
#endif
/*
*
* MACRO DEFINITIONS
*
*/
#ifndef vms
#define TRUE 1
#define FALSE 0
#endif
void cleanup(int shut, int socket);
/*
* Functional Description
*
* This example creates a socket of type SOCK_STREAM (TCP),
* initiates a connection to the remote host, sends
* a message to the remote host, and closes the connection.
* Error messages are printed to the screen.
*
* IPC calls used:
* close
* connect
* gethostbyname
* send
* shutdown
* socket
*
*
* Formal Parameters
* The client program expects two parameters:
* hostname ... name of remote host
* portnumber ... port where remote host(server) is listening
*
*
* Routine Value
*
* Status
*/
/*--------------------------------------------------------------------*/
main(int argc, char **argv)
{
int sock_1; /* socket */
static char message[] = "Hi there.";
static struct sockaddr_in sock2_name; /* Address struct for socket2.*/
struct hostent hostentstruct; /* Storage for hostent data. */
struct hostent *hostentptr; /* Pointer to hostent data. */
static char hostname[256]; /* Name of local host. */
int flag;
int retval; /* Helpful for debugging. */
int shut = FALSE; /* Flag to cleanup. */
/*
* Check input parameters.
*/
if (argc != 3 )
{
printf("Usage: client hostname portnumber.\n");
exit(EXIT_FAILURE);
}
/*
* Open socket 1: AF_INET, SOCK_STREAM.
*/
if ((sock_1 = socket (AF_INET, SOCK_STREAM, 0)) == -1)
{
perror( "socket");
exit(EXIT_FAILURE);
}
/*
*Get pointer to network data structure for socket 2 (remote host).
*/
if ((hostentptr = gethostbyname (argv[1])) == NULL)
{
perror( "gethostbyname");
cleanup(shut, sock_1);
}
/*
* Copy hostent data to safe storage.
*/
hostentstruct = *hostentptr;
/*
* Fill in the name & address structure for socket 2.
*/
sock2_name.sin_family = hostentstruct.h_addrtype;
sock2_name.sin_port = htons(atoi(argv[2]));
sock2_name.sin_addr = * ((struct in_addr *) hostentstruct.h_addr);
/*
* Connect socket 1 to sock2_name.
*/
retval = connect(sock_1, (struct sockaddr *)&sock2_name,
sizeof (sock2_name));
if (retval)
{
perror("connect");
cleanup(shut, sock_1);
}
/*
* Send message to socket 2.
*/
flag = 0; /* maybe 0 or MSG_OOB */
retval = send(sock_1, message ,sizeof (message), flag);
if (retval < 0)
{
perror ("send");
shut = TRUE;
}
/*
* Call cleanup to shutdown and close socket.
*/
cleanup(shut, sock_1);
} /* end main */
/*-----------------------------------------------------------*/
void cleanup(int shut, int socket)
{
int retval;
/*
* Shutdown socket completely -- only if it was connected.
*/
if (shut) {
retval = shutdown(socket,2);
if (retval == -1)
perror ("shutdown");
}
/*
* Close socket.
*/
retval = close (socket);
if (retval)
perror ("close");
exit(EXIT_SUCCESS);
} /* end main */
|
 |
|
