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