DIGITAL TCP/IP Services for OpenVMS
System Services and C Socket Programming


Previous Contents Index


select()

Allows you to poll or check a group of sockets for I/O activity. It can indicate which sockets are ready to be read or written, or which sockets have an exception pending.

Format

#include <time.h>

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


Arguments

nfds

The highest numbered socket descriptor for which to search. In other words, the nfds argument is the highest numbered bit plus 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).

This argument is used only to improve efficiency. If you are unsure what the highest numbered socket descriptor is, you can safely set nfds to 32.

The DEC C select() routine examines only the longwords referenced by the readfds, writefds, and exceptfds arguments. Therefore, any program that uses the DEC C select routine can never have more than 32 files and sockets opened simultaneously.

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 is 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 longword to which readfds points contains a bit mask of the sockets that are ready for reading. Only bits that were set on entry to select() could possibly be set on exit.

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 is 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 longword that writefds points to contains a bit mask of the sockets that are ready for writing. Only bits that were set on entry to select() are set on exit.

exceptfds

A pointer to a longword bit mask of the socket descriptors that is examined for exceptions. If bit n of the longword is set, socket descriptor n is 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 longword exceptfds pointer contains a bit mask of the sockets that have exceptions pending. Only bits that were set on entry to select() could possibly be set on exit.

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() returns before the timeout period has expired.

The timeout structure points to a timeval structure. See Section 5.8.9 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, when the timeout period expires, or when exceptions occur. If timeout is a nonzero integer, it specifies a maximum interval to wait for the selection to complete.

If the timeout argument is null, the select() routine blocks indefinitely. In order to effect a poll, timeout is non-null, and points to a zero-valued structure.

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

Note

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.

See also accept(), connect(), read(), recv(), recvfrom(), recvmsg(), send(), sendmsg(), sendto(), and write().


Return Values

n The number of sockets ready for I/O or pending exceptions. This value matches the number of returned bits that are set in all output masks.
0 The select() routine timed out before any socket became ready for I/O.
--1 Error; errno is set to indicate the error.

Errors

[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.

send()

Sends bytes through a socket to its connected peer.

The $QIO equivalent is the IO$_WRITEVBLK function.


Format

#include <types.h>

#include <socket.h>

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


Arguments

s

A socket descriptor created with socket() that was 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

Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data is 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.

If you include the TCPIP$INETDEF.H definition file, you can also use:


Description

You can only use this routine 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 can 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() normally blocks until buffer space becomes available. If the socket is defined as nonblocking, however, send() fails 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), send() fails 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 can use the select() routine to determine when it is possible to send more data.

See also read(), recv(), recvmsg(), recvfrom(), getsockopt(), and socket().


Return Values

n The number of bytes sent. This value normally equals len.
--1 Error; errno is set to indicate the error.

Errors

[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The descriptor references a file, not a socket.
[EFAULT] An invalid user space address is 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 <types.h>

#include <socket.h>

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

int sendmsg (int s, struct omsghdr msg[], int flags); (BSD Version 4.3)


Arguments

s

A socket descriptor created with socket().

msg

A pointer to a msghdr structure containing the message to be sent. See Section 5.8.5 for a description of the msghdr structure for BSD Versions 4.3 and 4.4.

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

Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data is 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.

If you include the TCPIP$INETDEF.H definition file, you can also use:


Description

You can use this routine 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 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 Section 5.8.3 for a description of the iovec structure.

If no space is available to buffer the data on the receiving end of the connection, the sendmsg() routine normally blocks until buffer space becomes available. If the socket is defined as nonblocking, the sendmsg() routine fails 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), the sendmsg() fails with an errno indication of EMSGSIZE.

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

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

See also read(), recv(), recvfrom(), recvmsg(), socket(), and getsockopt().


Return Values

n The number of bytes sent.
--1 Error; errno is set to indicate the error.

Errors

[EBADF] The descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a socket.
[EFAULT] An invalid user space address is specified for a parameter.
[EMSGSIZE] The socket requires that messages be sent atomically, and the size of the message to be sent makes 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.

The $QIO equivalent is the IO$_WRITEVBLK function.


Format

#include <types.h>

#include <socket.h>

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


Arguments

s

A socket descriptor 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

Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data is 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.

If you include the TCPIP$INETDEF.H definition file, you can also use:

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 can be used on sockets to send data to named sockets. The data in the msg buffer is sent to the socket whose address is specified in the to argument, 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, the sendto() routine blocks until buffer space becomes available. If the socket is defined as nonblocking, the sendto() routine fails 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), the sendto() routine fails 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 can 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(), socket(), and getsockopt().


Return Values

n The number of bytes sent. This value normally equals len.
--1 Error; errno is set to indicate the error.

Errors

[EBADF] The descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a socket.
[EFAULT] An invalid user space address is specified for a parameter.
[EMSGSIZE] The socket requires that messages be sent atomically, and the size of the message to be sent makes this impossible.
[EWOULDBLOCK] Blocks if the system does not have enough space for buffering the user data.

shutdown()

Shuts down all or part of a bidirectional connection on a socket. This routine disallows further receives, further sends, or both.

The $QIO equivalent is the IO$_DEACCESS function with the IO$M_SHUTDOWN function modifier.


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 (INET$C_DSC_RCV) Disallows further calls to recv() on the socket.
1 (INET$C_DSC_SND) Disallows further calls to send() on the socket.
2 (INET$C_DSC_ALL) 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. Use the shutdown() routine to create unidirectional connections rather than the normal bidirectional (full-duplex) connections.

See also connect() and socket().


Return Values

0 Successful completion.
--1 Error; errno is set to indicate the error.

Errors

[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 end point for communication by returning a special kind of file descriptor called a socket descriptor, which is associated with a TCP/IP Services socket device channel.

The $QIO equivalent is the IO$_SETMODE or IO$_SETCHAR function.


Format

#include <types.h>

#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 socket types are:

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, many protocols may exist, in which case a particular protocol must be specified with this argument. Use the protocol number that is specific to the communication domain in which communication takes 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, which are defined in the <socket.h> header file and described in the setsockopt() routine section of this chapter.

Use the setsockopt() and getsockopt() routines 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>.

See also accept(), bind(), connect(), listen(), read(), recv(), recvfrom(), recvmsg(), select(), send(), sendmsg(), sendto(), shutdown(), and write().

See also getsockname() and getsockopt().


Return Values

x A file descriptor that refers to the socket descriptor.
--1 Error; errno is set to indicate the error.

Errors

[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.


Previous Next Contents Index