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
29 \fBt = t_open ("/dev/rawip", O_RDWR);\fR
30 .fi
31
32 .SH DESCRIPTION
33 .sp
34 .LP
35 IP is the internetwork datagram delivery protocol that is central to the
36 Internet protocol family. Programs may use \fBIP\fR through higher-level
37 protocols such as the Transmission Control Protocol (TCP) or the User Datagram
38 Protocol (UDP), or may interface directly to IP. See \fBtcp\fR(7P) and
39 \fBudp\fR(7P). Direct access may be by means of the socket interface, using a
40 "raw socket," or by means of the Transport Level Interface (TLI). The protocol
41 options defined in the IP specification may be set in outgoing datagrams.
42 .sp
43 .LP
44 Packets sent to or from this system may be subject to IPsec policy. See
45 \fBipsec\fR(7P) for more information.
46 .SH APPLICATION PROGRAMMING INTERFACE
47 .sp
48 .LP
49 The STREAMS driver \fB/dev/rawip\fR is the TLI transport provider that provides
50 raw access to IP.
51 .sp
52 .LP
53 Raw IP sockets are connectionless and are normally used with the \fBsendto()\fR
54 and \fBrecvfrom()\fR calls (see \fBsend\fR(3SOCKET) and \fBrecv\fR(3SOCKET)),
55 although the \fBconnect\fR(3SOCKET) call may also be used to fix the
56 destination for future datagram. In this case, the \fBread\fR(2) or
57 \fBrecv\fR(3SOCKET) and \fBwrite\fR(2) or \fBsend\fR(3SOCKET) calls may be
58 used. If \fIproto\fR is \fBIPPROTO_RAW\fR or \fBIPPROTO_IGMP\fR, the
59 application is expected to include a complete IP header when sending.
60 Otherwise, that protocol number will be set in outgoing datagrams and used to
61 filter incoming datagrams and an IP header will be generated and prepended to
62 each outgoing datagram. In either case, received datagrams are returned with
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
444 .sp
445 .LP
446 The multicast socket options (IP_MULTICAST_IF, IP_MULTICAST_TTL,
447 IP_MULTICAST_LOOP and IP_RECVIF) can be used with any datagram socket type in
448 the Internet family.
449 .sp
450 .LP
451 At the socket level, the socket option \fBSO_DONTROUTE\fR may be applied. This
452 option forces datagrams being sent to bypass routing and forwarding by forcing
453 the IP Time To Live field to \fB1\fR, meaning that the packet will not be
454 forwarded by routers.
455 .sp
456 .LP
457 Raw IP datagrams can also be sent and received using the TLI connectionless
458 primitives.
459 .sp
460 .LP
461 Datagrams flow through the IP layer in two directions: from the network
462 \fIup\fR to user processes and from user processes \fIdown\fR to the network.
463 Using this orientation, IP is layered \fIabove\fR the network interface drivers
464 and \fIbelow\fR the transport protocols such as UDP and TCP. The Internet
465 Control Message Protocol (ICMP) is logically a part of IP. See \fBicmp\fR(7P).
466 .sp
467 .LP
468 IP provides for a checksum of the header part, but not the data part, of the
469 datagram. The checksum value is computed and set in the process of sending
470 datagrams and checked when receiving datagrams.
471 .sp
472 .LP
473 IP options in received datagrams are processed in the IP layer according to the
474 protocol specification. Currently recognized IP options include: security,
475 loose source and record route (LSRR), strict source and record route (SSRR),
476 record route, and internet timestamp.
477 .sp
478 .LP
479 By default, the IP layer will not forward IPv4 packets that are not addressed
480 to it. This behavior can be overridden by using \fBrouteadm\fR(1M) to enable
481 the ipv4-forwarding option. IPv4 forwarding is configured at boot time based on
482 the setting of \fBrouteadm\fR(1M)'s ipv4-forwarding option.
483 .sp
484 .LP
485 For backwards compatibility, IPv4 forwarding can be enabled or disabled using
486 \fBndd\fR(1M)'s ip_forwarding variable. It is set to 1 if IPv4 forwarding is
487 enabled, or 0 if it is disabled.
488 .sp
489 .LP
490 Additionally, finer-grained forwarding can be configured in IP. Each interface
491 can be configured to forward IP packets by setting the IFF_ROUTER interface
492 flag. This flag can be set and cleared using \fBifconfig\fR(1M)'s router and
493 router options. If an interface's IFF_ROUTER flag is set, packets can be
494 forwarded to or from the interface. If it is clear, packets will neither be
495 forwarded from this interface to others, nor forwarded to this interface.
496 Setting the ip_forwarding variable sets all of the IPv4 interfaces' IFF_ROUTER
497 flags.
498 .sp
499 .LP
500 For backwards compatibility, each interface creates an
501 \fB<ifname>:ip_forwarding /dev/ip\fR variable that can be modified using
502 \fBndd\fR(1M). An interface's \fB:ip_forwarding ndd\fR variable is a boolean
503 variable that mirrors the status of its IFF_ROUTER interface flag. It is set to
504 1 if the flag is set, or 0 if it is clear. This interface specific \fB<ifname>
505 :ip_forwarding ndd\fR variable is obsolete and may be removed in a future
506 release of Solaris. The \fBifconfig\fR(1M) router and -router interfaces are
507 preferred.
508 .sp
509 .LP
510 The IP layer sends an ICMP message back to the source host in many cases when
511 it receives a datagram that can not be handled. A "time exceeded" ICMP message
512 is sent if the "time to live" field in the IP header drops to zero in the
513 process of forwarding a datagram. A "destination unreachable" message is sent
514 if a datagram can not be forwarded because there is no route to the final
515 destination, or if it can not be fragmented. If the datagram is addressed to
516 the local host but is destined for a protocol that is not supported or a port
517 that is not in use, a destination unreachable message is also sent. The IP
518 layer may send an ICMP "source quench" message if it is receiving datagrams too
519 quickly. ICMP messages are only sent for the first fragment of a fragmented
520 datagram and are never returned in response to errors in other ICMP messages.
521 .sp
522 .LP
523 The IP layer supports fragmentation and reassembly. Datagrams are fragmented on
524 output if the datagram is larger than the maximum transmission unit (MTU) of
525 the network interface. Fragments of received datagrams are dropped from the
526 reassembly queues if the complete datagram is not reconstructed within a short
527 time period.
528 .sp
529 .LP
530 Errors in sending discovered at the network interface driver layer are passed
531 by IP back up to the user process.
532 .sp
533 .LP
534 Multi-Data Transmit allows more than one packet to be sent from the IP module
535 to another in a given call, thereby reducing the per-packet processing costs.
536 The behavior of Multi-Data Transmit can be overrideen by using \fBndd\fR(1M) to
537 set the \fB/dev/ip\fR variable, ip_multidata_outbound to 0. Note, the IP module
538 will only initiate Multi-Data Transmit if the network interface driver supports
539 it.
540 .SH PACKET EVENTS
541 .sp
542 .LP
543 Through the netinfo framework, this driver provides the following packet
544 events:
545 .sp
546 .ne 2
547 .na
548 \fBPhysical in\fR
549 .ad
550 .RS 16n
551 Packets received on a network interface from an external source.
552 .RE
553
554 .sp
555 .ne 2
556 .na
557 \fBPhysical out\fR
558 .ad
559 .RS 16n
560 Packets to be sent out a network interface.
561 .RE
562
563 .sp
564 .ne 2
565 .na
566 \fBForwarding\fR
567 .ad
568 .RS 16n
569 Packets being forwarded through this host to another network.
570 .RE
571
572 .sp
573 .ne 2
574 .na
575 \fBloopback in\fR
576 .ad
577 .RS 16n
578 Packets that have been sent by a local application to another.
579 .RE
580
581 .sp
582 .ne 2
583 .na
584 \fBloopback out\fR
585 .ad
586 .RS 16n
587 Packets about to be received by a local application from another.
588 .RE
589
590 .sp
591 .LP
592 Currently, only a single function may be registered for each event. As a
593 result, if the slot for an event is already occupied by someone else, a second
594 attempt to register a callback fails.
595 .sp
596 .LP
597 To receive packet events in a kernel module, it is first necessary to obtain a
598 handle for either IPv4 or IPv6 traffic. This is achieved by passing NHF_INET
599 or NHF_INET6 through to a net_protocol_lookup() call. The value returned from
600 this call must then be passed into a call to net_register_hook(), along with
601 a description of the hook to add. For a description of the structure passed
602 through to the callback, please see \fBhook_pkt_event\fR(9S). For IP
603 packets, this structure is filled out as follows:
604 .sp
605 .ne 2
606 .na
607 \fBhpe_ifp\fR
608 .ad
609 .RS 11n
610 Identifier indicating the inbound interface for packets received with the
611 "physical in" event.
612 .RE
613
614 .sp
615 .ne 2
616 .na
617 \fBhpe_ofp\fR
618 .ad
619 .RS 11n
620 Identifier indicating the outbound interface for packets received with the
621 "physical out" event.
622 .RE
623
624 .sp
625 .ne 2
626 .na
627 \fBhpe_hdr\fR
628 .ad
629 .RS 11n
630 Pointer to the start of the IP header (not the ethernet header).
631 .RE
632
633 .sp
634 .ne 2
635 .na
636 \fBhpe_mp\fR
637 .ad
638 .RS 11n
639 Pointer to the start of the mblk_t chain containing the IP packet.
640 .RE
641
642 .sp
643 .ne 2
644 .na
645 \fBhpe_mb\fR
646 .ad
647 .RS 11n
648 Pointer to the mblk_t with the IP header in it.
649 .RE
650
651 .SH NETWORK INTERFACE EVENTS
652 .sp
653 .LP
654 In addition to events describing packets as they move through the system, it is
655 also possible to receive notification of events relating to network interfaces.
656 These events are all reported back through the same callback. The list of
657 events is as follows:
658 .sp
659 .ne 2
660 .na
661 \fBplumb\fR
662 .ad
663 .RS 18n
664 A new network interface has been instantiated.
665 .RE
666
667 .sp
668 .ne 2
669 .na
670 \fBunplumb\fR
671 .ad
672 .RS 18n
673 A network interface is no longer associated with this protocol.
674 .RE
675
676 .sp
677 .ne 2
678 .na
679 \fBup\fR
680 .ad
681 .RS 18n
682 At least one logical interface is now ready to receive packets.
683 .RE
684
685 .sp
686 .ne 2
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.