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 inital 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         u_int16_t sinfo_stream;  /* Stream arriving on */
 150         u_int16_t sinfo_ssn;     /* Stream Sequence Number */
 151         u_int16_t sinfo_flags;   /* Flags on the incoming message */
 152         u_int32_t sinfo_ppid;    /* The ppid field */
 153         u_int32_t sinfo_context; /* context field */
 154         u_int32_t sinfo_timetolive; /* not used by sctp_recvmsg */
 155         u_int32_t sinfo_tsn;        /* The transport sequence number */
 156         u_int32_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 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 .Fa sinfo->sinfo_stream
 184 is the SCTP stream that the message was received on.
 185 Streams in SCTP are reliable (or partially reliable) flows of ordered
 186 messages.
 187 .Pp
 188 The
 189 .Fa sinfo->sinfo_context
 190 field is used only if the local application set an association level
 191 context with the
 192 .Dv SCTP_CONTEXT
 193 socket option.
 194 Optionally a user process can use this value to index some application
 195 specific data structure for all data coming from a specific
 196 association.
 197 .Pp
 198 The
 199 .Fa sinfo->sinfo_ssn
 200 will hold the stream sequence number assigned
 201 by the peer endpoint if the message is
 202 .Em not
 203 unordered.
 204 For unordered messages this field holds an undefined value.
 205 .Pp
 206 The
 207 .Fa sinfo->sinfo_tsn
 208 holds a transport sequence number (TSN) that was assigned
 209 to this message by the peer endpoint.
 210 For messages that fit in or less
 211 than the path MTU this will be the only TSN assigned.
 212 Note that for messages that span multiple TSNs this
 213 value will be one of the TSNs that was used on the
 214 message.
 215 .Pp
 216 The
 217 .Fa sinfo->sinfo_cumtsn
 218 holds the current cumulative acknowledgment point of
 219 the transport association.
 220 Note that this may be larger
 221 or smaller than the TSN assigned to the message itself.
 222 .Pp
 223 The
 224 .Fa sinfo->sinfo_assoc_id
 225 is the unique association identification that was assigned
 226 to the association.
 227 For one-to-many (SOCK_SEQPACKET) type
 228 sockets this value can be used to send data to the peer without
 229 the use of an address field.
 230 It is also quite useful in
 231 setting various socket options on the specific association
 232 (see
 233 .Xr sctp 4 ) .
 234 .Pp
 235 The
 236 .Fa sinfo->info_timetolive
 237 field is not used by
 238 .Fa sctp_recvmsg .
 239 .Sh RETURN VALUES
 240 The call returns the number of characters sent, or -1
 241 if an error occurred.
 242 .Sh ERRORS
 243 The
 244 .Fn sctp_recvmsg
 245 system call
 246 fails if:
 247 .Bl -tag -width Er
 248 .It Bq Er EBADF
 249 An invalid descriptor was specified.
 250 .It Bq Er ENOTSOCK
 251 The argument
 252 .Fa s
 253 is not a socket.
 254 .It Bq Er EFAULT
 255 An invalid user space address was specified for an argument.
 256 .It Bq Er EMSGSIZE
 257 The socket requires that message be sent atomically,
 258 and the size of the message to be sent made this impossible.
 259 .It Bq Er EAGAIN
 260 The socket is marked non-blocking and the requested operation
 261 would block.
 262 .It Bq Er ENOBUFS
 263 The system was unable to allocate an internal buffer.
 264 The operation may succeed when buffers become available.
 265 .It Bq Er ENOBUFS
 266 The output queue for a network interface was full.
 267 This generally indicates that the interface has stopped sending,
 268 but may be caused by transient congestion.
 269 .It Bq Er EHOSTUNREACH
 270 The remote host was unreachable.
 271 .It Bq Er ENOTCON
 272 On a one-to-one style socket no association exists.
 273 .It Bq Er ECONNRESET
 274 An abort was received by the stack while the user was
 275 attempting to send data to the peer.
 276 .It Bq Er ENOENT
 277 On a one to many style socket no address is specified
 278 so that the association cannot be located or the
 279 SCTP_ABORT flag was specified on a non-existing association.
 280 .It Bq Er EPIPE
 281 The socket is unable to send anymore data
 282 .Dv ( SBS_CANTSENDMORE
 283 has been set on the socket).
 284 This typically means that the socket
 285 is not connected and is a one-to-one style socket.
 286 .El
 287 .Sh SEE ALSO
 288 .Xr recv 2 ,
 289 .Xr select 2 ,
 290 .Xr socket 2 ,
 291 .Xr write 2 ,
 292 .Xr getsockopt 2 ,
 293 .Xr setsockopt 2 ,
 294 .Xr sctp_send 3 ,
 295 .Xr sctp_sendmsg 3 ,
 296 .Xr sendmsg 3 ,
 297 .Xr sctp 4