recvmsg.3p (8048B)
- '\" et
- .TH RECVMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- recvmsg
- \(em receive a message from a socket
- .SH SYNOPSIS
- .LP
- .nf
- #include <sys/socket.h>
- .P
- ssize_t recvmsg(int \fIsocket\fP, struct msghdr *\fImessage\fP, int \fIflags\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIrecvmsg\fR()
- function shall receive a message from a connection-mode or
- connectionless-mode socket. It is normally used with
- connectionless-mode sockets because it permits the application to
- retrieve the source address of received data.
- .P
- The
- \fIrecvmsg\fR()
- function takes the following arguments:
- .IP "\fIsocket\fR" 12
- Specifies the socket file descriptor.
- .IP "\fImessage\fR" 12
- Points to a
- .BR msghdr
- structure, containing both the buffer to store the source address and
- the buffers for the incoming message. The length and format of the
- address depend on the address family of the socket. The
- .IR msg_flags
- member is ignored on input, but may contain meaningful values on
- output.
- .IP "\fIflags\fR" 12
- Specifies the type of message reception. Values of this argument are
- formed by logically OR'ing zero or more of the following values:
- .RS 12
- .IP MSG_OOB 12
- Requests out-of-band data. The significance and semantics of
- out-of-band data are protocol-specific.
- .IP MSG_PEEK 12
- Peeks at the incoming message.
- .IP MSG_WAITALL 12
- On SOCK_STREAM sockets this requests that the function block until the
- full amount of data can be returned. The function may return the
- smaller amount of data if the socket is a message-based socket, if a
- signal is caught, if the connection is terminated, if MSG_PEEK was
- specified, or if an error is pending for the socket.
- .RE
- .P
- The
- \fIrecvmsg\fR()
- function shall receive messages from unconnected or connected
- sockets and shall return the length of the message.
- .P
- The
- \fIrecvmsg\fR()
- function shall return the total length of the message. For
- message-based sockets, such as SOCK_DGRAM and SOCK_SEQPACKET, the
- entire message shall be read in a single operation. If a message is too
- long to fit in the supplied buffers, and MSG_PEEK is not set in the
- .IR flags
- argument, the excess bytes shall be discarded, and MSG_TRUNC shall be
- set in the
- .IR msg_flags
- member of the
- .BR msghdr
- structure. For stream-based sockets, such as SOCK_STREAM, message
- boundaries shall be ignored. In this case, data shall be returned to
- the user as soon as it becomes available, and no data shall be
- discarded.
- .P
- If the MSG_WAITALL flag is not set, data shall be returned only up to
- the end of the first message.
- .P
- If no messages are available at the socket and O_NONBLOCK is not set on
- the socket's file descriptor,
- \fIrecvmsg\fR()
- shall block until a message arrives. If no messages are available at
- the socket and O_NONBLOCK is set on the socket's file descriptor, the
- \fIrecvmsg\fR()
- function shall fail and set
- .IR errno
- to
- .BR [EAGAIN]
- or
- .BR [EWOULDBLOCK] .
- .P
- In the
- .BR msghdr
- structure, the
- .IR msg_name
- member may be a null pointer if the source address is not required.
- Otherwise, if the socket is unconnected, the
- .IR msg_name
- member points to a
- .BR sockaddr
- structure in which the source address is to be stored, and the
- .IR msg_namelen
- member on input specifies the length of the supplied
- .BR sockaddr
- structure and on output specifies the length of the stored address.
- If the actual length of the address is greater than the length of the
- supplied
- .BR sockaddr
- structure, the stored address shall be truncated. If the socket is
- connected, the
- .IR msg_name
- and
- .IR msg_namelen
- members shall be ignored. The
- .IR msg_iov
- and
- .IR msg_iovlen
- fields are used to specify where the received data shall be stored.
- The
- .IR msg_iov
- member points to an array of
- .BR iovec
- structures; the
- .IR msg_iovlen
- member shall be set to the dimension of this array. In each
- .BR iovec
- structure, the
- .IR iov_base
- field specifies a storage area and the
- .IR iov_len
- field gives its size in bytes. Each storage area indicated by
- .IR msg_iov
- is filled with received data in turn until all of the received data is
- stored or all of the areas have been filled.
- .P
- Upon successful completion, the
- .IR msg_flags
- member of the message header shall be the bitwise-inclusive OR of all
- of the following flags that indicate conditions detected for the
- received message:
- .IP MSG_EOR 12
- End-of-record was received (if supported by the protocol).
- .IP MSG_OOB 12
- Out-of-band data was received.
- .IP MSG_TRUNC 12
- Normal data was truncated.
- .IP MSG_CTRUNC 12
- Control data was truncated.
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIrecvmsg\fR()
- shall return the length of the message in bytes. If no messages are
- available to be received and the peer has performed an orderly
- shutdown,
- \fIrecvmsg\fR()
- shall return 0. Otherwise, \-1 shall be returned and
- .IR errno
- set to indicate the error.
- .SH ERRORS
- The
- \fIrecvmsg\fR()
- function shall fail if:
- .TP
- .BR EAGAIN " or " EWOULDBLOCK
- .br
- The socket's file descriptor is marked O_NONBLOCK and no data is
- waiting to be received; or MSG_OOB is set and no out-of-band data is
- available and either the socket's file descriptor is marked O_NONBLOCK
- or the socket does not support blocking to await out-of-band data.
- .TP
- .BR EBADF
- The
- .IR socket
- argument is not a valid open file descriptor.
- .TP
- .BR ECONNRESET
- A connection was forcibly closed by a peer.
- .TP
- .BR EINTR
- This function was interrupted by a signal before any data was
- available.
- .TP
- .BR EINVAL
- The sum of the
- .IR iov_len
- values overflows a
- .BR ssize_t ,
- or the MSG_OOB flag is set and no out-of-band data is available.
- .TP
- .BR EMSGSIZE
- The
- .IR msg_iovlen
- member of the
- .BR msghdr
- structure pointed to by
- .IR message
- is less than or equal to 0, or is greater than
- {IOV_MAX}.
- .TP
- .BR ENOTCONN
- A receive is attempted on a connection-mode socket that is not
- connected.
- .TP
- .BR ENOTSOCK
- The
- .IR socket
- argument does not refer to a socket.
- .TP
- .BR EOPNOTSUPP
- The specified flags are not supported for this socket type.
- .TP
- .BR ETIMEDOUT
- The connection timed out during connection establishment, or due to a
- transmission timeout on active connection.
- .P
- The
- \fIrecvmsg\fR()
- function may fail if:
- .TP
- .BR EIO
- An I/O error occurred while reading from or writing to the file
- system.
- .TP
- .BR ENOBUFS
- Insufficient resources were available in the system to perform the
- operation.
- .TP
- .BR ENOMEM
- Insufficient memory was available to fulfill the request.
- .LP
- .IR "The following sections are informative."
- .SH "EXAMPLES"
- None.
- .SH "APPLICATION USAGE"
- The
- \fIselect\fR()
- and
- \fIpoll\fR()
- functions can be used to determine when data is available to be
- received.
- .SH "RATIONALE"
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIpoll\fR\^(\|)",
- .IR "\fIpselect\fR\^(\|)",
- .IR "\fIrecv\fR\^(\|)",
- .IR "\fIrecvfrom\fR\^(\|)",
- .IR "\fIsend\fR\^(\|)",
- .IR "\fIsendmsg\fR\^(\|)",
- .IR "\fIsendto\fR\^(\|)",
- .IR "\fIshutdown\fR\^(\|)",
- .IR "\fIsocket\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<sys_socket.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .