1.\" $NetBSD: netintro.4,v 1.4 1995/10/19 08:03:40 jtc Exp $ 2.\" 3.\" Copyright (c) 1983, 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)netintro.4 8.2 (Berkeley) 11/30/93 35.\" 36.Dd November 30, 1993 37.Dt NETINTRO 4 38.Os BSD 4.2 39.Sh NAME 40.Nm networking 41.Nd introduction to networking facilities 42.Sh SYNOPSIS 43.Fd #include <sys/socket.h> 44.Fd #include <net/route.h> 45.Fd #include <net/if.h> 46.Sh DESCRIPTION 47This section is a general introduction to the networking facilities 48available in the system. 49Documentation in this part of section 504 is broken up into three areas: 51.Em protocol families 52(domains), 53.Em protocols , 54and 55.Em network interfaces . 56.Pp 57All network protocols are associated with a specific 58.Em protocol family . 59A protocol family provides basic services to the protocol 60implementation to allow it to function within a specific 61network environment. These services may include 62packet fragmentation and reassembly, routing, addressing, and 63basic transport. A protocol family may support multiple 64methods of addressing, though the current protocol implementations 65do not. A protocol family is normally comprised of a number 66of protocols, one per 67.Xr socket 2 68type. It is not required that a protocol family support 69all socket types. A protocol family may contain multiple 70protocols supporting the same socket abstraction. 71.Pp 72A protocol supports one of the socket abstractions detailed in 73.Xr socket 2 . 74A specific protocol may be accessed either by creating a 75socket of the appropriate type and protocol family, or 76by requesting the protocol explicitly when creating a socket. 77Protocols normally accept only one type of address format, 78usually determined by the addressing structure inherent in 79the design of the protocol family/network architecture. 80Certain semantics of the basic socket abstractions are 81protocol specific. All protocols are expected to support 82the basic model for their particular socket type, but may, 83in addition, provide non-standard facilities or extensions 84to a mechanism. For example, a protocol supporting the 85.Dv SOCK_STREAM 86abstraction may allow more than one byte of out-of-band 87data to be transmitted per out-of-band message. 88.Pp 89A network interface is similar to a device interface. 90Network interfaces comprise the lowest layer of the 91networking subsystem, interacting with the actual transport 92hardware. An interface may support one or more protocol 93families and/or address formats. 94The SYNOPSIS section of each network interface 95entry gives a sample specification 96of the related drivers for use in providing 97a system description to the 98.Xr config 8 99program. 100The DIAGNOSTICS section lists messages which may appear on the console 101and/or in the system error log, 102.Pa /var/log/messages 103(see 104.Xr syslogd 8 ) , 105due to errors in device operation. 106.Sh PROTOCOLS 107The system currently supports the 108Internet 109protocols, the Xerox Network Systems(tm) protocols, 110and some of the 111.Tn ISO OSI 112protocols. 113Raw socket interfaces are provided to the 114.Tn IP 115protocol 116layer of the 117Internet, and to the 118.Tn IDP 119protocol of Xerox 120.Tn NS . 121Consult the appropriate manual pages in this section for more 122information regarding the support for each protocol family. 123.Sh ADDRESSING 124Associated with each protocol family is an address 125format. All network address adhere to a general structure, 126called a sockaddr, described below. However, each protocol 127imposes finer and more specific structure, generally renaming 128the variant, which is discussed in the protocol family manual 129page alluded to above. 130.Bd -literal -offset indent 131 struct sockaddr { 132 u_char sa_len; 133 u_char sa_family; 134 char sa_data[14]; 135}; 136.Ed 137.Pp 138The field 139.Ar sa_len 140contains the total length of the structure, 141which may exceed 16 bytes. 142The following address values for 143.Ar sa_family 144are known to the system 145(and additional formats are defined for possible future implementation): 146.Bd -literal 147#define AF_UNIX 1 /* local to host (pipes) */ 148#define AF_INET 2 /* IPv4: UDP, TCP, etc. */ 149#define AF_INET6 30 /* IPv6: UDP, TCP, etc. */ 150#define AF_NS 6 /* Xerox NS protocols */ 151#define AF_CCITT 10 /* CCITT protocols, X.25 etc */ 152#define AF_HYLINK 15 /* NSC Hyperchannel */ 153#define AF_ISO 18 /* ISO protocols */ 154#define AF_VSOCK 40 /* VM Sockets */ 155.Ed 156.Sh ROUTING 157Mac OS X provides some packet routing facilities. 158The kernel maintains a routing information database, which 159is used in selecting the appropriate network interface when 160transmitting packets. 161.Pp 162A user process (or possibly multiple co-operating processes) 163maintains this database by sending messages over a special kind 164of socket. 165This supplants fixed size 166.Xr ioctl 2 167used in earlier releases. 168.Pp 169This facility is described in 170.Xr route 4 . 171.Sh INTERFACES 172Each network interface in a system corresponds to a 173path through which messages may be sent and received. A network 174interface usually has a hardware device associated with it, though 175certain interfaces such as the loopback interface, 176.Xr lo 4 , 177do not. 178.Pp 179The following 180.Xr ioctl 181calls may be used to manipulate network interfaces. 182The 183.Xr ioctl 184is made on a socket (typically of type 185.Dv SOCK_DGRAM ) 186in the desired domain. 187Most of the requests supported in earlier releases 188take an 189.Ar ifreq 190structure as its parameter. This structure has the form 191.Bd -literal 192struct ifreq { 193#define IFNAMSIZ 16 194 char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 195 union { 196 struct sockaddr ifru_addr; 197 struct sockaddr ifru_dstaddr; 198 struct sockaddr ifru_broadaddr; 199 short ifru_flags; 200 int ifru_metric; 201 caddr_t ifru_data; 202 } ifr_ifru; 203#define ifr_addr ifr_ifru.ifru_addr /* address */ 204#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ 205#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ 206#define ifr_flags ifr_ifru.ifru_flags /* flags */ 207#define ifr_metric ifr_ifru.ifru_metric /* metric */ 208#define ifr_data ifr_ifru.ifru_data /* for use by interface */ 209}; 210.Ed 211.Pp 212Calls which are now deprecated are: 213.Bl -tag -width SIOCGIFBRDADDR 214.It Dv SIOCSIFADDR 215Set interface address for protocol family. Following the address 216assignment, the ``initialization'' routine for 217the interface is called. 218.It Dv SIOCSIFDSTADDR 219Set point to point address for protocol family and interface. 220.It Dv SIOCSIFBRDADDR 221Set broadcast address for protocol family and interface. 222.El 223.Pp 224.Xr Ioctl 225requests to obtain addresses and requests both to set and 226retrieve other data are still fully supported 227and use the 228.Ar ifreq 229structure: 230.Bl -tag -width SIOCGIFBRDADDR 231.It Dv SIOCGIFADDR 232Get interface address for protocol family. 233.It Dv SIOCGIFDSTADDR 234Get point to point address for protocol family and interface. 235.It Dv SIOCGIFBRDADDR 236Get broadcast address for protocol family and interface. 237.It Dv SIOCSIFFLAGS 238Set interface flags field. If the interface is marked down, 239any processes currently routing packets through the interface 240are notified; 241some interfaces may be reset so that incoming packets are no longer received. 242When marked up again, the interface is reinitialized. 243.It Dv SIOCGIFFLAGS 244Get interface flags. 245.It Dv SIOCSIFMETRIC 246Set interface routing metric. 247The metric is used only by user-level routers. 248.It Dv SIOCGIFMETRIC 249Get interface metric. 250.El 251.Pp 252There are requests that make use of a different structure: 253.Bl -tag -width SIOCGIFBRDADDR 254.It Dv SIOCAIFADDR 255An interface may have more than one address associated with it 256in some protocols. This request provides a means to 257add additional addresses (or modify characteristics of the 258primary address if the default address for the address family 259is specified). Rather than making separate calls to 260set destination or broadcast addresses, or network masks 261(now an integral feature of multiple protocols) 262a separate structure is used to specify all three facets simultaneously 263(see below). 264One would use a slightly tailored version of this struct specific 265to each family (replacing each sockaddr by one 266of the family-specific type). 267Where the sockaddr itself is larger than the 268default size, one needs to modify the 269.Xr ioctl 270identifier itself to include the total size, as described in 271.Xr ioctl . 272.It Dv SIOCDIFADDR 273This requests deletes the specified address from the list 274associated with an interface. It uses the 275.Ar ifreq 276structure for protocols like 277.Dv PF_INET 278whose 279address fit in the 280.Ar sockaddr 281structure. 282Protocols like 283.Dv PF_INET6 284with addresses that do not fit in the 285.Ar sockaddr 286structure 287must have a variant of that request. 288.It Dv SIOCGIFCONF 289Get interface configuration list. This request takes an 290.Ar ifconf 291structure (see below) as a value-result parameter. The 292.Ar ifc_len 293field should be initially set to the size of the buffer 294pointed to by 295.Ar ifc_buf . 296On return it will contain the length, in bytes, of the 297configuration list. 298.El 299.Bd -literal 300/* 301* Structure used in SIOCAIFADDR request. 302*/ 303struct ifaliasreq { 304 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 305 struct sockaddr ifra_addr; 306 struct sockaddr ifra_broadaddr; 307 struct sockaddr ifra_mask; 308}; 309.Ed 310.Pp 311.Bd -literal 312/* 313* Structure used in SIOCGIFCONF request. 314* Used to retrieve interface configuration 315* for machine (useful for programs which 316* must know all networks accessible). 317*/ 318struct ifconf { 319 int ifc_len; /* size of associated buffer */ 320 union { 321 caddr_t ifcu_buf; 322 struct ifreq *ifcu_req; 323 } ifc_ifcu; 324#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 325#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 326}; 327.Ed 328.Sh SEE ALSO 329.Xr ioctl 2 , 330.Xr socket 2 , 331.Xr intro 4 , 332.Xr config 5 , 333.Xr routed 8 334.Sh HISTORY 335The 336.Nm netintro 337manual appeared in 338.Bx 4.3 tahoe . 339