diff options
Diffstat (limited to 'share/man/man4/ip.4')
| -rw-r--r-- | share/man/man4/ip.4 | 380 |
1 files changed, 380 insertions, 0 deletions
diff --git a/share/man/man4/ip.4 b/share/man/man4/ip.4 new file mode 100644 index 00000000000..cfb7cfdf7c7 --- /dev/null +++ b/share/man/man4/ip.4 @@ -0,0 +1,380 @@ +.\" $NetBSD: ip.4,v 1.3 1994/11/30 16:22:19 jtc Exp $ +.\" +.\" 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 . |