recv(3xnet) - osol9

1recv(3XNET)      X/Open Networking Services Library Functions      recv(3XNET)
2
3
4

NAME

6       recv - receive a message from a connected socket
7

SYNOPSIS

9       cc [ flag ... ] file ... -lxnet [ library ... ]
10       #include <sys/socket.h>
11
12       ssize_t recv(int socket, void *buffer, size_t length, int flags);
13
14

DESCRIPTION

16       The   recv() function receives a message from a connection-mode or con‐
17       nectionless-mode socket. It is normally  used  with  connected  sockets
18       because  it  does  not  permit  the  application to retrieve the source
19       address of received data. The function takes the following arguments:
20
21       socket    Specifies the socket file descriptor.
22
23
24       buffer    Points to a buffer where the message should be stored.
25
26
27       length    Specifies the length in bytes of the buffer pointed to by the
28                 buffer argument.
29
30
31       flags     Specifies  the  type  of  message  reception.  Values of this
32                 argument are formed by logically OR'ing zero or more  of  the
33                 following values:
34
35                 MSG_PEEK       Peeks  at  an  incoming  message.  The data is
36                                treated as unread and the next recv() or simi‐
37                                lar function will still return this data.
38
39
40                 MSG_OOB        Requests  out-of-band  data.  The significance
41                                and semantics of out-of-band data  are  proto‐
42                                col-specific.
43
44
45                 MSG_WAITALL    Requests  that  the  function  block until the
46                                full amount of data requested can be returned.
47                                The  function  may  return a smaller amount of
48                                data if a signal is caught, if the  connection
49                                is  terminated,  if MSG_PEEK was specified, or
50                                if an error is pending for the socket.
51
52
53
54
55       The recv() function returns the length of the message  written  to  the
56       buffer  pointed  to  by the buffer argument.  For message-based sockets
57       such as SOCK_DGRAM and SOCK_SEQPACKET, the entire message must be  read
58       in a single operation.  If a message is too long to fit in the supplied
59       buffer, and MSG_PEEK is not set in the flags argument, the excess bytes
60       are  discarded.   For stream-based sockets such as SOCK_STREAM, message
61       boundaries are ignored.  In this case, data is returned to the user  as
62       soon as it becomes available, and no data is discarded.
63
64
65       If  the  MSG_WAITALL  flag is not set, data will be returned only up to
66       the end of the first message.
67
68
69       If no messages are available at the socket and O_NONBLOCK is not set on
70       the  socket's  file  descriptor, recv() blocks until a message arrives.
71       If no messages are available at the socket and O_NONBLOCK is set on the
72       socket's  file  descriptor,  recv()  fails  and sets errno to EAGAIN or
73       EWOULDBLOCK.
74

USAGE

76       The recv()  function  is  identical  to  recvfrom(3XNET)  with  a  zero
77       address_len argument, and to read() if no flags are used.
78
79
80       The select(3C) and poll(2) functions can be used to determine when data
81       is available to be received.
82

RETURN VALUES

84       Upon successful completion, recv() returns the length of the message in
85       bytes.   If  no  messages are available to be received and the peer has
86       performed an orderly shutdown, recv()  returns  0.   Otherwise,  -1  is
87       returned and errno is set to indicate the error.
88

ERRORS

90       The recv() function will fail if:
91
92       EAGAIN         The socket's file descriptor is marked O_NONBLOCK and no
93       EWOULDBLOCK    data is waiting to be received; or MSG_OOB is set and no
94                      out-of-band  data  is  available and either the socket's
95                      file descriptor is marked O_NONBLOCK or the socket  does
96                      not support blocking to await out-of-band data.
97
98
99       EBADF          The socket argument is not a valid file descriptor.
100
101
102       ECONNRESET     A connection was forcibly closed by a peer.
103
104
105       EFAULT         The  buffer parameter can not be accessed or written.
106
107
108       EINTR          The recv() function was interrupted by a signal that was
109                      caught, before any data was available.
110
111
112       EINVAL         The MSG_OOB flag is  set  and  no  out-of-band  data  is
113                      available.
114
115
116       ENOTCONN       A  receive is attempted on a connection-mode socket that
117                      is not connected.
118
119
120       ENOTSOCK       The socket argument does not refer to a socket.
121
122
123       EOPNOTSUPP     The specified flags are not supported  for  this  socket
124                      type or protocol.
125
126
127       ETIMEDOUT      The  connection  timed  out during connection establish‐
128                      ment, or due to a transmission timeout on active connec‐
129                      tion.
130
131
132
133       The recv() function may fail if:
134
135       EIO        An  I/O  error occurred while reading from or writing to the
136                  file system.
137
138
139       ENOBUFS    Insufficient resources were available in the system to  per‐
140                  form the operation.
141
142
143       ENOMEM     Insufficient memory was available to fulfill the request.
144
145
146       ENOSR      There  were insufficient STREAMS resources available for the
147                  operation to complete.
148
149

ATTRIBUTES

151       See attributes(5) for descriptions of the following attributes:
152
153
154
155
156       ┌─────────────────────────────┬─────────────────────────────┐
157       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
158       ├─────────────────────────────┼─────────────────────────────┤
159       │Interface Stability          │Standard                     │
160       ├─────────────────────────────┼─────────────────────────────┤
161       │MT-Level                     │MT-Safe                      │
162       └─────────────────────────────┴─────────────────────────────┘
163