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/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
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.
25 .\" This notice shall appear on any product containing this material.
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.
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.
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]
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
48 .TH SOCKET.H 3HEAD "July 2, 2024"
50 socket.h, socket, CMSG_DATA, CMSG_FIRSTHDR, CMSG_LEN, CMSG_NXTHDR, CMSG_SPACE \- Internet Protocol family
53 \fB#include <sys/socket.h>\fR
57 The \fB<sys/socket.h>\fR header defines the unsigned integral type
58 \fBsa_family_t\fR through \fBtypedef\fR.
61 The \fB<sys/socket.h>\fR header defines the \fBsockaddr\fR structure that
62 includes the following members:
66 sa_family_t sa_family /* address family */
67 char sa_data[] /* socket address (variable-length
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:
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 */
90 The \fB<sys/socket.h>\fR header defines the \fBcmsghdr\fR structure for
91 \fBlibxnet\fR that includes the following members:
95 socklen_t cmsg_len /* data byte count, including hdr */
96 int cmsg_level /* originating protocol */
97 int cmsg_type /* protocol-specific type */
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.
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.
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.
146 \fBIPPROTO_IP\fR, \fBIP_RECVDSTADDR\fR \(em \fBSOCK_DGRAM\fR only
150 \fBipaddr_t\fR, IP address
156 \fBIPPROTO_IP\fR, \fBIP_RECVIF\fR
160 \fBuint_t\fR, \fBifIndex\fR number
166 \fBIPPROTO_IP\fR, \fBIP_RECVOPTS\fR \(em \fBSOCK_DGRAM\fR only
170 variable-length IP options, up to 40 bytes
176 \fBIPPROTO_IP\fR, \fBIP_RECVPKTINFO\fR \(em \fBSOCK_DGRAM\fR only
186 \fBIPPROTO_IP\fR, \fBIP_RECVSLLA\fR \(em \fBSOCK_DGRAM\fR only
190 \fBstruct sockaddr_dl\fR, link layer address
196 \fBIPPROTO_IP\fR, \fBIP_RECVTTL\fR \(em \fBSOCK_DGRAM\fR only
200 \fBuint8_t\fR, the IP TTL (time to live)
206 \fBIPPROTO_IP\fR, \fBIP_RECVTOS\fR
210 \fBuint8_t\fR, the IP TOS (type of service)
216 \fBSOL_SOCKET\fR, \fBSO_UCRED\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.
230 \fBIPPROTO_IPV6\fR, \fBIPV6_PKTINFO\fR
240 \fBIPPROTO_IPV6\fR, \fBIPV6_TCLASS\fR
250 \fBIPPROTO_IPV6\fR, \fBIPV6_PATHMTU\fR
260 \fBIPPROTO_IPV6\fR, \fBIPV6_HOPLIMIT\fR
270 \fBIPPROTO_IPV6\fR, \fBIPV6_HOPOPTS\fR
274 variable-length IPv6 options
280 \fBIPPROTO_IPV6\fR, \fBIPV6_DSTOPTS\fR
284 variable-length IPv6 options
290 \fBIPPROTO_IPV6\fR, \fBIPV6_RTHDR\fR
294 variable-length IPv6 options
300 \fBIPPROTO_IPV6\fR, \fBIPV6_DSTOPTS\fR
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:
314 \fB\fBCMSG_DATA(\fR\fIcmsg\fR)\fR
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.
326 \fB\fBCMSG_NXTHDR(\fR\fImhdr\fR, \fIcmsg\fR)\fR
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.
340 \fB\fBCMSG_FIRSTHDR(\fR\fImhdr\fR)\fR
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.
353 \fB\fBCMSG_SPACE\fR(\fIlen\fR)\fR
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.
368 \fB\fBCMSG_LEN\fR(\fIlen\fR)\fR
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:
384 int l_onoff /* indicates whether linger option is enabled */
385 int l_linger /* linger time, in seconds */
391 The \fB<sys/socket.h>\fR header defines the following macros which indicate
417 Raw protocol interface
426 Reliably delivered message
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:
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.
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.
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.
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.
495 Options to be accessed at the socket level, not the protocol level.
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:
517 Debugging information is being recorded.
526 Socket is accepting connections.
535 Transmission of broadcast messages is supported.
544 Reuse of local addresses is supported.
553 Connections are kept alive with periodic messages.
562 Socket lingers on close.
571 Out-of-band data is transmitted in line.
635 Request the reception of user credential ancillary data. This is a
636 Sun-specific, Evolving interface. See \fBucred_get\fR(3C).
645 Mandatory Access Control (\fBMAC\fR) exemption for unlabeled peers. This option
646 is available only if the system is configured with Trusted Extensions.
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:
670 Control data truncated.
679 Terminates a record (if supported by the protocol).
697 Leave received data in queue.
706 Normal data truncated.
715 Wait for complete message.
724 Do not generate \fBSIGPIPE\fR signal.
730 \fBMSG_CMSG_CLOEXEC\fR
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.
743 \fBMSG_CMSG_CLOFORK\fR
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
755 The \fB<sys/socket.h>\fR header defines the following macros:
771 Internet domain sockets
776 The \fB<sys/socket.h>\fR header defines the following macros:
783 Disables further receive operations.
792 Disables further send operations.
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:
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 */
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.
828 See \fBattributes\fR(7) for descriptions of the following attributes:
836 ATTRIBUTE TYPE ATTRIBUTE VALUE
838 Interface Stability Standard
842 .BR getpeerucred (3C),
844 .BR libsocket (3LIB),
845 .BR accept (3SOCKET),
847 .BR connect (3SOCKET),
848 .BR getpeername (3SOCKET),
849 .BR getsockname (3SOCKET),
850 .BR getsockopt (3SOCKET),
851 .BR listen (3SOCKET),
853 .BR recvfrom (3SOCKET),
854 .BR recvmsg (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),
866 .BR getpeername (3XNET),
867 .BR getsockname (3XNET),
868 .BR getsockopt (3XNET),
871 .BR recvfrom (3XNET),
876 .BR setsockopt (3XNET),
877 .BR shutdown (3XNET),
879 .BR socketpair (3XNET),