]>
Commit | Line | Data |
---|---|---|
77117f4f MK |
1 | '\" t |
2 | .\" Don't change the line above. it tells man that tbl is needed. | |
3 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. | |
4 | .\" Permission is granted to distribute possibly modified copies | |
5 | .\" of this page provided the header is included verbatim, | |
6 | .\" and in case of nontrivial modification author and date | |
7 | .\" of the modification is added to the header. | |
8 | .\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $ | |
4fa50d72 | 9 | .TH IP 7 2009-02-28 "Linux" "Linux Programmer's Manual" |
77117f4f MK |
10 | .SH NAME |
11 | ip \- Linux IPv4 protocol implementation | |
12 | .SH SYNOPSIS | |
13 | .B #include <sys/socket.h> | |
14 | .br | |
15 | .\" .B #include <net/netinet.h> -- does not exist anymore | |
16 | .\" .B #include <linux/errqueue.h> -- never include <linux/foo.h> | |
17 | .B #include <netinet/in.h> | |
18 | .br | |
19 | .B #include <netinet/ip.h> \fR/* superset of previous */ | |
20 | .sp | |
d4c8c97c | 21 | .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" |
77117f4f | 22 | .br |
d4c8c97c | 23 | .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" |
77117f4f | 24 | .br |
d4c8c97c | 25 | .IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");" |
77117f4f MK |
26 | .SH DESCRIPTION |
27 | Linux implements the Internet Protocol, version 4, | |
28 | described in RFC\ 791 and RFC\ 1122. | |
29 | .B ip | |
119a1824 | 30 | contains a level 2 multicasting implementation conforming to RFC\ 1112. |
77117f4f MK |
31 | It also contains an IP router including a packet filter. |
32 | .\" FIXME has someone verified that 2.1 is really 1812 compliant? | |
33 | .PP | |
02f63637 | 34 | The programming interface is BSD-sockets compatible. |
77117f4f MK |
35 | For more information on sockets, see |
36 | .BR socket (7). | |
37 | .PP | |
38 | An IP socket is created by calling the | |
39 | .BR socket (2) | |
40 | function as | |
d4c8c97c | 41 | .BR "socket(AF_INET, socket_type, protocol)" . |
77117f4f MK |
42 | Valid socket types are |
43 | .B SOCK_STREAM | |
44 | to open a | |
45 | .BR tcp (7) | |
46 | socket, | |
47 | .B SOCK_DGRAM | |
48 | to open a | |
49 | .BR udp (7) | |
50 | socket, or | |
51 | .B SOCK_RAW | |
52 | to open a | |
53 | .BR raw (7) | |
54 | socket to access the IP protocol directly. | |
55 | .I protocol | |
56 | is the IP protocol in the IP header to be received or sent. | |
57 | The only valid values for | |
58 | .I protocol | |
39a165e0 | 59 | are 0 and |
77117f4f | 60 | .B IPPROTO_TCP |
39a165e0 | 61 | for TCP sockets, and 0 and |
77117f4f MK |
62 | .B IPPROTO_UDP |
63 | for UDP sockets. | |
64 | For | |
65 | .B SOCK_RAW | |
119a1824 MK |
66 | you may specify a valid IANA IP protocol defined in |
67 | RFC\ 1700 assigned numbers. | |
77117f4f MK |
68 | .PP |
69 | .\" FIXME ip current does an autobind in listen, but I'm not sure | |
70 | .\" if that should be documented. | |
71 | When a process wants to receive new incoming packets or connections, it | |
72 | should bind a socket to a local interface address using | |
73 | .BR bind (2). | |
74 | Only one IP socket may be bound to any given local (address, port) pair. | |
75 | When | |
76 | .B INADDR_ANY | |
f971627f | 77 | is specified in the bind call, the socket will be bound to |
77117f4f MK |
78 | .I all |
79 | local interfaces. | |
80 | When | |
81 | .BR listen (2) | |
82 | or | |
83 | .BR connect (2) | |
84 | are called on an unbound socket, it is automatically bound to a | |
85 | random free port with the local address set to | |
86 | .BR INADDR_ANY . | |
87 | ||
88 | A TCP local socket address that has been bound is unavailable for | |
119a1824 | 89 | some time after closing, unless the |
77117f4f MK |
90 | .B SO_REUSEADDR |
91 | flag has been set. | |
119a1824 | 92 | Care should be taken when using this flag as it makes TCP less reliable. |
77117f4f MK |
93 | .SS Address Format |
94 | An IP socket address is defined as a combination of an IP interface | |
95 | address and a 16-bit port number. | |
96 | The basic IP protocol does not supply port numbers, they | |
97 | are implemented by higher level protocols like | |
98 | .BR udp (7) | |
99 | and | |
100 | .BR tcp (7). | |
101 | On raw sockets | |
102 | .I sin_port | |
103 | is set to the IP protocol. | |
104 | .PP | |
105 | .in +4n | |
106 | .nf | |
107 | struct sockaddr_in { | |
108 | sa_family_t sin_family; /* address family: AF_INET */ | |
4fa50d72 | 109 | in_port_t sin_port; /* port in network byte order */ |
77117f4f MK |
110 | struct in_addr sin_addr; /* internet address */ |
111 | }; | |
112 | ||
113 | /* Internet address. */ | |
114 | struct in_addr { | |
115 | uint32_t s_addr; /* address in network byte order */ | |
116 | }; | |
117 | .fi | |
118 | .in | |
119 | .PP | |
120 | .I sin_family | |
121 | is always set to | |
122 | .BR AF_INET . | |
123 | This is required; in Linux 2.2 most networking functions return | |
124 | .B EINVAL | |
125 | when this setting is missing. | |
126 | .I sin_port | |
127 | contains the port in network byte order. | |
128 | The port numbers below 1024 are called | |
6eb334b2 MK |
129 | .IR "privileged ports" |
130 | (or sometimes: | |
131 | .IR "reserved ports" ). | |
77117f4f MK |
132 | Only privileged processes (i.e., those having the |
133 | .B CAP_NET_BIND_SERVICE | |
134 | capability) may | |
135 | .BR bind (2) | |
136 | to these sockets. | |
137 | Note that the raw IPv4 protocol as such has no concept of a | |
138 | port, they are only implemented by higher protocols like | |
139 | .BR tcp (7) | |
140 | and | |
141 | .BR udp (7). | |
142 | .PP | |
143 | .I sin_addr | |
144 | is the IP host address. | |
145 | The | |
146 | .I s_addr | |
147 | member of | |
148 | .I struct in_addr | |
149 | contains the host interface address in network byte order. | |
150 | .I in_addr | |
151 | should be assigned one of the INADDR_* values (e.g., | |
152 | .BR INADDR_ANY ) | |
153 | or set using the | |
154 | .BR inet_aton (3), | |
155 | .BR inet_addr (3), | |
156 | .BR inet_makeaddr (3) | |
157 | library functions or directly with the name resolver (see | |
158 | .BR gethostbyname (3)). | |
02f63637 | 159 | |
77117f4f MK |
160 | IPv4 addresses are divided into unicast, broadcast |
161 | and multicast addresses. | |
162 | Unicast addresses specify a single interface of a host, | |
163 | broadcast addresses specify all hosts on a network and multicast | |
164 | addresses address all hosts in a multicast group. | |
165 | Datagrams to broadcast addresses can be only sent or received when the | |
166 | .B SO_BROADCAST | |
167 | socket flag is set. | |
f971627f | 168 | In the current implementation, connection-oriented sockets are only allowed |
77117f4f MK |
169 | to use unicast addresses. |
170 | .\" Leave a loophole for XTP @) | |
171 | ||
172 | Note that the address and the port are always stored in | |
173 | network byte order. | |
174 | In particular, this means that you need to call | |
175 | .BR htons (3) | |
176 | on the number that is assigned to a port. | |
177 | All address/port manipulation | |
178 | functions in the standard library work in network byte order. | |
179 | ||
180 | There are several special addresses: | |
181 | .B INADDR_LOOPBACK | |
182 | (127.0.0.1) | |
183 | always refers to the local host via the loopback device; | |
184 | .B INADDR_ANY | |
185 | (0.0.0.0) | |
186 | means any address for binding; | |
187 | .B INADDR_BROADCAST | |
188 | (255.255.255.255) | |
189 | means any host and has the same effect on bind as | |
190 | .B INADDR_ANY | |
191 | for historical reasons. | |
192 | .SS Socket Options | |
193 | IP supports some protocol-specific socket options that can be set with | |
194 | .BR setsockopt (2) | |
195 | and read with | |
196 | .BR getsockopt (2). | |
197 | The socket option level for IP is | |
198 | .BR IPPROTO_IP . | |
199 | .\" or SOL_IP on Linux | |
200 | A boolean integer flag is zero when it is false, otherwise true. | |
201 | .\" | |
202 | .\" FIXME Document IP_FREEBIND | |
4ebab2e6 MK |
203 | .\" Boolean |
204 | .\" Since Linux 2.4.0-test10 | |
77117f4f MK |
205 | .\" |
206 | .TP | |