1 RECV(3C)                 Standard C Library Functions                 RECV(3C)
   2 
   3 NAME
   4      recv, recvfrom, recvmsg - receive a message from a socket
   5 
   6 LIBRARY
   7      Standard C Library (libc, -lc)
   8 
   9 SYNOPSIS
  10      #include <sys/types.h>
  11      #include <sys/socket.h>
  12      #include <sys/uio.h>
  13 
  14      ssize_t
  15      recv(int s, void *buf, size_t len, int flags);
  16 
  17      ssize_t
  18      recvfrom(int s, void *restrict buf, size_t len, int flags,
  19          struct sockaddr *restrict from, socklen_t *fromlen);
  20 
  21      ssize_t
  22      recvmsg(int s, struct msghdr *msg, int flags);
  23 
  24 DESCRIPTION
  25      The recv(), recvfrom(), and recvmsg() functions are used to receive
  26      messages from another socket.  The s socket is created with socket(3C).
  27 
  28      If from is a non- NULL pointer, the source address of the message is
  29      filled in.  The value-result parameter fromlen is initialized to the size
  30      of the buffer associated with from and modified on return to indicate the
  31      actual size of the address stored in the buffer.  The length of the
  32      message is returned.  If a message is too long to fit in the supplied
  33      buffer, excess bytes may be discarded depending on the type of socket
  34      from which the message is received.  See socket(3C).
  35 
  36      If no messages are available at the socket, the receive call waits for a
  37      message to arrive.  If the socket is non-blocking, -1 is returned with
  38      the external variable errno set to EWOULDBLOCK.  See fcntl(2).
  39 
  40      For processes on the same host, recvmsg() can be used to receive a file
  41      descriptor from another process, but it cannot receive ancillary data.
  42      See libxnet(3LIB).
  43 
  44      If a zero-length buffer is specified for a message, an EOF condition
  45      results that is indistinguishable from the successful transfer of a file
  46      descriptor.  For that reason, one or more bytes of data should be
  47      provided when recvmsg() passes a file descriptor.
  48 
  49      The select(3C) call can be used to determine when more data arrives.
  50 
  51      The flags parameter is formed by an OR operation on one or more of the
  52      following:
  53 
  54      MSG_OOB
  55              Read any out-of-band data present on the socket rather than the
  56              regular in-band data.
  57 
  58      MSG_PEEK
  59              Peek at the data present on the socket.  The data is returned,
  60              but not consumed to allow a subsequent receive operation to see
  61              the same data.
  62 
  63      MSG_WAITALL
  64              Messages are blocked until the full amount of data requested is
  65              returned.  The recv() function can return a smaller amount of
  66              data if a signal is caught, the connection is terminated,
  67              MSG_PEEK is specified, or if an error is pending for the socket.
  68 
  69      MSG_DONTWAIT
  70              Pending messages received on the connection are returned.  If
  71              data is unavailable, the function does not block.  This behavior
  72              is the equivalent to specifying O_NONBLOCK on the file descriptor
  73              of a socket, except that write requests are unaffected.
  74 
  75      The recvmsg() function call uses a msghdr structure defined in
  76      <sys/socket.h> to minimize   the number of directly supplied parameters.
  77 
  78 RETURN VALUES
  79      Upon successful completion, these functions return the number of bytes
  80      received.  Otherwise, they return -1 and set errno to indicate the error.
  81 
  82 ERRORS
  83      The recv(), recvfrom(), and recvmsg() functions return errors under the
  84      following conditions:
  85 
  86      [EBADF]            The s file descriptor is invalid.
  87 
  88      [ECONNRESET]       The s argument refers to a connection oriented socket
  89                         and the connection was forcibly closed by the peer and
  90                         is no longer valid.  I/O can no longer be performed to
  91                         filedes.
  92 
  93      [EINVAL]           The MSG_OOB flag is set and no out-of-band data is
  94                         available.
  95 
  96      [EINTR]            The operation is interrupted by the delivery of a
  97                         signal before any data is available to be received.
  98 
  99      [EIO]              An I/O error occurs while reading from or writing to
 100                         the file system.
 101 
 102      [ENOMEM]           Insufficient user memory is available to complete
 103                         operation.
 104 
 105      [ENOSR]            Insufficient STREAMS resources are available for the
 106                         operation to complete.
 107 
 108      [ENOTSOCK]         s is not a socket.
 109 
 110      [ESTALE]           A stale NFS file handle exists.
 111 
 112      [EWOULDBLOCK]      The socket is marked non-blocking and the requested
 113                         operation would block.
 114 
 115      [ECONNREFUSED]     The requested connection was refused by the peer.  For
 116                         connected IPv4 and IPv6 datagram sockets, this
 117                         indicates that the system received an ICMP
 118                         "Destination Port Unreachable" message from the peer.
 119 
 120      The recv() and recvfrom() functions fail under the following conditions:
 121 
 122      [EINVAL]           The len argument overflows a ssize_t.
 123 
 124      The recvmsg() function returns errors under the following conditions:
 125 
 126      [EINVAL]           The msg_iovlen member of the msghdr structure pointed
 127                         to by msg is less than or equal to 0, or greater than
 128                         [IOV_MAX}.  See Intro(2) for a definition of
 129                         [IOV_MAX}.
 130 
 131                         One of the iov_len values in the msg_iov array member
 132                         of the msghdr structure pointed to by msg is negative,
 133                         or the sum of the iov_len values in the msg_iov array
 134                         overflows a ssize_t.
 135 
 136 MT-LEVEL
 137      Safe
 138 
 139 SEE ALSO
 140      fcntl(2), ioctl(2), read(2), connect(3C), getsockopt(3C), select(3C),
 141      send(3C), sockaddr(3C), socket(3C), socket.h(3HEAD), libxnet(3LIB),
 142      attributes(5)
 143 
 144 illumos                         August 2, 2018                         illumos