Print this page
13175 Add support for IP_RECVTOS
13182 CMSG_ macros should have man pages
Change-ID: I784aa36cfd3c17e3cccbf1fd329fa7e69b663ef9
@@ -1,12 +1,13 @@
'\" te
+.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2008 AT&T
.\" 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 IP 7P "Dec 3, 2008"
+.TH IP 7P "Sep 18, 2020"
.SH NAME
ip, IP \- Internet Protocol
.SH SYNOPSIS
.LP
.nf
@@ -77,11 +78,11 @@
.LP
The socket options supported at the IP level are:
.sp
.ne 2
.na
-\fB\fBIP_OPTIONS\fR\fR
+\fBIP_OPTIONS\fR
.ad
.RS 22n
IP options for outgoing datagrams. This socket option may be used to set IP
options to be included in each outgoing datagram. IP options to be sent are set
with \fBsetsockopt()\fR (see \fBgetsockopt\fR(3SOCKET)). The
@@ -97,52 +98,52 @@
.RE
.sp
.ne 2
.na
-\fB\fBIP_SEC_OPT\fR\fR
+\fBIP_SEC_OPT\fR
.ad
.RS 22n
Enable or obtain IPsec security settings for this socket. For more details on
the protection services of IPsec, see \fBipsec\fR(7P).
.RE
.sp
.ne 2
.na
-\fB\fBIP_ADD_MEMBERSHIP\fR\fR
+\fBIP_ADD_MEMBERSHIP\fR
.ad
.RS 22n
Join a multicast group.
.RE
.sp
.ne 2
.na
-\fB\fBIP_DROP_MEMBERSHIP\fR\fR
+\fBIP_DROP_MEMBERSHIP\fR
.ad
.RS 22n
Leave a multicast group.
.RE
.sp
.ne 2
.na
-\fB\fBIP_BOUND_IF\fR\fR
+\fBIP_BOUND_IF\fR
.ad
.RS 22n
Limit reception and transmission of packets to this interface. Takes an
integer as an argument. The integer is the selected interface index.
.RE
.sp
.LP
-The following options take \fBin_pktinfo_t\fR as the parameter:
+The following option takes \fBin_pktinfo_t\fR as the parameter:
.sp
.ne 2
.na
-\fB\fBIP_PKTINFO\fR\fR
+\fBIP_PKTINFO\fR
.ad
.sp .6
.RS 4n
Set the source address and/or transmit interface of the packet(s). Note that
the IP_BOUND_IF socket option takes precedence over the interface index passed
@@ -162,33 +163,105 @@
is used as the source address and ipi_ifindex is used as the interface index to
send the packet out.
.RE
.sp
+.LP
+The following options are boolean switches controlling the reception of
+ancillary data:
+
+.sp
.ne 2
.na
-\fB\fBIP_RECVPKTINFO\fR\fR
+\fBIP_RECVDSTADDR\fR
.ad
-.sp .6
-.RS 4n
+.RS 22n
+When enabled on a SOCK_DGRAM socket, enables receipt of the destination
+IP address of the incoming packet. Returns \fBinaddr_t\fR as ancillary
+data.
+.RE
+
+.sp
+.ne 2
+.na
+\fBIP_RECVIF\fR
+.ad
+.RS 22n
+Enable/disable receipt of the inbound interface index. Returns \fBuint_t\fR as
+ancillary data.
+.RE
+
+.sp
+.ne 2
+.na
+\fBIP_RECVOPTS\fR
+.ad
+.RS 22n
+When enabled on a SOCK_DGRAM socket, enables receipt of the IP options
+from the incoming packet. Returns variable-length IP options, up to 40
+bytes, as ancillary data.
+.RE
+
+.sp
+.ne 2
+.na
+\fBIP_RECVPKTINFO\fR
+.ad
+.RS 22n
Enable/disable receipt of the index of the interface the packet arrived on, the
local address that was matched for reception, and the inbound packet's actual
-destination address. Takes boolean as the parameter. Returns struct
-in_pktinfo_t as ancillary data.
+destination address. Takes boolean as the parameter. Returns
+\fBin_pktinfo_t\fR as ancillary data.
.RE
+.RE
.sp
+.ne 2
+.na
+\fBIP_RECVSLLA\fR
+.ad
+.RS 22n
+When enabled on a SOCK_DGRAM socket, enables receipt of the source link-layer
+address for the incoming packet. Returns \fBstruct sockaddr_dl\fR as
+ancillary data.
+.RE
+
+.sp
+.ne 2
+.na
+\fBIP_RECVTTL\fR
+.ad
+.RS 22n
+When enabled on a SOCK_DGRAM socket, the IP TTL (time to live) field for an
+incoming datagram is returned as \fBuint8_t\fR in ancillary data.
+.RE
+
+.sp
+.ne 2
+.na
+\fBIP_RECVTOS\fR
+.ad
+.RS 22n
+When enabled, the IP TOS (type of service) field is returned as \fBuint8_t\fR
+in ancillary data. For \fBSOCK_DGRAM\fR sockets, the ancillary data item is
+included for every call to \fBrecvmsg()\fR. For \fBSOCK_STREAM\fR sockets,
+where there is no direct mapping between received TCP segments and receive
+operations, the ancillary data item will only be present when the value has
+changed.
+.RE
+
+.sp
.LP
The following options take a \fBstruct ip_mreq\fR as the parameter. The
structure contains a multicast address which must be set to the \fBCLASS-D\fR
\fBIP\fR multicast address and an interface address. Normally the interface
address is set to \fBINADDR_ANY\fR which causes the kernel to choose the
interface on which to join.
.sp
.ne 2
.na
-\fB\fBIP_BLOCK_SOURCE\fR\fR
+\fBIP_BLOCK_SOURCE\fR
.ad
.RS 29n
Block multicast packets whose source address matches the given source address.
The specified group must be joined previously using IP_ADD_MEMBERSHIP or
MCAST_JOIN_GROUP.
@@ -195,31 +268,31 @@
.RE
.sp
.ne 2
.na
-\fB\fBIP_UNBLOCK_SOURCE\fR\fR
+\fBIP_UNBLOCK_SOURCE\fR
.ad
.RS 29n
Unblock (begin receiving) multicast packets which were previously blocked using
IP_BLOCK_SOURCE.
.RE
.sp
.ne 2
.na
-\fB\fBIP_ADD_SOURCE_MEMBERSHIP\fR\fR
+\fBIP_ADD_SOURCE_MEMBERSHIP\fR
.ad
.RS 29n
Begin receiving packets for the given multicast group whose source address
matches the specified address.
.RE
.sp
.ne 2
.na
-\fB\fBIP_DROP_SOURCE_MEMBERSHIP\fR\fR
+\fBIP_DROP_SOURCE_MEMBERSHIP\fR
.ad
.RS 29n
Stop receiving packets for the given multicast group whose source address
matches the specified address.
.RE
@@ -230,20 +303,20 @@
structure contains a multicast address (which must be set to the CLASS-D IP
multicast address), an interface address, and a source address.
.sp
.ne 2
.na
-\fB\fBMCAST_JOIN_GROUP\fR\fR
+\fBMCAST_JOIN_GROUP\fR
.ad
.RS 28n
Join a multicast group. Functionally equivalent to IP_ADD_MEMBERSHIP.
.RE
.sp
.ne 2
.na
-\fB\fBMCAST_BLOCK_SOURCE\fR\fR
+\fBMCAST_BLOCK_SOURCE\fR
.ad
.RS 28n
Block multicast packets whose source address matches the given source address.
The specified group must be joined previously using IP_ADD_MEMBERSHIP or
MCAST_JOIN_GROUP.
@@ -250,40 +323,40 @@
.RE
.sp
.ne 2
.na
-\fB\fBMCAST_UNBLOCK_SOURCE\fR\fR
+\fBMCAST_UNBLOCK_SOURCE\fR
.ad
.RS 28n
Unblock (begin receiving) multicast packets which were previously blocked using
MCAST_BLOCK_SOURCE.
.RE
.sp
.ne 2
.na
-\fB\fBMCAST_LEAVE_GROUP\fR\fR
+\fBMCAST_LEAVE_GROUP\fR
.ad
.RS 28n
Leave a multicast group. Functionally equivalent to IP_DROP_MEMBERSHIP.
.RE
.sp
.ne 2
.na
-\fB\fBMCAST_JOIN_SOURCE_GROUP\fR\fR
+\fBMCAST_JOIN_SOURCE_GROUP\fR
.ad
.RS 28n
Begin receiving packets for the given multicast group whose source address
matches the specified address.
.RE
.sp
.ne 2
.na
-\fB\fBMCAST_LEAVE_SOURCE_GROUP\fR\fR
+\fBMCAST_LEAVE_SOURCE_GROUP\fR
.ad
.RS 28n
Stop receiving packets for the given multicast group whose source address
matches the specified address.
.RE
@@ -297,11 +370,11 @@
those options which include a source address. It contains an interface index,
multicast address, and source address.
.sp
.ne 2
.na
-\fB\fBIP_MULTICAST_IF\fR\fR
+\fBIP_MULTICAST_IF\fR
.ad
.RS 21n
The outgoing interface for multicast packets. This option takes a \fBstruct\fR
\fBin_addr\fR as an argument, and it selects that interface for outgoing IP
multicast packets. If the address specified is \fBINADDR_ANY\fR, it uses the
@@ -310,11 +383,11 @@
.RE
.sp
.ne 2
.na
-\fB\fBIP_MULTICAST_TTL\fR\fR
+\fBIP_MULTICAST_TTL\fR
.ad
.RS 21n
Time to live for multicast datagrams. This option takes an unsigned character
as an argument. Its value is the TTL that IP uses on outgoing multicast
datagrams. The default is \fB1\fR.
@@ -321,11 +394,11 @@
.RE
.sp
.ne 2
.na
-\fB\fBIP_MULTICAST_LOOP\fR\fR
+\fBIP_MULTICAST_LOOP\fR
.ad
.RS 21n
Loopback for multicast datagrams. Normally multicast datagrams are delivered
to members on the sending host (or sending zone). Setting the unsigned
character argument to 0 causes the opposite behavior, meaning that when
@@ -334,31 +407,22 @@
.RE
.sp
.ne 2
.na
-\fB\fBIP_RECVIF\fR\fR
+\fBIP_TOS\fR
.ad
.RS 21n
-Receive the inbound interface index.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBIP_TOS\fR\fR
-.ad
-.RS 21n
This option takes an integer argument as its input value. The least significant
8 bits of the value are used to set the Type Of Service field in the IP header
of the outgoing packets.
.RE
.sp
.ne 2
.na
-\fB\fBIP_NEXTHOP\fR\fR
+\fBIP_NEXTHOP\fR
.ad
.RS 21n
This option specifies the address of the onlink nexthop for traffic originating
from that socket. It causes the routing table to be bypassed and outgoing
traffic is sent directly to the specified nexthop. This option takes an
@@ -638,15 +702,16 @@
.SH SEE ALSO
.sp
.LP
\fBifconfig\fR(1M), \fBrouteadm\fR(1M), \fBndd\fR(1M), \fBread\fR(2),
-\fBwrite\fR(2), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET),
-\fBgetsockopt\fR(3SOCKET), \fBrecv\fR(3SOCKET), \fBsend\fR(3SOCKET),
-\fBdefaultrouter\fR(4), \fBicmp\fR(7P), \fBif_tcp\fR(7P), \fBinet\fR(7P),
-\fBip6\fR(7P), \fBipsec\fR(7P), \fBrouting\fR(7P), \fBtcp\fR(7P),
-\fBudp\fR(7P), \fBnet_hook_register\fR(9F), \fBhook_pkt_event\fR(9S)
+\fBwrite\fR(2), \fBsocket.h\fR(3HEAD), \fBbind\fR(3SOCKET),
+\fBconnect\fR(3SOCKET), \fBgetsockopt\fR(3SOCKET), \fBrecv\fR(3SOCKET),
+\fBsend\fR(3SOCKET), \fBdefaultrouter\fR(4), \fBicmp\fR(7P), \fBif_tcp\fR(7P),
+\fBinet\fR(7P), \fBip\fR(7P), \fBip6\fR(7P), \fBipsec\fR(7P),
+\fBrouting\fR(7P), \fBtcp\fR(7P), \fBudp\fR(7P), \fBnet_hook_register\fR(9F),
+\fBhook_pkt_event\fR(9S)
.sp
.LP
Braden, R., \fIRFC 1122, Requirements for Internet Hosts \(mi Communication
Layers\fR, Information Sciences Institute, University of Southern California,
October 1989.
@@ -660,11 +725,11 @@
.LP
A socket operation may fail with one of the following errors returned:
.sp
.ne 2
.na
-\fB\fBEACCES\fR\fR
+\fBEACCES\fR
.ad
.RS 17n
A \fBbind()\fR operation was attempted with a "reserved" port number and the
effective user ID of the process was not the privileged user.
.sp
@@ -673,50 +738,50 @@
.RE
.sp
.ne 2
.na
-\fB\fBEADDRINUSE\fR\fR
+\fBEADDRINUSE\fR
.ad
.RS 17n
A \fBbind()\fR operation was attempted on a socket with a network address/port
pair that has already been bound to another socket.
.RE
.sp
.ne 2
.na
-\fB\fBEADDRNOTAVAIL\fR\fR
+\fBEADDRNOTAVAIL\fR
.ad
.RS 17n
A \fBbind()\fR operation was attempted for an address that is not configured on
this machine.
.RE
.sp
.ne 2
.na
-\fB\fBEINVAL\fR\fR
+\fBEINVAL\fR
.ad
.RS 17n
A \fBsendmsg()\fR operation with a non-NULL \fBmsg_accrights\fR was attempted.
.RE
.sp
.ne 2
.na
-\fB\fBEINVAL\fR\fR
+\fBEINVAL\fR
.ad
.RS 17n
A \fBgetsockopt()\fR or \fBsetsockopt()\fR operation with an unknown socket
option name was given.
.RE
.sp
.ne 2
.na
-\fB\fBEINVAL\fR\fR
+\fBEINVAL\fR
.ad
.RS 17n
A \fBgetsockopt()\fR or \fBsetsockopt()\fR operation was attempted with the
\fBIP\fR option field improperly formed; an option field was shorter than the
minimum value or longer than the option buffer provided.
@@ -723,11 +788,11 @@
.RE
.sp
.ne 2
.na
-\fB\fBEISCONN\fR\fR
+\fBEISCONN\fR
.ad
.RS 17n
A \fBconnect()\fR operation was attempted on a socket on which a
\fBconnect()\fR operation had already been performed, and the socket could not
be successfully disconnected before making the new connection.
@@ -734,11 +799,11 @@
.RE
.sp
.ne 2
.na
-\fB\fBEISCONN\fR\fR
+\fBEISCONN\fR
.ad
.RS 17n
A \fBsendto()\fR or \fBsendmsg()\fR operation specifying an address to which
the message should be sent was attempted on a socket on which a \fBconnect()\fR
operation had already been performed.
@@ -745,11 +810,11 @@
.RE
.sp
.ne 2
.na
-\fB\fBEMSGSIZE\fR\fR
+\fBEMSGSIZE\fR
.ad
.RS 17n
A \fBsend()\fR, \fBsendto()\fR, or \fBsendmsg()\fR operation was attempted to
send a datagram that was too large for an interface, but was not allowed to be
fragmented (such as broadcasts).
@@ -756,11 +821,11 @@
.RE
.sp
.ne 2
.na
-\fB\fBENETUNREACH\fR\fR
+\fBENETUNREACH\fR
.ad
.RS 17n
An attempt was made to establish a connection by means of \fBconnect()\fR, or
to send a datagram by means of \fBsendto()\fR or \fBsendmsg()\fR, where there
was no matching entry in the routing table; or if an ICMP "destination
@@ -768,11 +833,11 @@
.RE
.sp
.ne 2
.na
-\fB\fBENOTCONN\fR\fR
+\fBENOTCONN\fR
.ad
.RS 17n
A \fBsend()\fR or \fBwrite()\fR operation, or a \fBsendto()\fR or
\fBsendmsg()\fR operation not specifying an address to which the message should
be sent, was attempted on a socket on which a \fBconnect()\fR operation had not
@@ -780,39 +845,39 @@
.RE
.sp
.ne 2
.na
-\fB\fBENOBUFS\fR\fR
+\fBENOBUFS\fR
.ad
.RS 17n
The system ran out of memory for fragmentation buffers or other internal data
structures.
.RE
.sp
.ne 2
.na
-\fB\fBENOBUFS\fR\fR
+\fBENOBUFS\fR
.ad
.RS 17n
\fBSO_SNDBUF\fR or \fBSO_RCVBUF\fR exceeds a system limit.
.RE
.sp
.ne 2
.na
-\fB\fBEINVAL\fR\fR
+\fBEINVAL\fR
.ad
.RS 17n
Invalid length for \fBIP_OPTIONS\fR.
.RE
.sp
.ne 2
.na
-\fB\fBEHOSTUNREACH\fR\fR
+\fBEHOSTUNREACH\fR
.ad
.RS 17n
Invalid address for \fBIP_MULTICAST_IF\fR.
.sp
Invalid (offlink) nexthop address for IP_NEXTHOP.
@@ -819,57 +884,57 @@
.RE
.sp
.ne 2
.na
-\fB\fBEINVAL\fR\fR
+\fBEINVAL\fR
.ad
.RS 17n
Not a multicast address for \fBIP_ADD_MEMBERSHIP\fR and
\fBIP_DROP_MEMBERSHIP\fR.
.RE
.sp
.ne 2
.na
-\fB\fBEADDRNOTAVAIL\fR\fR
+\fBEADDRNOTAVAIL\fR
.ad
.RS 17n
Bad interface address for \fBIP_ADD_MEMBERSHIP\fR and \fBIP_DROP_MEMBERSHIP\fR.
.RE
.sp
.ne 2
.na
-\fB\fBEADDRINUSE\fR\fR
+\fBEADDRINUSE\fR
.ad
.RS 17n
Address already joined for \fBIP_ADD_MEMBERSHIP\fR.
.RE
.sp
.ne 2
.na
-\fB\fBENOENT\fR\fR
+\fBENOENT\fR
.ad
.RS 17n
Address not joined for \fBIP_DROP_MEMBERSHIP\fR.
.RE
.sp
.ne 2
.na
-\fB\fBENOPROTOOPT\fR\fR
+\fBENOPROTOOPT\fR
.ad
.RS 17n
Invalid socket type.
.RE
.sp
.ne 2
.na
-\fB\fBEPERM\fR\fR
+\fBEPERM\fR
.ad
.RS 17n
No permissions.
.RE