d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Major cleanup: mdoc macros, style, typos etc.

Browse Source
This commit is contained in:
Christian Brueffer 2007-06-18 10:20:32 +00:00
parent dfe97ff4a5
commit 16c90ceeb3
10 changed files with 320 additions and 216 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
lib/libc/net/sctp_bindx.3
View File

@ -50,19 +50,24 @@
The The
.Fn sctp_bindx .Fn sctp_bindx
call binds or unbinds a address or a list of addresses to an call binds or unbinds a address or a list of addresses to an
SCTP endpoint. This allows a user to bind a subset of SCTP endpoint.
addresses. The This allows a user to bind a subset of
addresses.
The
.Fn sctp_bindx .Fn sctp_bindx
call operates similarly to call operates similarly to
.Fn bind .Fn bind
but allows a list of addresses and also allows a bind or an but allows a list of addresses and also allows a bind or an
unbind. The argument unbind.
The argument
.Fa s .Fa s
must be a valid SCTP socket descriptor. The argument must be a valid SCTP socket descriptor.
The argument
.Fa addrs .Fa addrs
is a list of addresses (where the list may be only 1 in is a list of addresses (where the list may be only 1 in
length) that the user wishes to bind or unbind to the length) that the user wishes to bind or unbind to the
socket. The argument socket.
The argument
.Fa type .Fa type
must be one of the following values. must be one of the following values.
.Pp .Pp
@ -75,7 +80,8 @@ This value indicates that the listed address(es) need to
be removed from the endpoint. be removed from the endpoint.
.Pp .Pp
Note that when a user adds or deletes an address to an Note that when a user adds or deletes an address to an
association if the dynamic address flag "net.inet.sctp.auto_asconf" association if the dynamic address flag
.Va net.inet.sctp.auto_asconf
is enabled any associations in the endpoint will attempt to is enabled any associations in the endpoint will attempt to
have the address(es) added dynamically to the existing have the address(es) added dynamically to the existing
association. association.
@ -104,6 +110,5 @@ The argument
is not a socket. is not a socket.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 ,
.Xr bind 2 , .Xr bind 2 ,
.Xr sctp 4

16
lib/libc/net/sctp_connectx.3
View File

@ -49,17 +49,20 @@
The The
.Fn sctp_connectx .Fn sctp_connectx
call attempts to initiate an association to a peer SCTP call attempts to initiate an association to a peer SCTP
endpoint. The call operates similarly to endpoint.
The call operates similarly to
.Fn connect .Fn connect
but it also provides the ability to specify multiple destination but it also provides the ability to specify multiple destination
addresses for the peer. This allows a fault tolerant method addresses for the peer.
of initiating an association. When one of the peers addresses This allows a fault tolerant method
of initiating an association.
When one of the peers addresses
is unreachable, the subsequent listed addresses will also be used is unreachable, the subsequent listed addresses will also be used
to setup the association with the peer. to set up the association with the peer.
.Pp .Pp
The user also needs to consider that any address listed in an The user also needs to consider that any address listed in an
.Fn sctp_connectx .Fn sctp_connectx
call is also consider "confirmed". call is also considered "confirmed".
A confirmed address is one in A confirmed address is one in
which the SCTP transport will trust is a part of the association which the SCTP transport will trust is a part of the association
and it will not send a confirmation heartbeat to it with and it will not send a confirmation heartbeat to it with
@ -93,6 +96,5 @@ The argument
is not a socket. is not a socket.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 ,
.Xr connect 2 , .Xr connect 2 ,
.Xr sctp 4

15
lib/libc/net/sctp_freepaddrs.3
View File

@ -36,9 +36,9 @@
.Dt SCTP_FREEPADDRS 3 .Dt SCTP_FREEPADDRS 3
.Os .Os
.Sh NAME .Sh NAME
.Nm sctp_freepaddrs .Nm sctp_freepaddrs ,
.Nm sctp_freeladdrs .Nm sctp_freeladdrs
.Nd release the memory returned from a previous call. .Nd release the memory returned from a previous call
.Sh LIBRARY .Sh LIBRARY
.Lb libc .Lb libc
.Sh SYNOPSIS .Sh SYNOPSIS
@ -49,13 +49,12 @@
.Fn sctp_freepaddrs "struct sockaddr *" .Fn sctp_freepaddrs "struct sockaddr *"
.Ft void .Ft void
.Fn sctp_freeladdrs "struct sockaddr *" .Fn sctp_freeladdrs "struct sockaddr *"
.Sh DESCRIPTION .Sh DESCRIPTION
The function The
.Fn sctp_freepaddrs .Fn sctp_freepaddrs
and and
.Fn sctp_freeladdrs .Fn sctp_freeladdrs
are used to release the memory allocated by previous functions are used to release the memory allocated by previous
calls to calls to
.Fn sctp_getpaddrs .Fn sctp_getpaddrs
or or
@ -63,9 +62,7 @@ or
respectively. respectively.
.Sh RETURN VALUES .Sh RETURN VALUES
none. none.
.El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 ,
.Xr sctp_getpaddrs 3 ,
.Xr sctp_getladdrs 3 , .Xr sctp_getladdrs 3 ,
.Xr sctp_getpaddrs 3 ,
.Xr sctp 4

25
lib/libc/net/sctp_getaddrlen.3
View File

