| United States |
|
|
|
| Previous | Contents | Index |
Sends gathered bytes through a socket to any other socket.
#include <socket.h>Routine Variants This socket routine has a variant named __bsd44_sendmsg . Enabled by defining _sockaddr_len , this variant implements 4.4BSD-compatible semantics. See Section A.7 for more information.int sendmsg (int s, struct msghdr msg[], int flags);
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 .
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.
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.
Sends bytes through a socket to any other socket.
#include <socket.h>Routine Variants This socket routine has a variant named __bsd44_sendto . Enabled by defining _sockaddr_len , this variant implements 4.4BSD-compatible semantics. See Section A.7 for more information.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)
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.
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.
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.
Opens and rewinds the network host database file.
#include <netdb.h>void sethostent (int stay_open);
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.
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.
Opens and rewinds the networks database file.
#include <netdb.h>void setnetent (int stay_open);
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.
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.
Opens, rewinds, or closes the protocols database file.
#include <netdb.h>void setprotoent (int stay_open);
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.
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.
1 Indicates success. 0 Indicates an error; unable to open the protocols database file.
If the setprotoent routine fails, the error is further specified in the global errno .
Opens and rewinds the network services database file.
#include <netdb.h>void setservent (int stay_open);
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 .
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.
Sets options on a socket.
#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)
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.
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.
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.
Shuts down all or part of a bidirectional connection on a socket. It can disallow further receives, further sends, or both.
#include <socket.h>int shutdown (int s, int how);
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 .
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.
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.
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.
#include <socket.h>int socket (int af, int type, int protocol);
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.
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.
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.
| Previous | Next | Contents | Index |
|
