1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $FreeBSD$ 33.\" 34.Dd August 13, 2007 35.Dt SCTP_RECVMSG 3 36.Os 37.Sh NAME 38.Nm sctp_recvmsg 39.Nd receive a message from an SCTP socket 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/types.h 44.In sys/socket.h 45.In netinet/sctp.h 46.Ft ssize_t 47.Fo sctp_recvmsg 48.Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from" 49.Fa "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags" 50.Fc 51.Sh DESCRIPTION 52The 53.Fn sctp_recvmsg 54system call 55is used to receive a message from another SCTP endpoint. 56The 57.Fn sctp_recvmsg 58call is used by one-to-one (SOCK_STREAM) type sockets after a 59successful 60.Fn connect 61call or after the application has performed a 62.Fn listen 63followed by a successful 64.Fn accept . 65For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call 66.Fn sctp_recvmsg 67after having implicitly started an association via one 68of the send calls including 69.Fn sctp_sendmsg 70.Fn sendto 71and 72.Fn sendmsg . 73Or, an application may also receive a message after having 74called 75.Fn listen 76with a positive backlog to enable the reception of new associations. 77.Pp 78The address of the sender is held in the 79.Fa from 80argument with 81.Fa fromlen 82specifying its size. 83At the completion of a successful 84.Fn sctp_recvmsg 85call 86.Fa from 87will hold the address of the peer and 88.Fa fromlen 89will hold the length of that address. 90Note that 91the address is bounded by the inital value of 92.Fa fromlen 93which is used as an in/out variable. 94.Pp 95The length of the message 96.Fa msg 97to be received is bounded by 98.Fa len . 99If the message is too long to fit in the users 100receive buffer, then the 101.Fa flags 102argument will 103.Em not 104have the 105.Dv MSG_EOF 106flag applied. 107If the message is a complete message then 108the 109.Fa flags 110argument will have 111.Dv MSG_EOF 112set. 113Locally detected errors are 114indicated by a return value of -1 with 115.Va errno 116set accordingly. 117The 118.Fa flags 119argument may also hold the value 120.Dv MSG_NOTIFICATION . 121When this 122occurs it indicates that the message received is 123.Em not 124from 125the peer endpoint, but instead is a notification from the 126SCTP stack (see 127.Xr sctp 4 128for more details). 129Note that no notifications are ever 130given unless the user subscribes to such notifications using 131the 132.Dv SCTP_EVENTS 133socket option. 134.Pp 135If no messages are available at the socket then 136.Fn sctp_recvmsg 137normally blocks on the reception of a message or NOTIFICATION, unless the 138socket has been placed in non-blocking I/O mode. 139The 140.Xr select 2 141system call may be used to determine when it is possible to 142receive a message. 143.Pp 144The 145.Fa sinfo 146argument is defined as follows. 147.Bd -literal 148struct sctp_sndrcvinfo { 149 u_int16_t sinfo_stream; /* Stream arriving on */ 150 u_int16_t sinfo_ssn; /* Stream Sequence Number */ 151 u_int16_t sinfo_flags; /* Flags on the incoming message */ 152 u_int32_t sinfo_ppid; /* The ppid field */ 153 u_int32_t sinfo_context; /* context field */ 154 u_int32_t sinfo_timetolive; /* not used by sctp_recvmsg */ 155 u_int32_t sinfo_tsn; /* The transport sequence number */ 156 u_int32_t sinfo_cumtsn; /* The cumulative acknowledgment point */ 157 sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */ 158}; 159.Ed 160.Pp 161The 162.Fa sinfo->sinfo_ppid 163is an opaque 32 bit value that is passed transparently 164through the stack from the peer endpoint. 165Note that the stack passes this value without regard to byte 166order. 167.Pp 168The 169.Fa sinfo->sinfo_flags 170field may include the following: 171.Bd -literal 172#define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ 173.Ed 174.Pp 175The 176.Dv SCTP_UNORDERED 177flag is used to specify that the message arrived with no 178specific order and was delivered to the peer application 179as soon as possible. 180When this flag is absent the message 181was delivered in order within the stream it was received. 182.Pp 183.Fa sinfo->sinfo_stream 184is the SCTP stream that the message was received on. 185Streams in SCTP are reliable (or partially reliable) flows of ordered 186messages. 187.Pp 188The 189.Fa sinfo->sinfo_context 190field is used only if the local application set an association level 191context with the 192.Dv SCTP_CONTEXT 193socket option. 194Optionally a user process can use this value to index some application 195specific data structure for all data coming from a specific 196association. 197.Pp 198The 199.Fa sinfo->sinfo_ssn 200will hold the stream sequence number assigned 201by the peer endpoint if the message is 202.Em not 203unordered. 204For unordered messages this field holds an undefined value. 205.Pp 206The 207.Fa sinfo->sinfo_tsn 208holds a transport sequence number (TSN) that was assigned 209to this message by the peer endpoint. 210For messages that fit in or less 211than the path MTU this will be the only TSN assigned. 212Note that for messages that span multiple TSNs this 213value will be one of the TSNs that was used on the 214message. 215.Pp 216The 217.Fa sinfo->sinfo_cumtsn 218holds the current cumulative acknowledgment point of 219the transport association. 220Note that this may be larger 221or smaller than the TSN assigned to the message itself. 222.Pp 223The 224.Fa sinfo->sinfo_assoc_id 225is the unique association identification that was assigned 226to the association. 227For one-to-many (SOCK_SEQPACKET) type 228sockets this value can be used to send data to the peer without 229the use of an address field. 230It is also quite useful in 231setting various socket options on the specific association 232(see 233.Xr sctp 4 ) . 234.Pp 235The 236.Fa sinfo->info_timetolive 237field is not used by 238.Fa sctp_recvmsg . 239.Sh RETURN VALUES 240The call returns the number of characters sent, or -1 241if an error occurred. 242.Sh ERRORS 243The 244.Fn sctp_recvmsg 245system call 246fails if: 247.Bl -tag -width Er 248.It Bq Er EBADF 249An invalid descriptor was specified. 250.It Bq Er ENOTSOCK 251The argument 252.Fa s 253is not a socket. 254.It Bq Er EFAULT 255An invalid user space address was specified for an argument. 256.It Bq Er EMSGSIZE 257The socket requires that message be sent atomically, 258and the size of the message to be sent made this impossible. 259.It Bq Er EAGAIN 260The socket is marked non-blocking and the requested operation 261would block. 262.It Bq Er ENOBUFS 263The system was unable to allocate an internal buffer. 264The operation may succeed when buffers become available. 265.It Bq Er ENOBUFS 266The output queue for a network interface was full. 267This generally indicates that the interface has stopped sending, 268but may be caused by transient congestion. 269.It Bq Er EHOSTUNREACH 270The remote host was unreachable. 271.It Bq Er ENOTCON 272On a one-to-one style socket no association exists. 273.It Bq Er ECONNRESET 274An abort was received by the stack while the user was 275attempting to send data to the peer. 276.It Bq Er ENOENT 277On a one to many style socket no address is specified 278so that the association cannot be located or the 279SCTP_ABORT flag was specified on a non-existing association. 280.It Bq Er EPIPE 281The socket is unable to send anymore data 282.Dv ( SBS_CANTSENDMORE 283has been set on the socket). 284This typically means that the socket 285is not connected and is a one-to-one style socket. 286.El 287.Sh SEE ALSO 288.Xr recv 2 , 289.Xr select 2 , 290.Xr socket 2 , 291.Xr write 2 , 292.Xr getsockopt 2 , 293.Xr setsockopt 2 , 294.Xr sctp_send 3 , 295.Xr sctp_sendmsg 3 , 296.Xr sendmsg 3 , 297.Xr sctp 4 298