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