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