@ -45,20 +45,27 @@
.In sys/socket.h .In sys/socket.h
.In netinet/sctp.h .In netinet/sctp.h
.Ft int .Ft int
.Fn sctp_getaddrlen "sa_family_t family"" .Fn sctp_getaddrlen "sa_family_t family"
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Fn sctp_getaddrlen .Fn sctp_getaddrlen
returns the size of a specific address family. This function function returns the size of a specific address family.
This function
is provided for application binary compatability since it is provided for application binary compatability since it
provides the application with the size the operating system provides the application with the size the operating system
thinks the specific address family is. Note that the function thinks the specific address family is.
Note that the function
will actually create an SCTP socket and then gather the will actually create an SCTP socket and then gather the
information via a information via a
.Fn getsockopt .Fn getsockopt
system calls. If for some reason a SCTP socket cannot system calls.
be created or the getsockopt fails, an error will be returned If for some reason a SCTP socket cannot
with errno set as specified in the be created or the
.Fn getsockopt
call fails, an error will be returned
with
.Va errno
set as specified in the
.Fn socket .Fn socket
or or
.Fn getsockopt .Fn getsockopt
@ -69,12 +76,12 @@ system expects for the specific address family or -1.
.Sh ERRORS .Sh ERRORS
The The
.Fn sctp_getaddrlen .Fn sctp_getaddrlen
function can return the following errors.
.Bl -tag -width Er .Bl -tag -width Er
.It Bq Er EINVAL .It Bq Er EINVAL
The address family specified does NOT exist. The address family specified does NOT exist.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 ,
.Xr socket 2 ,
.Xr getsockopt 2 , .Xr getsockopt 2 ,
.Xr socket 2 ,
.Xr sctp 4

7
lib/libc/net/sctp_getassocid.3
View File

@ -48,12 +48,12 @@
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Fn sctp_getassocid .Fn sctp_getassocid
call attempts to lookup the specified socket address call attempts to look up the specified socket address
.Fa addr .Fa addr
and find the respective association identification. and find the respective association identification.
.Pp .Pp
.Sh RETURN VALUES .Sh RETURN VALUES
The call returns the association id upon success and a The call returns the association id upon success and
0 is returned upon failure. 0 is returned upon failure.
.Sh ERRORS .Sh ERRORS
The The
@ -72,5 +72,4 @@ The argument
is not a socket. is not a socket.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 , .Xr sctp 4

16
lib/libc/net/sctp_getpaddrs.3
View File

@ -36,9 +36,9 @@
.Dt SCTP_GETPADDR 3 .Dt SCTP_GETPADDR 3
.Os .Os
.Sh NAME .Sh NAME
.Nm sctp_getpaddrs .Nm sctp_getpaddrs ,
.Nm sctp_getladdrs .Nm sctp_getladdrs
.Nd return a list of addresses to the caller. .Nd return a list of addresses to the caller
.Sh LIBRARY .Sh LIBRARY
.Lb libc .Lb libc
.Sh SYNOPSIS .Sh SYNOPSIS
@ -58,11 +58,12 @@ The
function is used to get the list of the local addresses. function is used to get the list of the local addresses.
The association of interest is identified by the The association of interest is identified by the
.Fa asocid .Fa asocid
argument. The addresses are returned in a newly allocated argument.
The addresses are returned in a newly allocated
array of socket addresses returned in the argument array of socket addresses returned in the argument
.Fa addrs .Fa addrs
upon success. upon success.
.Pp .Pp
After the caller is through the function After the caller is through the function
.Fn sctp_freepaddrs .Fn sctp_freepaddrs
or or
@ -93,8 +94,7 @@ The argument
is not a socket. is not a socket.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 ,
.Xr sctp_freepaddrs 3 ,
.Xr sctp_freeladdrs 3 ,
.Xr getsockopt 2 , .Xr getsockopt 2 ,
.Xr sctp_freeladdrs 3 ,
.Xr sctp_freepaddrs 3 ,
.Xr sctp 4

22
lib/libc/net/sctp_opt_info.3
View File

@ -53,14 +53,21 @@ call provides a multi-os compatible method for getting
specific specific
.Fn getsockopt .Fn getsockopt
data where an association identification needs to be passed data where an association identification needs to be passed
into the operating system. For FreeBSD a direct into the operating system.
For
.Fx
a direct
.Fn getsockopt .Fn getsockopt
may be used, since FreeBSD has the ability to pass information may be used, since
.Fx
has the ability to pass information
into the operating system on a into the operating system on a
.Fn getsockopt .Fn getsockopt
call. Other operating systems may not have this ability. For those call.
who wish to write portable code amongst multiple operating system Other operating systems may not have this ability.
this call should be used for the for the following sctp For those
who wish to write portable code amongst multiple operating systems
this call should be used for the following SCTP
socket options. socket options.
.Pp .Pp
.Dv SCTP_RTOINFO .Dv SCTP_RTOINFO
@ -83,7 +90,7 @@ socket options.
.Sh ERRORS .Sh ERRORS
The The
.Fn sctp_opt_info .Fn sctp_opt_info
can return the following errors. function can return the following errors.
.Bl -tag -width Er .Bl -tag -width Er
.It Bq Er EINVAL .It Bq Er EINVAL
The argument The argument
@ -104,6 +111,5 @@ The argument
is not a socket. is not a socket.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 ,
.Xr getsockopt 2 , .Xr getsockopt 2 ,
.Xr sctp 4

118
lib/libc/net/sctp_recvmsg.3
View File

