1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 2008 AT&T
4 .\" 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.
5 .\" 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.
6 .\" 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]
7 .TH IP 7P "Dec 3, 2008"
8 .SH NAME
9 ip, IP \- Internet Protocol
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fB#include <sys/socket.h>\fR
14 .fi
15
16 .LP
17 .nf
18 \fB#include <netinet/in.h>\fR
19 .fi
20
21 .LP
22 .nf
23 \fBs = socket(AF_INET, SOCK_RAW, proto);\fR
24 .fi
25
26 .LP
27 .nf
62 the IP header and options intact.
63 .sp
64 .LP
65 If an application uses \fBIP_HDRINCL\fR and provides the IP header contents,
66 the IP stack does not modify the following supplied fields under any
67 conditions: Type of Service, DF Flag, Protocol, and Destination Address. The IP
68 Options and IHL fields are set by use of \fBIP_OPTIONS\fR, and \fBTotal
69 Length\fR is updated to include any options. Version is set to the default.
70 Identification is chosen by the normal IP ID selection logic. The source
71 address is updated if none was specified and the TTL is changed if the packet
72 has a broadcast destination address. Since an applicaton cannot send down
73 fragments (as IP assigns the IP ID), Fragment Offset is always 0. The IP
74 Checksum field is computed by IP. None of the data beyond the IP header are
75 changed, including the application-provided transport header.
76 .sp
77 .LP
78 The socket options supported at the IP level are:
79 .sp
80 .ne 2
81 .na
82 \fB\fBIP_OPTIONS\fR\fR
83 .ad
84 .RS 22n
85 IP options for outgoing datagrams. This socket option may be used to set IP
86 options to be included in each outgoing datagram. IP options to be sent are set
87 with \fBsetsockopt()\fR (see \fBgetsockopt\fR(3SOCKET)). The
88 \fBgetsockopt\fR(3SOCKET) call returns the IP options set in the last
89 \fBsetsockopt()\fR call. IP options on received datagrams are visible to user
90 programs only using raw IP sockets. The format of IP options given in
91 \fBsetsockopt()\fR matches those defined in the IP specification with one
92 exception: the list of addresses for the source routing options must include
93 the first-hop gateway at the beginning of the list of gateways. The first-hop
94 gateway address will be extracted from the option list and the size adjusted
95 accordingly before use. IP options may be used with any socket type in the
96 Internet family.
97 .RE
98
99 .sp
100 .ne 2
101 .na
102 \fB\fBIP_SEC_OPT\fR\fR
103 .ad
104 .RS 22n
105 Enable or obtain IPsec security settings for this socket. For more details on
106 the protection services of IPsec, see \fBipsec\fR(7P).
107 .RE
108
109 .sp
110 .ne 2
111 .na
112 \fB\fBIP_ADD_MEMBERSHIP\fR\fR
113 .ad
114 .RS 22n
115 Join a multicast group.
116 .RE
117
118 .sp
119 .ne 2
120 .na
121 \fB\fBIP_DROP_MEMBERSHIP\fR\fR
122 .ad
123 .RS 22n
124 Leave a multicast group.
125 .RE
126
127 .sp
128 .ne 2
129 .na
130 \fB\fBIP_BOUND_IF\fR\fR
131 .ad
132 .RS 22n
133 Limit reception and transmission of packets to this interface. Takes an
134 integer as an argument. The integer is the selected interface index.
135 .RE
136
137 .sp
138 .LP
139 The following options take \fBin_pktinfo_t\fR as the parameter:
140 .sp
141 .ne 2
142 .na
143 \fB\fBIP_PKTINFO\fR\fR
144 .ad
145 .sp .6
146 .RS 4n
147 Set the source address and/or transmit interface of the packet(s). Note that
148 the IP_BOUND_IF socket option takes precedence over the interface index passed
149 in IP_PKTINFO.
150 .sp
151 .in +2
152 .nf
153 struct in_pktinfo {
154 unsigned int ipi_ifindex;/* send/recv interface index */
155 struct in_addr ipi_spec_dst;/* matched source addr. */
156 struct in_addr ipi_addr;/* src/dst addr. in IP hdr */
157 } in_pktinfo_t;
158 .fi
159 .in -2
160
161 When passed in (on transmit) via ancillary data with IP_PKTINFO, ipi_spec_dst
162 is used as the source address and ipi_ifindex is used as the interface index to
163 send the packet out.
164 .RE
165
166 .sp
167 .ne 2
168 .na
169 \fB\fBIP_RECVPKTINFO\fR\fR
170 .ad
171 .sp .6
172 .RS 4n
173 Enable/disable receipt of the index of the interface the packet arrived on, the
174 local address that was matched for reception, and the inbound packet's actual
175 destination address. Takes boolean as the parameter. Returns struct
176 in_pktinfo_t as ancillary data.
177 .RE
178
179 .sp
180 .LP
181 The following options take a \fBstruct ip_mreq\fR as the parameter. The
182 structure contains a multicast address which must be set to the \fBCLASS-D\fR
183 \fBIP\fR multicast address and an interface address. Normally the interface
184 address is set to \fBINADDR_ANY\fR which causes the kernel to choose the
185 interface on which to join.
186 .sp
187 .ne 2
188 .na
189 \fB\fBIP_BLOCK_SOURCE\fR\fR
190 .ad
191 .RS 29n
192 Block multicast packets whose source address matches the given source address.
193 The specified group must be joined previously using IP_ADD_MEMBERSHIP or
194 MCAST_JOIN_GROUP.
195 .RE
196
197 .sp
198 .ne 2
199 .na
200 \fB\fBIP_UNBLOCK_SOURCE\fR\fR
201 .ad
202 .RS 29n
203 Unblock (begin receiving) multicast packets which were previously blocked using
204 IP_BLOCK_SOURCE.
205 .RE
206
207 .sp
208 .ne 2
209 .na
210 \fB\fBIP_ADD_SOURCE_MEMBERSHIP\fR\fR
211 .ad
212 .RS 29n
213 Begin receiving packets for the given multicast group whose source address
214 matches the specified address.
215 .RE
216
217 .sp
218 .ne 2
219 .na
220 \fB\fBIP_DROP_SOURCE_MEMBERSHIP\fR\fR
221 .ad
222 .RS 29n
223 Stop receiving packets for the given multicast group whose source address
224 matches the specified address.
225 .RE
226
227 .sp
228 .LP
229 The following options take a \fBstruct ip_mreq_source\fR as the parameter. The
230 structure contains a multicast address (which must be set to the CLASS-D IP
231 multicast address), an interface address, and a source address.
232 .sp
233 .ne 2
234 .na
235 \fB\fBMCAST_JOIN_GROUP\fR\fR
236 .ad
237 .RS 28n
238 Join a multicast group. Functionally equivalent to IP_ADD_MEMBERSHIP.
239 .RE
240
241 .sp
242 .ne 2
243 .na
244 \fB\fBMCAST_BLOCK_SOURCE\fR\fR
245 .ad
246 .RS 28n
247 Block multicast packets whose source address matches the given source address.
248 The specified group must be joined previously using IP_ADD_MEMBERSHIP or
249 MCAST_JOIN_GROUP.
250 .RE
251
252 .sp
253 .ne 2
254 .na
255 \fB\fBMCAST_UNBLOCK_SOURCE\fR\fR
256 .ad
257 .RS 28n
258 Unblock (begin receiving) multicast packets which were previously blocked using
259 MCAST_BLOCK_SOURCE.
260 .RE
261
262 .sp
263 .ne 2
264 .na
265 \fB\fBMCAST_LEAVE_GROUP\fR\fR
266 .ad
267 .RS 28n
268 Leave a multicast group. Functionally equivalent to IP_DROP_MEMBERSHIP.
269 .RE
270
271 .sp
272 .ne 2
273 .na
274 \fB\fBMCAST_JOIN_SOURCE_GROUP\fR\fR
275 .ad
276 .RS 28n
277 Begin receiving packets for the given multicast group whose source address
278 matches the specified address.
279 .RE
280
281 .sp
282 .ne 2
283 .na
284 \fB\fBMCAST_LEAVE_SOURCE_GROUP\fR\fR
285 .ad
286 .RS 28n
287 Stop receiving packets for the given multicast group whose source address
288 matches the specified address.
289 .RE
290
291 .sp
292 .LP
293 The following options take a struct \fBgroup_req\fR or struct
294 \fBgroup_source_req\fR as the parameter. The `\fBgroup_req\fR structure
295 contains an interface index and a multicast address which must be set to the
296 CLASS-D multicast address. The \fBgroup_source_req\fR structure is used for
297 those options which include a source address. It contains an interface index,
298 multicast address, and source address.
299 .sp
300 .ne 2
301 .na
302 \fB\fBIP_MULTICAST_IF\fR\fR
303 .ad
304 .RS 21n
305 The outgoing interface for multicast packets. This option takes a \fBstruct\fR
306 \fBin_addr\fR as an argument, and it selects that interface for outgoing IP
307 multicast packets. If the address specified is \fBINADDR_ANY\fR, it uses the
308 unicast routing table to select the outgoing interface (which is the default
309 behavior).
310 .RE
311
312 .sp
313 .ne 2
314 .na
315 \fB\fBIP_MULTICAST_TTL\fR\fR
316 .ad
317 .RS 21n
318 Time to live for multicast datagrams. This option takes an unsigned character
319 as an argument. Its value is the TTL that IP uses on outgoing multicast
320 datagrams. The default is \fB1\fR.
321 .RE
322
323 .sp
324 .ne 2
325 .na
326 \fB\fBIP_MULTICAST_LOOP\fR\fR
327 .ad
328 .RS 21n
329 Loopback for multicast datagrams. Normally multicast datagrams are delivered
330 to members on the sending host (or sending zone). Setting the unsigned
331 character argument to 0 causes the opposite behavior, meaning that when
332 multiple zones are present, the datagrams are delivered to all zones except the
333 sending zone.
334 .RE
335
336 .sp
337 .ne 2
338 .na
339 \fB\fBIP_RECVIF\fR\fR
340 .ad
341 .RS 21n
342 Receive the inbound interface index.
343 .RE
344
345 .sp
346 .ne 2
347 .na
348 \fB\fBIP_TOS\fR\fR
349 .ad
350 .RS 21n
351 This option takes an integer argument as its input value. The least significant
352 8 bits of the value are used to set the Type Of Service field in the IP header
353 of the outgoing packets.
354 .RE
355
356 .sp
357 .ne 2
358 .na
359 \fB\fBIP_NEXTHOP\fR\fR
360 .ad
361 .RS 21n
362 This option specifies the address of the onlink nexthop for traffic originating
363 from that socket. It causes the routing table to be bypassed and outgoing
364 traffic is sent directly to the specified nexthop. This option takes an
365 ipaddr_t argument representing the IPv4 address of the nexthop as the input
366 value. The IP_NEXTHOP option takes precedence over IPOPT_LSRR. IP_BOUND_IF and
367 SO_DONTROUTE take precedence over IP_NEXTHOP. This option has no meaning for
368 broadcast and multicast packets. The application must ensure that the specified
369 nexthop is alive. An application may want to specify the IP_NEXTHOP option on a
370 TCP listener socket only for incoming requests to a particular IP address. In
371 this case, it must avoid binding the socket to INADDR_ANY and instead must bind
372 the listener socket to the specific IP address. In addition, typically the
373 application may want the incoming and outgoing interface to be the same. In
374 this case, the application must select a suitable nexthop that is onlink and
375 reachable via the desired interface and do a setsockopt (IP_NEXTHOP) on it.
376 Then it must bind to the IP address of the desired interface. Setting the
377 IP_NEXTHOP option requires the PRIV_SYS_NET_CONFIG privilege.
378 .RE
379
623 .na
624 \fBdown\fR
625 .ad
626 .RS 18n
627 There are no logical interfaces expecting to receive packets.
628 .RE
629
630 .sp
631 .ne 2
632 .na
633 \fBaddress change\fR
634 .ad
635 .RS 18n
636 An address has changed on a logical interface.
637 .RE
638
639 .SH SEE ALSO
640 .sp
641 .LP
642 \fBifconfig\fR(1M), \fBrouteadm\fR(1M), \fBndd\fR(1M), \fBread\fR(2),
643 \fBwrite\fR(2), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET),
644 \fBgetsockopt\fR(3SOCKET), \fBrecv\fR(3SOCKET), \fBsend\fR(3SOCKET),
645 \fBdefaultrouter\fR(4), \fBicmp\fR(7P), \fBif_tcp\fR(7P), \fBinet\fR(7P),
646 \fBip6\fR(7P), \fBipsec\fR(7P), \fBrouting\fR(7P), \fBtcp\fR(7P),
647 \fBudp\fR(7P), \fBnet_hook_register\fR(9F), \fBhook_pkt_event\fR(9S)
648 .sp
649 .LP
650 Braden, R., \fIRFC 1122, Requirements for Internet Hosts \(mi Communication
651 Layers\fR, Information Sciences Institute, University of Southern California,
652 October 1989.
653 .sp
654 .LP
655 Postel, J., \fIRFC 791, Internet Protocol \(mi DARPA Internet Program Protocol
656 Specification\fR, Information Sciences Institute, University of Southern
657 California, September 1981.
658 .SH DIAGNOSTICS
659 .sp
660 .LP
661 A socket operation may fail with one of the following errors returned:
662 .sp
663 .ne 2
664 .na
665 \fB\fBEACCES\fR\fR
666 .ad
667 .RS 17n
668 A \fBbind()\fR operation was attempted with a "reserved" port number and the
669 effective user ID of the process was not the privileged user.
670 .sp
671 Setting the IP_NEXTHOP was attempted by a process lacking the
672 PRIV_SYS_NET_CONFIG privilege.
673 .RE
674
675 .sp
676 .ne 2
677 .na
678 \fB\fBEADDRINUSE\fR\fR
679 .ad
680 .RS 17n
681 A \fBbind()\fR operation was attempted on a socket with a network address/port
682 pair that has already been bound to another socket.
683 .RE
684
685 .sp
686 .ne 2
687 .na
688 \fB\fBEADDRNOTAVAIL\fR\fR
689 .ad
690 .RS 17n
691 A \fBbind()\fR operation was attempted for an address that is not configured on
692 this machine.
693 .RE
694
695 .sp
696 .ne 2
697 .na
698 \fB\fBEINVAL\fR\fR
699 .ad
700 .RS 17n
701 A \fBsendmsg()\fR operation with a non-NULL \fBmsg_accrights\fR was attempted.
702 .RE
703
704 .sp
705 .ne 2
706 .na
707 \fB\fBEINVAL\fR\fR
708 .ad
709 .RS 17n
710 A \fBgetsockopt()\fR or \fBsetsockopt()\fR operation with an unknown socket
711 option name was given.
712 .RE
713
714 .sp
715 .ne 2
716 .na
717 \fB\fBEINVAL\fR\fR
718 .ad
719 .RS 17n
720 A \fBgetsockopt()\fR or \fBsetsockopt()\fR operation was attempted with the
721 \fBIP\fR option field improperly formed; an option field was shorter than the
722 minimum value or longer than the option buffer provided.
723 .RE
724
725 .sp
726 .ne 2
727 .na
728 \fB\fBEISCONN\fR\fR
729 .ad
730 .RS 17n
731 A \fBconnect()\fR operation was attempted on a socket on which a
732 \fBconnect()\fR operation had already been performed, and the socket could not
733 be successfully disconnected before making the new connection.
734 .RE
735
736 .sp
737 .ne 2
738 .na
739 \fB\fBEISCONN\fR\fR
740 .ad
741 .RS 17n
742 A \fBsendto()\fR or \fBsendmsg()\fR operation specifying an address to which
743 the message should be sent was attempted on a socket on which a \fBconnect()\fR
744 operation had already been performed.
745 .RE
746
747 .sp
748 .ne 2
749 .na
750 \fB\fBEMSGSIZE\fR\fR
751 .ad
752 .RS 17n
753 A \fBsend()\fR, \fBsendto()\fR, or \fBsendmsg()\fR operation was attempted to
754 send a datagram that was too large for an interface, but was not allowed to be
755 fragmented (such as broadcasts).
756 .RE
757
758 .sp
759 .ne 2
760 .na
761 \fB\fBENETUNREACH\fR\fR
762 .ad
763 .RS 17n
764 An attempt was made to establish a connection by means of \fBconnect()\fR, or
765 to send a datagram by means of \fBsendto()\fR or \fBsendmsg()\fR, where there
766 was no matching entry in the routing table; or if an ICMP "destination
767 unreachable" message was received.
768 .RE
769
770 .sp
771 .ne 2
772 .na
773 \fB\fBENOTCONN\fR\fR
774 .ad
775 .RS 17n
776 A \fBsend()\fR or \fBwrite()\fR operation, or a \fBsendto()\fR or
777 \fBsendmsg()\fR operation not specifying an address to which the message should
778 be sent, was attempted on a socket on which a \fBconnect()\fR operation had not
779 already been performed.
780 .RE
781
782 .sp
783 .ne 2
784 .na
785 \fB\fBENOBUFS\fR\fR
786 .ad
787 .RS 17n
788 The system ran out of memory for fragmentation buffers or other internal data
789 structures.
790 .RE
791
792 .sp
793 .ne 2
794 .na
795 \fB\fBENOBUFS\fR\fR
796 .ad
797 .RS 17n
798 \fBSO_SNDBUF\fR or \fBSO_RCVBUF\fR exceeds a system limit.
799 .RE
800
801 .sp
802 .ne 2
803 .na
804 \fB\fBEINVAL\fR\fR
805 .ad
806 .RS 17n
807 Invalid length for \fBIP_OPTIONS\fR.
808 .RE
809
810 .sp
811 .ne 2
812 .na
813 \fB\fBEHOSTUNREACH\fR\fR
814 .ad
815 .RS 17n
816 Invalid address for \fBIP_MULTICAST_IF\fR.
817 .sp
818 Invalid (offlink) nexthop address for IP_NEXTHOP.
819 .RE
820
821 .sp
822 .ne 2
823 .na
824 \fB\fBEINVAL\fR\fR
825 .ad
826 .RS 17n
827 Not a multicast address for \fBIP_ADD_MEMBERSHIP\fR and
828 \fBIP_DROP_MEMBERSHIP\fR.
829 .RE
830
831 .sp
832 .ne 2
833 .na
834 \fB\fBEADDRNOTAVAIL\fR\fR
835 .ad
836 .RS 17n
837 Bad interface address for \fBIP_ADD_MEMBERSHIP\fR and \fBIP_DROP_MEMBERSHIP\fR.
838 .RE
839
840 .sp
841 .ne 2
842 .na
843 \fB\fBEADDRINUSE\fR\fR
844 .ad
845 .RS 17n
846 Address already joined for \fBIP_ADD_MEMBERSHIP\fR.
847 .RE
848
849 .sp
850 .ne 2
851 .na
852 \fB\fBENOENT\fR\fR
853 .ad
854 .RS 17n
855 Address not joined for \fBIP_DROP_MEMBERSHIP\fR.
856 .RE
857
858 .sp
859 .ne 2
860 .na
861 \fB\fBENOPROTOOPT\fR\fR
862 .ad
863 .RS 17n
864 Invalid socket type.
865 .RE
866
867 .sp
868 .ne 2
869 .na
870 \fB\fBEPERM\fR\fR
871 .ad
872 .RS 17n
873 No permissions.
874 .RE
875
876 .SH NOTES
877 .sp
878 .LP
879 Raw sockets should receive \fBICMP\fR error packets relating to the protocol;
880 currently such packets are simply discarded.
881 .sp
882 .LP
883 Users of higher-level protocols such as \fBTCP\fR and \fBUDP\fR should be able
884 to see received IP options.
|
1 '\" te
2 .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
3 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
4 .\" Copyright 2008 AT&T
5 .\" 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.
6 .\" 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.
7 .\" 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]
8 .TH IP 7P "Sep 18, 2020"
9 .SH NAME
10 ip, IP \- Internet Protocol
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fB#include <sys/socket.h>\fR
15 .fi
16
17 .LP
18 .nf
19 \fB#include <netinet/in.h>\fR
20 .fi
21
22 .LP
23 .nf
24 \fBs = socket(AF_INET, SOCK_RAW, proto);\fR
25 .fi
26
27 .LP
28 .nf
63 the IP header and options intact.
64 .sp
65 .LP
66 If an application uses \fBIP_HDRINCL\fR and provides the IP header contents,
67 the IP stack does not modify the following supplied fields under any
68 conditions: Type of Service, DF Flag, Protocol, and Destination Address. The IP
69 Options and IHL fields are set by use of \fBIP_OPTIONS\fR, and \fBTotal
70 Length\fR is updated to include any options. Version is set to the default.
71 Identification is chosen by the normal IP ID selection logic. The source
72 address is updated if none was specified and the TTL is changed if the packet
73 has a broadcast destination address. Since an applicaton cannot send down
74 fragments (as IP assigns the IP ID), Fragment Offset is always 0. The IP
75 Checksum field is computed by IP. None of the data beyond the IP header are
76 changed, including the application-provided transport header.
77 .sp
78 .LP
79 The socket options supported at the IP level are:
80 .sp
81 .ne 2
82 .na
83 \fBIP_OPTIONS\fR
84 .ad
85 .RS 22n
86 IP options for outgoing datagrams. This socket option may be used to set IP
87 options to be included in each outgoing datagram. IP options to be sent are set
88 with \fBsetsockopt()\fR (see \fBgetsockopt\fR(3SOCKET)). The
89 \fBgetsockopt\fR(3SOCKET) call returns the IP options set in the last
90 \fBsetsockopt()\fR call. IP options on received datagrams are visible to user
91 programs only using raw IP sockets. The format of IP options given in
92 \fBsetsockopt()\fR matches those defined in the IP specification with one
93 exception: the list of addresses for the source routing options must include
94 the first-hop gateway at the beginning of the list of gateways. The first-hop
95 gateway address will be extracted from the option list and the size adjusted
96 accordingly before use. IP options may be used with any socket type in the
97 Internet family.
98 .RE
99
100 .sp
101 .ne 2
102 .na
103 \fBIP_SEC_OPT\fR
104 .ad
105 .RS 22n
106 Enable or obtain IPsec security settings for this socket. For more details on
107 the protection services of IPsec, see \fBipsec\fR(7P).
108 .RE
109
110 .sp
111 .ne 2
112 .na
113 \fBIP_ADD_MEMBERSHIP\fR
114 .ad
115 .RS 22n
116 Join a multicast group.
117 .RE
118
119 .sp
120 .ne 2
121 .na
122 \fBIP_DROP_MEMBERSHIP\fR
123 .ad
124 .RS 22n
125 Leave a multicast group.
126 .RE
127
128 .sp
129 .ne 2
130 .na
131 \fBIP_BOUND_IF\fR
132 .ad
133 .RS 22n
134 Limit reception and transmission of packets to this interface. Takes an
135 integer as an argument. The integer is the selected interface index.
136 .RE
137
138 .sp
139 .LP
140 The following option takes \fBin_pktinfo_t\fR as the parameter:
141 .sp
142 .ne 2
143 .na
144 \fBIP_PKTINFO\fR
145 .ad
146 .sp .6
147 .RS 4n
148 Set the source address and/or transmit interface of the packet(s). Note that
149 the IP_BOUND_IF socket option takes precedence over the interface index passed
150 in IP_PKTINFO.
151 .sp
152 .in +2
153 .nf
154 struct in_pktinfo {
155 unsigned int ipi_ifindex;/* send/recv interface index */
156 struct in_addr ipi_spec_dst;/* matched source addr. */
157 struct in_addr ipi_addr;/* src/dst addr. in IP hdr */
158 } in_pktinfo_t;
159 .fi
160 .in -2
161
162 When passed in (on transmit) via ancillary data with IP_PKTINFO, ipi_spec_dst
163 is used as the source address and ipi_ifindex is used as the interface index to
164 send the packet out.
165 .RE
166
167 .sp
168 .LP
169 The following options are boolean switches controlling the reception of
170 ancillary data:
171
172 .sp
173 .ne 2
174 .na
175 \fBIP_RECVDSTADDR\fR
176 .ad
177 .RS 22n
178 When enabled on a SOCK_DGRAM socket, enables receipt of the destination
179 IP address of the incoming packet. Returns \fBinaddr_t\fR as ancillary
180 data.
181 .RE
182
183 .sp
184 .ne 2
185 .na
186 \fBIP_RECVIF\fR
187 .ad
188 .RS 22n
189 Enable/disable receipt of the inbound interface index. Returns \fBuint_t\fR as
190 ancillary data.
191 .RE
192
193 .sp
194 .ne 2
195 .na
196 \fBIP_RECVOPTS\fR
197 .ad
198 .RS 22n
199 When enabled on a SOCK_DGRAM socket, enables receipt of the IP options
200 from the incoming packet. Returns variable-length IP options, up to 40
201 bytes, as ancillary data.
202 .RE
203
204 .sp
205 .ne 2
206 .na
207 \fBIP_RECVPKTINFO\fR
208 .ad
209 .RS 22n
210 Enable/disable receipt of the index of the interface the packet arrived on, the
211 local address that was matched for reception, and the inbound packet's actual
212 destination address. Takes boolean as the parameter. Returns
213 \fBin_pktinfo_t\fR as ancillary data.
214 .RE
215 .RE
216
217 .sp
218 .ne 2
219 .na
220 \fBIP_RECVSLLA\fR
221 .ad
222 .RS 22n
223 When enabled on a SOCK_DGRAM socket, enables receipt of the source link-layer
224 address for the incoming packet. Returns \fBstruct sockaddr_dl\fR as
225 ancillary data.
226 .RE
227
228 .sp
229 .ne 2
230 .na
231 \fBIP_RECVTTL\fR
232 .ad
233 .RS 22n
234 When enabled on a SOCK_DGRAM socket, the IP TTL (time to live) field for an
235 incoming datagram is returned as \fBuint8_t\fR in ancillary data.
236 .RE
237
238 .sp
239 .ne 2
240 .na
241 \fBIP_RECVTOS\fR
242 .ad
243 .RS 22n
244 When enabled, the IP TOS (type of service) field is returned as \fBuint8_t\fR
245 in ancillary data. For \fBSOCK_DGRAM\fR sockets, the ancillary data item is
246 included for every call to \fBrecvmsg()\fR. For \fBSOCK_STREAM\fR sockets,
247 where there is no direct mapping between received TCP segments and receive
248 operations, the ancillary data item will only be present when the value has
249 changed.
250 .RE
251
252 .sp
253 .LP
254 The following options take a \fBstruct ip_mreq\fR as the parameter. The
255 structure contains a multicast address which must be set to the \fBCLASS-D\fR
256 \fBIP\fR multicast address and an interface address. Normally the interface
257 address is set to \fBINADDR_ANY\fR which causes the kernel to choose the
258 interface on which to join.
259 .sp
260 .ne 2
261 .na
262 \fBIP_BLOCK_SOURCE\fR
263 .ad
264 .RS 29n
265 Block multicast packets whose source address matches the given source address.
266 The specified group must be joined previously using IP_ADD_MEMBERSHIP or
267 MCAST_JOIN_GROUP.
268 .RE
269
270 .sp
271 .ne 2
272 .na
273 \fBIP_UNBLOCK_SOURCE\fR
274 .ad
275 .RS 29n
276 Unblock (begin receiving) multicast packets which were previously blocked using
277 IP_BLOCK_SOURCE.
278 .RE
279
280 .sp
281 .ne 2
282 .na
283 \fBIP_ADD_SOURCE_MEMBERSHIP\fR
284 .ad
285 .RS 29n
286 Begin receiving packets for the given multicast group whose source address
287 matches the specified address.
288 .RE
289
290 .sp
291 .ne 2
292 .na
293 \fBIP_DROP_SOURCE_MEMBERSHIP\fR
294 .ad
295 .RS 29n
296 Stop receiving packets for the given multicast group whose source address
297 matches the specified address.
298 .RE
299
300 .sp
301 .LP
302 The following options take a \fBstruct ip_mreq_source\fR as the parameter. The
303 structure contains a multicast address (which must be set to the CLASS-D IP
304 multicast address), an interface address, and a source address.
305 .sp
306 .ne 2
307 .na
308 \fBMCAST_JOIN_GROUP\fR
309 .ad
310 .RS 28n
311 Join a multicast group. Functionally equivalent to IP_ADD_MEMBERSHIP.
312 .RE
313
314 .sp
315 .ne 2
316 .na
317 \fBMCAST_BLOCK_SOURCE\fR
318 .ad
319 .RS 28n
320 Block multicast packets whose source address matches the given source address.
321 The specified group must be joined previously using IP_ADD_MEMBERSHIP or
322 MCAST_JOIN_GROUP.
323 .RE
324
325 .sp
326 .ne 2
327 .na
328 \fBMCAST_UNBLOCK_SOURCE\fR
329 .ad
330 .RS 28n
331 Unblock (begin receiving) multicast packets which were previously blocked using
332 MCAST_BLOCK_SOURCE.
333 .RE
334
335 .sp
336 .ne 2
337 .na
338 \fBMCAST_LEAVE_GROUP\fR
339 .ad
340 .RS 28n
341 Leave a multicast group. Functionally equivalent to IP_DROP_MEMBERSHIP.
342 .RE
343
344 .sp
345 .ne 2
346 .na
347 \fBMCAST_JOIN_SOURCE_GROUP\fR
348 .ad
349 .RS 28n
350 Begin receiving packets for the given multicast group whose source address
351 matches the specified address.
352 .RE
353
354 .sp
355 .ne 2
356 .na
357 \fBMCAST_LEAVE_SOURCE_GROUP\fR
358 .ad
359 .RS 28n
360 Stop receiving packets for the given multicast group whose source address
361 matches the specified address.
362 .RE
363
364 .sp
365 .LP
366 The following options take a struct \fBgroup_req\fR or struct
367 \fBgroup_source_req\fR as the parameter. The `\fBgroup_req\fR structure
368 contains an interface index and a multicast address which must be set to the
369 CLASS-D multicast address. The \fBgroup_source_req\fR structure is used for
370 those options which include a source address. It contains an interface index,
371 multicast address, and source address.
372 .sp
373 .ne 2
374 .na
375 \fBIP_MULTICAST_IF\fR
376 .ad
377 .RS 21n
378 The outgoing interface for multicast packets. This option takes a \fBstruct\fR
379 \fBin_addr\fR as an argument, and it selects that interface for outgoing IP
380 multicast packets. If the address specified is \fBINADDR_ANY\fR, it uses the
381 unicast routing table to select the outgoing interface (which is the default
382 behavior).
383 .RE
384
385 .sp
386 .ne 2
387 .na
388 \fBIP_MULTICAST_TTL\fR
389 .ad
390 .RS 21n
391 Time to live for multicast datagrams. This option takes an unsigned character
392 as an argument. Its value is the TTL that IP uses on outgoing multicast
393 datagrams. The default is \fB1\fR.
394 .RE
395
396 .sp
397 .ne 2
398 .na
399 \fBIP_MULTICAST_LOOP\fR
400 .ad
401 .RS 21n
402 Loopback for multicast datagrams. Normally multicast datagrams are delivered
403 to members on the sending host (or sending zone). Setting the unsigned
404 character argument to 0 causes the opposite behavior, meaning that when
405 multiple zones are present, the datagrams are delivered to all zones except the
406 sending zone.
407 .RE
408
409 .sp
410 .ne 2
411 .na
412 \fBIP_TOS\fR
413 .ad
414 .RS 21n
415 This option takes an integer argument as its input value. The least significant
416 8 bits of the value are used to set the Type Of Service field in the IP header
417 of the outgoing packets.
418 .RE
419
420 .sp
421 .ne 2
422 .na
423 \fBIP_NEXTHOP\fR
424 .ad
425 .RS 21n
426 This option specifies the address of the onlink nexthop for traffic originating
427 from that socket. It causes the routing table to be bypassed and outgoing
428 traffic is sent directly to the specified nexthop. This option takes an
429 ipaddr_t argument representing the IPv4 address of the nexthop as the input
430 value. The IP_NEXTHOP option takes precedence over IPOPT_LSRR. IP_BOUND_IF and
431 SO_DONTROUTE take precedence over IP_NEXTHOP. This option has no meaning for
432 broadcast and multicast packets. The application must ensure that the specified
433 nexthop is alive. An application may want to specify the IP_NEXTHOP option on a
434 TCP listener socket only for incoming requests to a particular IP address. In
435 this case, it must avoid binding the socket to INADDR_ANY and instead must bind
436 the listener socket to the specific IP address. In addition, typically the
437 application may want the incoming and outgoing interface to be the same. In
438 this case, the application must select a suitable nexthop that is onlink and
439 reachable via the desired interface and do a setsockopt (IP_NEXTHOP) on it.
440 Then it must bind to the IP address of the desired interface. Setting the
441 IP_NEXTHOP option requires the PRIV_SYS_NET_CONFIG privilege.
442 .RE
443
687 .na
688 \fBdown\fR
689 .ad
690 .RS 18n
691 There are no logical interfaces expecting to receive packets.
692 .RE
693
694 .sp
695 .ne 2
696 .na
697 \fBaddress change\fR
698 .ad
699 .RS 18n
700 An address has changed on a logical interface.
701 .RE
702
703 .SH SEE ALSO
704 .sp
705 .LP
706 \fBifconfig\fR(1M), \fBrouteadm\fR(1M), \fBndd\fR(1M), \fBread\fR(2),
707 \fBwrite\fR(2), \fBsocket.h\fR(3HEAD), \fBbind\fR(3SOCKET),
708 \fBconnect\fR(3SOCKET), \fBgetsockopt\fR(3SOCKET), \fBrecv\fR(3SOCKET),
709 \fBsend\fR(3SOCKET), \fBdefaultrouter\fR(4), \fBicmp\fR(7P), \fBif_tcp\fR(7P),
710 \fBinet\fR(7P), \fBip\fR(7P), \fBip6\fR(7P), \fBipsec\fR(7P),
711 \fBrouting\fR(7P), \fBtcp\fR(7P), \fBudp\fR(7P), \fBnet_hook_register\fR(9F),
712 \fBhook_pkt_event\fR(9S)
713 .sp
714 .LP
715 Braden, R., \fIRFC 1122, Requirements for Internet Hosts \(mi Communication
716 Layers\fR, Information Sciences Institute, University of Southern California,
717 October 1989.
718 .sp
719 .LP
720 Postel, J., \fIRFC 791, Internet Protocol \(mi DARPA Internet Program Protocol
721 Specification\fR, Information Sciences Institute, University of Southern
722 California, September 1981.
723 .SH DIAGNOSTICS
724 .sp
725 .LP
726 A socket operation may fail with one of the following errors returned:
727 .sp
728 .ne 2
729 .na
730 \fBEACCES\fR
731 .ad
732 .RS 17n
733 A \fBbind()\fR operation was attempted with a "reserved" port number and the
734 effective user ID of the process was not the privileged user.
735 .sp
736 Setting the IP_NEXTHOP was attempted by a process lacking the
737 PRIV_SYS_NET_CONFIG privilege.
738 .RE
739
740 .sp
741 .ne 2
742 .na
743 \fBEADDRINUSE\fR
744 .ad
745 .RS 17n
746 A \fBbind()\fR operation was attempted on a socket with a network address/port
747 pair that has already been bound to another socket.
748 .RE
749
750 .sp
751 .ne 2
752 .na
753 \fBEADDRNOTAVAIL\fR
754 .ad
755 .RS 17n
756 A \fBbind()\fR operation was attempted for an address that is not configured on
757 this machine.
758 .RE
759
760 .sp
761 .ne 2
762 .na
763 \fBEINVAL\fR
764 .ad
765 .RS 17n
766 A \fBsendmsg()\fR operation with a non-NULL \fBmsg_accrights\fR was attempted.
767 .RE
768
769 .sp
770 .ne 2
771 .na
772 \fBEINVAL\fR
773 .ad
774 .RS 17n
775 A \fBgetsockopt()\fR or \fBsetsockopt()\fR operation with an unknown socket
776 option name was given.
777 .RE
778
779 .sp
780 .ne 2
781 .na
782 \fBEINVAL\fR
783 .ad
784 .RS 17n
785 A \fBgetsockopt()\fR or \fBsetsockopt()\fR operation was attempted with the
786 \fBIP\fR option field improperly formed; an option field was shorter than the
787 minimum value or longer than the option buffer provided.
788 .RE
789
790 .sp
791 .ne 2
792 .na
793 \fBEISCONN\fR
794 .ad
795 .RS 17n
796 A \fBconnect()\fR operation was attempted on a socket on which a
797 \fBconnect()\fR operation had already been performed, and the socket could not
798 be successfully disconnected before making the new connection.
799 .RE
800
801 .sp
802 .ne 2
803 .na
804 \fBEISCONN\fR
805 .ad
806 .RS 17n
807 A \fBsendto()\fR or \fBsendmsg()\fR operation specifying an address to which
808 the message should be sent was attempted on a socket on which a \fBconnect()\fR
809 operation had already been performed.
810 .RE
811
812 .sp
813 .ne 2
814 .na
815 \fBEMSGSIZE\fR
816 .ad
817 .RS 17n
818 A \fBsend()\fR, \fBsendto()\fR, or \fBsendmsg()\fR operation was attempted to
819 send a datagram that was too large for an interface, but was not allowed to be
820 fragmented (such as broadcasts).
821 .RE
822
823 .sp
824 .ne 2
825 .na
826 \fBENETUNREACH\fR
827 .ad
828 .RS 17n
829 An attempt was made to establish a connection by means of \fBconnect()\fR, or
830 to send a datagram by means of \fBsendto()\fR or \fBsendmsg()\fR, where there
831 was no matching entry in the routing table; or if an ICMP "destination
832 unreachable" message was received.
833 .RE
834
835 .sp
836 .ne 2
837 .na
838 \fBENOTCONN\fR
839 .ad
840 .RS 17n
841 A \fBsend()\fR or \fBwrite()\fR operation, or a \fBsendto()\fR or
842 \fBsendmsg()\fR operation not specifying an address to which the message should
843 be sent, was attempted on a socket on which a \fBconnect()\fR operation had not
844 already been performed.
845 .RE
846
847 .sp
848 .ne 2
849 .na
850 \fBENOBUFS\fR
851 .ad
852 .RS 17n
853 The system ran out of memory for fragmentation buffers or other internal data
854 structures.
855 .RE
856
857 .sp
858 .ne 2
859 .na
860 \fBENOBUFS\fR
861 .ad
862 .RS 17n
863 \fBSO_SNDBUF\fR or \fBSO_RCVBUF\fR exceeds a system limit.
864 .RE
865
866 .sp
867 .ne 2
868 .na
869 \fBEINVAL\fR
870 .ad
871 .RS 17n
872 Invalid length for \fBIP_OPTIONS\fR.
873 .RE
874
875 .sp
876 .ne 2
877 .na
878 \fBEHOSTUNREACH\fR
879 .ad
880 .RS 17n
881 Invalid address for \fBIP_MULTICAST_IF\fR.
882 .sp
883 Invalid (offlink) nexthop address for IP_NEXTHOP.
884 .RE
885
886 .sp
887 .ne 2
888 .na
889 \fBEINVAL\fR
890 .ad
891 .RS 17n
892 Not a multicast address for \fBIP_ADD_MEMBERSHIP\fR and
893 \fBIP_DROP_MEMBERSHIP\fR.
894 .RE
895
896 .sp
897 .ne 2
898 .na
899 \fBEADDRNOTAVAIL\fR
900 .ad
901 .RS 17n
902 Bad interface address for \fBIP_ADD_MEMBERSHIP\fR and \fBIP_DROP_MEMBERSHIP\fR.
903 .RE
904
905 .sp
906 .ne 2
907 .na
908 \fBEADDRINUSE\fR
909 .ad
910 .RS 17n
911 Address already joined for \fBIP_ADD_MEMBERSHIP\fR.
912 .RE
913
914 .sp
915 .ne 2
916 .na
917 \fBENOENT\fR
918 .ad
919 .RS 17n
920 Address not joined for \fBIP_DROP_MEMBERSHIP\fR.
921 .RE
922
923 .sp
924 .ne 2
925 .na
926 \fBENOPROTOOPT\fR
927 .ad
928 .RS 17n
929 Invalid socket type.
930 .RE
931
932 .sp
933 .ne 2
934 .na
935 \fBEPERM\fR
936 .ad
937 .RS 17n
938 No permissions.
939 .RE
940
941 .SH NOTES
942 .sp
943 .LP
944 Raw sockets should receive \fBICMP\fR error packets relating to the protocol;
945 currently such packets are simply discarded.
946 .sp
947 .LP
948 Users of higher-level protocols such as \fBTCP\fR and \fBUDP\fR should be able
949 to see received IP options.
|