diff options
Diffstat (limited to 'lib/libc/net/sctp_recvmsg.3')
| -rw-r--r-- | lib/libc/net/sctp_recvmsg.3 | 272 |
1 files changed, 272 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..4a085da --- /dev/null +++ b/lib/libc/net/sctp_recvmsg.3 @@ -0,0 +1,272 @@ +.\" 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 December 15, 2006 +.Dt SCTP_RECVMSG 3 +.Os +.Sh NAME +.Nm sctp_recvmsg +.Nd send 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 +.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" +.Sh DESCRIPTION +The +.Fn sctp_recvmsg +system calls +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 +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 sctp_recvmsg +after having implicitly started an association via one +of the send calls including +.Fn sctp_sendmsg 2 +.Fn sendto 2 +and +.Fn sendmsg 2 +Or, an application may also receive a message after having +called +.Fn listen 2 +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 +.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 inital 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 to 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 +the +.Fa flags +argument will have MSG_EOF set. Locally detected errors are +indicated by a return value of -1 with errno set accordingly. +The +.Fa flags +argument may also hold the value 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 +given unless the user subscribes to such notifications using +the SCTP_EVENTS socket option. +.Pp +If no messages is 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 { + u_int16_t sinfo_stream; /* Stream arriving on */ + u_int16_t sinfo_ssn; /* Stream Sequence Number */ + u_int16_t sinfo_flags; /* Flags on the incoming message */ + u_int32_t sinfo_ppid; /* The ppid field */ + u_int32_t sinfo_context; /* context field */ + u_int32_t sinfo_timetolive; /* not used by sctp_recvmsg */ + u_int32_t sinfo_tsn; /* The transport sequence number */ + u_int32_t sinfo_cumtsn; /* The cumulative acknowledgment point */ + sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */ +}; +.Ed + +The +.Fa sinfo->sinfo_ppid +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 +.Fa sinfo->sinfo_stream +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 a association level +context with the 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 +will hold the stream sequence number assigned +by the peer endpoint if the message is NOT unordered. +For unordered messages this field holds an undefined value. +.Pp +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 +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 +message. +.Pp +The +.Fa sinfo->sinfo_cumtsn +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 +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 +.Fn sctp 4 +). +.Pp +The +sinfo->info_timetolive +field is not used by +.Fa sctp_recvmsg . +.Sh RETURN VALUES +The call returns the number of characters sent, or -1 +if an error occurred. +.Sh ERRORS +The +.Fn sctp_recvmsg +system call +fail 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 ENOTCON +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 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 + |
