sctp_recvv() Function

ssize_t sctp_recvv(int sd, const struct iovec *iov, int iovlen, struct sockaddr *from, int fromlen, void *info, socklen_t infolen, unsigned int infotype, int flags);

The sctp_recvv() function provides an extensible way for the SCTP stack to pass up different SCTP attributes associated with a received message to an application. The following attributes are specified:

sd

The socket descriptor.

iov

The scatter buffer containing the received message.

iovlen

The number of elements in iov.

from

A pointer to a buffer to be filled with the sender address of the received message.

fromlen

The size of the from buffer. Upon return, it is set to the actual size of the sender's address.

info

A pointer to the buffer containing the attributes of the received message. The type of structure is indicated by info_type parameter.

infolen

The length in bytes of info buffer. Upon return, it is set to the actual size of the returned info buffer.

infotype

The type of the info buffer. The following values are defined:

SCTP_RECVV_NOINFO

If both SCTP_RECVRCVINFO and SCTP_RECVNXTINFO options are not enabled, no attribute will be returned. If only the SCTP_RECVNXTINFO option is enabled but there is no next message in the buffer, there will also no attribute be returned. In these cases, infotype will be set to SCTP_RECVV_NOINFO.

SCTP_RECVV_RCVINFO

The type of info is struct sctp_rcvinfo and the attribute is about the received message.

SCTP_RECVV_NXTINFO

The type of info is struct sctp_nxtinfo and the attribute is about the next message in receive buffer. This is the case when only the SCTP_RECVNXTINFO option is enabled and there is a next message in the buffer.

SCTP_RECVV_RN

The type of info is struct sctp_recvv_rn. The recvv_rcvinfo field is the attribute of the received message and the recvv_nxtinfo field is the attribute of the next message in buffer. This is the case when both SCTP_RECVRCVINFO and SCTP_RECVNXTINFO options are enabled and there is a next message in the receive buffer.

flags

Flag for receive as in recvmsg. On return, its value will be different from what was set in to the call. It has the same value as rcv_flags. For more information, see the recvmsg(3C) man page.

There are two types of attributes which can be returned by the call to sctp_recvv():

• The attribute of the received message and the attribute of the next message in receive buffer. The caller enables the SCTP_RECVRCVINFO and SCTP_RECVNXTINFO socket option to receive these attributes respectively.

Attributes of the received message are returned in struct sctp_rcvinfo and attributes of the next message are returned in the structure sctp_nxtinfo. If both options are enabled, both attributes are returned using the following structure.

struct sctp_recvv_rn {
    struct sctp_rcvinfo recvv_rcvinfo;
    struct sctp_nxtinfo recvv_nxtinfo;
};

The sctp_rcvinfo structure is defined as follows:

struct sctp_rcvinfo {
    uint16_t rcv_sid;
    uint16_t rcv_ssn;
    uint16_t rcv_flags;
    uint32_t rcv_ppid;
    uint32_t rcv_tsn;
    uint32_t rcv_cumtsn;
    uint32_t rcv_context;
    sctp_assoc_t rcv_assoc_id;
};

where:

rcv_info

The stream number of the received message.

rcv_ssn

The stream sequence number that the peer endpoint assigned to the DATA chunk of this message. For fragmented messages, this is the same number for all deliveries of the message (if more than one sctp_recvv() is needed to read the message).

rcv_flags

May be set to SCTP_UNORDERED when the message was sent unordered.

rcv_ppid

This value is the same information that is passed by the peer socket to its SCTP stack. The SCTP stack performs no byte order modification of this field.

rcv_tsn

The transmission sequence number that the peer endpoint assigned to the received message.

rcv_cumtsn

The current cumulative transmission sequence number of the association known to the SCTP stack.

rcv_assoc_id

The association identifier of the association of the received message. This field applies only to a one-to-many sockets model.

rcv_context

This value is an opaque 32 bit context datum that was set by the caller with the SCTP_CONTEXT socket option. This value is passed back to the upper layer if an error occurs on the transmission of a message and is retrieved with each undelivered message.

The sctp_nxtinfo structure is defined as follows:

struct sctp_nxtinfo {
    uint16_t nxt_sid;
    uint16_t nxt_flags;
    uint32_t nxt_ppid;
    size_t  nxt_length;
    sctp_assoc_t nxt_assoc_id;
};

where:

nxt_sid

The stream number of the next message.

flags

This field can contain any of the following flags and is composed of a bitwise–OR of the following values:

SCTP_UNORDERED

The next message was sent unordered.

SCTP_COMPLETE

The entire message has been received and is in the socket buffer. This flag has special implications with respect to the nxt_length field.

SCTP_NOTIFICATION

The next message is not a user message but instead is a notification.

ppid

This value is the same information that was passed by the peer socket to its SCTP stack when sending the next message. The SCTP stack performs no byte order modification of this field.

length

The length of the message currently received in the socket buffer. This might not be the entire length of the next message since a partial delivery may be in progress. This field represents the entire next message size only if the flag SCTP_COMPLETE is set in the nxt_flags field.

assoc_id

The association identifier of the association of the next message. This field applies only to a one-to-many sockets model.

The following error values are defined for sctp_recvv():

EBADF

The sd parameter is not a valid file descriptor.

EFAULT

A parameter can not be accessed.

EINTR

The operation was interrupted by delivery of a signal before any data could be buffered to be sent or the operation was interrupted by delivery of a signal before any data is available to be received.

EINVAL

A parameter provided is invalid for this operation.

ENOBUFS

Insufficient memory is available to complete the operation.

EWOULDBLOCK

The socket is marked as non-blocking and the requested operation would get blocked.