@ -44,47 +44,50 @@
.In sys/socket.h .In sys/socket.h
.In netinet/sctp.h .In netinet/sctp.h
.Ft ssize_t .Ft ssize_t
.Ft ssize_t .Fo sctp_recvmsg
.Fn sctp_recvmsg "int s" "void *msg" "size_t len" "struct sockaddr * restrict from" "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags" .Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from"
.Fa "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags"
.Fc
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Fn sctp_recvmsg .Fn sctp_recvmsg
system calls system call
is used to receive a message from another SCTP endpoint. is used to receive a message from another SCTP endpoint.
The The
.Fn sctp_recvmsg .Fn sctp_recvmsg
call is used by one-to-one (SOCK_STREAM) type sockets after a call is used by one-to-one (SOCK_STREAM) type sockets after a
sucessful successful
.Fn connect 2 .Fn connect
call or after the application has performed a call or after the application has performed a
.Fn listen .Fn listen
followed by a sucessful followed by a sucessful
.Fn accept 2 .Fn accept
For a one-to-many (SOCK_SEQPACKET)type socket, an endpoint may call For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
.Fn sctp_recvmsg .Fn sctp_recvmsg
after having implicitly started an association via one after having implicitly started an association via one
of the send calls including of the send calls including
.Fn sctp_sendmsg 2 .Fn sctp_sendmsg
.Fn sendto 2 .Fn sendto
and and
.Fn sendmsg 2 .Fn sendmsg .
Or, an application may also receive a message after having Or, an application may also receive a message after having
called called
.Fn listen 2 .Fn listen
with a postive backlog to enable the reception of new associations. with a postive backlog to enable the reception of new associations.
.Pp .Pp
.Pp
The address of the sender is held in the The address of the sender is held in the
.Fa from .Fa from
argument with argument with
.Fa fromlen .Fa fromlen
specifying its size. At the completion of a sucessful specifying its size.
At the completion of a successful
.Fn sctp_recvmsg .Fn sctp_recvmsg
call call
.Fa from .Fa from
will hold the address of the peer and will hold the address of the peer and
.Fa fromlen .Fa fromlen
will hold the length of that address. Note that will hold the length of that address.
Note that
the address is bounded by the inital value of the address is bounded by the inital value of
.Fa fromlen .Fa fromlen
which is used as an in/out variable. which is used as an in/out variable.
@ -93,36 +96,47 @@ The length of the message
.Fa msg .Fa msg
to be received is bounded by to be received is bounded by
.Fa len . .Fa len .
If the message is to long to fit in the users If the message is too long to fit in the users
receive buffer, then the receive buffer, then the
.Fa flags .Fa flags
argument will NOT have the MSG_EOF flag argument will NOT have the
applied. If the message is a complete message then .Dv MSG_EOF
flag applied.
If the message is a complete message then
the the
.Fa flags .Fa flags
argument will have MSG_EOF set. Locally detected errors are argument will have
indicated by a return value of -1 with errno set accordingly. .Dv MSG_EOF
set.
Locally detected errors are
indicated by a return value of -1 with
.Va errno
set accordingly.
The The
.Fa flags .Fa flags
argument may also hold the value MSG_NOTIFICATION. When this argument may also hold the value
.Dv MSG_NOTIFICATION .
When this
occurs this indicates that the message received is NOT from occurs this indicates that the message received is NOT from
the peer endpoint, but instead is a notification from the the peer endpoint, but instead is a notification from the
SCTP stack (see SCTP stack (see
.Fn sctp 4 .Xr sctp 4
for more details). Note that no notifications are ever for more details).
Note that no notifications are ever
given unless the user subscribes to such notifications using given unless the user subscribes to such notifications using
the SCTP_EVENTS socket option. the
.Dv SCTP_EVENTS
socket option.
.Pp .Pp
If no messages is available at the socket then If no messages are available at the socket then
.Fn sctp_recvmsg .Fn sctp_recvmsg
normally blocks on the reception of a message or NOTIFICATION, unless the socket has been placed in normally blocks on the reception of a message or NOTIFICATION, unless the
non-blocking I/O mode. socket has been placed in non-blocking I/O mode.
The The
.Xr select 2 .Xr select 2
system call may be used to determine when it is possible to system call may be used to determine when it is possible to
receive a message. receive a message.
.Pp .Pp
The The
.Fa sinfo .Fa sinfo
argument is defined as follows. argument is defined as follows.
@ -139,7 +153,7 @@ struct sctp_sndrcvinfo {
sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */ sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */
}; };
.Ed .Ed
.Pp
The The
.Fa sinfo->sinfo_ppid .Fa sinfo->sinfo_ppid
is an opaque 32 bit value that is passed transparently is an opaque 32 bit value that is passed transparently
@ -158,7 +172,8 @@ The
.Dv SCTP_UNORDERED .Dv SCTP_UNORDERED
flag is used to specify that the message arrived with no flag is used to specify that the message arrived with no
specific order and was delivered to the peer application specific order and was delivered to the peer application
as soon as possible. When this flag is absent the message as soon as possible.
When this flag is absent the message
was delivered in order within the stream it was received. was delivered in order within the stream it was received.
.Pp .Pp
.Fa sinfo->sinfo_stream .Fa sinfo->sinfo_stream
@ -166,10 +181,12 @@ is the SCTP stream that the message was received on.
Streams in SCTP are reliable (or partially reliable) flows of ordered Streams in SCTP are reliable (or partially reliable) flows of ordered
messages. messages.
.Pp .Pp
The The
.Fa sinfo->sinfo_context .Fa sinfo->sinfo_context
field is used only if the local application set a association level field is used only if the local application set an association level
context with the SCTP_CONTEXT socket option. context with the
.Dv SCTP_CONTEXT
socket option.
Optionally a user process can use this value to index some application Optionally a user process can use this value to index some application
specific data structure for all data coming from a specific specific data structure for all data coming from a specific
association. association.
@ -183,7 +200,8 @@ For unordered messages this field holds an undefined value.
The The
.Fa sinfo->sinfo_tsn .Fa sinfo->sinfo_tsn
holds a transport sequence number (TSN) that was assigned holds a transport sequence number (TSN) that was assigned
to this message by the peer endpoint. For messages that fit in or less to this message by the peer endpoint.
For messages that fit in or less
than the path MTU this will be the only TSN assigned. than the path MTU this will be the only TSN assigned.
Note that for messages that span multiple TSN's this Note that for messages that span multiple TSN's this
value will be one of the TSN's that was used on the value will be one of the TSN's that was used on the
@ -192,22 +210,25 @@ message.
The The
.Fa sinfo->sinfo_cumtsn .Fa sinfo->sinfo_cumtsn
holds the current cumulative acknowledgment point of holds the current cumulative acknowledgment point of
the transport association. Note that this may be larger the transport association.
Note that this may be larger
or smaller than the TSN assigned to the message itself. or smaller than the TSN assigned to the message itself.
.Pp .Pp
The The
sinfo->sinfo_assoc_id .Fa sinfo->sinfo_assoc_id
is the unique association identification that was assigned is the unique association identification that was assigned
to the association. For one-to-many (SOCK_SEQPACKET) type to the association.
For one-to-many (SOCK_SEQPACKET) type
sockets this value can be used to send data to the peer without sockets this value can be used to send data to the peer without
the use of an address field. It is also quite useful in the use of an address field.
It is also quite useful in
setting various socket options on the specific association setting various socket options on the specific association
(see (see
.Fn sctp 4 .Xr sctp 4
). ).
.Pp .Pp
The The
sinfo->info_timetolive .Fa sinfo->info_timetolive
field is not used by field is not used by
.Fa sctp_recvmsg . .Fa sctp_recvmsg .
.Sh RETURN VALUES .Sh RETURN VALUES
@ -217,7 +238,7 @@ if an error occurred.
The The
.Fn sctp_recvmsg .Fn sctp_recvmsg
system call system call
fail if: fails if:
.Bl -tag -width Er .Bl -tag -width Er
.It Bq Er EBADF .It Bq Er EBADF
An invalid descriptor was specified. An invalid descriptor was specified.
@ -243,7 +264,7 @@ but may be caused by transient congestion.
.It Bq Er EHOSTUNREACH .It Bq Er EHOSTUNREACH
The remote host was unreachable. The remote host was unreachable.
.It Bq Er ENOTCON .It Bq Er ENOTCON
On a one to one style socket no association exists. On a one-to-one style socket no association exists.
.It Bq Er ECONNRESET .It Bq Er ECONNRESET
An abort was received by the stack while the user was An abort was received by the stack while the user was
attempting to send data to the peer. attempting to send data to the peer.
@ -259,14 +280,13 @@ This typically means that the socket
is not connected and is a one-to-one style socket. is not connected and is a one-to-one style socket.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 ,
.Xr sendmsg 3 ,
.Xr sctp_sendmsg 3 ,
.Xr sctp_send 3 ,
.Xr getsockopt 2 ,
.Xr setsockopt 2 ,
.Xr recv 2 , .Xr recv 2 ,
.Xr select 2 , .Xr select 2 ,
.Xr socket 2 , .Xr socket 2 ,
.Xr write 2 .Xr write 2 ,
.Xr getsockopt 2 ,
.Xr setsockopt 2 ,
.Xr sctp_send 3 ,
.Xr sctp_sendmsg 3 ,
.Xr sendmsg 3 ,
.Xr sctp 4

