select

Allows the user to poll or check a group of sockets for I/O activity. It can check what sockets are ready to be read or written, or what sockets have a pending exception.

As of OpenVMS Version 7.0, this routine can operate on any number of sockets up to the limit of open files supported by the Compaq C RTL (65535 on OpenVMS Alpha; 2047 on OpenVMS VAX). However, for select to use more than 32 sockets, the TCP/IP Services for OpenVMS used with the Compaq C RTL must offer the same support.

Format

#include <socket.h>

int select (int nfds, int *readfds, int *writefds, int *exceptfds, struct timeval *timeout);

(_DECC_V4_SOURCE) int select (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);

(NOT _DECC_V4_SOURCE)

Arguments

nfds

The highest numbered socket descriptor to search for. That is, the highest numbered bit + 1 in readfds, writefds, and exceptfds that should be examined. Descriptor s is represented by 1<< s (1 shifted to the left s number of times).

Note You must increase the value of FD_SETSIZE if your application will use more sockets in the call to select than the value of FD_SETSIZE in the <time.h> or <socket.h> header files. Do this by defining a larger value for FD_SETSIZE within the application before including <time.h> or <socket.h> .

readfds

A pointer to an array of bits, organized as integers (each integer describing 32 descriptors), that should be examined for read readiness. If bit n of the longword is set, socket descriptor n will be checked to see if it is ready to be read. All bits set in the bit mask must correspond to the file descriptors of sockets. The select routine cannot be used on normal files.

On return, the array of bits to which readfds points contains a bit mask of the sockets that are ready for reading. Only bits that are set on entry to select will be set on exit.

If this pointer is NULL, select ignores the array.

writefds

A pointer to a longword bit mask of the socket descriptors that should be examined for write readiness. If bit n of the longword is set, socket descriptor n will be checked to see if it is ready to be written to. All bits set in the bit mask must correspond to socket descriptors.

On return, the array of bits that writefds points to contains a bit mask of the sockets that are ready for writing. Only bits that are set on entry to select will be set on exit.

If this pointer is NULL, select ignores the array.

exceptfds

A pointer to a longword bit mask of the socket descriptors that should be examined for exceptions. If bit n of the longword is set, socket descriptor n will be checked to see if it has any pending exceptions. All bits set in the bit mask must correspond to the file descriptors of sockets.

On return, the array of bits pointer exceptfds contains a bit mask of the sockets that have exceptions pending. Only bits that are set on entry to select will be set on exit.

If this pointer is NULL, select ignores the array.

timeout

The length of time that select should examine the sockets before returning. If one of the sockets specified in the readfds, writefds, and exceptfds bit masks is ready for I/O, select will return before the timeout period has expired.

The timeout structure points to a timeval structure. See <socket.h> for a description of the timeval structure.

Description

This routine determines the I/O status of the sockets specified in the various mask arguments. It returns either when a socket is ready to be read or written, or when the timeout period expires. If timeout is a nonzero integer, it specifies a maximum interval to wait for the selection to complete.

If the timeout argument is NULL, select will block indefinitely. In order to effect a poll, timeout should be non-NULL, and should point to a zero-valued structure.

If a process is blocked on a select while waiting for input from a socket and the sending process closes the socket, the select notes this as an event and will unblock the process. The descriptors are always modified on return if select returns because of the timeout.

When the socket option SO_OOBINLINE is set on the device_socket, a select on both read and exception events returns the socket mask set on both the read and exception mask. Otherwise, only the exception mask is set.

Note Beginning with OpenVMS Version 7.2-1, the select function fails if one of the specified file descriptor sets contains an invalid file descriptor ( errno is set to EBADF) or a file descriptor not associated with a socket ( errno is set to ENOTSOCK). Previously, select set errno as described, but was otherwise ignoring invalid file descriptors and file descriptors not associated with sockets. To request this old behavior, define the logical name DECC$SELECT_IGNORES_INVALID_FD to any value before invoking the application.

See also accept , connect , read , recv , recvfrom , recvmsg , send , sendmsg , sendto , and write in this section.

