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.10 (Berkeley) 03/28/91 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 81.Tn DARPA 82Internet 83protocols, the Xerox Network Systems(tm) protocols, 84and some of the 85.Tn ISO OSI 86protocols. 87Raw socket interfaces are provided to the 88.Tn IP 89protocol 90layer of the 91.Tn DARPA 92Internet, to the 93.Tn IMP 94link layer (1822), and to 95the 96.Tn IDP 97protocol of Xerox 98.Tn NS . 99Consult the appropriate manual pages in this section for more 100information regarding the support for each protocol family. 101.Sh ADDRESSING 102Associated with each protocol family is an address 103format. All network address adhere to a general structure, 104called a sockaddr, described below. However, each protocol 105imposes finer and more specific structure, generally renaming 106the variant, which is discussed in the protocol family manual 107page alluded to above. 108.Bd -literal -offset indent 109 struct sockaddr { 110 u_char sa_len; 111 u_char sa_family; 112 char sa_data[14]; 113}; 114.Ed 115.Pp 116The field 117.Ar sa_len 118contains the total length of the of the structure, 119which may exceed 16 bytes. 120The following address values for 121.Ar sa_family 122are known to the system 123(and additional formats are defined for possible future implementation): 124.Bd -literal 125#define AF_UNIX 1 /* local to host (pipes, portals) */ 126#define AF_INET 2 /* internetwork: UDP, TCP, etc. */ 127#define AF_IMPLINK 3 /* arpanet imp addresses */ 128#define AF_NS 6 /* Xerox NS protocols */ 129#define AF_CCITT 10 /* CCITT protocols, X.25 etc */ 130#define AF_HYLINK 15 /* NSC Hyperchannel */ 131#define AF_ISO 18 /* ISO protocols */ 132.Ed 133.Sh ROUTING 134.Tn UNIX 135provides some packet routing facilities. 136The kernel maintains a routing information database, which 137is used in selecting the appropriate network interface when 138transmitting packets. 139.Pp 140A user process (or possibly multiple co-operating processes) 141maintains this database by sending messages over a special kind 142of socket. 143This supplants fixed size 144.Xr ioctl 2 145used in earlier releases. 146.Pp 147This facility is described in 148.Xr route 4 . 149.Sh INTERFACES 150Each network interface in a system corresponds to a 151path through which messages may be sent and received. A network 152interface usually has a hardware device associated with it, though 153certain interfaces such as the loopback interface, 154.Xr lo 4 , 155do not. 156.Pp 157The following 158.Xr ioctl 159calls may be used to manipulate network interfaces. 160The 161.Xr ioctl 162is made on a socket (typically of type 163.Dv SOCK_DGRAM ) 164in the desired domain. 165Most of the requests supported in earlier releases 166take an 167.Ar ifreq 168structure as its parameter. This structure has the form 169.Bd -literal 170struct ifreq { 171#define IFNAMSIZ 16 172 char ifr_name[IFNAMSIZE]; /* if name, e.g. "en0" */ 173 union { 174 struct sockaddr ifru_addr; 175 struct sockaddr ifru_dstaddr; 176 struct sockaddr ifru_broadaddr; 177 short ifru_flags; 178 int ifru_metric; 179 caddr_t ifru_data; 180 } ifr_ifru; 181#define ifr_addr ifr_ifru.ifru_addr /* address */ 182#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ 183#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ 184#define ifr_flags ifr_ifru.ifru_flags /* flags */ 185#define ifr_metric ifr_ifru.ifru_metric /* metric */ 186#define ifr_data ifr_ifru.ifru_data /* for use by interface */ 187}; 188.Ed 189.Pp 190Calls which are now deprecated are: 191.Bl -tag -width SIOCGIFBRDADDR 192.It Dv SIOCSIFADDR 193Set interface address for protocol family. Following the address 194assignment, the ``initialization'' routine for 195the interface is called. 196.It Dv SIOCSIFDSTADDR 197Set point to point address for protocol family and interface. 198.It Dv SIOCSIFBRDADDR 199Set broadcast address for protocol family and interface. 200.El 201.Pp 202.Xr Ioctl 203requests to obtain addresses and requests both to set and 204retreive other data are still fully supported 205and use the 206.Ar ifreq 207structure: 208.Bl -tag -width SIOCGIFBRDADDR 209.It Dv SIOCGIFADDR 210Get interface address for protocol family. 211.It Dv SIOCGIFDSTADDR 212Get point to point address for protocol family and interface. 213.It Dv SIOCGIFBRDADDR 214Get broadcast address for protocol family and interface. 215.It Dv SIOCSIFFLAGS 216Set interface flags field. If the interface is marked down, 217any processes currently routing packets through the interface 218are notified; 219some interfaces may be reset so that incoming packets are no longer received. 220When marked up again, the interface is reinitialized. 221.It Dv SIOCGIFFLAGS 222Get interface flags. 223.It Dv SIOCSIFMETRIC 224Set interface routing metric. 225The metric is used only by user-level routers. 226.It Dv SIOCGIFMETRIC 227Get interface metric. 228.El 229.Pp 230There are two requests that make use of a new structure: 231.Bl -tag -width SIOCGIFBRDADDR 232.It Dv SIOCAIFADDR 233An interface may have more than one address associated with it 234in some protocols. This request provides a means to 235add additional addresses (or modify characteristics of the 236primary address if the default address for the address family 237is specified). Rather than making separate calls to 238set destination or broadcast addresses, or network masks 239(now an integral feature of multiple protocols) 240a separate structure is used to specify all three facets simultaneously 241(see below). 242One would use a slightly tailored version of this struct specific 243to each family (replacing each sockaddr by one 244of the family-specific type). 245Where the sockaddr itself is larger than the 246default size, one needs to modify the 247.Xr ioctl 248identifier itself to include the total size, as described in 249.Xr ioctl . 250.It Dv SIOCDIFADDR 251This requests deletes the specified address from the list 252associated with an interface. It also uses the 253.Ar if_aliasreq 254structure to allow for the possibility of protocols allowing 255multiple masks or destination addresses, and also adopts the 256convention that specification of the default address means 257to delete the first address for the interface belonging to 258the address family in which the original socket was opened. 259.It Dv SIOCGIFCONF 260Get interface configuration list. This request takes an 261.Ar ifconf 262structure (see below) as a value-result parameter. The 263.Ar ifc_len 264field should be initially set to the size of the buffer 265pointed to by 266.Ar ifc_buf . 267On return it will contain the length, in bytes, of the 268configuration list. 269.El 270.Bd -literal 271/* 272* Structure used in SIOCAIFCONF request. 273*/ 274struct ifaliasreq { 275 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 276 struct sockaddr ifra_addr; 277 struct sockaddr ifra_broadaddr; 278 struct sockaddr ifra_mask; 279}; 280.Ed 281.Pp 282.Bd -literal 283/* 284* Structure used in SIOCGIFCONF request. 285* Used to retrieve interface configuration 286* for machine (useful for programs which 287* must know all networks accessible). 288*/ 289struct ifconf { 290 int ifc_len; /* size of associated buffer */ 291 union { 292 caddr_t ifcu_buf; 293 struct ifreq *ifcu_req; 294 } ifc_ifcu; 295#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 296#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 297}; 298.Ed 299.Sh SEE ALSO 300.Xr socket 2 , 301.Xr ioctl 2 , 302.Xr intro 4 , 303.Xr config 8 , 304.Xr routed 8 305.Sh HISTORY 306The 307.Nm netintro 308manual appeared in 309.Bx 4.3 tahoe . 310