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
.Fn sctp_bindx
call binds or unbinds a address or a list of addresses to an
SCTP endpoint. This allows a user to bind a subset of
addresses. The
SCTP endpoint.
This allows a user to bind a subset of
addresses.
The
.Fn sctp_bindx
call operates similarly to
.Fn bind
but allows a list of addresses and also allows a bind or an
unbind. The argument
unbind.
The argument
.Fa s
must be a valid SCTP socket descriptor. The argument
must be a valid SCTP socket descriptor.
The argument
.Fa addrs
is a list of addresses (where the list may be only 1 in
length) that the user wishes to bind or unbind to the
socket. The argument
socket.
The argument
.Fa type
must be one of the following values.
.Pp
@ -75,7 +80,8 @@ This value indicates that the listed address(es) need to
be removed from the endpoint.
.Pp
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
have the address(es) added dynamically to the existing
association.
@ -104,6 +110,5 @@ The argument
is not a socket.
.El
.Sh SEE ALSO
.Xr sctp 4 ,
.Xr bind 2 ,
.Xr sctp 4

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

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

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

@ -36,9 +36,9 @@
.Dt SCTP_FREEPADDRS 3
.Os
.Sh NAME
.Nm sctp_freepaddrs
.Nm sctp_freepaddrs ,
.Nm sctp_freeladdrs
.Nd release the memory returned from a previous call.
.Nd release the memory returned from a previous call
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
@ -49,13 +49,12 @@
.Fn sctp_freepaddrs "struct sockaddr *"
.Ft void
.Fn sctp_freeladdrs "struct sockaddr *"
.Sh DESCRIPTION
The function
The
.Fn sctp_freepaddrs
and
.Fn sctp_freeladdrs
are used to release the memory allocated by previous
functions are used to release the memory allocated by previous
calls to
.Fn sctp_getpaddrs
or
@ -63,9 +62,7 @@ or
respectively.
.Sh RETURN VALUES
none.
.El
.Sh SEE ALSO
.Xr sctp 4 ,
.Xr sctp_getpaddrs 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 netinet/sctp.h
.Ft int
.Fn sctp_getaddrlen "sa_family_t family""
.Fn sctp_getaddrlen "sa_family_t family"
.Sh DESCRIPTION
The
.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
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
information via a
.Fn getsockopt
system calls. If for some reason a SCTP socket cannot
be created or the getsockopt fails, an error will be returned
with errno set as specified in the
system calls.
If for some reason a SCTP socket cannot
be created or the
.Fn getsockopt
call fails, an error will be returned
with
.Va errno
set as specified in the
.Fn socket
or
.Fn getsockopt
@ -69,12 +76,12 @@ system expects for the specific address family or -1.
.Sh ERRORS
The
.Fn sctp_getaddrlen
function can return the following errors.
.Bl -tag -width Er
.It Bq Er EINVAL
The address family specified does NOT exist.
.El
.Sh SEE ALSO
.Xr sctp 4 ,
.Xr socket 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
The
.Fn sctp_getassocid
call attempts to lookup the specified socket address
call attempts to look up the specified socket address
.Fa addr
and find the respective association identification.
.Pp
.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.
.Sh ERRORS
The
@ -72,5 +72,4 @@ The argument
is not a socket.
.El
.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
.Os
.Sh NAME
.Nm sctp_getpaddrs
.Nm sctp_getpaddrs ,
.Nm sctp_getladdrs
.Nd return a list of addresses to the caller.
.Nd return a list of addresses to the caller
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
@ -58,11 +58,12 @@ The
function is used to get the list of the local addresses.
The association of interest is identified by the
.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
.Fa addrs
upon success.
.Pp
.Pp
After the caller is through the function
.Fn sctp_freepaddrs
or
@ -93,8 +94,7 @@ The argument
is not a socket.
.El
.Sh SEE ALSO
.Xr sctp 4 ,
.Xr sctp_freepaddrs 3 ,
.Xr sctp_freeladdrs 3 ,
.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
.Fn getsockopt
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
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
.Fn getsockopt
call. Other operating systems may not have this ability. For those
who wish to write portable code amongst multiple operating system
this call should be used for the for the following sctp
call.
Other operating systems may not have this ability.
For those
who wish to write portable code amongst multiple operating systems
this call should be used for the following SCTP
socket options.
.Pp
.Dv SCTP_RTOINFO
@ -83,7 +90,7 @@ socket options.
.Sh ERRORS
The
.Fn sctp_opt_info
can return the following errors.
function can return the following errors.
.Bl -tag -width Er
.It Bq Er EINVAL
The argument
@ -104,6 +111,5 @@ The argument
is not a socket.
.El
.Sh SEE ALSO
.Xr sctp 4 ,
.Xr getsockopt 2 ,
.Xr sctp 4

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

