1.\" $OpenBSD: netintro.4,v 1.11 1999/02/26 19:56:32 jason 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 Sept 3, 1994 38.Dt NETINTRO 4 39.Os BSD 4.2 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. These services may include 63packet fragmentation and reassembly, routing, addressing, and 64basic transport. A protocol family may support multiple 65methods of addressing, though the current protocol implementations 66do not. A protocol family is normally comprised of a number 67of protocols, one per 68.Xr socket 2 69type. It is not required that a protocol family support 70all socket types. A protocol family may contain multiple 71protocols supporting the same socket abstraction. 72.Pp 73A protocol supports one of the socket abstractions detailed in 74.Xr socket 2 . 75A specific protocol may be accessed either by creating a 76socket of the appropriate type and protocol family, or 77by requesting the protocol explicitly when creating a socket. 78Protocols normally accept only one type of address format, 79usually determined by the addressing structure inherent in 80the design of the protocol family/network architecture. 81Certain semantics of the basic socket abstractions are 82protocol specific. All protocols are expected to support 83the basic model for their particular socket type, but may, 84in addition, provide non-standard facilities or extensions 85to a mechanism. For 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 92networking subsystem, interacting with the actual transport 93hardware. An interface may support one or more protocol 94families and/or address formats. 95The SYNOPSIS section of each network interface 96entry gives a sample specification 97of the related drivers for use in providing 98a system description to the 99.Xr config 8 100program. 101The DIAGNOSTICS section lists messages which may appear on the console 102and/or in the system error log, 103.Pa /var/log/messages 104(see 105.Xr syslogd 8 ) , 106due to errors in device operation. 107.Sh PROTOCOLS 108The system currently supports the 109Internet 110protocols, the Xerox Network Systems(tm) protocols, 111and some of the 112.Tn ISO OSI 113protocols. 114Raw socket interfaces are provided to the 115.Tn IP 116protocol 117layer of the 118Internet, and to the 119.Tn IDP 120protocol of Xerox 121.Tn NS . 122Consult the appropriate manual pages in this section for more 123information regarding the support for each protocol family. 124.Sh ADDRESSING 125Associated with each protocol family is an address 126format. All network addresses adhere to a general structure, 127called a sockaddr, described below. However, each protocol 128imposes a finer, more specific structure, generally renaming 129the variant, which is discussed in the protocol family manual 130page alluded to above. 131.Bd -literal -offset indent 132struct sockaddr { 133 u_char sa_len; 134 u_char sa_family; 135 char sa_data[14]; 136}; 137.Ed 138.Pp 139The field 140.Ar sa_len 141contains the total length of the structure, 142which may exceed 16 bytes. 143The following address values for 144.Ar sa_family 145are known to the system 146(and additional formats are defined for possible future implementation): 147.Bd -literal 148#define AF_UNIX 1 /* local to host (pipes, portals) */ 149#define AF_INET 2 /* internetwork: UDP, TCP, etc. */ 150#define AF_NS 6 /* Xerox NS protocols */ 151#define AF_CCITT 10 /* CCITT protocols, X.25 etc */ 152#define AF_HYLINK 15 /* NSC Hyperchannel */ 153#define AF_APPLETALK 16 /* AppleTalk */ 154#define AF_ISO 18 /* ISO protocols */ 155#define AF_IPX 23 /* Novell Internet Protocol */ 156#define AF_INET6 24 /* IPv6 */ 157#define AF_NATM 27 /* native ATM access */ 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[IFNAMSIZ]; /* 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_media ifr_ifru.ifru_metric /* media options (overload) */ 213#define ifr_data ifr_ifru.ifru_data /* for use by interface */ 214}; 215.Ed 216.Pp 217Calls which are now deprecated are: 218.Bl -tag -width SIOCGIFBRDADDR 219.It Dv SIOCSIFADDR 220Set interface address for protocol family. Following the address 221assignment, the ``initialization'' routine for 222the interface is called. 223.It Dv SIOCSIFDSTADDR 224Set point to point address for protocol family and interface. 225.It Dv SIOCSIFBRDADDR 226Set broadcast address for protocol family and interface. 227.El 228.Pp 229.Xr Ioctl 230requests to obtain addresses and requests both to set and 231retrieve other data are still fully supported 232and use the 233.Ar ifreq 234structure: 235.Bl -tag -width SIOCGIFBRDADDR 236.It Dv SIOCGIFADDR 237Get interface address for protocol family. 238.It Dv SIOCGIFDSTADDR 239Get point to point address for protocol family and interface. 240.It Dv SIOCGIFBRDADDR 241Get broadcast address for protocol family and interface. 242.It Dv SIOCSIFFLAGS 243Set interface flags field. If the interface is marked down, 244any processes currently routing packets through the interface 245are notified; 246some interfaces may be reset so that incoming packets are no longer received. 247When marked up again, the interface is reinitialized. 248.It Dv SIOCGIFFLAGS 249Get interface flags. 250.It Dv SIOCSIFMEDIA 251Set interface media. See 252.Xr ifmedia 4 253for possible values. 254.It Dv SIOCGIFMEDIA 255Get interface media. See 256.Xr ifmedia 4 257for interpretting this value. 258.It Dv SIOCSIFMETRIC 259Set interface routing metric. 260The metric is used only by user-level routers. 261.It Dv SIOCGIFMETRIC 262Get interface metric. 263.El 264.Pp 265There are two requests that make use of a new structure: 266.Bl -tag -width SIOCGIFBRDADDR 267.It Dv SIOCAIFADDR 268An interface may have more than one address associated with it 269in some protocols. This request provides a means to 270add additional addresses (or modify characteristics of the 271primary address if the default address for the address family 272is specified). Rather than making separate calls to 273set destination or broadcast addresses, or network masks 274(now an integral feature of multiple protocols) 275a separate structure is used to specify all three facets simultaneously 276(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 283identifier itself to include the total size, as described in 284.Xr ioctl . 285.It Dv SIOCDIFADDR 286This request deletes the specified address from the list 287associated with an interface. It also uses the 288.Ar if_aliasreq 289structure to allow for the possibility of protocols allowing 290multiple masks or destination addresses, and also adopts the 291convention that specification of the default address means 292to delete the first address for the interface belonging to 293the address family in which the original socket was opened. 294.It Dv SIOCGIFCONF 295Get interface configuration list. This request takes an 296.Ar ifconf 297structure (see below) as a value-result parameter. The 298.Ar ifc_len 299field should be initially set to the size of the buffer 300pointed to by 301.Ar ifc_buf . 302On return it will contain the length, in bytes, of the 303configuration list. Alternately, if the 304.Ar ifc_len 305passed in is set to 0, 306.Dv SIOCGIFCONF 307will set 308.Ar ifc_len 309to the size that 310.Ar ifc_buf 311needs to be to fit the entire configuration list and not 312fill in the other parameters. 313This is useful for determining the exact size that 314.Ar ifc_buf 315needs to be in advance. Note, however, that this is an extension 316that not all operating systems support. 317.El 318.Bd -literal 319/* 320* Structure used in SIOCAIFADDR request. 321*/ 322struct ifaliasreq { 323 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 324 struct sockaddr ifra_addr; 325 struct sockaddr ifra_broadaddr; 326 struct sockaddr ifra_mask; 327}; 328.Ed 329.Pp 330.Bd -literal 331/* 332* Structure used in SIOCGIFCONF request. 333* Used to retrieve interface configuration 334* for machine (useful for programs which 335* must know all networks accessible). 336*/ 337struct ifconf { 338 int ifc_len; /* size of associated buffer */ 339 union { 340 caddr_t ifcu_buf; 341 struct ifreq *ifcu_req; 342 } ifc_ifcu; 343#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 344#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 345}; 346.Ed 347.Sh SEE ALSO 348.Xr socket 2 , 349.Xr ioctl 2 , 350.Xr intro 4 , 351.Xr bridge 4 , 352.Xr ifmedia 4 , 353.Xr config 8 , 354.Xr routed 8 355.Sh HISTORY 356The 357.Nm netintro 358manual appeared in 359.Bx 4.3 tahoe . 360