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