1 .\"
   2 .\" The contents of this file are subject to the terms of the
   3 .\" Common Development and Distribution License (the "License").
   4 .\" You may not use this file except in compliance with the License.
   5 .\"
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   7 .\" or http://www.opensolaris.org/os/licensing.
   8 .\" See the License for the specific language governing permissions
   9 .\" and limitations under the License.
  10 .\"
  11 .\" When distributing Covered Code, include this CDDL HEADER in each
  12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  13 .\" If applicable, add the following below this CDDL HEADER, with the
  14 .\" fields enclosed by brackets "[]" replaced with your own identifying
  15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  16 .\"
  17 .\"
  18 .\" Copyright 1989 AT&T
  19 .\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
  20 .\" Copyright 2018 Nexenta Systems, Inc.
  21 .\"
  22 .Dd August 2, 2018
  23 .Dt RECV 3C
  24 .Os
  25 .Sh NAME
  26 .Nm recv ,
  27 .Nm recvfrom ,
  28 .Nm recvmsg
  29 .Nd receive a message from a socket
  30 .Sh LIBRARY
  31 .Lb libc
  32 .Sh SYNOPSIS
  33 .In sys/types.h
  34 .In sys/socket.h
  35 .In sys/uio.h
  36 .Ft ssize_t
  37 .Fo recv
  38 .Fa "int s"
  39 .Fa "void *buf"
  40 .Fa "size_t len"
  41 .Fa "int flags"
  42 .Fc
  43 .Ft ssize_t
  44 .Fo recvfrom
  45 .Fa "int s"
  46 .Fa "void *restrict buf"
  47 .Fa "size_t len"
  48 .Fa "int flags"
  49 .Fa "struct sockaddr *restrict from"
  50 .Fa "socklen_t *fromlen"
  51 .Fc
  52 .Ft ssize_t
  53 .Fo recvmsg
  54 .Fa "int s"
  55 .Fa "struct msghdr *msg"
  56 .Fa "int flags"
  57 .Fc
  58 .Sh DESCRIPTION
  59 The
  60 .Fn recv ,
  61 .Fn recvfrom ,
  62 and
  63 .Fn recvmsg
  64 functions are used to receive messages from another socket.
  65 The
  66 .Fa s
  67 socket is created with
  68 .Xr socket 3C .
  69 .Pp
  70 If
  71 .Fa from
  72 is a non-
  73 .Dv NULL
  74 pointer, the source address of the message is filled in.
  75 The value-result parameter
  76 .Fa fromlen
  77 is initialized to the size of the buffer associated with
  78 .Fa from
  79 and modified on return to indicate the actual size of the address stored in the
  80 buffer.
  81 The length of the message is returned.
  82 If a message is too long to fit in the supplied buffer, excess bytes may be
  83 discarded depending on the type of socket from which the message is received.
  84 See
  85 .Xr socket 3C .
  86 .Pp
  87 If no messages are available at the socket, the receive call waits for a message
  88 to arrive.
  89 If the socket is non-blocking, -1 is returned with the external variable
  90 .Va errno
  91 set to
  92 .Er EWOULDBLOCK .
  93 See
  94 .Xr fcntl 2 .
  95 .Pp
  96 For processes on the same host,
  97 .Fn recvmsg
  98 can be used to receive a file descriptor from another process, but it cannot
  99 receive ancillary data.
 100 See
 101 .Xr libxnet 3LIB .
 102 .Pp
 103 If a zero-length buffer is specified for a message, an EOF condition results
 104 that is indistinguishable from the successful transfer of a file descriptor.
 105 For that reason, one or more bytes of data should be provided when
 106 .Fn recvmsg
 107 passes a file descriptor.
 108 .Pp
 109 The
 110 .Xr select 3C
 111 call can be used to determine when more data arrives.
 112 .Pp
 113 The
 114 .Fa flags
 115 parameter is formed by an OR operation on one or more of the following:
 116 .Bl -tag -width Ds
 117 .It Dv MSG_OOB
 118 Read any out-of-band data present on the socket rather than the regular in-band
 119 data.
 120 .It Dv MSG_PEEK
 121 Peek at the data present on the socket.
 122 The data is returned, but not consumed to allow a subsequent receive operation
 123 to see the same data.
 124 .It Dv MSG_WAITALL
 125 Messages are blocked until the full amount of data requested is returned.
 126 The
 127 .Fn recv
 128 function can return a smaller amount of data if a signal is caught, the
 129 connection is terminated,
 130 .Dv MSG_PEEK
 131 is specified, or if an error is pending for the socket.
 132 .It Dv MSG_DONTWAIT
 133 Pending messages received on the connection are returned.
 134 If data is unavailable, the function does not block.
 135 This behavior is the equivalent to specifying
 136 .Dv O_NONBLOCK
 137 on the file descriptor of a socket, except that write requests are unaffected.
 138 .El
 139 .Pp
 140 The
 141 .Fn recvmsg
 142 function call uses a
 143 .Va msghdr
 144 structure defined in
 145 .In sys/socket.h
 146 to minimize the number of directly supplied parameters.
 147 .Sh RETURN VALUES
 148 Upon successful completion, these functions return the number of bytes
 149 received.
 150 Otherwise, they return -1 and set
 151 .Va errno
 152 to indicate the error.
 153 .Sh ERRORS
 154 The
 155 .Fn recv ,
 156 .Fn recvfrom ,
 157 and
 158 .Fn recvmsg
 159 functions return errors under the following conditions:
 160 .Bl -tag -width Er
 161 .It Bq Er EBADF
 162 The
 163 .Fa s
 164 file descriptor is invalid.
 165 .It Bq Er ECONNRESET
 166 The
 167 .Fa s
 168 argument refers to a connection oriented socket and the connection was forcibly
 169 closed by the peer and is no longer valid.
 170 I/O can no longer be performed to filedes.
 171 .It Bq Er EINVAL
 172 The
 173 .Dv MSG_OOB
 174 flag is set and no out-of-band data is available.
 175 .It Bq Er EINTR
 176 The operation is interrupted by the delivery of a signal before any data is
 177 available to be received.
 178 .It Bq Er EIO
 179 An I/O error occurs while reading from or writing to the file system.
 180 .It Bq Er ENOMEM
 181 Insufficient user memory is available to complete operation.
 182 .It Bq Er ENOSR
 183 Insufficient STREAMS resources are available for the operation to complete.
 184 .It Bq Er ENOTSOCK
 185 .Fa s
 186 is not a socket.
 187 .It Bq Er ESTALE
 188 A stale NFS file handle exists.
 189 .It Bq Er EWOULDBLOCK
 190 The socket is marked non-blocking and the requested operation would block.
 191 .It Bq Er ECONNREFUSED
 192 The requested connection was refused by the peer.
 193 For connected IPv4 and IPv6 datagram sockets, this indicates that the system
 194 received an ICMP
 195 .Dq Destination Port Unreachable
 196 message from the peer.
 197 .El
 198 .Pp
 199 The
 200 .Fn recv
 201 and
 202 .Fn recvfrom
 203 functions fail under the following conditions:
 204 .Bl -tag -width Er
 205 .It Bq Er EINVAL
 206 The
 207 .Fa len
 208 argument overflows a
 209 .Vt ssize_t .
 210 .El
 211 .Pp
 212 The
 213 .Fn recvmsg
 214 function returns errors under the following conditions:
 215 .Bl -tag -width Er
 216 .It Bq Er EINVAL
 217 The
 218 .Va msg_iovlen
 219 member of the
 220 .Va msghdr
 221 structure pointed to by
 222 .Fa msg
 223 is less than or equal to 0, or greater than
 224 .Dv [IOV_MAX} .
 225 See
 226 .Xr Intro 2
 227 for a definition of
 228 .Dv [IOV_MAX} .
 229 .Pp
 230 One of the
 231 .Va iov_len
 232 values in the
 233 .Va msg_iov
 234 array member of the
 235 .Va msghdr
 236 structure pointed to by
 237 .Fa msg
 238 is negative, or the sum of the
 239 .Va iov_len
 240 values in the
 241 .Va msg_iov
 242 array overflows a
 243 .Vt ssize_t .
 244 .El
 245 .Sh MT-LEVEL
 246 .Sy Safe
 247 .Sh SEE ALSO
 248 .Xr fcntl 2 ,
 249 .Xr ioctl 2 ,
 250 .Xr read 2 ,
 251 .Xr connect 3C ,
 252 .Xr getsockopt 3C ,
 253 .Xr select 3C ,
 254 .Xr send 3C ,
 255 .Xr sockaddr 3C ,
 256 .Xr socket 3C ,
 257 .Xr socket.h 3HEAD ,
 258 .Xr libxnet 3LIB ,
 259 .Xr attributes 5