usr/src/man/man3socket/recv.3socket

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH RECV 3SOCKET "Dec 03, 2014"
   8 .SH NAME
   9 recv, recvfrom, recvmsg \- receive a message from a socket
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ]
  14 #include <sys/types.h>
  15 #include <sys/socket.h>
  16 #include <sys/uio.h>
  17
  18 \fBssize_t\fR \fBrecv\fR(\fBint\fR \fIs\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIflags\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBssize_t\fR \fBrecvfrom\fR(\fBint\fR \fIs\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIflags\fR,
  24      \fBstruct sockaddr *\fR\fIfrom\fR, \fBsocklen_t *\fR\fIfromlen\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBssize_t\fR \fBrecvmsg\fR(\fBint\fR \fIs\fR, \fBstruct msghdr *\fR\fImsg\fR, \fBint\fR \fIflags\fR);
  30 .fi
  31
  32 .SH DESCRIPTION
  33 .LP
  34 The \fBrecv()\fR, \fBrecvfrom()\fR, and \fBrecvmsg()\fR functions are used to
  35 receive messages from another socket. The \fIs\fR socket is created with
  36 \fBsocket\fR(3SOCKET).
  37 .sp
  38 .LP
  39 If \fIfrom\fR is a non-\fBNULL\fR pointer, the source address of the message is
  40 filled in. The value-result parameter \fIfromlen\fR is initialized to the size
  41 of the buffer associated with \fIfrom\fR and modified on return to indicate the
  42 actual size of the address stored in the buffer. The length of the message is
  43 returned. If a message is too long to fit in the supplied buffer, excess bytes
  44 may be discarded depending on the type of socket from which the message is
  45 received. See \fBsocket\fR(3SOCKET).
  46 .sp
  47 .LP
  48 If no messages are available at the socket, the receive call waits for a
  49 message to arrive. If the socket is non-blocking, \fB-1\fR is returned with the
  50 external variable \fBerrno\fR set to \fBEWOULDBLOCK\fR. See \fBfcntl\fR(2).
  51 .sp
  52 .LP
  53 For processes on the same host, \fBrecvmsg()\fR can be used to receive a file
  54 descriptor from another process, but it cannot receive ancillary data. See
  55 \fBlibxnet\fR(3LIB).
  56 .sp
  57 .LP
  58 If a zero-length buffer is specified for a message, an EOF condition results
  59 that is indistinguishable from the successful transfer of a file descriptor.
  60 For that reason, one or more bytes of data should be provided when
  61 \fBrecvmsg()\fR passes a file descriptor.
  62 .sp
  63 .LP
  64 The \fBselect\fR(3C) call can be used to determine when more data arrives.
  65 .sp
  66 .LP
  67 The \fIflags\fR parameter is formed by an \fBOR\fR operation on one or more of
  68 the following:
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBMSG_OOB\fR\fR
  73 .ad
  74 .RS 16n
  75 Read any \fBout-of-band\fR data present on the socket rather than the regular
  76 \fBin-band\fR data.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fBMSG_PEEK\fR\fR
  83 .ad
  84 .RS 16n
  85 Peek at the data present on the socket. The data is returned, but not consumed
  86 to allow a subsequent receive operation to see the same data.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBMSG_WAITALL\fR\fR
  93 .ad
  94 .RS 16n
  95 Messages are blocked until the full amount of data requested is returned. The
  96 \fBrecv()\fR function can return a smaller amount of data if a signal is
  97 caught, the connection is terminated, \fBMSG_PEEK\fR is specified, or if an
  98 error is pending for the socket.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBMSG_DONTWAIT\fR\fR
 105 .ad
 106 .RS 16n
 107 Pending messages received on the connection are returned. If data is
 108 unavailable, the function does not block. This behavior is the equivalent to
 109 specifying \fBO_NONBLOCK\fR on the file descriptor of a socket, except that
 110 write requests are unaffected.
 111 .RE
 112
 113 .sp
 114 .LP
 115 The \fBrecvmsg()\fR function call uses a \fBmsghdr\fR structure defined in
 116 <\fBsys/socket.h\fR> to minimize the number of directly supplied parameters.
 117 .SH RETURN VALUES
 118 .LP
 119 Upon successful completion, these functions return the number of bytes
 120 received. Otherwise, they return \fB-1\fR and set \fBerrno\fR to indicate the
 121 error.
 122 .SH ERRORS
 123 .LP
 124 The \fBrecv()\fR, \fBrecvfrom()\fR, and \fBrecvmsg()\fR functions return errors
 125 under the following conditions:
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBEBADF\fR\fR
 130 .ad
 131 .RS 16n
 132 The \fIs\fR file descriptor is invalid.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBECONNRESET\fR\fR
 139 .ad
 140 .RS 16n
 141 The \fIs\fR argument refers to a connection oriented socket and the connection
 142 was forcibly closed by the peer and is no longer valid. I/O can no longer be
 143 performed to \fIfiledes\fR.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBEINVAL\fR\fR
 150 .ad
 151 .RS 16n
 152 The \fBMSG_OOB\fR flag is set and no out-of-band data is available.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBEINTR\fR\fR
 159 .ad
 160 .RS 16n
 161 The operation is interrupted by the delivery of a signal before any data is
 162 available to be received.
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBEIO\fR\fR
 169 .ad
 170 .RS 16n
 171 An I/O error occurs while reading from or writing to the file system.
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fBENOMEM\fR\fR
 178 .ad
 179 .RS 16n
 180 Insufficient user memory is available to complete operation.
 181 .RE
 182
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fBENOSR\fR\fR
 187 .ad
 188 .RS 16n
 189 Insufficient \fBSTREAMS\fR resources are available for the operation to
 190 complete.
 191 .RE
 192
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBENOTSOCK\fR\fR
 197 .ad
 198 .RS 16n
 199 \fIs\fR is not a socket.
 200 .RE
 201
 202 .sp
 203 .ne 2
 204 .na
 205 \fB\fBESTALE\fR\fR
 206 .ad
 207 .RS 16n
 208 A stale NFS file handle exists.
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fBEWOULDBLOCK\fR\fR
 215 .ad
 216 .RS 16n
 217 The socket is marked non-blocking and the requested operation would block.
 218 .RE
 219
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fBECONNREFUSED\fR\fR
 224 .ad
 225 .RS 16n
 226 The requested connection was refused by the peer. For connected IPv4 and IPv6
 227 datagram sockets, this indicates that the system received an \fBICMP
 228 Destination Port Unreachable\fR message from the peer.
 229 .RE
 230
 231 .sp
 232 .LP
 233 The \fBrecv()\fR and \fBrecvfrom()\fR functions fail under the following
 234 conditions:
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fBEINVAL\fR\fR
 239 .ad
 240 .RS 10n
 241 The \fIlen\fR argument overflows a \fBssize_t\fR.
 242 .RE
 243
 244 .sp
 245 .LP
 246 The \fBrecvmsg()\fR function returns errors under the following conditions:
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBEINVAL\fR\fR
 251 .ad
 252 .RS 10n
 253 The \fBmsg_iovlen\fR member of the \fBmsghdr\fR structure pointed to by
 254 \fImsg\fR is less than or equal to \fB0\fR, or greater than \fB[IOV_MAX}\fR.
 255 See \fBIntro\fR(2) for a definition of \fB[IOV_MAX}\fR.
 256 .RE
 257
 258 .sp
 259 .ne 2
 260 .na
 261 \fB\fBEINVAL\fR\fR
 262 .ad
 263 .RS 10n
 264 One of the \fIiov_len\fR values in the \fBmsg_iov\fR array member of the
 265 \fBmsghdr\fR structure pointed to by \fImsg\fR is negative, or the sum of the
 266 \fIiov_len\fR values in the \fBmsg_iov\fR array overflows a \fBssize_t\fR.
 267 .RE
 268
 269 .SH ATTRIBUTES
 270 .LP
 271 See \fBattributes\fR(5) for descriptions of the following attributes:
 272 .sp
 273
 274 .sp
 275 .TS
 276 box;
 277 c | c
 278 l | l .
 279 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 280 _
 281 Interface Stability     Committed
 282 _
 283 MT-Level        Safe
 284 .TE
 285
 286 .SH SEE ALSO
 287 .LP
 288 \fBfcntl\fR(2), \fBioctl\fR(2), \fBread\fR(2), \fBconnect\fR(3SOCKET),
 289 \fBgetsockopt\fR(3SOCKET), \fBlibxnet\fR(3LIB), \fBselect\fR(3C),
 290 \fBsend\fR(3SOCKET), \fBsockaddr\fR(3SOCKET), \fBsocket\fR(3SOCKET),
 291 \fBsocket.h\fR(3HEAD), \fBattributes\fR(5)