mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-20 11:11:24 +00:00
edf0e5b3f8
man pages up to mdoc guidelines and fix some minor formatting glitches. Also fixed a number of man pages to not abuse the .Xr macro to display functions and path names and a lot of other junk.
414 lines
12 KiB
Groff
414 lines
12 KiB
Groff
.\" 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
|
|
and
|
|
.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 2
|
|
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
|
|
.Pp
|
|
.Dv IP_PORTRANGE
|
|
may be used to set the port range used for selecting a local port number
|
|
on a socket with an unspecified (zero) port number. It has the following
|
|
possible values:
|
|
.Bl -tag -width IP_PORTRANGE_DEFAULT
|
|
.It Dv IP_PORTRANGE_DEFAULT
|
|
use the default range of values, normally
|
|
.Dv IPPORT_RESERVED
|
|
through
|
|
.Dv IPPORT_RESERVED .
|
|
This is adjustable through the sysctl setting:
|
|
.Nm net.inet.ip.portrange.first
|
|
and
|
|
.Nm net.inet.ip.portrange.last .
|
|
.It Dv IP_PORTRANGE_HIGH
|
|
use a high range of values, normally
|
|
.Dv IPPORT_HIFIRSTAUTO
|
|
and
|
|
.Dv IPPORT_HILASTAUTO .
|
|
This is adjustable through the sysctl setting:
|
|
.Nm net.inet.ip.portrange.hifirst
|
|
and
|
|
.Nm net.inet.ip.portrange.hilast .
|
|
.It Dv IP_PORTRANGE_LOW
|
|
use a low range of ports, which are normally restricted to
|
|
privileged processes on
|
|
.Ux
|
|
systems. The range is normally from
|
|
.Dv IPPORT_RESERVED
|
|
down to
|
|
.Li 1
|
|
in descending order. This range is not sysctl configurable.
|
|
.El
|
|
.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 2
|
|
and
|
|
.Xr recvfrom 2
|
|
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 .
|