X/Open Networking Services Library Functions recv(3XN) NAME recv - receive a message from a connected socket SYNOPSIS cc [ _f_l_a_g ... ] _f_i_l_e ... -lxnet [ _l_i_b_r_a_r_y ... ] #include ssize_t recv(int _s_o_c_k_e_t, void *_b_u_f_f_e_r, size_t _l_e_n_g_t_h, int _f_l_a_g_s); DESCRIPTION The recv() function receives messages from a connected socket. The function takes the following arguments: _s_o_c_k_e_t Specifies the socket file descriptor. _b_u_f_f_e_r Points to a buffer where the message should be stored. _l_e_n_g_t_h Specifies the length in bytes of the buffer pointed to by the _b_u_f_f_e_r argument. _f_l_a_g_s Specifies the type of message reception. Values of this argument are formed by logi- cally OR'ing zero or more of the following values: MSG_PEEK Peeks at an incoming message. The data is treated as unread and the next recv() or similar function will still return this data. MSG_OOB Requests out-of-band data. The significance and semantics of out-of-band data are protocol-specific. MSG_WAITALL Requests that the function block until the full amount of data requested can be returned. The function may return a smaller amount of data if a signal is caught, the connection is terminated, or an error is pending for the socket. The recv() function returns the length of the message writ- ten to the buffer pointed to by the _b_u_f_f_e_r argument. For message-based sockets such as SOCK_DGRAM and SOCK_SEQPACKET SunOS 5.6 Last change: 16 May 1997 1 X/Open Networking Services Library Functions recv(3XN) , the entire message must be read in a single operation. If a message is too long to fit in the supplied buffer, and MSG_PEEK is not set in the _f_l_a_g_s argument, the excess bytes are discarded. For stream-based sockets such as SOCK_STREAM, message boundaries are ignored. In this case, data is returned to the user as soon as it becomes avail- able, and no data is discarded. If the MSG_WAITALL flag is not set, data will be returned only up to the end of the first message. If no messages are available at the socket and O_NONBLOCK is not set on the socket's file descriptor, recv() blocks until a message arrives. If no messages are available at the socket and O_NONBLOCK is set on the socket's file descrip- tor, recv() fails and sets errno to EAGAIN. RETURN VALUES Upon successful completion, recv() returns the length of the message in bytes. If no messages are available to be received and the peer has performed an orderly shutdown, recv() returns 0. Otherwise, -1 is returned and errno is set to indicate the error. ERRORS The recv() function will fail if: EBADF The _s_o_c_k_e_t argument is not a valid file descriptor. ECONNRESET A connection was forcibly closed by a peer. EINTR The recv() function was interrupted by a sig- nal that was caught, before any data was available. EINVAL The MSG_OOB flag is set and no out-of-band data is available. ENOTCONN A receive is attempted on a connection-mode socket that is not connected. ENOTSOCK The _s_o_c_k_e_t argument does not refer to a socket. EOPNOTSUPP The specified flags are not supported for this socket type or protocol. ETIMEDOUT The connection timed out during connection establishment, or due to a transmission timeout on active connection. SunOS 5.6 Last change: 16 May 1997 2 X/Open Networking Services Library Functions recv(3XN) EAGAIN The socket's file descriptor is marked O_NONBLOCK and no data is waiting to be received; or MSG_OOB is set and no out-of- band data is available and either the socket's file descriptor is marked O_NONBLOCK or the socket does not support blocking to await out-of-band data. The recv() function may fail if: EIO An I/O error occurred while reading from or writing to the file system. ENOBUFS Insufficient resources were available in the system to perform the operation. ENOMEM Insufficient memory was available to fulfill the request. ENOSR There were insufficient STREAMS resources available for the operation to complete. USAGE The recv() function is identical to recvfrom(3XN) with a zero _a_d_d_r_e_s_s__l_e_n argument, and to read(2) if no flags are used. The select(3C) and poll(2) functions can be used to deter- mine when data is available to be received. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: __________________________________ | ATTRIBUTE TYPE| ATTRIBUTE VALUE| |_______________________________|____________________________________|_ | MT-Level | MT-Safe | |________________|__________________| SEE ALSO poll(2), read(2), write(2), recvmsg(3XN), recvfrom(3XN), select(3C), send(3XN), sendmsg(3XN), sendto(3XN), shutdown(3XN), socket(3XN), attributes(5), socket(5) SunOS 5.6 Last change: 16 May 1997 3