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 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. 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. 128However, each protocol 129imposes finer and more specific structure, generally renaming 130the variant, which is discussed in the protocol family manual 131page alluded to above. 132.Bd -literal -offset indent 133struct sockaddr { 134 u_char sa_len; 135 u_char sa_family; 136 char sa_data[14]; 137}; 138.Ed 139.Pp 140The field 141.Va sa_len 142contains the total length of the structure, 143which may exceed 16 bytes. 144The following address values for 145.Va sa_family 146are known to the system 147(and additional formats are defined for possible future implementation): 148.Bd -literal 149#define AF_UNIX 1 /* local to host (pipes, portals) */ 150#define AF_INET 2 /* internetwork: UDP, TCP, etc. */ 151#define AF_NS 6 /* Xerox NS protocols */ 152#define AF_CCITT 10 /* CCITT protocols, X.25 etc */ 153#define AF_HYLINK 15 /* NSC Hyperchannel */ 154#define AF_ISO 18 /* ISO protocols */ 155.Ed 156.Sh ROUTING 157.Fx 158provides some packet routing facilities. 159The kernel maintains a routing information database, which 160is used in selecting the appropriate network interface when 161transmitting packets. 162.Pp 163A user process (or possibly multiple co-operating processes) 164maintains this database by sending messages over a special kind 165of socket. 166This supplants fixed size 167.Xr ioctl 2 168used in earlier releases. 169.Pp 170This facility is described in 171.Xr route 4 . 172.Sh INTERFACES 173Each network interface in a system corresponds to a 174path through which messages may be sent and received. A network 175interface usually has a hardware device associated with it, though 176certain interfaces such as the loopback interface, 177.Xr lo 4 , 178do not. 179.Pp 180The following 181.Xr ioctl 2 182calls may be used to manipulate network interfaces. 183The 184.Fn ioctl 185is made on a socket (typically of type 186.Dv SOCK_DGRAM ) 187in the desired domain. 188Most of the requests supported in earlier releases 189take an 190.Vt ifreq 191structure as its parameter. This structure has the form 192.Bd -literal 193struct ifreq { 194#define IFNAMSIZ 16 195 char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 196 union { 197 struct sockaddr ifru_addr; 198 struct sockaddr ifru_dstaddr; 199 struct sockaddr ifru_broadaddr; 200 short ifru_flags[2]; 201 int ifru_metric; 202 int ifru_mtu; 203 int ifru_phys; 204 caddr_t ifru_data; 205 } ifr_ifru; 206#define ifr_addr ifr_ifru.ifru_addr /* address */ 207#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ 208#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ 209#define ifr_flags ifr_ifru.ifru_flags[0] /* flags (low 16 bits) */ 210#define ifr_flagshigh ifr_ifru.ifru_flags[1] /* flags (high 16 bits) */ 211#define ifr_metric ifr_ifru.ifru_metric /* metric */ 212#define ifr_mtu ifr_ifru.ifru_mtu /* mtu */ 213#define ifr_phys ifr_ifru.ifru_phys /* physical wire */ 214#define ifr_data ifr_ifru.ifru_data /* for use by interface */ 215}; 216.Ed 217.Pp 218Calls which are now deprecated are: 219.Bl -tag -width SIOCGIFBRDADDR 220.It Dv SIOCSIFADDR 221Set interface address for protocol family. Following the address 222assignment, the ``initialization'' routine for 223the interface is called. 224.It Dv SIOCSIFDSTADDR 225Set point to point address for protocol family and interface. 226.It Dv SIOCSIFBRDADDR 227Set broadcast address for protocol family and interface. 228.El 229.Pp 230.Fn Ioctl 231requests to obtain addresses and requests both to set and 232retrieve other data are still fully supported 233and use the 234.Vt ifreq 235structure: 236.Bl -tag -width SIOCGIFBRDADDR 237.It Dv SIOCGIFADDR 238Get interface address for protocol family. 239.It Dv SIOCGIFDSTADDR 240Get point to point address for protocol family and interface. 241.It Dv SIOCGIFBRDADDR 242Get broadcast address for protocol family and interface. 243.It Dv SIOCSIFFLAGS 244Set interface flags field. If the interface is marked down, 245any processes currently routing packets through the interface 246are notified; 247some interfaces may be reset so that incoming packets are no longer received. 248When marked up again, the interface is reinitialized. 249.It Dv SIOCGIFFLAGS 250Get interface flags. 251.It Dv SIOCSIFMETRIC 252Set interface routing metric. 253The metric is used only by user-level routers. 254.It Dv SIOCGIFMETRIC 255Get interface metric. 256.It Dv SIOCIFCREATE 257Attempt to create the specified interface. 258If the interface name is given without a unit number the system 259will attempt to create a new interface with an arbitrary unit number. 260On successful return the 261.Va ifr_name 262field will contain the new interface name. 263.It Dv SIOCIFDESTROY 264Attempt to destroy the specified interface. 265.El 266.Pp 267There are two requests that make use of a new structure: 268.Bl -tag -width SIOCGIFBRDADDR 269.It Dv SIOCAIFADDR 270An interface may have more than one address associated with it 271in some protocols. This request provides a means to 272add additional addresses (or modify characteristics of the 273primary address if the default address for the address family 274is specified). Rather than making separate calls to 275set destination or broadcast addresses, or network masks 276(now an integral feature of multiple protocols) 277a separate structure is used to specify all three facets simultaneously 278(see below). 279One would use a slightly tailored version of this struct specific 280to each family (replacing each sockaddr by one 281of the family-specific type). 282Where the sockaddr itself is larger than the 283default size, one needs to modify the 284.Fn ioctl 285identifier itself to include the total size, as described in 286.Fn ioctl . 287.It Dv SIOCDIFADDR 288This requests deletes the specified address from the list 289associated with an interface. It also uses the 290.Vt ifaliasreq 291structure to allow for the possibility of protocols allowing 292multiple masks or destination addresses, and also adopts the 293convention that specification of the default address means 294to delete the first address for the interface belonging to 295the address family in which the original socket was opened. 296.It Dv SIOCGIFCONF 297Get interface configuration list. This request takes an 298.Vt ifconf 299structure (see below) as a value-result parameter. The 300.Va ifc_len 301field should be initially set to the size of the buffer 302pointed to by 303.Va ifc_buf . 304On return it will contain the length, in bytes, of the 305configuration list. 306.It Dv SIOCIFGCLONERS 307Get list of clonable interfaces. 308This request takes an 309.Vt if_clonereq 310structure (see below) as a value-result parameter. 311The 312.Va ifcr_count 313field should be set to the number of 314.Dv IFNAMSIZ 315sized strings that can be fit in the buffer pointed to by 316.Va ifcr_buffer . 317On return, 318.Va ifcr_total 319will be set to the number of clonable interfaces and the buffer pointed 320to by 321.Va ifcr_buffer 322will be filled with the names of clonable interfaces aligned on 323.Dv IFNAMSIZ 324boundaries. 325.El 326.Bd -literal 327/* 328* Structure used in SIOCAIFCONF request. 329*/ 330struct ifaliasreq { 331 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 332 struct sockaddr ifra_addr; 333 struct sockaddr ifra_broadaddr; 334 struct sockaddr ifra_mask; 335}; 336.Ed 337.Pp 338.Bd -literal 339/* 340* Structure used in SIOCGIFCONF request. 341* Used to retrieve interface configuration 342* for machine (useful for programs which 343* must know all networks accessible). 344*/ 345struct ifconf { 346 int ifc_len; /* size of associated buffer */ 347 union { 348 caddr_t ifcu_buf; 349 struct ifreq *ifcu_req; 350 } ifc_ifcu; 351#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 352#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 353}; 354.Ed 355.Pp 356.Bd -literal 357/* Structure used in SIOCIFGCLONERS request. */ 358struct if_clonereq { 359 int ifcr_total; /* total cloners (out) */ 360 int ifcr_count; /* room for this many in user buffer */ 361 char *ifcr_buffer; /* buffer for cloner names */ 362}; 363.Ed 364.Sh SEE ALSO 365.Xr ioctl 2 , 366.Xr socket 2 , 367.Xr intro 4 , 368.Xr config 8 , 369.Xr routed 8 370.Sh HISTORY 371The 372.Nm netintro 373manual appeared in 374.Bx 4.3 tahoe . 375