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

Previous | Contents

If a connection request arrives with the queue full (more than backlog connection requests pending), the client receives an error with an errno indication of ECONNREFUSED.

See also accept(), connect(), and socket().

## Return Values

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

## Errors

> You can set errno to the following values:
> [EBADF] | The socket descriptor is invalid.
> [ENOTSOCK] | The socket descriptor references a file, not a socket.
> [EOPNOTSUPP] | The socket is not of a type that supports the operation listen().

# read()

> Reads bytes from a socket or file and places them in a user-provided buffer.

> The $QIO equivalent is the IO$_READVBLK function.

## Format

> ### #include <unixio.h>

> ### int read (int d, void *buffer, int nbytes);

## ARGUMENTS

> ### d

> A descriptor that must refer to a socket or file currently opened for reading.

> ### buffer

> The address of a user-provided buffer in which the input data is placed.

> ### nbytes

> The maximum number of bytes allowed in the read operation.

## DESCRIPTION

> If the end-of-file is not reached, the read() routine returns nbytes. If the end-of-file occurs during the read() routine, it returns the number of bytes read.

> Upon successful completion, read() returns the number of bytes actually read and placed in the buffer.

> See also socket().

## Return Values

> x | The number of bytes read and placed in the buffer.
> 0 | Peer has closed the connection.
> --1 | Error; errno is set to indicate the error.

## Errors

> You can set errno to the following values:
> [EBADF] | The descriptor is invalid.
> [EFAULT] | The buffer points outside the allocated address space.
> [EINVAL] | The nbytes argument is negative.
> [EWOULDBLOCK] | The NBIO socket option (nonblocking) flag is set for the socket or file descriptor and the process would be delayed in the read operation.

# recv()

> Receives bytes from a connected socket and places them into a user-provided buffer.

> The $QIO equivalent is the IO$_READVBLK function.

## Format

> ### #include <types.h>

> ### #include <socket.h>

> ### int recv (int s, char *buf, int len, int flags);

## ARGUMENTS

> ### s

> A socket descriptor created as the result of a call to accept() or connect().

> ### buf

> A pointer to a user-provided buffer into which received data will be placed.

> ### len

> The size of the buffer pointed to by buf.

> ### flags

> A bit mask that can contain one or more MSG_OOB and MSG_PEEK flags. It is built by ORing the appropriate values together, as follows:

> Flag | Description
> --- | ---
> MSG_OOB | Allows you to receive out-of-band data.
> | If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_OOB flag is ignored.
> | Use the send(), sendmsg(), and sendto() to send out-of-band data.
> MSG_PEEK | Allows you to peek at the data next in line to be received without actually removing it from the system's buffers.

> If you include the UCX$INETDEF definition file, use the flags listed in the following table:

> Flag | Description
> --- | ---
> UCX$C_MSG_NBIO | Does not block the I/O operation if the transmit queue is full. Similar to using the $QIO IO$M_NOWAIT function.
> UCX$C_MSG_PURGE | Flushes data from the queue. Similar to using the $QIO IO$M_PURGE function.
> UCX$C_MSG_BLOCKALL | Blocks the completion of the operation until the buffer is filled completely or until the connection is closed. Similar to using the $QIO IO$M_LOCKBUF function.

## DESCRIPTION

> This routine receives data from a connected socket. To receive data on an unconnected socket, use the recvfrom() or recvmsg() routines. The received data is placed in the buffer buf.

> Data is sent by the socket's peer using the send, sendmsg(), or sendto() routines.

> Use the select() routine to determine when more data arrives.

> If no data is available at the socket, the receive call waits for data to arrive, unless the socket is nonblocking, in which case a --1 is returned with the external variable errno set to EWOULDBLOCK.

> See also read(), send(), sendmsg(), sendto(), and socket().

## Return Values

> x | The number of bytes received and placed in buf.
> 0 | Peer has closed.
> --1 | Error; errno is set to indicate the error.

## Errors

> You can set errno to the following values:
> [EBADF] | The socket descriptor is invalid.
> [ENOTSOCK] | The descriptor references a file, not a socket.
> [EPIPE] | You tried to write to a socket that is not open for reading by any process.
> [EWOULDBLOCK] | The NBIO (nonblocking) flag is set for the socket descriptor and the process is delayed during the write operation.
> [EFAULT] | The data was specified to be received into a nonexistent or protected part of the process address space.

# recvfrom()

> Receives bytes for a socket from any source.

## Format

> ### #include <types.h>

> ### #include <socket.h>

> ### int recvfrom (int s, char *buf, int len, int flags, struct sockaddr *from, int *fromlen)

> ;

## ARGUMENTS

> ### s

> A socket descriptor created with socket() and bound to a name using bind() or as a result of accept().

> ### buf

> A pointer to a buffer into which received data is placed.

> ### len

> The size of the buffer pointed to by buf.

> ### flags

> A bit mask that can contain one or more MSG_OOB and MSG_PEEK flag. It is built by ORing the appropriate values together, as follows:

> Flag | Description
> --- | ---
> MSG_OOB | Allows you to receive out-of-band data. If out-of-band data is available, it is read first.
> | If no out-of-band data is available, the MSG_OOB flag is ignored. To send out-of-band data, use the send(), sendmsg(), and sendto().
> MSG_PEEK | Allows you to peek at the data that is next in line to be received without actually removing it from the system's buffers.

> If you include the UCX$INETDEF definition file, use the flags listed in the following table:

