8.2.10 recvfrom, recvmsg: receive a message from a socket

 

SYNOPSIS

#include <oskit/net/socket.h>

oskit_error_t oskit_socket_recvfrom(oskit_socket_t *s, [out] void *buf, oskit_size_t len, oskit_u32_t flags, [out] struct oskit_sockaddr *from, [in/out] oskit_size_t *fromlen, [out] oskit_size_t *retval);

oskit_error_t oskit_socket_recvmsg(oskit_socket_t *s, [in/out] struct oskit_msghdr *msg, oskit_u32_t flags, [out] oskit_size_t *retval);

DESCRIPTION

recvfrom and recvmsg are used to receive messages from a socket, and may be used to receive data on a socket whether or not it is connection-oriented.

Note: The recv library function can be implemented using recvfrom with a nil from parameter.

If no messages are available at the socket, the receive call waits for a message to arrive. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount equested; this behavior is affected by the socket-level options OSKIT_SO_RCVLOWAT and OSKIT_SO_RCVTIMEO described in getsockopt.

PARAMETERS

s

The socket from the message is to be received.

buf

Buffer in which the message is to be copied.

len

Length of the buffer provided.

flags

The flags argument is formed by or'ing one or more of the values:

OSKIT_MSG_OOB process out-of-band data

OSKIT_MSG_PEEK peek at incoming message

OSKIT_MSG_WAITALL wait for full request or error

The OSKIT_MSG_OOB flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. The OSKIT_MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. The OSKIT_MSG_WAITALL flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if an error or disconnect occurs, or the next data to be received is of a different type than that returned.

from

If from is non-nil, and the socket is not connection-oriented, the source address of the message is filled in.

fromlen

Initialized to the size of the buffer associated with from, and modified on return to indicate the actual size of the address stored there.

msg

The recvmsg method uses a struct oskit_msghdr structure to minimize the number of directly supplied parameters.

struct oskit_msghdr  {

        oskit_addr_t     msg_name;               /* optional address */
        oskit_u32_t      msg_namelen;            /* size of address */
        struct  oskit_iovec *msg_iov;            /* scatter/gather array */
        oskit_u32_t      msg_iovlen;             /* # elements in msg_iov */
        oskit_addr_t     msg_control;            /* ancillary data, see below */
        oskit_u32_t      msg_controllen;         /* ancillary data buffer len */
        oskit_u32_t      msg_flags;              /* flags on received message */
 

};

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 scatter gather locations.

msg_control, which has length msg_controllen, points to a buffer for other protocol control related messages or other miscellaneous ancillary data.

The msg_flags field is set on return according to the message received. OSKIT_MSG_EOR indicates end-of-record; the data returned completed a record (generally used with sockets of type OSKIT_SOCK_SEQPACKET). OSKIT_MSG_TRUNC indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. OSKIT_CMSG_TRUNC indicates that some control data were discarded due to lack of space in the buffer for ancillary data. OSKIT_MSG_OOB is returned to indicate that expedited or out-of-band data were received.

retval

Contains the number of characters received, i.e., the total length of the message upon return. 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.

RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.