Return Values

n	The number of sockets that were ready for I/O or that had pending exceptions. This value matches the number of returned bits that are set in all output masks.
0	Indicates that select timed out before any socket became ready for I/O.
--1	Indicates an error; errno is set to one of the following values: EBADF -- One of the bit masks specified an invalid descriptor. EINVAL -- The specified time limit is unacceptable. One of its components is negative or too large. ENOTSOCK -- A file descriptor not associated with a socket was found in one of the specified file descriptor sets.

send

Sends bytes though a socket to its connected peer.

Format

#include <socket.h>

int send (int s, char *msg, int len, int flags);

(_DECC_V4_SOURCE) ssize_t send (int s, const void *msg, size_t len, int flags);

(NOT _DECC_V4_SOURCE)

Arguments

s

A socket descriptor that was created with socket , and connected to another socket using accept or connect .

msg

A pointer to a buffer containing the data to be sent.

len

The length, in bytes, of the data pointed to by msg.

flags

May be either 0 or MSG_OOB . If it is equal to MSG_OOB , the data will be sent out-of-band. This means that the data can be received before other pending data on the receiving socket if the receiver also specifies a MSG_OOB in the flag parameter of the call.

Description

This routine may only be used on connected sockets. To send data on an unconnected socket, use the sendmsg or sendto routines. The send routine passes data along to its connected peer, which may receive the data by using recv .

If there is no space available to buffer the data being sent on the receiving end of the connection, send will normally block until buffer space becomes available. If the socket is defined as nonblocking, however, send will fail with an errno indication of EWOULDBLOCK . If the message is too large to be sent in one piece and the socket type requires that messages be sent atomically (using SOCK_DGRAM), send will fail with an errno indication of EMSGSIZE .

No indication of failure to deliver is implicit in a send . All errors (except EWOULDBLOCK ) are detected locally. You may use the select routine to determine when it is possible to send more data.

See also read , recv , recvmsg , recvfrom , getsocketopt , and socket in this appendix.

Return Values

n

The number of bytes sent. This value will normally equal len.

--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. EFAULT -- An invalid user space address was specified for a parameter. EMSGSIZE --The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible. EWOULDBLOCK -- Blocks if the system does not have enough space for buffering the user data.

sendmsg

Sends gathered bytes through a socket to any other socket.

Format

#include <socket.h>

int sendmsg (int s, struct msghdr msg[], int flags);

Arguments

s

A socket descriptor that has been created with socket .

msg

A pointer to a msghdr structure containing the message to be sent. See <socket.h> for a description of the msghdr structure.

The msg_iov field of the msghdr structure is used as a series of buffers from which data is read in order until msg_iovlen bytes have been obtained.

flags

May be either 0 or MSG_OOB . If it is equal to MSG_OOB , the data will be sent out-of-band. This means that the data can be received before other pending data on the receiving socket if the receiver also specifies a flag of MSG_OOB .

Description

This routine may be used on any socket to send data to any named socket. The data in the msg_iovec field of the msg structure is sent to the socket whose address is specified in the msg_name field of the structure. The receiving socket gets the data using either the read , recv , recvfrom , or recvmsg routine. When the iovec array specifies more than one buffer, the data is gathered from all specified buffers before being sent. See <uio.h> for a description of the iovec structure.

If there is no space available to buffer the data being sent on the receiving end of the connection, sendmsg will normally block until buffer space becomes available. If the socket is defined as nonblocking, however, sendmsg will fail with an errno indication of EWOULDBLOCK . If the message is too large to be sent in one piece and the socket type requires that messages be sent atomically (SOCK_DGRAM), sendmsg will fail with an errno indication of EMSGSIZE .

If the address specified is a INADDR_BROADCAST address, then the SO_BROADCAST option must be set and the process must have SYSPRV or BYPASS privilege for the I/O operation to succeed.

No indication of failure to deliver is implicit in a sendmsg . All errors (except EWOULDBLOCK ) are detected locally. You may use the select routine to determine when it is possible to send more data.

