1RECVMSG(3P)                POSIX Programmer's Manual               RECVMSG(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       recvmsg — receive a message from a socket
14

SYNOPSIS

16       #include <sys/socket.h>
17
18       ssize_t recvmsg(int socket, struct msghdr *message, int flags);
19

DESCRIPTION

21       The recvmsg() function shall receive a message from  a  connection-mode
22       or connectionless-mode socket. It is normally used with connectionless-
23       mode sockets because it permits the application to retrieve the  source
24       address of received data.
25
26       The recvmsg() function takes the following arguments:
27
28       socket      Specifies the socket file descriptor.
29
30       message     Points to a msghdr structure, containing both the buffer to
31                   store the source address and the buffers for  the  incoming
32                   message. The length and format of the address depend on the
33                   address family of  the  socket.  The  msg_flags  member  is
34                   ignored on input, but may contain meaningful values on out‐
35                   put.
36
37       flags       Specifies the type of message  reception.  Values  of  this
38                   argument are formed by logically OR'ing zero or more of the
39                   following values:
40
41                   MSG_OOB     Requests out-of-band data. The significance and
42                               semantics of out-of-band data are protocol-spe‐
43                               cific.
44
45                   MSG_PEEK    Peeks at the incoming message.
46
47                   MSG_WAITALL On SOCK_STREAM sockets this requests  that  the
48                               function  block  until  the full amount of data
49                               can be returned. The function  may  return  the
50                               smaller  amount of data if the socket is a mes‐
51                               sage-based socket, if a signal  is  caught,  if
52                               the  connection  is terminated, if MSG_PEEK was
53                               specified, or if an error is  pending  for  the
54                               socket.
55
56       The  recvmsg() function shall receive messages from unconnected or con‐
57       nected sockets and shall return the length of the message.
58
59       The recvmsg() function shall return the total length  of  the  message.
60       For  message-based  sockets, such as SOCK_DGRAM and SOCK_SEQPACKET, the
61       entire message shall be read in a single operation. If a message is too
62       long  to  fit  in  the supplied buffers, and MSG_PEEK is not set in the
63       flags argument, the excess bytes  shall  be  discarded,  and  MSG_TRUNC
64       shall  be  set  in  the  msg_flags  member of the msghdr structure. For
65       stream-based sockets, such as SOCK_STREAM, message boundaries shall  be
66       ignored. In this case, data shall be returned to the user as soon as it
67       becomes available, and no data shall be discarded.
68
69       If the MSG_WAITALL flag is not set, data shall be returned only  up  to
70       the end of the first message.
71
72       If no messages are available at the socket and O_NONBLOCK is not set on
73       the socket's file descriptor, recvmsg() shall  block  until  a  message
74       arrives.  If  no messages are available at the socket and O_NONBLOCK is
75       set on the socket's file descriptor, the recvmsg() function shall  fail
76       and set errno to [EAGAIN] or [EWOULDBLOCK].
77
78       In  the  msghdr structure, the msg_name member may be a null pointer if
79       the source address is not required.  Otherwise, if the socket is uncon‐
80       nected, the msg_name member points to a sockaddr structure in which the
81       source address is to be stored, and the  msg_namelen  member  on  input
82       specifies  the  length of the supplied sockaddr structure and on output
83       specifies the length of the stored address.  If the  actual  length  of
84       the  address is greater than the length of the supplied sockaddr struc‐
85       ture, the stored address shall be truncated.  If  the  socket  is  con‐
86       nected,  the  msg_name  and  msg_namelen  members shall be ignored. The
87       msg_iov and msg_iovlen fields are used to specify  where  the  received
88       data  shall  be stored.  The msg_iov member points to an array of iovec
89       structures; the msg_iovlen member shall be set to the dimension of this
90       array.  In each iovec structure, the iov_base field specifies a storage
91       area and the iov_len field gives its size in bytes. Each  storage  area
92       indicated  by msg_iov is filled with received data in turn until all of
93       the received data is stored or all of the areas have been filled.
94
95       Upon successful completion, the msg_flags member of the message  header
96       shall  be  the  bitwise-inclusive OR of all of the following flags that
97       indicate conditions detected for the received message:
98
99       MSG_EOR     End-of-record was received (if supported by the protocol).
100
101       MSG_OOB     Out-of-band data was received.
102
103       MSG_TRUNC   Normal data was truncated.
104
105       MSG_CTRUNC  Control data was truncated.
106

RETURN VALUE

108       Upon successful completion, recvmsg() shall return the  length  of  the
109       message  in  bytes. If no messages are available to be received and the
110       peer has performed an orderly shutdown, recvmsg() shall return 0.  Oth‐
111       erwise, −1 shall be returned and errno set to indicate the error.
112

ERRORS

114       The recvmsg() function shall fail if:
115
116       EAGAIN or EWOULDBLOCK
117              The socket's file descriptor is marked O_NONBLOCK and no data is
118              waiting to be received; or MSG_OOB is  set  and  no  out-of-band
119              data  is  available  and  either the socket's file descriptor is
120              marked O_NONBLOCK or the socket does  not  support  blocking  to
121              await out-of-band data.
122
123       EBADF  The socket argument is not a valid open file descriptor.
124
125       ECONNRESET
126              A connection was forcibly closed by a peer.
127
128       EINTR  This  function  was  interrupted by a signal before any data was
129              available.
130
131       EINVAL The sum of the  iov_len  values  overflows  a  ssize_t,  or  the
132              MSG_OOB flag is set and no out-of-band data is available.
133
134       EMSGSIZE
135              The msg_iovlen member of the msghdr structure pointed to by mes‐
136              sage is less than or equal to 0, or is greater than {IOV_MAX}.
137
138       ENOTCONN
139              A receive is attempted on a connection-mode socket that  is  not
140              connected.
141
142       ENOTSOCK
143              The socket argument does not refer to a socket.
144
145       EOPNOTSUPP
146              The specified flags are not supported for this socket type.
147
148       ETIMEDOUT
149              The connection timed out during connection establishment, or due
150              to a transmission timeout on active connection.
151
152       The recvmsg() function may fail if:
153
154       EIO    An I/O error occurred while reading from or writing to the  file
155              system.
156
157       ENOBUFS
158              Insufficient  resources  were available in the system to perform
159              the operation.
160
161       ENOMEM Insufficient memory was available to fulfill the request.
162
163       The following sections are informative.
164

EXAMPLES

166       None.
167

APPLICATION USAGE

169       The select() and poll() functions can be used to determine when data is
170       available to be received.
171

RATIONALE

173       None.
174

FUTURE DIRECTIONS

176       None.
177

SEE ALSO

179       poll(),  pselect(),  recv(),  recvfrom(),  send(), sendmsg(), sendto(),
180       shutdown(), socket()
181
182       The Base Definitions volume of POSIX.1‐2008, <sys_socket.h>
183
185       Portions of this text are reprinted and reproduced in  electronic  form
186       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
187       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
188       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
189       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
190       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
191       event of any discrepancy between this version and the original IEEE and
192       The  Open Group Standard, the original IEEE and The Open Group Standard
193       is the referee document. The original Standard can be  obtained  online
194       at http://www.unix.org/online.html .
195
196       Any  typographical  or  formatting  errors that appear in this page are
197       most likely to have been introduced during the conversion of the source
198       files  to  man page format. To report such errors, see https://www.ker
199       nel.org/doc/man-pages/reporting_bugs.html .
200
201
202
203IEEE/The Open Group                  2013                          RECVMSG(3P)
Impressum