SYS_RECVMSG


Receive messages from a socket, and may be used to receive data on a socket whether or not it is connection-oriented.

Arguments:

1st Socket descriptor.
2nd Pointer to a properly initialized msghdr structure:
struc msghdr
{
.msg_name       rd 1
.msg_namelen    rd 1
.msg_iov        rd 1
.msg_iovlen     rd 1
.msg_control    rd 1
.msg_controllen rd 1
.msg_flags      rd 1
}

msghdr members:

msg_name
Pointer to a sockaddr structure specifying the source address if the socket is unconnected. It may be 0.
msg_namelen
Size of the structure pointed by msg_namelen
msg_iov
Pointer to an array of iovec structures describe scatter-gather locations, as discussed in sys_readv.
msg_iovlen
Number of elements in the iovec array.
msg_control
Pointer to a buffer for other protocol control related messages or miscellaneous ancillary data.
msg_controllen
Size of the buffer pointed by msg_control. Upon return this member will contain the length of the control message sequence.
msg_flags
This member is set on return of SYS_RECVMSG. It can contain several flags:
MSG_EOR Indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET).
MSG_TRUNC Indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied.
MSG_CTRUNC Indicates that some control data were discarded due to lack of space in the buffer for ancillary data.
MSG_OOB Is returned to indicate that expedited or out-of-band data were received
MSG_ERRQUEUE Indicates that no data was received but an extended error from the socket error queue.
3rd Flags:
MSG_OOB This flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols.
MSG_PEEK This flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data.
MSG_DONTROUTE *to be documented*
MSG_TRYHARD *to be documented*
MSG_CTRUNC *to be documented*
MSG_PROBE *to be documented*
MSG_TRUNC Return the real length of the packet, even when it was longer than the passed buffer. Only valid for packet sockets.
MSG_DONTWAIT Enables non-blocking operation; if the operation would block, -EAGAIN is returned (this can also be enabled using the O_NONBLOCK with the F_SETFL sys_fcntl).
MSG_EOR *to be documented*
MSG_WAITALL This flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned.
MSG_FIN *to be documented*
MSG_SYN *to be documented*
MSG_CONFIRM *to be documented*
MSG_RST *to be documented*
MSG_ERRQUEUE This flag specifies that queued errors should be received from the socket error queue. The error is passed in an ancillary message with a type dependent on the protocol (for IPv4 IP_RECVERR). The user should supply a buffer of sufficient size. See man 3 cmsg and man 7 ip for more information. The payload of the original packet that caused the error is passed as normal data via msg_iovec. The original destination address of the datagram that caused the error is supplied via msg_name.

For local errors, no address is passed (this can be checked with the cmsg_len member of the cmsghdr). For error receives, the MSG_ERRQUEUE is set in the msghdr. After an error has been passed, the pending socket error is regenerated based on the next queued error and will be passed on the next socket operation.

The error is supplied in a sock_extended_err structure:

struc sock_extended_err
{
.ee_errno  rd 1
.ee_origin rb 1
.ee_type   rb 1
.ee_code   rb 1
.ee_pad    rb 1
.ee_info   rd 1
.ee_data   rd 1
}

sock_extended_err members:

ee_errno
Error number. Curreently defined values are:
SO_EE_ORIGIN_NONE *to be documented*
SO_EE_ORIGIN_LOCAL *to be documented*
SO_EE_ORIGIN_ICMP *to be documented*
SO_EE_ORIGIN_ICMP6 *to be documented*
ee_origin
Origin code of where the error originated.
ee_type
This field is protocol specific. *to be documented*
ee_code
This field is protocol specific. *to be documented*
ee_pad
Padding.
ee_info
This field is protocol specific. *to be documented*
ee_data
This field is protocol specific. *to be documented*
MSG_NOSIGNAL *to be documented*
MSG_MORE *to be documented*

Return values

If the system call succeeds the return value is the number of bytes received.
If the system call fails the return value is one of the following errno values (These are some standard errors generated by the socket layer. Additional errors may be generated and returned from the underlying protocol modules):

-EAGAIN The socket is marked non-blocking and the receive operation would block, or a receive timeout had been set and the timeout expired before data was received.
-EBADF The 1st argument is an invalid descriptor.
-ECONNREFUSED A remote host refused to allow the network connection (typically because it is not running the requested service).
-EFAULT The receive buffer pointer(s) point outside the process's address space.
-EINTR The receive was interrupted by delivery of a signal before any data were available.
-EINVAL Invalid argument passed.
-ENOTCONN The socket is associated with a connection-oriented protocol and has not been connected (see SYS_CONNECT and SYS_ACCEPT).
-ENOTSOCK The 1st argument does not refer to a socket.
-ENOMEM Could not allocate memory.

Remarks

n/a

Compatibility

n/a