xref: /freebsd/lib/libc/net/sctp_recvmsg.3 (revision cf771f223b1a69e11fd1b70b0a274a73fe844335)
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. 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.
19.\"
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
30.\" SUCH DAMAGE.
31.\"
32.\" $FreeBSD$
33.\"
34.Dd August 13, 2007
35.Dt SCTP_RECVMSG 3
36.Os
37.Sh NAME
38.Nm sctp_recvmsg
39.Nd receive a message from an SCTP socket
40.Sh LIBRARY
41.Lb libc
42.Sh SYNOPSIS
43.In sys/types.h
44.In sys/socket.h
45.In netinet/sctp.h
46.Ft ssize_t
47.Fo sctp_recvmsg
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"
50.Fc
51.Sh DESCRIPTION
52The
53.Fn sctp_recvmsg
54system call
55is used to receive a message from another SCTP endpoint.
56The
57.Fn sctp_recvmsg
58call is used by one-to-one (SOCK_STREAM) type sockets after a
59successful
60.Fn connect
61call or after the application has performed a
62.Fn listen
63followed by a successful
64.Fn accept .
65For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
66.Fn sctp_recvmsg
67after having implicitly started an association via one
68of the send calls including
69.Fn sctp_sendmsg
70.Fn sendto
71and
72.Fn sendmsg .
73Or, an application may also receive a message after having
74called
75.Fn listen
76with a positive backlog to enable the reception of new associations.
77.Pp
78The address of the sender is held in the
79.Fa from
80argument with
81.Fa fromlen
82specifying its size.
83At the completion of a successful
84.Fn sctp_recvmsg
85call
86.Fa from
87will hold the address of the peer and
88.Fa fromlen
89will hold the length of that address.
90Note that
91the address is bounded by the initial value of
92.Fa fromlen
93which is used as an in/out variable.
94.Pp
95The length of the message
96.Fa msg
97to be received is bounded by
98.Fa len .
99If the message is too long to fit in the users
100receive buffer, then the
101.Fa flags
102argument will
103.Em not
104have the
105.Dv MSG_EOF
106flag applied.
107If the message is a complete message then
108the
109.Fa flags
110argument will have
111.Dv MSG_EOF
112set.
113Locally detected errors are
114indicated by a return value of -1 with
115.Va errno
116set accordingly.
117The
118.Fa flags
119argument may also hold the value
120.Dv MSG_NOTIFICATION .
121When this
122occurs it indicates that the message received is
123.Em not
124from
125the peer endpoint, but instead is a notification from the
126SCTP stack (see
127.Xr sctp 4
128for more details).
129Note that no notifications are ever
130given unless the user subscribes to such notifications using
131the
132.Dv SCTP_EVENTS
133socket option.
134.Pp
135If no messages are available at the socket then
136.Fn sctp_recvmsg
137normally blocks on the reception of a message or NOTIFICATION, unless the
138socket has been placed in non-blocking I/O mode.
139The
140.Xr select 2
141system call may be used to determine when it is possible to
142receive a message.
143.Pp
144The
145.Fa sinfo
146argument is defined as follows.
147.Bd -literal
148struct 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 */
158};
159.Ed
160.Pp
161The
162.Fa sinfo->sinfo_ppid
163field is an opaque 32 bit value that is passed transparently
164through the stack from the peer endpoint.
165Note that the stack passes this value without regard to byte
166order.
167.Pp
168The
169.Fa sinfo->sinfo_flags
170field may include the following:
171.Bd -literal
172#define SCTP_UNORDERED 	  0x0400	/* Message is un-ordered */
173.Ed
174.Pp
175The
176.Dv SCTP_UNORDERED
177flag is used to specify that the message arrived with no
178specific order and was delivered to the peer application
179as soon as possible.
180When this flag is absent the message
181was delivered in order within the stream it was received.
182.Pp
183The
184.Fa sinfo->sinfo_stream
185field is the SCTP stream that the message was received on.
186Streams in SCTP are reliable (or partially reliable) flows of ordered
187messages.
188.Pp
189The
190.Fa sinfo->sinfo_context
191field is used only if the local application set an association level
192context with the
193.Dv SCTP_CONTEXT
194socket option.
195Optionally a user process can use this value to index some application
196specific data structure for all data coming from a specific
197association.
198.Pp
199The
200.Fa sinfo->sinfo_ssn
201field will hold the stream sequence number assigned
202by the peer endpoint if the message is
203.Em not
204unordered.
205For unordered messages this field holds an undefined value.
206.Pp
207The
208.Fa sinfo->sinfo_tsn
209field holds a transport sequence number (TSN) that was assigned
210to this message by the peer endpoint.
211For messages that fit in or less
212than the path MTU this will be the only TSN assigned.
213Note that for messages that span multiple TSNs this
214value will be one of the TSNs that was used on the
215message.
216.Pp
217The
218.Fa sinfo->sinfo_cumtsn
219field holds the current cumulative acknowledgment point of
220the transport association.
221Note that this may be larger
222or smaller than the TSN assigned to the message itself.
223.Pp
224The
225.Fa sinfo->sinfo_assoc_id
226is the unique association identification that was assigned
227to the association.
228For one-to-many (SOCK_SEQPACKET) type
229sockets 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 EBADF
250An invalid descriptor was specified.
251.It Bq Er ENOTSOCK
252The argument
253.Fa s
254is not a socket.
255.It Bq Er EFAULT
256An invalid user space address was specified for an argument.
257.It Bq Er EMSGSIZE
258The socket requires that message be sent atomically,
259and the size of the message to be sent made this impossible.
260.It Bq Er EAGAIN
261The socket is marked non-blocking and the requested operation
262would block.
263.It Bq Er ENOBUFS
264The system was unable to allocate an internal buffer.
265The operation may succeed when buffers become available.
266.It Bq Er ENOBUFS
267The output queue for a network interface was full.
268This generally indicates that the interface has stopped sending,
269but may be caused by transient congestion.
270.It Bq Er EHOSTUNREACH
271The remote host was unreachable.
272.It Bq Er ENOTCONN
273On a one-to-one style socket no association exists.
274.It Bq Er ECONNRESET
275An abort was received by the stack while the user was
276attempting to send data to the peer.
277.It Bq Er ENOENT
278On a one to many style socket no address is specified
279so that the association cannot be located or the
280SCTP_ABORT flag was specified on a non-existing association.
281.It Bq Er EPIPE
282The socket is unable to send anymore data
283.Dv ( SBS_CANTSENDMORE
284has been set on the socket).
285This typically means that the socket
286is not connected and is a one-to-one style socket.
287.El
288.Sh SEE ALSO
289.Xr recv 2 ,
290.Xr select 2 ,
291.Xr socket 2 ,
292.Xr write 2 ,
293.Xr getsockopt 2 ,
294.Xr setsockopt 2 ,
295.Xr sctp_send 3 ,
296.Xr sctp_sendmsg 3 ,
297.Xr sendmsg 3 ,
298.Xr sctp 4
299