@ -44,47 +44,50 @@
.In sys/socket.h
.In netinet/sctp.h
.Ft ssize_t
.Ft ssize_t
.Fn sctp_recvmsg "int s" "void *msg" "size_t len" "struct sockaddr * restrict from" "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags"
.Fo sctp_recvmsg
.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
The
.Fn sctp_recvmsg
system calls
system call
is used to receive a message from another SCTP endpoint.
The
.Fn sctp_recvmsg
call is used by one-to-one (SOCK_STREAM) type sockets after a
sucessful
.Fn connect 2
successful
.Fn connect
call or after the application has performed a
.Fn listen
followed by a sucessful
.Fn accept 2
For a one-to-many (SOCK_SEQPACKET)type socket, an endpoint may call
.Fn accept
For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
.Fn sctp_recvmsg
after having implicitly started an association via one
of the send calls including
.Fn sctp_sendmsg 2
.Fn sendto 2
.Fn sctp_sendmsg
.Fn sendto
and
.Fn sendmsg 2
.Fn sendmsg .
Or, an application may also receive a message after having
called
.Fn listen 2
.Fn listen
with a postive backlog to enable the reception of new associations.
.Pp
.Pp
The address of the sender is held in the
.Fa from
argument with
.Fa fromlen
specifying its size. At the completion of a sucessful
specifying its size.
At the completion of a successful
.Fn sctp_recvmsg
call
.Fa from
will hold the address of the peer and
.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
.Fa fromlen
which is used as an in/out variable.
@ -93,36 +96,47 @@ The length of the message
.Fa msg
to be received is bounded by
.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
.Fa flags
argument will NOT have the MSG_EOF flag
applied. If the message is a complete message then
argument will NOT have the
.Dv MSG_EOF
flag applied.
If the message is a complete message then
the
.Fa flags
argument will have MSG_EOF set. Locally detected errors are
indicated by a return value of -1 with errno set accordingly.
argument will have
.Dv MSG_EOF
set.
Locally detected errors are
indicated by a return value of -1 with
.Va errno
set accordingly.
The
.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
the peer endpoint, but instead is a notification from the
SCTP stack (see
.Fn sctp 4
for more details). Note that no notifications are ever
.Xr sctp 4
for more details).
Note that no notifications are ever
given unless the user subscribes to such notifications using
the SCTP_EVENTS socket option.
the
.Dv SCTP_EVENTS
socket option.
.Pp
If no messages is available at the socket then
If no messages are available at the socket then
.Fn sctp_recvmsg
normally blocks on the reception of a message or NOTIFICATION, unless the socket has been placed in
non-blocking I/O mode.
normally blocks on the reception of a message or NOTIFICATION, unless the
socket has been placed in non-blocking I/O mode.
The
.Xr select 2
system call may be used to determine when it is possible to
receive a message.
.Pp
The
.Fa sinfo
argument is defined as follows.
@ -139,7 +153,7 @@ struct sctp_sndrcvinfo {
sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */
};
.Ed
.Pp
The
.Fa sinfo->sinfo_ppid
is an opaque 32 bit value that is passed transparently
@ -158,7 +172,8 @@ The
.Dv SCTP_UNORDERED
flag is used to specify that the message arrived with no
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.
.Pp
.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
messages.
.Pp
The
The
.Fa sinfo->sinfo_context
field is used only if the local application set a association level
context with the SCTP_CONTEXT socket option.
field is used only if the local application set an association level
context with the
.Dv SCTP_CONTEXT
socket option.
Optionally a user process can use this value to index some application
specific data structure for all data coming from a specific
association.
@ -183,7 +200,8 @@ For unordered messages this field holds an undefined value.
The
.Fa sinfo->sinfo_tsn
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.
Note that for messages that span multiple TSN's this
value will be one of the TSN's that was used on the
@ -192,22 +210,25 @@ message.
The
.Fa sinfo->sinfo_cumtsn
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.
.Pp
The
sinfo->sinfo_assoc_id
.Fa sinfo->sinfo_assoc_id
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
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
(see
.Fn sctp 4
.Xr sctp 4
).
.Pp
The
sinfo->info_timetolive
.Fa sinfo->info_timetolive
field is not used by
.Fa sctp_recvmsg .
.Sh RETURN VALUES
@ -217,7 +238,7 @@ if an error occurred.
The
.Fn sctp_recvmsg
system call
fail if:
fails if:
.Bl -tag -width Er
.It Bq Er EBADF
An invalid descriptor was specified.
@ -243,7 +264,7 @@ but may be caused by transient congestion.
.It Bq Er EHOSTUNREACH
The remote host was unreachable.
.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
An abort was received by the stack while the user was
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.
.El
.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 select 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
.Os
.Sh NAME
.Nm sctp_send
.Nm sctp_send ,
.Nm sctp_sendx
.Nd send a message from an SCTP socket
.Sh LIBRARY
@ -45,15 +45,20 @@
.In sys/socket.h
.In netinet/sctp.h
.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
.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
The
.Fn sctp_send
system calls
system call
is used to transmit a message to another SCTP endpoint.
The
.Fn sctp_send
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.
@ -62,9 +67,11 @@ The length of the message
is given by
.Fa len .
If the message is too long to pass atomically through the
underlying protocol, the errno is set to
.Er EMSGSIZE
a -1 is returned, and
underlying protocol,
.Va errno
is set to
.Er EMSGSIZE ,
-1 is returned, and
the message is not transmitted.
.Pp
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
non-blocking I/O mode.
The
.Fn select 2
.Xr select 2
system call may be used to determine when it is possible to
send more data on one-to-one type (SOCK_STREAM) sockets.
.Pp
@ -98,13 +105,15 @@ struct sctp_sndrcvinfo {
sctp_assoc_t sinfo_assoc_id; /* The association id */
};
.Ed
.Pp
The
.Fa sinfo->sinfo_ppid
argument is an opaque 32 bit value that is passed transparently
through the stack to the peer endpoint. It will be available on
reception of a message (see
.Fn sctp_recvmsg 2
). Note that the stack passes this value without regard to byte
.Xr sctp_recvmsg 2
).
Note that the stack passes this value without regard to byte
order.
.Pp
The
@ -126,54 +135,65 @@ argument may include one or more of the following:
The flag
.Dv SCTP_EOF
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
will be shutdown.
will be shut down.
.Pp
.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.
.Pp
.Dv SCTP_UNORDERED
is used to specify that the message being sent has no
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
respect to order to peer streams.
.Pp
The flag
.Dv SCTP_ADDR_OVER
is used to specify that an specific address should be used. Normally
SCTP will use only one of a multi-homed peers address as the primary
address to send to. By default, no matter what the
is used to specify that a specific address should be used.
Normally
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
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
and instead use the specified address not only has a lookup mechanism
to find the association but also has the actual address to send to.
and instead use the specified address not only as a lookup mechanism
to find the association but also as the actual address to send to.
.Pp
For a one-to-many type (SOCK_SEQPACKET) socket the flag
.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.
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.
.Pp
The remaining flags are used for the partial reliabilty extension (RFC3758)
and will only be effective if the peer endpoint supports this extension.
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
This option specifies what local policy the local endpoint should use
in skipping data.
If none of these options are set, then data is
never skipped over.
.Pp
.Dv SCTP_PR_SCTP_TTL
Is used to indicate that a time based lifetime is being applied
to the data. The
to the data.
The
.Fa sinfo->sinfo_timetolive
argument is then a number of milliseconds for which the data is
attempted to be transmitted. If that many milliseconds ellapses
and the peer has not acknowledge the data, the data will be
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
attempted to be transmitted.
If that many milliseconds ellapse
and the peer has not acknowledged the data, the data will be
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
.Fa sinfo->sinfo_timetolive
may expire before the first transmission is ever made.
@ -183,8 +203,9 @@ The
based policy transforms the
.Fa sinfo->sinfo_timetolive
field into a total number of bytes allowed on the outbound
send queue. If that number or more bytes are in queue, then
other buffer based sends are looked to be removed and
send queue.
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
never being sent if no buffer based sends are in queue and
the maximum specified by
@ -195,35 +216,40 @@ The
.Dv SCTP_PR_SCTP_RTX
policy transforms the
.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
made of the data. After which no more than
made of the data.
After which no more than
.Fa sinfo->sinfo_timetolive
retransmissions will be made before the data is skipped.
.Pp
.Fa sinfo->sinfo_stream
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.
.Pp
The
.Fa sinfo->sinfo_assoc_id
field is used to
select the association to send to on an one-to-many socket. For a
one-to-one socket, this field is ignored.
select the association to send to on an one-to-many socket.
For a one-to-one socket, this field is ignored.
.Pp
.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
is given if that notification is enabled (see
.Tn sctp
). Normally a user process can use this value to index some application
.Xr sctp 4
).
Normally a user process can use this value to index some application
specific data structure when a send cannot be fulfilled.
.Pp
The
.Fa flags
argument holds the same meaning and values has those found in
.Fn sendmsg 2
argument holds the same meaning and values as those found in
.Xr sendmsg 2
but is generally ignored by SCTP.
.Pp
The fields
@ -232,30 +258,35 @@ The fields
and
.Fa sinfo->sinfo_cumtsn
are used only when receiving messages and are thus ignored by
.Fn sctp_send.
.Fn sctp_send .
The function
.Fn sctp_sendx
has the same properties as
.Fn sctp_send
with the additional arguments of an array of sockaddr structures
passed in. With the
passed in.
With the
.Fa addrs
argument being given as an array of addresses to be sent to and
the
.Fa addrcnt
argument indicating how many socket addresses are in the passed
in array. Note that all of the addresses will only be used
when an implicit association is being setup. This allows the
in array.
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
.Fn sctp_connectx
followed by a
.Fn sctp_send
to the association. Note that if the association id.
to the association.
Note that if the
.Fa sinfo->sinfo_assoc_id
field is 0, then the first address will be used to look up
the association in place of the association id. If both
an address and and association id are specified, the association
id has priority.
the association in place of the association id.
If both
an address and an association id are specified, the association
id has priority.
.Sh RETURN VALUES
The call returns the number of characters sent, or -1
if an error occurred.
@ -289,12 +320,12 @@ but may be caused by transient congestion.
.It Bq Er EHOSTUNREACH
The remote host was unreachable.
.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
An abort was received by the stack while the user was
attempting to send data to the peer.
.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
SCTP_ABORT flag was specified on a non-existing association.
.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.
.El
.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 recv 2 ,
.Xr select 2 ,
.Xr sendmsg 2 ,
.Xr socket 2 ,
.Xr write 2
.Xr sctp_connectx 3 ,
.Xr sctp_recvmsg 3 ,
.Xr sctp_sendmsg 3 ,
.Xr sctp 4
.Sh BUGS
Because
.Fn sctp_send
may have multiple associations under one endpoint, a
select on write will only work for a one-to-one style
socket.

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

