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