lib/libc/net/sctp_recvmsg.3

   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
  52 The
  53 .Fn sctp_recvmsg
  54 system call
  55 is used to receive a message from another SCTP endpoint.
  56 The
  57 .Fn sctp_recvmsg
  58 call is used by one-to-one (SOCK_STREAM) type sockets after a
  59 successful
  60 .Fn connect
  61 call or after the application has performed a
  62 .Fn listen
  63 followed by a successful
  64 .Fn accept .
  65 For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call
  66 .Fn sctp_recvmsg
  67 after having implicitly started an association via one
  68 of the send calls including
  69 .Fn sctp_sendmsg ,
  70 .Fn sendto
  71 and
  72 .Fn sendmsg .
  73 Or, an application may also receive a message after having
  74 called
  75 .Fn listen
  76 with a positive backlog to enable the reception of new associations.
  77 .Pp
  78 The address of the sender is held in the
  79 .Fa from
  80 argument with
  81 .Fa fromlen
  82 specifying its size.
  83 At the completion of a successful
  84 .Fn sctp_recvmsg
  85 call
  86 .Fa from
  87 will hold the address of the peer and
  88 .Fa fromlen
  89 will hold the length of that address.
  90 Note that
  91 the address is bounded by the initial value of
  92 .Fa fromlen
  93 which is used as an in/out variable.
  94 .Pp
  95 The length of the message
  96 .Fa msg
  97 to be received is bounded by
  98 .Fa len .
  99 If the message is too long to fit in the users
 100 receive buffer, then the
 101 .Fa flags
 102 argument will
 103 .Em not
 104 have the
 105 .Dv MSG_EOF
 106 flag applied.
 107 If the message is a complete message then
 108 the
 109 .Fa flags
 110 argument will have
 111 .Dv MSG_EOF
 112 set.
 113 Locally detected errors are
 114 indicated by a return value of -1 with
 115 .Va errno
 116 set accordingly.
 117 The
 118 .Fa flags
 119 argument may also hold the value
 120 .Dv MSG_NOTIFICATION .
 121 When this
 122 occurs it indicates that the message received is
 123 .Em not
 124 from
 125 the peer endpoint, but instead is a notification from the
 126 SCTP stack (see
 127 .Xr sctp 4
 128 for more details).
 129 Note that no notifications are ever
 130 given unless the user subscribes to such notifications using
 131 the
 132 .Dv SCTP_EVENTS
 133 socket option.
 134 .Pp
 135 If no messages are available at the socket then
 136 .Fn sctp_recvmsg
 137 normally blocks on the reception of a message or NOTIFICATION, unless the
 138 socket has been placed in non-blocking I/O mode.
 139 The
 140 .Xr select 2
 141 system call may be used to determine when it is possible to
 142 receive a message.
 143 .Pp
 144 The
 145 .Fa sinfo
 146 argument is defined as follows.
 147 .Bd -literal
 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 */
 158 };
 159 .Ed
 160 .Pp
 161 The
 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
 166 order.
 167 .Pp
 168 The
 169 .Fa sinfo->sinfo_flags
 170 field may include the following:
 171 .Bd -literal
 172 #define SCTP_UNORDERED    0x0400        /* Message is un-ordered */
 173 .Ed
 174 .Pp
 175 The
 176 .Dv SCTP_UNORDERED
 177 flag is used to specify that the message arrived with no
 178 specific order and was delivered to the peer application
 179 as soon as possible.
 180 When this flag is absent the message
 181 was delivered in order within the stream it was received.
 182 .Pp
 183 The
 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
 187 messages.
 188 .Pp
 189 The
 190 .Fa sinfo->sinfo_context
 191 field is used only if the local application set an association level
 192 context with the
 193 .Dv SCTP_CONTEXT
 194 socket option.
 195 Optionally a user process can use this value to index some application
 196 specific data structure for all data coming from a specific
 197 association.
 198 .Pp
 199 The
 200 .Fa sinfo->sinfo_ssn
 201 field will hold the stream sequence number assigned
 202 by the peer endpoint if the message is
 203 .Em not
 204 unordered.
 205 For unordered messages this field holds an undefined value.
 206 .Pp
 207 The
 208 .Fa sinfo->sinfo_tsn
 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
 215 message.
 216 .Pp
 217 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.
 223 .Pp
 224 The
 225 .Fa sinfo->sinfo_assoc_id
 226 is the unique association identification that was assigned
 227 to the association.
 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
 233 (see
 234 .Xr sctp 4 ) .
 235 .Pp
 236 The
 237 .Fa sinfo->info_timetolive
 238 field is not used by
 239 .Fn sctp_recvmsg .
 240 .Sh RETURN VALUES
 241 The call returns the number of bytes received, or -1
 242 if an error occurred.
 243 .Sh ERRORS
 244 The
 245 .Fn sctp_recvmsg
 246 system call
 247 fails if:
 248 .Bl -tag -width Er
 249 .It Bq Er EBADF
 250 An invalid descriptor was specified.
 251 .It Bq Er ENOTSOCK
 252 The argument
 253 .Fa s
 254 is not a socket.
 255 .It Bq Er EFAULT
 256 An invalid user space address was specified for an argument.
 257 .It Bq Er EMSGSIZE
 258 The socket requires that message be sent atomically,
 259 and the size of the message to be sent made this impossible.
 260 .It Bq Er EAGAIN
 261 The socket is marked non-blocking and the requested operation
 262 would block.
 263 .It Bq Er ENOBUFS
 264 The system was unable to allocate an internal buffer.
 265 The operation may succeed when buffers become available.
 266 .It Bq Er ENOBUFS
 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.
 272 .It Bq Er ENOTCONN
 273 On a one-to-one style socket no association exists.
 274 .It Bq Er ECONNRESET
 275 An abort was received by the stack while the user was
 276 attempting to send data to the peer.
 277 .It Bq Er ENOENT
 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.
 281 .It Bq Er EPIPE
 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.
 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