]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
7c4ddad1 | 2 | .\" SPDX-License-Identifier: Linux-man-pages-1-para |
2297bf0e | 3 | .\" |
7c4ddad1 | 4 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. |
6a717e5e | 5 | .\" |
77117f4f | 6 | .\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $ |
3ac83a00 | 7 | .\" |
bea08fec | 8 | .\" FIXME The following socket options are yet to be documented |
2c596bf5 | 9 | .\" |
f645fea8 MK |
10 | .\" IP_XFRM_POLICY (2.5.48) |
11 | .\" Needs CAP_NET_ADMIN | |
2c596bf5 | 12 | .\" |
f645fea8 MK |
13 | .\" IP_IPSEC_POLICY (2.5.47) |
14 | .\" Needs CAP_NET_ADMIN | |
2c596bf5 | 15 | .\" |
f645fea8 MK |
16 | .\" IP_MINTTL (2.6.34) |
17 | .\" commit d218d11133d888f9745802146a50255a4781d37a | |
18 | .\" Author: Stephen Hemminger <shemminger@vyatta.com> | |
2c596bf5 | 19 | .\" |
f645fea8 | 20 | .\" MCAST_JOIN_GROUP (2.4.22 / 2.6) |
2c596bf5 | 21 | .\" |
f645fea8 | 22 | .\" MCAST_BLOCK_SOURCE (2.4.22 / 2.6) |
2c596bf5 | 23 | .\" |
f645fea8 | 24 | .\" MCAST_UNBLOCK_SOURCE (2.4.22 / 2.6) |
2c596bf5 | 25 | .\" |
f645fea8 | 26 | .\" MCAST_LEAVE_GROUP (2.4.22 / 2.6) |
2c596bf5 | 27 | .\" |
f645fea8 | 28 | .\" MCAST_JOIN_SOURCE_GROUP (2.4.22 / 2.6) |
2c596bf5 | 29 | .\" |
f645fea8 | 30 | .\" MCAST_LEAVE_SOURCE_GROUP (2.4.22 / 2.6) |
2c596bf5 | 31 | .\" |
f645fea8 | 32 | .\" MCAST_MSFILTER (2.4.22 / 2.6) |
2c596bf5 | 33 | .\" |
f645fea8 MK |
34 | .\" IP_UNICAST_IF (3.4) |
35 | .\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71 | |
36 | .\" Author: Erich E. Hoover <ehoover@mines.edu> | |
3ac83a00 | 37 | .\" |
4c1c5274 | 38 | .TH ip 7 (date) "Linux man-pages (unreleased)" |
77117f4f MK |
39 | .SH NAME |
40 | ip \- Linux IPv4 protocol implementation | |
41 | .SH SYNOPSIS | |
c7db92b9 | 42 | .nf |
77117f4f | 43 | .B #include <sys/socket.h> |
77117f4f MK |
44 | .\" .B #include <net/netinet.h> -- does not exist anymore |
45 | .\" .B #include <linux/errqueue.h> -- never include <linux/foo.h> | |
46 | .B #include <netinet/in.h> | |
77117f4f | 47 | .B #include <netinet/ip.h> \fR/* superset of previous */ |
c6d039a3 | 48 | .P |
d4c8c97c | 49 | .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" |
d4c8c97c | 50 | .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" |
d4c8c97c | 51 | .IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");" |
c7db92b9 | 52 | .fi |
77117f4f MK |
53 | .SH DESCRIPTION |
54 | Linux implements the Internet Protocol, version 4, | |
55 | described in RFC\ 791 and RFC\ 1122. | |
56 | .B ip | |
119a1824 | 57 | contains a level 2 multicasting implementation conforming to RFC\ 1112. |
77117f4f | 58 | It also contains an IP router including a packet filter. |
c6d039a3 | 59 | .P |
02f63637 | 60 | The programming interface is BSD-sockets compatible. |
77117f4f MK |
61 | For more information on sockets, see |
62 | .BR socket (7). | |
c6d039a3 | 63 | .P |
38fdd3bb MK |
64 | An IP socket is created using |
65 | .BR socket (2): | |
c6d039a3 | 66 | .P |
1ae6b2c7 AC |
67 | .in +4n |
68 | .EX | |
69 | socket(AF_INET, socket_type, protocol); | |
70 | .EE | |
71 | .in | |
c6d039a3 | 72 | .P |
d8833593 | 73 | Valid socket types include |
77117f4f | 74 | .B SOCK_STREAM |
d8833593 | 75 | to open a stream socket, |
77117f4f | 76 | .B SOCK_DGRAM |
d8833593 | 77 | to open a datagram socket, and |
77117f4f MK |
78 | .B SOCK_RAW |
79 | to open a | |
80 | .BR raw (7) | |
81 | socket to access the IP protocol directly. | |
c6d039a3 | 82 | .P |
77117f4f MK |
83 | .I protocol |
84 | is the IP protocol in the IP header to be received or sent. | |
d8833593 | 85 | Valid values for |
77117f4f | 86 | .I protocol |
d8833593 | 87 | include: |
cdede5cd | 88 | .IP \[bu] 3 |
d8833593 | 89 | 0 and |
77117f4f | 90 | .B IPPROTO_TCP |
d8833593 MK |
91 | for |
92 | .BR tcp (7) | |
93 | stream sockets; | |
cdede5cd | 94 | .IP \[bu] |
d8833593 | 95 | 0 and |
77117f4f | 96 | .B IPPROTO_UDP |
d8833593 MK |
97 | for |
98 | .BR udp (7) | |
99 | datagram sockets; | |
cdede5cd | 100 | .IP \[bu] |
d8833593 MK |
101 | .B IPPROTO_SCTP |
102 | for | |
103 | .BR sctp (7) | |
104 | stream sockets; and | |
cdede5cd | 105 | .IP \[bu] |
d8833593 MK |
106 | .B IPPROTO_UDPLITE |
107 | for | |
108 | .BR udplite (7) | |
109 | datagram sockets. | |
c6d039a3 | 110 | .P |
77117f4f MK |
111 | For |
112 | .B SOCK_RAW | |
119a1824 MK |
113 | you may specify a valid IANA IP protocol defined in |
114 | RFC\ 1700 assigned numbers. | |
c6d039a3 | 115 | .P |
77117f4f MK |
116 | When a process wants to receive new incoming packets or connections, it |
117 | should bind a socket to a local interface address using | |
118 | .BR bind (2). | |
0a03fceb FL |
119 | In this case, only one IP socket may be bound to any given local |
120 | (address, port) pair. | |
77117f4f MK |
121 | When |
122 | .B INADDR_ANY | |
f971627f | 123 | is specified in the bind call, the socket will be bound to |
77117f4f MK |
124 | .I all |
125 | local interfaces. | |
126 | When | |
127 | .BR listen (2) | |
0a03fceb FL |
128 | is called on an unbound socket, the socket is automatically bound |
129 | to a random free port with the local address set to | |
130 | .BR INADDR_ANY . | |
131 | When | |
77117f4f | 132 | .BR connect (2) |
0a03fceb | 133 | is called on an unbound socket, the socket is automatically bound |
c534b25d | 134 | to a random free port or to a usable shared port with the local address |
0a03fceb | 135 | set to |
77117f4f | 136 | .BR INADDR_ANY . |
c6d039a3 | 137 | .P |
77117f4f | 138 | A TCP local socket address that has been bound is unavailable for |
119a1824 | 139 | some time after closing, unless the |
77117f4f MK |
140 | .B SO_REUSEADDR |
141 | flag has been set. | |
119a1824 | 142 | Care should be taken when using this flag as it makes TCP less reliable. |
c634028a | 143 | .SS Address format |
77117f4f MK |
144 | An IP socket address is defined as a combination of an IP interface |
145 | address and a 16-bit port number. | |
146 | The basic IP protocol does not supply port numbers, they | |
147 | are implemented by higher level protocols like | |
148 | .BR udp (7) | |
149 | and | |
150 | .BR tcp (7). | |
151 | On raw sockets | |
152 | .I sin_port | |
153 | is set to the IP protocol. | |
c6d039a3 | 154 | .P |
77117f4f | 155 | .in +4n |
b8302363 | 156 | .EX |
77117f4f MK |
157 | struct sockaddr_in { |
158 | sa_family_t sin_family; /* address family: AF_INET */ | |
4fa50d72 | 159 | in_port_t sin_port; /* port in network byte order */ |
77117f4f MK |
160 | struct in_addr sin_addr; /* internet address */ |
161 | }; | |
fe5dba13 | 162 | \& |
c2e81ff9 | 163 | /* Internet address */ |
77117f4f MK |
164 | struct in_addr { |
165 | uint32_t s_addr; /* address in network byte order */ | |
166 | }; | |
b8302363 | 167 | .EE |
77117f4f | 168 | .in |
c6d039a3 | 169 | .P |
77117f4f MK |
170 | .I sin_family |
171 | is always set to | |
172 | .BR AF_INET . | |
173 | This is required; in Linux 2.2 most networking functions return | |
174 | .B EINVAL | |
175 | when this setting is missing. | |
176 | .I sin_port | |
177 | contains the port in network byte order. | |
178 | The port numbers below 1024 are called | |
1ae6b2c7 | 179 | .I privileged ports |
6eb334b2 MK |
180 | (or sometimes: |
181 | .IR "reserved ports" ). | |
ed1ba8a5 MK |
182 | Only a privileged process |
183 | (on Linux: a process that has the | |
77117f4f | 184 | .B CAP_NET_BIND_SERVICE |
ed1ba8a5 | 185 | capability in the user namespace governing its network namespace) may |
77117f4f MK |
186 | .BR bind (2) |
187 | to these sockets. | |
188 | Note that the raw IPv4 protocol as such has no concept of a | |
33a0ccb2 | 189 | port, they are implemented only by higher protocols like |
77117f4f MK |
190 | .BR tcp (7) |
191 | and | |
192 | .BR udp (7). | |
c6d039a3 | 193 | .P |
77117f4f MK |
194 | .I sin_addr |
195 | is the IP host address. | |
196 | The | |
197 | .I s_addr | |
198 | member of | |
199 | .I struct in_addr | |
200 | contains the host interface address in network byte order. | |
201 | .I in_addr | |
e89c8911 | 202 | should be assigned one of the |
1ae6b2c7 | 203 | .B INADDR_* |
c0a0e532 RBP |
204 | values |
205 | (e.g., | |
5d0ea688 | 206 | .BR INADDR_LOOPBACK ) |
c0a0e532 RBP |
207 | using |
208 | .BR htonl (3) | |
77117f4f MK |
209 | or set using the |
210 | .BR inet_aton (3), | |
211 | .BR inet_addr (3), | |
212 | .BR inet_makeaddr (3) | |
213 | library functions or directly with the name resolver (see | |
214 | .BR gethostbyname (3)). | |
c6d039a3 | 215 | .P |
173fa792 | 216 | IPv4 addresses are divided into unicast, broadcast, |
77117f4f MK |
217 | and multicast addresses. |
218 | Unicast addresses specify a single interface of a host, | |
173fa792 | 219 | broadcast addresses specify all hosts on a network, and multicast |
77117f4f | 220 | addresses address all hosts in a multicast group. |
33a0ccb2 | 221 | Datagrams to broadcast addresses can be sent or received only when the |
77117f4f MK |
222 | .B SO_BROADCAST |
223 | socket flag is set. | |
33a0ccb2 MK |
224 | In the current implementation, connection-oriented sockets are allowed |
225 | to use only unicast addresses. | |
77117f4f | 226 | .\" Leave a loophole for XTP @) |
c6d039a3 | 227 | .P |
77117f4f MK |
228 | Note that the address and the port are always stored in |
229 | network byte order. | |
230 | In particular, this means that you need to call | |
231 | .BR htons (3) | |
232 | on the number that is assigned to a port. | |
233 | All address/port manipulation | |
234 | functions in the standard library work in network byte order. | |
8cf319f3 | 235 | .SS Special and reserved addresses |
77117f4f | 236 | There are several special addresses: |
8cf319f3 SDS |
237 | .TP |
238 | .BR INADDR_LOOPBACK " (127.0.0.1)" | |
77117f4f | 239 | always refers to the local host via the loopback device; |
8cf319f3 SDS |
240 | .TP |
241 | .BR INADDR_ANY " (0.0.0.0)" | |
242 | means any address for socket binding; | |
243 | .TP | |
244 | .BR INADDR_BROADCAST " (255.255.255.255)" | |
245 | has the same effect on | |
246 | .BR bind (2) | |
247 | as | |
77117f4f | 248 | .B INADDR_ANY |
8cf319f3 SDS |
249 | for historical reasons. |
250 | A packet addressed to | |
77117f4f | 251 | .B INADDR_BROADCAST |
8cf319f3 SDS |
252 | through a socket which has |
253 | .B SO_BROADCAST | |
254 | set will be broadcast to all hosts on the local network segment, | |
255 | as long as the link is broadcast-capable. | |
256 | .TP | |
257 | Highest-numbered address | |
258 | .TQ | |
259 | Lowest-numbered address | |
260 | On any locally-attached non-point-to-point IP subnet | |
261 | with a link type that supports broadcasts, | |
262 | the highest-numbered address | |
263 | (e.g., the .255 address on a subnet with netmask 255.255.255.0) | |
264 | is designated as a broadcast address. | |
265 | It cannot usefully be assigned to an individual interface, | |
266 | and can only be addressed with a socket on which the | |
267 | .B SO_BROADCAST | |
268 | option has been set. | |
269 | Internet standards have historically | |
270 | also reserved the lowest-numbered address | |
271 | (e.g., the .0 address on a subnet with netmask 255.255.255.0) | |
272 | for broadcast, though they call it "obsolete" for this purpose. | |
273 | (Some sources also refer to this as the "network address.") | |
274 | Since Linux 5.14, | |
275 | .\" commit 58fee5fc83658aaacf60246aeab738946a9ba516 | |
276 | it is treated as an ordinary unicast address | |
277 | and can be assigned to an interface. | |
c6d039a3 | 278 | .P |
8cf319f3 SDS |
279 | Internet standards have traditionally also reserved various addresses |
280 | for particular uses, though Linux no longer treats | |
281 | some of these specially. | |
282 | .TP | |
283 | [0.0.0.1, 0.255.255.255] | |
284 | .TQ | |
285 | [240.0.0.0, 255.255.255.254] | |
286 | Addresses in these ranges (0/8 and 240/4) are reserved globally. | |
287 | Since Linux 5.3 | |
288 | .\" commit 96125bf9985a75db00496dd2bc9249b777d2b19b | |
289 | and Linux 2.6.25, | |
290 | .\" commit 1e637c74b0f84eaca02b914c0b8c6f67276e9697 | |
291 | respectively, | |
292 | the 0/8 and 240/4 addresses, other than | |
77117f4f | 293 | .B INADDR_ANY |
8cf319f3 SDS |
294 | and |
295 | .BR INADDR_BROADCAST , | |
296 | are treated as ordinary unicast addresses. | |
297 | Systems that follow the traditional behaviors may not | |
298 | interoperate with these historically reserved addresses. | |
299 | .TP | |
300 | [127.0.0.1, 127.255.255.254] | |
301 | Addresses in this range (127/8) are treated as loopback addresses | |
302 | akin to the standardized local loopback address | |
303 | .B INADDR_LOOPBACK | |
304 | (127.0.0.1); | |
305 | .TP | |
306 | [224.0.0.0, 239.255.255.255] | |
307 | Addresses in this range (224/4) are dedicated to multicast use. | |
c634028a | 308 | .SS Socket options |
77117f4f MK |
309 | IP supports some protocol-specific socket options that can be set with |
310 | .BR setsockopt (2) | |
311 | and read with | |
312 | .BR getsockopt (2). | |
313 | The socket option level for IP is | |
314 | .BR IPPROTO_IP . | |
315 | .\" or SOL_IP on Linux | |
316 | A boolean integer flag is zero when it is false, otherwise true. | |
c6d039a3 | 317 | .P |
651b8a82 MK |
318 | When an invalid socket option is specified, |
319 | .BR getsockopt (2) | |
320 | and | |
321 | .BR setsockopt (2) | |
322 | fail with the error | |
323 | .BR ENOPROTOOPT . | |
77117f4f | 324 | .TP |