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