/share/man/man4/ip.4

  1.\" Copyright (c) 1983, 1991, 1993
  2.\"	The Regents of the University of California.  All rights reserved.
  3.\"
  4.\" Redistribution and use in source and binary forms, with or without
  5.\" modification, are permitted provided that the following conditions
  6.\" are met:
  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.
 19.\"
 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
 30.\" SUCH DAMAGE.
 31.\"
 32.\"     @(#)ip.4	8.2 (Berkeley) 11/30/93
 33.\" $FreeBSD$
 34.\"
 35.Dd October 12, 2012
 36.Dt IP 4
 37.Os
 38.Sh NAME
 39.Nm ip
 40.Nd Internet Protocol
 41.Sh SYNOPSIS
 42.In sys/types.h
 43.In sys/socket.h
 44.In netinet/in.h
 45.Ft int
 46.Fn socket AF_INET SOCK_RAW proto
 47.Sh DESCRIPTION
 48.Tn IP
 49is the transport layer protocol used
 50by the Internet protocol family.
 51Options may be set at the
 52.Tn IP
 53level
 54when using higher-level protocols that are based on
 55.Tn IP
 56(such as
 57.Tn TCP
 58and
 59.Tn UDP ) .
 60It may also be accessed
 61through a
 62.Dq raw socket
 63when developing new protocols, or
 64special-purpose applications.
 65.Pp
 66There are several
 67.Tn IP-level
 68.Xr setsockopt 2
 69and
 70.Xr getsockopt 2
 71options.
 72.Dv IP_OPTIONS
 73may be used to provide
 74.Tn IP
 75options to be transmitted in the
 76.Tn IP
 77header of each outgoing packet
 78or to examine the header options on incoming packets.
 79.Tn IP
 80options may be used with any socket type in the Internet family.
 81The format of
 82.Tn IP
 83options to be sent is that specified by the
 84.Tn IP
 85protocol specification (RFC-791), with one exception:
 86the list of addresses for Source Route options must include the first-hop
 87gateway at the beginning of the list of gateways.
 88The first-hop gateway address will be extracted from the option list
 89and the size adjusted accordingly before use.
 90To disable previously specified options,
 91use a zero-length buffer:
 92.Bd -literal
 93setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);
 94.Ed
 95.Pp
 96.Dv IP_TOS
 97and
 98.Dv IP_TTL
 99may be used to set the type-of-service and time-to-live
