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