1.\" $OpenBSD: netintro.4,v 1.19 2001/11/13 13:54:25 mpech Exp $ 2.\" $NetBSD: netintro.4,v 1.4 1995/10/19 08:03:40 jtc Exp $ 3.\" 4.\" Copyright (c) 1983, 1990, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)netintro.4 8.2 (Berkeley) 11/30/93 36.\" 37.Dd September 3, 1994 38.Dt NETINTRO 4 39.Os 40.Sh NAME 41.Nm networking 42.Nd introduction to networking facilities 43.Sh SYNOPSIS 44.Fd #include <sys/socket.h> 45.Fd #include <net/route.h> 46.Fd #include <net/if.h> 47.Sh DESCRIPTION 48This section is a general introduction to the networking facilities 49available in the system. 50Documentation in this part of section 514 is broken up into three areas: 52.Em protocol families 53(domains), 54.Em protocols , 55and 56.Em network interfaces . 57.Pp 58All network protocols are associated with a specific 59.Em protocol family . 60A protocol family provides basic services to the protocol 61implementation to allow it to function within a specific 62network environment. 63These services may include packet fragmentation and reassembly, routing, 64addressing, and basic transport. 65A protocol family may support multiple methods of addressing, though 66the current protocol implementations do not. 67A protocol family is normally comprised of a number of protocols, one per 68.Xr socket 2 69type. 70It is not required that a protocol family support all socket types. 71A protocol family may contain multiple protocols supporting the same socket 72abstraction. 73.Pp 74A protocol supports one of the socket abstractions detailed in 75.Xr socket 2 . 76A specific protocol may be accessed either by creating a 77socket of the appropriate type and protocol family, or 78by requesting the protocol explicitly when creating a socket. 79Protocols normally accept only one type of address format, 80usually determined by the addressing structure inherent in 81the design of the protocol family/network architecture. 82Certain semantics of the basic socket abstractions are 83protocol specific. 84All protocols are expected to support the basic model for their particular 85socket type, but may, in addition, provide non-standard facilities or 86extensions to a mechanism. 87For example, a protocol supporting the 88.Dv SOCK_STREAM 89abstraction may allow more than one byte of out-of-band 90data to be transmitted per out-of-band message. 91.Pp 92A network interface is similar to a device interface. 93Network interfaces comprise the lowest layer of the 94networking subsystem, interacting with the actual transport 95hardware. 96An interface may support one or more protocol families and/or address formats. 97The SYNOPSIS section of each network interface entry gives a sample 98specification of the related drivers for use in providing a system description 99to the 100.Xr config 8 101program. 102The DIAGNOSTICS section lists messages which may appear on the console 103and/or in the system error log, 104.Pa /var/log/messages 105(see 106.Xr syslogd 8 ) , 107due to errors in device operation. 108.Sh PROTOCOLS 109The system currently supports the 110Internet 111protocols, the Xerox Network Systems(tm) protocols, 112and some of the 113.Tn ISO OSI 114protocols. 115Raw socket interfaces are provided to the 116.Tn IP 117protocol 118layer of the 119Internet, and to the 120.Tn IDP 121protocol of Xerox 122.Tn NS . 123Consult the appropriate manual pages in this section for more 124information regarding the support for each protocol family. 125.Sh ADDRESSING 126Associated with each protocol family is an address 127format. 128All network addresses adhere to a general structure, called a sockaddr, 129described below. 130However, each protocol imposes a finer, more specific structure, generally 131renaming the variant, which is discussed in the protocol family manual 132page alluded to above. 133.Bd -literal -offset indent 134struct sockaddr { 135 u_int8_t sa_len; 136 sa_family_t sa_family; 137 char sa_data[14]; 138}; 139.Ed 140.Pp 141The field 142.Ar sa_len 143contains the total length of the structure, 144which may exceed 16 bytes. 145The following address values for 146.Ar sa_family 147are known to the system 148(and additional formats are defined for possible future implementation): 149.Bd -literal 150#define AF_UNIX 1 /* local to host (pipes, portals) */ 151#define AF_INET 2 /* internetwork: UDP, TCP, etc. */ 152#define AF_NS 6 /* Xerox NS protocols */ 153#define AF_CCITT 10 /* CCITT protocols, X.25 etc */ 154#define AF_HYLINK 15 /* NSC Hyperchannel */ 155#define AF_APPLETALK 16 /* AppleTalk */ 156#define AF_ISO 18 /* ISO protocols */ 157#define AF_IPX 23 /* Novell Internet Protocol */ 158#define AF_INET6 24 /* IPv6 */ 159#define AF_NATM 27 /* native ATM access */ 160.Ed 161.Sh ROUTING 162.Tn UNIX 163provides some packet routing facilities. 164The kernel maintains a routing information database, which 165is used in selecting the appropriate network interface when 166transmitting packets. 167.Pp 168A user process (or possibly multiple co-operating processes) 169maintains this database by sending messages over a special kind 170of socket. 171This supplants fixed size 172.Xr ioctl 2 173used in earlier releases. 174.Pp 175This facility is described in 176.Xr route 4 . 177.Sh INTERFACES 178Each network interface in a system corresponds to a 179path through which messages may be sent and received. 180A network interface usually has a hardware device associated with it, 181though certain interfaces such as the loopback interface, 182.Xr lo 4 , 183do not. 184.Pp 185The following 186.Xr ioctl 2 187calls may be used to manipulate network interfaces. 188The 189.Xr ioctl 2 190is made on a socket (typically of type 191.Dv SOCK_DGRAM ) 192in the desired domain. 193Most of the requests supported in earlier releases 194take an 195.Ar ifreq 196structure as its parameter. 197This structure has the form 198.Bd -literal 199struct ifreq { 200#define IFNAMSIZ 16 201 char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 202 union { 203 struct sockaddr ifru_addr; 204 struct sockaddr ifru_dstaddr; 205 struct sockaddr ifru_broadaddr; 206 short ifru_flags; 207 int ifru_metric; 208 caddr_t ifru_data; 209 } ifr_ifru; 210#define ifr_addr ifr_ifru.ifru_addr /* address */ 211#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ 212#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ 213#define ifr_flags ifr_ifru.ifru_flags /* flags */ 214#define ifr_metric ifr_ifru.ifru_metric /* metric */ 215#define ifr_media ifr_ifru.ifru_metric /* media options (overload) */ 216#define ifr_data ifr_ifru.ifru_data /* for use by interface */ 217}; 218.Ed 219.Pp 220Calls which are now deprecated are: 221.Bl -tag -width SIOCGIFBRDADDR 222.It Dv SIOCSIFADDR 223Set interface address for protocol family. 224Following the address assignment, the ``initialization'' routine for the 225interface is called. 226.It Dv SIOCSIFDSTADDR 227Set point to point address for protocol family and interface. 228.It Dv SIOCSIFBRDADDR 229Set broadcast address for protocol family and interface. 230.El 231.Pp 232.Xr ioctl 2 233requests to obtain addresses and requests both to set and 234retrieve other data are still fully supported 235and use the 236.Ar ifreq 237structure: 238.Bl -tag -width SIOCGIFBRDADDR 239.It Dv SIOCGIFADDR 240Get interface address for protocol family. 241.It Dv SIOCGIFDSTADDR 242Get point to point address for protocol family and interface. 243.It Dv SIOCGIFBRDADDR 244Get broadcast address for protocol family and interface. 245.It Dv SIOCSIFFLAGS 246Set interface flags field. 247If the interface is marked down, any processes currently routing packets 248through the interface are notified; some interfaces may be reset so that 249incoming packets are no longer received. 250When marked up again, the interface is reinitialized. 251.It Dv SIOCGIFFLAGS 252Get interface flags. 253.It Dv SIOCSIFMEDIA 254Set interface media. 255See 256.Xr ifmedia 4 257for possible values. 258.It Dv SIOCGIFMEDIA 259Get interface media. 260See 261.Xr ifmedia 4 262for interpreting this value. 263.It Dv SIOCSIFMETRIC 264Set interface routing metric. 265The metric is used only by user-level routers. 266.It Dv SIOCGIFMETRIC 267Get interface metric. 268.El 269.Pp 270There are two requests that make use of a new structure: 271.Bl -tag -width SIOCGIFBRDADDR 272.It Dv SIOCAIFADDR 273An interface may have more than one address associated with it 274in some protocols. 275This request provides a means to add additional addresses (or modify 276characteristics of the primary address if the default address for the 277address family is specified). 278Rather than making separate calls to set destination or broadcast addresses, 279or network masks (now an integral feature of multiple protocols) a separate 280structure is used to specify all three facets simultaneously (see below). 281One would use a slightly tailored version of this struct specific 282to each family (replacing each sockaddr by one 283of the family-specific type). 284Where the sockaddr itself is larger than the 285default size, one needs to modify the 286.Xr ioctl 2 287identifier itself to include the total size, as described in 288.Xr ioctl 2 . 289.It Dv SIOCDIFADDR 290This request deletes the specified address from the list 291associated with an interface. 292It also uses the 293.Ar if_aliasreq 294structure to allow for the possibility of protocols allowing 295multiple masks or destination addresses, and also adopts the 296convention that specification of the default address means 297to delete the first address for the interface belonging to 298the address family in which the original socket was opened. 299.It Dv SIOCGIFCONF 300Get interface configuration list. 301This request takes an 302.Ar ifconf 303structure (see below) as a value-result parameter. 304The 305.Ar ifc_len 306field should be initially set to the size of the buffer 307pointed to by 308.Ar ifc_buf . 309On return it will contain the length, in bytes, of the 310configuration list. 311Alternately, if the 312.Ar ifc_len 313passed in is set to 0, 314.Dv SIOCGIFCONF 315will set 316.Ar ifc_len 317to the size that 318.Ar ifc_buf 319needs to be to fit the entire configuration list and not 320fill in the other parameters. 321This is useful for determining the exact size that 322.Ar ifc_buf 323needs to be in advance. 324Note, however, that this is an extension 325that not all operating systems support. 326.El 327.Bd -literal 328/* 329* Structure used in SIOCAIFADDR request. 330*/ 331struct ifaliasreq { 332 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 333 struct sockaddr ifra_addr; 334 struct sockaddr ifra_broadaddr; 335 struct sockaddr ifra_mask; 336}; 337.Ed 338.Pp 339.Bd -literal 340/* 341* Structure used in SIOCGIFCONF request. 342* Used to retrieve interface configuration 343* for machine (useful for programs which 344* must know all networks accessible). 345*/ 346struct ifconf { 347 int ifc_len; /* size of associated buffer */ 348 union { 349 caddr_t ifcu_buf; 350 struct ifreq *ifcu_req; 351 } ifc_ifcu; 352#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 353#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 354}; 355.Ed 356.Sh SEE ALSO 357.Xr ioctl 2 , 358.Xr socket 2 , 359.Xr bridge 4 , 360.Xr ifmedia 4 , 361.Xr intro 4 , 362.Xr config 8 , 363.Xr routed 8 364.Sh HISTORY 365The 366.Nm netintro 367manual appeared in 368.Bx 4.3 tahoe . 369