1.\" $OpenBSD: netintro.4,v 1.28 2004/08/21 21:58:15 jaredy Exp $ 2.\" $NetBSD: netintro.4,v 1.4 1995/10/19 08:03:40 jtc Exp $ 3.\" 4.\" Copyright (c) 1983, 1990, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)netintro.4 8.2 (Berkeley) 11/30/93 32.\" 33.Dd September 3, 1994 34.Dt NETINTRO 4 35.Os 36.Sh NAME 37.Nm netintro 38.Nd introduction to networking facilities 39.Sh SYNOPSIS 40.Fd #include <sys/socket.h> 41.Fd #include <net/route.h> 42.Fd #include <net/if.h> 43.Sh DESCRIPTION 44This section is a general introduction to the networking facilities 45available in the system. 46Documentation in this part of section 474 is broken up into three areas: 48.Em protocol families 49(domains), 50.Em protocols , 51and 52.Em network interfaces . 53.Pp 54All network protocols are associated with a specific 55.Em protocol family . 56A protocol family provides basic services to the protocol 57implementation to allow it to function within a specific 58network environment. 59These services may include packet fragmentation and reassembly, routing, 60addressing, and basic transport. 61A protocol family may support multiple methods of addressing, though 62the current protocol implementations do not. 63A protocol family is normally comprised of a number of protocols, one per 64.Xr socket 2 65type. 66It is not required that a protocol family support all socket types. 67A protocol family may contain multiple protocols supporting the same socket 68abstraction. 69.Pp 70A protocol supports one of the socket abstractions detailed in 71.Xr socket 2 . 72A specific protocol may be accessed either by creating a 73socket of the appropriate type and protocol family, or 74by requesting the protocol explicitly when creating a socket. 75Protocols normally accept only one type of address format, 76usually determined by the addressing structure inherent in 77the design of the protocol family/network architecture. 78Certain semantics of the basic socket abstractions are 79protocol specific. 80All protocols are expected to support the basic model for their particular 81socket type, but may, in addition, provide non-standard facilities or 82extensions to a mechanism. 83For example, a protocol supporting the 84.Dv SOCK_STREAM 85abstraction may allow more than one byte of out-of-band 86data to be transmitted per out-of-band message. 87.Pp 88A network interface is similar to a device interface. 89Network interfaces comprise the lowest layer of the 90networking subsystem, interacting with the actual transport 91hardware. 92An interface may support one or more protocol families and/or address formats. 93The 94.Sx SYNOPSIS 95section of each network interface entry gives a sample 96specification of the related drivers for use in providing a system description 97to the 98.Xr config 8 99program. 100The 101.Sx DIAGNOSTICS 102section 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.Pp 109Network interfaces may be collected together into interface groups. 110An interface group is a container that can be used generically when 111referring to any interface related by some criteria. 112Interfaces may be a member of any number of interface groups. 113All interfaces are members of their interface family group by default. 114For example, a PPP interface such as 115.Li ppp0 116is a member of the PPP interface family group, 117.Li ppp . 118When an action is performed on an interface group, such as packet 119filtering by the 120.Xr pf 4 121subsystem, the operation will be applied to each member interface in the 122group, if supported by the subsystem. 123The 124.Xr ifconfig 8 125utility can be used to view and assign membership of an interface to an 126interface group with the 127.Cm group 128modifier. 129.Sh PROTOCOLS 130The system currently supports the 131Internet protocols (IPv4 and IPv6), 132the Xerox Network Systems(tm) protocols, 133CCITT, Appletalk, Novell's IPX protocols, 134and a few others. 135Raw socket interfaces are provided to the 136.Tn IP 137protocol 138layer of the 139Internet, and to the 140.Tn IDP 141protocol of Xerox 142.Tn NS . 143Consult the appropriate manual pages in this section for more 144information regarding the support for each protocol family. 145.Sh ADDRESSING 146Associated with each protocol family is an address 147format. 148All network addresses adhere to a general structure, called a 149.Vt sockaddr , 150described below. 151However, each protocol imposes a finer, more specific structure, generally 152renaming the variant, which is discussed in the protocol family manual 153page alluded to above. 154.Bd -literal -offset indent 155struct sockaddr { 156 u_int8_t sa_len; /* total length */ 157 sa_family_t sa_family; /* address family */ 158 char sa_data[14]; /* actually longer */ 159}; 160.Ed 161.Pp 162The field 163.Va sa_len 164contains the total length of the structure, 165which may exceed 16 bytes. 166The following address values for 167.Va sa_family 168are known to the system 169(and additional formats are defined for possible future implementation): 170.Bd -literal 171#define AF_LOCAL 1 /* local to host (pipes, portals) */ 172#define AF_INET 2 /* internetwork: UDP, TCP, etc. */ 173#define AF_NS 6 /* Xerox NS protocols */ 174#define AF_CCITT 10 /* CCITT protocols, X.25 etc */ 175#define AF_HYLINK 15 /* NSC Hyperchannel */ 176#define AF_APPLETALK 16 /* AppleTalk */ 177#define AF_IPX 23 /* Novell Internet Protocol */ 178#define AF_INET6 24 /* IPv6 */ 179#define AF_NATM 27 /* native ATM access */ 180.Ed 181.Pp 182The 183.Va sa_data 184field contains the actual address value. 185Note that it may be longer than 14 bytes. 186.Sh ROUTING 187.Ox 188provides some packet routing facilities. 189The kernel maintains a routing information database, which 190is used in selecting the appropriate network interface when 191transmitting packets. 192.Pp 193A user process (or possibly multiple co-operating processes) 194maintains this database by sending messages over a special kind 195of socket. 196This supplants fixed-size 197.Xr ioctl 2 's 198used in earlier releases. 199.Pp 200This facility is described in 201.Xr route 4 . 202.Sh INTERFACES 203Each network interface in a system corresponds to a 204path through which messages may be sent and received. 205A network interface usually has a hardware device associated with it, 206though certain interfaces such as the loopback interface, 207.Xr lo 4 , 208do not. 209.Pp 210The following 211.Xr ioctl 2 212calls may be used to manipulate network interfaces. 213The 214.Xr ioctl 2 215is made on a socket (typically of type 216.Dv SOCK_DGRAM ) 217in the desired domain. 218Most of the requests 219take an 220.Vt ifreq 221structure pointer as their parameter. 222This structure is as follows: 223.Bd -literal 224struct ifreq { 225#define IFNAMSIZ 16 226 char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 227 union { 228 struct sockaddr ifru_addr; 229 struct sockaddr ifru_dstaddr; 230 struct sockaddr ifru_broadaddr; 231 short ifru_flags; 232 int ifru_metric; 233 caddr_t ifru_data; 234 } ifr_ifru; 235#define ifr_addr ifr_ifru.ifru_addr /* address */ 236#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* p-to-p peer */ 237#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ 238#define ifr_flags ifr_ifru.ifru_flags /* flags */ 239#define ifr_metric ifr_ifru.ifru_metric /* metric */ 240#define ifr_mtu ifr_ifru.ifru_metric /* mtu (overload) */ 241#define ifr_media ifr_ifru.ifru_metric /* media options */ 242#define ifr_data ifr_ifru.ifru_data /* used by interface */ 243}; 244.Ed 245.Pp 246The supported 247.Xr ioctl 2 248requests are: 249.Bl -tag -width Ds 250.It Dv SIOCSIFADDR Fa "struct ifreq *" 251Set the interface address for a protocol family. 252Following the address assignment, the 253.Dq initialization 254routine for the 255interface is called. 256.Pp 257This call has been deprecated and superceded by the 258.Dv SIOCAIFADDR 259call, described below. 260.It Dv SIOCSIFDSTADDR Fa "struct ifreq *" 261Set the point-to-point address for a protocol family and interface. 262.Pp 263This call has been deprecated and superceded by the 264.Dv SIOCAIFADDR 265call, described below. 266.It Dv SIOCSIFBRDADDR Fa "struct ifreq *" 267Set the broadcast address for a protocol family and interface. 268.Pp 269This call has been deprecated and superceded by the 270.Dv SIOCAIFADDR 271call, described below. 272.It Dv SIOCGIFADDR Fa "struct ifreq *" 273Get the interface address for a protocol family. 274.It Dv SIOCGIFDSTADDR Fa "struct ifreq *" 275Get the point-to-point address for a protocol family and interface. 276.It Dv SIOCGIFBRDADDR Fa "struct ifreq *" 277Get the broadcast address for a protocol family and interface. 278.It Dv SIOCGIFDESCR Fa "struct ifreq *" 279Get the interface description, returned in the 280.Va ifru_data 281field. 282.It Dv SIOCSIFDESCR Fa "struct ifreq *" 283Set the interface description to the value of the 284.Va ifru_data 285field, limited to the size of 286.Dv IFDESCRSIZE . 287.It Dv SIOCSIFFLAGS Fa "struct ifreq *" 288Set the interface flags. 289If the interface is marked down, any processes currently routing packets 290through the interface are notified; some interfaces may be reset so that 291incoming packets are no longer received. 292When marked up again, the interface is reinitialized. 293.It Dv SIOCGIFFLAGS Fa "struct ifreq *" 294Get the interface flags. 295.It Dv SIOCSIFMEDIA Fa "struct ifreq *" 296Set the interface media settings. 297See 298.Xr ifmedia 4 299for possible values. 300.It Dv SIOCGIFMEDIA Fa "struct ifmediareq *" 301Get the interface media settings. 302The 303.Vt ifmediareq 304structure is as follows: 305.Bd -literal 306struct ifmediareq { 307 char ifm_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 308 int ifm_current; /* current media options */ 309 int ifm_mask; /* don't care mask */ 310 int ifm_status; /* media status */ 311 int ifm_active; /* active options */ 312 int ifm_count; /* #entries in ifm_ulist array */ 313 int *ifm_ulist; /* media words */ 314}; 315.Ed 316.Pp 317See 318.Xr ifmedia 4 319for interpreting this value. 320.It Dv SIOCSIFMETRIC Fa "struct ifreq *" 321Set the interface routing metric. 322The metric is used only by user-level routers. 323.It Dv SIOCGIFMETRIC Fa "struct ifreq *" 324Get the interface metric. 325.It Dv SIOCAIFADDR Fa "struct ifaliasreq *" 326An interface may have more than one address associated with it 327in some protocols. 328This request provides a means to add additional addresses (or modify 329characteristics of the primary address if the default address for the 330address family is specified). 331.Pp 332Rather than making separate calls to set destination or broadcast addresses, 333or network masks (now an integral feature of multiple protocols), a separate 334structure, 335.Vt ifaliasreq , 336is used to specify all three facets simultaneously (see below). 337One would use a slightly tailored version of this structure specific 338to each family (replacing each 339.Vt sockaddr 340by one 341of the family-specific type). 342One should always set the length of a 343.Vt sockaddr , 344as described in 345.Xr ioctl 2 . 346.Pp 347The 348.Vt ifaliasreq 349structure is as follows: 350.Bd -literal 351struct ifaliasreq { 352 char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ 353 struct sockaddr ifra_addr; 354 struct sockaddr ifra_dstaddr; 355#define ifra_broadaddr ifra_dstaddr 356 struct sockaddr ifra_mask; 357}; 358.Ed 359.It Dv SIOCDIFADDR Fa "struct ifreq *" 360This request deletes the specified address from the list 361associated with an interface. 362It also uses the 363.Vt ifaliasreq 364structure to allow for the possibility of protocols allowing 365multiple masks or destination addresses, and also adopts the 366convention that specification of the default address means 367to delete the first address for the interface belonging to 368the address family in which the original socket was opened. 369.It Dv SIOCGIFCONF Fa "struct ifconf *" 370Get the interface configuration list. 371This request takes an 372.Vt ifconf 373structure (see below) as a value-result parameter. 374The 375.Va ifc_len 376field should be initially set to the size of the buffer 377pointed to by 378.Va ifc_buf . 379On return it will contain the length, in bytes, of the 380configuration list. 381.Pp 382Alternately, if the 383.Va ifc_len 384passed in is set to 0, 385.Dv SIOCGIFCONF 386will set 387.Va ifc_len 388to the size that 389.Va ifc_buf 390needs to be to fit the entire configuration list and will not 391fill in the other parameters. 392This is useful for determining the exact size that 393.Va ifc_buf 394needs to be in advance. 395Note, however, that this is an extension 396that not all operating systems support. 397.Bd -literal 398struct ifconf { 399 int ifc_len; /* size of associated buffer */ 400 union { 401 caddr_t ifcu_buf; 402 struct ifreq *ifcu_req; 403 } ifc_ifcu; 404#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 405#define ifc_req ifc_ifcu.ifcu_req /* array of structures ret'd */ 406}; 407.Ed 408.It Dv SIOCIFCREATE Fa "struct ifreq *" 409Attempt to create the specified interface. 410.It Dv SIOCIFDESTROY Fa "struct ifreq *" 411Attempt to destroy the specified interface. 412.It Dv SIOCIFGCLONERS Fa "struct if_clonereq *" 413Get the list of clonable interfaces. 414This request takes an 415.Vt if_clonereq 416structure pointer (see below) as a value-result parameter. 417The 418.Va ifcr_count 419field should be set to the number of 420.Dv IFNAMSIZ Ns -sized 421strings that can fit in the buffer pointed to by 422.Va ifcr_buffer . 423On return, 424.Va ifcr_total 425will be set to the number of clonable interfaces, and the buffer pointed 426to by 427.Va ifcr_buffer 428will be filled with the names of clonable interfaces aligned on 429.Dv IFNAMSIZ 430boundaries. 431.Pp 432The 433.Vt if_clonereq 434structure is as follows: 435.Bd -literal 436struct if_clonereq { 437 int ifcr_total; /* total cloners (out) */ 438 int ifcr_count; /* room for this many in user buf */ 439 char *ifcr_buffer; /* buffer for cloner names */ 440}; 441.Ed 442.It Dv SIOCAIFGROUP Fa "struct ifgroupreq *" 443Associate the interface named by 444.Va ifgr_name 445with the interface group named by 446.Va ifgr_group . 447The 448.Vt ifgroupreq 449structure is as follows: 450.Bd -literal 451struct ifgroupreq { 452 char ifgr_name[IFNAMSIZ]; 453 u_int ifgr_len; 454 union { 455 char ifgru_group[IFNAMSIZ]; 456 struct ifgroup *ifgru_groups; 457 } ifgr_ifgru; 458#define ifgr_group ifgr_ifgru.ifgru_group 459#define ifgr_groups ifgr_ifgru.ifgru_groups 460}; 461.Ed 462.It Dv SIOCGIFGROUP Fa "struct ifgroupreq *" 463Retrieve the list of groups for which an interface is a member. 464The interface is named by 465.Va ifgr_name . 466On enter, the amount of memory in which the group names will 467be written is stored in 468.Va ifgr_len , 469and the group names themselves will be written to the memory 470pointed to by 471.Va ifgr_groups . 472On return, the amount of memory actually written is returned in 473.Va ifgr_len . 474.Pp 475Alternately, if the 476.Va ifgr_len 477passed in is set to 0, 478.Dv SIOCGIFGROUP 479will set 480.Va ifgr_len 481to the size that 482.Va ifgr_groups 483needs to be to fit the entire group list and will not 484fill in the other parameters. 485This is useful for determining the exact size that 486.Va ifgr_groups 487needs to be in advance. 488.It Dv SIOCDIFGROUP Fa "struct ifgroupreq *" 489Remove the membership of the interface named by 490.Va ifgr_name 491from the group 492.Va ifgr_group . 493.El 494.Sh SEE ALSO 495.Xr netstat 1 , 496.Xr ioctl 2 , 497.Xr socket 2 , 498.Xr inet 3 , 499.Xr ipx 3 , 500.Xr arp 4 , 501.Xr bridge 4 , 502.Xr ifmedia 4 , 503.Xr inet 4 , 504.Xr intro 4 , 505.Xr ip 4 , 506.Xr ip6 4 , 507.Xr lo 4 , 508.Xr pf 4 , 509.Xr tcp 4 , 510.Xr udp 4 , 511.Xr hosts 5 , 512.Xr networks 5 , 513.Xr config 8 , 514.Xr ifconfig 8 , 515.Xr netstart 8 , 516.Xr route 8 , 517.Xr routed 8 518.Sh HISTORY 519The 520.Nm 521manual appeared in 522.Bx 4.3 Tahoe . 523