diff options
Diffstat (limited to 'share/man/man4/netintro.4')
| -rw-r--r-- | share/man/man4/netintro.4 | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/share/man/man4/netintro.4 b/share/man/man4/netintro.4 new file mode 100644 index 00000000000..062104385e4 --- /dev/null +++ b/share/man/man4/netintro.4 @@ -0,0 +1,330 @@ +.\" $NetBSD: netintro.4,v 1.3 1994/11/30 16:22:24 jtc Exp $ +.\" +.\" Copyright (c) 1983, 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)netintro.4 8.2 (Berkeley) 11/30/93 +.\" +.Dd November 30, 1993 +.Dt NETINTRO 4 +.Os BSD 4.2 +.Sh NAME +.Nm networking +.Nd introduction to networking facilities +.Sh SYNOPSIS +.Fd #include <sys/socket.h> +.Fd #include <net/route.h> +.Fd #include <net/if.h> +.Sh DESCRIPTION +This section is a general introduction to the networking facilities +available in the system. +Documentation in this part of section +4 is broken up into three areas: +.Em protocol families +(domains), +.Em protocols , +and +.Em network interfaces . +.Pp +All network protocols are associated with a specific +.Em protocol family . +A protocol family provides basic services to the protocol +implementation to allow it to function within a specific +network environment. These services may include +packet fragmentation and reassembly, routing, addressing, and +basic transport. A protocol family may support multiple +methods of addressing, though the current protocol implementations +do not. A protocol family is normally comprised of a number +of protocols, one per +.Xr socket 2 +type. It is not required that a protocol family support +all socket types. A protocol family may contain multiple +protocols supporting the same socket abstraction. +.Pp +A protocol supports one of the socket abstractions detailed in +.Xr socket 2 . +A specific protocol may be accessed either by creating a +socket of the appropriate type and protocol family, or +by requesting the protocol explicitly when creating a socket. +Protocols normally accept only one type of address format, +usually determined by the addressing structure inherent in +the design of the protocol family/network architecture. +Certain semantics of the basic socket abstractions are +protocol specific. All protocols are expected to support +the basic model for their particular socket type, but may, +in addition, provide non-standard facilities or extensions +to a mechanism. For example, a protocol supporting the +.Dv SOCK_STREAM +abstraction may allow more than one byte of out-of-band +data to be transmitted per out-of-band message. +.Pp +A network interface is similar to a device interface. +Network interfaces comprise the lowest layer of the +networking subsystem, interacting with the actual transport +hardware. An interface may support one or more protocol +families and/or address formats. +The SYNOPSIS section of each network interface +entry gives a sample specification +of the related drivers for use in providing +a system description to the +.Xr config 8 +program. +The DIAGNOSTICS section lists messages which may appear on the console +and/or in the system error log, +.Pa /var/log/messages +(see +.Xr syslogd 8 ) , +due to errors in device operation. +.Sh PROTOCOLS +The system currently supports the +Internet +protocols, the Xerox Network Systems(tm) protocols, +and some of the +.Tn ISO OSI +protocols. +Raw socket interfaces are provided to the +.Tn IP +protocol +layer of the +Internet, and to the +.Tn IDP +protocol of Xerox +.Tn NS . +Consult the appropriate manual pages in this section for more +information regarding the support for each protocol family. +.Sh ADDRESSING +Associated with each protocol family is an address +format. All network address adhere to a general structure, +called a sockaddr, described below. However, each protocol +imposes finer and more specific structure, generally renaming +the variant, which is discussed in the protocol family manual +page alluded to above. +.Bd -literal -offset indent + struct sockaddr { + u_char sa_len; + u_char sa_family; + char sa_data[14]; +}; +.Ed +.Pp +The field +.Ar sa_len +contains the total length of the of the structure, +which may exceed 16 bytes. +The following address values for +.Ar sa_family +are known to the system +(and additional formats are defined for possible future implementation): +.Bd -literal +#define AF_UNIX 1 /* local to host (pipes, portals) */ +#define AF_INET 2 /* internetwork: UDP, TCP, etc. */ +#define AF_NS 6 /* Xerox NS protocols */ +#define AF_CCITT 10 /* CCITT protocols, X.25 etc */ +#define AF_HYLINK 15 /* NSC Hyperchannel */ +#define AF_ISO 18 /* ISO protocols */ +.Ed +.Sh ROUTING +.Tn UNIX +provides some packet routing facilities. +The kernel maintains a routing information database, which +is used in selecting the appropriate network interface when +transmitting packets. +.Pp +A user process (or possibly multiple co-operating processes) +maintains this database by sending messages over a special kind +of socket. +This supplants fixed size +.Xr ioctl 2 +used in earlier releases. +.Pp +This facility is described in +.Xr route 4 . +.Sh INTERFACES +Each network interface in a system corresponds to a +path through which messages may be sent and received. A network +interface usually has a hardware device associated with it, though +certain interfaces such as the loopback interface, +.Xr lo 4 , +do not. +.Pp +The following +.Xr ioctl +calls may be used to manipulate network interfaces. +The +.Xr ioctl +is made on a socket (typically of type +.Dv SOCK_DGRAM ) +in the desired domain. +Most of the requests supported in earlier releases +take an +.Ar ifreq +structure as its parameter. This structure has the form +.Bd -literal +struct ifreq { +#define IFNAMSIZ 16 + char ifr_name[IFNAMSIZE]; /* if name, e.g. "en0" */ + union { + struct sockaddr ifru_addr; + struct sockaddr ifru_dstaddr; + struct sockaddr ifru_broadaddr; + short ifru_flags; + int ifru_metric; + caddr_t ifru_data; + } ifr_ifru; +#define ifr_addr ifr_ifru.ifru_addr /* address */ +#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ +#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ +#define ifr_flags ifr_ifru.ifru_flags /* flags */ +#define ifr_metric ifr_ifru.ifru_metric /* metric */ +#define ifr_data ifr_ifru.ifru_data /* for use by interface */ +}; +.Ed +.Pp +Calls which are now deprecated are: +.Bl -tag -width SIOCGIFBRDADDR +.It Dv SIOCSIFADDR +Set interface address for protocol family. Following the address +assignment, the ``initialization'' routine for +the interface is called. +.It Dv SIOCSIFDSTADDR +Set point to point address for protocol family and interface. +.It Dv SIOCSIFBRDADDR +Set broadcast address for protocol family and interface. +.El +.Pp +.Xr Ioctl +requests to obtain addresses and requests both to set and +retrieve other data are still fully supported +and use the +.Ar ifreq +structure: +.Bl -tag -width SIOCGIFBRDADDR +.It Dv SIOCGIFADDR +Get interface address for protocol family. +.It Dv SIOCGIFDSTADDR +Get point to point address for protocol family and interface. +.It Dv SIOCGIFBRDADDR +Get broadcast address for protocol family and interface. +.It Dv SIOCSIFFLAGS +Set interface flags field. If the interface is marked down, +any processes currently routing packets through the interface +are notified; +some interfaces may be reset so that incoming packets are no longer received. +When marked up again, the interface is reinitialized. +.It Dv SIOCGIFFLAGS +Get interface flags. +.It Dv SIOCSIFMETRIC +Set interface routing metric. +The metric is used only by user-level routers. +.It Dv SIOCGIFMETRIC +Get interface metric. +.El +.Pp +There are two requests that make use of a new structure: +.Bl -tag -width SIOCGIFBRDADDR +.It Dv SIOCAIFADDR +An interface may have more than one address associated with it +in some protocols. This request provides a means to +add additional addresses (or modify characteristics of the +primary address if the default address for the address family +is specified). Rather than making separate calls to +set destination or broadcast addresses, or network masks +(now an integral feature of multiple protocols) +a separate structure is used to specify all three facets simultaneously +(see below). +One would use a slightly tailored version of this struct specific +to each family (replacing each sockaddr by one +of the family-specific type). +Where the sockaddr itself is larger than the +default size, one needs to modify the +.Xr ioctl +identifier itself to include the total size, as described in +.Xr ioctl . +.It Dv SIOCDIFADDR +This requests deletes the specified address from the list +associated with an interface. It also uses the +.Ar if_aliasreq +structure to allow for the possibility of protocols allowing +multiple masks or destination addresses, and also adopts the +convention that specification of the default address means +to delete the first address for the interface belonging to +the address family in which the original socket was opened. +.It Dv SIOCGIFCONF +Get interface configuration list. This request takes an +.Ar ifconf +structure (see below) as a value-result parameter. The +.Ar ifc_len +field should be initially set to the size of the buffer +pointed to by +.Ar ifc_buf . +On return it will contain the length, in bytes, of the +configuration list. +.El +.Bd -literal +/* +* Structure used in SIOCAIFCONF request. +*/ +struct ifaliasreq { + char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ + struct sockaddr ifra_addr; + struct sockaddr ifra_broadaddr; + struct sockaddr ifra_mask; +}; +.Ed +.Pp +.Bd -literal +/* +* Structure used in SIOCGIFCONF request. +* Used to retrieve interface configuration +* for machine (useful for programs which +* must know all networks accessible). +*/ +struct ifconf { + int ifc_len; /* size of associated buffer */ + union { + caddr_t ifcu_buf; + struct ifreq *ifcu_req; + } ifc_ifcu; +#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ +#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ +}; +.Ed +.Sh SEE ALSO +.Xr socket 2 , +.Xr ioctl 2 , +.Xr intro 4 , +.Xr config 8 , +.Xr routed 8 +.Sh HISTORY +The +.Nm netintro +manual appeared in +.Bx 4.3 tahoe . |