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