144
lib/libc/net/sctp_send.3
View File

@ -35,7 +35,7 @@
.Dt SCTP_SEND 3 .Dt SCTP_SEND 3
.Os .Os
.Sh NAME .Sh NAME
.Nm sctp_send .Nm sctp_send ,
.Nm sctp_sendx .Nm sctp_sendx
.Nd send a message from an SCTP socket .Nd send a message from an SCTP socket
.Sh LIBRARY .Sh LIBRARY
@ -45,15 +45,20 @@
.In sys/socket.h .In sys/socket.h
.In netinet/sctp.h .In netinet/sctp.h
.Ft ssize_t .Ft ssize_t
.Fn sctp_send "int sd" "const void *msg" "size_t len" "const struct sctp_sndrcvinfo *sinfo" "int flags" .Fo sctp_send
.Fa "int sd" "const void *msg" "size_t len"
.Fa "const struct sctp_sndrcvinfo *sinfo" "int flags"
.Fc
.Ft ssize_t .Ft ssize_t
.Fn sctp_sendx "int sd" "const void *msg" "size_t len" "struct sockaddr *addrs" "int addrcnt" "const struct sctp_sndrcvinfo *sinfo" "int flags" .Fo sctp_sendx
.Fa "int sd" "const void *msg" "size_t len" "struct sockaddr *addrs"
.Fa "int addrcnt" "const struct sctp_sndrcvinfo *sinfo" "int flags"
.Fc
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Fn sctp_send .Fn sctp_send
system calls system call
is used to transmit a message to another SCTP endpoint. is used to transmit a message to another SCTP endpoint.
The
.Fn sctp_send .Fn sctp_send
may be used to send data to an existing association for both may be used to send data to an existing association for both
one-to-many (SOCK_SEQPACKET) and one-to-one (SOCK_STREAM) socket types. one-to-many (SOCK_SEQPACKET) and one-to-one (SOCK_STREAM) socket types.
@ -62,9 +67,11 @@ The length of the message
is given by is given by
.Fa len . .Fa len .
If the message is too long to pass atomically through the If the message is too long to pass atomically through the
underlying protocol, the errno is set to underlying protocol,
.Er EMSGSIZE .Va errno
a -1 is returned, and is set to
.Er EMSGSIZE ,
-1 is returned, and
the message is not transmitted. the message is not transmitted.
.Pp .Pp
No indication of failure to deliver is implicit in a No indication of failure to deliver is implicit in a
@ -77,7 +84,7 @@ the message to be transmitted, then
normally blocks, unless the socket has been placed in normally blocks, unless the socket has been placed in
non-blocking I/O mode. non-blocking I/O mode.
The The
.Fn select 2 .Xr select 2
system call may be used to determine when it is possible to system call may be used to determine when it is possible to
send more data on one-to-one type (SOCK_STREAM) sockets. send more data on one-to-one type (SOCK_STREAM) sockets.
.Pp .Pp
@ -98,13 +105,15 @@ struct sctp_sndrcvinfo {
sctp_assoc_t sinfo_assoc_id; /* The association id */ sctp_assoc_t sinfo_assoc_id; /* The association id */
}; };
.Ed .Ed
.Pp
The The
.Fa sinfo->sinfo_ppid .Fa sinfo->sinfo_ppid
argument is an opaque 32 bit value that is passed transparently argument is an opaque 32 bit value that is passed transparently
through the stack to the peer endpoint. It will be available on through the stack to the peer endpoint. It will be available on
reception of a message (see reception of a message (see
.Fn sctp_recvmsg 2 .Xr sctp_recvmsg 2
). Note that the stack passes this value without regard to byte ).
Note that the stack passes this value without regard to byte
order. order.
.Pp .Pp
The The
@ -126,54 +135,65 @@ argument may include one or more of the following:
The flag The flag
.Dv SCTP_EOF .Dv SCTP_EOF
is used to instruct the SCTP stack to queue this message is used to instruct the SCTP stack to queue this message
and then start a graceful shutdown of the association. All and then start a graceful shutdown of the association.
All
remaining data in queue will be sent after which the association remaining data in queue will be sent after which the association
will be shutdown. will be shut down.
.Pp .Pp
.Dv SCTP_ABORT .Dv SCTP_ABORT
is used to immediately terminate an association. An abort is used to immediately terminate an association.
An abort
is sent to the peer and the local TCB is destroyed. is sent to the peer and the local TCB is destroyed.
.Pp .Pp
.Dv SCTP_UNORDERED .Dv SCTP_UNORDERED
is used to specify that the message being sent has no is used to specify that the message being sent has no
specific order and should be delivered to the peer application specific order and should be delivered to the peer application
as soon as possible. When this flag is absent messages as soon as possible.
When this flag is absent messages
are delivered in order within the stream they are sent, but without are delivered in order within the stream they are sent, but without
respect to order to peer streams. respect to order to peer streams.
.Pp .Pp
The flag The flag
.Dv SCTP_ADDR_OVER .Dv SCTP_ADDR_OVER
is used to specify that an specific address should be used. Normally is used to specify that a specific address should be used.
SCTP will use only one of a multi-homed peers address as the primary Normally
address to send to. By default, no matter what the SCTP will use only one of a multi-homed peers addresses as the primary
address to send to.
By default, no matter what the
.Fa to .Fa to
argument is, this primary address is used to send data. By specifying argument is, this primary address is used to send data.
By specifying
this flag, the user is asking the stack to ignore the primary address this flag, the user is asking the stack to ignore the primary address
and instead use the specified address not only has a lookup mechanism and instead use the specified address not only as a lookup mechanism
to find the association but also has the actual address to send to. to find the association but also as the actual address to send to.
.Pp .Pp
For a one-to-many type (SOCK_SEQPACKET) socket the flag For a one-to-many type (SOCK_SEQPACKET) socket the flag
.Dv SCTP_SENDALL .Dv SCTP_SENDALL
can be used as a convient way to make one send call and have can be used as a convenient way to make one send call and have
all associations that are under the socket get a copy of the message. all associations that are under the socket get a copy of the message.
Note that this mechanism is quite efficent and makes only one actual Note that this mechanism is quite efficent and makes only one actual
copy of the data which is shared by all the associations for sending. copy of the data which is shared by all the associations for sending.
.Pp .Pp
The remaining flags are used for the partial reliabilty extension (RFC3758) The remaining flags are used for the partial reliabilty extension (RFC3758)
and will only be effective if the peer endpoint supports this extension. and will only be effective if the peer endpoint supports this extension.
This option specify's what local policy the local endpoint should use This option specifies what local policy the local endpoint should use
in skipping data. If none of these options are set, then data is in skipping data.
If none of these options are set, then data is
never skipped over. never skipped over.
.Pp .Pp
.Dv SCTP_PR_SCTP_TTL .Dv SCTP_PR_SCTP_TTL
Is used to indicate that a time based lifetime is being applied Is used to indicate that a time based lifetime is being applied
to the data. The to the data.
The
.Fa sinfo->sinfo_timetolive .Fa sinfo->sinfo_timetolive
argument is then a number of milliseconds for which the data is argument is then a number of milliseconds for which the data is
attempted to be transmitted. If that many milliseconds ellapses attempted to be transmitted.
and the peer has not acknowledge the data, the data will be If that many milliseconds ellapse
skipped and no longer transmitted. Note that this policy does and the peer has not acknowledged the data, the data will be
not even assure that the data will ever be sent. In times of a congestion skipped and no longer transmitted.
Note that this policy does
not even assure that the data will ever be sent.
In times of a congestion
with large amounts of data being queued, the with large amounts of data being queued, the
.Fa sinfo->sinfo_timetolive .Fa sinfo->sinfo_timetolive
may expire before the first transmission is ever made. may expire before the first transmission is ever made.
@ -183,8 +203,9 @@ The
based policy transforms the based policy transforms the
.Fa sinfo->sinfo_timetolive .Fa sinfo->sinfo_timetolive
field into a total number of bytes allowed on the outbound field into a total number of bytes allowed on the outbound
send queue. If that number or more bytes are in queue, then send queue.
other buffer based sends are looked to be removed and If that number or more bytes are in queue, then
other buffer-based sends are looked to be removed and
skipped. Note that this policy may also result in the data skipped. Note that this policy may also result in the data
never being sent if no buffer based sends are in queue and never being sent if no buffer based sends are in queue and
the maximum specified by the maximum specified by
@ -195,35 +216,40 @@ The
.Dv SCTP_PR_SCTP_RTX .Dv SCTP_PR_SCTP_RTX
policy transforms the policy transforms the
.Fa sinfo->sinfo_timetolive .Fa sinfo->sinfo_timetolive
into a number of retransmissions to allow. This policy into a number of retransmissions to allow.
This policy
always assures that at a minimum one send attempt is always assures that at a minimum one send attempt is
made of the data. After which no more than made of the data.
After which no more than
.Fa sinfo->sinfo_timetolive .Fa sinfo->sinfo_timetolive
retransmissions will be made before the data is skipped. retransmissions will be made before the data is skipped.
.Pp .Pp
.Fa sinfo->sinfo_stream .Fa sinfo->sinfo_stream
is the SCTP stream that you wish to send the is the SCTP stream that you wish to send the
message on. Streams in SCTP are reliable (or partially reliable) flows of ordered message on.
Streams in SCTP are reliable (or partially reliable) flows of ordered
messages. messages.
.Pp .Pp
The The
.Fa sinfo->sinfo_assoc_id .Fa sinfo->sinfo_assoc_id
field is used to field is used to
select the association to send to on an one-to-many socket. For a select the association to send to on an one-to-many socket.
one-to-one socket, this field is ignored. For a one-to-one socket, this field is ignored.
.Pp .Pp
.Fa sinfo->sinfo_context .Fa sinfo->sinfo_context
field is used only in the event the message cannot be sent. This is an opaque field is used only in the event the message cannot be sent.
This is an opaque
value that the stack retains and will give to the user when a failed send value that the stack retains and will give to the user when a failed send
is given if that notification is enabled (see is given if that notification is enabled (see
.Tn sctp .Xr sctp 4
). Normally a user process can use this value to index some application ).
Normally a user process can use this value to index some application
specific data structure when a send cannot be fulfilled. specific data structure when a send cannot be fulfilled.
.Pp .Pp
The The
.Fa flags .Fa flags
argument holds the same meaning and values has those found in argument holds the same meaning and values as those found in
.Fn sendmsg 2 .Xr sendmsg 2
but is generally ignored by SCTP. but is generally ignored by SCTP.
.Pp .Pp
The fields The fields
@ -232,30 +258,35 @@ The fields
and and
.Fa sinfo->sinfo_cumtsn .Fa sinfo->sinfo_cumtsn
are used only when receiving messages and are thus ignored by are used only when receiving messages and are thus ignored by
.Fn sctp_send. .Fn sctp_send .
The function The function
.Fn sctp_sendx .Fn sctp_sendx
has the same properties as has the same properties as
.Fn sctp_send .Fn sctp_send
with the additional arguments of an array of sockaddr structures with the additional arguments of an array of sockaddr structures
passed in. With the passed in.
With the
.Fa addrs .Fa addrs
argument being given as an array of addresses to be sent to and argument being given as an array of addresses to be sent to and
the the
.Fa addrcnt .Fa addrcnt
argument indicating how many socket addresses are in the passed argument indicating how many socket addresses are in the passed
in array. Note that all of the addresses will only be used in array.
when an implicit association is being setup. This allows the Note that all of the addresses will only be used
when an implicit association is being set up.
This allows the
user the equivilant behavior as doing a user the equivilant behavior as doing a
.Fn sctp_connectx .Fn sctp_connectx
followed by a followed by a
.Fn sctp_send .Fn sctp_send
to the association. Note that if the association id. to the association.
Note that if the
.Fa sinfo->sinfo_assoc_id .Fa sinfo->sinfo_assoc_id
field is 0, then the first address will be used to look up field is 0, then the first address will be used to look up
the association in place of the association id. If both the association in place of the association id.
an address and and association id are specified, the association If both
id has priority. an address and an association id are specified, the association
id has priority.
.Sh RETURN VALUES .Sh RETURN VALUES
The call returns the number of characters sent, or -1 The call returns the number of characters sent, or -1
if an error occurred. if an error occurred.
@ -289,12 +320,12 @@ but may be caused by transient congestion.
.It Bq Er EHOSTUNREACH .It Bq Er EHOSTUNREACH
The remote host was unreachable. The remote host was unreachable.
.It Bq Er ENOTCON .It Bq Er ENOTCON
On a one to one style socket no association exists. On a one-to-one style socket no association exists.
.It Bq Er ECONNRESET .It Bq Er ECONNRESET
An abort was received by the stack while the user was An abort was received by the stack while the user was
attempting to send data to the peer. attempting to send data to the peer.
.It Bq Er ENOENT .It Bq Er ENOENT
On a one to many style socket no address is specified On a one-to-many style socket no address is specified
so that the association cannot be located or the so that the association cannot be located or the
SCTP_ABORT flag was specified on a non-existing association. SCTP_ABORT flag was specified on a non-existing association.
.It Bq Er EPIPE .It Bq Er EPIPE
@ -305,20 +336,19 @@ This typically means that the socket
is not connected and is a one-to-one style socket. is not connected and is a one-to-one style socket.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 ,
.Xr sendmsg 2 ,
.Xr sctp_sendmsg 3 ,
.Xr sctp_recvmsg 3 ,
.Xr sctp_connectx 3 ,
.Xr getsockopt 2 , .Xr getsockopt 2 ,
.Xr recv 2 , .Xr recv 2 ,
.Xr select 2 , .Xr select 2 ,
.Xr sendmsg 2 ,
.Xr socket 2 , .Xr socket 2 ,
.Xr write 2 .Xr write 2
.Xr sctp_connectx 3 ,
.Xr sctp_recvmsg 3 ,
.Xr sctp_sendmsg 3 ,
.Xr sctp 4
.Sh BUGS .Sh BUGS
Because Because
.Fn sctp_send .Fn sctp_send
may have multiple associations under one endpoint, a may have multiple associations under one endpoint, a
select on write will only work for a one-to-one style select on write will only work for a one-to-one style
socket. socket.

