sctp_send.3 (fa9896e082a1046ff4fbc75fcba4d18d1f2efc19) sctp_send.3 (5590bacaafd8687bf522bb0413178c177c43f952)
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.

--- 11 unchanged lines hidden (view full) ---

20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
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.

--- 11 unchanged lines hidden (view full) ---

20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd December 15, 2006
28.Dd February 2, 2024
29.Dt SCTP_SEND 3
30.Os
31.Sh NAME
32.Nm sctp_send ,
29.Dt SCTP_SEND 3
30.Os
31.Sh NAME
32.Nm sctp_send ,
33.Nm sctp_sendx
33.Nm sctp_sendx ,
34.Nm sctp_sendv
34.Nd send a message from an SCTP socket
35.Sh LIBRARY
36.Lb libc
37.Sh SYNOPSIS
38.In sys/types.h
39.In sys/socket.h
40.In netinet/sctp.h
41.Ft ssize_t
42.Fo sctp_send
43.Fa "int sd" "const void *msg" "size_t len"
44.Fa "const struct sctp_sndrcvinfo *sinfo" "int flags"
45.Fc
46.Ft ssize_t
47.Fo sctp_sendx
48.Fa "int sd" "const void *msg" "size_t len" "struct sockaddr *addrs"
49.Fa "int addrcnt" "const struct sctp_sndrcvinfo *sinfo" "int flags"
50.Fc
35.Nd send a message from an SCTP socket
36.Sh LIBRARY
37.Lb libc
38.Sh SYNOPSIS
39.In sys/types.h
40.In sys/socket.h
41.In netinet/sctp.h
42.Ft ssize_t
43.Fo sctp_send
44.Fa "int sd" "const void *msg" "size_t len"
45.Fa "const struct sctp_sndrcvinfo *sinfo" "int flags"
46.Fc
47.Ft ssize_t
48.Fo sctp_sendx
49.Fa "int sd" "const void *msg" "size_t len" "struct sockaddr *addrs"
50.Fa "int addrcnt" "const struct sctp_sndrcvinfo *sinfo" "int flags"
51.Fc
52.Ft ssize_t
53.Fo sctp_sendv
54.Fa "int sd" "const struct iovec *iov" "int iocnt" "struct sockaddr *addrs"
55.Fa "int addrcnt" "void *info" "socklen_t infolen" "unsigned int infotype"
56.Fa "int flags"
57.Fc
51.Sh DESCRIPTION
52The
53.Fn sctp_send
54system call
55is used to transmit a message to another SCTP endpoint.
58.Sh DESCRIPTION
59The
60.Fn sctp_send
61system call
62is used to transmit a message to another SCTP endpoint.
63The
64.Fn sctp_sendx
65function is used to specify multiple peer addresses when creating an implicit
66association, as in
67.Xr sctp_connectx 3 .
68The
69.Fn sctp_sendv
70function is used to transmit a message whose data is gathered from the
71provided I/O buffers.
72.Pp
56.Fn sctp_send
57may be used to send data to an existing association for both
58one-to-many (SOCK_SEQPACKET) and one-to-one (SOCK_STREAM) socket types.
59The length of the message
60.Fa msg
61is given by
62.Fa len .
63If the message is too long to pass atomically through the

--- 184 unchanged lines hidden (view full) ---

248.Pp
249The fields
250.Fa sinfo->sinfo_ssn ,
251.Fa sinfo->sinfo_tsn ,
252and
253.Fa sinfo->sinfo_cumtsn
254are used only when receiving messages and are thus ignored by
255.Fn sctp_send .
73.Fn sctp_send
74may be used to send data to an existing association for both
75one-to-many (SOCK_SEQPACKET) and one-to-one (SOCK_STREAM) socket types.
76The length of the message
77.Fa msg
78is given by
79.Fa len .
80If the message is too long to pass atomically through the

--- 184 unchanged lines hidden (view full) ---

