Debian Codegraph @

upstream/debian-unstable/man7/ip.7

raw
1 .\" Copyright 1999, Andi Kleen <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-1-para
5 .\"
6 .TH ip 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 ip \- Linux IPv4 protocol implementation
9 .SH SYNOPSIS
10 .nf
11 .B #include <sys/socket.h>
12 .\" .B #include <net/netinet.h> -- does not exist anymore
13 .\" .B #include <linux/errqueue.h> -- never include <linux/foo.h>
14 .B #include <netinet/in.h>
15 .BR "#include <netinet/ip.h>" " /* superset of previous */"
16 .P
17 .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);"
18 .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);"
19 .IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");"
20 .fi
21 .SH DESCRIPTION
22 Linux implements the Internet Protocol, version 4,
23 described in RFC\ 791 and RFC\ 1122.
24 .B ip
25 contains a level 2 multicasting implementation conforming to RFC\ 1112.
26 It also contains an IP router including a packet filter.
27 .P
28 The programming interface is BSD-sockets compatible.
29 For more information on sockets, see
30 .BR socket (7).
31 .P
32 An IP socket is created using
33 .BR socket (2):
34 .P
35 .in +4n
36 .EX
37 socket(AF_INET, socket_type, protocol);
38 .EE
39 .in
40 .P
41 Valid socket types include
42 .B SOCK_STREAM
43 to open a stream socket,
44 .B SOCK_DGRAM
45 to open a datagram socket, and
46 .B SOCK_RAW
47 to open a
48 .BR raw (7)
49 socket to access the IP protocol directly.
50 .P
51 .I protocol
52 is the IP protocol in the IP header to be received or sent.
53 Valid values for
54 .I protocol
55 include:
56 .IP \[bu] 3
57 0 and
58 .B IPPROTO_TCP
59 for
60 .BR tcp (7)
61 stream sockets;
62 .IP \[bu]
63 0 and
64 .B IPPROTO_UDP
65 for
66 .BR udp (7)
67 datagram sockets;
68 .IP \[bu]
69 .B IPPROTO_SCTP
70 for
71 .BR sctp (7)
72 stream sockets;
73 and
74 .IP \[bu]
75 .B IPPROTO_UDPLITE
76 for
77 .BR udplite (7)
78 datagram sockets.
79 .P
80 For
81 .B SOCK_RAW
82 you may specify a valid IANA IP protocol defined in
83 RFC\ 1700 assigned numbers.
84 .P
85 When a process wants to receive new incoming packets or connections, it
86 should bind a socket to a local interface address using
87 .BR bind (2).
88 In this case, only one IP socket may be bound to any given local
89 (address, port) pair.
90 When
91 .B INADDR_ANY
92 is specified in the bind call, the socket will be bound to
93 .I all
94 local interfaces.
95 When
96 .BR listen (2)
97 is called on an unbound socket, the socket is automatically bound
98 to a random free port with the local address set to
99 .BR INADDR_ANY .
100 When
101 .BR connect (2)
102 is called on an unbound socket, the socket is automatically bound
103 to a random free port or to a usable shared port with the local address
104 set to
105 .BR INADDR_ANY .
106 .P
107 A TCP local socket address that has been bound is unavailable for
108 some time after closing, unless the
109 .B SO_REUSEADDR
110 flag has been set.
111 Care should be taken when using this flag as it makes TCP less reliable.
112 .SS Address format
113 An IP socket address is defined as a combination of an IP interface
114 address and a 16-bit port number.
115 The basic IP protocol does not supply port numbers, they
116 are implemented by higher level protocols like
117 .BR udp (7)
118 and
119 .BR tcp (7).
120 On raw sockets
121 .I .sin_port
122 is set to the IP protocol.
123 .P
124 See
125 .BR sockaddr_in (3type).
126 .P
127 .I .sin_family
128 is always set to
129 .BR AF_INET .
130 This is required; in Linux 2.2 most networking functions return
131 .B EINVAL
132 when this setting is missing.
133 .I .sin_port
134 contains the port in network byte order.
135 The port numbers below 1024 are called
136 .I privileged ports
137 (or sometimes:
138 .IR "reserved ports" ).
139 Only a privileged process
140 (on Linux: a process that has the
141 .B CAP_NET_BIND_SERVICE
142 capability in the user namespace governing its network namespace) may
143 .BR bind (2)
144 to these sockets.
145 Note that the raw IPv4 protocol as such has no concept of a
146 port, they are implemented only by higher protocols like
147 .BR tcp (7)
148 and
149 .BR udp (7).
150 .P
151 .I .sin_addr
152 is the IP host address.
153 The
154 .I .s_addr
155 member of the
156 .BR in_addr (3type)
157 structure
158 contains the host interface address in network byte order.
159 .BR in_addr (3type)
160 should be assigned one of the
161 .B INADDR_*
162 values
163 (e.g.,
164 .BR INADDR_LOOPBACK )
165 using
166 .BR htonl (3)
167 or set using the
168 .BR inet_aton (3),
169 .BR inet_addr (3),
170 .BR inet_makeaddr (3)
171 library functions or directly with the name resolver (see
172 .BR gethostbyname (3)).
173 .P
174 IPv4 addresses are divided into unicast, broadcast,
175 and multicast addresses.
176 Unicast addresses specify a single interface of a host,
177 broadcast addresses specify all hosts on a network, and multicast
178 addresses address all hosts in a multicast group.
179 Datagrams to broadcast addresses can be sent or received only when the
180 .B SO_BROADCAST
181 socket flag is set.
182 In the current implementation, connection-oriented sockets are allowed
183 to use only unicast addresses.
184 .\" Leave a loophole for XTP @)
185 .P
186 Note that the address and the port are always stored in
187 network byte order.
188 In particular, this means that you need to call
189 .BR htons (3)
190 on the number that is assigned to a port.
191 All address/port manipulation
192 functions in the standard library work in network byte order.
193 .SS Special and reserved addresses
194 There are several special addresses:
195 .TP
196 .BR INADDR_LOOPBACK " (127.0.0.1)"
197 always refers to the local host via the loopback device;
198 .TP
199 .BR INADDR_ANY " (0.0.0.0)"
200 means any address for socket binding;
201 .TP
202 .BR INADDR_BROADCAST " (255.255.255.255)"
203 A packet addressed to
204 .B INADDR_BROADCAST
205 through a socket which has
206 .B SO_BROADCAST
207 set will be broadcast to all hosts on the local network segment,
208 as long as the link is broadcast-capable.
209 .TP
210 Highest-numbered address
211 .TQ
212 Lowest-numbered address
213 On any locally-attached non-point-to-point IP subnet
214 with a link type that supports broadcasts,
215 the highest-numbered address
216 (e.g., the .255 address on a subnet with netmask 255.255.255.0)
217 is designated as a broadcast address.
218 It cannot usefully be assigned to an individual interface,
219 and can only be addressed with a socket on which the
220 .B SO_BROADCAST
221 option has been set.
222 Internet standards have historically
223 also reserved the lowest-numbered address
224 (e.g., the .0 address on a subnet with netmask 255.255.255.0)
225 for broadcast, though they call it "obsolete" for this purpose.
226 (Some sources also refer to this as the "network address.")
227 Since Linux 5.14,
228 .\" commit 58fee5fc83658aaacf60246aeab738946a9ba516
229 it is treated as an ordinary unicast address
230 and can be assigned to an interface.
231 .P
232 Internet standards have traditionally also reserved various addresses
233 for particular uses, though Linux no longer treats
234 some of these specially.
235 .TP
236 [0.0.0.1, 0.255.255.255]
237 .TQ
238 [240.0.0.0, 255.255.255.254]
239 Addresses in these ranges (0/8 and 240/4) are reserved globally.
240 Since Linux 5.3
241 .\" commit 96125bf9985a75db00496dd2bc9249b777d2b19b
242 and Linux 2.6.25,
243 .\" commit 1e637c74b0f84eaca02b914c0b8c6f67276e9697
244 respectively,
245 the 0/8 and 240/4 addresses, other than
246 .B INADDR_ANY
247 and
248 .BR INADDR_BROADCAST ,
249 are treated as ordinary unicast addresses.
250 Systems that follow the traditional behaviors may not
251 interoperate with these historically reserved addresses.
252 .TP
253 [127.0.0.1, 127.255.255.254]
254 Addresses in this range (127/8) are treated as loopback addresses
255 akin to the standardized local loopback address
256 .B INADDR_LOOPBACK
257 (127.0.0.1);
258 .TP
259 [224.0.0.0, 239.255.255.255]
260 Addresses in this range (224/4) are dedicated to multicast use.
261 .SS Socket options
262 See
263 .BR IPPROTO_IP (2const).
264 .SS /proc interfaces
265 See
266 .BR proc_sys_net_ipv4 (5).
267 .SS Ioctls
268 All ioctls described in
269 .BR socket (7)
270 apply to
271 .BR ip .
272 .P
273 Ioctls to configure generic device parameters are described in
274 .BR netdevice (7).
275 .\" FIXME Add a discussion of multicasting
276 .SH ERRORS
277 .\" FIXME document all errors.
278 .\" We should really fix the kernels to give more uniform
279 .\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.)
280 .TP
281 .B EACCES
282 The user tried to execute an operation without the necessary permissions.
283 These include:
284 sending a packet to a broadcast address without having the
285 .B SO_BROADCAST
286 flag set;
287 sending a packet via a
288 .I prohibit
289 route;
290 modifying firewall settings without superuser privileges (the
291 .B CAP_NET_ADMIN
292 capability);
293 binding to a privileged port without superuser privileges (the
294 .B CAP_NET_BIND_SERVICE
295 capability).
296 .TP
297 .B EADDRINUSE
298 Tried to bind to an address already in use.
299 .TP
300 .B EADDRNOTAVAIL
301 A nonexistent interface was requested or the requested source
302 address was not local.
303 .TP
304 .B EAGAIN
305 Operation on a nonblocking socket would block.
306 .TP
307 .B EALREADY
308 A connection operation on a nonblocking socket is already in progress.
309 .TP
310 .B ECONNABORTED
311 A connection was closed during an
312 .BR accept (2).
313 .TP
314 .B EHOSTUNREACH
315 No valid routing table entry matches the destination address.
316 This error can be caused by an ICMP message from a remote router or
317 for the local routing table.
318 .TP
319 .B EINVAL
320 Invalid argument passed.
321 For send operations this can be caused by sending to a
322 .I blackhole
323 route.
324 .TP
325 .B EISCONN
326 .BR connect (2)
327 was called on an already connected socket.
328 .TP
329 .B EMSGSIZE
330 Datagram is bigger than an MTU on the path and it cannot be fragmented.
331 .TP
332 .B ENOBUFS
333 .TQ
334 .B ENOMEM
335 Not enough free memory.
336 This often means that the memory allocation is limited by the socket
337 buffer limits, not by the system memory, but this is not 100% consistent.
338 .TP
339 .B ENOENT
340 .B SIOCGSTAMP
341 was called on a socket where no packet arrived.
342 .TP
343 .B ENOPKG
344 A kernel subsystem was not configured.
345 .TP
346 .B ENOPROTOOPT
347 .TQ
348 .B EOPNOTSUPP
349 Invalid socket option passed.
350 .TP
351 .B ENOTCONN
352 The operation is defined only on a connected socket, but the socket wasn't
353 connected.
354 .TP
355 .B EPERM
356 User doesn't have permission to set high priority, change configuration,
357 or send signals to the requested process or group.
358 .TP
359 .B EPIPE
360 The connection was unexpectedly closed or shut down by the other end.
361 .TP
362 .B ESOCKTNOSUPPORT
363 The socket is not configured or an unknown socket type was requested.
364 .P
365 Other errors may be generated by the overlaying protocols;
366 see
367 .BR tcp (7),
368 .BR raw (7),
369 .BR udp (7),
370 and
371 .BR socket (7).
372 .SH NOTES
373 Be very careful with the
374 .B SO_BROADCAST
375 option \- it is not privileged in Linux.
376 It is easy to overload the network
377 with careless broadcasts.
378 For new application protocols
379 it is better to use a multicast group instead of broadcasting.
380 Broadcasting is discouraged.
381 See RFC 6762 for an example of a protocol (mDNS)
382 using the more modern multicast approach
383 to communicating with an open-ended
384 group of hosts on the local network.
385 .P
386 Using the
387 .B SOL_IP
388 socket options level isn't portable;
389 BSD-based stacks use the
390 .B IPPROTO_IP
391 level.
392 .P
393 .B INADDR_ANY
394 (0.0.0.0) and
395 .B INADDR_BROADCAST
396 (255.255.255.255) are byte-order-neutral.
397 This means
398 .BR htonl (3)
399 has no effect on them.
400 .SS Compatibility
401 For compatibility with Linux 2.0, the obsolete
402 .BI "socket(AF_INET, SOCK_PACKET, " protocol )
403 syntax is still supported to open a
404 .BR packet (7)
405 socket.
406 This is deprecated and should be replaced by
407 .BI "socket(AF_PACKET, SOCK_RAW, " protocol )
408 instead.
409 The main difference is the new
410 .I sockaddr_ll
411 address structure for generic link layer information instead of the old
412 .BR sockaddr_pkt .
413 .SH BUGS
414 There are too many inconsistent error values.
415 .P
416 The error used to diagnose exhaustion of the ephemeral port range differs
417 across the various system calls
418 .RB ( connect (2),
419 .BR bind (2),
420 .BR listen (2),
421 .BR sendto (2))
422 that can assign ephemeral ports.
423 .P
424 The ioctls to configure IP-specific interface options and ARP tables are
425 not described.
426 .\" .P
427 .\" Some versions of glibc forget to declare
428 .\" .IR in_pktinfo .
429 .\" Workaround currently is to copy it into your program from this man page.
430 .P
431 Receiving the original destination address with
432 .B MSG_ERRQUEUE
433 in
434 .I msg_name
435 by
436 .BR recvmsg (2)
437 does not work in some Linux 2.2 kernels.
438 .\" .SH AUTHORS
439 .\" This man page was written by Andi Kleen.
440 .SH SEE ALSO
441 .BR IPPROTO_IP (2const),
442 .BR recvmsg (2),
443 .BR sendmsg (2),
444 .BR byteorder (3),
445 .BR capabilities (7),
446 .BR icmp (7),
447 .BR ipv6 (7),
448 .BR netdevice (7),
449 .BR netlink (7),
450 .BR raw (7),
451 .BR socket (7),
452 .BR tcp (7),
453 .BR udp (7),
454 .BR ip (8)
455 .P
456 The kernel source file
457 .IR Documentation/networking/ip\-sysctl.rst .
458 .P
459 RFC\ 791 for the original IP specification.
460 RFC\ 1122 for the IPv4 host requirements.
461 RFC\ 1812 for the IPv4 router requirements.