'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SCTP_SENDMSG 3SOCKET "Aug 22, 2007"
.SH NAME
sctp_sendmsg \- send message from an SCTP socket
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ]
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/sctp.h>

\fBssize_t\fR \fBsctp_sendmsg\fR(\fBint\fR \fIs\fR, \fBconst void *\fR\fImsg\fR, \fBsize_t\fR \fIlen\fR,
     \fBconst struct sockaddr *\fR\fIto\fR, \fBsocklen_t\fR \fItolen\fR, \fBuint32_t\fR \fIppid\fR,
     \fBuint32_t\fR \fIflags\fR, \fBuint16_t\fR \fIstream_no\fR, \fBuint32_t\fR \fItimetolive\fR,
     \fBuint32_t\fR \fIcontext\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsctp_sendmsg()\fR function sends a message from the SCTP endpoint
\fIs\fR.
.sp
.LP
In addition to specifying \fImsg\fR as the message buffer and \fIlen\fR as the
length of the buffer, the following parameters can be set:
.sp
.ne 2
.na
\fB\fIto\fR\fR
.ad
.RS 14n
Destination address
.RE

.sp
.ne 2
.na
\fB\fItolen\fR\fR
.ad
.RS 14n
Length of the destination address
.RE

.sp
.ne 2
.na
\fB\fIppid\fR\fR
.ad
.RS 14n
Application-specified payload protocol identifier
.RE

.sp
.ne 2
.na
\fB\fIstream_no\fR\fR
.ad
.RS 14n
Target stream for the message
.RE

.sp
.ne 2
.na
\fB\fItimetolive\fR\fR
.ad
.RS 14n
Time period in milliseconds after which the message expires if transmission for
the message has not been started. A value of \fB0\fR indicates that the message
does not expire. When the \fBMSG_PR_SCTP\fR flag is set the message expires,
even if transmission has started, unless the entire message is transmitted
within the \fItimetolive\fR period.
.RE

.sp
.ne 2
.na
\fB\fIcontext\fR\fR
.ad
.RS 14n
Value returned when an error occurs in sending a message
.RE

.sp
.LP
The \fIflags\fR parameter is formed from the bitwise OR of zero or more of the
following flags:
.sp
.ne 2
.na
\fBMSG_UNORDERED\fR
.ad
.RS 17n
This flag requests un-ordered delivery of the message. If this flag is clear
the message is considered an ordered send.
.RE

.sp
.ne 2
.na
\fBMSG_ABORT\fR
.ad
.RS 17n
When set, this flag causes the specified association to abort by sending an
ABORT to the peer. The flag is used only for one-to-many style SCTP socket
associations.
.RE

.sp
.ne 2
.na
\fBMSG_EOF\fR
.ad
.RS 17n
When set, this flag invokes a graceful shutdown on a specified association. The
flag is used only for one-to-many style SCTP socket associations.
.RE

.sp
.ne 2
.na
\fBMSG_PR_SCTP\fR
.ad
.RS 17n
This flag indicates that the message is treated as partially reliable. The
message expires unless the entire message is successfully transmitted within
the time period specified in the \fItimetolive\fR parameter.
.sp
\fBMSG_PR_SCTP\fR implements \fItimed reliability\fR service for SCTP messages.
As yet, no common standard has been defined for the service and the interface
is considered unstable.
.RE

.sp
.LP
The initial call to \fBsctp_sendmsg()\fR can be used to create an association,
but it cannot be used subsequently on an existing association. Since
\fBsctp_sendmsg()\fR always uses 0 internally as the association ID, it is not
suitable for use on one-to-many sockets.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, the \fBsctp_sendmsg()\fR function returns the
number of bytes sent. The function returns \fB-1\fR if an error occurs.
.SH ERRORS
.sp
.LP
The \fBsctp_sendmsg()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 16n
The \fIs\fR argument is an invalid file descriptor.
.RE

.sp
.ne 2
.na
\fB\fBENOTSOCK\fR\fR
.ad
.RS 16n
The \fIs\fR argument is not a socket.
.RE

.sp
.ne 2
.na
\fB\fBEOPNOTSUPP\fR\fR
.ad
.RS 16n
\fBMSG_OOB\fR is set as a \fIflag\fR.
.RE

.sp
.ne 2
.na
\fB\fBEOPNOTSUPP\fR\fR
.ad
.RS 16n
\fBMSG_ABORT\fR or \fBMSG_EOF\fR is set on a one-to-one style SCTP socket.
.RE

.sp
.ne 2
.na
\fB\fBEPIPE\fR\fR
.ad
.RS 16n
The socket is shutting down and no more writes are allowed.
.RE

.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 16n
The socket is non-blocking and the transmit queue is full.
.RE

.sp
.ne 2
.na
\fB\fBENOTCONN\fR\fR
.ad
.RS 16n
There is no established association.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 16n
Control message length is incorrect.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 16n
Specified destination address does not belong to the association.
.RE

.sp
.ne 2
.na
\fB\fBEAFNOSUPPORT\fR\fR
.ad
.RS 16n
Address family of the specified destination address is other than \fBAF_INET\fR
or \fBAF_INET6\fR.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBaccept\fR(3SOCKET), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET),
\fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB), \fBlisten\fR(3SOCKET),
\fBsendmsg\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD),
\fBattributes\fR(5), \fBsctp\fR(7P)