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