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