#include <sys.types.h>
#include <sys.socket.h>
#include <sys.uio.h>
Kernighan-Ritchie-C:
int recvmsg(s, msg, flags);
int s;
flags
struct msghdr *msg;
ANSI-C:
int recvmsg(int s, struct msghdr* msg, int flags);
Description
The recvmsg() function is supported in the AF_INET, AF_INET6 and AF_ISO address families and provides the following functionality depending on the parameterization (msg parameter):
recvmsg() can be used to receive user data from the partner socket on socket s.
Only in AF_ISO: recvmsg() can be used to read connection data from socket s.
A pointer to an object of the data type struct msghdr must be specified as the current parameter for msg. The desired functionality for recvmsg() is selected via the component msg->msg_control (data type caddr_t or char *)
If msg->msg_control is the null pointer, user data is received.
Only in AF_ISO: If msg->msg_control is not the null pointer, msg->msg_control is interpreted as a pointer to a storage area with the structure cmsghdr, and connection data is read from the socket.
Due to the internal socket status for s, recvmsg() selects the connection data type (CONN_DATA, CFRM_DATA or DISC_DATA) and writes the relevant data in the data area of the msg->msg_control pointer (see msghdr and cmsghdr structures on the next page).
TPOPT_REDI_DATA and TPOPT_REDI_BDOK are provided for the handoff procedure. In this case, the structure cmsg_redhdr is required. Refer to chapter "Extended SOCKETS(BS2000) functions" for a description.
msghdr structure
The msghdr structure is declared in <sys.socket.h> as follows:
struct msghdr {
caddr_t msg_name; /* destination address */
int msg_namelen; /* length of the destination address */
struct iovec *msg_iov; /* scatter/gather fields */
int msg_iovlen; /* number of elements in msg_iov */
caddr_t msg_control; /* auxiliary data*/
int msg_controllen; /* length of the buffer for */
/* auxiliary data */
int msg_flags; /* flag for received message */
};
struct msghdr *msg;
msg->msg_name and msg->msg_namelen can return different information in connectionless mode:
1: The flag MSG_ERRQUEUE is set and an error packet is received: Destination address and its length
2: The flag MSG_ERRQUEUE is set and no error packet is received: No information is written to both fields and recvmsg() returns with -1
3: The flag MSG_ERRQUEUE is not set and an error packet is received: No information is written to both fields
4: The flag MSG_ERRQUEUE is not set and no error packet is received: Address of the sender of the just received packet and its length
If msg_name is not null then the content is interpreted as the pointer to a buffer in which the partner’s address information is entered. msg_namelen specifies the length of this buffer. If the socket is “non-connected” then the sender’s address information is stored using a sockaddr structure and msg_namelen contains the length of this structure.
If these parameters are not to be used, msg_name should have the value of the null pointer and msg_namelen the value 0.
msg->msg_iov is a pointer to a storage area with objects of the type struct iovec. msg->msg_iovlen indicates the number of elements (max. 16) in this storage area.msg->msg_control is a pointer to an object of the type struct cmsghdr in which recvmsg() enters the expected connection data.
msg->msg_controllen indicates the length of *msg->msg_control.
msg->msg_flags = MSG_EOR indicates the end of a record (only AF_ISO).
iovec structure
The iovec structure is declared in <sys.uio.h> as follows:
struct iovec{
caddr_t iov_base; /* buffer for auxiliary data */
int iov_len; /* buffer length */
};
cmsghdr structure
The cmsghdr structure is declared in <sys.socket.h> as follows:
struct cmsghdr {
u_int cmsg_len; /* number of data bytes incl. header */
int cmsg_level; /* generating protocol */
int cmsg_type; /* protocol-specific type */
/* followed by u_char cmsg_data[] */
};
struct cmsghdr *cmsg;
cmsg->cmsg_len contains the length of the storage area of *msg->msg_control.
cmsg->cmsg_level describes the type of information included in the data area by stating a specific protocol level.
cmsg->cmsg_type gives additional information about the contents of the data area with an options value.
Connection data and the final null byte are entered in the data portion of the cmsghdr. It can be accessed with the CMSG_DATA macro.
The flags Parameter currently supports the following flags:
- MSG_PEEK (only for datagram sockets):
MSG_PEEK allows the data to be read without it being deleted at the source. This means that a repeat read operation is necessary.
- MSG_ERRQUEUE (only for datagram and raw sockets):
MSQ_ERRQUEUE provides more detailed information in case there is an error. The data is written into msg_iov and the error protocol into msg_control.
Return value
>0:
If successful:
Number of bytes of the received user data
=0:
only AF_ISO
for connection data (CONN_DATA, CFRM_DATA, DISC_DATA)AF_INET, AF_INET6
No more data can be received. The partner has closed his connection correctly (only for sockets of the type SOCK_STREAM).Sockets of type SOCK_DGRAM receive a data packet with the length 0 or the data is deleted by the transport system for a timeout.
-1:
If errors occur. errno is set to indicate the error.
Errors indicated by errno
EBADF
The s parameter is not a valid descriptor.
ECONNRESET
The connection to the partner was interrupted.
EFAULT
The flag MSG_ERRQUEUE was set and no error package is available
EINVAL
A parameter specifies an invalid value.
ENETDOWN
The connection to the network is down.
ENOTCONN
No connection exists for the socket.
EOPNOTSUPP
The function call includes illegal attributes
EPIPE
The partner has interrupted the connection.
EWOULDBLOCK
The socket is marked as non-blocking, and the requested operation would block.