152
lib/libc/net/sctp_sendmsg.3
View File

@ -36,7 +36,7 @@
.Dt SCTP_SENDMSG 3 .Dt SCTP_SENDMSG 3
.Os .Os
.Sh NAME .Sh NAME
.Nm sctp_sendmsg .Nm sctp_sendmsg ,
.Nm sctp_sendmsgx .Nm sctp_sendmsgx
.Nd send a message from an SCTP socket .Nd send a message from an SCTP socket
.Sh LIBRARY .Sh LIBRARY
@ -46,31 +46,44 @@
.In sys/socket.h .In sys/socket.h
.In netinet/sctp.h .In netinet/sctp.h
.Ft ssize_t .Ft ssize_t
.Fn sctp_sendmsg "int s" "const void *msg" "size_t len" "const struct sockaddr *to" "socklen_t tolen" "uint32_t ppid" "uint32_t flags" "uint16_t stream_no" "uint32_t timetolive" "uint32_t context" .Fo sctp_sendmsg
.Fa "int s" "const void *msg" "size_t len" "const struct sockaddr *to"
.Fa "socklen_t tolen" "uint32_t ppid" "uint32_t flags" "uint16_t stream_no"
.Fa "uint32_t timetolive" "uint32_t context"
.Fc
.Ft ssize_t .Ft ssize_t
.Fn sctp_sendmsgx "int s" "const void *msg" "size_t len" "const struct sockaddr *to" "int addrcnt" "uint32_t ppid" "uint32_t flags" "uint16_t stream_no" "uint32_t timetolive" "uint32_t context" .Fo sctp_sendmsgx
.Fa "int s" "const void *msg" "size_t len" "const struct sockaddr *to"
.Fa "int addrcnt" "uint32_t ppid" "uint32_t flags" "uint16_t stream_no"
.Fa "uint32_t timetolive" "uint32_t context"
.Fc
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Fn sctp_sendmsg .Fn sctp_sendmsg
system calls system call
is used to transmit a message to another SCTP endpoint. is used to transmit a message to another SCTP endpoint.
The The
.Fn sctp_sendmsg .Fn sctp_sendmsg
may be used at any time. If the socket is a one-to-many type (SOCK_SEQPACKET) may be used at any time.
If the socket is a one-to-many type (SOCK_SEQPACKET)
socket then an attempt to send to an address that no association exists to will socket then an attempt to send to an address that no association exists to will
implicitly create a new association. Data sent in such an instance will result in implicitly create a new association.
the data being sent on the third leg of the SCTP four-way handshake. Note that if Data sent in such an instance will result in
the data being sent on the third leg of the SCTP four-way handshake.
Note that if
the socket is a one-to-one type (SOCK_STREAM) socket then an association must the socket is a one-to-one type (SOCK_STREAM) socket then an association must
be in existance (by use of the be in existance (by use of the
.Fn connect 2 .Xr connect 2
system call). Calling system call).
Calling
.Fn sctp_sendmsg .Fn sctp_sendmsg
or or
.Fn sctp_sendmsgx .Fn sctp_sendmsgx
on a non-connected one-to-one socket will result in the errno being set to on a non-connected one-to-one socket will result in
.Er ENOTCONN .Va errno
a -1 being returned, and the message is not transmitted. being set to
.Er ENOTCONN ,
-1 being returned, and the message not being transmitted.
.Pp .Pp
The address of the target is given by The address of the target is given by
.Fa to .Fa to
@ -82,32 +95,37 @@ The length of the message
is given by is given by
.Fa len . .Fa len .
If the message is too long to pass atomically through the If the message is too long to pass atomically through the
underlying protocol, the errno is set to underlying protocol,
.Er EMSGSIZE .Va errno
a -1 is returned, and is set to
.Er EMSGSIZE ,
-1 is returned, and
the message is not transmitted. the message is not transmitted.
.Pp .Pp
No indication of failure to deliver is implicit in a No indication of failure to deliver is implicit in a
.Fn sctp_sendmsg 2 .Xr sctp_sendmsg 2
call.
Locally detected errors are indicated by a return value of -1. Locally detected errors are indicated by a return value of -1.
.Pp .Pp
If no messages space is available at the socket to hold If no space is available at the socket to hold
the message to be transmitted, then the message to be transmitted, then
.Fn sctp_sendmsg 2 .Xr sctp_sendmsg 2
normally blocks, unless the socket has been placed in normally blocks, unless the socket has been placed in
non-blocking I/O mode. non-blocking I/O mode.
The The
.Fn select 2 .Xr select 2
system call may be used to determine when it is possible to system call may be used to determine when it is possible to
send more data on one-to-one type (SOCK_STREAM) sockets. send more data on one-to-one type (SOCK_STREAM) sockets.
.Pp .Pp
The The
.Fa ppid .Fa ppid
argument is an opaque 32 bit value that is passed transparently argument is an opaque 32 bit value that is passed transparently
through the stack to the peer endpoint. It will be available on through the stack to the peer endpoint.
It will be available on
reception of a message (see reception of a message (see
.Fn sctp_recvmsg 2 .Xr sctp_recvmsg 2
). Note that the stack passes this value without regard to byte ).
Note that the stack passes this value without regard to byte
order. order.
.Pp .Pp
The The
@ -129,31 +147,37 @@ argument may include one or more of the following:
The flag The flag
.Dv SCTP_EOF .Dv SCTP_EOF
is used to instruct the SCTP stack to queue this message is used to instruct the SCTP stack to queue this message
and then start a graceful shutdown of the association. All and then start a graceful shutdown of the association.
All
remaining data in queue will be sent after which the association remaining data in queue will be sent after which the association
will be shutdown. will be shut down.
.Pp .Pp
.Dv SCTP_ABORT .Dv SCTP_ABORT
is used to immediately terminate an association. An abort is used to immediately terminate an association.
An abort
is sent to the peer and the local TCB is destroyed. is sent to the peer and the local TCB is destroyed.
.Pp .Pp
.Dv SCTP_UNORDERED .Dv SCTP_UNORDERED
is used to specify that the message being sent has no is used to specify that the message being sent has no
specific order and should be delivered to the peer application specific order and should be delivered to the peer application
as soon as possible. When this flag is absent messages as soon as possible.
When this flag is absent messages
are delivered in order within the stream they are sent, but without are delivered in order within the stream they are sent, but without
respect to order to peer streams. respect to order to peer streams.
.Pp .Pp
The flag The flag
.Dv SCTP_ADDR_OVER .Dv SCTP_ADDR_OVER
is used to specify that an specific address should be used. Normally is used to specify that an specific address should be used.
SCTP will use only one of a multi-homed peers address as the primary Normally
address to send to. By default, no matter what the SCTP will use only one of a multi-homed peers addresses as the primary
address to send to.
By default, no matter what the
.Fa to .Fa to
argument is, this primary address is used to send data. By specifying argument is, this primary address is used to send data.
By specifying
this flag, the user is asking the stack to ignore the primary address this flag, the user is asking the stack to ignore the primary address
and instead use the specified address not only has a lookup mechanism and instead use the specified address not only as a lookup mechanism
to find the association but also has the actual address to send to. to find the association but also as the actual address to send to.
.Pp .Pp
For a one-to-many type (SOCK_SEQPACKET) socket the flag For a one-to-many type (SOCK_SEQPACKET) socket the flag
.Dv SCTP_SENDALL .Dv SCTP_SENDALL
@ -165,18 +189,23 @@ copy of the data which is shared by all the associations for sending.
The remaining flags are used for the partial reliabilty extension (RFC3758) The remaining flags are used for the partial reliabilty extension (RFC3758)
and will only be effective if the peer endpoint supports this extension. and will only be effective if the peer endpoint supports this extension.
This option specify's what local policy the local endpoint should use This option specify's what local policy the local endpoint should use
in skipping data. If none of these options are set, then data is in skipping data.
If none of these options are set, then data is
never skipped over. never skipped over.
.Pp .Pp
.Dv SCTP_PR_SCTP_TTL .Dv SCTP_PR_SCTP_TTL
Is used to indicate that a time based lifetime is being applied Is used to indicate that a time based lifetime is being applied
to the data. The to the data.
The
.Fa timetolive .Fa timetolive
argument is then a number of milliseconds for which the data is argument is then a number of milliseconds for which the data is
attempted to be transmitted. If that many milliseconds ellapses attempted to be transmitted.
and the peer has not acknowledge the data, the data will be If that many milliseconds ellapse
skipped and no longer transmitted. Note that this policy does and the peer has not acknowledged the data, the data will be
not even assure that the data will ever be sent. In times of a congestion skipped and no longer transmitted.
Note that this policy does
not even assure that the data will ever be sent.
In times of a congestion
with large amounts of data being queued, the with large amounts of data being queued, the
.Fa timetolive .Fa timetolive
may expire before the first transmission is ever made. may expire before the first transmission is ever made.
@ -186,9 +215,11 @@ The
based policy transforms the based policy transforms the
.Fa timetolive .Fa timetolive
field into a total number of bytes allowed on the outbound field into a total number of bytes allowed on the outbound
send queue. If that number or more bytes are in queue, then send queue.
If that number or more bytes are in queue, then
other buffer based sends are looked to be removed and other buffer based sends are looked to be removed and
skipped. Note that this policy may also result in the data skipped.
Note that this policy may also result in the data
never being sent if no buffer based sends are in queue and never being sent if no buffer based sends are in queue and
the maximum specified by the maximum specified by
.Fa timetolive .Fa timetolive
@ -198,22 +229,28 @@ The
.Dv SCTP_PR_SCTP_RTX .Dv SCTP_PR_SCTP_RTX
policy transforms the policy transforms the
.Fa timetolive .Fa timetolive
into a number of retransmissions to allow. This policy into a number of retransmissions to allow.
This policy
always assures that at a minimum one send attempt is always assures that at a minimum one send attempt is
made of the data. After which no more than made of the data.
After which no more than
.Fa timetolive .Fa timetolive
retransmissions will be made before the data is skipped. retransmissions will be made before the data is skipped.
.Pp .Pp
.Fa stream_no .Fa stream_no
is the SCTP stream that you wish to send the is the SCTP stream that you wish to send the
message on. Streams in SCTP are reliable (or partially reliable) flows of ordered message on.
messages. The Streams in SCTP are reliable (or partially reliable) flows of ordered
messages.
The
.Fa context .Fa context
field is used only in the event the message cannot be sent. This is an opaque field is used only in the event the message cannot be sent.
This is an opaque
value that the stack retains and will give to the user when a failed send value that the stack retains and will give to the user when a failed send
is given if that notification is enabled (see is given if that notification is enabled (see
.Tn sctp .Xr sctp 4
). Normally a user process can use this value to index some application ).
Normally a user process can use this value to index some application
specific data structure when a send cannot be fulfilled. specific data structure when a send cannot be fulfilled.
.Fn sctp_sendmsgx .Fn sctp_sendmsgx
is identical to is identical to
@ -223,7 +260,8 @@ argument
.Fa to .Fa to
and adds the additional argument and adds the additional argument
.Fa addrcnt .Fa addrcnt
which specifies how many addresses are in the array. This allows a which specifies how many addresses are in the array.
This allows a
caller to implictly setup an association passing multiple addresses caller to implictly setup an association passing multiple addresses
as if an as if an
.Fn sctp_connectx .Fn sctp_connectx
@ -261,14 +299,15 @@ but may be caused by transient congestion.
.It Bq Er EHOSTUNREACH .It Bq Er EHOSTUNREACH
The remote host was unreachable. The remote host was unreachable.
.It Bq Er ENOTCON .It Bq Er ENOTCON
On a one to one style socket no association exists. On a one-to-one style socket no association exists.
.It Bq Er ECONNRESET .It Bq Er ECONNRESET
An abort was received by the stack while the user was An abort was received by the stack while the user was
attempting to send data to the peer. attempting to send data to the peer.
.It Bq Er ENOENT .It Bq Er ENOENT
On a one to many style socket no address is specified On a one-to-many style socket no address is specified
so that the association cannot be located or the so that the association cannot be located or the
SCTP_ABORT flag was specified on a non-existing association. .Dv SCTP_ABORT
flag was specified on a non-existing association.
.It Bq Er EPIPE .It Bq Er EPIPE
The socket is unable to send anymore data The socket is unable to send anymore data
.Dv ( SBS_CANTSENDMORE .Dv ( SBS_CANTSENDMORE
@ -277,15 +316,15 @@ This typically means that the socket
is not connected and is a one-to-one style socket. is not connected and is a one-to-one style socket.
.El .El
.Sh SEE ALSO .Sh SEE ALSO
.Xr sctp 4 ,
.Xr sendmsg 3 ,
.Xr connect 2 , .Xr connect 2 ,
.Xr sctp_connectx 3 ,
.Xr getsockopt 2 , .Xr getsockopt 2 ,
.Xr recv 2 , .Xr recv 2 ,
.Xr select 2 , .Xr select 2 ,
.Xr socket 2 , .Xr socket 2 ,
.Xr write 2 .Xr write 2 ,
.Xr sendmsg 3 ,
.Xr sctp_connectx 3 ,
.Xr sctp 4
.Sh BUGS .Sh BUGS
Because in the one-to-many style socket the Because in the one-to-many style socket the
.Fn sctp_sendmsg .Fn sctp_sendmsg
@ -294,4 +333,3 @@ or
may have multiple associations under one endpoint, a may have multiple associations under one endpoint, a
select on write will only work for a one-to-one style select on write will only work for a one-to-one style
socket. socket.