sctp_recvv

- receive a message from an SCTP socket

Synopsis

cc [ flag... ] file... -lsocket -lnsl -lsctp [ library... ]
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/sctp.h>

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

Parameters

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 to hold the attributes of the received message. The structure type of info is determined by the infotype parameter.

infolen

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

infotype

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

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(3SOCKET). On return, its value will be different from what was set in to the call. It has the same value as rcv_flags.

Description

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.

There are two types of attributes which can be returned by this call: 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 struct 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:

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;
};

rcv_sid

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

This field may be set to following values:

SCTP_UNORDERED

This flag is set 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 style socket.

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;
};

nxt_sid

The stream number of the next message.

nxt_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.

nxt_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.

nxt_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. Only if the flag SCTP_COMPLETE is set in the nxt_flags field does this field represent the entire next message size.

nxt_assoc_id

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

New structures can be defined to hold new types of attributes. The new structures do not need to be based on struct sctp_recvv_rn or struct sctp_rcvinfo.

Return Values

Upon successful completion, the sctp_recvv() function returns the number of bytes received. The function returns -1 if an error occurs and errno is set to indicate the error.

Errors

The sctp_recvv() function will fail if:

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.

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 block.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

libsctp(3LIB), recvmsg(3SOCKET), setsockopt(3SOCKET), socket(3SOCKET), attributes(5), sctp(7P)