265.Pp
266The fields
267.Fa sinfo->sinfo_ssn ,
268.Fa sinfo->sinfo_tsn ,
269and
270.Fa sinfo->sinfo_cumtsn
271are used only when receiving messages and are thus ignored by
272.Fn sctp_send .
273.Pp
256The function
257.Fn sctp_sendx
258has the same properties as
259.Fn sctp_send
260with the additional arguments of an array of sockaddr structures
261passed in.
262With the
263.Fa addrs

--- 12 unchanged lines hidden (view full) ---

276to the association.
277Note that if the
278.Fa sinfo->sinfo_assoc_id
279field is 0, then the first address will be used to look up
280the association in place of the association id.
281If both
282an address and an association id are specified, the association
283id has priority.
274The function
275.Fn sctp_sendx
276has the same properties as
277.Fn sctp_send
278with the additional arguments of an array of sockaddr structures
279passed in.
280With the
281.Fa addrs

--- 12 unchanged lines hidden (view full) ---

294to the association.
295Note that if the
296.Fa sinfo->sinfo_assoc_id
297field is 0, then the first address will be used to look up
298the association in place of the association id.
299If both
300an address and an association id are specified, the association
301id has priority.
302.Pp
303The function
304.Fn sctp_sendv
305works as
306.Fn sctp_sendx ,
307with two differences.
308Firstly, the data to be written is passed as an array containing
309.Vt iocnt
310objects of type
311.Vt struct iovec ,
312which will be gathered for sending in the same manner as
313.Xr writev 2 .
314Secondly, the
315.Fa info
316argument is replaced by the tuple
317.Fa sinfo ,
318.Fa infolen ,
319.Fa infotype ,
320where
321.Fa sinfo
322is a pointer to a struct of size
323.Fa infolen
324whose type is indicated by the
325.Fa infotype
326argument.
327.Pp
328If no information is passed, set
329.Fa infotype
330to
331.Va SCTP_SENDV_NOINFO .
332.Fa sinfo
333may be a null pointer.
334.Pp
335If
336.Fa sinfo
337points to a
338.Vt struct sctp_sndinfo ,
339set
340.Fa infotype
341to
342.Va SCTP_SENDV_SNDINFO .
343The
344.Vt sctp_sndinfo
345structure has the following format:
346.Bd -literal
347struct sctp_sndinfo {
348 uint16_t snd_sid; /* stream identifier */
349 uint16_t snd_flags; /* Flags */
350 uint32_t snd_ppid; /* ppid field */
351 uint32_t snd_context; /* context field */
352 sctp_assoc_t snd_assoc_id; /* association id */
353};
354.Ed
355.Pp
356The meaning of these fields is the same as in
357.Vt struct sctp_sndrcvinfo ,
358described above.
359.Pp
360If
361.Fa sinfo
362points to a
363.Vt struct sctp_authinfo ,
364set
365.Fa infotype
366to
367.Va SCTP_SENDV_AUTHINFO .
368The
369.Vt sctp_authinfo
370struct has the following format:
371.Bd -literal
372struct sctp_authinfo {
373 uint16_t auth_keynumber; /* Shared key identifier */
374};
375.Ed
376.Pp
377The
378.Va auth_keynumber
379field specifies the shared key identifier that will be used for sending the
380message.
381.Pp
382If
383.Fa sinfo
384points to a
385.Vt struct sctp_prinfo ,
386set
387.Fa infotype
388to
389.Va SCTP_SENDV_PRINFO .
390The
391.Vt sctp_prinfo
392structure has the following format:
393.Bd -literal
394struct sctp_prinfo {
395 uint16_t pr_policy; /* PR-SCTP policy */
396 uint32_t pr_value; /* PR-SCTP Policy option */
397};
398.Ed
399.Pp
400The
401.Va pr_policy
402field should be set to either
403.Va SCTP_PR_SCTP_NONE
404to use reliable transmission (in which case the field
405.Va pr_value
406is ignored), or
407.Va SCTP_PR_SCTP_TTL
408to use RFC 3758 timed reliability, in which case the field
409.Va pr_value
410contains the lifetime in milliseconds.
411.Pp
412To pass two or more types in
413.Fa sinfo ,
414set
415.Fa infotype
416to
417.Va SCTP_SENDV_SPA
418and pass a pointer to a
419.Vt struct sctp_sendv_spa
420in
421.Fa sinfo .
422The
423.Ft sctp_sendv_spa
424structure has the following format:
425.Bd -literal
426struct sctp_sendv_spa {
427 uint32_t sendv_flags;
428 struct sctp_sndinfo sendv_sndinfo;
429 struct sctp_prinfo sendv_prinfo;
430 struct sctp_authinfo sendv_authinfo;
431};
432.Ed
433.Pp
434The
435.Va sendv_flags
436member should be set to the bitwise OR of the flags
437.Va SCTP_SEND_SNDINFO_VALID ,
438.Va SCTP_SEND_PRINFO_VALID ,
439and
440.Va SCTP_SEND_AUTHINFO_VALID
441to indicate which fields of the struct contain valid data.
442.Pp
443If
444.Fa infotype
445is set to SCTP_SENDV_NOINFO, the
446.Fa infolen
447argument should be set to zero.
448Otherwise,
449.Fa infolen
450should be set to the length of the data structure pointed to by
451.Fa info .
284.Sh RETURN VALUES
285The call returns the number of characters sent, or -1
286if an error occurred.
287.Sh ERRORS
288The
289.Fn sctp_send
290system call
291fails if:

