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