# Compaq TCP/IP Services for OpenVMS
Sockets API and System Services Programming

Previous | Contents | Index

# 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 the `socket()` function that was connected to another socket using the `accept()` or `connect()` function.

> ### 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 MSG_OOB, the data is sent out of band. Data can be received before other pending data on the receiving socket if the receiver also specifies `MSG_OOB` in the flag argument of its `recv()` or `recvfrom()` call.

## Description

> You can use this function only on connected sockets. To send data on an unconnected socket, use the `sendmsg()` or `sendto()` function. The `send()` function passes data along to its connected peer, which can receive the data by using the `recv()` or `read()` function.

> 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()` function to determine when it is possible to send more data.

> Related Functions

> 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.
> ECONNRESET | A connection was forcibly closed by a peer.
> EDESTADDRREQ | The socket is not connection-oriented, and no peer address is set.
> EFAULT | The message argument is not in a readable or writable part of the user address space.
> EINTR | A signal interrupted the `send()` before any data was transmitted.
> EMSGSIZE | The message is too large to be sent all at once, as the socket requires.
> ENETDOWN | The local network connection is not operational.
> ENETUNREACH | The destination network is unreachable.
> ENOBUFS | The system has insufficient resources to complete the call.
> ENOTCONN | The socket is not connected or has not had the peer prespecified.
> ENOTSOCK | The socket descriptor is invalid.
> EOPNOTSUPP | The socket argument is associated with a socket that does not support one or more of the values set in flags.
> EWOULDBLOCK | The socket is marked nonblocking, and no space is available for the `send()` function.

# 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 the `socket()` function.

> ### msg

> A pointer to a `msghdr` structure containing the message to be sent. See Section 3.2.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. Data can be received before other pending data on the receiving socket if the receiver specifies a flag of `MSG_OOB` .

## Description

> You can use this function on any socket to send data to any named socket. The data in the `msg_iov` field of the `msghdr` 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()` function. When the `iovec` array specifies more than one buffer, the data is gathered from all specified buffers before being sent. See Section 3.2.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()` function blocks until buffer space becomes available. If the socket is defined as nonblocking, the `sendmsg()` function 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 an INADDR_BROADCAST address, the SO_BROADCAST socket 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 the `sendmsg()` function. All errors (except `EWOULDBLOCK` ) are detected locally. You can use the `select()` function to determine when it is possible to send more data.

> Related Functions

> 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

> ENOTSOCK | The socket descriptor is invalid.
> EFAULT | An invalid user space address is specified for a argument.
> EMSGSIZE | The socket requires that messages be sent atomically, but 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 the `socket()` function.

> ### msg

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

> ### len

> The length of the data pointed to by the msg argument.

> ### flags

> Can be either 0 or `MSG_OOB` . If it is `MSG_OOB` , the data is sent out of band. Data can be received before other pending data on the receiving socket if the receiver specifies `MSG_OOB` in its flag argument of its `recv()` , `recvfrom()` or `recvmsg()` call.

> ### to

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

> ### tolen

> The length of the address pointed to by the to argument.

## Description

> This function 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 the `read()` , `recv()` , `recvfrom()` , or `recvmsg()` function.

> If there is no space available to buffer the data being sent on the receiving end of the connection, the `sendto()` function blocks until buffer space becomes available. If the socket is defined as nonblocking, the `sendto()` function 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()` function 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()` function to determine when it is possible to send more data.

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

> Related Functions

> 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

> EAFNOSUPPORT | Addresses in the specified address family cannot be used with this socket.
> EBADF | The socket descriptor is invalid.
> ECONNRESET | A connection was forcibly closed by a peer.
> EDESTADDRREQ | You did not specify a destination address for the connectionless socket and no peer address is set.
> EFAULT | An invalid user space address is specified for a argument.
> EHOSTUNREACH | The destination host is unreachable.
> EINTR | A signal interrupted `sendto()` before any data was transmitted.
> EINVAL | The dest_len argument is not a valid size for the specified address family.
> EISCONN | The connection-oriented socket for which a destination address was specified is already connected.
> EMSGSIZE | The message is too large to be sent all at once, as the socket requires.
> ENETDOWN | The local network connection is not operational.
> ENETUNREACH | The destination network is unreachable.
> ENOBUFS | The system has insufficient to complete the call.
> ENOMEM | The system did not have sufficient memory to fulfill the request.
> ENOTCONN | The socket is connection-oriented but is not connected.
> ENOTSOCK | The socket descriptor is invalid.
> EOPNOTSUPP | The socket argument is associated with a socket that does not support one or more of the values set in flags.
> EPIPE | The socket is shut down for writing or is connection oriented, and the peer is closed or shut down for reading. In the latter case, if the socket is of type `SOCK_STREAM` , the `SIGPIPE` signal is generated to the calling process.
> EWOULDBLOCK | The socket is marked nonblocking, and no space is available for the `sendto()` function.

# setsockopt()

> Sets options on a socket.

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

## Format

> #include <types.h>

> #include <socket.h>

> int setsockopt ( int s, int level, int optname, char *optval, int optlen );

## Arguments

> ### s

> A socket descriptor created by the `socket()` function.

> ### level

> The protocol level for which the socket options are to be modified. It can 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

> Interpreted by the protocol specified in level. Options at each protocol level are documented with the protocol.

> Refer to:

> - Table A-1 for a list of socket options
> - Table A-2 for a list of TCP options
> - Table A-3 for a list of IP options

> ### optval

> Points to a buffer containing the arguments of the specified option.

> All socket-level options other than `SO_LINGER` should be nonzero if the option is to be enabled, or zero if it is to be disabled.

> `SO_LINGER` uses a `linger` structure argument defined in the SOCKET.H header 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 Section 3.2.4 for a description of the `linger` structure.

> If the socket promises the reliable delivery of data and `l_onoff` is nonzero, the system blocks 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 zero and a `close()` is issued, the system processes the close in a manner that allows the process to continue as soon as possible.

> ### optlen

> An integer specifying the size of the buffer pointed to by optval.

## Description

> This function manipulates options associated with a socket. Options can exist at multiple protocol levels. They are always present at the uppermost socket level.

> When manipulating socket options, specify the level at which the option resides and the name of the option. To manipulate options at the socket level, specify the value of level as SOL_SOCKET. To manipulate options at any other level, supply the protocol number of the appropriate protocol controlling the option. For example, to indicate that an option is to be interpreted by TCP, set the value for level argument to the protocol number ( `IPPROTO_TCP` ) of TCP. See the `IN.H` header file for the various `IPPROTO` values.

## Return Values

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

## Errors

> EACCES | The calling process does not have appropriate permissions.
> EBADF | The descriptor is invalid.
> EDOM | The send and receive timeout values are too large to fit in the timeout fields of the socket structure.
> EINVAL | The optlen argument is invalid.
> EISCONN | The socket is already connected; the specified option cannot be set when the socket is in the connected state.
> EFAULT | The optval argument is not in a readable part of the user address space.
> ENOBUFS | The system had insufficient resources to complete the call.
> ENOPROTOOPT | The option is unknown.
> ENOTSOCK | The socket descriptor is invalid.
> EFAULT | The optname argument is invalid.

# shutdown()

> Shuts down all or part of a bidirectional connection on a socket. This function does not allow further receives or 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 | Do not allow further calls to `recv()` on the socket.
> 1 | Do not allow further calls to `send()` on the socket.
> 2 | Do not allow further calls to both `send()` and `recv()` .

## Description

> This function allows communications on a socket to be shut down one piece at a time rather than all at once. Use the `shutdown()` function to create unidirectional connections rather than the normal bidirectional (full-duplex) connections.

> Related Functions

> 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.
> EINVAL | The how argument is invalid.
> ENOBUFS | The system has insufficient resources to complete the call.
> ENOTCONN | The specified socket is not connected.
> ENOTSOCK | The socket descriptor is invalid.

Previous | Next | Contents | Index