recv()

receive message from socket 

Function


SYNOPSIS

#include <sys/socket.h>

int recv(int s, void *buf, size_t len, int flags);


DESCRIPTION

The recv() function receives a message from a socket. The recv() call can be used on a connection mode socket or a bound, connectionless socket. If no messages are available at the socket, the recv() call waits for a message to arrive unless the socket is nonblocking. If a socket is nonblocking, -1 is returned and the external variable errno is set to EWOULDBLOCK. select() can be used to wait for incoming messages.

A recv() on a SOCK_STREAM socket returns as much available information as the size of the buffer supplied can hold. If the socket has been configured for in-line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band data is unread, only out-of-band data is returned. The application may use the ioctl() SIOCATMARK to determine whether any more out-of-band data remains to be read.

For SOCK_DGRAM sockets, data is extracted from the first queued datagram for the destination address specified in the connect call. If unconnected, the socket must be bound and have no source address restrictions on the datagrams received. If the datagram is larger than the buffer supplied, the buffer is filled with the first part of the datagram and recv() generates the error EMSGSIZE. For unreliable protocols (such as UDP), excess data is lost. For reliable protocols, data is successfully read by calling recv() with a large enough buffer.

If the socket is connection-oriented and the remote side has shut down the connection gracefully, a recv() call completes with 0 bytes received. If the connection has been reset, recv() fails and sets errno to ECONNRESET.

flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

MSG_PEEK 

Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue.

MSG_OOB 

Process out-of-band data


PARAMETERS

s 

Specifies a socket descriptor from which data should be received.

buf 

Points to the buffer in which to place the message.

len 

Specifies the length of the buffer.

flags 

Lets the caller control the reception by peeking at incoming data (MSG_PEEK) or receive out-of-band data (MSG_OOB).


RETURN VALUES

If successful, recv() returns the number of bytes received. On failure, it returns a value of -1 and sets errno to one of the following values:

EBADF 

s is an invalid descriptor.

ECONNABORTED 

The virtual circuit was aborted because of a timeout or other failure.

ECONNRESET 

The virtual circuit was reset by the remote host executing a hard or abortive close.

EFAULT 

buf is an invalid pointer.

EINTR 

A signal interrupted the recv() call.

EINVAL 

The socket was not bound using bind(), or an invalid flag was specified, or len was 0 or negative.

EMSGSIZE 

The message was too large to fit the specified buffer.

ENETDOWN 

The network subsystem has failed.

ENETRESET 

The connection is broken; the remote host reset.

ENOTCONN 

The socket is not connected.

ENOTSOCK 

s is not a socket descriptor.

EOPNOTSUPP 

MSG_OOB was specified on socket that does not support out of band data.

ESHUTDOWN 

The socket has been shut down.

ETIMEDOUT 

The connection has been dropped because of a network failure.

EWOULDBLOCK 

s is nonblocking and recv() would block.


CONFORMANCE

UNIX 98, with exceptions.


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

The recv() does not support MSG_PEEK for AF_UNIX sockets.

The NuTCRACKER Platform supports all the address families that WinSock 2.0 supports.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
bind(), connect(), ioctl(), read(), recvfrom(), recvmsg(), send(), sendmsg(), sendto(), socket(), socketpair()


PTC MKS Toolkit 10.1 patch 1 Documentation Build 2.