DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

recv(SSC)


recv, recvfrom, recvmsg -- receive a message from a socket

Syntax

cc ... -lsocket

#include <sys/types.h>
#include <sys/socket.h>

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

int recvfrom(s, buf, len, flags, from, fromlen) int s; void *buf; int len, flags; struct sockaddr *from; int *fromlen;

int recvmsg(s, msg, flags) int s; struct msghdr *msg; int flags;

Description

recv( ), recvfrom( ), and recvmsg( ) calls are used to receive messages from a socket.

The recv( ) call may be used only on a connected socket (see connect(SSC) for more information), while recvfrom( ) and recvmsg( ) may be used to receive data on a socket whether it is in a connected state or not.

If from is non-zero, the source address of the message is filled in. fromlen is a value-result parameter, initialized to the size of the buffer associated with from, and modified on return to indicate the actual size of the address stored there. The length of the message is returned in cc. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from; see socket(SSC).

If no messages are available at the socket, the receive call waits for a message to arrive.

The flags argument to a send call is formed by or'ing one or more of the values:

   #define	MSG_OOB	0x1		/* process out-of-band data */
   #define	MSG_PEEK	0x2	/* peek at incoming message */

The recvmsg( ) call uses a msghdr structure to minimize the number of directly supplied parameters. This structure is defined in the sys/socket.h header file, and includes the following members:

   caddr_t msg_name;               /* optional address */
   int     msg_namelen;            /* size of address */
   struct iovec    *msg_iov;       /* scatter/gather array */
   int     msg_iovlen;             /* # elements in msg_iov */
   caddr_t msg_control;            /* control information sent/received */
   int     msg_controllen;         /* size of control information */
   int     msg_flags;              /* size of control information */

Here msg_name and msg_namelen specify the destination address if the socket is unconnected; msg_name may be given as a NULL pointer if no names are desired or required. msg_iov and msg_iovlen describe the scatter-gather locations, as described in readv(S). A buffer to receive any control information sent along with the message is specified in msg_control, which has length msg_controllen .

Control messages are of the form:

   struct cmsghdr {
   	u_int   cmsg_len;       /* data byte count, including hdr */
   	int     cmsg_level;     /* originating protocol */
   	int     cmsg_type;      /* protocol-specific type */
   	/* followed by u_char  cmsg_data[]; */
   };

Control messages can be stepped through using the CMSG_FIRSTHDR and CMSG_NEXTHDR macros defined in <sys/socket.h>.

The ``msg_flags'' member is set on return according to the message received. MSG_TRUNC indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. MSG_CTRUNC indicates that some control data were discarded due to lack of space in the buffer for ancillary data. MSG_OOB is returned to indicate that expedited or out-of-band data were received.

Return values

These calls return the number of bytes received, or -1 if an error occurred.

Diagnostics

The calls fail if:

[EBADF]
The s argument is an invalid descriptor.

[ENOTSOCK]
The s argument does not point to a socket.

[EINTR]
The receive was interrupted by delivery of a signal before any data was available for the receive.

[EFAULT]
The data was specified to be received into a non-existent or protected part of the process address space.

See also

Intro(ADMP), Intro(SSC), connect(SSC), read(S), readv(S), send(SSC), socket(SSC)
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003