1.\" $NetBSD: netintro.4,v 1.16 2002/02/13 08:17:42 ross 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 August 29, 2000 37.Dt NETINTRO 4 38.Os 39.Sh NAME 40.Nm netintro 41.Nd introduction to networking facilities 42.Sh SYNOPSIS 43.Fd #include \*[Lt]sys/types.h\*[Gt] 44.Fd #include \*[Lt]sys/socket.h\*[Gt] 45.Fd #include \*[Lt]net/route.h\*[Gt] 46.Fd #include \*[Lt]net/if.h\*[Gt] 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 implementation 61to allow it to function within a specific network environment. 62These services may include packet fragmentation and reassembly, 63routing, addressing, and basic transport. 64A protocol family may support multiple methods of addressing, though 65the current protocol implementations do not. 66A protocol family normally comprises a number of protocols, one per 67.Xr socket 2 68type. 69It is not required that a protocol family support all socket types. 70A protocol family may contain multiple protocols supporting the 71same 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. 83All protocols are expected to support the basic model for their 84particular socket type, but may, in addition, provide non-standard 85facilities or extensions to a mechanism. 86For example, a protocol supporting the 87.Dv SOCK_STREAM 88abstraction may allow more than one byte of out-of-band 89data to be transmitted per out-of-band message. 90.Pp 91A network interface is similar to a device interface. 92Network interfaces comprise the lowest layer of the networking 93subsystem, interacting with the actual transport hardware. 94An interface may support one or more protocol families and/or address formats. 95The 96.Em SYNOPSIS 97section of each network interface entry gives a sample specification 98of the related drivers for use in providing a system description to the 99.Xr config 8 100program. 101.Pp 102The 103.Em DIAGNOSTICS 104section lists messages which may appear on the console 105and/or in the system error log, 106.Pa /var/log/messages 107(see 108.Xr syslogd 8 ) , 109due to errors in device operation. 110.Sh PROTOCOLS 111The system currently supports the Internet protocols, 112the Xerox Network Systems (XNS)(tm) protocols, and some of the 113.Tn ISO OSI 114protocols. 115Raw socket interfaces are provided to the 116.Tn IP 117protocol layer of the Internet, 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 format. 125All network address adhere to a general structure, called a sockaddr, 126described below. 127However, each protocol imposes finer and more specific structure, 128generally renaming the variant, which is discussed in the protocol 129family manual page alluded to above. 130.Bd -literal -offset indent 131struct 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, which 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_LOCAL 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_ISO 18 /* ISO protocols */ 152.Ed 153.Sh ROUTING 154.Ux 155provides some packet routing facilities. 156The kernel maintains a routing information database, which 157is used in selecting the appropriate network interface when 158transmitting packets. 159.Pp 160A user process (or possibly multiple co-operating processes) 161maintains this database by sending messages over a special kind 162of socket. 163This supplants fixed size 164.Xr ioctl 2 165used in earlier releases. 166.Pp 167This facility is described in 168.Xr route 4 . 169.Sh INTERFACES 170Each network interface in a system corresponds to a 171path through which messages may be sent and received. 172A network interface usually has a hardware device associated with it, 173though certain interfaces such as the loopback interface, 174.Xr lo 4 , 175do not. 176.Pp 177The following 178.Xr ioctl 2 179calls may be used to manipulate network interfaces. 180The 181.Xr ioctl 2 182is made on a socket (typically of type 183.Dv SOCK_DGRAM ) 184in the desired domain. 185Most of the requests supported in earlier releases 186take an 187.Ar ifreq 188structure as its parameter. 189This 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. 215Following the address assignment, 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 2 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. 238If the interface is marked down, any processes currently routing 239packets through the interface are notified; some interfaces may be 240reset 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. 256This request provides a means to add additional addresses (or modify 257characteristics of the primary address if the default address for 258the address family is specified). 259Rather than making separate calls to set destination or broadcast 260addresses, or network masks (now an integral feature of multiple 261protocols) a separate structure, 262.Ar ifaliasreq , 263is used to specify all three facets 264simultaneously (see below). 265One would use a slightly tailored version of this struct specific 266to each family (replacing each sockaddr by one 267of the family-specific type). 268Where the sockaddr itself is larger than the 269default size, one needs to modify the 270.Xr ioctl 2 271identifier itself to include the total size, as described in 272.Xr ioctl 2 . 273.It Dv SIOCDIFADDR 274This requests deletes the specified address from the list 275associated with an interface. 276It also uses the 277.Ar ifaliasreq 278structure to allow for the possibility of protocols allowing 279multiple masks or destination addresses, and also adopts the 280convention that specification of the default address means 281to delete the first address for the interface belonging to 282the address family in which the original socket was opened. 283.El 284.Pp 285Request making use of the 286.Ar ifconf 287structure: 288.Bl -tag -width SIOCGIFBRDADDR 289.It Dv SIOCGIFCONF 290Get interface configuration list. 291This request takes an 292.Ar ifconf 293structure (see below) as a value-result parameter. 294The 295.Ar ifc_len 296field should be initially set to the size of the buffer 297pointed to by 298.Ar ifc_buf . 299On return it will contain the length, in bytes, of the 300configuration list. 301.El 302.Bd -literal 303/* 304* Structure used in SIOC[AD]IFADDR request. 305*/ 306struct ifaliasreq { 307 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 308 struct sockaddr ifra_addr; 309 struct sockaddr ifra_dstaddr; 310#define ifra_broadaddr ifra_dstaddr 311 struct sockaddr ifra_mask; 312}; 313.Ed 314.Pp 315.Bd -literal 316/* 317* Structure used in SIOCGIFCONF request. 318* Used to retrieve interface configuration 319* for machine (useful for programs which 320* must know all networks accessible). 321*/ 322struct ifconf { 323 int ifc_len; /* size of associated buffer */ 324 union { 325 caddr_t ifcu_buf; 326 struct ifreq *ifcu_req; 327 } ifc_ifcu; 328#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 329#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 330}; 331.Ed 332.Sh SEE ALSO 333.Xr ioctl 2 , 334.Xr socket 2 , 335.Xr intro 4 , 336.Xr config 8 , 337.Xr routed 8 338.Sh HISTORY 339The 340.Nm netintro 341manual appeared in 342.Bx 4.3 Tahoe . 343