sctp_sendv

- send a message to 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_sendv(int sd, const struct iovec *iov, int iovcnt,
      struct sockaddr *addrs, int addrcnt, void *info, socklen_t infolen,
      unsigned int infotype, int flags);

Parameters

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

Identifies the type of the information provided in info. The defined values are:

SCTP_SENDV_SNDINFO

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 ( not supported).

SCTP_SENDV_SPA

The type of info is struct sctp_sendv_spa.

flags

The same flags as used by sendmsg(3SOCKET) (for example, MSG_DONTROUTE).

Description

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(3SOCKET).

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 (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, indicating whether the sendv_sndinfo, sendv_prinfo, and sendv_authinfo fields contain valid information.

The sctp_sndinfo structure is defined as:

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

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

This 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 style sockets 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 style sockets 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(3SOCKET) computation.

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 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 style sockets only.

The sctp_prinfo structure is defined as:

struct sctp_prinfo {
    uint16_t pr_policy;
    uint32_t pr_value;
};

pr_policy

This field specifies which partial reliability (PR-SCTP) policy 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 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 style sockets 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 style socket, 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 style sockets. 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), it 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.

Return Values

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

Errors

The sctp_sendv() function will fail if:

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(2) and issue another socket(3SOCKET) call to obtain a new descriptor before making another attempt.

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.

Attributes

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

See Also

htonl(3SOCKET), libsctp(3LIB), sctp_connectx(3SOCKET), sendmsg(3SOCKET), socket(3SOCKET), attributes(5), sctp(7P)