.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved.
.\" Portions Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
.\" Copyright 2024 Oxide Computer Company
.\"
.TH SOCKET.H 3HEAD "July 2, 2024"
.SH NAME
socket.h, socket, CMSG_DATA, CMSG_FIRSTHDR, CMSG_LEN, CMSG_NXTHDR, CMSG_SPACE \- Internet Protocol family
.SH SYNOPSIS
.nf
\fB#include <sys/socket.h>\fR
.fi

.SH DESCRIPTION
The \fB<sys/socket.h>\fR header defines the unsigned integral type
\fBsa_family_t\fR through \fBtypedef\fR.
.sp
.LP
The \fB<sys/socket.h>\fR header defines the \fBsockaddr\fR structure that
includes the following members:
.sp
.in +2
.nf
sa_family_t   sa_family     /* address family */
char          sa_data[]     /* socket   address (variable-length
                                data) */
.fi
.in -2

.SS "\fBlibxnet\fR Interfaces"
The \fB<sys/socket.h>\fR header defines the \fBmsghdr\fR structure for
\fBlibxnet\fR interfaces that includes the following members:
.sp
.in +2
.nf
void            *msg_name         /* optional address */
socklen_t       msg_namelen       /* size of address */
struct iovec    *msg_iov          /* scatter/gather array */
int             msg_iovlen        /* members in msg_iov */
void            *msg_control      /* ancillary data, see below */
socklen_t       msg_controllen    /* ancillary data buffer len */
int             msg_flags         /* flags on received message */
.fi
.in -2

.sp
.LP
The \fB<sys/socket.h>\fR header defines the \fBcmsghdr\fR structure for
\fBlibxnet\fR that includes the following members:
.sp
.in +2
.nf
socklen_t  cmsg_len      /* data byte count, including hdr */
int        cmsg_level    /* originating protocol */
int        cmsg_type     /* protocol-specific type */
.fi
.in -2

.sp
.LP
Ancillary data consists of a sequence of pairs, each consisting of a
\fBcmsghdr\fR structure followed by a data array. The data array contains the
ancillary data message, and the \fBcmsghdr\fR structure contains descriptive
information that allows an application to correctly parse the data.
.sp
.LP
The values for \fBcmsg_level\fR will be legal values for the level argument to
the \fBgetsockopt()\fR and \fBsetsockopt()\fR functions. The \fBSCM_RIGHTS\fR
type is supported for level \fBSOL_SOCKET\fR.
.sp
.LP
Ancillary data is also possible at the socket level. The \fB<sys/socket.h>\fR
header defines the following macros for use as the \fBcmsg_type\fR values when
\fBcmsg_level\fR is \fBSOL_SOCKET\fR.
.sp
.ne 2
.na
\fBSCM_RIGHTS\fR
.ad
.RS 14n
Indicates that the data array contains the access rights (set of open file
descriptors) to be sent or received. Each file descriptor requires one
\fBint\fR to send or receive.
.RE

.sp
.ne 2
.na
\fBSCM_UCRED\fR
.ad
.RS 14n
Indicates that the data array contains a \fBucred_t\fR to be received. The
\fBucred_t\fR is the credential of the sending process at the time the message
was sent. This is a Sun-specific, Evolving interface. See \fBucred_get\fR(3C).
.RE

