sctp_sendv() Function

`sctp_sendv`() Function

ssize_t sctp_sendv(int sd, const struct iovec *iov, int iovcnt, struct sockaddr *addrs, int addrcnt, void *info, socklen_t infolen, unsigned int infotype, int flags);

The sctp_sendv() sends a message to an SCTP socket. The following attributes are specified:

sd

The socket descriptor.

iov

The message to be sent. The data in the buffer are treated as one single user message.

iovcnt

The number of elements in iov.

addrs

An array of addresses to be used to set up an association or one single address to be used to send the message. Pass in NULL if the caller does not want to set up an association nor want to send the message to a specific address.

addrcnt

The number of addresses in the addrs array.

info

A pointer to the buffer containing the attribute associated with the message to be sent. The type is indicated by info_type parameter.

infolen

The length in bytes of info.

infotype

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

SCTP_SENDV_SNDFO: The type of info is struct sctp_sndinfo.
SCTP_SENDV_PRINFO: The type of info is struct sctp_prinfo.
SCTP_SENDV_AUTHINFO: The type of info is struct sctp_authinfo. This type is not supported.
SCTP_SENDV_SPA: The type of info is struct sctp_send_spa.

The sctp_sendv() function provides an extensible way for an application to communicate different send attributes to the SCTP stack when sending a message. This function can also be used to set up an association. The addrs array is similar to the addrs array used by sctp_connectx Function.

There are three types of attributes which can be used to describe a message to be sent. They are represented by struct sctp_sndinfo, struct sctp_prinfo, and struct sctp_authinfo which is currently not supported.

The following structure sctp_sendv_spa is defined to be used when more than one of the above attributes are needed to describe a message to be sent.

struct sctp_sendv_spa {
    uint32_t sendv_flags;
    struct sctp_sndinfo sendv_sndinfo;
    struct sctp_prinfo  sendv_prinfo;
    struct sctp_authinfo sendv_authinfo;
};

The sendv_flags field holds a bitwise–OR of SCTP_SEND_SNDINFO_VALID, SCTP_SEND_PRINFO_VALID, and SCTP_SEND_AUTHINFO_VALID values, indicating whether the sendv_sndinfo, sendv_prinfo, and sendv_authinfo fields contain valid information.

The sctp_sndinfo structure is defined as follows:

struct sctp_sndinfo {
    uint16_t       snd_sid;
    uint16_t       snd_flags;
    uint32_t       snd_ppid;
    uint32_t       snd_context;
    sctp_assoc_t   snd_assoc_id;
};

where:

snd_sid

This value holds the stream number to send the message to. If a sender specifies an invalid stream number, an error value is returned and the call fails.

snd_flags

This field is a bit wise OR of the following flags:

SCTP_UNORDERED: his flag requests the unordered delivery of the message.
SCTP_ADDR_OVER: This flag requests the SCTP stack to override the primary destination address and send the message to the given address in addrs. Only one address can be given is this case. If this flag is not specified and addrs is not NULL, this call is treated as a connect request. This flag is applicable to one-to-many sockets model only.
SCTP_ABORT: Setting this flag causes the specified association to be aborted by sending an ABORT message to the peer. The ABORT message will contain an error cause User Initiated Abort with cause code 12. The specific information the cause of this error is provided in msg_iov.
SCTP_EOF: Setting this flag invokes the SCTP graceful shutdown procedures on the specified association. Graceful shutdown assures that all data queued by both endpoints is successfully transmitted before closing the association.
SCTP_SENDALL: This flag requests that the message is sent to all associations that are currently established on the socket. This flag is applicable to one-to-many sockets model only.

snd_ppid

An unsigned integer that is passed to the remote end in each user message (SCTP DATA chunk). The SCTP stack performs no byte order modification of this field. For example, if the DATA chunk has to contain a given value in network byte order, the SCTP user has to perform the htonl computation. For more information, see the htonl(3C) man page.

snd_context

This value is an opaque 32 bit context datum. It is passed back to the caller if an error occurs on the transmission of the message and is retrieved with each undelivered message.

snd_assoc_id

When sending a message, this field holds the identifier for the association which the message is sent to. When this call is used to set up an association, the association identifier of the newly created association is returned in this field. This field is applicable to one-to-many sockets model only.

The sctp_prininfo structure is defined as follows:

struct sctp_prinfo {
    uint16_t pr_policy;
    uint32_t pr_value;
};

where:

pr_policy: This field specifies the partial reliability (PR-SCTP) policy that is used to send the message. If it is SCTP_PR_SCTP_NONE, the message is sent reliably (the default is normal send). If it is SCTP_PR_SCTP_TTL, timed reliability as defined in Stream Control Transmission Protocol (SCTP) Partial Reliability Extension, RFC 3758 is used. In this case, the lifetime is provided in pr_value.
pr_value: The meaning of this field depends on the PR-SCTP policy specified by the pr_policy field. It is ignored when SCTP_PR_SCTP_NONE is specified. In case of SCTP_PR_SCTP_TTL, this field specifies the lifetime in milliseconds of the message.

When new send attributes are needed, new structures can be defined. Those new structures do not need to be based on any of the above defined structures.

The struct sctp_sndinfo attribute for one-to-many sockets model must always be used in order to specify the association the message is to be sent to. The only case where it is not needed is when this call is used to set up a new association.

The caller provides a list of addresses in the addrs parameter to set up an association. This function will behave like calling sctp_connectx(), first using the list of addresses, and then calling sendmsg() with the given message and attributes. For an one-to-many sockets model, if a struct sctp_sndinfo attribute is provided, the snd_assoc_id field must be 0. When this function returns, the snd_assoc_id field will contain the association identifier of the newly established association. The struct sctp_sndinfo attribute is not required to set up an association for one-to-many sockets model. If this attribute is not provided, the caller can enable the SCTP_ASSOC_CHANGE notification and use the SCTP_COMM_UP message to find out the association identifier.

If the caller wants to send the message to a specific peer address (overriding the primary address), the caller can provide the specific address in the addrs parameter and provide a struct sctp_sndinfo attribute with the snd_flags field set to SCTP_ADDR_OVER.

This function can also be used to terminate an association. The caller provides an sctp_sndinfo attribute with the snd_flags set to SCTP_EOF. In this case, the length of the message would be zero. Sending a message using sctp_sendv() is atomic unless explicit EOR marking is enabled on the socket specified by sd.

Upon successful completion, the number of bytes sent is returned. Otherwise, -1 is returned and errno is set to indicate the error.

The following error values are defined:

EADDRINUSE: The address is already in use.
EADDRNOTAVAIL: No local address is available for this operation.
EAFNOSUPPORT: Addresses in the specified address family cannot be used with this socket.
EBADF: The sd parameter is not a valid file descriptor.
ECONNREFUSED: The attempt to connect was forcefully rejected. The calling program should close the socket descriptor using close and issue another socket call to obtain a new descriptor before making another attempt. For more information, see the close(2) and socket(3C) man pages.
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.
EINVAL: A parameter provided is invalid for this operation.
EMSGSIZE: The message is too large to be sent all at once.
ENETUNREACH: The network is not reachable from this host.
ENOBUFS: Insufficient memory is available to complete the operation.
EOPNOTSUPP: Operation not supported in this type of socket.
EPIPE: The peer end point has shutdown the association.
ETIMEDOUT: Attempt timed out.
EWOULDBLOCK: The socket is marked as non-blocking, and the requested operation would block.