See also read , recv , recvfrom , recvmsg , and socket in this section, and getsockopt in this appendix.

Return Values

n

The number of bytes sent.

--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. EFAULT -- An invalid user space address was specified for a parameter. EMSGSIZE --The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible. EWOULDBLOCK -- Blocks if the system does not have enough space for buffering the user data.

sendto

Sends bytes through a socket to any other socket.

Format

#include <socket.h>

int sendto (int s, char *msg, int len, int flags, struct sockaddr *to, int tolen);

(_DECC_V4_SOURCE) ssize_t sendto (int s, const void *msg, size_t len, int flags, const struct sockaddr *to, size_t tolen);

(NOT _DECC_V4_SOURCE)

Arguments

s

A socket descriptor that has been created with socket .

msg

A pointer to a buffer containing the data to be sent.

len

The length of the data pointed to by msg.

flags

May be either 0 or MSG_OOB . If it is equal to MSG_OOB , the data will be sent out-of-band. This means that the data can be received before other pending data on the receiving socket if the receiver also specifies a MSG_OOB in its flag parameter of the call.

to

Points to the address structure of the socket to which the data is to be sent.

tolen

The length of the address structure to points to.

Description

This routine may be used on any socket to send data to any named socket. The data in the msg buffer is sent to the socket whose address is specified in to, and the address of socket s is provided to the receiving socket. The receiving socket gets the data using either the read , recv , recvfrom , or recvmsg routine.

If there is no space available to buffer the data being sent on the receiving end of the connection, sendto will normally block until buffer space becomes available. If the socket is defined as nonblocking, however, sendto will fail with an errno indication of EWOULDBLOCK . If the message is too large to be sent in one piece and the socket type requires that messages be sent atomically (using SOCK_DGRAM), sendto will fail with an errno indication of EMSGSIZE .

No indication of failure to deliver is implicit in a sendto . All errors (except EWOULDBLOCK ) are detected locally. You may use the select routine to determine when it is possible to send more data.

If the address specified is a INADDR_BROADCAST address, then the SO_BROADCAST option must be set and the process must have SYSPRV or BYPASS privilege for the I/O operation to succeed.

See also read , recv , recvfrom , recvmsg , and socket in this section, and getsockopt in this appendix.

Return Values

n

The number of bytes sent. This value will normally equal len.

--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. EFAULT -- An invalid user space address was specified for a parameter. EMSGSIZE --The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible. EWOULDBLOCK -- Blocks if the system does not have enough space for buffering the user data.

sethostent

Opens and rewinds the network host database file.

Format

#include <netdb.h>

void sethostent (int stay_open);

Arguments

stay_open

Specifies a value used to indicate when to close the host database file:

• 0 (zero) to close the host database file after each call to the gethostbyname or gethostbyaddr routine.
• nonzero to keep the host database file open after each call.

Description

The sethostent routine opens or rewinds the network host 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 the endhostent or exit routine is called.

See also endhostent in this section.

setnetent

Opens and rewinds the networks database file.

Format

#include <netdb.h>

void setnetent (int stay_open);

Arguments

stay_open

Specifies a value used to indicate when to close the networks database file:

• 0 (zero) to close the networks database file after each call to the getnetent .
• nonzero to keep the networks database file open after each call.

Description

The setnetent routine opens the networks 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 endnetent or exit routine.

See also endnetent , getnetent , and exit in this section.

setprotoent

Opens, rewinds, or closes the protocols database file.

Format

#include <netdb.h>

void setprotoent (int stay_open);

Arguments

stay_open

Specifies a value used to indicate when to close the protocols database file:

• 0 (zero) to close the host database file after each call to the getprotoent routine.
• nonzero to keep the host database file open after each call.

Description

The setprotoent routine opens, or rewinds the protocols database file and sets 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 endprotoent , or exit routine.

See also endprotoent , exit , and getprotoent in this section.

Return Values

1	Indicates success.
0	Indicates an error; unable to open the protocols database file.

Errors

If the setprotoent routine fails, the error is further specified in the global errno .