sctp_recvmsg.3 (fa9896e082a1046ff4fbc75fcba4d18d1f2efc19) sctp_recvmsg.3 (5590bacaafd8687bf522bb0413178c177c43f952)
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.

--- 11 unchanged lines hidden (view full) ---

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.\"
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.

--- 11 unchanged lines hidden (view full) ---

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.Dd April 23, 2015
28.Dd February 2, 2024
29.Dt SCTP_RECVMSG 3
30.Os
31.Sh NAME
29.Dt SCTP_RECVMSG 3
30.Os
31.Sh NAME
32.Nm sctp_recvmsg
32.Nm sctp_recvmsg ,
33.Nm sctp_recvv
33.Nd receive a message from an SCTP socket
34.Sh LIBRARY
35.Lb libc
36.Sh SYNOPSIS
37.In sys/types.h
38.In sys/socket.h
39.In netinet/sctp.h
40.Ft ssize_t
41.Fo sctp_recvmsg
42.Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from"
43.Fa "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags"
44.Fc
34.Nd receive a message from an SCTP socket
35.Sh LIBRARY
36.Lb libc
37.Sh SYNOPSIS
38.In sys/types.h
39.In sys/socket.h
40.In netinet/sctp.h
41.Ft ssize_t
42.Fo sctp_recvmsg
43.Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from"
44.Fa "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags"
45.Fc
46.Ft ssize_t
47.Fo sctp_recvv
48.Fa "int s" "const struct iovec *iov" "int iovlen" "struct sockaddr *from"
49.Fa "socklen_t *fromlen" "void *info" "socklen_t *infolen"
50.Fa "unsigned int *infotype" "int *flags"
51.Fc
45.Sh DESCRIPTION
46The
47.Fn sctp_recvmsg
52.Sh DESCRIPTION
53The
54.Fn sctp_recvmsg
48system call
49is used to receive a message from another SCTP endpoint.
50The
51.Fn sctp_recvmsg
52call is used by one-to-one (SOCK_STREAM) type sockets after a
53successful
55and
56.Fn sctp_recvv
57functions are used to receive a message from another SCTP endpoint.
58They are used by one-to-one (SOCK_STREAM) type sockets after a successful
54.Fn connect
55call or after the application has performed a
56.Fn listen
57followed by a successful
58.Fn accept .
59For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
60.Fn sctp_recvmsg
59.Fn connect
60call or after the application has performed a
61.Fn listen
62followed by a successful
63.Fn accept .
64For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
65.Fn sctp_recvmsg
66or
67.Fn sctp_recvv
61after having implicitly started an association via one
62of the send calls including
63.Fn sctp_sendmsg ,
64.Fn sendto
65and
66.Fn sendmsg .
67Or, an application may also receive a message after having
68called

--- 157 unchanged lines hidden (view full) ---

226setting various socket options on the specific association
227(see
228.Xr sctp 4 ) .
229.Pp
230The
231.Fa sinfo->info_timetolive
232field is not used by
233.Fn sctp_recvmsg .
68after having implicitly started an association via one
69of the send calls including
70.Fn sctp_sendmsg ,
71.Fn sendto
72and
73.Fn sendmsg .
74Or, an application may also receive a message after having
75called

--- 157 unchanged lines hidden (view full) ---

