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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)netintro.4 8.2 (Berkeley) 11/30/93 29.\" $FreeBSD: src/share/man/man4/netintro.4,v 1.10.2.6 2002/08/30 14:23:38 sobomax Exp $ 30.\" $DragonFly: src/share/man/man4/netintro.4,v 1.4 2008/05/02 02:05:05 swildner Exp $ 31.\" 32.Dd November 30, 1993 33.Dt NETINTRO 4 34.Os 35.Sh NAME 36.Nm networking 37.Nd introduction to networking facilities 38.Sh SYNOPSIS 39.In sys/types.h 40.In sys/time.h 41.In sys/socket.h 42.In net/if.h 43.In net/route.h 44.Sh DESCRIPTION 45This section is a general introduction to the networking facilities 46available in the system. 47Documentation in this part of section 484 is broken up into three areas: 49.Em protocol families 50(domains), 51.Em protocols , 52and 53.Em network interfaces . 54.Pp 55All network protocols are associated with a specific 56.Em protocol family . 57A protocol family provides basic services to the protocol 58implementation to allow it to function within a specific 59network environment. These services may include 60packet fragmentation and reassembly, routing, addressing, and 61basic transport. A protocol family may support multiple 62methods of addressing, though the current protocol implementations 63do not. A protocol family is normally comprised of a number 64of protocols, one per 65.Xr socket 2 66type. It is not required that a protocol family support 67all socket types. A protocol family may contain multiple 68protocols supporting the same socket abstraction. 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. All protocols are expected to support 80the basic model for their particular socket type, but may, 81in addition, provide non-standard facilities or extensions 82to a mechanism. For example, a protocol supporting the 83.Dv SOCK_STREAM 84abstraction may allow more than one byte of out-of-band 85data to be transmitted per out-of-band message. 86.Pp 87A network interface is similar to a device interface. 88Network interfaces comprise the lowest layer of the 89networking subsystem, interacting with the actual transport 90hardware. An interface may support one or more protocol 91families and/or address formats. 92The SYNOPSIS section of each network interface 93entry gives a sample specification 94of the related drivers for use in providing 95a system description to 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. All network address adhere to a general structure, 124called a sockaddr, described below. 125However, 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.Va sa_len 139contains the total length of the structure, 140which may exceed 16 bytes. 141The following address values for 142.Va 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.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. 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.Vt 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[2]; 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[0] /* flags (low 16 bits) */ 207#define ifr_flagshigh ifr_ifru.ifru_flags[1] /* flags (high 16 bits) */ 208#define ifr_metric ifr_ifru.ifru_metric /* metric */ 209#define ifr_mtu ifr_ifru.ifru_mtu /* mtu */ 210#define ifr_phys ifr_ifru.ifru_phys /* physical wire */ 211#define ifr_data ifr_ifru.ifru_data /* for use by interface */ 212}; 213.Ed 214.Pp 215Calls which are now deprecated are: 216.Bl -tag -width ".Dv SIOCGIFBRDADDR" 217.It Dv SIOCSIFADDR 218Set interface address for protocol family. Following the address 219assignment, the ``initialization'' routine for 220the interface is called. 221.It Dv SIOCSIFDSTADDR 222Set point to point address for protocol family and interface. 223.It Dv SIOCSIFBRDADDR 224Set broadcast address for protocol family and interface. 225.El 226.Pp 227.Fn Ioctl 228requests to obtain addresses and requests both to set and 229retrieve other data are still fully supported 230and use the 231.Vt ifreq 232structure: 233.Bl -tag -width ".Dv SIOCGIFBRDADDR" 234.It Dv SIOCGIFADDR 235Get interface address for protocol family. 236.It Dv SIOCGIFDSTADDR 237Get point to point address for protocol family and interface. 238.It Dv SIOCGIFBRDADDR 239Get broadcast address for protocol family and interface. 240.It Dv SIOCSIFFLAGS 241Set interface flags field. If the interface is marked down, 242any processes currently routing packets through the interface 243are notified; 244some interfaces may be reset so that incoming packets are no longer received. 245When marked up again, the interface is reinitialized. 246.It Dv SIOCGIFFLAGS 247Get interface flags. 248.It Dv SIOCSIFMETRIC 249Set interface routing metric. 250The metric is used only by user-level routers. 251.It Dv SIOCGIFMETRIC 252Get interface metric. 253.It Dv SIOCIFCREATE 254Attempt to create the specified interface. 255If the interface name is given without a unit number the system 256will attempt to create a new interface with an arbitrary unit number. 257On successful return the 258.Va ifr_name 259field will contain the new interface name. 260.It Dv SIOCIFDESTROY 261Attempt to destroy the specified interface. 262.El 263.Pp 264There are two requests that make use of a new structure: 265.Bl -tag -width ".Dv SIOCGIFBRDADDR" 266.It Dv SIOCAIFADDR 267An interface may have more than one address associated with it 268in some protocols. This request provides a means to 269add additional addresses (or modify characteristics of the 270primary address if the default address for the address family 271is specified). Rather than making separate calls to 272set destination or broadcast addresses, or network masks 273(now an integral feature of multiple protocols) 274a separate structure is used to specify all three facets simultaneously 275(see below). 276One would use a slightly tailored version of this struct specific 277to each family (replacing each sockaddr by one 278of the family-specific type). 279Where the sockaddr itself is larger than the 280default size, one needs to modify the 281.Fn ioctl 282identifier itself to include the total size, as described in 283.Fn ioctl . 284.It Dv SIOCDIFADDR 285This requests deletes the specified address from the list 286associated with an interface. It also uses the 287.Vt ifaliasreq 288structure to allow for the possibility of protocols allowing 289multiple masks or destination addresses, and also adopts the 290convention that specification of the default address means 291to delete the first address for the interface belonging to 292the address family in which the original socket was opened. 293.It Dv SIOCGIFCONF 294Get interface configuration list. This request takes an 295.Vt ifconf 296structure (see below) as a value-result parameter. The 297.Va ifc_len 298field should be initially set to the size of the buffer 299pointed to by 300.Va ifc_buf . 301On return it will contain the length, in bytes, of the 302configuration list. 303.It Dv SIOCIFGCLONERS 304Get list of clonable interfaces. 305This request takes an 306.Vt if_clonereq 307structure (see below) as a value-result parameter. 308The 309.Va ifcr_count 310field should be set to the number of 311.Dv IFNAMSIZ 312sized strings that can be fit in the buffer pointed to by 313.Va ifcr_buffer . 314On return, 315.Va ifcr_total 316will be set to the number of clonable interfaces and the buffer pointed 317to by 318.Va ifcr_buffer 319will be filled with the names of clonable interfaces aligned on 320.Dv IFNAMSIZ 321boundaries. 322.El 323.Bd -literal 324/* 325* Structure used in SIOCAIFCONF 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.Bd -literal 335/* 336* Structure used in SIOCGIFCONF request. 337* Used to retrieve interface configuration 338* for machine (useful for programs which 339* must know all networks accessible). 340*/ 341struct ifconf { 342 int ifc_len; /* size of associated buffer */ 343 union { 344 caddr_t ifcu_buf; 345 struct ifreq *ifcu_req; 346 } ifc_ifcu; 347#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 348#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 349}; 350.Ed 351.Bd -literal 352/* Structure used in SIOCIFGCLONERS request. */ 353struct if_clonereq { 354 int ifcr_total; /* total cloners (out) */ 355 int ifcr_count; /* room for this many in user buffer */ 356 char *ifcr_buffer; /* buffer for cloner names */ 357}; 358.Ed 359.Sh SEE ALSO 360.Xr ioctl 2 , 361.Xr socket 2 , 362.Xr intro 4 , 363.Xr config 8 , 364.Xr routed 8 365.Sh HISTORY 366The 367.Nm netintro 368manual appeared in 369.Bx 4.3 tahoe . 370