| 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. |