1.\" $NetBSD: sctp_recvmsg.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd August 1, 2018 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 55.Dv ( SOCK_STREAM ) 56type sockets after a successful 57.Fn connect 58call or after the application has performed a 59.Fn listen 60followed by a successful 61.Fn accept . 62For a one-to-many 63.Dv ( SOCK_SEQPACKET ) 64type socket, an endpoint may call 65.Fn sctp_recvmsg 66after having implicitly started an association via one 67of the send calls including 68.Fn sctp_sendmsg , 69.Fn sendto , 70and 71.Fn sendmsg . 72Or, an application may also receive a message after having 73called 74.Fn listen 75with a positive backlog to enable the reception of new associations. 76.Pp 77The address of the sender is held in the 78.Fa from 79argument with 80.Fa fromlen 81specifying its size. 82At the completion of a successful 83.Fn sctp_recvmsg 84call 85.Fa from 86will hold the address of the peer and 87.Fa fromlen 88will hold the length of that address. 89Note that 90the address is bounded by the initial value of 91.Fa fromlen 92which is used as an in/out variable. 93.Pp 94The length of the message 95.Fa msg 96to be received is bounded by 97.Fa len . 98If the message is too long to fit in the users 99receive buffer, then the 100.Fa flags 101argument will 102.Em not 103have the 104.Dv MSG_EOF 105flag applied. 106If the message is a complete message then 107the 108.Fa flags 109argument will have 110.Dv MSG_EOF 111set. 112Locally detected errors are 113indicated by a return value of \-1 with 114.Va errno 115set accordingly. 116The 117.Fa flags 118argument may also hold the value 119.Dv MSG_NOTIFICATION . 120When this 121occurs it indicates that the message received is 122.Em not 123from 124the peer endpoint, but instead is a notification from the 125SCTP stack (see 126.Xr sctp 4 127for more details). 128Note that no notifications are ever 129given unless the user subscribes to such notifications using 130the 131.Dv SCTP_EVENTS 132socket option. 133.Pp 134If no messages are available at the socket then 135.Fn sctp_recvmsg 136normally blocks on the reception of a message or NOTIFICATION, unless the 137socket has been placed in non-blocking I/O mode. 138The 139.Xr select 2 140system call may be used to determine when it is possible to 141receive a message. 142.Pp 143The 144.Fa sinfo 145argument is defined as follows. 146.Bd -literal 147struct sctp_sndrcvinfo { 148 uint16_t sinfo_stream; /* Stream arriving on */ 149 uint16_t sinfo_ssn; /* Stream Sequence Number */ 150 uint16_t sinfo_flags; /* Flags on the incoming message */ 151 uint32_t sinfo_ppid; /* The ppid field */ 152 uint32_t sinfo_context; /* context field */ 153 uint32_t sinfo_timetolive; /* not used by sctp_recvmsg */ 154 uint32_t sinfo_tsn; /* The transport sequence number */ 155 uint32_t sinfo_cumtsn; /* The cumulative acknowledgment point */ 156 sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */ 157}; 158.Ed 159.Pp 160The 161.Fa sinfo->sinfo_ppid 162field is an opaque 32 bit value that is passed transparently 163through the stack from the peer endpoint. 164Note that the stack passes this value without regard to byte 165order. 166.Pp 167The 168.Fa sinfo->sinfo_flags 169field may include the following: 170.Bd -literal 171#define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ 172.Ed 173.Pp 174The 175.Dv SCTP_UNORDERED 176flag is used to specify that the message arrived with no 177specific order and was delivered to the peer application 178as soon as possible. 179When this flag is absent the message 180was delivered in order within the stream it was received. 181.Pp 182The 183.Fa sinfo->sinfo_stream 184field is 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 200field will 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 208field holds 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 218field holds 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 228.Dv ( SOCK_SEQPACKET ) 229type sockets this value can be used to send data to the peer without 230the use of an address field. 231It is also quite useful in 232setting various socket options on the specific association 233(see 234.Xr sctp 4 ) . 235.Pp 236The 237.Fa sinfo->info_timetolive 238field is not used by 239.Fn sctp_recvmsg . 240.Sh RETURN VALUES 241The call returns the number of bytes received, or \-1 242if an error occurred. 243.Sh ERRORS 244The 245.Fn sctp_recvmsg 246system call 247fails if: 248.Bl -tag -width Er 249.It Bq Er EAGAIN 250The socket is marked non-blocking and the requested operation 251would block. 252.It Bq Er EBADF 253An invalid descriptor was specified. 254.It Bq Er ECONNRESET 255An abort was received by the stack while the user was 256attempting to send data to the peer. 257.It Bq Er EFAULT 258An invalid user space address was specified for an argument. 259.It Bq Er EHOSTUNREACH 260The remote host was unreachable. 261.It Bq Er EMSGSIZE 262The socket requires that message be sent atomically, 263and the size of the message to be sent made this impossible. 264.It Bq Er ENOBUFS 265The system was unable to allocate an internal buffer. 266The operation may succeed when buffers become available. 267This error is also returned when 268the output queue for a network interface was full. 269This generally indicates that the interface has stopped sending, 270but may be caused by transient congestion. 271.It Bq Er ENOENT 272On a one to many style socket no address is specified 273so that the association cannot be located or the 274.Dv SCTP_ABORT 275flag was specified on a non-existing association. 276.It Bq Er ENOTCONN 277On a one-to-one style socket no association exists. 278.It Bq Er ENOTSOCK 279The argument 280.Fa s 281is not a socket. 282.It Bq Er EPIPE 283The socket is unable to send anymore data 284.Dv ( SBS_CANTSENDMORE 285has been set on the socket). 286This typically means that the socket 287is not connected and is a one-to-one style socket. 288.El 289.Sh SEE ALSO 290.Xr getsockopt 2 , 291.Xr recv 2 , 292.Xr select 2 , 293.Xr sendmsg 2 , 294.Xr setsockopt 2 , 295.Xr socket 2 , 296.Xr write 2 , 297.Xr sctp_send 3 , 298.Xr sctp_sendmsg 3 , 299.Xr sctp 4 300.Rs 301.%R RFC 302.%N 6458 303.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" 304.%D December 2011 305.Re 306.Sh HISTORY 307This function first appeared in 308.Nx 9.0 . 309