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: src/share/man/man4/netintro.4,v 1.10.2.6 2002/08/30 14:23:38 sobomax Exp $
  30 .\"
  31 .Dd August 8, 2015
  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.  These services may include
  59 packet fragmentation and reassembly, routing, addressing, and
  60 basic transport.  A protocol family may support multiple
  61 methods of addressing, though the current protocol implementations
  62 do not.  A protocol family is normally comprised of a number
  63 of protocols, one per
  64 .Xr socket 2
  65 type.  It is not required that a protocol family support
  66 all socket types.  A protocol family may contain multiple
  67 protocols supporting the 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.  All protocols are expected to support
  79 the basic model for their particular socket type, but may,
  80 in addition, provide non-standard facilities or extensions
  81 to a mechanism.  For example, a protocol supporting the
  82 .Dv SOCK_STREAM
  83 abstraction may allow more than one byte of out-of-band
  84 data to be transmitted per out-of-band message.
  85 .Pp
  86 A network interface is similar to a device interface.
  87 Network interfaces comprise the lowest layer of the
  88 networking subsystem, interacting with the actual transport
  89 hardware.  An interface may support one or more protocol
  90 families and/or address formats.
  91 The SYNOPSIS section of each network interface
  92 entry gives a sample specification
  93 of the related drivers for use in providing
  94 a system description to the
  95 .Xr config 8
  96 program.
  97 The DIAGNOSTICS section lists messages which may appear on the console
  98 and/or in the system error log,
  99 .Pa /var/log/messages
 100 (see
 101 .Xr syslogd 8 ) ,
 102 due to errors in device operation.
 103 .Sh PROTOCOLS
 104 The system currently supports the
 105 Internet
 106 protocols, the Xerox Network Systems(tm) protocols,
 107 and some of the
 108 .Tn ISO OSI
 109 protocols.
 110 Raw socket interfaces are provided to the
 111 .Tn IP
 112 protocol
 113 layer of the
 114 Internet, and to the
 115 .Tn IDP
 116 protocol of Xerox
 117 .Tn NS .
 118 Consult the appropriate manual pages in this section for more
 119 information regarding the support for each protocol family.
 120 .Sh ADDRESSING
 121 Associated with each protocol family is an address
 122 format.  All network address adhere to a general structure,
 123 called a sockaddr, described below.
 124 However, each protocol
 125 imposes finer and more specific structure, generally renaming
 126 the variant, which is discussed in the protocol family manual
 127 page alluded to above.
 128 .Bd -literal -offset indent
 129     struct sockaddr {
 130         u_char  sa_len;
 131         u_char  sa_family;
 132         char    sa_data[14];
 133 };
 134 .Ed
 135 .Pp
 136 The field
 137 .Va sa_len
 138 contains the total length of the structure,
 139 which may exceed 16 bytes.
 140 The following address values for
 141 .Va sa_family
 142 are known to the system
 143 (and additional formats are defined for possible future implementation):
 144 .Bd -literal
 145 #define    AF_UNIX      1    /* local to host (pipes, portals) */
 146 #define    AF_INET      2    /* internetwork: UDP, TCP, etc. */
 147 #define    AF_CCITT     10   /* CCITT protocols, X.25 etc */
 148 #define    AF_HYLINK    15   /* NSC Hyperchannel */
 149 .Ed
 150 .Sh ROUTING
 151 .Ux
 152 provides some packet routing facilities.
 153 The kernel maintains a routing information database, which
 154 is used in selecting the appropriate network interface when
 155 transmitting packets.
 156 .Pp
 157 A user process (or possibly multiple co-operating processes)
 158 maintains this database by sending messages over a special kind
 159 of socket.
 160 This supplants fixed size
 161 .Xr ioctl 2
 162 used in earlier releases.
 163 .Pp
 164 This facility is described in
 165 .Xr route 4 .
 166 .Sh INTERFACES
 167 Each network interface in a system corresponds to a
 168 path through which messages may be sent and received.  A network
 169 interface usually has a hardware device associated with it, though
 170 certain interfaces such as the loopback interface,
 171 .Xr lo 4 ,
 172 do not.
 173 .Pp
 174 The following
 175 .Xr ioctl 2
 176 calls may be used to manipulate network interfaces.
 177 The
 178 .Fn ioctl
 179 is made on a socket (typically of type
 180 .Dv SOCK_DGRAM )
 181 in the desired domain.
 182 Most of the requests supported in earlier releases
 183 take an
 184 .Vt ifreq
 185 structure as its parameter.  This structure has the form
 186 .Bd -literal
 187 struct  ifreq {
 188 #define    IFNAMSIZ    16
 189     char    ifr_name[IFNAMSIZ];        /* if name, e.g. "en0" */
 190     union {
 191         struct    sockaddr ifru_addr;
 192         struct    sockaddr ifru_dstaddr;
 193         struct    sockaddr ifru_broadaddr;
 194         short     ifru_flags[2];
 195         int       ifru_metric;
 196         int       ifru_mtu;
 197         int       ifru_phys;
 198         caddr_t   ifru_data;
 199     } ifr_ifru;
 200 #define ifr_addr      ifr_ifru.ifru_addr      /* address */
 201 #define ifr_dstaddr   ifr_ifru.ifru_dstaddr   /* other end of p-to-p link */
 202 #define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */
 203 #define ifr_flags     ifr_ifru.ifru_flags[0]  /* flags (low 16 bits) */
 204 #define ifr_flagshigh ifr_ifru.ifru_flags[1]  /* flags (high 16 bits) */
 205 #define ifr_metric    ifr_ifru.ifru_metric    /* metric */
 206 #define ifr_mtu       ifr_ifru.ifru_mtu       /* mtu */
 207 #define ifr_phys      ifr_ifru.ifru_phys      /* physical wire */
 208 #define ifr_data      ifr_ifru.ifru_data      /* for use by interface */
 209 };
 210 .Ed
 211 .Pp
 212 Calls which are now deprecated are:
 213 .Bl -tag -width ".Dv SIOCGIFBRDADDR"
 214 .It Dv SIOCSIFADDR
 215 Set interface address for protocol family.  Following the address
 216 assignment, the ``initialization'' routine for
 217 the interface is called.
 218 .It Dv SIOCSIFDSTADDR
 219 Set point to point address for protocol family and interface.
 220 .It Dv SIOCSIFBRDADDR
 221 Set broadcast address for protocol family and interface.
 222 .El
 223 .Pp
 224 .Fn Ioctl
 225 requests to obtain addresses and requests both to set and
 226 retrieve other data are still fully supported
 227 and use the
 228 .Vt ifreq
 229 structure:
 230 .Bl -tag -width ".Dv SIOCGIFBRDADDR"
 231 .It Dv SIOCGIFADDR
 232 Get interface address for protocol family.
 233 .It Dv SIOCGIFDSTADDR
 234 Get point to point address for protocol family and interface.
 235 .It Dv SIOCGIFBRDADDR
 236 Get broadcast address for protocol family and interface.
 237 .It Dv SIOCSIFFLAGS
 238 Set interface flags field.  If the interface is marked down,
 239 any processes currently routing packets through the interface
 240 are notified;
 241 some interfaces may be reset so that incoming packets are no longer received.
 242 When marked up again, the interface is reinitialized.
 243 .It Dv SIOCGIFFLAGS
 244 Get interface flags.
 245 .It Dv SIOCSIFMETRIC
 246 Set interface routing metric.
 247 The metric is used only by user-level routers.
 248 .It Dv SIOCGIFMETRIC
 249 Get interface metric.
 250 .It Dv SIOCIFCREATE
 251 Attempt to create the specified interface.
 252 If the interface name is given without a unit number the system
 253 will attempt to create a new interface with an arbitrary unit number.
 254 On successful return the
 255 .Va ifr_name
 256 field will contain the new interface name.
 257 .It Dv SIOCIFDESTROY
 258 Attempt to destroy the specified interface.
 259 .El
 260 .Pp
 261 There are two requests that make use of a new structure:
 262 .Bl -tag -width ".Dv SIOCGIFBRDADDR"
 263 .It Dv SIOCAIFADDR
 264 An interface may have more than one address associated with it
 265 in some protocols.  This request provides a means to
 266 add additional addresses (or modify characteristics of the
 267 primary address if the default address for the address family
 268 is specified).  Rather than making separate calls to
 269 set destination or broadcast addresses, or network masks
 270 (now an integral feature of multiple protocols)
 271 a separate structure is used to specify all three facets simultaneously
 272 (see below).
 273 One would use a slightly tailored version of this struct specific
 274 to each family (replacing each sockaddr by one
 275 of the family-specific type).
 276 Where the sockaddr itself is larger than the
 277 default size, one needs to modify the
 278 .Fn ioctl
 279 identifier itself to include the total size, as described in
 280 .Fn ioctl .
 281 .It Dv SIOCDIFADDR
 282 This requests deletes the specified address from the list
 283 associated with an interface.  It also uses the
 284 .Vt ifaliasreq
 285 structure to allow for the possibility of protocols allowing
 286 multiple masks or destination addresses, and also adopts the
 287 convention that specification of the default address means
 288 to delete the first address for the interface belonging to
 289 the address family in which the original socket was opened.
 290 .It Dv SIOCGIFCONF
 291 Get interface configuration list.  This request takes an
 292 .Vt ifconf
 293 structure (see below) as a value-result parameter.  The
 294 .Va ifc_len
 295 field should be initially set to the size of the buffer
 296 pointed to by
 297 .Va ifc_buf .
 298 On return it will contain the length, in bytes, of the
 299 configuration list.
 300 .It Dv SIOCIFGCLONERS
 301 Get list of clonable interfaces.
 302 This request takes an
 303 .Vt if_clonereq
 304 structure (see below) as a value-result parameter.
 305 The
 306 .Va ifcr_count
 307 field should be set to the number of
 308 .Dv IFNAMSIZ
 309 sized strings that can be fit in the buffer pointed to by
 310 .Va ifcr_buffer .
 311 On return,
 312 .Va ifcr_total
 313 will be set to the number of clonable interfaces and the buffer pointed
 314 to by
 315 .Va ifcr_buffer
 316 will be filled with the names of clonable interfaces aligned on
 317 .Dv IFNAMSIZ
 318 boundaries.
 319 .El
 320 .Bd -literal
 321 /*
 322 * Structure used in SIOCAIFCONF request.
 323 */
 324 struct ifaliasreq {
 325         char    ifra_name[IFNAMSIZ];   /* if name, e.g. "en0" */
 326         struct  sockaddr        ifra_addr;
 327         struct  sockaddr        ifra_broadaddr;
 328         struct  sockaddr        ifra_mask;
 329 };
 330 .Ed
 331 .Bd -literal
 332 /*
 333 * Structure used in SIOCGIFCONF request.
 334 * Used to retrieve interface configuration
 335 * for machine (useful for programs which
 336 * must know all networks accessible).
 337 */
 338 struct ifconf {
 339     int   ifc_len;              /* size of associated buffer */
 340     union {
 341         caddr_t    ifcu_buf;
 342         struct     ifreq *ifcu_req;
 343     } ifc_ifcu;
 344 #define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */
 345 #define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */
 346 };
 347 .Ed
 348 .Bd -literal
 349 /* Structure used in SIOCIFGCLONERS request. */
 350 struct if_clonereq {
 351         int     ifcr_total;     /* total cloners (out) */
 352         int     ifcr_count;     /* room for this many in user buffer */
 353         char    *ifcr_buffer;   /* buffer for cloner names */
 354 };
 355 .Ed
 356 .Sh SEE ALSO
 357 .Xr ioctl 2 ,
 358 .Xr socket 2 ,
 359 .Xr intro 4 ,
 360 .Xr config 8 ,
 361 .Xr routed 8
 362 .Sh HISTORY
 363 The
 364 .Nm netintro
 365 manual appeared in
 366 .Bx 4.3 tahoe .