| blob | 21391e42a7e620b314c5b722ce47fef8495a9bfb |
1 .\" Copyright (c) 1983, 1990, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" @(#)netintro.4 8.2 (Berkeley) 11/30/93
33 .\" $FreeBSD: src/share/man/man4/netintro.4,v 1.10.2.6 2002/08/30 14:23:38 sobomax Exp $
34 .\" $DragonFly: src/share/man/man4/netintro.4,v 1.4 2008/05/02 02:05:05 swildner Exp $
35 .\"
36 .Dd November 30, 1993
37 .Dt NETINTRO 4
38 .Os
39 .Sh NAME
40 .Nm networking
41 .Nd introduction to networking facilities
42 .Sh SYNOPSIS
43 .In sys/types.h
44 .In sys/time.h
45 .In sys/socket.h
46 .In net/if.h
47 .In net/route.h
48 .Sh DESCRIPTION
49 This section is a general introduction to the networking facilities
50 available in the system.
51 Documentation in this part of section
52 4 is broken up into three areas:
53 .Em protocol families
54 (domains),
55 .Em protocols ,
56 and
57 .Em network interfaces .
58 .Pp
59 All network protocols are associated with a specific
60 .Em protocol family .
61 A protocol family provides basic services to the protocol
62 implementation to allow it to function within a specific
63 network environment. These services may include
64 packet fragmentation and reassembly, routing, addressing, and
65 basic transport. A protocol family may support multiple
66 methods of addressing, though the current protocol implementations
67 do not. A protocol family is normally comprised of a number
68 of protocols, one per
69 .Xr socket 2
70 type. It is not required that a protocol family support
71 all socket types. A protocol family may contain multiple
72 protocols supporting the same socket abstraction.
73 .Pp
74 A protocol supports one of the socket abstractions detailed in
75 .Xr socket 2 .
76 A specific protocol may be accessed either by creating a
77 socket of the appropriate type and protocol family, or
78 by requesting the protocol explicitly when creating a socket.
79 Protocols normally accept only one type of address format,
80 usually determined by the addressing structure inherent in
81 the design of the protocol family/network architecture.
82 Certain semantics of the basic socket abstractions are
83 protocol specific. All protocols are expected to support
84 the basic model for their particular socket type, but may,
85 in addition, provide non-standard facilities or extensions
86 to a mechanism. For example, a protocol supporting the
87 .Dv SOCK_STREAM
88 abstraction may allow more than one byte of out-of-band
89 data to be transmitted per out-of-band message.
90 .Pp
91 A network interface is similar to a device interface.
92 Network interfaces comprise the lowest layer of the
93 networking subsystem, interacting with the actual transport
94 hardware. An interface may support one or more protocol
95 families and/or address formats.
96 The SYNOPSIS section of each network interface
97 entry gives a sample specification
98 of the related drivers for use in providing
99 a system description to the
100 .Xr config 8
101 program.
102 The DIAGNOSTICS section lists messages which may appear on the console
103 and/or in the system error log,
104 .Pa /var/log/messages
105 (see
106 .Xr syslogd 8 ) ,
107 due to errors in device operation.
108 .Sh PROTOCOLS
109 The system currently supports the
110 Internet
111 protocols, the Xerox Network Systems(tm) protocols,
112 and some of the
113 .Tn ISO OSI
114 protocols.
115 Raw socket interfaces are provided to the
116 .Tn IP
117 protocol
118 layer of the
119 Internet, and to the
120 .Tn IDP
121 protocol of Xerox
122 .Tn NS .
123 Consult the appropriate manual pages in this section for more
124 information regarding the support for each protocol family.
125 .Sh ADDRESSING
126 Associated with each protocol family is an address
127 format. All network address adhere to a general structure,
128 called a sockaddr, described below.
129 However, each protocol
130 imposes finer and more specific structure, generally renaming
131 the variant, which is discussed in the protocol family manual
132 page alluded to above.
133 .Bd -literal -offset indent
134 struct sockaddr {
135 u_char sa_len;
136 u_char sa_family;
137 char sa_data[14];
138 };
139 .Ed
140 .Pp
141 The field
142 .Va sa_len
143 contains the total length of the structure,
144 which may exceed 16 bytes.
145 The following address values for
146 .Va sa_family
147 are known to the system
148 (and additional formats are defined for possible future implementation):
149 .Bd -literal
150 #define AF_UNIX 1 /* local to host (pipes, portals) */
151 #define AF_INET 2 /* internetwork: UDP, TCP, etc. */
152 #define AF_NS 6 /* Xerox NS protocols */
153 #define AF_CCITT 10 /* CCITT protocols, X.25 etc */
154 #define AF_HYLINK 15 /* NSC Hyperchannel */
155 #define AF_ISO 18 /* ISO protocols */
156 .Ed
157 .Sh ROUTING
158 .Ux
159 provides some packet routing facilities.
160 The kernel maintains a routing information database, which
161 is used in selecting the appropriate network interface when
162 transmitting packets.
163 .Pp
164 A user process (or possibly multiple co-operating processes)
165 maintains this database by sending messages over a special kind
166 of socket.
167 This supplants fixed size
168 .Xr ioctl 2
169 used in earlier releases.
170 .Pp
171 This facility is described in
172 .Xr route 4 .
173 .Sh INTERFACES
174 Each network interface in a system corresponds to a
175 path through which messages may be sent and received. A network
176 interface usually has a hardware device associated with it, though
177 certain interfaces such as the loopback interface,
178 .Xr lo 4 ,
179 do not.
180 .Pp
181 The following
182 .Xr ioctl 2
183 calls may be used to manipulate network interfaces.
184 The
185 .Fn ioctl
186 is made on a socket (typically of type
187 .Dv SOCK_DGRAM )
188 in the desired domain.
189 Most of the requests supported in earlier releases
190 take an
191 .Vt ifreq
192 structure as its parameter. This structure has the form
193 .Bd -literal
194 struct ifreq {
195 #define IFNAMSIZ 16
196 char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */
197 union {
198 struct sockaddr ifru_addr;
199 struct sockaddr ifru_dstaddr;
200 struct sockaddr ifru_broadaddr;
201 short ifru_flags[2];
202 int ifru_metric;
203 int ifru_mtu;
204 int ifru_phys;
205 caddr_t ifru_data;
206 } ifr_ifru;
207 #define ifr_addr ifr_ifru.ifru_addr /* address */
208 #define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */
209 #define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */
210 #define ifr_flags ifr_ifru.ifru_flags[0] /* flags (low 16 bits) */
211 #define ifr_flagshigh ifr_ifru.ifru_flags[1] /* flags (high 16 bits) */
212 #define ifr_metric ifr_ifru.ifru_metric /* metric */
213 #define ifr_mtu ifr_ifru.ifru_mtu /* mtu */
214 #define ifr_phys ifr_ifru.ifru_phys /* physical wire */
215 #define ifr_data ifr_ifru.ifru_data /* for use by interface */
216 };
217 .Ed
218 .Pp
219 Calls which are now deprecated are:
220 .Bl -tag -width ".Dv SIOCGIFBRDADDR"
221 .It Dv SIOCSIFADDR
222 Set interface address for protocol family. Following the address
223 assignment, the ``initialization'' routine for
224 the interface is called.
225 .It Dv SIOCSIFDSTADDR
226 Set point to point address for protocol family and interface.
227 .It Dv SIOCSIFBRDADDR
228 Set broadcast address for protocol family and interface.
229 .El
230 .Pp
231 .Fn Ioctl
232 requests to obtain addresses and requests both to set and
233 retrieve other data are still fully supported
234 and use the
235 .Vt ifreq
236 structure:
237 .Bl -tag -width ".Dv SIOCGIFBRDADDR"
238 .It Dv SIOCGIFADDR
239 Get interface address for protocol family.
240 .It Dv SIOCGIFDSTADDR
241 Get point to point address for protocol family and interface.
242 .It Dv SIOCGIFBRDADDR
243 Get broadcast address for protocol family and interface.
244 .It Dv SIOCSIFFLAGS
245 Set interface flags field. If the interface is marked down,
246 any processes currently routing packets through the interface
247 are notified;
248 some interfaces may be reset so that incoming packets are no longer received.
249 When marked up again, the interface is reinitialized.
250 .It Dv SIOCGIFFLAGS
251 Get interface flags.
252 .It Dv SIOCSIFMETRIC
253 Set interface routing metric.
254 The metric is used only by user-level routers.
255 .It Dv SIOCGIFMETRIC
256 Get interface metric.
257 .It Dv SIOCIFCREATE
258 Attempt to create the specified interface.
259 If the interface name is given without a unit number the system
260 will attempt to create a new interface with an arbitrary unit number.
261 On successful return the
262 .Va ifr_name
263 field will contain the new interface name.
264 .It Dv SIOCIFDESTROY
265 Attempt to destroy the specified interface.
266 .El
267 .Pp
268 There are two requests that make use of a new structure:
269 .Bl -tag -width ".Dv SIOCGIFBRDADDR"
270 .It Dv SIOCAIFADDR
271 An interface may have more than one address associated with it
272 in some protocols. This request provides a means to
273 add additional addresses (or modify characteristics of the
274 primary address if the default address for the address family
275 is specified). Rather than making separate calls to
276 set destination or broadcast addresses, or network masks
277 (now an integral feature of multiple protocols)
278 a separate structure is used to specify all three facets simultaneously
279 (see below).
280 One would use a slightly tailored version of this struct specific
281 to each family (replacing each sockaddr by one
282 of the family-specific type).
283 Where the sockaddr itself is larger than the
284 default size, one needs to modify the
285 .Fn ioctl
286 identifier itself to include the total size, as described in
287 .Fn ioctl .
288 .It Dv SIOCDIFADDR
289 This requests deletes the specified address from the list
290 associated with an interface. It also uses the
291 .Vt ifaliasreq
292 structure to allow for the possibility of protocols allowing
293 multiple masks or destination addresses, and also adopts the
294 convention that specification of the default address means
295 to delete the first address for the interface belonging to
296 the address family in which the original socket was opened.
297 .It Dv SIOCGIFCONF
298 Get interface configuration list. This request takes an
299 .Vt ifconf
300 structure (see below) as a value-result parameter. The
301 .Va ifc_len
302 field should be initially set to the size of the buffer
303 pointed to by
304 .Va ifc_buf .
305 On return it will contain the length, in bytes, of the
306 configuration list.
307 .It Dv SIOCIFGCLONERS
308 Get list of clonable interfaces.
309 This request takes an
310 .Vt if_clonereq
311 structure (see below) as a value-result parameter.
312 The
313 .Va ifcr_count
314 field should be set to the number of
315 .Dv IFNAMSIZ
316 sized strings that can be fit in the buffer pointed to by
317 .Va ifcr_buffer .
318 On return,
319 .Va ifcr_total
320 will be set to the number of clonable interfaces and the buffer pointed
321 to by
322 .Va ifcr_buffer
323 will be filled with the names of clonable interfaces aligned on
324 .Dv IFNAMSIZ
325 boundaries.
326 .El
327 .Bd -literal
328 /*
329 * Structure used in SIOCAIFCONF request.
330 */
331 struct ifaliasreq {
332 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */
333 struct sockaddr ifra_addr;
334 struct sockaddr ifra_broadaddr;
335 struct sockaddr ifra_mask;
336 };
337 .Ed
338 .Bd -literal
339 /*
340 * Structure used in SIOCGIFCONF request.
341 * Used to retrieve interface configuration
342 * for machine (useful for programs which
343 * must know all networks accessible).
344 */
345 struct ifconf {
346 int ifc_len; /* size of associated buffer */
347 union {
348 caddr_t ifcu_buf;
349 struct ifreq *ifcu_req;
350 } ifc_ifcu;
351 #define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */
352 #define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */
353 };
354 .Ed
355 .Bd -literal
356 /* Structure used in SIOCIFGCLONERS request. */
357 struct if_clonereq {
358 int ifcr_total; /* total cloners (out) */
359 int ifcr_count; /* room for this many in user buffer */
360 char *ifcr_buffer; /* buffer for cloner names */
361 };
362 .Ed
363 .Sh SEE ALSO
364 .Xr ioctl 2 ,
365 .Xr socket 2 ,
366 .Xr intro 4 ,
367 .Xr config 8 ,
368 .Xr routed 8
369 .Sh HISTORY
370 The
371 .Nm netintro
372 manual appeared in
373 .Bx 4.3 tahoe .