9.9 sctp_sendmsg Function

An application can control various features of SCTP by using the sendmsg function along with ancillary data (described in Chapter 14). However, because the use of ancillary data may be inconvenient, many SCTP implementations provide an auxiliary library call (possibly implemented as a system call) that eases an application's use of SCTP's advanced features. The call takes the following form:

ssize_t sctp_sendmsg(int sockfd, const void *msg, size_t msgsz, const struct sockaddr *to, socklen_t tolen, uint32_t ppid, uint32_t flags, uint16_t stream, uint32_t timetolive, uint32_t context);
Returns: the number of bytes written, –1 on error

The user of sctp_sendmsg has a greatly simplified sending method at the cost of more arguments. The sockfd field holds the socket descriptor returned from a socket system call. The msg field points to a buffer of msgsz bytes to be sent to the peer endpoint to. The tolen field holds the length of the address stored in to. The ppid field holds the pay-load protocol identifier that will be passed with the data chunk. The flags field will be passed to the SCTP stack to identify any SCTP options; valid values for this field may be found in Figure 7.16.

A caller specifies an SCTP stream number by filling in the stream. The caller may specify the lifetime of the message in milliseconds in the lifetime field, where 0 represents an infinite lifetime. A user context, if any, may be specified in context. A user context associates a failed message transmission, received via a message notification, with some local application-specific context. For example, to send a message to stream number 1, with the send flags set to MSG_PR_SCTP_TTL, the lifetime set to 1000 milliseconds, a payload protocol identifier of 24, and a context of 52, a user would formulate the following call:

ret = sctp_sendmsg(sockfd,
                   data, datasz, &dest, sizeof(dest),
                   24, MSG_PR_SCTP_TTL, 1, 1000, 52);

This approach is much easier than allocating the necessary ancillary data and setting up the appropriate structures in the msghdr structure. Note that if an implementation maps the sctp_sendmsg to a sendmsg function call, the flags field of the sendmsg call is set to 0.