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