233setting various socket options on the specific association
234(see
235.Xr sctp 4 ) .
236.Pp
237The
238.Fa sinfo->info_timetolive
239field is not used by
240.Fn sctp_recvmsg .
241.Pp
242The
243.Fn sctp_recvv
244function works as
245.Fn sctp_recvmsg
246with two differences.
247Firstly, the receive buffer is passed as an array containing
248.Vt iocnt
249objects of type
250.Vt struct iovec ,
251where the received data will be scattered in the same manner as
252.Xr readv 2 .
253Secondly, the
254.Fa sinfo
255argument is replaced by the tuple
256.Fa info ,
257.Fa infolen ,
258and
259.Fa infotype ,
260which allow different information to be received based on the socket options.
261.Pp
262To receive an
263.Vt sctp_rcvinfo
264structure, set the
265.Va SCTP_RECVRCVINFO
266socket option, and pass a pointer to a
267.Vt struct sctp_rcvinfo
268structure in
269.Fa info .
270The
271.Vt sctp_rcvinfo
272structure has the following format:
273.Bd -literal
274struct sctp_rcvinfo {
275 uint16_t rcv_sid; /* Stream arriving on */
276 uint16_t rcv_ssn; /* Stream Sequence Number */
277 uint16_t rcv_flags; /* Flags on the incoming message */
278 uint32_t rcv_ppid; /* The ppid field */
279 uint32_t rcv_tsn; /* The transport sequence number */
280 uint32_t rcv_cumtsn; /* The cumulative TSN */
281 uint32_t rcv_context; /* Opaque context field */
282 sctp_assoc_t rcv_assoc_id; /* Peer association id */
283};
284.Ed
285.Pp
286These fields have the same meaning as the equivalent fields in
287.Vt struct sctp_sndrcvinfo ,
288defined above.
289.Pp
290To receive an
291.Vt sctp_nxtinfo
292structure, set the
293.Va SCTP_RECVNXTINFO
294socket option, and pass a pointer to a
295.Vt struct sctp_nxtinfo
296structure in
297.Fa info .
298The
299.Vt struct sctp_nxtinfo
300structure has the following format:
301.Bd -literal
302struct sctp_nxtinfo {
303 uint16_t nxt_sid; /* Next message's stream number */
304 uint16_t nxt_flags; /* Flags (see below) */
305 uint32_t nxt_ppid; /* The ppid field */
306 uint32_t nxt_length; /* Length of next message */
307 sctp_assoc_t nxt_assoc_id; /* Peer association id */
308};
309.Ed
310.Pp
311The fields
312.Va nxt_sid ,
313.Va nxt_ppid ,
314and
315.Va nxt_assoc_id
316have the same meaning as in
317.Vt struct sctp_rcvinfo ,
318except they refer to the next message rather than the message that was
319received.
320The field
321.Va nxt_length
322contains the length of the part of the next message currently available in
323the socket buffer.
324This may not represent the length of the entire message unless the
325.Va SCTP_COMPLETE
326flag is set in
327.Va nxt_flags .
328.Pp
329The
330.Va nxt_flags
331field is a bitmask which may contain any of the following values:
332.Bl -bullet
333.It
334.Va SCTP_UNORDERED :
335The next message was sent unordered.
336.It
337.Va SCTP_COMPLETE :
338The entirety of the next message has been received in the socket buffer.
339In this case, the
340.Va nxt_length
341field contains the length of the entire message.
342.It
343.Va SCTP_NOTIFICATION :
344The next message is a notification, not a user message.
345.El
346.Pp
347If both the
348.Va SCTP_RECVRCVINFO
349and
350.Va SCTP_RECVNXTINFO
351socket options are set, then pass a pointer to a
352.Vt struct sctp_recvv_rn
353structure in
354.Fa info .
355This struct has the following format:
356.Bd -literal
357struct sctp_recvv_rn {
358 struct sctp_rcvinfo recvv_rcvinfo;
359 struct sctp_nxtinfo recvv_nxtinfo;
360};
361.Ed
362.Pp
363The value pointed to by
364.Fa infolen
365should initially contain the length of the structure to which
366.Fa info
367points.
368When the function returns, it will be set to the length of the
369returned structure.
370Additionally,
371.Fa *infotype
372will be set to one of the following values depending on what type of info
373was returned:
374.Bl -bullet
375.It
376.Va SCTP_RECVV_NOINFO :
377no information was returned.
378.It
379.Va SCTP_RECVV_RCVINFO :
380.Fa *info
381contains an object of type
382.Vt struct sctp_rcvinfo .
383.It
384.Va SCTP_RECVV_NXTINFO :
385.Fa *info
386contains an object of type
387.Vt struct sctp_nxtinfo .
388.It
389.Va SCTP_RECVV_RN :
390.Fa *info
391contains an object of type
392.Vt struct sctp_recvv_rn .
393.El
234.Sh RETURN VALUES
235The call returns the number of bytes received, or -1
236if an error occurred.
237.Sh ERRORS
238The
239.Fn sctp_recvmsg
240system call
241fails if:

--- 32 unchanged lines hidden (view full) ---

274SCTP_ABORT flag was specified on a non-existing association.
275.It Bq Er EPIPE
276The socket is unable to send anymore data
277.Dv ( SBS_CANTSENDMORE
278has been set on the socket).
279This typically means that the socket
280is not connected and is a one-to-one style socket.
281.El
394.Sh RETURN VALUES
395The call returns the number of bytes received, or -1
396if an error occurred.
397.Sh ERRORS
398The
399.Fn sctp_recvmsg
400system call
401fails if:

--- 32 unchanged lines hidden (view full) ---

434SCTP_ABORT flag was specified on a non-existing association.
435.It Bq Er EPIPE
436The socket is unable to send anymore data
437.Dv ( SBS_CANTSENDMORE
438has been set on the socket).
439This typically means that the socket
440is not connected and is a one-to-one style socket.
441.El
442.Sh NOTES
443The
444.Fn sctp_recvmsg
445function is deprecated.
446New applications should use
447.Fn sctp_recvv .
282.Sh SEE ALSO
283.Xr getsockopt 2 ,
284.Xr recv 2 ,
285.Xr select 2 ,
286.Xr sendmsg 2 ,
287.Xr setsockopt 2 ,
288.Xr socket 2 ,
289.Xr write 2 ,
290.Xr sctp_send 3 ,
291.Xr sctp_sendmsg 3 ,
292.Xr sctp 4
448.Sh SEE ALSO
449.Xr getsockopt 2 ,
450.Xr recv 2 ,
451.Xr select 2 ,
452.Xr sendmsg 2 ,
453.Xr setsockopt 2 ,
454.Xr socket 2 ,
455.Xr write 2 ,
456.Xr sctp_send 3 ,
457.Xr sctp_sendmsg 3 ,
458.Xr sctp 4
459.Rs
460.%A R. Stewart
461.%A M. Tuexen
462.%A K. Poon
463.%A P. Lei
464.%A V. Yasevich
465.%T Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)
466.%R RFC 6458
467.%D December 2011
468.Re
469.Sh STANDARDS
470The functions described in this document conform to RFC 6458.