'\" te .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved. .\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. .\" 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 Sun OS 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] .TH socket.h 3HEAD "28 Jan 2009" "SunOS 5.11" "Headers" .SH NAME socket.h, socket \- Internet Protocol family .SH SYNOPSIS .LP .nf \fB#include \fR .fi .SH DESCRIPTION .sp .LP The \fB\fR header defines the unsigned integral type \fBsa_family_t\fR through \fBtypedef\fR. .sp .LP The \fB\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" .sp .LP The \fB\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\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\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 .mk .na \fB\fBSCM_RIGHTS\fR\fR .ad .RS 14n .rt Indicates that the data array contains the access rights to be sent or received. .RE .sp .ne 2 .mk .na \fB\fBSCM_UCRED\fR\fR .ad .RS 14n .rt 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 data formats generally use the same values for data passed back in \fBcmsghdr\fR as for \fBsetsockopt()\fR to enable the feature. The IPv4 data formats are listed below with the associated payload for each. .sp .ne 2 .mk .na \fB\fBIPPROTO_IP\fR\fR .ad .br .na \fB\fBIP_RECVDSTADDR\fR\fR .ad .sp .6 .RS 4n \fBipaddr_t\fR, IP address .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IP\fR\fR .ad .br .na \fB\fBIP_RECVOPTS\fR\fR .ad .sp .6 .RS 4n variable-length IP options, up to 40 bytes .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IP\fR\fR .ad .br .na \fB\fBIP_RECVIF\fR\fR .ad .sp .6 .RS 4n \fBuint_t\fR, \fBifIndex\fR number .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IP\fR\fR .ad .br .na \fB\fBIP_RECVSLLA\fR\fR .ad .sp .6 .RS 4n \fBstruct sockaddr_dl\fR, link layer address .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IP\fR\fR .ad .br .na \fB\fBIP_RECVTTL\fR\fR .ad .sp .6 .RS 4n \fBuint8_t\fR .RE .sp .ne 2 .mk .na \fB\fBSOL_SOCKET\fR\fR .ad .br .na \fB\fBSO_RECVUCRED\fR\fR .ad .sp .6 .RS 4n \fBucred_t\fR \(em \fBcmsghdr.cmsg_type\fR is \fBSCM_UCRED\fR, not \fBSO_RECVUCRED\fR .RE .sp .LP The IPv6 data formats use different values for enabling the option and for passing the value back to the application. The IPv6 data formats are listed below with the associated payload for each. .sp .ne 2 .mk .na \fB\fBIPPROTO_IPV6\fR\fR .ad .br .na \fB\fBIPV6_RECVPKTINFO\fR\fR .ad .sp .6 .RS 4n \fBin_pktinfo\fR, \fBcmsg_type\fR \fBIPV6_PKTINFO\fR .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IPV6\fR\fR .ad .br .na \fB\fBIPV6_RECVTCLASS\fR\fR .ad .sp .6 .RS 4n \fBuint_t\fR, \fBcmsg_type\fR \fBIPV6_TCLASS\fR .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IPV6\fR\fR .ad .br .na \fB\fBIPV6_RECVPATHMTU\fR\fR .ad .sp .6 .RS 4n \fBip6_mtuinfo\fR, \fBcmsg_type\fR \fBIPV6_PATHMTU\fR .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IPV6\fR\fR .ad .br .na \fB\fBIPV6_RECVHOPLIMIT\fR\fR .ad .sp .6 .RS 4n \fBuint_t\fR, \fBcmsg_type\fR \fBIPV6_HOPLIMIT\fR .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IPV6\fR\fR .ad .br .na \fB\fBIPV6_RECVHOPOPTS\fR\fR .ad .sp .6 .RS 4n variable-length IPv6 options, \fBcmsg_type\fR \fBIPV6_HOPOPTS\fR .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IPV6\fR\fR .ad .br .na \fB\fBIPV6_RECVDSTOPTS\fR\fR .ad .sp .6 .RS 4n variable-length IPv6 options, \fBcmsg_type\fR \fBIPV6_DSTOPTS\fR .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IPV6\fR\fR .ad .br .na \fB\fBIPV6_RECVRTHDR\fR\fR .ad .sp .6 .RS 4n variable-length IPv6 options, \fBcmsg_type\fR \fBIPV6_RTHDR\fR .RE .sp .ne 2 .mk .na \fB\fBIPPROTO_IPV6\fR\fR .ad .br .na \fB\fBIPV6_RECVRTHDRDSTOPTS\fR\fR .ad .sp .6 .RS 4n variable-length IPv6 options, \fBcmsg_type\fR \fBIPV6_DSTOPTS\fR .RE .sp .LP The \fB\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 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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\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\fR header defines the following macros: .sp .ne 2 .mk .na \fB\fBSOCK_DGRAM\fR\fR .ad .RS 18n .rt Datagram socket .RE .sp .ne 2 .mk .na \fB\fBSOCK_STREAM\fR\fR .ad .RS 18n .rt Byte-stream socket .RE .sp .ne 2 .mk .na \fB\fBSOCK_SEQPACKET\fR\fR .ad .RS 18n .rt Sequenced-packet socket .RE .sp .LP The \fB\fR header defines the following macros for use as the \fIlevel\fR argument of \fBsetsockopt()\fR and \fBgetsockopt()\fR. .sp .ne 2 .mk .na \fB\fBSOL_SOCKET\fR\fR .ad .RS 14n .rt Options to be accessed at the socket level, not the protocol level. .RE .sp .ne 2 .mk .na \fB\fBSOL_ROUTE\fR\fR .ad .RS 14n .rt Options to be accessed at the routing socket level, not the protocol level. .RE .sp .LP The \fB\fR header defines the following macros for use as the \fIoption_name\fR argument of \fBgetsockopt()\fR or \fBsetsockopt()\fR calls: .sp .ne 2 .mk .na \fB\fBSO_DEBUG\fR\fR .ad .RS 17n .rt Debugging information is being recorded. .RE .sp .ne 2 .mk .na \fB\fBSO_ACCEPTCONN\fR\fR .ad .RS 17n .rt Socket is accepting connections. .RE .sp .ne 2 .mk .na \fB\fBSO_BROADCAST\fR\fR .ad .RS 17n .rt Transmission of broadcast messages is supported. .RE .sp .ne 2 .mk .na \fB\fBSO_REUSEADDR\fR\fR .ad .RS 17n .rt Reuse of local addresses is supported. .RE .sp .ne 2 .mk .na \fB\fBSO_KEEPALIVE\fR\fR .ad .RS 17n .rt Connections are kept alive with periodic messages. .RE .sp .ne 2 .mk .na \fB\fBSO_LINGER\fR\fR .ad .RS 17n .rt Socket lingers on close. .RE .sp .ne 2 .mk .na \fB\fBSO_OOBINLINE\fR\fR .ad .RS 17n .rt Out-of-band data is transmitted in line. .RE .sp .ne 2 .mk .na \fB\fBSO_SNDBUF\fR\fR .ad .RS 17n .rt Send buffer size. .RE .sp .ne 2 .mk .na \fB\fBSO_RCVBUF\fR\fR .ad .RS 17n .rt Receive buffer size. .RE .sp .ne 2 .mk .na \fB\fBSO_ERROR\fR\fR .ad .RS 17n .rt Socket error status. .RE .sp .ne 2 .mk .na \fB\fBSO_TYPE\fR\fR .ad .RS 17n .rt Socket type. .RE .sp .ne 2 .mk .na \fB\fBSO_RECVUCRED\fR\fR .ad .RS 17n .rt Request the reception of user credential ancillary data. This is a Sun-specific, Evolving interface. See \fBucred_get\fR(3C). .RE .sp .ne 2 .mk .na \fB\fBSO_MAC_EXEMPT\fR\fR .ad .RS 17n .rt 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 .mk .na \fB\fBSO_ALLZONES\fR\fR .ad .RS 17n .rt Bypass zone boundaries (privileged). .RE .sp .LP The \fB\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 .mk .na \fB\fBMSG_CTRUNC\fR\fR .ad .RS 15n .rt Control data truncated. .RE .sp .ne 2 .mk .na \fB\fBMSG_EOR\fR\fR .ad .RS 15n .rt Terminates a record (if supported by the protocol). .RE .sp .ne 2 .mk .na \fB\fBMSG_OOB\fR\fR .ad .RS 15n .rt Out-of-band data. .RE .sp .ne 2 .mk .na \fB\fBMSG_PEEK\fR\fR .ad .RS 15n .rt Leave received data in queue. .RE .sp .ne 2 .mk .na \fB\fBMSG_TRUNC\fR\fR .ad .RS 15n .rt Normal data truncated. .RE .sp .ne 2 .mk .na \fB\fBMSG_WAITALL\fR\fR .ad .RS 15n .rt Wait for complete message. .RE .sp .LP The \fB\fR header defines the following macros: .sp .ne 2 .mk .na \fB\fBAF_UNIX\fR\fR .ad .RS 11n .rt UNIX domain sockets .RE .sp .ne 2 .mk .na \fB\fBAF_INET\fR\fR .ad .RS 11n .rt Internet domain sockets .RE .sp .LP The \fB\fR header defines the following macros: .sp .ne 2 .mk .na \fB\fBSHUT_RD\fR\fR .ad .RS 13n .rt Disables further receive operations. .RE .sp .ne 2 .mk .na \fB\fBSHUT_WR\fR\fR .ad .RS 13n .rt Disables further send operations. .RE .sp .ne 2 .mk .na \fB\fBSHUT_RDWR\fR\fR .ad .RS 13n .rt Disables further send and receive operations. .RE .SS "\fBlibsocket\fR Interfaces" .sp .LP The \fB\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 .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityStandard .TE .SH SEE ALSO .sp .LP \fBaccept\fR(3SOCKET), \fBaccept\fR(3XNET), \fBbind\fR(3SOCKET), \fBbind\fR(3XNET), \fBconnect\fR(3SOCKET), \fBconnect\fR(3XNET), \fBgetpeername\fR(3SOCKET), \fBgetpeername\fR(3XNET), \fBgetpeerucred\fR(3C), \fBgetsockname\fR(3SOCKET), \fBgetsockname\fR(3XNET), \fBgetsockopt\fR(3SOCKET), \fBgetsockopt\fR(3XNET), \fBlibsocket\fR(3LIB), \fBlisten\fR(3SOCKET), \fBlisten\fR(3XNET), \fBrecv\fR(3SOCKET), \fBrecv\fR(3XNET), \fBrecvfrom\fR(3SOCKET), \fBrecvfrom\fR(3XNET), \fBrecvmsg\fR(3SOCKET), \fBrecvmsg\fR(3XNET), \fBsend\fR(3SOCKET), \fBsend\fR(3XNET), \fBsendmsg\fR(3SOCKET), \fBsendmsg\fR(3XNET), \fBsendto\fR(3SOCKET), \fBsendto\fR(3XNET), \fBsetsockopt\fR(3SOCKET), \fBsetsockopt\fR(3XNET), \fBshutdown\fR(3SOCKET), \fBshutdown\fR(3XNET), \fBsocket\fR(3SOCKET), \fBsocket\fR(3XNET), \fBsocketpair\fR(3SOCKET), \fBsocketpair\fR(3XNET), \fBucred_get\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)