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