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 June 18, 2004 36.Dt NETINTRO 4 37.Os 38.Sh NAME 39.Nm networking 40.Nd introduction to networking facilities 41.Sh SYNOPSIS 42.In sys/types.h 43.In sys/time.h 44.In sys/socket.h 45.In net/if.h 46.In net/route.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. 63These services may include 64packet fragmentation and reassembly, routing, addressing, and 65basic transport. 66A protocol family may support multiple 67methods of addressing, though the current protocol implementations 68do not. 69A protocol family is normally comprised of a number of protocols, one per 70.Xr socket 2 71type. 72It is not required that a protocol family support all socket types. 73A protocol family may contain multiple 74protocols supporting the same socket abstraction. 75.Pp 76A protocol supports one of the socket abstractions detailed in 77.Xr socket 2 . 78A specific protocol may be accessed either by creating a 79socket of the appropriate type and protocol family, or 80by requesting the protocol explicitly when creating a socket. 81Protocols normally accept only one type of address format, 82usually determined by the addressing structure inherent in 83the design of the protocol family/network architecture. 84Certain semantics of the basic socket abstractions are 85protocol specific. 86All protocols are expected to support 87the basic model for their particular socket type, but may, 88in addition, provide non-standard facilities or extensions 89to a mechanism. 90For example, a protocol supporting the 91.Dv SOCK_STREAM 92abstraction may allow more than one byte of out-of-band 93data to be transmitted per out-of-band message. 94.Pp 95A network interface is similar to a device interface. 96Network interfaces comprise the lowest layer of the 97networking subsystem, interacting with the actual transport 98hardware. 99An interface may support one or more protocol families and/or address formats. 100The SYNOPSIS section of each network interface 101entry gives a sample specification 102of the related drivers for use in providing 103a system description to the 104.Xr config 8 105program. 106The DIAGNOSTICS section lists messages which may appear on the console 107and/or in the system error log, 108.Pa /var/log/messages 109(see 110.Xr syslogd 8 ) , 111due to errors in device operation. 112.Sh PROTOCOLS 113The system currently supports the 114Internet 115protocols, the Xerox Network Systems(tm) protocols, 116and some of the 117.Tn ISO OSI 118protocols. 119Raw socket interfaces are provided to the 120.Tn IP 121protocol 122layer of the 123Internet, and to the 124.Tn IDP 125protocol of Xerox 126.Tn NS . 127Consult the appropriate manual pages in this section for more 128information regarding the support for each protocol family. 129.Sh ADDRESSING 130Associated with each protocol family is an address 131format. 132All network addresses adhere to a general structure, 133called a sockaddr, described below. 134However, each protocol 135imposes finer and more specific structure, generally renaming 136the variant, which is discussed in the protocol family manual 137page alluded to above. 138.Bd -literal -offset indent 139struct sockaddr { 140 u_char sa_len; 141 u_char sa_family; 142 char sa_data[14]; 143}; 144.Ed 145.Pp 146The field 147.Va sa_len 148contains the total length of the structure, 149which may exceed 16 bytes. 150The following address values for 151.Va sa_family 152are known to the system 153(and additional formats are defined for possible future implementation): 154.Bd -literal 155#define AF_UNIX 1 /* local to host (pipes, portals) */ 156#define AF_INET 2 /* internetwork: UDP, TCP, etc. */ 157#define AF_NS 6 /* Xerox NS protocols */ 158#define AF_CCITT 10 /* CCITT protocols, X.25 etc */ 159#define AF_HYLINK 15 /* NSC Hyperchannel */ 160#define AF_ISO 18 /* ISO protocols */ 161.Ed 162.Sh ROUTING 163.Fx 164provides some packet routing facilities. 165The kernel maintains a routing information database, which 166is used in selecting the appropriate network interface when 167transmitting packets. 168.Pp 169A user process (or possibly multiple co-operating processes) 170maintains this database by sending messages over a special kind 171of socket. 172This supplants fixed size 173.Xr ioctl 2 174used in earlier releases. 175.Pp 176This facility is described in 177.Xr route 4 . 178.Sh INTERFACES 179Each network interface in a system corresponds to a 180path through which messages may be sent and received. 181A network interface usually has a hardware device associated with it, though 182certain interfaces such as the loopback interface, 183.Xr lo 4 , 184do not. 185.Pp 186The following 187.Xr ioctl 2 188calls may be used to manipulate network interfaces. 189The 190.Fn ioctl 191is made on a socket (typically of type 192.Dv SOCK_DGRAM ) 193in the desired domain. 194Most of the requests supported in earlier releases 195take an 196.Vt ifreq 197structure as its parameter. 198This structure has the form 199.Bd -literal 200struct ifreq { 201#define IFNAMSIZ 16 202 char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 203 union { 204 struct sockaddr ifru_addr; 205 struct sockaddr ifru_dstaddr; 206 struct sockaddr ifru_broadaddr; 207 short ifru_flags[2]; 208 short ifru_index; 209 int ifru_metric; 210 int ifru_mtu; 211 int ifru_phys; 212 int ifru_media; 213 caddr_t ifru_data; 214 int ifru_cap[2]; 215 } ifr_ifru; 216#define ifr_addr ifr_ifru.ifru_addr /* address */ 217#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ 218#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ 219#define ifr_flags ifr_ifru.ifru_flags[0] /* flags (low 16 bits) */ 220#define ifr_flagshigh ifr_ifru.ifru_flags[1] /* flags (high 16 bits) */ 221#define ifr_metric ifr_ifru.ifru_metric /* metric */ 222#define ifr_mtu ifr_ifru.ifru_mtu /* mtu */ 223#define ifr_phys ifr_ifru.ifru_phys /* physical wire */ 224#define ifr_media ifr_ifru.ifru_media /* physical media */ 225#define ifr_data ifr_ifru.ifru_data /* for use by interface */ 226#define ifr_reqcap ifr_ifru.ifru_cap[0] /* requested capabilities */ 227#define ifr_curcap ifr_ifru.ifru_cap[1] /* current capabilities */ 228#define ifr_index ifr_ifru.ifru_index /* interface index */ 229}; 230.Ed 231.Pp 232Calls which are now deprecated are: 233.Bl -tag -width SIOCGIFBRDADDR 234.It Dv SIOCSIFADDR 235Set interface address for protocol family. 236Following the address assignment, the 237.Dq initialization 238routine for the interface is called. 239.It Dv SIOCSIFDSTADDR 240Set point to point address for protocol family and interface. 241.It Dv SIOCSIFBRDADDR 242Set broadcast address for protocol family and interface. 243.El 244.Pp 245.Fn Ioctl 246requests to obtain addresses and requests both to set and 247retrieve other data are still fully supported 248and use the 249.Vt ifreq 250structure: 251.Bl -tag -width SIOCGIFBRDADDR 252.It Dv SIOCGIFADDR 253Get interface address for protocol family. 254.It Dv SIOCGIFDSTADDR 255Get point to point address for protocol family and interface. 256.It Dv SIOCGIFBRDADDR 257Get broadcast address for protocol family and interface. 258.It Dv SIOCSIFCAP 259Attempt to set the enabled capabilities field for the interface 260to the value of the 261.Va ifr_reqcap 262field of the 263.Vt ifreq 264structure. 265Note that, depending on the particular interface features, 266some capabilities may appear hard-coded to enabled, or toggling 267a capability may affect the status of other ones. 268The supported capabilities field is read-only, and the 269.Va ifr_curcap 270field is unused by this call. 271.It Dv SIOCGIFCAP 272Get the interface capabilities fields. 273The values for supported and enabled capabilities will be returned in the 274.Va ifr_reqcap 275and 276.Va ifr_curcap 277fields of the 278.Vt ifreq 279structure, respectively. 280.It Dv SIOCSIFFLAGS 281Set interface flags field. 282If the interface is marked down, 283any processes currently routing packets through the interface 284are notified; 285some interfaces may be reset so that incoming packets are no longer received. 286When marked up again, the interface is reinitialized. 287.It Dv SIOCGIFFLAGS 288Get interface flags. 289.It Dv SIOCSIFMETRIC 290Set interface routing metric. 291The metric is used only by user-level routers. 292.It Dv SIOCGIFMETRIC 293Get interface metric. 294.It Dv SIOCIFCREATE 295Attempt to create the specified interface. 296If the interface name is given without a unit number the system 297will attempt to create a new interface with an arbitrary unit number. 298On successful return the 299.Va ifr_name 300field will contain the new interface name. 301.It Dv SIOCIFDESTROY 302Attempt to destroy the specified interface. 303.El 304.Pp 305There are two requests that make use of a new structure: 306.Bl -tag -width SIOCGIFBRDADDR 307.It Dv SIOCAIFADDR 308An interface may have more than one address associated with it 309in some protocols. 310This request provides a means to 311add additional addresses (or modify characteristics of the 312primary address if the default address for the address family 313is specified). 314Rather than making separate calls to 315set destination or broadcast addresses, or network masks 316(now an integral feature of multiple protocols) 317a separate structure is used to specify all three facets simultaneously 318(see below). 319One would use a slightly tailored version of this struct specific 320to each family (replacing each sockaddr by one 321of the family-specific type). 322Where the sockaddr itself is larger than the 323default size, one needs to modify the 324.Fn ioctl 325identifier itself to include the total size, as described in 326.Fn ioctl . 327.It Dv SIOCDIFADDR 328This requests deletes the specified address from the list 329associated with an interface. 330It also uses the 331.Vt ifaliasreq 332structure to allow for the possibility of protocols allowing 333multiple masks or destination addresses, and also adopts the 334convention that specification of the default address means 335to delete the first address for the interface belonging to 336the address family in which the original socket was opened. 337.It Dv SIOCGIFCONF 338Get interface configuration list. 339This request takes an 340.Vt ifconf 341structure (see below) as a value-result parameter. 342The 343.Va ifc_len 344field should be initially set to the size of the buffer 345pointed to by 346.Va ifc_buf . 347On return it will contain the length, in bytes, of the 348configuration list. 349.It Dv SIOCIFGCLONERS 350Get list of clonable interfaces. 351This request takes an 352.Vt if_clonereq 353structure (see below) as a value-result parameter. 354The 355.Va ifcr_count 356field should be set to the number of 357.Dv IFNAMSIZ 358sized strings that can be fit in the buffer pointed to by 359.Va ifcr_buffer . 360On return, 361.Va ifcr_total 362will be set to the number of clonable interfaces and the buffer pointed 363to by 364.Va ifcr_buffer 365will be filled with the names of clonable interfaces aligned on 366.Dv IFNAMSIZ 367boundaries. 368.El 369.Bd -literal 370/* 371* Structure used in SIOCAIFCONF request. 372*/ 373struct ifaliasreq { 374 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 375 struct sockaddr ifra_addr; 376 struct sockaddr ifra_broadaddr; 377 struct sockaddr ifra_mask; 378}; 379.Ed 380.Pp 381.Bd -literal 382/* 383* Structure used in SIOCGIFCONF request. 384* Used to retrieve interface configuration 385* for machine (useful for programs which 386* must know all networks accessible). 387*/ 388struct ifconf { 389 int ifc_len; /* size of associated buffer */ 390 union { 391 caddr_t ifcu_buf; 392 struct ifreq *ifcu_req; 393 } ifc_ifcu; 394#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 395#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 396}; 397.Ed 398.Pp 399.Bd -literal 400/* Structure used in SIOCIFGCLONERS request. */ 401struct if_clonereq { 402 int ifcr_total; /* total cloners (out) */ 403 int ifcr_count; /* room for this many in user buffer */ 404 char *ifcr_buffer; /* buffer for cloner names */ 405}; 406.Ed 407.Sh SEE ALSO 408.Xr ioctl 2 , 409.Xr socket 2 , 410.Xr intro 4 , 411.Xr config 8 , 412.Xr routed 8 , 413.Xr ifnet 9 414.Sh HISTORY 415The 416.Nm netintro 417manual appeared in 418.Bx 4.3 tahoe . 419