]>
Commit | Line | Data |
---|---|---|
77117f4f | 1 | '\" t |
77117f4f | 2 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. |
2297bf0e | 3 | .\" |
00acdba1 | 4 | .\" %%%LICENSE_START(VERBATIM_ONE_PARA) |
77117f4f MK |
5 | .\" Permission is granted to distribute possibly modified copies |
6 | .\" of this page provided the header is included verbatim, | |
7 | .\" and in case of nontrivial modification author and date | |
8 | .\" of the modification is added to the header. | |
8ff7380d | 9 | .\" %%%LICENSE_END |
6a717e5e | 10 | .\" |
77117f4f | 11 | .\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $ |
3ac83a00 | 12 | .\" |
bea08fec | 13 | .\" FIXME The following socket options are yet to be documented |
2c596bf5 | 14 | .\" |
f645fea8 MK |
15 | .\" IP_XFRM_POLICY (2.5.48) |
16 | .\" Needs CAP_NET_ADMIN | |
2c596bf5 | 17 | .\" |
f645fea8 MK |
18 | .\" IP_IPSEC_POLICY (2.5.47) |
19 | .\" Needs CAP_NET_ADMIN | |
2c596bf5 | 20 | .\" |
f645fea8 MK |
21 | .\" IP_PASSSEC (2.6.17) |
22 | .\" Boolean | |
23 | .\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c | |
24 | .\" Author: Catherine Zhang <cxzhang@watson.ibm.com> | |
2c596bf5 | 25 | .\" |
f645fea8 MK |
26 | .\" IP_MINTTL (2.6.34) |
27 | .\" commit d218d11133d888f9745802146a50255a4781d37a | |
28 | .\" Author: Stephen Hemminger <shemminger@vyatta.com> | |
2c596bf5 | 29 | .\" |
f645fea8 | 30 | .\" MCAST_JOIN_GROUP (2.4.22 / 2.6) |
2c596bf5 | 31 | .\" |
f645fea8 | 32 | .\" MCAST_BLOCK_SOURCE (2.4.22 / 2.6) |
2c596bf5 | 33 | .\" |
f645fea8 | 34 | .\" MCAST_UNBLOCK_SOURCE (2.4.22 / 2.6) |
2c596bf5 | 35 | .\" |
f645fea8 | 36 | .\" MCAST_LEAVE_GROUP (2.4.22 / 2.6) |
2c596bf5 | 37 | .\" |
f645fea8 | 38 | .\" MCAST_JOIN_SOURCE_GROUP (2.4.22 / 2.6) |
2c596bf5 | 39 | .\" |
f645fea8 | 40 | .\" MCAST_LEAVE_SOURCE_GROUP (2.4.22 / 2.6) |
2c596bf5 | 41 | .\" |
f645fea8 | 42 | .\" MCAST_MSFILTER (2.4.22 / 2.6) |
2c596bf5 | 43 | .\" |
f645fea8 MK |
44 | .\" IP_UNICAST_IF (3.4) |
45 | .\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71 | |
46 | .\" Author: Erich E. Hoover <ehoover@mines.edu> | |
3ac83a00 | 47 | .\" |
31a1b45e | 48 | .TH IP 7 2017-03-13 "Linux" "Linux Programmer's Manual" |
77117f4f MK |
49 | .SH NAME |
50 | ip \- Linux IPv4 protocol implementation | |
51 | .SH SYNOPSIS | |
52 | .B #include <sys/socket.h> | |
53 | .br | |
54 | .\" .B #include <net/netinet.h> -- does not exist anymore | |
55 | .\" .B #include <linux/errqueue.h> -- never include <linux/foo.h> | |
56 | .B #include <netinet/in.h> | |
57 | .br | |
58 | .B #include <netinet/ip.h> \fR/* superset of previous */ | |
68e4db0a | 59 | .PP |
d4c8c97c | 60 | .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" |
77117f4f | 61 | .br |
d4c8c97c | 62 | .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" |
77117f4f | 63 | .br |
d4c8c97c | 64 | .IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");" |
77117f4f MK |
65 | .SH DESCRIPTION |
66 | Linux implements the Internet Protocol, version 4, | |
67 | described in RFC\ 791 and RFC\ 1122. | |
68 | .B ip | |
119a1824 | 69 | contains a level 2 multicasting implementation conforming to RFC\ 1112. |
77117f4f | 70 | It also contains an IP router including a packet filter. |
77117f4f | 71 | .PP |
02f63637 | 72 | The programming interface is BSD-sockets compatible. |
77117f4f MK |
73 | For more information on sockets, see |
74 | .BR socket (7). | |
75 | .PP | |
38fdd3bb MK |
76 | An IP socket is created using |
77 | .BR socket (2): | |
5711c04f | 78 | .PP |
38fdd3bb | 79 | socket(AF_INET, socket_type, protocol); |
5711c04f | 80 | .PP |
77117f4f MK |
81 | Valid socket types are |
82 | .B SOCK_STREAM | |
83 | to open a | |
84 | .BR tcp (7) | |
85 | socket, | |
86 | .B SOCK_DGRAM | |
87 | to open a | |
88 | .BR udp (7) | |
89 | socket, or | |
90 | .B SOCK_RAW | |
91 | to open a | |
92 | .BR raw (7) | |
93 | socket to access the IP protocol directly. | |
94 | .I protocol | |
95 | is the IP protocol in the IP header to be received or sent. | |
96 | The only valid values for | |
97 | .I protocol | |
39a165e0 | 98 | are 0 and |
77117f4f | 99 | .B IPPROTO_TCP |
39a165e0 | 100 | for TCP sockets, and 0 and |
77117f4f MK |
101 | .B IPPROTO_UDP |
102 | for UDP sockets. | |
103 | For | |
104 | .B SOCK_RAW | |
119a1824 MK |
105 | you may specify a valid IANA IP protocol defined in |
106 | RFC\ 1700 assigned numbers. | |
77117f4f | 107 | .PP |
77117f4f MK |
108 | When a process wants to receive new incoming packets or connections, it |
109 | should bind a socket to a local interface address using | |
110 | .BR bind (2). | |
0a03fceb FL |
111 | In this case, only one IP socket may be bound to any given local |
112 | (address, port) pair. | |
77117f4f MK |
113 | When |
114 | .B INADDR_ANY | |
f971627f | 115 | is specified in the bind call, the socket will be bound to |
77117f4f MK |
116 | .I all |
117 | local interfaces. | |
118 | When | |
119 | .BR listen (2) | |
0a03fceb FL |
120 | is called on an unbound socket, the socket is automatically bound |
121 | to a random free port with the local address set to | |
122 | .BR INADDR_ANY . | |
123 | When | |
77117f4f | 124 | .BR connect (2) |
0a03fceb | 125 | is called on an unbound socket, the socket is automatically bound |
c534b25d | 126 | to a random free port or to a usable shared port with the local address |
0a03fceb | 127 | set to |
77117f4f | 128 | .BR INADDR_ANY . |
5711c04f | 129 | .PP |
77117f4f | 130 | A TCP local socket address that has been bound is unavailable for |
119a1824 | 131 | some time after closing, unless the |
77117f4f MK |
132 | .B SO_REUSEADDR |
133 | flag has been set. | |
119a1824 | 134 | Care should be taken when using this flag as it makes TCP less reliable. |
c634028a | 135 | .SS Address format |
77117f4f MK |
136 | An IP socket address is defined as a combination of an IP interface |
137 | address and a 16-bit port number. | |
138 | The basic IP protocol does not supply port numbers, they | |
139 | are implemented by higher level protocols like | |
140 | .BR udp (7) | |
141 | and | |
142 | .BR tcp (7). | |
143 | On raw sockets | |
144 | .I sin_port | |
145 | is set to the IP protocol. | |
146 | .PP | |
147 | .in +4n | |
b8302363 | 148 | .EX |
77117f4f MK |
149 | struct sockaddr_in { |
150 | sa_family_t sin_family; /* address family: AF_INET */ | |
4fa50d72 | 151 | in_port_t sin_port; /* port in network byte order */ |
77117f4f MK |
152 | struct in_addr sin_addr; /* internet address */ |
153 | }; | |
154 | ||
155 | /* Internet address. */ | |
156 | struct in_addr { | |
157 | uint32_t s_addr; /* address in network byte order */ | |
158 | }; | |
b8302363 | 159 | .EE |
77117f4f MK |
160 | .in |
161 | .PP | |
162 | .I sin_family | |
163 | is always set to | |
164 | .BR AF_INET . | |
165 | This is required; in Linux 2.2 most networking functions return | |
166 | .B EINVAL | |
167 | when this setting is missing. | |
168 | .I sin_port | |
169 | contains the port in network byte order. | |
170 | The port numbers below 1024 are called | |
6eb334b2 MK |
171 | .IR "privileged ports" |
172 | (or sometimes: | |
173 | .IR "reserved ports" ). | |
ed1ba8a5 MK |
174 | Only a privileged process |
175 | (on Linux: a process that has the | |
77117f4f | 176 | .B CAP_NET_BIND_SERVICE |
ed1ba8a5 | 177 | capability in the user namespace governing its network namespace) may |
77117f4f MK |
178 | .BR bind (2) |
179 | to these sockets. | |
180 | Note that the raw IPv4 protocol as such has no concept of a | |
33a0ccb2 | 181 | port, they are implemented only by higher protocols like |
77117f4f MK |
182 | .BR tcp (7) |
183 | and | |
184 | .BR udp (7). | |
185 | .PP | |
186 | .I sin_addr | |
187 | is the IP host address. | |
188 | The | |
189 | .I s_addr | |
190 | member of | |
191 | .I struct in_addr | |
192 | contains the host interface address in network byte order. | |
193 | .I in_addr | |
e89c8911 DP |
194 | should be assigned one of the |
195 | .BR INADDR_* | |
196 | values (e.g., | |
77117f4f MK |
197 | .BR INADDR_ANY ) |
198 | or set using the | |
199 | .BR inet_aton (3), | |
200 | .BR inet_addr (3), | |
201 | .BR inet_makeaddr (3) | |
202 | library functions or directly with the name resolver (see | |
203 | .BR gethostbyname (3)). | |
5711c04f | 204 | .PP |
173fa792 | 205 | IPv4 addresses are divided into unicast, broadcast, |
77117f4f MK |
206 | and multicast addresses. |
207 | Unicast addresses specify a single interface of a host, | |
173fa792 | 208 | broadcast addresses specify all hosts on a network, and multicast |
77117f4f | 209 | addresses address all hosts in a multicast group. |
33a0ccb2 | 210 | Datagrams to broadcast addresses can be sent or received only when the |
77117f4f MK |
211 | .B SO_BROADCAST |
212 | socket flag is set. | |
33a0ccb2 MK |
213 | In the current implementation, connection-oriented sockets are allowed |
214 | to use only unicast addresses. | |
77117f4f | 215 | .\" Leave a loophole for XTP @) |
5711c04f | 216 | .PP |
77117f4f MK |
217 | Note that the address and the port are always stored in |
218 | network byte order. | |
219 | In particular, this means that you need to call | |
220 | .BR htons (3) | |
221 | on the number that is assigned to a port. | |
222 | All address/port manipulation | |
223 | functions in the standard library work in network byte order. | |
5711c04f | 224 | .PP |
77117f4f MK |
225 | There are several special addresses: |
226 | .B INADDR_LOOPBACK | |
227 | (127.0.0.1) | |
228 | always refers to the local host via the loopback device; | |
229 | .B INADDR_ANY | |
230 | (0.0.0.0) | |
231 | means any address for binding; | |
232 | .B INADDR_BROADCAST | |
233 | (255.255.255.255) | |
234 | means any host and has the same effect on bind as | |
235 | .B INADDR_ANY | |
236 | for historical reasons. | |
c634028a | 237 | .SS Socket options |
77117f4f MK |
238 | IP supports some protocol-specific socket options that can be set with |
239 | .BR setsockopt (2) | |
240 | and read with | |
241 | .BR getsockopt (2). | |
242 | The socket option level for IP is | |
243 | .BR IPPROTO_IP . | |
244 | .\" or SOL_IP on Linux | |
245 | A boolean integer flag is zero when it is false, otherwise true. | |
5711c04f | 246 | .PP |
651b8a82 MK |
247 | When an invalid socket option is specified, |
248 | .BR getsockopt (2) | |
249 | and | |
250 | .BR setsockopt (2) | |
251 | fail with the error | |
252 | .BR ENOPROTOOPT . | |
77117f4f | 253 | .TP |