xref: /freebsd/lib/libc/net/sctp_recvmsg.3 (revision acc1a9ef) 
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. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
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.\" $FreeBSD$
29.\"
30.Dd April 23, 2015
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 (SOCK_STREAM) type sockets after a
55successful
56.Fn connect
57call or after the application has performed a
58.Fn listen
59followed by a successful
60.Fn accept .
61For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
62.Fn sctp_recvmsg
63after having implicitly started an association via one
64of the send calls including
65.Fn sctp_sendmsg ,
66.Fn sendto
67and
68.Fn sendmsg .
69Or, an application may also receive a message after having
70called
71.Fn listen
72with a positive backlog to enable the reception of new associations.
73.Pp
74The address of the sender is held in the
75.Fa from
76argument with
77.Fa fromlen
78specifying its size.
79At the completion of a successful
80.Fn sctp_recvmsg
81call
82.Fa from
83will hold the address of the peer and
84.Fa fromlen
85will hold the length of that address.
86Note that
87the address is bounded by the initial value of
88.Fa fromlen
89which is used as an in/out variable.
90.Pp
91The length of the message
92.Fa msg
93to be received is bounded by
94.Fa len .
95If the message is too long to fit in the users
96receive buffer, then the
97.Fa flags
98argument will
99.Em not
100have the
101.Dv MSG_EOR
102flag applied.
103If the message is a complete message then
104the
105.Fa flags
106argument will have
107.Dv MSG_EOR
108set.
109Locally detected errors are
110indicated by a return value of -1 with
111.Va errno
112set accordingly.
113The
114.Fa flags
115argument may also hold the value
116.Dv MSG_NOTIFICATION .
117When this
118occurs it indicates that the message received is
119.Em not
120from
121the peer endpoint, but instead is a notification from the
122SCTP stack (see
123.Xr sctp 4
124for more details).
125Note that no notifications are ever
126given unless the user subscribes to such notifications using
127the
128.Dv SCTP_EVENTS
129socket option.
130.Pp
131If no messages are available at the socket then
132.Fn sctp_recvmsg
133normally blocks on the reception of a message or NOTIFICATION, unless the
134socket has been placed in non-blocking I/O mode.
135The
136.Xr select 2
137system call may be used to determine when it is possible to
138receive a message.
139.Pp
140The
141.Fa sinfo
142argument is defined as follows.
143.Bd -literal
144struct sctp_sndrcvinfo {
145	uint16_t sinfo_stream;  /* Stream arriving on */
146	uint16_t sinfo_ssn;     /* Stream Sequence Number */
147	uint16_t sinfo_flags;   /* Flags on the incoming message */
148	uint32_t sinfo_ppid;    /* The ppid field */
149	uint32_t sinfo_context; /* context field */
150	uint32_t sinfo_timetolive; /* not used by sctp_recvmsg */
151	uint32_t sinfo_tsn;        /* The transport sequence number */
152	uint32_t sinfo_cumtsn;     /* The cumulative acknowledgment point  */
153	sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */
154};
155.Ed
156.Pp
157The
158.Fa sinfo->sinfo_ppid
159field is an opaque 32 bit value that is passed transparently
160through the stack from the peer endpoint.
161Note that the stack passes this value without regard to byte
162order.
163.Pp
164The
165.Fa sinfo->sinfo_flags
166field may include the following:
167.Bd -literal
168#define SCTP_UNORDERED 	  0x0400	/* Message is un-ordered */
169.Ed
170.Pp
171The
172.Dv SCTP_UNORDERED
173flag is used to specify that the message arrived with no
174specific order and was delivered to the peer application
175as soon as possible.
176When this flag is absent the message
177was delivered in order within the stream it was received.
178.Pp
179The
180.Fa sinfo->sinfo_stream
181field is the SCTP stream that the message was received on.
182Streams in SCTP are reliable (or partially reliable) flows of ordered
183messages.
184.Pp
185The
186.Fa sinfo->sinfo_context
187field is used only if the local application set an association level
188context with the
189.Dv SCTP_CONTEXT
190socket option.
191Optionally a user process can use this value to index some application
192specific data structure for all data coming from a specific
193association.
194.Pp
195The
196.Fa sinfo->sinfo_ssn
197field will hold the stream sequence number assigned
198by the peer endpoint if the message is
199.Em not
200unordered.
201For unordered messages this field holds an undefined value.
202.Pp
203The
204.Fa sinfo->sinfo_tsn
205field holds a transport sequence number (TSN) that was assigned
206to this message by the peer endpoint.
207For messages that fit in or less
208than the path MTU this will be the only TSN assigned.
209Note that for messages that span multiple TSNs this
210value will be one of the TSNs that was used on the
211message.
212.Pp
213The
214.Fa sinfo->sinfo_cumtsn
215field holds the current cumulative acknowledgment point of
216the transport association.
217Note that this may be larger
218or smaller than the TSN assigned to the message itself.
219.Pp
220The
221.Fa sinfo->sinfo_assoc_id
222is the unique association identification that was assigned
223to the association.
224For one-to-many (SOCK_SEQPACKET) type
225sockets this value can be used to send data to the peer without
226the use of an address field.
227It is also quite useful in
228setting various socket options on the specific association
229(see
230.Xr sctp 4 ) .
231.Pp
232The
233.Fa sinfo->info_timetolive
234field is not used by
235.Fn sctp_recvmsg .
236.Sh RETURN VALUES
237The call returns the number of bytes received, or -1
238if an error occurred.
239.Sh ERRORS
240The
241.Fn sctp_recvmsg
242system call
243fails if:
244.Bl -tag -width Er
245.It Bq Er EBADF
246An invalid descriptor was specified.
247.It Bq Er ENOTSOCK
248The argument
249.Fa s
250is not a socket.
251.It Bq Er EFAULT
252An invalid user space address was specified for an argument.
253.It Bq Er EMSGSIZE
254The socket requires that message be sent atomically,
255and the size of the message to be sent made this impossible.
256.It Bq Er EAGAIN
257The socket is marked non-blocking and the requested operation
258would block.
259.It Bq Er ENOBUFS
260The system was unable to allocate an internal buffer.
261The operation may succeed when buffers become available.
262.It Bq Er ENOBUFS
263The output queue for a network interface was full.
264This generally indicates that the interface has stopped sending,
265but may be caused by transient congestion.
266.It Bq Er EHOSTUNREACH
267The remote host was unreachable.
268.It Bq Er ENOTCONN
269On a one-to-one style socket no association exists.
270.It Bq Er ECONNRESET
271An abort was received by the stack while the user was
272attempting to send data to the peer.
273.It Bq Er ENOENT
274On a one to many style socket no address is specified
275so that the association cannot be located or the
276SCTP_ABORT flag was specified on a non-existing association.
277.It Bq Er EPIPE
278The socket is unable to send anymore data
279.Dv ( SBS_CANTSENDMORE
280has been set on the socket).
281This typically means that the socket
282is not connected and is a one-to-one style socket.
283.El
284.Sh SEE ALSO
285.Xr getsockopt 2 ,
286.Xr recv 2 ,
287.Xr select 2 ,
288.Xr sendmsg 2 ,
289.Xr setsockopt 2 ,
290.Xr socket 2 ,
291.Xr write 2 ,
292.Xr sctp_send 3 ,
293.Xr sctp_sendmsg 3 ,
294.Xr sctp 4
295