--- 32 unchanged lines hidden (view full) ---

324SCTP_ABORT flag was specified on a non-existing association.
325.It Bq Er EPIPE
326The socket is unable to send anymore data
327.Dv ( SBS_CANTSENDMORE
328has been set on the socket).
329This typically means that the socket
330is not connected and is a one-to-one style socket.
331.El
452.Sh RETURN VALUES
453The call returns the number of characters sent, or -1
454if an error occurred.
455.Sh ERRORS
456The
457.Fn sctp_send
458system call
459fails if:

--- 32 unchanged lines hidden (view full) ---

492SCTP_ABORT flag was specified on a non-existing association.
493.It Bq Er EPIPE
494The socket is unable to send anymore data
495.Dv ( SBS_CANTSENDMORE
496has been set on the socket).
497This typically means that the socket
498is not connected and is a one-to-one style socket.
499.El
500.Sh NOTES
501The functions
502.Fn sctp_send
503and
504.Fn sctp_sendx
505are deprecated.
506New applications should use
507.Fn sctp_sendv .
332.Sh SEE ALSO
333.Xr getsockopt 2 ,
334.Xr recv 2 ,
335.Xr select 2 ,
336.Xr sendmsg 2 ,
337.Xr socket 2 ,
338.Xr write 2 ,
339.Xr sctp_connectx 3 ,
340.Xr sctp_recvmsg 3 ,
341.Xr sctp_sendmsg 3 ,
342.Xr sctp 4
508.Sh SEE ALSO
509.Xr getsockopt 2 ,
510.Xr recv 2 ,
511.Xr select 2 ,
512.Xr sendmsg 2 ,
513.Xr socket 2 ,
514.Xr write 2 ,
515.Xr sctp_connectx 3 ,
516.Xr sctp_recvmsg 3 ,
517.Xr sctp_sendmsg 3 ,
518.Xr sctp 4
519.Rs
520.%A R. Stewart
521.%A M. Tuexen
522.%A K. Poon
523.%A P. Lei
524.%A V. Yasevich
525.%T Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)
526.%R RFC 6458
527.%D December 2011
528.Re
529.Sh STANDARDS
530The functions described in this document conform to RFC 6458.
343.Sh BUGS
344Because
345.Fn sctp_send
346may have multiple associations under one endpoint, a
347select on write will only work for a one-to-one style
348socket.
531.Sh BUGS
532Because
533.Fn sctp_send
534may have multiple associations under one endpoint, a
535select on write will only work for a one-to-one style
536socket.