@ -36,7 +36,7 @@
.Dt SCTP_SENDMSG 3
.Os
.Sh NAME
.Nm sctp_sendmsg
.Nm sctp_sendmsg ,
.Nm sctp_sendmsgx
.Nd send a message from an SCTP socket
.Sh LIBRARY
@ -46,31 +46,44 @@
.In sys/socket.h
.In netinet/sctp.h
.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
.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
The
.Fn sctp_sendmsg
system calls
system call
is used to transmit a message to another SCTP endpoint.
The
.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
implicitly create a new association. 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
implicitly create a new association.
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
be in existance (by use of the
.Fn connect 2
system call). Calling
.Xr connect 2
system call).
Calling
.Fn sctp_sendmsg
or
.Fn sctp_sendmsgx
on a non-connected one-to-one socket will result in the errno being set to
.Er ENOTCONN
a -1 being returned, and the message is not transmitted.
on a non-connected one-to-one socket will result in
.Va errno
being set to
.Er ENOTCONN ,
-1 being returned, and the message not being transmitted.
.Pp
The address of the target is given by
.Fa to
@ -82,32 +95,37 @@ The length of the message
is given by
.Fa len .
If the message is too long to pass atomically through the
underlying protocol, the errno is set to
.Er EMSGSIZE
a -1 is returned, and
underlying protocol,
.Va errno
is set to
.Er EMSGSIZE ,
-1 is returned, and
the message is not transmitted.
.Pp
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.
.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
.Fn sctp_sendmsg 2
.Xr sctp_sendmsg 2
normally blocks, unless the socket has been placed in
non-blocking I/O mode.
The
.Fn select 2
.Xr select 2
system call may be used to determine when it is possible to
send more data on one-to-one type (SOCK_STREAM) sockets.
.Pp
The
.Fa ppid
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
.Fn sctp_recvmsg 2
). Note that the stack passes this value without regard to byte
.Xr sctp_recvmsg 2
).
Note that the stack passes this value without regard to byte
order.
.Pp
The
@ -129,31 +147,37 @@ argument may include one or more of the following:
The flag
.Dv SCTP_EOF
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
will be shutdown.
will be shut down.
.Pp
.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.
.Pp
.Dv SCTP_UNORDERED
is used to specify that the message being sent has no
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
respect to order to peer streams.
.Pp
The flag
.Dv SCTP_ADDR_OVER
is used to specify that an specific address should be used. Normally
SCTP will use only one of a multi-homed peers address as the primary
address to send to. By default, no matter what the
is used to specify that an specific address should be used.
Normally
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
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
and instead use the specified address not only has a lookup mechanism
to find the association but also has the actual address to send to.
and instead use the specified address not only as a lookup mechanism
to find the association but also as the actual address to send to.
.Pp
For a one-to-many type (SOCK_SEQPACKET) socket the flag
.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)
and will only be effective if the peer endpoint supports this extension.
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.
.Pp
.Dv SCTP_PR_SCTP_TTL
Is used to indicate that a time based lifetime is being applied
to the data. The
to the data.
The
.Fa timetolive
argument is then a number of milliseconds for which the data is
attempted to be transmitted. If that many milliseconds ellapses
and the peer has not acknowledge the data, the data will be
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
attempted to be transmitted.
If that many milliseconds ellapse
and the peer has not acknowledged the data, the data will be
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
.Fa timetolive
may expire before the first transmission is ever made.
@ -186,9 +215,11 @@ The
based policy transforms the
.Fa timetolive
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
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
the maximum specified by
.Fa timetolive
@ -198,22 +229,28 @@ The
.Dv SCTP_PR_SCTP_RTX
policy transforms the
.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
made of the data. After which no more than
made of the data.
After which no more than
.Fa timetolive
retransmissions will be made before the data is skipped.
.Pp
.Fa stream_no
is the SCTP stream that you wish to send the
message on. Streams in SCTP are reliable (or partially reliable) flows of ordered
messages. The
message on.
Streams in SCTP are reliable (or partially reliable) flows of ordered
messages.
The
.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
is given if that notification is enabled (see
.Tn sctp
). Normally a user process can use this value to index some application
.Xr sctp 4
).
Normally a user process can use this value to index some application
specific data structure when a send cannot be fulfilled.
.Fn sctp_sendmsgx
is identical to
@ -223,7 +260,8 @@ argument
.Fa to
and adds the additional argument
.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
as if an
.Fn sctp_connectx
@ -261,14 +299,15 @@ but may be caused by transient congestion.
.It Bq Er EHOSTUNREACH
The remote host was unreachable.
.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
An abort was received by the stack while the user was
attempting to send data to the peer.
.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
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
The socket is unable to send anymore data
.Dv ( SBS_CANTSENDMORE
@ -277,15 +316,15 @@ This typically means that the socket
is not connected and is a one-to-one style socket.
.El
.Sh SEE ALSO
.Xr sctp 4 ,
.Xr sendmsg 3 ,
.Xr connect 2 ,
.Xr sctp_connectx 3 ,
.Xr getsockopt 2 ,
.Xr recv 2 ,
.Xr select 2 ,
.Xr socket 2 ,
.Xr write 2
.Xr write 2 ,
.Xr sendmsg 3 ,
.Xr sctp_connectx 3 ,
.Xr sctp 4
.Sh BUGS
Because in the one-to-many style socket the
.Fn sctp_sendmsg
@ -294,4 +333,3 @@ or
may have multiple associations under one endpoint, a
select on write will only work for a one-to-one style
socket.