> Flag | Description
> --- | ---
> UCX$C_MSG_NBIO | Does not block the I/O operation if the transmit queue is full. Similar to using the $QIO IO$M_NOWAIT function.
> UCX$C_MSG_PURGE | Flushes data from the queue. Similar to using the $QIO IO$M_PURGE modifier.
> UCX$C_MSG_BLOCKALL | Blocks the completion of the operation until the buffer is filled completely or until the connection is closed. Similar to using the $QIO IO$M_LOCKBUF function.

> ### from

> A buffer that the recvfrom routine uses to place the address of the socket from which the data is received.

> If from is nonzero, the address is returned. If from is 0, the address is not returned.

> ### fromlen

> Points to an integer containing the size of the buffer pointed to by from. On return, the integer is modified to contain the actual length of the socket address structure returned.

## DESCRIPTION

> This routine allows a named, unconnected socket to receive data. The data is placed in the buffer pointed to by buf, and the address of the sender of the data is placed in the buffer pointed to by from if from is non-null. The structure that from points to is assumed to be as large as the sockaddr structure. See Section 5.8.7 for a description of sockaddr structure.

> To receive bytes from any source, the socket need not be connected to another socket.

> You can use the select() routine to determine if data is available.

> If no data is available at the socket, the recvfrom() call waits for data to arrive, unless the socket is nonblocking, in which case a --1 is returned with the external variable errno set to EWOULDBLOCK.

> See also read(), send(), sendmsg(), sendto(), and socket().

## Return Values

> x | The number of bytes of data received and placed in buf.
> 0 | Successful completion.
> --1 | Error; errno is set to indicate the error.

## Errors

> You can set errno to the following values:
> [EBADF] | The socket descriptor is invalid.
> [ENOTSOCK] | The descriptor references a file, not a socket.
> [EPIPE] | You tried to write to a socket that is not open for reading by any process.
> [EWOULDBLOCK] | The NBIO (nonblocking) flag is set for the socket descriptor and the process delayed during the write operation.
> [EFAULT] | The data is specified to be received into a non-existent or protected part of the process address space.

# recvmsg()

> Receives bytes on a socket and places them into scattered buffers.

## Format

> ### #include <types.h>

> ### #include <socket.h>

> ### int recvmsg (int s, struct msghdr msg[], int flags);

## ARGUMENTS

> ### s

> A socket descriptor created with socket().

> ### msg

> See Section 5.8.5 for a description of the msghdr structure.

> ### flags

> A bit mask that can contain one or more MSG_OOB and MSG_PEEK flags. It is built by ORing the appropriate values together, as follows:

> Flag | Description
> --- | ---
> MSG_OOB | Allows you to receive out-of-band data.
> | If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_OOB flag is ignored. Use send(), sendmsg(), and sendto() routines to send out-of-band data.
> MSG_PEEK | Allows you to peek at the data that is next in line to be received without actually removing it from the system's buffers.

> If you include the UCX$INETDEF definition file, you can use the flags listed in the following table:

> Flag | Description
> --- | ---
> UCX$C_MSG_NBIO | Does not block the I/O operation if the transmit queue is full. Similar to using the $QIO IO$M_NOWAIT function.
> UCX$C_MSG_PURGE | Flushes data from the queue. Similar to using the $QIO IO$M_PURGE function.
> UCX$C_MSG_BLOCKALL | Blocks the completion of the operation until the buffer is filled completely or until the connection is closed. Similar to using to the $QIO IO$M_LOCKBUF modifier.

## DESCRIPTION

> You can use this routine with any socket, whether it is in a connected state or not. It receives data sent by a call to sendmsg(), send(), or sendto(). The message is scattered into several user buffers if such buffers are specified.

> To receive data, the socket need not be connected to another socket.

> When the iovec[iovcnt] array specifies more than one buffer, the input data is scattered into iovcnt buffers as specified by the members of the iovec array:

>     iov[0], iov[1], ..., iov[iovcnt]

> When a message is received, it is split among the buffers by filling the first buffer in the list, then the second, and so on, until either all of the buffers are full or there is no more data to be placed in the buffers.

> You can use the select() routine to determine when more data arrives.

> See also read(), send(), and socket().

## Return Values

> x | The number of bytes returned in the msg_iov buffers.
> 0 | Successful completion.
> --1 | Error; errno is set to indicate the error.

## Errors

> You can set errno to the following values:
> [EBADF] | The socket descriptor is invalid.
> [ENOTSOCK] | The descriptor references a file, not a socket.
> [EPIPE] | You tried to read a socket that is not open for reading by any process.
> [EWOULDBLOCK] | The NBIO (nonblocking) flag is set for the socket descriptor and the process is delayed during the read operation.
> [EINTR] | The receive is interrupted by delivery of a signal before any data is available for the receive.
> [EFAULT] | The data is specified to be received into a non-existent or protected part of the process address space.

# 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

> You can set errno to 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.

# 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 UCX$INETDEF definition file, you can also use:

> - UCX$C_MSG_DONTROUTE --- Sends the message directly without routing.
> - UCX$C_MSG_NBIO --- Completes the I/O operation and returns an error if a condition occurs that would cause the I/O operation to be blocked. Similar to using the $QIO IO$M_NOWAIT modifier.

## 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

> You can set errno to the following values:
> [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);

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

> 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 UCX$INETDEF definition file, you can also use:

> - UCX$C_MSG_DONTROUTE --- Sends the message directly without routing.
> - UCX$C_MSG_NBIO --- Completes the I/O operation and returns an error if a condition occurs that would cause the I/O operation to be blocked. Similar to using the $QIO IO$M_NOWAIT modifier.

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

> Previous | Next | Contents