Many pages: Fix style issues reported by `make lint-groff`

[thirdparty/man-pages.git] / man7 / ip.7

.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
.\"
.\" %%%LICENSE_START(VERBATIM_ONE_PARA)
.\" Permission is granted to distribute possibly modified copies
.\" of this page provided the header is included verbatim,
.\" and in case of nontrivial modification author and date
.\" of the modification is added to the header.
.\" %%%LICENSE_END
.\"
.\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $
.\"
.\" FIXME The following socket options are yet to be documented
.\"
.\" 	IP_XFRM_POLICY (2.5.48)
.\"	    Needs CAP_NET_ADMIN
.\"
.\" 	IP_IPSEC_POLICY (2.5.47)
.\"	    Needs CAP_NET_ADMIN
.\"
.\"	IP_MINTTL (2.6.34)
.\"	    commit d218d11133d888f9745802146a50255a4781d37a
.\"	    Author: Stephen Hemminger <shemminger@vyatta.com>
.\"
.\"	MCAST_JOIN_GROUP (2.4.22 / 2.6)
.\"
.\"	MCAST_BLOCK_SOURCE (2.4.22 / 2.6)
.\"
.\"	MCAST_UNBLOCK_SOURCE (2.4.22 / 2.6)
.\"
.\"	MCAST_LEAVE_GROUP (2.4.22 / 2.6)
.\"
.\"	MCAST_JOIN_SOURCE_GROUP (2.4.22 / 2.6)
.\"
.\"	MCAST_LEAVE_SOURCE_GROUP (2.4.22 / 2.6)
.\"
.\"	MCAST_MSFILTER (2.4.22 / 2.6)
.\"
.\"	IP_UNICAST_IF (3.4)
.\"	    commit 76e21053b5bf33a07c76f99d27a74238310e3c71
.\"	    Author: Erich E. Hoover <ehoover@mines.edu>
.\"
.TH IP  7 2021-03-22 "Linux" "Linux Programmer's Manual"
.SH NAME
ip \- Linux IPv4 protocol implementation
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
.\" .B #include <net/netinet.h> -- does not exist anymore
.\" .B #include <linux/errqueue.h> -- never include <linux/foo.h>
.B #include <netinet/in.h>
.B #include <netinet/ip.h>        \fR/* superset of previous */
.PP
.IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);"
.IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);"
.IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");"
.fi
.SH DESCRIPTION
Linux implements the Internet Protocol, version 4,
described in RFC\ 791 and RFC\ 1122.
.B ip
contains a level 2 multicasting implementation conforming to RFC\ 1112.
It also contains an IP router including a packet filter.
.PP
The programming interface is BSD-sockets compatible.
For more information on sockets, see
.BR socket (7).
.PP
An IP socket is created using
.BR socket (2):
.PP
.in +4n
.EX
socket(AF_INET, socket_type, protocol);
.EE
.in
.PP
Valid socket types include
.B SOCK_STREAM
to open a stream socket,
.B SOCK_DGRAM
to open a datagram socket, and
.B SOCK_RAW
to open a
.BR raw (7)
socket to access the IP protocol directly.
.PP
.I protocol
is the IP protocol in the IP header to be received or sent.
Valid values for
.I protocol
include:
.IP \(bu 2
0 and
.B IPPROTO_TCP
for
.BR tcp (7)
stream sockets;
.IP \(bu
0 and
.B IPPROTO_UDP
for
.BR udp (7)
datagram sockets;
.IP \(bu
.B IPPROTO_SCTP
for
.BR sctp (7)
stream sockets; and
.IP \(bu
.B IPPROTO_UDPLITE
for
.BR udplite (7)
datagram sockets.
.PP
For
.B SOCK_RAW
you may specify a valid IANA IP protocol defined in
RFC\ 1700 assigned numbers.
.PP
When a process wants to receive new incoming packets or connections, it
should bind a socket to a local interface address using
.BR bind (2).
In this case, only one IP socket may be bound to any given local
(address, port) pair.
When
.B INADDR_ANY
is specified in the bind call, the socket will be bound to
.I all
local interfaces.
When
.BR listen (2)
is called on an unbound socket, the socket is automatically bound
to a random free port with the local address set to
.BR INADDR_ANY .
When
.BR connect (2)
is called on an unbound socket, the socket is automatically bound
to a random free port or to a usable shared port with the local address
set to
.BR INADDR_ANY .
.PP
A TCP local socket address that has been bound is unavailable for
some time after closing, unless the
.B SO_REUSEADDR
flag has been set.
Care should be taken when using this flag as it makes TCP less reliable.
.SS Address format
An IP socket address is defined as a combination of an IP interface
address and a 16-bit port number.
The basic IP protocol does not supply port numbers, they
are implemented by higher level protocols like
.BR udp (7)
and
.BR tcp (7).
On raw sockets
.I sin_port
is set to the IP protocol.
.PP
.in +4n
.EX
struct sockaddr_in {
    sa_family_t    sin_family; /* address family: AF_INET */
    in_port_t      sin_port;   /* port in network byte order */
    struct in_addr sin_addr;   /* internet address */
};

/* Internet address */
struct in_addr {
    uint32_t       s_addr;     /* address in network byte order */
};
.EE
.in
.PP
.I sin_family
is always set to
.BR AF_INET .
This is required; in Linux 2.2 most networking functions return
.B EINVAL
when this setting is missing.
.I sin_port
contains the port in network byte order.
The port numbers below 1024 are called
.I privileged ports
(or sometimes:
.IR "reserved ports" ).
Only a privileged process
(on Linux: a process that has the
.B CAP_NET_BIND_SERVICE
capability in the user namespace governing its network namespace) may
.BR bind (2)
to these sockets.
Note that the raw IPv4 protocol as such has no concept of a
port, they are implemented only by higher protocols like
.BR tcp (7)
and
.BR udp (7).
.PP
.I sin_addr
is the IP host address.
The
.I s_addr
member of
.I struct in_addr
contains the host interface address in network byte order.
.I in_addr
should be assigned one of the
.B INADDR_*
values
(e.g.,
.BR INADDR_LOOPBACK )
using
.BR htonl (3)
or set using the
.BR inet_aton (3),
.BR inet_addr (3),
.BR inet_makeaddr (3)
library functions or directly with the name resolver (see
.BR gethostbyname (3)).
.PP
IPv4 addresses are divided into unicast, broadcast,
and multicast addresses.
Unicast addresses specify a single interface of a host,
broadcast addresses specify all hosts on a network, and multicast
addresses address all hosts in a multicast group.
Datagrams to broadcast addresses can be sent or received only when the
.B SO_BROADCAST
socket flag is set.
In the current implementation, connection-oriented sockets are allowed
to use only unicast addresses.
.\" Leave a loophole for XTP @)
.PP
Note that the address and the port are always stored in
network byte order.
In particular, this means that you need to call
.BR htons (3)
on the number that is assigned to a port.
All address/port manipulation
functions in the standard library work in network byte order.
.PP
There are several special addresses:
.B INADDR_LOOPBACK
(127.0.0.1)
always refers to the local host via the loopback device;
.B INADDR_ANY
(0.0.0.0)
means any address for binding;
.B INADDR_BROADCAST
(255.255.255.255)
means any host and has the same effect on bind as
.B INADDR_ANY
for historical reasons.
.SS Socket options
IP supports some protocol-specific socket options that can be set with
.BR setsockopt (2)
and read with
.BR getsockopt (2).
The socket option level for IP is
.BR IPPROTO_IP .
.\" or SOL_IP on Linux
A boolean integer flag is zero when it is false, otherwise true.
.PP
When an invalid socket option is specified,
.BR getsockopt (2)
and
.BR setsockopt (2)
fail with the error
.BR ENOPROTOOPT .
.TP