16863 implement C23 stdbit.h
[illumos-gate.git] / usr / src / man / man3head / socket.h.3head
blob63884190132a8c6cf2dff8eaa04a0a0f3fc572fe
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document.  The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved.
44 .\" Portions Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
45 .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
46 .\" Copyright 2024 Oxide Computer Company
47 .\"
48 .TH SOCKET.H 3HEAD "July 2, 2024"
49 .SH NAME
50 socket.h, socket, CMSG_DATA, CMSG_FIRSTHDR, CMSG_LEN, CMSG_NXTHDR, CMSG_SPACE \- Internet Protocol family
51 .SH SYNOPSIS
52 .nf
53 \fB#include <sys/socket.h>\fR
54 .fi
56 .SH DESCRIPTION
57 The \fB<sys/socket.h>\fR header defines the unsigned integral type
58 \fBsa_family_t\fR through \fBtypedef\fR.
59 .sp
60 .LP
61 The \fB<sys/socket.h>\fR header defines the \fBsockaddr\fR structure that
62 includes the following members:
63 .sp
64 .in +2
65 .nf
66 sa_family_t   sa_family     /* address family */
67 char          sa_data[]     /* socket   address (variable-length
68                                 data) */
69 .fi
70 .in -2
72 .SS "\fBlibxnet\fR Interfaces"
73 The \fB<sys/socket.h>\fR header defines the \fBmsghdr\fR structure for
74 \fBlibxnet\fR interfaces that includes the following members:
75 .sp
76 .in +2
77 .nf
78 void            *msg_name         /* optional address */
79 socklen_t       msg_namelen       /* size of address */
80 struct iovec    *msg_iov          /* scatter/gather array */
81 int             msg_iovlen        /* members in msg_iov */
82 void            *msg_control      /* ancillary data, see below */
83 socklen_t       msg_controllen    /* ancillary data buffer len */
84 int             msg_flags         /* flags on received message */
85 .fi
86 .in -2
88 .sp
89 .LP
90 The \fB<sys/socket.h>\fR header defines the \fBcmsghdr\fR structure for
91 \fBlibxnet\fR that includes the following members:
92 .sp
93 .in +2
94 .nf
95 socklen_t  cmsg_len      /* data byte count, including hdr */
96 int        cmsg_level    /* originating protocol */
97 int        cmsg_type     /* protocol-specific type */
98 .fi
99 .in -2
103 Ancillary data consists of a sequence of pairs, each consisting of a
104 \fBcmsghdr\fR structure followed by a data array. The data array contains the
105 ancillary data message, and the \fBcmsghdr\fR structure contains descriptive
106 information that allows an application to correctly parse the data.
109 The values for \fBcmsg_level\fR will be legal values for the level argument to
110 the \fBgetsockopt()\fR and \fBsetsockopt()\fR functions. The \fBSCM_RIGHTS\fR
111 type is supported for level \fBSOL_SOCKET\fR.
114 Ancillary data is also possible at the socket level. The \fB<sys/socket.h>\fR
115 header defines the following macros for use as the \fBcmsg_type\fR values when
116 \fBcmsg_level\fR is \fBSOL_SOCKET\fR.
118 .ne 2
120 \fBSCM_RIGHTS\fR
122 .RS 14n
123 Indicates that the data array contains the access rights (set of open file
124 descriptors) to be sent or received. Each file descriptor requires one
125 \fBint\fR to send or receive.
129 .ne 2
131 \fBSCM_UCRED\fR
133 .RS 14n
134 Indicates that the data array contains a \fBucred_t\fR to be received. The
135 \fBucred_t\fR is the credential of the sending process at the time the message
136 was sent. This is a Sun-specific, Evolving interface. See \fBucred_get\fR(3C).
141 The IPv4 ancillary data formats are listed below by \fBcmsg_level\fR and
142 \fBcmsg_type\fR, along with the associated payload for each.
144 .ne 2
146 \fBIPPROTO_IP\fR, \fBIP_RECVDSTADDR\fR \(em \fBSOCK_DGRAM\fR only
148 .sp .6
149 .RS 4n
150 \fBipaddr_t\fR, IP address
154 .ne 2
156 \fBIPPROTO_IP\fR, \fBIP_RECVIF\fR
158 .sp .6
159 .RS 4n
160 \fBuint_t\fR, \fBifIndex\fR number
164 .ne 2
166 \fBIPPROTO_IP\fR, \fBIP_RECVOPTS\fR \(em \fBSOCK_DGRAM\fR only
168 .sp .6
169 .RS 4n
170 variable-length IP options, up to 40 bytes
174 .ne 2
176 \fBIPPROTO_IP\fR, \fBIP_RECVPKTINFO\fR \(em \fBSOCK_DGRAM\fR only
178 .sp .6
179 .RS 4n
180 \fBin_pktinfo_t\fR
184 .ne 2
186 \fBIPPROTO_IP\fR, \fBIP_RECVSLLA\fR \(em \fBSOCK_DGRAM\fR only
188 .sp .6
189 .RS 4n
190 \fBstruct sockaddr_dl\fR, link layer address
194 .ne 2
196 \fBIPPROTO_IP\fR, \fBIP_RECVTTL\fR \(em \fBSOCK_DGRAM\fR only
198 .sp .6
199 .RS 4n
200 \fBuint8_t\fR, the IP TTL (time to live)
204 .ne 2
206 \fBIPPROTO_IP\fR, \fBIP_RECVTOS\fR
208 .sp .6
209 .RS 4n
210 \fBuint8_t\fR, the IP TOS (type of service)
214 .ne 2
216 \fBSOL_SOCKET\fR, \fBSO_UCRED\fR
218 .sp .6
219 .RS 4n
220 \fBucred_t\fR
225 The IPv6 ancillary data formats are listed below by \fBcmsg_level\fR and
226 \fBcmsg_type\fR, along with the associated payload for each.
228 .ne 2
230 \fBIPPROTO_IPV6\fR, \fBIPV6_PKTINFO\fR
232 .sp .6
233 .RS 4n
234 \fBin_pktinfo_t\fR
238 .ne 2
240 \fBIPPROTO_IPV6\fR, \fBIPV6_TCLASS\fR
242 .sp .6
243 .RS 4n
244 \fBuint_t\fR
248 .ne 2
250 \fBIPPROTO_IPV6\fR, \fBIPV6_PATHMTU\fR
252 .sp .6
253 .RS 4n
254 \fBip6_mtuinfo\fR
258 .ne 2
260 \fBIPPROTO_IPV6\fR, \fBIPV6_HOPLIMIT\fR
262 .sp .6
263 .RS 4n
264 \fBuint_t\fR
268 .ne 2
270 \fBIPPROTO_IPV6\fR, \fBIPV6_HOPOPTS\fR
272 .sp .6
273 .RS 4n
274 variable-length IPv6 options
278 .ne 2
280 \fBIPPROTO_IPV6\fR, \fBIPV6_DSTOPTS\fR
282 .sp .6
283 .RS 4n
284 variable-length IPv6 options
288 .ne 2
290 \fBIPPROTO_IPV6\fR, \fBIPV6_RTHDR\fR
292 .sp .6
293 .RS 4n
294 variable-length IPv6 options
298 .ne 2
300 \fBIPPROTO_IPV6\fR, \fBIPV6_DSTOPTS\fR
302 .sp .6
303 .RS 4n
304 variable-length IPv6 options
309 The \fB<sys/socket.h>\fR header defines the following macros to gain access to
310 the data arrays in the ancillary data associated with a message header:
312 .ne 2
314 \fB\fBCMSG_DATA(\fR\fIcmsg\fR)\fR
316 .sp .6
317 .RS 4n
318 If the argument is a pointer to a \fBcmsghdr\fR structure, this macro returns
319 an unsigned character pointer to the data array associated with the
320 \fBcmsghdr\fR structure.
324 .ne 2
326 \fB\fBCMSG_NXTHDR(\fR\fImhdr\fR, \fIcmsg\fR)\fR
328 .sp .6
329 .RS 4n
330 If the first argument is a pointer to a \fBmsghdr\fR structure and the second
331 argument is a pointer to a \fBcmsghdr\fR structure in the ancillary data,
332 pointed to by the \fBmsg_control\fR field of that \fBmsghdr\fR structure, this
333 macro returns a pointer to the next \fBcmsghdr\fR structure, or a null pointer
334 if this structure is the last \fBcmsghdr\fR in the ancillary data.
338 .ne 2
340 \fB\fBCMSG_FIRSTHDR(\fR\fImhdr\fR)\fR
342 .sp .6
343 .RS 4n
344 If the argument is a pointer to a \fBmsghdr\fR structure, this macro returns a
345 pointer to the first \fBcmsghdr\fR structure in the ancillary data associated
346 with this \fBmsghdr\fR structure, or a null pointer if there is no ancillary
347 data associated with the \fBmsghdr\fR structure.
351 .ne 2
353 \fB\fBCMSG_SPACE\fR(\fIlen\fR)\fR
355 .sp .6
356 .RS 4n
357 Given the length of an ancillary data object, \fBCMSG_SPACE()\fR returns the
358 space required by the object and its \fBcmsghdr\fR structure, including any
359 padding needed to satisfy alignment requirements. This macro can be used, for
360 example, to allocate space dynamically for the ancillary data. This macro
361 should not be used to initialize the \fBcmsg_len\fR member of a \fBcmsghdr\fR
362 structure. Use the \fBCMSG_LEN()\fR macro instead.
366 .ne 2
368 \fB\fBCMSG_LEN\fR(\fIlen\fR)\fR
370 .sp .6
371 .RS 4n
372 Given the length of an ancillary data object, \fBCMSG_LEN()\fR returns the
373 value to store in the cmsg_len member of the \fBcmsghdr\fR structure, taking
374 into account any padding needed to satisfy alignment requirements.
379 The \fB<sys/socket.h>\fR header defines the \fBlinger\fR structure that
380 includes the following members:
382 .in +2
384 int   l_onoff   /* indicates  whether  linger option is enabled */
385 int   l_linger  /* linger time, in seconds */
387 .in -2
391 The \fB<sys/socket.h>\fR header defines the following macros which indicate
392 types of sockets:
394 .ne 2
396 \fBSOCK_DGRAM\fR
398 .RS 18n
399 Datagram socket
403 .ne 2
405 \fBSOCK_STREAM\fR
407 .RS 18n
408 Byte-stream socket
412 .ne 2
414 \fBSOCK_RAW\fR
416 .RS 18n
417 Raw protocol interface
421 .ne 2
423 \fBSOCK_RDM\fR
425 .RS 18n
426 Reliably delivered message
430 .ne 2
432 \fBSOCK_SEQPACKET\fR
434 .RS 18n
435 Sequenced-packet socket
440 In some cases, the above types are bitwise-inclusive-ORed with zero or more of
441 the following macros which modify the socket's default behavior:
444 .ne 2
446 \fBSOCK_CLOEXEC\fR
448 .RS 18n
449 The socket should have the close-on-exec, \fBFD_CLOEXEC\fR file descriptor flag
450 set on it. The socket will be closed when the process calls any of the
451 \fBexec\fR(2) family of functions.
455 .ne 2
457 \fBSOCK_CLOFORK\fR
459 .RS 18n
460 The socket should have the close-on-fork, \fBFD_CLOFORK\fR file descriptor flag
461 set on it. The socket will be closed in any child process created with the
462 \fBfork\fR(2) family of functions.
466 .ne 2
468 \fBSOCK_NDELAY\fR
470 .RS 18n
471 The socket should have the \fBO_NDELAY\fR flag set. See \fBopen\fR(2) for a
472 discussion of the specific non-blocking behavior this implies.
476 .ne 2
478 \fBSOCK_NONBLOCK\fR
480 .RS 18n
481 The socket should have the \fBO_NONBLOCK\fR flag set. See \fBopen\fR(2) for a
482 discussion of the specific non-blocking behavior this implies.
487 The \fB<sys/socket.h>\fR header defines the following macros for use as the
488 \fIlevel\fR argument of \fBsetsockopt()\fR and \fBgetsockopt()\fR.
490 .ne 2
492 \fBSOL_SOCKET\fR
494 .RS 14n
495 Options to be accessed at the socket level, not the protocol level.
499 .ne 2
501 \fBSOL_ROUTE\fR
503 .RS 14n
504 Options to be accessed at the routing socket level, not the protocol level.
509 The \fB<sys/socket.h>\fR header defines the following macros for use as the
510 \fIoption_name\fR argument of \fBgetsockopt()\fR or \fBsetsockopt()\fR calls:
512 .ne 2
514 \fBSO_DEBUG\fR
516 .RS 17n
517 Debugging information is being recorded.
521 .ne 2
523 \fBSO_ACCEPTCONN\fR
525 .RS 17n
526 Socket is accepting connections.
530 .ne 2
532 \fBSO_BROADCAST\fR
534 .RS 17n
535 Transmission of broadcast messages is supported.
539 .ne 2
541 \fBSO_REUSEADDR\fR
543 .RS 17n
544 Reuse of local addresses is supported.
548 .ne 2
550 \fBSO_KEEPALIVE\fR
552 .RS 17n
553 Connections are kept alive with periodic messages.
557 .ne 2
559 \fBSO_LINGER\fR
561 .RS 17n
562 Socket lingers on close.
566 .ne 2
568 \fBSO_OOBINLINE\fR
570 .RS 17n
571 Out-of-band data is transmitted in line.
575 .ne 2
577 \fBSO_SNDBUF\fR
579 .RS 17n
580 Send buffer size.
584 .ne 2
586 \fBSO_RCVBUF\fR
588 .RS 17n
589 Receive buffer size.
593 .ne 2
595 \fBSO_ERROR\fR
597 .RS 17n
598 Socket error status.
602 .ne 2
604 \fBSO_DOMAIN\fR
606 .RS 17n
607 Socket family.
611 .ne 2
613 \fBSO_TYPE\fR
615 .RS 17n
616 Socket type.
620 .ne 2
622 \fBSO_PROTOCOL\fR,
623 .B SO_PROTOTYPE
625 .RS 17n
626 Socket protocol.
630 .ne 2
632 \fBSO_RECVUCRED\fR
634 .RS 17n
635 Request the reception of user credential ancillary data. This is a
636 Sun-specific, Evolving interface. See \fBucred_get\fR(3C).
640 .ne 2
642 \fBSO_MAC_EXEMPT\fR
644 .RS 17n
645 Mandatory Access Control (\fBMAC\fR) exemption for unlabeled peers. This option
646 is available only if the system is configured with Trusted Extensions.
650 .ne 2
652 \fBSO_ALLZONES\fR
654 .RS 17n
655 Bypass zone boundaries (privileged).
660 The \fB<sys/socket.h>\fR header defines the following macros for use as the
661 valid values for the \fBmsg_flags\fR field in the \fBmsghdr\fR structure, or
662 the flags parameter in \fBrecvfrom()\fR, \fBrecvmsg()\fR, \fBsendto()\fR, or
663 \fBsendmsg()\fR calls:
665 .ne 2
667 \fBMSG_CTRUNC\fR
669 .RS 15n
670 Control data truncated.
674 .ne 2
676 \fBMSG_EOR\fR
678 .RS 15n
679 Terminates a record (if supported by the protocol).
683 .ne 2
685 \fBMSG_OOB\fR
687 .RS 15n
688 Out-of-band data.
692 .ne 2
694 \fBMSG_PEEK\fR
696 .RS 15n
697 Leave received data in queue.
701 .ne 2
703 \fBMSG_TRUNC\fR
705 .RS 15n
706 Normal data truncated.
710 .ne 2
712 \fBMSG_WAITALL\fR
714 .RS 15n
715 Wait for complete message.
719 .ne 2
721 \fBMSG_NOSIGNAL\fR
723 .RS 15n
724 Do not generate \fBSIGPIPE\fR signal.
728 .ne 2
730 \fBMSG_CMSG_CLOEXEC\fR
732 .RS 15n
733 When receiving a message with the \fBSCM_RIGHTS\fR ancillary data present, all
734 file descriptors should have the close-on-exec, \fBFD_CLOEXEC\fR flag set on
735 them. They will be closed when the process successfully calls any of the
736 \fBexec\fR(2) family of functions. This has no effect when sending
737 \fBSCM_RIGHTS\fR ancillary data.
741 .ne 2
743 \fBMSG_CMSG_CLOFORK\fR
745 .RS 15n
746 When receiving a message with the \fBSCM_RIGHTS\fR ancillary data present, all
747 file descriptors should have the close-on-fork, \fBFD_CLOFORK\fR flag set on
748 them. They will be closed in any child processes created with the \fBfork\fR(2)
749 family of functions. This has no effect when sending \fBSCM_RIGHTS\fR ancillary
750 data.
755 The \fB<sys/socket.h>\fR header defines the following macros:
757 .ne 2
759 \fBAF_UNIX\fR
761 .RS 11n
762 UNIX domain sockets
766 .ne 2
768 \fBAF_INET\fR
770 .RS 11n
771 Internet domain sockets
776 The \fB<sys/socket.h>\fR header defines the following macros:
778 .ne 2
780 \fBSHUT_RD\fR
782 .RS 13n
783 Disables further receive operations.
787 .ne 2
789 \fBSHUT_WR\fR
791 .RS 13n
792 Disables further send operations.
796 .ne 2
798 \fBSHUT_RDWR\fR
800 .RS 13n
801 Disables further send and receive operations.
804 .SS "\fBlibsocket\fR Interfaces"
805 The \fB<sys/socket.h>\fR header defines the \fBmsghdr\fR structure for
806 \fBlibsocket\fR interfaces that includes the following members:
808 .in +2
810 void           *msg_name        /* optional address */
811 socklen_t      msg_namelen      /* size of address */
812 struct iovec   *msg_iov         /* scatter/gather array */
813 int            msg_iovlen       /* # elements in msg_iov */
814 caddr_t        msg_accrights    /* access rights sent/received */
816 .in -2
820 The \fImsg_name\fR and \fImsg_namelen\fR parameters specify the destination
821 address when the socket is unconnected The \fImsg_name\fR can be specified as a
822 \fINULL\fR pointer if no names are desired or required. The \fImsg_iov\fR and
823 \fImsg_iovlen\fR parameters describe the scatter-gather locations, as described
824 in \fBread\fR(2). The \fImsg_accrights\fR parameter specifies the buffer in
825 which access rights sent along with the message are received. The
826 \fImsg_accrightslen\fR specifies the length of the buffer.
827 .SH ATTRIBUTES
828 See \fBattributes\fR(7) for descriptions of the following attributes:
833 box;
834 c | c
835 l | l .
836 ATTRIBUTE TYPE  ATTRIBUTE VALUE
838 Interface Stability     Standard
841 .SH SEE ALSO
842 .BR getpeerucred (3C),
843 .BR ucred_get (3C),
844 .BR libsocket (3LIB),
845 .BR accept (3SOCKET),
846 .BR bind (3SOCKET),
847 .BR connect (3SOCKET),
848 .BR getpeername (3SOCKET),
849 .BR getsockname (3SOCKET),
850 .BR getsockopt (3SOCKET),
851 .BR listen (3SOCKET),
852 .BR recv (3SOCKET),
853 .BR recvfrom (3SOCKET),
854 .BR recvmsg (3SOCKET),
855 .BR send (3SOCKET),
856 .BR sendmsg (3SOCKET),
857 .BR sendto (3SOCKET),
858 .BR setsockopt (3SOCKET),
859 .BR shutdown (3SOCKET),
860 .BR sockaddr (3SOCKET),
861 .BR socket (3SOCKET),
862 .BR socketpair (3SOCKET),
863 .BR accept (3XNET),
864 .BR bind (3XNET),
865 .BR connect (3XNET),
866 .BR getpeername (3XNET),
867 .BR getsockname (3XNET),
868 .BR getsockopt (3XNET),
869 .BR listen (3XNET),
870 .BR recv (3XNET),
871 .BR recvfrom (3XNET),
872 .BR recvmsg (3XNET),
873 .BR send (3XNET),
874 .BR sendmsg (3XNET),
875 .BR sendto (3XNET),
876 .BR setsockopt (3XNET),
877 .BR shutdown (3XNET),
878 .BR socket (3XNET),
879 .BR socketpair (3XNET),
880 .BR attributes (7),
881 .BR standards (7)