diff options
Diffstat (limited to 'lib/libc/net/sctp_recvmsg.3')
-rw-r--r-- | lib/libc/net/sctp_recvmsg.3 | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/lib/libc/net/sctp_recvmsg.3 b/lib/libc/net/sctp_recvmsg.3 new file mode 100644 index 0000000..8ddbeb8 --- /dev/null +++ b/lib/libc/net/sctp_recvmsg.3 @@ -0,0 +1,298 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 13, 2007 +.Dt SCTP_RECVMSG 3 +.Os +.Sh NAME +.Nm sctp_recvmsg +.Nd receive a message from an SCTP socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft ssize_t +.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 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 +successful +.Fn connect +call or after the application has performed a +.Fn listen +followed by a successful +.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 +.Fn sendto +and +.Fn sendmsg . +Or, an application may also receive a message after having +called +.Fn listen +with a positive backlog to enable the reception of new associations. +.Pp +The address of the sender is held in the +.Fa from +argument with +.Fa fromlen +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 +the address is bounded by the initial value of +.Fa fromlen +which is used as an in/out variable. +.Pp +The length of the message +.Fa msg +to be received is bounded by +.Fa len . +If the message is too long to fit in the users +receive buffer, then the +.Fa flags +argument will +.Em not +have the +.Dv MSG_EOF +flag applied. +If the message is a complete message then +the +.Fa flags +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 +.Dv MSG_NOTIFICATION . +When this +occurs it indicates that the message received is +.Em not +from +the peer endpoint, but instead is a notification from the +SCTP stack (see +.Xr sctp 4 +for more details). +Note that no notifications are ever +given unless the user subscribes to such notifications using +the +.Dv SCTP_EVENTS +socket option. +.Pp +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. +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. +.Bd -literal +struct sctp_sndrcvinfo { + uint16_t sinfo_stream; /* Stream arriving on */ + uint16_t sinfo_ssn; /* Stream Sequence Number */ + uint16_t sinfo_flags; /* Flags on the incoming message */ + uint32_t sinfo_ppid; /* The ppid field */ + uint32_t sinfo_context; /* context field */ + uint32_t sinfo_timetolive; /* not used by sctp_recvmsg */ + uint32_t sinfo_tsn; /* The transport sequence number */ + uint32_t sinfo_cumtsn; /* The cumulative acknowledgment point */ + sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */ +}; +.Ed +.Pp +The +.Fa sinfo->sinfo_ppid +field is an opaque 32 bit value that is passed transparently +through the stack from the peer endpoint. +Note that the stack passes this value without regard to byte +order. +.Pp +The +.Fa sinfo->sinfo_flags +field may include the following: +.Bd -literal +#define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ +.Ed +.Pp +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 +was delivered in order within the stream it was received. +.Pp +The +.Fa sinfo->sinfo_stream +field is the SCTP stream that the message was received on. +Streams in SCTP are reliable (or partially reliable) flows of ordered +messages. +.Pp +The +.Fa sinfo->sinfo_context +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. +.Pp +The +.Fa sinfo->sinfo_ssn +field will hold the stream sequence number assigned +by the peer endpoint if the message is +.Em not +unordered. +For unordered messages this field holds an undefined value. +.Pp +The +.Fa sinfo->sinfo_tsn +field holds a transport sequence number (TSN) that was assigned +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 TSNs this +value will be one of the TSNs that was used on the +message. +.Pp +The +.Fa sinfo->sinfo_cumtsn +field holds the current cumulative acknowledgment point of +the transport association. +Note that this may be larger +or smaller than the TSN assigned to the message itself. +.Pp +The +.Fa sinfo->sinfo_assoc_id +is the unique association identification that was assigned +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 +setting various socket options on the specific association +(see +.Xr sctp 4 ) . +.Pp +The +.Fa sinfo->info_timetolive +field is not used by +.Fn sctp_recvmsg . +.Sh RETURN VALUES +The call returns the number of bytes received, or -1 +if an error occurred. +.Sh ERRORS +The +.Fn sctp_recvmsg +system call +fails if: +.Bl -tag -width Er +.It Bq Er EBADF +An invalid descriptor was specified. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.It Bq Er EFAULT +An invalid user space address was specified for an argument. +.It Bq Er EMSGSIZE +The socket requires that message be sent atomically, +and the size of the message to be sent made this impossible. +.It Bq Er EAGAIN +The socket is marked non-blocking and the requested operation +would block. +.It Bq Er ENOBUFS +The system was unable to allocate an internal buffer. +The operation may succeed when buffers become available. +.It Bq Er ENOBUFS +The output queue for a network interface was full. +This generally indicates that the interface has stopped sending, +but may be caused by transient congestion. +.It Bq Er EHOSTUNREACH +The remote host was unreachable. +.It Bq Er ENOTCONN +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 +so that the association cannot be located or the +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 +has been set on the socket). +This typically means that the socket +is not connected and is a one-to-one style socket. +.El +.Sh SEE ALSO +.Xr recv 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr write 2 , +.Xr getsockopt 2 , +.Xr setsockopt 2 , +.Xr sctp_send 3 , +.Xr sctp_sendmsg 3 , +.Xr sendmsg 3 , +.Xr sctp 4 |