share/man/man4/netintro.4

   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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)netintro.4  8.2 (Berkeley) 11/30/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd October 14, 2020
  32 .Dt NETINTRO 4
  33 .Os
  34 .Sh NAME
  35 .Nm networking
  36 .Nd introduction to networking facilities
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/time.h
  40 .In sys/socket.h
  41 .In net/if.h
  42 .In net/route.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
  57 implementation to allow it to function within a specific
  58 network environment.
  59 These services may include
  60 packet fragmentation and reassembly, routing, addressing, and
  61 basic transport.
  62 A protocol family may support multiple
  63 methods of addressing, though the current protocol implementations
  64 do not.
  65 A protocol family is normally comprised of a number of protocols, one per
  66 .Xr socket 2
  67 type.
  68 It is not required that a protocol family support all socket types.
  69 A protocol family may contain multiple
  70 protocols supporting the same socket abstraction.
  71 .Pp
  72 A protocol supports one of the socket abstractions detailed in
  73 .Xr socket 2 .
  74 A specific protocol may be accessed either by creating a
  75 socket of the appropriate type and protocol family, or
  76 by requesting the protocol explicitly when creating a socket.
  77 Protocols normally accept only one type of address format,
  78 usually determined by the addressing structure inherent in
  79 the design of the protocol family/network architecture.
  80 Certain semantics of the basic socket abstractions are
  81 protocol specific.
  82 All protocols are expected to support
  83 the basic model for their particular socket type, but may,
  84 in addition, provide non-standard facilities or extensions
  85 to a mechanism.
  86 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.
  95 An interface may support one or more protocol 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.
 128 All network addresses adhere to a general structure,
 129 called a sockaddr, described below.
 130 However, each protocol
 131 imposes finer and more specific structure, generally renaming
 132 the variant, which is discussed in the protocol family manual
 133 page alluded to above.
 134 .Bd -literal -offset indent
 135 struct sockaddr {
 136     u_char      sa_len;
 137     u_char      sa_family;
 138     char        sa_data[14];
 139 };
 140 .Ed
 141 .Pp
 142 The field
 143 .Va sa_len
 144 contains the total length of the structure,
 145 which may exceed 16 bytes.
 146 The following address values for
 147 .Va sa_family
 148 are known to the system
 149 (and additional formats are defined for possible future implementation):
 150 .Bd -literal
 151 #define    AF_UNIX      1    /* local to host (pipes, portals) */
 152 #define    AF_INET      2    /* internetwork: UDP, TCP, etc. */
 153 #define    AF_NS        6    /* Xerox NS protocols */
 154 #define    AF_CCITT     10   /* CCITT protocols, X.25 etc */
 155 #define    AF_HYLINK    15   /* NSC Hyperchannel */
 156 #define    AF_ISO       18   /* ISO protocols */
 157 .Ed
 158 .Sh ROUTING
 159 .Fx
 160 provides some packet routing facilities.
 161 The kernel maintains a routing information database, which
 162 is used in selecting the appropriate network interface when
 163 transmitting packets.
 164 .Pp
 165 A user process (or possibly multiple co-operating processes)
 166 maintains this database by sending messages over a special kind
 167 of socket.
 168 This supplants fixed size
 169 .Xr ioctl 2
 170 used in earlier releases.
 171 .Pp
 172 This facility is described in
 173 .Xr route 4 .
 174 .Sh INTERFACES
 175 Each network interface in a system corresponds to a
 176 path through which messages may be sent and received.
 177 A network interface usually has a hardware device associated with it, though
 178 certain interfaces such as the loopback interface,
 179 .Xr lo 4 ,
 180 do not.
 181 .Pp
 182 The following
 183 .Xr ioctl 2
 184 calls may be used to manipulate network interfaces.
 185 The
 186 .Fn ioctl
 187 is made on a socket (typically of type
 188 .Dv SOCK_DGRAM )
 189 in the desired domain.
 190 Most of the requests supported in earlier releases
 191 take an
 192 .Vt ifreq
 193 structure as its parameter.
 194 This structure has the form
 195 .Bd -literal
 196 struct  ifreq {
 197 #define    IFNAMSIZ    16
 198     char    ifr_name[IFNAMSIZ];        /* if name, e.g. "en0" */
 199     union {
 200         struct    sockaddr ifru_addr;
 201         struct    sockaddr ifru_dstaddr;
 202         struct    sockaddr ifru_broadaddr;
 203         struct    ifreq_buffer ifru_buffer;
 204         short     ifru_flags[2];
 205         short     ifru_index;
 206         int       ifru_metric;
 207         int       ifru_mtu;
 208         int       ifru_phys;
 209         int       ifru_media;
 210         caddr_t   ifru_data;
 211         int       ifru_cap[2];
 212     } ifr_ifru;
 213 #define ifr_addr      ifr_ifru.ifru_addr      /* address */
 214 #define ifr_dstaddr   ifr_ifru.ifru_dstaddr   /* other end of p-to-p link */
 215 #define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */
 216 #define ifr_buffer    ifr_ifru.ifru_buffer    /* user supplied buffer with its length */
 217 #define ifr_flags     ifr_ifru.ifru_flags[0]  /* flags (low 16 bits) */
 218 #define ifr_flagshigh ifr_ifru.ifru_flags[1]  /* flags (high 16 bits) */
 219 #define ifr_metric    ifr_ifru.ifru_metric    /* metric */
 220 #define ifr_mtu       ifr_ifru.ifru_mtu       /* mtu */
 221 #define ifr_phys      ifr_ifru.ifru_phys      /* physical wire */
 222 #define ifr_media     ifr_ifru.ifru_media     /* physical media */
 223 #define ifr_data      ifr_ifru.ifru_data      /* for use by interface */
 224 #define ifr_reqcap    ifr_ifru.ifru_cap[0]    /* requested capabilities */
 225 #define ifr_curcap    ifr_ifru.ifru_cap[1]    /* current capabilities */
 226 #define ifr_index     ifr_ifru.ifru_index     /* interface index */
 227 };
 228 .Ed
 229 .Pp
 230 .Fn Ioctl
 231 requests to obtain addresses and requests both to set and
 232 retrieve other data are still fully supported
 233 and use the
 234 .Vt ifreq
 235 structure:
 236 .Bl -tag -width SIOCGIFBRDADDR
 237 .It Dv SIOCGIFADDR
 238 Get interface address for protocol family.
 239 .It Dv SIOCGIFDSTADDR
 240 Get point to point address for protocol family and interface.
 241 .It Dv SIOCGIFBRDADDR
 242 Get broadcast address for protocol family and interface.
 243 .It Dv SIOCSIFCAP
 244 Attempt to set the enabled capabilities field for the interface
 245 to the value of the
 246 .Va ifr_reqcap
 247 field of the
 248 .Vt ifreq
 249 structure.
 250 Note that, depending on the particular interface features,
 251 some capabilities may appear hard-coded to enabled, or toggling
 252 a capability may affect the status of other ones.
 253 The supported capabilities field is read-only, and the
 254 .Va ifr_curcap
 255 field is unused by this call.
 256 .It Dv SIOCGIFCAP
 257 Get the interface capabilities fields.
 258 The values for supported and enabled capabilities will be returned in the
 259 .Va ifr_reqcap
 260 and
 261 .Va ifr_curcap
 262 fields of the
 263 .Vt ifreq
 264 structure, respectively.
 265 .It Dv SIOCGIFDESCR
 266 Get the interface description, returned in the
 267 .Va buffer
 268 field of
 269 .Va ifru_buffer
 270 struct.
 271 The user supplied buffer length should be defined in the
 272 .Va length
 273 field of
 274 .Va ifru_buffer
 275 struct passed in as parameter, and the length would include
 276 the terminating nul character.
 277 If there is not enough space to hold the interface length,
 278 no copy would be done and the
 279 .Va buffer
 280 field of
 281 .Va ifru_buffer
 282 would be set to NULL.
 283 The kernel will store the buffer length in the
 284 .Va length
 285 field upon return, regardless whether the buffer itself is
 286 sufficient to hold the data.
 287 .It Dv SIOCSIFDESCR
 288 Set the interface description to the value of the
 289 .Va buffer
 290 field of
 291 .Va ifru_buffer
 292 struct, with
 293 .Va length
 294 field specifying its length (counting the terminating nul).
 295 .It Dv SIOCSIFFLAGS
 296 Set interface flags field.
 297 If the interface is marked down,
 298 any processes currently routing packets through the interface
 299 are notified;
 300 some interfaces may be reset so that incoming packets are no longer received.
 301 When marked up again, the interface is reinitialized.
 302 .It Dv SIOCGIFFLAGS
 303 Get interface flags.
 304 .It Dv SIOCSIFMETRIC
 305 Set interface routing metric.
 306 The metric is used only by user-level routers.
 307 .It Dv SIOCGIFMETRIC
 308 Get interface metric.
 309 .It Dv SIOCIFCREATE
 310 Attempt to create the specified interface.
 311 If the interface name is given without a unit number the system
 312 will attempt to create a new interface with an arbitrary unit number.
 313 On successful return the
 314 .Va ifr_name
 315 field will contain the new interface name.
 316 .It Dv SIOCIFDESTROY
 317 Attempt to destroy the specified interface.
 318 .El
 319 .Pp
 320 There are two requests that make use of a new structure:
 321 .Bl -tag -width SIOCGIFBRDADDR
 322 .It Dv SIOCAIFADDR
 323 An interface may have more than one address associated with it
 324 in some protocols.
 325 This request provides a means to
 326 add additional addresses (or modify characteristics of the
 327 primary address if the default address for the address family
 328 is specified).
 329 Rather than making separate calls to
 330 set destination or broadcast addresses, or network masks
 331 (now an integral feature of multiple protocols)
 332 a separate structure is used to specify all three facets simultaneously
 333 (see below).
 334 One would use a slightly tailored version of this struct specific
 335 to each family (replacing each sockaddr by one
 336 of the family-specific type).
 337 Where the sockaddr itself is larger than the
 338 default size, one needs to modify the
 339 .Fn ioctl
 340 identifier itself to include the total size, as described in
 341 .Fn ioctl .
 342 .It Dv SIOCDIFADDR
 343 This requests deletes the specified address from the list
 344 associated with an interface.
 345 It also uses the
 346 .Vt ifaliasreq
 347 structure to allow for the possibility of protocols allowing
 348 multiple masks or destination addresses, and also adopts the
 349 convention that specification of the default address means
 350 to delete the first address for the interface belonging to
 351 the address family in which the original socket was opened.
 352 .It Dv SIOCGIFALIAS
 353 This request provides means to get additional addresses
 354 together with netmask and broadcast/destination from an
 355 interface.
 356 It also uses the
 357 .Vt ifaliasreq
 358 structure.
 359 .It Dv SIOCGIFCONF
 360 Get interface configuration list.
 361 This request takes an
 362 .Vt ifconf
 363 structure (see below) as a value-result parameter.
 364 The
 365 .Va ifc_len
 366 field should be initially set to the size of the buffer
 367 pointed to by
 368 .Va ifc_buf .
 369 On return it will contain the length, in bytes, of the
 370 configuration list.
 371 .It Dv SIOCIFGCLONERS
 372 Get list of clonable interfaces.
 373 This request takes an
 374 .Vt if_clonereq
 375 structure (see below) as a value-result parameter.
 376 The
 377 .Va ifcr_count
 378 field should be set to the number of
 379 .Dv IFNAMSIZ
 380 sized strings that can be fit in the buffer pointed to by
 381 .Va ifcr_buffer .
 382 On return,
 383 .Va ifcr_total
 384 will be set to the number of clonable interfaces and the buffer pointed
 385 to by
 386 .Va ifcr_buffer
 387 will be filled with the names of clonable interfaces aligned on
 388 .Dv IFNAMSIZ
 389 boundaries.
 390 .El
 391 .Bd -literal
 392 /*
 393 * Structure used in SIOCAIFADDR request.
 394 */
 395 struct ifaliasreq {
 396         char    ifra_name[IFNAMSIZ];   /* if name, e.g. "en0" */
 397         struct  sockaddr        ifra_addr;
 398         struct  sockaddr        ifra_broadaddr;
 399         struct  sockaddr        ifra_mask;
 400 };
 401 .Ed
 402 .Bd -literal
 403 /*
 404 * Structure used in SIOCGIFCONF request.
 405 * Used to retrieve interface configuration
 406 * for machine (useful for programs which
 407 * must know all networks accessible).
 408 */
 409 struct ifconf {
 410     int   ifc_len;              /* size of associated buffer */
 411     union {
 412         caddr_t    ifcu_buf;
 413         struct     ifreq *ifcu_req;
 414     } ifc_ifcu;
 415 #define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */
 416 #define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */
 417 };
 418 .Ed
 419 .Bd -literal
 420 /* Structure used in SIOCIFGCLONERS request. */
 421 struct if_clonereq {
 422         int     ifcr_total;     /* total cloners (out) */
 423         int     ifcr_count;     /* room for this many in user buffer */
 424         char    *ifcr_buffer;   /* buffer for cloner names */
 425 };
 426 .Ed
 427 .Bd -literal
 428 /* Structure used in SIOCGIFDESCR and SIOCSIFDESCR requests */
 429 struct ifreq_buffer {
 430         size_t  length;         /* length of the buffer */
 431         void   *buffer;         /* pointer to userland space buffer */
 432 };
 433 .Ed
 434 .Sh SEE ALSO
 435 .Xr ioctl 2 ,
 436 .Xr socket 2 ,
 437 .Xr intro 4 ,
 438 .Xr config 8 ,
 439 .Xr routed 8 ,
 440 .Xr ifnet 9
 441 .Sh HISTORY
 442 The
 443 .Nm netintro
 444 manual appeared in
 445 .Bx 4.3 tahoe .