Commit | Line | Data |
---|---|---|
804b4358 KM |
1 | .\" Copyright (c) 1983 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
6613a54c | 5 | .\" @(#)netintro.4 6.5 (Berkeley) %G% |
804b4358 | 6 | .\" |
18b4c4a1 | 7 | .TH NETINTRO 4 "" |
804b4358 KM |
8 | .UC 5 |
9 | .SH NAME | |
10 | networking \- introduction to networking facilities | |
11 | .SH SYNOPSIS | |
12 | .nf | |
13 | .ft B | |
14 | #include <sys/socket.h> | |
15 | #include <net/route.h> | |
16 | #include <net/if.h> | |
17 | .fi R | |
18 | .fi | |
19 | .SH DESCRIPTION | |
20 | .de _d | |
21 | .if t .ta .6i 2.1i 2.6i | |
22 | .\" 2.94 went to 2.6, 3.64 to 3.30 | |
23 | .if n .ta .84i 2.6i 3.30i | |
24 | .. | |
25 | .de _f | |
26 | .if t .ta .5i 1.25i 2.5i | |
27 | .\" 3.5i went to 3.8i | |
28 | .if n .ta .7i 1.75i 3.8i | |
29 | .. | |
30 | This section briefly describes the networking facilities | |
31 | available in the system. | |
32 | Documentation in this part of section | |
33 | 4 is broken up into three areas: | |
72ccc903 MK |
34 | .I "protocol families |
35 | (domains), | |
804b4358 KM |
36 | .IR protocols , |
37 | and | |
38 | .IR "network interfaces" . | |
72ccc903 MK |
39 | Entries describing a protocol family are marked ``4F,'' |
40 | while entries describing protocol use are marked ``4P.'' | |
804b4358 KM |
41 | Hardware support for network interfaces are found |
42 | among the standard ``4'' entries. | |
43 | .PP | |
44 | All network protocols are associated with a specific | |
72ccc903 MK |
45 | .IR "protocol family" . |
46 | A protocol family provides basic services to the protocol | |
804b4358 KM |
47 | implementation to allow it to function within a specific |
48 | network environment. These services may include | |
49 | packet fragmentation and reassembly, routing, addressing, and | |
72ccc903 | 50 | basic transport. A protocol family may support multiple |
804b4358 | 51 | methods of addressing, though the current protocol implementations |
72ccc903 | 52 | do not. A protocol family is normally comprised of a number |
804b4358 KM |
53 | of protocols, one per |
54 | .IR socket (2) | |
72ccc903 MK |
55 | type. It is not required that a protocol family support |
56 | all socket types. A protocol family may contain multiple | |
804b4358 KM |
57 | protocols supporting the same socket abstraction. |
58 | .PP | |
59 | A protocol supports one of the socket abstractions detailed | |
60 | in | |
61 | .IR socket (2). | |
62 | A specific protocol may be accessed either by creating a | |
72ccc903 | 63 | socket of the appropriate type and protocol family, or |
804b4358 KM |
64 | by requesting the protocol explicitly when creating a socket. |
65 | Protocols normally accept only one type of address format, | |
66 | usually determined by the addressing structure inherent in | |
72ccc903 | 67 | the design of the protocol family/network architecture. |
804b4358 KM |
68 | Certain semantics of the basic socket abstractions are |
69 | protocol specific. All protocols are expected to support | |
70 | the basic model for their particular socket type, but may, | |
71 | in addition, provide non-standard facilities or extensions | |
72 | to a mechanism. For example, a protocol supporting the | |
73 | SOCK_STREAM | |
74 | abstraction may allow more than one byte of out-of-band | |
75 | data to be transmitted per out-of-band message. | |
76 | .PP | |
77 | A network interface is similar to a device interface. | |
78 | Network interfaces comprise the lowest layer of the | |
79 | networking subsystem, interacting with the actual transport | |
80 | hardware. An interface may support one or more protocol | |
72ccc903 | 81 | families and/or address formats. |
804b4358 KM |
82 | The SYNOPSIS section of each network interface |
83 | entry gives a sample specification | |
84 | of the related drivers for use in providing | |
85 | a system description to the | |
86 | .IR config (8) | |
87 | program. | |
88 | The DIAGNOSTICS section lists messages which may appear on the console | |
72ccc903 | 89 | and/or in the system error log, |
804b4358 | 90 | .I /usr/adm/messages |
72ccc903 MK |
91 | (see |
92 | .IR syslogd (8)), | |
804b4358 KM |
93 | due to errors in device operation. |
94 | .SH PROTOCOLS | |
72ccc903 MK |
95 | The system currently supports the DARPA Internet |
96 | protocols and the Xerox Network Systems(tm) protocols. | |
97 | Raw socket interfaces are provided to the IP protocol | |
804b4358 | 98 | layer of the DARPA Internet, to the IMP link layer (1822), and to |
72ccc903 | 99 | the IDP protocol of Xerox NS. |
804b4358 KM |
100 | Consult the appropriate manual pages in this section for more |
101 | information regarding the support for each protocol family. | |
102 | .SH ADDRESSING | |
103 | Associated with each protocol family is an address | |
4c631ca5 MS |
104 | format. The following address formats are used by the system (and additional |
105 | formats are defined for possible future implementation): | |
804b4358 KM |
106 | .sp 1 |
107 | .nf | |
108 | ._d | |
109 | #define AF_UNIX 1 /* local to host (pipes, portals) */ | |
110 | #define AF_INET 2 /* internetwork: UDP, TCP, etc. */ | |
111 | #define AF_IMPLINK 3 /* arpanet imp addresses */ | |
112 | #define AF_PUP 4 /* pup protocols: e.g. BSP */ | |
4c631ca5 MS |
113 | #define AF_NS 6 /* Xerox NS protocols */ |
114 | #define AF_HYLINK 15 /* NSC Hyperchannel */ | |
804b4358 KM |
115 | .fi |
116 | .SH ROUTING | |
117 | The network facilities provided limited packet routing. | |
118 | A simple set of data structures comprise a ``routing table'' | |
119 | used in selecting the appropriate network interface when | |
120 | transmitting packets. This table contains a single entry for | |
121 | each route to a specific network or host. A user process, | |
122 | the routing daemon, maintains this data base with the aid | |
4c631ca5 | 123 | of two socket-specific |
804b4358 KM |
124 | .IR ioctl (2) |
125 | commands, SIOCADDRT and SIOCDELRT. The commands allow | |
126 | the addition and deletion of a single routing | |
127 | table entry, respectively. Routing table manipulations may | |
128 | only be carried out by super-user. | |
129 | .PP | |
130 | A routing table entry has the following form, as defined | |
131 | in | |
132 | .RI < net/route.h >; | |
133 | .sp 1 | |
134 | ._f | |
135 | .nf | |
136 | struct rtentry { | |
137 | u_long rt_hash; | |
138 | struct sockaddr rt_dst; | |
139 | struct sockaddr rt_gateway; | |
140 | short rt_flags; | |
141 | short rt_refcnt; | |
142 | u_long rt_use; | |
143 | struct ifnet *rt_ifp; | |
144 | }; | |
145 | .sp 1 | |
146 | .fi | |
147 | with | |
148 | .I rt_flags | |
149 | defined from, | |
150 | .sp 1 | |
151 | .nf | |
152 | ._d | |
153 | #define RTF_UP 0x1 /* route usable */ | |
154 | #define RTF_GATEWAY 0x2 /* destination is a gateway */ | |
155 | #define RTF_HOST 0x4 /* host entry (net otherwise) */ | |
72ccc903 | 156 | #define RTF_DYNAMIC 0x10 /* created dynamically (by redirect) */ |
804b4358 KM |
157 | .fi |
158 | .PP | |
159 | Routing table entries come in three flavors: for a specific | |
160 | host, for all hosts on a specific network, for any destination | |
161 | not matched by entries of the first two types (a wildcard route). | |
72ccc903 MK |
162 | When the system is booted and addresses are assigned |
163 | to the network interfaces, each protocol family | |
164 | installs a routing table entry for each interface when it is ready for traffic. | |
165 | Normally the protocol specifies the route | |
166 | through each interface as a ``direct'' connection to the destination host | |
804b4358 KM |
167 | or network. If the route is direct, the transport layer of |
168 | a protocol family usually requests the packet be sent to the | |
169 | same host specified in the packet. Otherwise, the interface | |
72ccc903 MK |
170 | is requested to address the packet to the gateway listed in the routing entry |
171 | (i.e. the packet is forwarded). | |
804b4358 KM |
172 | .PP |
173 | Routing table entries installed by a user process may not specify | |
174 | the hash, reference count, use, or interface fields; these are filled | |
175 | in by the routing routines. If | |
176 | a route is in use when it is deleted | |
177 | .RI ( rt_refcnt | |
178 | is non-zero), | |
72ccc903 MK |
179 | the routing entry will be marked down and removed from the routing table, |
180 | but the resources associated with it will not | |
181 | be reclaimed until all references to it are released. | |
804b4358 KM |
182 | The routing code returns EEXIST if |
183 | requested to duplicate an existing entry, ESRCH if | |
4c631ca5 | 184 | requested to delete a non-existent entry, |
804b4358 KM |
185 | or ENOBUFS if insufficient resources were available |
186 | to install a new route. | |
804b4358 KM |
187 | User processes read the routing tables through the |
188 | .I /dev/kmem | |
189 | device. | |
804b4358 KM |
190 | The |
191 | .I rt_use | |
192 | field contains the number of packets sent along the route. | |
72ccc903 MK |
193 | .PP |
194 | When routing a packet, | |
195 | the kernel will first attempt to find a route to the destination host. | |
196 | Failing that, a search is made for a route to the network of the destination. | |
197 | Finally, any route to a default (``wildcard'') gateway is chosen. | |
198 | If multiple routes are present in the table, | |
199 | the first route found will be used. | |
200 | If no entry is found, the destination is declared to be unreachable. | |
804b4358 KM |
201 | .PP |
202 | A wildcard routing entry is specified with a zero | |
203 | destination address value. Wildcard routes are used | |
204 | only when the system fails to find a route to the | |
205 | destination host and network. The combination of wildcard | |
206 | routes and routing redirects can provide an economical | |
207 | mechanism for routing traffic. | |
208 | .SH INTERFACES | |
209 | Each network interface in a system corresponds to a | |
210 | path through which messages may be sent and received. A network | |
211 | interface usually has a hardware device associated with it, though | |
212 | certain interfaces such as the loopback interface, | |
213 | .IR lo (4), | |
214 | do not. | |
215 | .PP | |
804b4358 KM |
216 | The following |
217 | .I ioctl | |
72ccc903 MK |
218 | calls may be used to manipulate network interfaces. |
219 | The | |
220 | .I ioctl | |
221 | is made on a socket (typically of type SOCK_DGRAM) | |
222 | in the desired domain. | |
223 | Unless specified otherwise, the request takes an | |
804b4358 KM |
224 | .I ifrequest |
225 | structure as its parameter. This structure has the form | |
226 | .PP | |
227 | .nf | |
228 | .DT | |
229 | struct ifreq { | |
6613a54c KB |
230 | #define IFNAMSIZ 16 |
231 | char ifr_name[IFNAMSIZE]; /* if name, e.g. "en0" */ | |
804b4358 KM |
232 | union { |
233 | struct sockaddr ifru_addr; | |
234 | struct sockaddr ifru_dstaddr; | |
72ccc903 | 235 | struct sockaddr ifru_broadaddr; |
804b4358 | 236 | short ifru_flags; |
72ccc903 | 237 | int ifru_metric; |
6613a54c | 238 | caddr_t ifru_data; |
804b4358 KM |
239 | } ifr_ifru; |
240 | #define ifr_addr ifr_ifru.ifru_addr /* address */ | |
241 | #define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ | |
72ccc903 | 242 | #define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ |
804b4358 | 243 | #define ifr_flags ifr_ifru.ifru_flags /* flags */ |
6613a54c KB |
244 | #define ifr_metric ifr_ifru.ifru_metric /* metric */ |
245 | #define ifr_data ifr_ifru.ifru_data /* for use by interface */ | |
804b4358 KM |
246 | }; |
247 | .fi | |
248 | .TP | |
249 | SIOCSIFADDR | |
72ccc903 | 250 | Set interface address for protocol family. Following the address |
804b4358 KM |
251 | assignment, the ``initialization'' routine for |
252 | the interface is called. | |
253 | .TP | |
254 | SIOCGIFADDR | |
72ccc903 | 255 | Get interface address for protocol family. |
804b4358 KM |
256 | .TP |
257 | SIOCSIFDSTADDR | |
72ccc903 | 258 | Set point to point address for protocol family and interface. |
804b4358 KM |
259 | .TP |
260 | SIOCGIFDSTADDR | |
72ccc903 MK |
261 | Get point to point address for protocol family and interface. |
262 | .TP | |
263 | SIOCSIFBRDADDR | |
264 | Set broadcast address for protocol family and interface. | |
265 | .TP | |
266 | SIOCGIFBRDADDR | |
267 | Get broadcast address for protocol family and interface. | |
804b4358 KM |
268 | .TP |
269 | SIOCSIFFLAGS | |
270 | Set interface flags field. If the interface is marked down, | |
271 | any processes currently routing packets through the interface | |
72ccc903 MK |
272 | are notified; |
273 | some interfaces may be reset so that incoming packets are no longer received. | |
274 | When marked up again, the interface is reinitialized. | |
804b4358 KM |
275 | .TP |
276 | SIOCGIFFLAGS | |
277 | Get interface flags. | |
278 | .TP | |
72ccc903 MK |
279 | SIOCSIFMETRIC |
280 | Set interface routing metric. | |
281 | The metric is used only by user-level routers. | |
282 | .TP | |
283 | SIOCGIFMETRIC | |
284 | Get interface metric. | |
285 | .TP | |
804b4358 KM |
286 | SIOCGIFCONF |
287 | Get interface configuration list. This request takes an | |
288 | .I ifconf | |
289 | structure (see below) as a value-result parameter. The | |
290 | .I ifc_len | |
291 | field should be initially set to the size of the buffer | |
292 | pointed to by | |
293 | .IR ifc_buf . | |
294 | On return it will contain the length, in bytes, of the | |
295 | configuration list. | |
296 | .PP | |
297 | .nf | |
298 | .DT | |
299 | /* | |
300 | * Structure used in SIOCGIFCONF request. | |
301 | * Used to retrieve interface configuration | |
302 | * for machine (useful for programs which | |
303 | * must know all networks accessible). | |
304 | */ | |
305 | struct ifconf { | |
306 | int ifc_len; /* size of associated buffer */ | |
307 | union { | |
308 | caddr_t ifcu_buf; | |
309 | struct ifreq *ifcu_req; | |
310 | } ifc_ifcu; | |
311 | #define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ | |
312 | #define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ | |
313 | }; | |
314 | .fi | |
315 | .SH SEE ALSO | |
18b4c4a1 | 316 | socket(2), ioctl(2), intro(4), config(8), routed(8C) |