| sctp_recvmsg.3 (210933) | sctp_recvmsg.3 (233648) |
|---|---|
| 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. --- 15 unchanged lines hidden (view full) --- 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.\" | 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. --- 15 unchanged lines hidden (view full) --- 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: head/lib/libc/net/sctp_recvmsg.3 210933 2010-08-06 14:33:42Z joel $ | 32.\" $FreeBSD: head/lib/libc/net/sctp_recvmsg.3 233648 2012-03-29 05:02:12Z eadler $ |
| 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 --- 10 unchanged lines hidden (view full) --- 51.Sh DESCRIPTION 52The 53.Fn sctp_recvmsg 54system call 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 | 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 --- 10 unchanged lines hidden (view full) --- 51.Sh DESCRIPTION 52The 53.Fn sctp_recvmsg 54system call 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 |
| 59successful | 59successful |
| 60.Fn connect | 60.Fn connect |
| 61call or after the application has performed a 62.Fn listen 63followed by a successful | 61call or after the application has performed a 62.Fn listen 63followed by a successful |
| 64.Fn accept . 65For 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 69.Fn sctp_sendmsg 70.Fn sendto 71and 72.Fn sendmsg . 73Or, an application may also receive a message after having 74called 75.Fn listen 76with a positive backlog to enable the reception of new associations. 77.Pp 78The address of the sender is held in the 79.Fa from | 64.Fn accept . 65For 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 69.Fn sctp_sendmsg 70.Fn sendto 71and 72.Fn sendmsg . 73Or, an application may also receive a message after having 74called 75.Fn listen 76with a positive backlog to enable the reception of new associations. 77.Pp 78The address of the sender is held in the 79.Fa from |
| 80argument with | 80argument with |
| 81.Fa fromlen 82specifying its size. 83At the completion of a successful 84.Fn sctp_recvmsg 85call 86.Fa from 87will hold the address of the peer and 88.Fa fromlen 89will hold the length of that address. 90Note that | 81.Fa fromlen 82specifying its size. 83At the completion of a successful 84.Fn sctp_recvmsg 85call 86.Fa from 87will hold the address of the peer and 88.Fa fromlen 89will hold the length of that address. 90Note that |
| 91the address is bounded by the initial value of | 91the address is bounded by the initial value of |
| 92.Fa fromlen 93which is used as an in/out variable. 94.Pp | 92.Fa fromlen 93which is used as an in/out variable. 94.Pp |
| 95The length of the message | 95The length of the message |
| 96.Fa msg 97to be received is bounded by 98.Fa len . 99If the message is too long to fit in the users | 96.Fa msg 97to be received is bounded by 98.Fa len . 99If the message is too long to fit in the users |
| 100receive buffer, then the | 100receive buffer, then the |
| 101.Fa flags 102argument will 103.Em not 104have the 105.Dv MSG_EOF 106flag applied. 107If the message is a complete message then | 101.Fa flags 102argument will 103.Em not 104have the 105.Dv MSG_EOF 106flag applied. 107If the message is a complete message then |
| 108the | 108the |
| 109.Fa flags 110argument will have 111.Dv MSG_EOF 112set. | 109.Fa flags 110argument will have 111.Dv MSG_EOF 112set. |
| 113Locally detected errors are | 113Locally detected errors are |
| 114indicated by a return value of -1 with 115.Va errno 116set accordingly. | 114indicated by a return value of -1 with 115.Va errno 116set accordingly. |
| 117The | 117The |
| 118.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 125the peer endpoint, but instead is a notification from the --- 10 unchanged lines hidden (view full) --- 136.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. 139The 140.Xr select 2 141system call may be used to determine when it is possible to 142receive a message. 143.Pp | 118.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 125the peer endpoint, but instead is a notification from the --- 10 unchanged lines hidden (view full) --- 136.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. 139The 140.Xr select 2 141system call may be used to determine when it is possible to 142receive a message. 143.Pp |
| 144The | 144The |
| 145.Fa sinfo 146argument is defined as follows. 147.Bd -literal 148struct 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 161The 162.Fa sinfo->sinfo_ppid 163field is an opaque 32 bit value that is passed transparently | 145.Fa sinfo 146argument is defined as follows. 147.Bd -literal 148struct 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 161The 162.Fa sinfo->sinfo_ppid 163field is an opaque 32 bit value that is passed transparently |
| 164through the stack from the peer endpoint. | 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 */ --- 4 unchanged lines hidden (view full) --- 177flag is used to specify that the message arrived with no 178specific order and was delivered to the peer application 179as soon as possible. 180When this flag is absent the message 181was delivered in order within the stream it was received. 182.Pp 183The 184.Fa sinfo->sinfo_stream | 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 */ --- 4 unchanged lines hidden (view full) --- 177flag is used to specify that the message arrived with no 178specific order and was delivered to the peer application 179as soon as possible. 180When this flag is absent the message 181was delivered in order within the stream it was received. 182.Pp 183The 184.Fa sinfo->sinfo_stream |
| 185field is the SCTP stream that the message was received on. | 185field is the SCTP stream that the message was received on. |
| 186Streams in SCTP are reliable (or partially reliable) flows of ordered 187messages. 188.Pp 189The 190.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. 195Optionally a user process can use this value to index some application 196specific data structure for all data coming from a specific | 186Streams in SCTP are reliable (or partially reliable) flows of ordered 187messages. 188.Pp 189The 190.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. 195Optionally a user process can use this value to index some application 196specific data structure for all data coming from a specific |
| 197association. | 197association. |
| 198.Pp 199The 200.Fa sinfo->sinfo_ssn 201field will hold the stream sequence number assigned 202by the peer endpoint if the message is 203.Em not 204unordered. 205For unordered messages this field holds an undefined value. --- 19 unchanged lines hidden (view full) --- 225.Fa sinfo->sinfo_assoc_id 226is the unique association identification that was assigned 227to the association. 228For one-to-many (SOCK_SEQPACKET) type 229sockets this value can be used to send data to the peer without 230the use of an address field. 231It is also quite useful in 232setting various socket options on the specific association | 198.Pp 199The 200.Fa sinfo->sinfo_ssn 201field will hold the stream sequence number assigned 202by the peer endpoint if the message is 203.Em not 204unordered. 205For unordered messages this field holds an undefined value. --- 19 unchanged lines hidden (view full) --- 225.Fa sinfo->sinfo_assoc_id 226is the unique association identification that was assigned 227to the association. 228For one-to-many (SOCK_SEQPACKET) type 229sockets this value can be used to send data to the peer without 230the use of an address field. 231It is also quite useful in 232setting various socket options on the specific association |
| 233(see | 233(see |
| 234.Xr sctp 4 ) . 235.Pp 236The 237.Fa sinfo->info_timetolive | 234.Xr sctp 4 ) . 235.Pp 236The 237.Fa sinfo->info_timetolive |
| 238field is not used by | 238field is not used by |
| 239.Fn sctp_recvmsg . 240.Sh RETURN VALUES 241The call returns the number of bytes received, or -1 242if an error occurred. 243.Sh ERRORS 244The 245.Fn sctp_recvmsg 246system call --- 52 unchanged lines hidden --- | 239.Fn sctp_recvmsg . 240.Sh RETURN VALUES 241The call returns the number of bytes received, or -1 242if an error occurred. 243.Sh ERRORS 244The 245.Fn sctp_recvmsg 246system call --- 52 unchanged lines hidden --- |