1.\" Copyright (c) 1983, 1990, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)netintro.4 8.2 (Berkeley) 11/30/93 33.\" $FreeBSD$ 34.\" 35.Dd November 30, 1993 36.Dt NETINTRO 4 37.Os BSD 4.2 38.Sh NAME 39.Nm networking 40.Nd introduction to networking facilities 41.Sh SYNOPSIS 42.Fd #include <sys/socket.h> 43.Fd #include <net/route.h> 44.Fd #include <net/if.h> 45.Sh DESCRIPTION 46This section is a general introduction to the networking facilities 47available in the system. 48Documentation in this part of section 494 is broken up into three areas: 50.Em protocol families 51(domains), 52.Em protocols , 53and 54.Em network interfaces . 55.Pp 56All network protocols are associated with a specific 57.Em protocol family . 58A protocol family provides basic services to the protocol 59implementation to allow it to function within a specific 60network environment. These services may include 61packet fragmentation and reassembly, routing, addressing, and 62basic transport. A protocol family may support multiple 63methods of addressing, though the current protocol implementations 64do not. A protocol family is normally comprised of a number 65of protocols, one per 66.Xr socket 2 67type. It is not required that a protocol family support 68all socket types. A protocol family may contain multiple 69protocols supporting the same socket abstraction. 70.Pp 71A protocol supports one of the socket abstractions detailed in 72.Xr socket 2 . 73A specific protocol may be accessed either by creating a 74socket of the appropriate type and protocol family, or 75by requesting the protocol explicitly when creating a socket. 76Protocols normally accept only one type of address format, 77usually determined by the addressing structure inherent in 78the design of the protocol family/network architecture. 79Certain semantics of the basic socket abstractions are 80protocol specific. All protocols are expected to support 81the basic model for their particular socket type, but may, 82in addition, provide non-standard facilities or extensions 83to a mechanism. For 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. An interface may support one or more protocol 92families and/or address formats. 93The SYNOPSIS section of each network interface 94entry gives a sample specification 95of the related drivers for use in providing 96a system description to the 97.Xr config 8 98program. 99The DIAGNOSTICS section lists messages which may appear on the console 100and/or in the system error log, 101.Pa /var/log/messages 102(see 103.Xr syslogd 8 ) , 104due to errors in device operation. 105.Sh PROTOCOLS 106The system currently supports the 107Internet 108protocols, the Xerox Network Systems(tm) protocols, 109and some of the 110.Tn ISO OSI 111protocols. 112Raw socket interfaces are provided to the 113.Tn IP 114protocol 115layer of the 116Internet, 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 124format. All network address adhere to a general structure, 125called a sockaddr, described below. However, each protocol 126imposes finer and more specific structure, generally renaming 127the variant, which is discussed in the protocol family manual 128page alluded to above. 129.Bd -literal -offset indent 130 struct 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, 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_ISO 18 /* ISO protocols */ 152.Ed 153.Sh ROUTING 154.Tn UNIX 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. A network 172interface usually has a hardware device associated with it, though 173certain 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.Fn ioctl 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. This 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 int ifru_mtu; 200 int ifru_phys; 201 caddr_t ifru_data; 202 } ifr_ifru; 203#define ifr_addr ifr_ifru.ifru_addr /* address */ 204#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ 205#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ 206#define ifr_flags ifr_ifru.ifru_flags /* flags */ 207#define ifr_metric ifr_ifru.ifru_metric /* metric */ 208#define ifr_mtu ifr_ifru.ifru_mtu /* mtu */ 209#define ifr_phys ifr_ifru.ifru_phys /* physical wire */ 210#define ifr_data ifr_ifru.ifru_data /* for use by interface */ 211}; 212.Ed 213.Pp 214Calls which are now deprecated are: 215.Bl -tag -width SIOCGIFBRDADDR 216.It Dv SIOCSIFADDR 217Set interface address for protocol family. Following the address 218assignment, the ``initialization'' routine for 219the interface is called. 220.It Dv SIOCSIFDSTADDR 221Set point to point address for protocol family and interface. 222.It Dv SIOCSIFBRDADDR 223Set broadcast address for protocol family and interface. 224.El 225.Pp 226.Fn Ioctl 227requests to obtain addresses and requests both to set and 228retrieve other data are still fully supported 229and use the 230.Ar ifreq 231structure: 232.Bl -tag -width SIOCGIFBRDADDR 233.It Dv SIOCGIFADDR 234Get interface address for protocol family. 235.It Dv SIOCGIFDSTADDR 236Get point to point address for protocol family and interface. 237.It Dv SIOCGIFBRDADDR 238Get broadcast address for protocol family and interface. 239.It Dv SIOCSIFFLAGS 240Set interface flags field. If the interface is marked down, 241any processes currently routing packets through the interface 242are notified; 243some interfaces may be reset so that incoming packets are no longer received. 244When marked up again, the interface is reinitialized. 245.It Dv SIOCGIFFLAGS 246Get interface flags. 247.It Dv SIOCSIFMETRIC 248Set interface routing metric. 249The metric is used only by user-level routers. 250.It Dv SIOCGIFMETRIC 251Get interface metric. 252.El 253.Pp 254There are two requests that make use of a new structure: 255.Bl -tag -width SIOCGIFBRDADDR 256.It Dv SIOCAIFADDR 257An interface may have more than one address associated with it 258in some protocols. This request provides a means to 259add additional addresses (or modify characteristics of the 260primary address if the default address for the address family 261is specified). Rather than making separate calls to 262set destination or broadcast addresses, or network masks 263(now an integral feature of multiple protocols) 264a separate structure is used to specify all three facets simultaneously 265(see below). 266One would use a slightly tailored version of this struct specific 267to each family (replacing each sockaddr by one 268of the family-specific type). 269Where the sockaddr itself is larger than the 270default size, one needs to modify the 271.Fn ioctl 272identifier itself to include the total size, as described in 273.Fn ioctl . 274.It Dv SIOCDIFADDR 275This requests deletes the specified address from the list 276associated with an interface. It also uses the 277.Ar if_aliasreq 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.It Dv SIOCGIFCONF 284Get interface configuration list. This request takes an 285.Ar ifconf 286structure (see below) as a value-result parameter. The 287.Ar ifc_len 288field should be initially set to the size of the buffer 289pointed to by 290.Ar ifc_buf . 291On return it will contain the length, in bytes, of the 292configuration list. 293.El 294.Bd -literal 295/* 296* Structure used in SIOCAIFCONF request. 297*/ 298struct ifaliasreq { 299 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 300 struct sockaddr ifra_addr; 301 struct sockaddr ifra_broadaddr; 302 struct sockaddr ifra_mask; 303}; 304.Ed 305.Pp 306.Bd -literal 307/* 308* Structure used in SIOCGIFCONF request. 309* Used to retrieve interface configuration 310* for machine (useful for programs which 311* must know all networks accessible). 312*/ 313struct ifconf { 314 int ifc_len; /* size of associated buffer */ 315 union { 316 caddr_t ifcu_buf; 317 struct ifreq *ifcu_req; 318 } ifc_ifcu; 319#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 320#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 321}; 322.Ed 323.Sh SEE ALSO 324.Xr ioctl 2 , 325.Xr socket 2 , 326.Xr intro 4 , 327.Xr config 8 , 328.Xr routed 8 329.Sh HISTORY 330The 331.Nm netintro 332manual appeared in 333.Bx 4.3 tahoe . 334