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