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