lib/libc/sys/recv.2

   1 .\" Copyright (c) 1983, 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)recv.2      8.3 (Berkeley) 2/21/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd September 12, 2012
  32 .Dt RECV 2
  33 .Os
  34 .Sh NAME
  35 .Nm recv ,
  36 .Nm recvfrom ,
  37 .Nm recvmsg
  38 .Nd receive a message from a socket
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/types.h
  43 .In sys/socket.h
  44 .Ft ssize_t
  45 .Fn recv "int s" "void *buf" "size_t len" "int flags"
  46 .Ft ssize_t
  47 .Fn recvfrom "int s" "void * restrict buf" "size_t len" "int flags" "struct sockaddr * restrict from" "socklen_t * restrict fromlen"
  48 .Ft ssize_t
  49 .Fn recvmsg "int s" "struct msghdr *msg" "int flags"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn recvfrom
  53 and
  54 .Fn recvmsg
  55 system calls
  56 are used to receive messages from a socket,
  57 and may be used to receive data on a socket whether or not
  58 it is connection-oriented.
  59 .Pp
  60 If
  61 .Fa from
  62 is not a null pointer
  63 and the socket is not connection-oriented,
  64 the source address of the message is filled in.
  65 The
  66 .Fa fromlen
  67 argument
  68 is a value-result argument, initialized to the size of
  69 the buffer associated with
  70 .Fa from ,
  71 and modified on return to indicate the actual size of the
  72 address stored there.
  73 .Pp
  74 The
  75 .Fn recv
  76 function is normally used only on a
  77 .Em connected
  78 socket (see
  79 .Xr connect 2 )
  80 and is identical to
  81 .Fn recvfrom
  82 with a
  83 null pointer passed as its
  84 .Fa from
  85 argument.
  86 .Pp
  87 All three routines return the length of the message on successful
  88 completion.
  89 If a message is too long to fit in the supplied buffer,
  90 excess bytes may be discarded depending on the type of socket
  91 the message is received from (see
  92 .Xr socket 2 ) .
  93 .Pp
  94 If no messages are available at the socket, the
  95 receive call waits for a message to arrive, unless
  96 the socket is non-blocking (see
  97 .Xr fcntl 2 )
  98 in which case the value
  99 \-1 is returned and the global variable
 100 .Va errno
 101 is set to
 102 .Er EAGAIN .
 103 The receive calls normally return any data available,
 104 up to the requested amount,
 105 rather than waiting for receipt of the full amount requested;
 106 this behavior is affected by the socket-level options
 107 .Dv SO_RCVLOWAT
 108 and
 109 .Dv SO_RCVTIMEO
 110 described in
 111 .Xr getsockopt 2 .
 112 .Pp
 113 The
 114 .Xr select 2
 115 system call may be used to determine when more data arrives.
 116 .Pp
 117 The
 118 .Fa flags
 119 argument to a
 120 .Fn recv
 121 function is formed by
 122 .Em or Ap ing
 123 one or more of the values:
 124 .Bl -column ".Dv MSG_DONTWAIT" -offset indent
 125 .It Dv MSG_OOB Ta process out-of-band data
 126 .It Dv MSG_PEEK Ta peek at incoming message
 127 .It Dv MSG_WAITALL Ta wait for full request or error
 128 .It Dv MSG_DONTWAIT Ta do not block
 129 .El
 130 .Pp
 131 The
 132 .Dv MSG_OOB
 133 flag requests receipt of out-of-band data
 134 that would not be received in the normal data stream.
 135 Some protocols place expedited data at the head of the normal
 136 data queue, and thus this flag cannot be used with such protocols.
 137 The
 138 .Dv MSG_PEEK
 139 flag causes the receive operation to return data
 140 from the beginning of the receive queue without removing that
 141 data from the queue.
 142 Thus, a subsequent receive call will return the same data.
 143 The
 144 .Dv MSG_WAITALL
 145 flag requests that the operation block until
 146 the full request is satisfied.
 147 However, the call may still return less data than requested
 148 if a signal is caught, an error or disconnect occurs,
 149 or the next data to be received is of a different type than that returned.
 150 The
 151 .Dv MSG_DONTWAIT
 152 flag requests the call to return when it would block otherwise.
 153 If no data is available,
 154 .Va errno
 155 is set to
 156 .Er EAGAIN .
 157 This flag is not available in strict
 158 .Tn ANSI
 159 or C99 compilation mode.
 160 .Pp
 161 The
 162 .Fn recvmsg
 163 system call uses a
 164 .Fa msghdr
 165 structure to minimize the number of directly supplied arguments.
 166 This structure has the following form, as defined in
 167 .In sys/socket.h :
 168 .Bd -literal
 169 struct msghdr {
 170         void            *msg_name;      /* optional address */
 171         socklen_t        msg_namelen;   /* size of address */
 172         struct iovec    *msg_iov;       /* scatter/gather array */
 173         int              msg_iovlen;    /* # elements in msg_iov */
 174         void            *msg_control;   /* ancillary data, see below */
 175         socklen_t        msg_controllen;/* ancillary data buffer len */
 176         int              msg_flags;     /* flags on received message */
 177 };
 178 .Ed
 179 .Pp
 180 Here
 181 .Fa msg_name
 182 and
 183 .Fa msg_namelen
 184 specify the destination address if the socket is unconnected;
 185 .Fa msg_name
 186 may be given as a null pointer if no names are desired or required.
 187 The
 188 .Fa msg_iov
 189 and
 190 .Fa msg_iovlen
 191 arguments
 192 describe scatter gather locations, as discussed in
 193 .Xr read 2 .
 194 The
 195 .Fa msg_control
 196 argument,
 197 which has length
 198 .Fa msg_controllen ,
 199 points to a buffer for other protocol control related messages
 200 or other miscellaneous ancillary data.
 201 The messages are of the form:
 202 .Bd -literal
 203 struct cmsghdr {
 204         socklen_t  cmsg_len;    /* data byte count, including hdr */
 205         int        cmsg_level;  /* originating protocol */
 206         int        cmsg_type;   /* protocol-specific type */
 207 /* followed by
 208         u_char     cmsg_data[]; */
 209 };
 210 .Ed
 211 .Pp
 212 As an example, one could use this to learn of changes in the data-stream
 213 in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
 214 a
 215 .Fn recvmsg
 216 with no data buffer provided immediately after an
 217 .Fn accept
 218 system call.
 219 .Pp
 220 Open file descriptors are now passed as ancillary data for
 221 .Dv AF_UNIX
 222 domain sockets, with
 223 .Fa cmsg_level
 224 set to
 225 .Dv SOL_SOCKET
 226 and
 227 .Fa cmsg_type
 228 set to
 229 .Dv SCM_RIGHTS .
 230 .Pp
 231 Process credentials can also be passed as ancillary data for
 232 .Dv AF_UNIX
 233 domain sockets using a
 234 .Fa cmsg_type
 235 of
 236 .Dv SCM_CREDS .
 237 In this case,
 238 .Fa cmsg_data
 239 should be a structure of type
 240 .Fa cmsgcred ,
 241 which is defined in
 242 .In sys/socket.h
 243 as follows:
 244 .Bd -literal
 245 struct cmsgcred {
 246         pid_t   cmcred_pid;             /* PID of sending process */
 247         uid_t   cmcred_uid;             /* real UID of sending process */
 248         uid_t   cmcred_euid;            /* effective UID of sending process */
 249         gid_t   cmcred_gid;             /* real GID of sending process */
 250         short   cmcred_ngroups;         /* number or groups */
 251         gid_t   cmcred_groups[CMGROUP_MAX];     /* groups */
 252 };
 253 .Ed
 254 .Pp
 255 If a sender supplies ancillary data with enough space for the above struct
 256 tagged as
 257 .Dv SCM_CREDS
 258 control message type to the
 259 .Fn sendmsg
 260 system call, then kernel will fill in the credential information of the
 261 sending process and deliver it to the receiver.
 262 Since receiver usually has no control over a sender, this method of retrieving
 263 credential information isn't reliable.
 264 For reliable retrieval of remote side credentials it is advised to use the
 265 .Dv LOCAL_CREDS
 266 socket option on the receiving socket.
 267 See
 268 .Xr unix 4
 269 for details.
 270 .Pp
 271 The
 272 .Fa msg_flags
 273 field is set on return according to the message received.
 274 .Dv MSG_EOR
 275 indicates end-of-record;
 276 the data returned completed a record (generally used with sockets of type
 277 .Dv SOCK_SEQPACKET ) .
 278 .Dv MSG_TRUNC
 279 indicates that
 280 the trailing portion of a datagram was discarded because the datagram
 281 was larger than the buffer supplied.
 282 .Dv MSG_CTRUNC
 283 indicates that some
 284 control data were discarded due to lack of space in the buffer
 285 for ancillary data.
 286 .Dv MSG_OOB
 287 is returned to indicate that expedited or out-of-band data were received.
 288 .Sh RETURN VALUES
 289 These calls return the number of bytes received, or -1
 290 if an error occurred.
 291 .Sh ERRORS
 292 The calls fail if:
 293 .Bl -tag -width Er
 294 .It Bq Er EBADF
 295 The argument
 296 .Fa s
 297 is an invalid descriptor.
 298 .It Bq Er ECONNRESET
 299 The remote socket end is forcibly closed.
 300 .It Bq Er ENOTCONN
 301 The socket is associated with a connection-oriented protocol
 302 and has not been connected (see
 303 .Xr connect 2
 304 and
 305 .Xr accept 2 ) .
 306 .It Bq Er ENOTSOCK
 307 The argument
 308 .Fa s
 309 does not refer to a socket.
 310 .It Bq Er EMSGSIZE
 311 The
 312 .Fn recvmsg
 313 system call
 314 was used to receive rights (file descriptors) that were in flight on the
 315 connection.
 316 However, the receiving program did not have enough free file
 317 descriptor slots to accept them.
 318 In this case the descriptors are
 319 closed, any pending data can be returned by another call to
 320 .Fn recvmsg .
 321 .It Bq Er EAGAIN
 322 The socket is marked non-blocking, and the receive operation
 323 would block, or
 324 a receive timeout had been set,
 325 and the timeout expired before data were received.
 326 .It Bq Er EINTR
 327 The receive was interrupted by delivery of a signal before
 328 any data were available.
 329 .It Bq Er EFAULT
 330 The receive buffer pointer(s) point outside the process's
 331 address space.
 332 .El
 333 .Sh SEE ALSO
 334 .Xr fcntl 2 ,
 335 .Xr getsockopt 2 ,
 336 .Xr read 2 ,
 337 .Xr select 2 ,
 338 .Xr socket 2 ,
 339 .Xr unix 4
 340 .Sh HISTORY
 341 The
 342 .Fn recv
 343 function appeared in
 344 .Bx 4.2 .