1 .\" Copyright (c) 1983, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
39 .Nd receive a message from an SCTP socket
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"
55 is used to receive a message from another SCTP endpoint.
58 call is used by one-to-one (SOCK_STREAM) type sockets after a
61 call or after the application has performed a
63 followed by a successful
65 For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
67 after having implicitly started an association via one
68 of the send calls including
73 Or, an application may also receive a message after having
76 with a positive backlog to enable the reception of new associations.
78 The address of the sender is held in the
83 At the completion of a successful
87 will hold the address of the peer and
89 will hold the length of that address.
91 the address is bounded by the initial value of
93 which is used as an in/out variable.
95 The length of the message
97 to be received is bounded by
99 If the message is too long to fit in the users
100 receive buffer, then the
107 If the message is a complete message then
113 Locally detected errors are
114 indicated by a return value of -1 with
119 argument may also hold the value
120 .Dv MSG_NOTIFICATION .
122 occurs it indicates that the message received is
125 the peer endpoint, but instead is a notification from the
129 Note that no notifications are ever
130 given unless the user subscribes to such notifications using
135 If no messages are available at the socket then
137 normally blocks on the reception of a message or NOTIFICATION, unless the
138 socket has been placed in non-blocking I/O mode.
141 system call may be used to determine when it is possible to
146 argument is defined as follows.
148 struct sctp_sndrcvinfo {
149 uint16_t sinfo_stream; /* Stream arriving on */
150 uint16_t sinfo_ssn; /* Stream Sequence Number */
151 uint16_t sinfo_flags; /* Flags on the incoming message */
152 uint32_t sinfo_ppid; /* The ppid field */
153 uint32_t sinfo_context; /* context field */
154 uint32_t sinfo_timetolive; /* not used by sctp_recvmsg */
155 uint32_t sinfo_tsn; /* The transport sequence number */
156 uint32_t sinfo_cumtsn; /* The cumulative acknowledgment point */
157 sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */
162 .Fa sinfo->sinfo_ppid
163 field is an opaque 32 bit value that is passed transparently
164 through the stack from the peer endpoint.
165 Note that the stack passes this value without regard to byte
169 .Fa sinfo->sinfo_flags
170 field may include the following:
172 #define SCTP_UNORDERED 0x0400 /* Message is un-ordered */
177 flag is used to specify that the message arrived with no
178 specific order and was delivered to the peer application
180 When this flag is absent the message
181 was delivered in order within the stream it was received.
184 .Fa sinfo->sinfo_stream
185 field is the SCTP stream that the message was received on.
186 Streams in SCTP are reliable (or partially reliable) flows of ordered
190 .Fa sinfo->sinfo_context
191 field is used only if the local application set an association level
195 Optionally a user process can use this value to index some application
196 specific data structure for all data coming from a specific
201 field will hold the stream sequence number assigned
202 by the peer endpoint if the message is
205 For unordered messages this field holds an undefined value.
209 field holds a transport sequence number (TSN) that was assigned
210 to this message by the peer endpoint.
211 For messages that fit in or less
212 than the path MTU this will be the only TSN assigned.
213 Note that for messages that span multiple TSNs this
214 value will be one of the TSNs that was used on the
218 .Fa sinfo->sinfo_cumtsn
219 field holds the current cumulative acknowledgment point of
220 the transport association.
221 Note that this may be larger
222 or smaller than the TSN assigned to the message itself.
225 .Fa sinfo->sinfo_assoc_id
226 is the unique association identification that was assigned
228 For one-to-many (SOCK_SEQPACKET) type
229 sockets this value can be used to send data to the peer without
230 the use of an address field.
231 It is also quite useful in
232 setting various socket options on the specific association
237 .Fa sinfo->info_timetolive
241 The call returns the number of bytes received, or -1
242 if an error occurred.
250 An invalid descriptor was specified.
256 An invalid user space address was specified for an argument.
258 The socket requires that message be sent atomically,
259 and the size of the message to be sent made this impossible.
261 The socket is marked non-blocking and the requested operation
264 The system was unable to allocate an internal buffer.
265 The operation may succeed when buffers become available.
267 The output queue for a network interface was full.
268 This generally indicates that the interface has stopped sending,
269 but may be caused by transient congestion.
270 .It Bq Er EHOSTUNREACH
271 The remote host was unreachable.
273 On a one-to-one style socket no association exists.
275 An abort was received by the stack while the user was
276 attempting to send data to the peer.
278 On a one to many style socket no address is specified
279 so that the association cannot be located or the
280 SCTP_ABORT flag was specified on a non-existing association.
282 The socket is unable to send anymore data
283 .Dv ( SBS_CANTSENDMORE
284 has been set on the socket).
285 This typically means that the socket
286 is not connected and is a one-to-one style socket.