100fields in the
101.Tn IP
102header for
103.Dv SOCK_STREAM , SOCK_DGRAM ,
104and certain types of
105.Dv SOCK_RAW
106sockets.
107For example,
108.Bd -literal
109int tos = IPTOS_LOWDELAY;       /* see <netinet/ip.h> */
110setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos));
111
112int ttl = 60;                   /* max = 255 */
113setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl));
114.Ed
115.Pp
116.Dv IP_MINTTL
117may be used to set the minimum acceptable TTL a packet must have when
118received on a socket.
119All packets with a lower TTL are silently dropped.
120This option is only really useful when set to 255, preventing packets
121from outside the directly connected networks reaching local listeners
122on sockets.
123.Pp
124.Dv IP_DONTFRAG
125may be used to set the Don't Fragment flag on IP packets.
126Currently this option is respected only on
127.Xr udp 4
128and raw
129.Xr ip 4
130sockets, unless the
131.Dv IP_HDRINCL
132option has been set.
133On
134.Xr tcp 4
135sockets, the Don't Fragment flag is controlled by the Path
136MTU Discovery option.
137Sending a packet larger than the MTU size of the egress interface,
138determined by the destination address, returns an
139.Er EMSGSIZE
140error.
141.Pp
142If the
143.Dv IP_RECVDSTADDR
144option is enabled on a
145.Dv SOCK_DGRAM
146socket,
147the
148.Xr recvmsg 2
149call will return the destination
150.Tn IP
151address for a
152.Tn UDP
153datagram.
154The
155.Vt msg_control
156field in the
157.Vt msghdr
158structure points to a buffer
159that contains a
160.Vt cmsghdr
161structure followed by the
162.Tn IP
163address.
164The
165.Vt cmsghdr
166fields have the following values:
167.Bd -literal
168cmsg_len = CMSG_LEN(sizeof(struct in_addr))
169cmsg_level = IPPROTO_IP
170cmsg_type = IP_RECVDSTADDR
171.Ed
172.Pp
173The source address to be used for outgoing
174.Tn UDP
175datagrams on a socket can be specified as ancillary data with a type code of
176.Dv IP_SENDSRCADDR .
177The msg_control field in the msghdr structure should point to a buffer
178that contains a
179.Vt cmsghdr
180structure followed by the
181.Tn IP
182address.
183The cmsghdr fields should have the following values:
184.Bd -literal
185cmsg_len = CMSG_LEN(sizeof(struct in_addr))
186cmsg_level = IPPROTO_IP
187cmsg_type = IP_SENDSRCADDR
188.Ed
189.Pp
190The socket should be either bound to
191.Dv INADDR_ANY
192and a local port, and the address supplied with
193.Dv IP_SENDSRCADDR
194should't be
195.Dv INADDR_ANY ,
196or the socket should be bound to a local address and the address supplied with
197.Dv IP_SENDSRCADDR
198should be
199.Dv INADDR_ANY .
200In the latter case bound address is overriden via generic source address
201selection logic, which would choose IP address of interface closest to
202destination.
203.Pp
204For convenience,
205.Dv IP_SENDSRCADDR
206is defined to have the same value as
207.Dv IP_RECVDSTADDR ,
208so the
209.Dv IP_RECVDSTADDR
210control message from
211.Xr recvmsg 2
212can be used directly as a control message for
213.Xr sendmsg 2 .
214.\"
215.Pp
216If the
217.Dv IP_ONESBCAST
218option is enabled on a
219.Dv SOCK_DGRAM
220or a
221.Dv SOCK_RAW
222socket, the destination address of outgoing
223broadcast datagrams on that socket will be forced
224to the undirected broadcast address,
225.Dv INADDR_BROADCAST ,
226before transmission.
227This is in contrast to the default behavior of the
228system, which is to transmit undirected broadcasts
229via the first network interface with the
230.Dv IFF_BROADCAST
231flag set.
232.Pp
233This option allows applications to choose which
234interface is used to transmit an undirected broadcast
235datagram.
236For example, the following code would force an
237undirected broadcast to be transmitted via the interface
238configured with the broadcast address 192.168.2.255:
239.Bd -literal
240char msg[512];
241struct sockaddr_in sin;
242int onesbcast = 1;	/* 0 = disable (default), 1 = enable */
243
244setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast));
245sin.sin_addr.s_addr = inet_addr("192.168.2.255");
246sin.sin_port = htons(1234);
247sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin));
248.Ed
249.Pp
250It is the application's responsibility to set the
251.Dv IP_TTL
252option
253to an appropriate value in order to prevent broadcast storms.
254The application must have sufficient credentials to set the
255.Dv SO_BROADCAST
256socket level option, otherwise the
257.Dv IP_ONESBCAST
258option has no effect.
259.Pp
260If the
261.Dv IP_BINDANY
262option is enabled on a
263.Dv SOCK_STREAM ,
264.Dv SOCK_DGRAM
265or a
266.Dv SOCK_RAW
267socket, one can
268.Xr bind 2
269to any address, even one not bound to any available network interface in the
270system.
271This functionality (in conjunction with special firewall rules) can be used for
272implementing a transparent proxy.
273The
274.Dv PRIV_NETINET_BINDANY
275privilege is needed to set this option.
276.Pp
277If the
278.Dv IP_RECVTTL
279option is enabled on a
280.Dv SOCK_DGRAM
281socket, the
282.Xr recvmsg 2
283call will return the
284.Tn IP
285.Tn TTL
286(time to live) field for a
287.Tn UDP
288datagram.
289The msg_control field in the msghdr structure points to a buffer
290that contains a cmsghdr structure followed by the
291.Tn TTL .
292The cmsghdr fields have the following values:
293.Bd -literal
294cmsg_len = CMSG_LEN(sizeof(u_char))
295cmsg_level = IPPROTO_IP
296cmsg_type = IP_RECVTTL
297.Ed
298.\"
299.Pp
300If the
301.Dv IP_RECVTOS
302option is enabled on a
303.Dv SOCK_DGRAM
304socket, the
305.Xr recvmsg 2
306call will return the
307.Tn IP
308.Tn TOS
309(type of service) field for a
310.Tn UDP
311datagram.
312The msg_control field in the msghdr structure points to a buffer
313that contains a cmsghdr structure followed by the
314.Tn TOS .
315The cmsghdr fields have the following values:
316.Bd -literal
317cmsg_len = CMSG_LEN(sizeof(u_char))
318cmsg_level = IPPROTO_IP
319cmsg_type = IP_RECVTOS
320.Ed
321.\"
322.Pp
323If the
324.Dv IP_RECVIF
325option is enabled on a
326.Dv SOCK_DGRAM
327socket, the
328.Xr recvmsg 2
329call returns a
330.Vt "struct sockaddr_dl"
331corresponding to the interface on which the
332packet was received.
333The
334.Va msg_control
335field in the
336.Vt msghdr
337structure points to a buffer that contains a
338.Vt cmsghdr
339structure followed by the
340.Vt "struct sockaddr_dl" .
341The
342.Vt cmsghdr
343fields have the following values:
344.Bd -literal
345cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl))
346cmsg_level = IPPROTO_IP
347cmsg_type = IP_RECVIF
348.Ed
349.Pp
350.Dv IP_PORTRANGE
351may be used to set the port range used for selecting a local port number
352on a socket with an unspecified (zero) port number.
353It has the following
354possible values:
355.Bl -tag -width IP_PORTRANGE_DEFAULT
356.It Dv IP_PORTRANGE_DEFAULT
357use the default range of values, normally
358.Dv IPPORT_HIFIRSTAUTO
359through
360.Dv IPPORT_HILASTAUTO .
361This is adjustable through the sysctl setting:
362.Va net.inet.ip.portrange.first
363and
364.Va net.inet.ip.portrange.last .
365.It Dv IP_PORTRANGE_HIGH
366use a high range of values, normally
367.Dv IPPORT_HIFIRSTAUTO
368and
369.Dv IPPORT_HILASTAUTO .
370This is adjustable through the sysctl setting:
371.Va net.inet.ip.portrange.hifirst
372and
373.Va net.inet.ip.portrange.hilast .
374.It Dv IP_PORTRANGE_LOW
375use a low range of ports, which are normally restricted to
376privileged processes on
377.Ux
378systems.
379The range is normally from
380.Dv IPPORT_RESERVED
381\- 1 down to
382.Li IPPORT_RESERVEDSTART
383in descending order.
384This is adjustable through the sysctl setting:
385.Va net.inet.ip.portrange.lowfirst
386and
387.Va net.inet.ip.portrange.lowlast .
388.El
389.Pp
390The range of privileged ports which only may be opened by
391root-owned processes may be modified by the
392.Va net.inet.ip.portrange.reservedlow
393and
394.Va net.inet.ip.portrange.reservedhigh
395sysctl settings.
396The values default to the traditional range,
3970 through
398.Dv IPPORT_RESERVED
399\- 1
400(0 through 1023), respectively.
401Note that these settings do not affect and are not accounted for in the
402use or calculation of the other
403.Va net.inet.ip.portrange
404values above.
405Changing these values departs from
406.Ux
407tradition and has security
408consequences that the administrator should carefully evaluate before
409modifying these settings.
410.Pp
411Ports are allocated at random within the specified port range in order
412to increase the difficulty of random spoofing attacks.
413In scenarios such as benchmarking, this behavior may be undesirable.
414In these cases,
415.Va net.inet.ip.portrange.randomized
416can be used to toggle randomization off.
417If more than
418.Va net.inet.ip.portrange.randomcps
419ports have been allocated in the last second, then return to sequential
420port allocation.
421Return to random allocation only once the current port allocation rate
422drops below
423.Va net.inet.ip.portrange.randomcps
424for at least
425.Va net.inet.ip.portrange.randomtime
426seconds.
427The default values for
428.Va net.inet.ip.portrange.randomcps
429and
430.Va net.inet.ip.portrange.randomtime
431are 10 port allocations per second and 45 seconds correspondingly.
432.Ss "Multicast Options"
433.Tn IP
434multicasting is supported only on
435.Dv AF_INET
436sockets of type
437.Dv SOCK_DGRAM
438and
439.Dv SOCK_RAW ,
440and only on networks where the interface
441driver supports multicasting.
442.Pp
443The
444.Dv IP_MULTICAST_TTL
445option changes the time-to-live (TTL)
446for outgoing multicast datagrams
447in order to control the scope of the multicasts:
448.Bd -literal
449u_char ttl;	/* range: 0 to 255, default = 1 */
450setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl));
451.Ed
452.Pp
453Datagrams with a TTL of 1 are not forwarded beyond the local network.
454Multicast datagrams with a TTL of 0 will not be transmitted on any network,
455but may be delivered locally if the sending host belongs to the destination
456group and if multicast loopback has not been disabled on the sending socket
457(see below).
458Multicast datagrams with TTL greater than 1 may be forwarded
459to other networks if a multicast router is attached to the local network.
460.Pp
461For hosts with multiple interfaces, where an interface has not
462been specified for a multicast group membership,
463each multicast transmission is sent from the primary network interface.
464The
465.Dv IP_MULTICAST_IF
466option overrides the default for
467subsequent transmissions from a given socket:
468.Bd -literal
469struct in_addr addr;
470setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr));
471.Ed
472.Pp
473where "addr" is the local
474.Tn IP
475address of the desired interface or
476.Dv INADDR_ANY
477to specify the default interface.
478.Pp
479To specify an interface by index, an instance of
480.Vt ip_mreqn
481may be passed instead.
482The
483.Vt imr_ifindex
484member should be set to the index of the desired interface,
485or 0 to specify the default interface.
486The kernel differentiates between these two structures by their size.
487.Pp
488The use of
489.Vt IP_MULTICAST_IF
490is
491.Em not recommended ,
492as multicast memberships are scoped to each
493individual interface.
494It is supported for legacy use only by applications,
495such as routing daemons, which expect to
496be able to transmit link-local IPv4 multicast datagrams (224.0.0.0/24)
497on multiple interfaces,
498without requesting an individual membership for each interface.
499.Pp
500.\"
501An interface's local IP address and multicast capability can
502be obtained via the
503.Dv SIOCGIFCONF
504and
505.Dv SIOCGIFFLAGS
506ioctls.
507Normal applications should not need to use this option.
508.Pp
509If a multicast datagram is sent to a group to which the sending host itself
510belongs (on the outgoing interface), a copy of the datagram is, by default,
511looped back by the IP layer for local delivery.
512The
513.Dv IP_MULTICAST_LOOP
514option gives the sender explicit control
515over whether or not subsequent datagrams are looped back:
516.Bd -literal
517u_char loop;	/* 0 = disable, 1 = enable (default) */
518setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop));
519.Ed
520.Pp
521This option
522improves performance for applications that may have no more than one
523instance on a single host (such as a routing daemon), by eliminating
524the overhead of receiving their own transmissions.
525It should generally not
526be used by applications for which there may be more than one instance on a
527single host (such as a conferencing program) or for which the sender does
528not belong to the destination group (such as a time querying program).
529.Pp
530The sysctl setting
531.Va net.inet.ip.mcast.loop
532controls the default setting of the
533.Dv IP_MULTICAST_LOOP
534socket option for new sockets.
535.Pp
536A multicast datagram sent with an initial TTL greater than 1 may be delivered
537to the sending host on a different interface from that on which it was sent,
538if the host belongs to the destination group on that other interface.
539The loopback control option has no effect on such delivery.
540.Pp
541A host must become a member of a multicast group before it can receive
542datagrams sent to the group.
543To join a multicast group, use the
544.Dv IP_ADD_MEMBERSHIP
545option:
546.Bd -literal
547struct ip_mreq mreq;
548setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq));
549.Ed
550.Pp
551where
552.Fa mreq
553is the following structure:
554.Bd -literal
555struct ip_mreq {
556    struct in_addr imr_multiaddr; /* IP multicast address of group */
557    struct in_addr imr_interface; /* local IP address of interface */
558}
559.Ed
560.Pp
561.Va imr_interface
562should be set to the
563.Tn IP
564address of a particular multicast-capable interface if
565the host is multihomed.
566It may be set to
567.Dv INADDR_ANY
568to choose the default interface, although this is not recommended;
569this is considered to be the first interface corresponding
570to the default route.
571Otherwise, the first multicast-capable interface
572configured in the system will be used.
573.Pp
574Prior to
575.Fx 7.0 ,
576if the
577.Va imr_interface
578member is within the network range
579.Li 0.0.0.0/8 ,
580it is treated as an interface index in the system interface MIB,
581as per the RIP Version 2 MIB Extension (RFC-1724).
582In versions of
583.Fx
584since 7.0, this behavior is no longer supported.
585Developers should
586instead use the RFC 3678 multicast source filter APIs; in particular,
587.Dv MCAST_JOIN_GROUP .
588.Pp
589Up to
590.Dv IP_MAX_MEMBERSHIPS
591memberships may be added on a single socket.
592Membership is associated with a single interface;
593programs running on multihomed hosts may need to
594join the same group on more than one interface.
595.Pp
596To drop a membership, use:
597.Bd -literal
598struct ip_mreq mreq;
599setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
600.Ed
601.Pp
602where
603.Fa mreq
604contains the same values as used to add the membership.
605Memberships are dropped when the socket is closed or the process exits.
606.\" TODO: Update this piece when IPv4 source-address selection is implemented.
607.Pp
608The IGMP protocol uses the primary IP address of the interface
609as its identifier for group membership.
610This is the first IP address configured on the interface.
611If this address is removed or changed, the results are
612undefined, as the IGMP membership state will then be inconsistent.
613If multiple IP aliases are configured on the same interface,
614they will be ignored.
615.Pp
616This shortcoming was addressed in IPv6; MLDv2 requires
617that the unique link-local address for an interface is
618used to identify an MLDv2 listener.
619.Ss "Source-Specific Multicast Options"
620Since
621.Fx 8.0 ,
622the use of Source-Specific Multicast (SSM) is supported.
623These extensions require an IGMPv3 multicast router in order to
624make best use of them.
625If a legacy multicast router is present on the link,
626.Fx
627will simply downgrade to the version of IGMP spoken by the router,
628and the benefits of source filtering on the upstream link
629will not be present, although the kernel will continue to
630squelch transmissions from blocked sources.
631.Pp
632Each group membership on a socket now has a filter mode:
633.Bl -tag -width MCAST_EXCLUDE
634.It Dv MCAST_EXCLUDE
635Datagrams sent to this group are accepted,
636unless the source is in a list of blocked source addresses.
637.It Dv MCAST_INCLUDE
638Datagrams sent to this group are accepted
639only if the source is in a list of accepted source addresses.
640.El
641.Pp
642Groups joined using the legacy
643.Dv IP_ADD_MEMBERSHIP
644option are placed in exclusive-mode,
645and are able to request that certain sources are blocked or allowed.
646This is known as the
647.Em delta-based API .
648.Pp
649To block a multicast source on an existing group membership:
650.Bd -literal
651struct ip_mreq_source mreqs;
652setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs));
653.Ed
654.Pp
655where
656.Fa mreqs
657is the following structure:
658.Bd -literal
659struct ip_mreq_source {
660    struct in_addr imr_multiaddr; /* IP multicast address of group */
661    struct in_addr imr_sourceaddr; /* IP address of source */
662    struct in_addr imr_interface; /* local IP address of interface */
663}
664.Ed
665.Va imr_sourceaddr
666should be set to the address of the source to be blocked.
667.Pp
668To unblock a multicast source on an existing group:
669.Bd -literal
670struct ip_mreq_source mreqs;
671setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs));
672.Ed
673.Pp
674The
675.Dv IP_BLOCK_SOURCE
676and
677.Dv IP_UNBLOCK_SOURCE
678options are
679.Em not permitted
680for inclusive-mode group memberships.
681.Pp
682To join a multicast group in
683.Dv MCAST_INCLUDE
684mode with a single source,
685or add another source to an existing inclusive-mode membership:
686.Bd -literal
687struct ip_mreq_source mreqs;
688setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));
689.Ed
690.Pp
691To leave a single source from an existing group in inclusive mode:
692.Bd -literal
693struct ip_mreq_source mreqs;
694setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));
695.Ed
696If this is the last accepted source for the group, the membership
697will be dropped.
698.Pp
699The
700.Dv IP_ADD_SOURCE_MEMBERSHIP
701and
702.Dv IP_DROP_SOURCE_MEMBERSHIP
703options are
704.Em not accepted
705for exclusive-mode group memberships.
706However, both exclusive and inclusive mode memberships
707support the use of the
708.Em full-state API
709documented in RFC 3678.
710For management of source filter lists using this API,
711please refer to
712.Xr sourcefilter 3 .
713.Pp
714The sysctl settings
715.Va net.inet.ip.mcast.maxsocksrc
716and
717.Va net.inet.ip.mcast.maxgrpsrc
718are used to specify an upper limit on the number of per-socket and per-group
719source filter entries which the kernel may allocate.
720.\"-----------------------
721.Ss "Raw IP Sockets"
722Raw
723.Tn IP
724sockets are connectionless,
725and are normally used with the
726.Xr sendto 2
727and
728.Xr recvfrom 2
729calls, though the
730.Xr connect 2
731call may also be used to fix the destination for future
732packets (in which case the
733.Xr read 2
734or
735.Xr recv 2
736and
737.Xr write 2
738or
739.Xr send 2
740system calls may be used).
741.Pp
742If
743.Fa proto
744is 0, the default protocol
745.Dv IPPROTO_RAW
746is used for outgoing
747packets, and only incoming packets destined for that protocol
748are received.
749If
750.Fa proto
751is non-zero, that protocol number will be used on outgoing packets
752and to filter incoming packets.
753.Pp
754Outgoing packets automatically have an
755.Tn IP
756header prepended to
757them (based on the destination address and the protocol
758number the socket is created with),
759unless the
760.Dv IP_HDRINCL
761option has been set.
762Incoming packets are received with
763.Tn IP
764header and options intact, except for
765.Va ip_len
766and
767.Va ip_off
768fields converted to host byte order.
769.Pp
770.Dv IP_HDRINCL
771indicates the complete IP header is included with the data
772and may be used only with the
773.Dv SOCK_RAW
774type.
775.Bd -literal
776#include <netinet/in_systm.h>
777#include <netinet/ip.h>
778
779int hincl = 1;                  /* 1 = on, 0 = off */
780setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl));
781.Ed
782.Pp
783Unlike previous
784.Bx
785releases, the program must set all
786the fields of the IP header, including the following:
787.Bd -literal
788ip->ip_v = IPVERSION;
789ip->ip_hl = hlen >> 2;
790ip->ip_id = 0;  /* 0 means kernel set appropriate value */
791ip->ip_off = offset;
792.Ed
793.Pp
794The
795.Va ip_len
796and
797.Va ip_off
798fields
799.Em must
800be provided in host byte order.
801All other fields must be provided in network byte order.
802See
803.Xr byteorder 3
804for more information on network byte order.
805If the
806.Va ip_id
807field is set to 0 then the kernel will choose an
808appropriate value.
809If the header source address is set to
810.Dv INADDR_ANY ,
811the kernel will choose an appropriate address.
812.Sh ERRORS
813A socket operation may fail with one of the following errors returned:
814.Bl -tag -width Er
815.It Bq Er EISCONN
816when trying to establish a connection on a socket which
817already has one, or when trying to send a datagram with the destination
818address specified and the socket is already connected;
819.It Bq Er ENOTCONN
820when trying to send a datagram, but
821no destination address is specified, and the socket has not been
822connected;
823.It Bq Er ENOBUFS
824when the system runs out of memory for
825an internal data structure;
826.It Bq Er EADDRNOTAVAIL
827when an attempt is made to create a
828socket with a network address for which no network interface
829exists.
830.It Bq Er EACCES
831when an attempt is made to create
832a raw IP socket by a non-privileged process.
833.El
834.Pp
835The following errors specific to
836.Tn IP
837may occur when setting or getting
838.Tn IP
839options:
840.Bl -tag -width Er
841.It Bq Er EINVAL
842An unknown socket option name was given.
843.It Bq Er EINVAL
844The IP option field was improperly formed;
845an option field was shorter than the minimum value
846or longer than the option buffer provided.
847.El
848.Pp
849The following errors may occur when attempting to send
850.Tn IP
851datagrams via a
852.Dq raw socket
853with the
854.Dv IP_HDRINCL
855option set:
856.Bl -tag -width Er
857.It Bq Er EINVAL
858The user-supplied
859.Va ip_len
860field was not equal to the length of the datagram written to the socket.
861.El
862.Sh SEE ALSO
863.Xr getsockopt 2 ,
864.Xr recv 2 ,
865.Xr send 2 ,
866.Xr byteorder 3 ,
867.Xr icmp 4 ,
868.Xr igmp 4 ,
869.Xr inet 4 ,
870.Xr intro 4 ,
871.Xr multicast 4 ,
872.Xr sourcefilter 3
873.Rs
874.%A D. Thaler
875.%A B. Fenner
876.%A B. Quinn
877.%T "Socket Interface Extensions for Multicast Source Filters"
878.%N RFC 3678
879.%D Jan 2004
880.Re
881.Sh HISTORY
882The
883.Nm
884protocol appeared in
885.Bx 4.2 .
886The
887.Vt ip_mreqn
888structure appeared in
889.Tn Linux 2.4 .
890.Sh BUGS
891Before
892.Fx 10.0
893packets received on raw IP sockets had the
894.Va ip_hl
895subtracted from the
896.Va ip_len
897field.