BSD 4.4 Lite Share Sources

1 files changed, 378 insertions, 0 deletions

diff --git a/share/man/man4/ip.4 b/share/man/man4/ip.4
new file mode 100644
index 0000000..0f95c4b
--- /dev/null
+++ b/share/man/man4/ip.4
@@ -0,0 +1,378 @@
+.\" Copyright (c) 1983, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)ip.4	8.2 (Berkeley) 11/30/93
+.\"
+.Dd November 30, 1993
+.Dt IP 4
+.Os BSD 4.2
+.Sh NAME
+.Nm ip
+.Nd Internet Protocol
+.Sh SYNOPSIS
+.Fd #include <sys/socket.h>
+.Fd #include <netinet/in.h>
+.Ft int
+.Fn socket AF_INET SOCK_RAW proto
+.Sh DESCRIPTION
+.Tn IP 
+is the transport layer protocol used
+by the Internet protocol family.
+Options may be set at the
+.Tn IP
+level
+when using higher-level protocols that are based on
+.Tn IP
+(such as
+.Tn TCP
+and
+.Tn UDP ) .
+It may also be accessed
+through a
+.Dq raw socket
+when developing new protocols, or
+special-purpose applications.
+.Pp
+There are several
+.Tn IP-level
+.Xr setsockopt 2 / Ns
+.Xr getsockopt 2
+options.
+.Dv IP_OPTIONS 
+may be used to provide
+.Tn IP
+options to be transmitted in the
+.Tn IP
+header of each outgoing packet
+or to examine the header options on incoming packets.
+.Tn IP
+options may be used with any socket type in the Internet family.
+The format of
+.Tn IP
+options to be sent is that specified by the
+.Tn IP 
+protocol specification (RFC-791), with one exception:
+the list of addresses for Source Route options must include the first-hop
+gateway at the beginning of the list of gateways.
+The first-hop gateway address will be extracted from the option list
+and the size adjusted accordingly before use.
+To disable previously specified options,
+use a zero-length buffer:
+.Bd -literal
+setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);
+.Ed
+.Pp
+.Dv IP_TOS 
+and 
+.Dv IP_TTL 
+may be used to set the type-of-service and time-to-live
+fields in the 
+.Tn IP 
+header for 
+.Dv SOCK_STREAM 
+and 
+.Dv SOCK_DGRAM 
+sockets. For example,
+.Bd -literal
+int tos = IPTOS_LOWDELAY;       /* see <netinet/in.h> */
+setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos));
+
+int ttl = 60;                   /* max = 255 */
+setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl));
+.Ed
+.Pp
+If the 
+.Dv IP_RECVDSTADDR 
+option is enabled on a 
+.Dv SOCK_DGRAM 
+socket,
+the
+.Xr recvmsg
+call will return the destination 
+.Tn IP 
+address for a 
+.Tn UDP 
+datagram. 
+The msg_control field in the msghdr structure points to a buffer 
+that contains a cmsghdr structure followed by the 
+.Tn IP 
+address. 
+The cmsghdr fields have the following values:
+.Bd -literal
+cmsg_len = sizeof(struct in_addr)
+cmsg_level = IPPROTO_IP
+cmsg_type = IP_RECVDSTADDR
+.Ed
+.Ss "Multicast Options"
+.Pp
+.Tn IP 
+multicasting is supported only on 
+.Dv AF_INET 
+sockets of type
+.Dv SOCK_DGRAM 
+and 
+.Dv SOCK_RAW,
+and only on networks where the interface
+driver supports multicasting.
+.Pp
+The 
+.Dv IP_MULTICAST_TTL 
+option changes the time-to-live (TTL)
+for outgoing multicast datagrams
+in order to control the scope of the multicasts:
+.Bd -literal
+u_char ttl;	/* range: 0 to 255, default = 1 */
+setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl));
+.Ed
+.sp
+Datagrams with a TTL of 1 are not forwarded beyond the local network.
+Multicast datagrams with a TTL of 0 will not be transmitted on any network,
+but may be delivered locally if the sending host belongs to the destination
+group and if multicast loopback has not been disabled on the sending socket
+(see below).  Multicast datagrams with TTL greater than 1 may be forwarded
+to other networks if a multicast router is attached to the local network.
+.Pp
+For hosts with multiple interfaces, each multicast transmission is 
+sent from the primary network interface.
+The 
+.Dv IP_MULTICAST_IF 
+option overrides the default for 
+subsequent transmissions from a given socket:
+.Bd -literal
+struct in_addr addr;
+setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr));
+.Ed
+.sp
+where "addr" is the local 
+.Tn IP 
+address of the desired interface or
+.Dv INADDR_ANY 
+to specify the default interface.
+An interface's local IP address and multicast capability can 
+be obtained via the 
+.Dv SIOCGIFCONF 
+and 
+.Dv SIOCGIFFLAGS 
+ioctls. 
+Normal applications should not need to use this option.
+.Pp
+If a multicast datagram is sent to a group to which the sending host itself
+belongs (on the outgoing interface), a copy of the datagram is, by default,
+looped back by the IP layer for local delivery. 
+The 
+.Dv IP_MULTICAST_LOOP 
+option gives the sender explicit control 
+over whether or not subsequent datagrams are looped back:
+.Bd -literal
+u_char loop;	/* 0 = disable, 1 = enable (default) */
+setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop));
+.Ed
+.sp
+This option
+improves performance for applications that may have no more than one
+instance on a single host (such as a router demon), by eliminating
+the overhead of receiving their own transmissions.  It should generally not
+be used by applications for which there may be more than one instance on a
+single host (such as a conferencing program) or for which the sender does
+not belong to the destination group (such as a time querying program).
+.Pp
+A multicast datagram sent with an initial TTL greater than 1 may be delivered
+to the sending host on a different interface from that on which it was sent,
+if the host belongs to the destination group on that other interface.  The
+loopback control option has no effect on such delivery.
+.Pp
+A host must become a member of a multicast group before it can receive 
+datagrams sent to the group.  To join a multicast group, use the 
+.Dv IP_ADD_MEMBERSHIP 
+option:
+.Bd -literal
+struct ip_mreq mreq;
+setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq));
+.Ed
+.sp
+where 
+.Fa mreq
+is the following structure:
+.Bd -literal
+struct ip_mreq {
+    struct in_addr imr_multiaddr; /* multicast group to join */
+    struct in_addr imr_interface; /* interface to join on */
+}
+.Ed
+.sp
+.Dv imr_interface 
+should
+be 
+.Dv INADDR_ANY 
+to choose the default multicast interface, 
+or the 
+.Tn IP 
+address of a particular multicast-capable interface if
+the host is multihomed.
+Membership is associated with a single interface; 
+programs running on multihomed hosts may need to 
+join the same group on more than one interface.  
+Up to 
+.Dv IP_MAX_MEMBERSHIPS 
+(currently 20) memberships may be added on a
+single socket.
+.Pp
+To drop a membership, use:
+.Bd -literal
+struct ip_mreq mreq;
+setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
+.Ed
+.sp
+where 
+.Fa mreq
+contains the same values as used to add the membership. 
+Memberships are dropped when the socket is closed or the process exits.  
+.\"-----------------------
+.Ss "Raw IP Sockets"
+.Pp
+Raw
+.Tn IP
+sockets are connectionless,
+and are normally used with the
+.Xr sendto
+and
+.Xr recvfrom
+calls, though the
+.Xr connect 2
+call may also be used to fix the destination for future
+packets (in which case the 
+.Xr read 2
+or
+.Xr recv 2
+and 
+.Xr write 2
+or
+.Xr send 2
+system calls may be used).
+.Pp
+If
+.Fa proto
+is 0, the default protocol
+.Dv IPPROTO_RAW
+is used for outgoing
+packets, and only incoming packets destined for that protocol
+are received.
+If
+.Fa proto
+is non-zero, that protocol number will be used on outgoing packets
+and to filter incoming packets.
+.Pp
+Outgoing packets automatically have an
+.Tn IP
+header prepended to
+them (based on the destination address and the protocol
+number the socket is created with),
+unless the 
+.Dv IP_HDRINCL 
+option has been set.
+Incoming packets are received with
+.Tn IP
+header and options intact.
+.Pp
+.Dv IP_HDRINCL 
+indicates the complete IP header is included with the data
+and may be used only with the 
+.Dv SOCK_RAW 
+type.
+.Bd -literal
+#include <netinet/ip.h>
+
+int hincl = 1;                  /* 1 = on, 0 = off */
+setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl));
+.Ed
+.sp
+Unlike previous 
+.Tn BSD 
+releases, the program must set all
+the fields of the IP header, including the following:
+.Bd -literal
+ip->ip_v = IPVERSION;
+ip->ip_hl = hlen >> 2;
+ip->ip_id = 0;  /* 0 means kernel set appropriate value */
+ip->ip_off = offset;
+.Ed
+.sp .5
+If the header source address is set to 
+.Dv INADDR_ANY,
+the kernel will choose an appropriate address.
+.Sh DIAGNOSTICS
+A socket operation may fail with one of the following errors returned:
+.Bl -tag -width [EADDRNOTAVAIL]
+.It Bq Er EISCONN
+when trying to establish a connection on a socket which
+already has one, or when trying to send a datagram with the destination
+address specified and the socket is already connected;
+.It Bq Er ENOTCONN
+when trying to send a datagram, but
+no destination address is specified, and the socket hasn't been
+connected;
+.It Bq Er ENOBUFS
+when the system runs out of memory for
+an internal data structure;
+.It Bq Er EADDRNOTAVAIL
+when an attempt is made to create a 
+socket with a network address for which no network interface
+exists.
+.It Bq Er EACESS
+when an attempt is made to create
+a raw IP socket by a non-privileged process.
+.El
+.Pp
+The following errors specific to
+.Tn IP
+may occur when setting or getting
+.Tn IP
+options:
+.Bl -tag -width EADDRNOTAVAILxx
+.It Bq Er EINVAL
+An unknown socket option name was given.
+.It Bq Er EINVAL
+The IP option field was improperly formed;
+an option field was shorter than the minimum value
+or longer than the option buffer provided.
+.El
+.Sh SEE ALSO
+.Xr getsockopt 2 ,
+.Xr send 2 ,
+.Xr recv 2 ,
+.Xr intro 4 ,
+.Xr icmp 4 ,
+.Xr inet 4
+.Sh HISTORY
+The
+.Nm
+protocol appeared in
+.Bx 4.2 .