.sp
.LP
The IPv4 ancillary data formats are listed below by \fBcmsg_level\fR and
\fBcmsg_type\fR, along with the associated payload for each.
.sp
.ne 2
.na
\fBIPPROTO_IP\fR, \fBIP_RECVDSTADDR\fR \(em \fBSOCK_DGRAM\fR only
.ad
.sp .6
.RS 4n
\fBipaddr_t\fR, IP address
.RE

.sp
.ne 2
.na
\fBIPPROTO_IP\fR, \fBIP_RECVIF\fR
.ad
.sp .6
.RS 4n
\fBuint_t\fR, \fBifIndex\fR number
.RE

.sp
.ne 2
.na
\fBIPPROTO_IP\fR, \fBIP_RECVOPTS\fR \(em \fBSOCK_DGRAM\fR only
.ad
.sp .6
.RS 4n
variable-length IP options, up to 40 bytes
.RE

.sp
.ne 2
.na
\fBIPPROTO_IP\fR, \fBIP_RECVPKTINFO\fR \(em \fBSOCK_DGRAM\fR only
.ad
.sp .6
.RS 4n
\fBin_pktinfo_t\fR
.RE

.sp
.ne 2
.na
\fBIPPROTO_IP\fR, \fBIP_RECVSLLA\fR \(em \fBSOCK_DGRAM\fR only
.ad
.sp .6
.RS 4n
\fBstruct sockaddr_dl\fR, link layer address
.RE

.sp
.ne 2
.na
\fBIPPROTO_IP\fR, \fBIP_RECVTTL\fR \(em \fBSOCK_DGRAM\fR only
.ad
.sp .6
.RS 4n
\fBuint8_t\fR, the IP TTL (time to live)
.RE

.sp
.ne 2
.na
\fBIPPROTO_IP\fR, \fBIP_RECVTOS\fR
.ad
.sp .6
.RS 4n
\fBuint8_t\fR, the IP TOS (type of service)
.RE

.sp
.ne 2
.na
\fBSOL_SOCKET\fR, \fBSO_UCRED\fR
.ad
.sp .6
.RS 4n
\fBucred_t\fR
.RE

.sp
.LP
The IPv6 ancillary data formats are listed below by \fBcmsg_level\fR and
\fBcmsg_type\fR, along with the associated payload for each.
.sp
.ne 2
.na
\fBIPPROTO_IPV6\fR, \fBIPV6_PKTINFO\fR
.ad
.sp .6
.RS 4n
\fBin_pktinfo_t\fR
.RE

.sp
.ne 2
.na
\fBIPPROTO_IPV6\fR, \fBIPV6_TCLASS\fR
.ad
.sp .6
.RS 4n
\fBuint_t\fR
.RE

.sp
.ne 2
.na
\fBIPPROTO_IPV6\fR, \fBIPV6_PATHMTU\fR
.ad
.sp .6
.RS 4n
\fBip6_mtuinfo\fR
.RE

.sp
.ne 2
.na
\fBIPPROTO_IPV6\fR, \fBIPV6_HOPLIMIT\fR
.ad
.sp .6
.RS 4n
\fBuint_t\fR
.RE

.sp
.ne 2
.na
\fBIPPROTO_IPV6\fR, \fBIPV6_HOPOPTS\fR
.ad
.sp .6
.RS 4n
variable-length IPv6 options
.RE

.sp
.ne 2
.na
\fBIPPROTO_IPV6\fR, \fBIPV6_DSTOPTS\fR
.ad
.sp .6
.RS 4n
variable-length IPv6 options
.RE

.sp
.ne 2
.na
\fBIPPROTO_IPV6\fR, \fBIPV6_RTHDR\fR
.ad
.sp .6
.RS 4n
variable-length IPv6 options
.RE

.sp
.ne 2
.na
\fBIPPROTO_IPV6\fR, \fBIPV6_DSTOPTS\fR
.ad
.sp .6
.RS 4n
variable-length IPv6 options
.RE

.sp
.LP
The \fB<sys/socket.h>\fR header defines the following macros to gain access to
the data arrays in the ancillary data associated with a message header:
.sp
.ne 2
.na
\fB\fBCMSG_DATA(\fR\fIcmsg\fR)\fR
.ad
.sp .6
.RS 4n
If the argument is a pointer to a \fBcmsghdr\fR structure, this macro returns
an unsigned character pointer to the data array associated with the
\fBcmsghdr\fR structure.
.RE

.sp
.ne 2
.na
\fB\fBCMSG_NXTHDR(\fR\fImhdr\fR, \fIcmsg\fR)\fR
.ad
.sp .6
.RS 4n
If the first argument is a pointer to a \fBmsghdr\fR structure and the second
argument is a pointer to a \fBcmsghdr\fR structure in the ancillary data,
pointed to by the \fBmsg_control\fR field of that \fBmsghdr\fR structure, this
macro returns a pointer to the next \fBcmsghdr\fR structure, or a null pointer
if this structure is the last \fBcmsghdr\fR in the ancillary data.
.RE

.sp
.ne 2
.na
\fB\fBCMSG_FIRSTHDR(\fR\fImhdr\fR)\fR
.ad
.sp .6
.RS 4n
If the argument is a pointer to a \fBmsghdr\fR structure, this macro returns a
pointer to the first \fBcmsghdr\fR structure in the ancillary data associated
with this \fBmsghdr\fR structure, or a null pointer if there is no ancillary
data associated with the \fBmsghdr\fR structure.
.RE

.sp
.ne 2
.na
\fB\fBCMSG_SPACE\fR(\fIlen\fR)\fR
.ad
.sp .6
.RS 4n
Given the length of an ancillary data object, \fBCMSG_SPACE()\fR returns the
space required by the object and its \fBcmsghdr\fR structure, including any
padding needed to satisfy alignment requirements. This macro can be used, for
example, to allocate space dynamically for the ancillary data. This macro
should not be used to initialize the \fBcmsg_len\fR member of a \fBcmsghdr\fR
structure. Use the \fBCMSG_LEN()\fR macro instead.
.RE

.sp
.ne 2
.na
\fB\fBCMSG_LEN\fR(\fIlen\fR)\fR
.ad
.sp .6
.RS 4n
Given the length of an ancillary data object, \fBCMSG_LEN()\fR returns the
value to store in the cmsg_len member of the \fBcmsghdr\fR structure, taking
into account any padding needed to satisfy alignment requirements.
.RE

.sp
.LP
The \fB<sys/socket.h>\fR header defines the \fBlinger\fR structure that
includes the following members:
.sp
.in +2
.nf
int   l_onoff   /* indicates  whether  linger option is enabled */
int   l_linger  /* linger time, in seconds */
.fi
.in -2

.sp
.LP
The \fB<sys/socket.h>\fR header defines the following macros which indicate
types of sockets:
.sp
.ne 2
.na
\fBSOCK_DGRAM\fR
.ad
.RS 18n
Datagram socket
.RE

.sp
.ne 2
.na
\fBSOCK_STREAM\fR
.ad
.RS 18n
Byte-stream socket
.RE

.sp
.ne 2
.na
\fBSOCK_RAW\fR
.ad
.RS 18n
Raw protocol interface
.RE

.sp
.ne 2
.na
\fBSOCK_RDM\fR
.ad
.RS 18n
Reliably delivered message
.RE

.sp
.ne 2
.na
\fBSOCK_SEQPACKET\fR
.ad
.RS 18n
Sequenced-packet socket
.RE

.sp
.LP
In some cases, the above types are bitwise-inclusive-ORed with zero or more of
the following macros which modify the socket's default behavior:

.sp
.ne 2
.na
\fBSOCK_CLOEXEC\fR
.ad
.RS 18n
The socket should have the close-on-exec, \fBFD_CLOEXEC\fR file descriptor flag
set on it. The socket will be closed when the process calls any of the
\fBexec\fR(2) family of functions.
.RE

.sp
.ne 2
.na
\fBSOCK_CLOFORK\fR
.ad
.RS 18n
The socket should have the close-on-fork, \fBFD_CLOFORK\fR file descriptor flag
set on it. The socket will be closed in any child process created with the
\fBfork\fR(2) family of functions.
.RE

.sp
.ne 2
.na
\fBSOCK_NDELAY\fR
.ad
.RS 18n
The socket should have the \fBO_NDELAY\fR flag set. See \fBopen\fR(2) for a
discussion of the specific non-blocking behavior this implies.
.RE

.sp
.ne 2
.na
\fBSOCK_NONBLOCK\fR
.ad
.RS 18n
The socket should have the \fBO_NONBLOCK\fR flag set. See \fBopen\fR(2) for a
discussion of the specific non-blocking behavior this implies.
.RE

.sp
.LP
The \fB<sys/socket.h>\fR header defines the following macros for use as the
\fIlevel\fR argument of \fBsetsockopt()\fR and \fBgetsockopt()\fR.
.sp
.ne 2
.na
\fBSOL_SOCKET\fR
.ad
.RS 14n
Options to be accessed at the socket level, not the protocol level.
.RE

.sp
.ne 2
.na
\fBSOL_ROUTE\fR
.ad
.RS 14n
Options to be accessed at the routing socket level, not the protocol level.
.RE

.sp
.LP
The \fB<sys/socket.h>\fR header defines the following macros for use as the
\fIoption_name\fR argument of \fBgetsockopt()\fR or \fBsetsockopt()\fR calls:
.sp
.ne 2
.na
\fBSO_DEBUG\fR
.ad
.RS 17n
Debugging information is being recorded.
.RE

.sp
.ne 2
.na
\fBSO_ACCEPTCONN\fR
.ad
.RS 17n
Socket is accepting connections.
.RE

.sp
.ne 2
.na
\fBSO_BROADCAST\fR
.ad
.RS 17n
Transmission of broadcast messages is supported.
.RE

.sp
.ne 2
.na
\fBSO_REUSEADDR\fR
.ad
.RS 17n
Reuse of local addresses is supported.
.RE

.sp
.ne 2
.na
\fBSO_KEEPALIVE\fR
.ad
.RS 17n
Connections are kept alive with periodic messages.
.RE

.sp
.ne 2
.na
\fBSO_LINGER\fR
.ad
.RS 17n
Socket lingers on close.
.RE

.sp
.ne 2
.na
\fBSO_OOBINLINE\fR
.ad
.RS 17n
Out-of-band data is transmitted in line.
.RE

.sp
.ne 2
.na
\fBSO_SNDBUF\fR
.ad
.RS 17n
Send buffer size.
.RE

.sp
.ne 2
.na
\fBSO_RCVBUF\fR
.ad
.RS 17n
Receive buffer size.
.RE

.sp
.ne 2
.na
\fBSO_ERROR\fR
.ad
.RS 17n
Socket error status.
.RE

.sp
.ne 2
.na
\fBSO_DOMAIN\fR
.ad
.RS 17n
Socket family.
.RE

.sp
.ne 2
.na
\fBSO_TYPE\fR
.ad
.RS 17n
Socket type.
.RE

.sp
.ne 2
.na
\fBSO_PROTOCOL\fR,
.B SO_PROTOTYPE
.ad
.RS 17n
Socket protocol.
.RE

.sp
.ne 2
.na
\fBSO_RECVUCRED\fR
.ad
.RS 17n
Request the reception of user credential ancillary data. This is a
Sun-specific, Evolving interface. See \fBucred_get\fR(3C).
.RE

.sp
.ne 2
.na
\fBSO_MAC_EXEMPT\fR
.ad
.RS 17n
Mandatory Access Control (\fBMAC\fR) exemption for unlabeled peers. This option
is available only if the system is configured with Trusted Extensions.
.RE

.sp
.ne 2
.na
\fBSO_ALLZONES\fR
.ad
.RS 17n
Bypass zone boundaries (privileged).
.RE

.sp
.LP
The \fB<sys/socket.h>\fR header defines the following macros for use as the
valid values for the \fBmsg_flags\fR field in the \fBmsghdr\fR structure, or
the flags parameter in \fBrecvfrom()\fR, \fBrecvmsg()\fR, \fBsendto()\fR, or
\fBsendmsg()\fR calls:
.sp
.ne 2
.na
\fBMSG_CTRUNC\fR
.ad
.RS 15n
Control data truncated.
.RE

.sp
.ne 2
.na
\fBMSG_EOR\fR
.ad
.RS 15n
Terminates a record (if supported by the protocol).
.RE

.sp
.ne 2
.na
\fBMSG_OOB\fR
.ad
.RS 15n
Out-of-band data.
.RE

.sp
.ne 2
.na
\fBMSG_PEEK\fR
.ad
.RS 15n
Leave received data in queue.
.RE

.sp
.ne 2
.na
\fBMSG_TRUNC\fR
.ad
.RS 15n
Normal data truncated.
.RE

.sp
.ne 2
.na
\fBMSG_WAITALL\fR
.ad
.RS 15n
Wait for complete message.
.RE

.sp
.ne 2
.na
\fBMSG_NOSIGNAL\fR
.ad
.RS 15n
Do not generate \fBSIGPIPE\fR signal.
.RE

.sp
.ne 2
.na
\fBMSG_CMSG_CLOEXEC\fR
.ad
.RS 15n
When receiving a message with the \fBSCM_RIGHTS\fR ancillary data present, all
file descriptors should have the close-on-exec, \fBFD_CLOEXEC\fR flag set on
them. They will be closed when the process successfully calls any of the
\fBexec\fR(2) family of functions. This has no effect when sending
\fBSCM_RIGHTS\fR ancillary data.
.RE

.sp
.ne 2
.na
\fBMSG_CMSG_CLOFORK\fR
.ad
.RS 15n
When receiving a message with the \fBSCM_RIGHTS\fR ancillary data present, all
file descriptors should have the close-on-fork, \fBFD_CLOFORK\fR flag set on
them. They will be closed in any child processes created with the \fBfork\fR(2)
family of functions. This has no effect when sending \fBSCM_RIGHTS\fR ancillary
data.
.RE

.sp
.LP
The \fB<sys/socket.h>\fR header defines the following macros:
.sp
.ne 2
.na
\fBAF_UNIX\fR
.ad
.RS 11n
UNIX domain sockets
.RE

.sp
.ne 2
.na
\fBAF_INET\fR
.ad
.RS 11n
Internet domain sockets
.RE

.sp
.LP
The \fB<sys/socket.h>\fR header defines the following macros:
.sp
.ne 2
.na
\fBSHUT_RD\fR
.ad
.RS 13n
Disables further receive operations.
.RE

.sp
.ne 2
.na
\fBSHUT_WR\fR
.ad
.RS 13n
Disables further send operations.
.RE

.sp
.ne 2
.na
\fBSHUT_RDWR\fR
.ad
.RS 13n
Disables further send and receive operations.
.RE

.SS "\fBlibsocket\fR Interfaces"
The \fB<sys/socket.h>\fR header defines the \fBmsghdr\fR structure for
\fBlibsocket\fR interfaces that includes the following members:
.sp
.in +2
.nf
void           *msg_name        /* optional address */
socklen_t      msg_namelen      /* size of address */
struct iovec   *msg_iov         /* scatter/gather array */
int            msg_iovlen       /* # elements in msg_iov */
caddr_t        msg_accrights    /* access rights sent/received */
.fi
.in -2

.sp
.LP
The \fImsg_name\fR and \fImsg_namelen\fR parameters specify the destination
address when the socket is unconnected The \fImsg_name\fR can be specified as a
\fINULL\fR pointer if no names are desired or required. The \fImsg_iov\fR and
\fImsg_iovlen\fR parameters describe the scatter-gather locations, as described
in \fBread\fR(2). The \fImsg_accrights\fR parameter specifies the buffer in
which access rights sent along with the message are received. The
\fImsg_accrightslen\fR specifies the length of the buffer.
.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
.TE

.SH SEE ALSO
.BR getpeerucred (3C),
.BR ucred_get (3C),
.BR libsocket (3LIB),
.BR accept (3SOCKET),
.BR bind (3SOCKET),
.BR connect (3SOCKET),
.BR getpeername (3SOCKET),
.BR getsockname (3SOCKET),
.BR getsockopt (3SOCKET),
.BR listen (3SOCKET),
.BR recv (3SOCKET),
.BR recvfrom (3SOCKET),
.BR recvmsg (3SOCKET),
.BR send (3SOCKET),
.BR sendmsg (3SOCKET),
.BR sendto (3SOCKET),
.BR setsockopt (3SOCKET),
.BR shutdown (3SOCKET),
.BR sockaddr (3SOCKET),
.BR socket (3SOCKET),
.BR socketpair (3SOCKET),
.BR accept (3XNET),
.BR bind (3XNET),
.BR connect (3XNET),
.BR getpeername (3XNET),
.BR getsockname (3XNET),
.BR getsockopt (3XNET),
.BR listen (3XNET),
.BR recv (3XNET),
.BR recvfrom (3XNET),
.BR recvmsg (3XNET),
.BR send (3XNET),
.BR sendmsg (3XNET),
.BR sendto (3XNET),
.BR setsockopt (3XNET),
.BR shutdown (3XNET),
.BR socket (3XNET),
.BR socketpair (3XNET),
.BR attributes (7),
.BR standards (7)