diff options
Diffstat (limited to 'static/netbsd/man4/netintro.4')
| -rw-r--r-- | static/netbsd/man4/netintro.4 | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/static/netbsd/man4/netintro.4 b/static/netbsd/man4/netintro.4 new file mode 100644 index 00000000..fbe9f0a1 --- /dev/null +++ b/static/netbsd/man4/netintro.4 @@ -0,0 +1,348 @@ +.\" $NetBSD: netintro.4,v 1.30 2018/08/13 05:41:54 wiz 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. 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 August 2, 2018 +.Dt NETINTRO 4 +.Os +.Sh NAME +.Nm netintro +.Nd introduction to networking facilities +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/route.h +.In 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 normally comprises 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 +.Em 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 1 +program. +.Pp +The +.Em 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. +Raw socket interfaces are provided to the +.Tn IP +protocol layer of the Internet. +Consult the appropriate manual pages in this section for more +information regarding the support for a protocol. +.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_LOCAL 1 /* local to host */ +#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_INET6 24 /* internetwork, v6: UDP, TCP, etc. */ +.Ed +.Sh ROUTING +.Ux +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 2 +calls may be used to manipulate network interfaces. +The +.Xr ioctl 2 +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[IFNAMSIZ]; /* if name, e.g. "en0" */ + union { + struct sockaddr ifru_addr; + struct sockaddr ifru_dstaddr; + struct sockaddr ifru_broadaddr; + short ifru_flags; + int ifru_metric; + void *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_space ifr_ifru.ifru_space /* sockaddr_storage */ +#define ifr_flags ifr_ifru.ifru_flags /* flags */ +#define ifr_metric ifr_ifru.ifru_metric /* metric */ +#define ifr_mtu ifr_ifru.ifru_mtu /* mtu */ +#define ifr_dlt ifr_ifru.ifru_dlt /* data link type (DLT_*) */ +#define ifr_value ifr_ifru.ifru_value /* generic value */ +#define ifr_media ifr_ifru.ifru_metric /* media options (overload) */ +#define ifr_data ifr_ifru.ifru_data /* for use by interface */ +#define ifr_buf ifr_ifru.ifru_b.b_buf /* new interface ioctls */ +#define ifr_buflen ifr_ifru.ifru_b.b_buflen +#define ifr_index ifr_ifru.ifru_value /* interface index */ +}; +.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 2 +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. +.It Dv SIOCGIFINDEX +Get the interface index and populate ifr_index. +.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, +.Ar ifaliasreq , +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 2 +identifier itself to include the total size, as described in +.Xr ioctl 2 . +.It Dv SIOCDIFADDR +This requests deletes the specified address from the list +associated with an interface. +It also uses the +.Ar ifaliasreq +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 SIOCGIFALIAS +This request provides means to get additional addresses together +with netmask and broadcast/destination from an interface. +It also uses the +.Ar ifaliasreq +structure. +.El +.Pp +Request making use of the +.Ar ifconf +structure: +.Bl -tag -width SIOCGIFBRDADDR +.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 SIOC[AD]IFADDR request. +*/ +struct ifaliasreq { + char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ + struct sockaddr ifra_addr; + struct sockaddr ifra_dstaddr; +#define ifra_broadaddr ifra_dstaddr + 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 { + void *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 config 1 , +.Xr ioctl 2 , +.Xr socket 2 , +.Xr intro 4 , +.Xr routed 8 +.Sh HISTORY +The +.Nm netintro +manual appeared in +.Bx 4.3 Tahoe . |