1 .\" Copyright (c) 1983, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)ip.4 8.2 (Berkeley) 11/30/93
46 .Fn socket AF_INET SOCK_RAW proto
49 is the transport layer protocol used
50 by the Internet protocol family.
51 Options may be set at the
54 when using higher-level protocols that are based on
60 It may also be accessed
63 when developing new protocols, or
64 special-purpose applications.
73 may be used to provide
75 options to be transmitted in the
77 header of each outgoing packet
78 or to examine the header options on incoming packets.
80 options may be used with any socket type in the Internet family.
83 options to be sent is that specified by the
85 protocol specification (RFC-791), with one exception:
86 the list of addresses for Source Route options must include the first-hop
87 gateway at the beginning of the list of gateways.
88 The first-hop gateway address will be extracted from the option list
89 and the size adjusted accordingly before use.
90 To disable previously specified options,
91 use a zero-length buffer:
93 setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);
99 may be used to set the type-of-service and time-to-live
103 .Dv SOCK_STREAM , SOCK_DGRAM ,
109 int tos = IPTOS_LOWDELAY; /* see <netinet/ip.h> */
110 setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos));
112 int ttl = 60; /* max = 255 */
113 setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl));
117 may be used to set the minimum acceptable TTL a packet must have when
118 received on a socket.
119 All packets with a lower TTL are silently dropped.
120 This option is only really useful when set to 255, preventing packets
121 from outside the directly connected networks reaching local listeners
125 may be used to set the Don't Fragment flag on IP packets.
126 Currently this option is respected only on
135 sockets, the Don't Fragment flag is controlled by the Path
136 MTU Discovery option.
137 Sending a packet larger than the MTU size of the egress interface,
138 determined by the destination address, returns an
144 option is enabled on a
149 call will return the destination
158 structure points to a buffer
161 structure followed by the
166 fields have the following values:
168 cmsg_len = sizeof(struct in_addr)
169 cmsg_level = IPPROTO_IP
170 cmsg_type = IP_RECVDSTADDR
173 The source address to be used for outgoing
175 datagrams on a socket that is not bound to a specific
177 address can be specified as ancillary data with a type code of
179 The msg_control field in the msghdr structure should point to a buffer
182 structure followed by the
185 The cmsghdr fields should have the following values:
187 cmsg_len = sizeof(struct in_addr)
188 cmsg_level = IPPROTO_IP
189 cmsg_type = IP_SENDSRCADDR
194 is defined to have the same value as
200 can be used directly as a control message for
206 option is enabled on a
210 socket, the destination address of outgoing
211 broadcast datagrams on that socket will be forced
212 to the undirected broadcast address,
213 .Dv INADDR_BROADCAST ,
215 This is in contrast to the default behavior of the
216 system, which is to transmit undirected broadcasts
217 via the first network interface with the
218 .Dv IFF_BROADCAST flag set.
220 This option allows applications to choose which
221 interface is used to transmit an undirected broadcast
223 For example, the following code would force an
224 undirected broadcast to be transmitted via the interface
225 configured with the broadcast address 192.168.2.255:
228 struct sockaddr_in sin;
229 u_char onesbcast = 1; /* 0 = disable (default), 1 = enable */
231 setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast));
232 sin.sin_addr.s_addr = inet_addr("192.168.2.255");
233 sin.sin_port = htons(1234);
234 sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin));
237 It is the application's responsibility to set the
239 to an appropriate value in order to prevent broadcast storms.
240 The application must have sufficient credentials to set the
242 socket level option, otherwise the
243 .Dv IP_ONESBCAST option has no effect.
247 option is enabled on a
254 (time to live) field for a
257 The msg_control field in the msghdr structure points to a buffer
258 that contains a cmsghdr structure followed by the
260 The cmsghdr fields have the following values:
262 cmsg_len = sizeof(u_char)
263 cmsg_level = IPPROTO_IP
264 cmsg_type = IP_RECVTTL
270 option is enabled on a
275 .Vt "struct sockaddr_dl"
276 corresponding to the interface on which the
282 structure points to a buffer that contains a
284 structure followed by the
285 .Vt "struct sockaddr_dl" .
288 fields have the following values:
290 cmsg_len = sizeof(struct sockaddr_dl)
291 cmsg_level = IPPROTO_IP
292 cmsg_type = IP_RECVIF
296 may be used to set the port range used for selecting a local port number
297 on a socket with an unspecified (zero) port number.
300 .Bl -tag -width IP_PORTRANGE_DEFAULT
301 .It Dv IP_PORTRANGE_DEFAULT
302 use the default range of values, normally
303 .Dv IPPORT_HIFIRSTAUTO
305 .Dv IPPORT_HILASTAUTO .
306 This is adjustable through the sysctl setting:
307 .Va net.inet.ip.portrange.first
309 .Va net.inet.ip.portrange.last .
310 .It Dv IP_PORTRANGE_HIGH
311 use a high range of values, normally
312 .Dv IPPORT_HIFIRSTAUTO
314 .Dv IPPORT_HILASTAUTO .
315 This is adjustable through the sysctl setting:
316 .Va net.inet.ip.portrange.hifirst
318 .Va net.inet.ip.portrange.hilast .
319 .It Dv IP_PORTRANGE_LOW
320 use a low range of ports, which are normally restricted to
321 privileged processes on
324 The range is normally from
327 .Li IPPORT_RESERVEDSTART
329 This is adjustable through the sysctl setting:
330 .Va net.inet.ip.portrange.lowfirst
332 .Va net.inet.ip.portrange.lowlast .
335 The range of privileged ports which only may be opened by
336 root-owned processes may be modified by the
337 .Va net.inet.ip.portrange.reservedlow
339 .Va net.inet.ip.portrange.reservedhigh
341 The values default to the traditional range,
345 (0 through 1023), respectively.
346 Note that these settings do not affect and are not accounted for in the
347 use or calculation of the other
348 .Va net.inet.ip.portrange
350 Changing these values departs from
352 tradition and has security
353 consequences that the administrator should carefully evaluate before
354 modifying these settings.
356 Ports are allocated at random within the specified port range in order
357 to increase the difficulty of random spoofing attacks.
358 In scenarios such as benchmarking, this behavior may be undesirable.
360 .Va net.inet.ip.portrange.randomized
361 can be used to toggle randomization off.
363 .Va net.inet.ip.portrange.randomcps
364 ports have been allocated in the last second, then return to sequential
366 Return to random allocation only once the current port allocation rate
368 .Va net.inet.ip.portrange.randomcps
370 .Va net.inet.ip.portrange.randomtime
372 The default values for
373 .Va net.inet.ip.portrange.randomcps
375 .Va net.inet.ip.portrange.randomtime
376 are 10 port allocations per second and 45 seconds correspondingly.
377 .Ss "Multicast Options"
380 multicasting is supported only on
386 and only on networks where the interface
387 driver supports multicasting.
391 option changes the time-to-live (TTL)
392 for outgoing multicast datagrams
393 in order to control the scope of the multicasts:
395 u_char ttl; /* range: 0 to 255, default = 1 */
396 setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl));
399 Datagrams with a TTL of 1 are not forwarded beyond the local network.
400 Multicast datagrams with a TTL of 0 will not be transmitted on any network,
401 but may be delivered locally if the sending host belongs to the destination
402 group and if multicast loopback has not been disabled on the sending socket
404 Multicast datagrams with TTL greater than 1 may be forwarded
405 to other networks if a multicast router is attached to the local network.
407 For hosts with multiple interfaces, where an interface has not
408 been specified for a multicast group membership,
409 each multicast transmission is sent from the primary network interface.
412 option overrides the default for
413 subsequent transmissions from a given socket:
416 setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr));
419 where "addr" is the local
421 address of the desired interface or
423 to specify the default interface.
425 To specify an interface by index, an instance of
427 may be passed instead.
430 member should be set to the index of the desired interface,
431 or 0 to specify the default interface.
432 The kernel differentiates between these two structures by their size.
437 .Em not recommended ,
438 as multicast memberships are scoped to each
439 individual interface.
440 It is supported for legacy use only by applications,
441 such as routing daemons, which expect to
442 be able to transmit link-local IPv4 multicast datagrams (224.0.0.0/24)
443 on multiple interfaces,
444 without requesting an individual membership for each interface.
447 An interface's local IP address and multicast capability can
453 Normal applications should not need to use this option.
455 If a multicast datagram is sent to a group to which the sending host itself
456 belongs (on the outgoing interface), a copy of the datagram is, by default,
457 looped back by the IP layer for local delivery.
459 .Dv IP_MULTICAST_LOOP
460 option gives the sender explicit control
461 over whether or not subsequent datagrams are looped back:
463 u_char loop; /* 0 = disable, 1 = enable (default) */
464 setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop));
468 improves performance for applications that may have no more than one
469 instance on a single host (such as a routing daemon), by eliminating
470 the overhead of receiving their own transmissions.
471 It should generally not
472 be used by applications for which there may be more than one instance on a
473 single host (such as a conferencing program) or for which the sender does
474 not belong to the destination group (such as a time querying program).
477 .Va net.inet.ip.mcast.loop
478 controls the default setting of the
479 .Dv IP_MULTICAST_LOOP
480 socket option for new sockets.
482 A multicast datagram sent with an initial TTL greater than 1 may be delivered
483 to the sending host on a different interface from that on which it was sent,
484 if the host belongs to the destination group on that other interface.
485 The loopback control option has no effect on such delivery.
487 A host must become a member of a multicast group before it can receive
488 datagrams sent to the group.
489 To join a multicast group, use the
490 .Dv IP_ADD_MEMBERSHIP
494 setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq));
499 is the following structure:
502 struct in_addr imr_multiaddr; /* IP multicast address of group */
503 struct in_addr imr_interface; /* local IP address of interface */
510 address of a particular multicast-capable interface if
511 the host is multihomed.
514 to choose the default interface, although this is not recommended;
515 this is considered to be the first interface corresponding
516 to the default route.
517 Otherwise, the first multicast-capable interface
518 configured in the system will be used.
524 member is within the network range
526 it is treated as an interface index in the system interface MIB,
527 as per the RIP Version 2 MIB Extension (RFC-1724).
530 since 7.0, this behavior is no longer supported.
532 instead use the RFC 3678 multicast source filter APIs; in particular,
533 .Dv MCAST_JOIN_GROUP .
536 .Dv IP_MAX_MEMBERSHIPS
537 memberships may be added on a single socket.
538 Membership is associated with a single interface;
539 programs running on multihomed hosts may need to
540 join the same group on more than one interface.
542 To drop a membership, use:
545 setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
550 contains the same values as used to add the membership.
551 Memberships are dropped when the socket is closed or the process exits.
552 .\" TODO: Update this piece when IPv4 source-address selection is implemented.
554 The IGMP protocol uses the primary IP address of the interface
555 as its identifier for group membership.
556 This is the first IP address configured on the interface.
557 If this address is removed or changed, the results are
558 undefined, as the IGMP membership state will then be inconsistent.
559 If multiple IP aliases are configured on the same interface,
560 they will be ignored.
562 This shortcoming was addressed in IPv6; MLDv2 requires
563 that the unique link-local address for an interface is
564 used to identify an MLDv2 listener.
565 .Ss "Source-Specific Multicast Options"
568 the use of Source-Specific Multicast (SSM) is supported.
569 These extensions require an IGMPv3 multicast router in order to
570 make best use of them.
571 If a legacy multicast router is present on the link,
573 will simply downgrade to the version of IGMP spoken by the router,
574 and the benefits of source filtering on the upstream link
575 will not be present, although the kernel will continue to
576 squelch transmissions from blocked sources.
578 Each group membership on a socket now has a filter mode:
579 .Bl -tag -width MCAST_EXCLUDE
581 Datagrams sent to this group are accepted,
582 unless the source is in a list of blocked source addresses.
584 Datagrams sent to this group are accepted
585 only if the source is in a list of accepted source addresses.
588 Groups joined using the legacy
589 .Dv IP_ADD_MEMBERSHIP
590 option are placed in exclusive-mode,
591 and are able to request that certain sources are blocked or allowed.
593 .Em delta-based API .
595 To block a multicast source on an existing group membership:
597 struct ip_mreq_source mreqs;
598 setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs));
603 is the following structure:
605 struct ip_mreq_source {
606 struct in_addr imr_multiaddr; /* IP multicast address of group */
607 struct in_addr imr_sourceaddr; /* IP address of source */
608 struct in_addr imr_interface; /* local IP address of interface */
612 should be set to the address of the source to be blocked.
614 To unblock a multicast source on an existing group:
616 struct ip_mreq_source mreqs;
617 setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs));
623 .Dv IP_UNBLOCK_SOURCE
626 for inclusive-mode group memberships.
628 To join a multicast group in
630 mode with a single source,
631 or add another source to an existing inclusive-mode membership:
633 struct ip_mreq_source mreqs;
634 setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));
637 To leave a single source from an existing group in inclusive mode:
639 struct ip_mreq_source mreqs;
640 setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));
642 If this is the last accepted source for the group, the membership
646 .Dv IP_ADD_SOURCE_MEMBERSHIP
648 .Dv IP_DROP_SOURCE_MEMBERSHIP
651 for exclusive-mode group memberships.
652 However, both exclusive and inclusive mode memberships
653 support the use of the
655 documented in RFC 3678.
656 For management of source filter lists using this API,
661 .Va net.inet.ip.mcast.maxsocksrc
663 .Va net.inet.ip.mcast.maxgrpsrc
664 are used to specify an upper limit on the number of per-socket and per-group
665 source filter entries which the kernel may allocate.
666 .\"-----------------------
671 sockets are connectionless,
672 and are normally used with the
678 call may also be used to fix the destination for future
679 packets (in which case the
687 system calls may be used).
691 is 0, the default protocol
694 packets, and only incoming packets destined for that protocol
698 is non-zero, that protocol number will be used on outgoing packets
699 and to filter incoming packets.
701 Outgoing packets automatically have an
704 them (based on the destination address and the protocol
705 number the socket is created with),
709 Incoming packets are received with
711 header and options intact.
714 indicates the complete IP header is included with the data
715 and may be used only with the
719 #include <netinet/in_systm.h>
720 #include <netinet/ip.h>
722 int hincl = 1; /* 1 = on, 0 = off */
723 setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl));
728 releases, the program must set all
729 the fields of the IP header, including the following:
731 ip->ip_v = IPVERSION;
732 ip->ip_hl = hlen >> 2;
733 ip->ip_id = 0; /* 0 means kernel set appropriate value */
743 be provided in host byte order .
744 All other fields must be provided in network byte order.
747 for more information on network byte order.
750 field is set to 0 then the kernel will choose an
752 If the header source address is set to
754 the kernel will choose an appropriate address.
756 A socket operation may fail with one of the following errors returned:
759 when trying to establish a connection on a socket which
760 already has one, or when trying to send a datagram with the destination
761 address specified and the socket is already connected;
763 when trying to send a datagram, but
764 no destination address is specified, and the socket has not been
767 when the system runs out of memory for
768 an internal data structure;
769 .It Bq Er EADDRNOTAVAIL
770 when an attempt is made to create a
771 socket with a network address for which no network interface
774 when an attempt is made to create
775 a raw IP socket by a non-privileged process.
778 The following errors specific to
780 may occur when setting or getting
785 An unknown socket option name was given.
787 The IP option field was improperly formed;
788 an option field was shorter than the minimum value
789 or longer than the option buffer provided.
792 The following errors may occur when attempting to send
803 field was not equal to the length of the datagram written to the socket.
820 .%T "Socket Interface Extensions for Multicast Source Filters"
831 structure appeared in