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 sucessful
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 postive 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 inital 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
102 argument will NOT have the
105 If the message is a complete message then
111 Locally detected errors are
112 indicated by a return value of -1 with
117 argument may also hold the value
118 .Dv MSG_NOTIFICATION .
120 occurs this indicates that the message received is NOT from
121 the peer endpoint, but instead is a notification from the
125 Note that no notifications are ever
126 given unless the user subscribes to such notifications using
131 If no messages are available at the socket then
133 normally blocks on the reception of a message or NOTIFICATION, unless the
134 socket has been placed in non-blocking I/O mode.
137 system call may be used to determine when it is possible to
142 argument is defined as follows.
144 struct sctp_sndrcvinfo {
145 u_int16_t sinfo_stream; /* Stream arriving on */
146 u_int16_t sinfo_ssn; /* Stream Sequence Number */
147 u_int16_t sinfo_flags; /* Flags on the incoming message */
148 u_int32_t sinfo_ppid; /* The ppid field */
149 u_int32_t sinfo_context; /* context field */
150 u_int32_t sinfo_timetolive; /* not used by sctp_recvmsg */
151 u_int32_t sinfo_tsn; /* The transport sequence number */
152 u_int32_t sinfo_cumtsn; /* The cumulative acknowledgment point */
153 sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */
158 .Fa sinfo->sinfo_ppid
159 is an opaque 32 bit value that is passed transparently
160 through the stack from the peer endpoint.
161 Note that the stack passes this value without regard to byte
165 .Fa sinfo->sinfo_flags
166 field may include the following:
168 #define SCTP_UNORDERED 0x0400 /* Message is un-ordered */
173 flag is used to specify that the message arrived with no
174 specific order and was delivered to the peer application
176 When this flag is absent the message
177 was delivered in order within the stream it was received.
179 .Fa sinfo->sinfo_stream
180 is the SCTP stream that the message was received on.
181 Streams in SCTP are reliable (or partially reliable) flows of ordered
185 .Fa sinfo->sinfo_context
186 field is used only if the local application set an association level
190 Optionally a user process can use this value to index some application
191 specific data structure for all data coming from a specific
196 will hold the stream sequence number assigned
197 by the peer endpoint if the message is NOT unordered.
198 For unordered messages this field holds an undefined value.
202 holds a transport sequence number (TSN) that was assigned
203 to this message by the peer endpoint.
204 For messages that fit in or less
205 than the path MTU this will be the only TSN assigned.
206 Note that for messages that span multiple TSN's this
207 value will be one of the TSN's that was used on the
211 .Fa sinfo->sinfo_cumtsn
212 holds the current cumulative acknowledgment point of
213 the transport association.
214 Note that this may be larger
215 or smaller than the TSN assigned to the message itself.
218 .Fa sinfo->sinfo_assoc_id
219 is the unique association identification that was assigned
221 For one-to-many (SOCK_SEQPACKET) type
222 sockets this value can be used to send data to the peer without
223 the use of an address field.
224 It is also quite useful in
225 setting various socket options on the specific association
231 .Fa sinfo->info_timetolive
235 The call returns the number of characters sent, or -1
236 if an error occurred.
244 An invalid descriptor was specified.
250 An invalid user space address was specified for an argument.
252 The socket requires that message be sent atomically,
253 and the size of the message to be sent made this impossible.
255 The socket is marked non-blocking and the requested operation
258 The system was unable to allocate an internal buffer.
259 The operation may succeed when buffers become available.
261 The output queue for a network interface was full.
262 This generally indicates that the interface has stopped sending,
263 but may be caused by transient congestion.
264 .It Bq Er EHOSTUNREACH
265 The remote host was unreachable.
267 On a one-to-one style socket no association exists.
269 An abort was received by the stack while the user was
270 attempting to send data to the peer.
272 On a one to many style socket no address is specified
273 so that the association cannot be located or the
274 SCTP_ABORT flag was specified on a non-existing association.
276 The socket is unable to send anymore data
277 .Dv ( SBS_CANTSENDMORE
278 has been set on the socket).
279 This typically means that the socket
280 is not connected and is a one-to-one style socket.