1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
1 |
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved |
2
by Francesco Paolo Lovergine
* Alligned to linux main manpages edition. |
2 |
.TH "RECVMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" |
1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
3 |
.\" recvmsg |
4 |
.SH NAME |
|
5 |
recvmsg \- receive a message from a socket
|
|
6 |
.SH SYNOPSIS |
|
7 |
.LP
|
|
8 |
\fB#include <sys/socket.h>
|
|
9 |
.br
|
|
10 |
.sp
|
|
11 |
ssize_t recvmsg(int\fP \fIsocket\fP\fB, struct msghdr *\fP\fImessage\fP\fB, |
|
12 |
int\fP \fIflags\fP\fB); |
|
13 |
.br
|
|
14 |
\fP
|
|
15 |
.SH DESCRIPTION |
|
16 |
.LP
|
|
17 |
The \fIrecvmsg\fP() function shall receive a message from a connection-mode |
|
18 |
or connectionless-mode socket. It is normally used |
|
19 |
with connectionless-mode sockets because it permits the application |
|
20 |
to retrieve the source address of received data. |
|
21 |
.LP
|
|
22 |
The \fIrecvmsg\fP() function takes the following arguments: |
|
23 |
.TP 7 |
|
24 |
\fIsocket\fP |
|
25 |
Specifies the socket file descriptor. |
|
26 |
.TP 7 |
|
27 |
\fImessage\fP |
|
28 |
Points to a \fBmsghdr\fP structure, containing both the buffer to |
|
29 |
store the source address and the buffers for the incoming |
|
30 |
message. The length and format of the address depend on the address |
|
31 |
family of the socket. The \fImsg_flags\fP member is ignored on |
|
32 |
input, but may contain meaningful values on output. |
|
33 |
.TP 7 |
|
34 |
\fIflags\fP |
|
35 |
Specifies the type of message reception. Values of this argument are |
|
36 |
formed by logically OR'ing zero or more of the following |
|
37 |
values: |
|
38 |
.TP 7 |
|
39 |
MSG_OOB |
|
40 |
.RS
|
|
41 |
Requests out-of-band data. The significance and semantics of out-of-band |
|
42 |
data are protocol-specific. |
|
43 |
.RE
|
|
44 |
.TP 7 |
|
45 |
MSG_PEEK |
|
46 |
.RS
|
|
47 |
Peeks at the incoming message. |
|
48 |
.RE
|
|
49 |
.TP 7 |
|
50 |
MSG_WAITALL |
|
51 |
.RS
|
|
52 |
On SOCK_STREAM sockets this requests that the function block until |
|
53 |
the full amount of data can be returned. The function may |
|
54 |
return the smaller amount of data if the socket is a message-based |
|
55 |
socket, if a signal is caught, if the connection is terminated, |
|
56 |
if MSG_PEEK was specified, or if an error is pending for the socket. |
|
57 |
.RE
|
|
58 |
.sp
|
|
59 |
.sp
|
|
60 |
.LP
|
|
61 |
The \fIrecvmsg\fP() function shall receive messages from unconnected |
|
62 |
or connected sockets and shall return the length of the |
|
63 |
message. |
|
64 |
.LP
|
|
65 |
The \fIrecvmsg\fP() function shall return the total length of the |
|
66 |
message. For message-based sockets, such as SOCK_DGRAM and |
|
67 |
SOCK_SEQPACKET, the entire message shall be read in a single operation. |
|
68 |
If a message is too long to fit in the supplied buffers, |
|
69 |
and MSG_PEEK is not set in the \fIflags\fP argument, the excess bytes |
|
70 |
shall be discarded, and MSG_TRUNC shall be set in the |
|
71 |
\fImsg_flags\fP member of the \fBmsghdr\fP structure. For stream-based |
|
72 |
sockets, such as SOCK_STREAM, message boundaries shall be |
|
73 |
ignored. In this case, data shall be returned to the user as soon |
|
74 |
as it becomes available, and no data shall be discarded. |
|
75 |
.LP
|
|
76 |
If the MSG_WAITALL flag is not set, data shall be returned only up |
|
77 |
to the end of the first message. |
|
78 |
.LP
|
|
79 |
If no messages are available at the socket and O_NONBLOCK is not set |
|
80 |
on the socket's file descriptor, \fIrecvmsg\fP() shall |
|
81 |
block until a message arrives. If no messages are available at the |
|
82 |
socket and O_NONBLOCK is set on the socket's file descriptor, |
|
83 |
the \fIrecvmsg\fP() function shall fail and set \fIerrno\fP to [EAGAIN] |
|
84 |
or [EWOULDBLOCK]. |
|
85 |
.LP
|
|
86 |
In the \fBmsghdr\fP structure, the \fImsg_name\fP and \fImsg_namelen\fP |
|
87 |
members specify the source address if the socket is |
|
88 |
unconnected. If the socket is connected, the \fImsg_name\fP and \fImsg_namelen\fP |
|
89 |
members shall be ignored. The \fImsg_name\fP |
|
90 |
member may be a null pointer if no names are desired or required. |
|
91 |
The \fImsg_iov\fP and \fImsg_iovlen\fP fields are used to |
|
92 |
specify where the received data shall be stored. \fImsg_iov\fP points |
|
93 |
to an array of \fBiovec\fP structures; \fImsg_iovlen\fP |
|
94 |
shall be set to the dimension of this array. In each \fBiovec\fP structure, |
|
95 |
the \fIiov_base\fP field specifies a storage area and |
|
96 |
the \fIiov_len\fP field gives its size in bytes. Each storage area |
|
97 |
indicated by \fImsg_iov\fP is filled with received data in |
|
98 |
turn until all of the received data is stored or all of the areas |
|
99 |
have been filled. |
|
100 |
.LP
|
|
101 |
Upon successful completion, the \fImsg_flags\fP member of the message |
|
102 |
header shall be the bitwise-inclusive OR of all of the |
|
103 |
following flags that indicate conditions detected for the received |
|
104 |
message: |
|
105 |
.TP 7 |
|
106 |
MSG_EOR |
|
107 |
End-of-record was received (if supported by the protocol). |
|
108 |
.TP 7 |
|
109 |
MSG_OOB |
|
110 |
Out-of-band data was received. |
|
111 |
.TP 7 |
|
112 |
MSG_TRUNC |
|
113 |
Normal data was truncated. |
|
114 |
.TP 7 |
|
115 |
MSG_CTRUNC |
|
116 |
Control data was truncated. |
|
117 |
.sp
|
|
118 |
.SH RETURN VALUE |
|
119 |
.LP
|
|
120 |
Upon successful completion, \fIrecvmsg\fP() shall return the length |
|
121 |
of the message in bytes. If no messages are available to be |
|
122 |
received and the peer has performed an orderly shutdown, \fIrecvmsg\fP() |
|
123 |
shall return 0. Otherwise, -1 shall be returned and |
|
124 |
\fIerrno\fP set to indicate the error. |
|
125 |
.SH ERRORS |
|
126 |
.LP
|
|
127 |
The \fIrecvmsg\fP() function shall fail if: |
|
128 |
.TP 7 |
|
2
by Francesco Paolo Lovergine
* Alligned to linux main manpages edition. |
129 |
.B EAGAIN \fRor\fP EWOULDBLOCK |
1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
130 |
.sp
|
131 |
The socket's file descriptor is marked O_NONBLOCK and no data is waiting |
|
132 |
to be received; or MSG_OOB is set and no out-of-band data |
|
133 |
is available and either the socket's file descriptor is marked O_NONBLOCK |
|
134 |
or the socket does not support blocking to await |
|
135 |
out-of-band data. |
|
136 |
.TP 7 |
|
137 |
.B EBADF |
|
138 |
The \fIsocket\fP argument is not a valid open file descriptor. |
|
139 |
.TP 7 |
|
140 |
.B ECONNRESET |
|
141 |
A connection was forcibly closed by a peer. |
|
142 |
.TP 7 |
|
143 |
.B EINTR |
|
144 |
This function was interrupted by a signal before any data was available. |
|
145 |
.TP 7 |
|
146 |
.B EINVAL |
|
147 |
The sum of the \fIiov_len\fP values overflows a \fBssize_t\fP, or |
|
148 |
the MSG_OOB flag is set and no out-of-band data is |
|
149 |
available. |
|
150 |
.TP 7 |
|
151 |
.B EMSGSIZE |
|
152 |
The \fImsg_iovlen\fP member of the \fBmsghdr\fP structure pointed |
|
153 |
to by \fImessage\fP is less than or equal to 0, or is |
|
154 |
greater than {IOV_MAX}. |
|
155 |
.TP 7 |
|
156 |
.B ENOTCONN |
|
157 |
A receive is attempted on a connection-mode socket that is not connected. |
|
158 |
.TP 7 |
|
159 |
.B ENOTSOCK |
|
160 |
The \fIsocket\fP argument does not refer to a socket. |
|
161 |
.TP 7 |
|
162 |
.B EOPNOTSUPP |
|
163 |
The specified flags are not supported for this socket type. |
|
164 |
.TP 7 |
|
165 |
.B ETIMEDOUT |
|
166 |
The connection timed out during connection establishment, or due to |
|
167 |
a transmission timeout on active connection. |
|
168 |
.sp
|
|
169 |
.LP
|
|
170 |
The \fIrecvmsg\fP() function may fail if: |
|
171 |
.TP 7 |
|
172 |
.B EIO |
|
173 |
An I/O error occurred while reading from or writing to the file system. |
|
174 |
.TP 7 |
|
175 |
.B ENOBUFS |
|
176 |
Insufficient resources were available in the system to perform the |
|
177 |
operation. |
|
178 |
.TP 7 |
|
179 |
.B ENOMEM |
|
180 |
Insufficient memory was available to fulfill the request. |
|
181 |
.sp
|
|
182 |
.LP
|
|
183 |
\fIThe following sections are informative.\fP |
|
184 |
.SH EXAMPLES |
|
185 |
.LP
|
|
186 |
None. |
|
187 |
.SH APPLICATION USAGE |
|
188 |
.LP
|
|
189 |
The \fIselect\fP() and \fIpoll\fP() functions can |
|
190 |
be used to determine when data is available to be received. |
|
191 |
.SH RATIONALE |
|
192 |
.LP
|
|
193 |
None. |
|
194 |
.SH FUTURE DIRECTIONS |
|
195 |
.LP
|
|
196 |
None. |
|
197 |
.SH SEE ALSO |
|
198 |
.LP
|
|
199 |
\fIpoll\fP() , \fIrecv\fP() , \fIrecvfrom\fP() , |
|
200 |
\fIselect\fP() , \fIsend\fP() , \fIsendmsg\fP() , |
|
201 |
\fIsendto\fP() , \fIshutdown\fP() , \fIsocket\fP() , the Base Definitions |
|
202 |
volume of IEEE\ Std\ 1003.1-2001, \fI<sys/socket.h>\fP |
|
203 |
.SH COPYRIGHT |
|
204 |
Portions of this text are reprinted and reproduced in electronic form |
|
205 |
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology |
|
206 |
-- Portable Operating System Interface (POSIX), The Open Group Base |
|
207 |
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of |
|
208 |
Electrical and Electronics Engineers, Inc and The Open Group. In the |
|
209 |
event of any discrepancy between this version and the original IEEE and |
|
210 |
The Open Group Standard, the original IEEE and The Open Group Standard |
|
211 |
is the referee document. The original Standard can be obtained online at |
|
212 |
http://www.opengroup.org/unix/online.html . |