ip.4

操作系统设计与实现源码

.\"
.\" Copyright 1994 Vrije Universiteit, The Netherlands.
.\" For full copyright and restrictions on use see the file COPYRIGHT in the
.\" top level of the Amoeba distribution.
.\"
.ig
	Software: Philip Homburg, 1991
	Document: Philip Homburg, Sept 3, 1991
	Modified: Greg Sharp and Philip Homburg, March 1992
		  - merged with udp(L) and made a little more complete.
		  Greg Sharp, April 1992
		  - updated keywords for auto index generation
	Modified: Kees J. Bot, June 1994
		  - changed to man(7) format for Minix.
..
.TH IP 4
.SH NAME
ip, eth, psip, udp, tcp \- Internet Protocol server devices and definitions
.SH DESCRIPTION
.de SP
.if t .sp 0.4
.if n .sp
..
The
.BR ip* ,
.BR eth* ,
.BR psip* ,
.BR tcp* ,
and
.B udp*
devices give access to the Internet Protocol (IP) services in Minix.
There are 16 such devices for four different networks, and four
different ways of accessing them.  The
.B eth*
and
.B psip*
devices give direct access to the network packets at the lowest level.
The
.BR ip* ,
.BR tcp* ,
and
.B udp*
devices give access to IP, TCP, or UDP services.  See
.BR set_net_default (8)
for a description of the default network devices and environment
variables.  The proper TCP device to use for instance is found by:
.PP
.RS
.nf
if ((tcp_device= getenv("TCP_DEVICE")) == NULL)
	tcp_device= "/dev/tcp";
.fi
.RE
.PP
Access to the IP services is provided using filedescriptors to open IP
devices.  These open IP channels can be configured with
.BR ioctl (2)
calls, and data can be transferred by calls to
.BR read (2),
and
.BR write (2).
.SS "Types (general)"
.IP <sys/types.h>
.br
defines
.BR u8_t ,
.BR u16_t ,
.B u32_t
and
.B i32_t
(and
.BR U8_t ,
.BR U16_t ,
.B U32_t
and
.B I32_t
for use in prototypes).
.SS "Types (eth)"
.IP <net/gen/ether.h>
.br
defines struct ether_addr (\fBether_addr_t\fP) and
.B ether_type_t
and
.B Ether_type_t
for use in prototypes.
.IP <net/gen/eth_io.h>
.br
defines struct nwio_ethopt (\fBnwio_ethopt_t\fP) and
struct nwio_ethstat (\fBnwio_ethstat_t\fP)
.IP <net/gen/eth_hdr.h>
.br
defines struct eth_hdr (\fBeth_hdr_t\fP)
.SS "Types (ip)"
.IP <net/gen/in.h>
.br
defines
.BR ipaddr_t ,
.BR ipproto_t
and struct ip_hdropt (\fBip_hdropt_t\fP).
.IP <net/gen/ip_io.h>
.br
defines struct nwio_ipconf (\fBnwio_ipconf_t\fP) and
struct nwio_ipopt (\fBnwio_ipopt_t\fP)
.IP <net/gen/ip_hdr.h>
.br
defines struct ip_hdr (\fBip_hdr_t\fP)
.IP <net/gen/route.h>
.br
defines struct nwio_route (\fBnwio_route_t\fP)
.SS "Types (tcp)"
.IP <net/gen/tcp.h>
.br
defines
.B tcpport_t
and
.B Tcpport_t
for use in prototypes.
.IP <net/gen/tcp_io.h>
.br
defines struct nwio_tcpconf (\fBnwio_tcpconf_t\fP),
struct nwio_tcpcl (\fBnwio_tcpcl_t\fP),
struct nwio_tcpatt (\fBnwio_tcpatt_t\fP) and
struct nwio_tcpopt (\fBnwio_tcpopt_t\fP).
.IP <net/gen/tcp_hdr.h>
.br
defines struct tcp_hdr (\fBtcp_hdr_t\fP) and struct tcp_hdropt
(\fBtcp_hdropt_t\fP).
.SS "Types (udp)"
.IP <net/gen/udp.h>
.br
defines
.B udpport_t
and
.B Udpport_t
for use in prototypes.
.IP <net/gen/udp_io.h>
.br
defines struct nwio_udpopt (\fBnwio_udpopt_t\fP).
.IP <net/gen/udp_hdr.h>
.br
defines struct udp_hdr (\fBudp_hdr_t\fP) and struct udp_io_hdr
(\fBudp_io_hdr_t\fP).
.SS "Byte Order Conversion"
All 16-bit and 32-bit quantities in IP headers must be in network byte
order.  The macros described in
.BR hton (3)
can be used to convert these values to and from the byte order used by
the host machine.
.SS "The Internet Checksum"
The
.B OneC_sum
function (see
.BR oneC_sum (3))
is used to calculate the one's complement checksum needed for IP network
packets.
.SS "General Functions"
.PP
.ft B
\fIfd\fP = open(\fItcpip_device\fP, O_RDWR)
.ft R
.PP
This is how one normally obtains a filedescriptor for a new TCP/IP channel.
.I tcpip_device
names one of the TCP/IP devices.  The channel may be used both to send or to
receive data.
.PP
.ft B
\fIn\fP = read(\fIfd\fP, \fIbuf\fP, \fIsize\fP)
.ft R
.PP
Receives one packet (low level devices) or a number of bytes (TCP stream).
Returns the the number of bytes placed into
.IR buf ,
or returns -1 with an error code placed into
.BR errno .
.PP
.ft B
\fIn\fP = write(\fIfd\fP, \fIbuf\fP, \fIsize\fP)
.ft R
.PP
Sends one packet (low level devices) or a number of bytes (TCP stream).
Returns
.I size
or -1 with the error code placed into
.BR errno .
The TCP/IP
.B read
and
.B write
functions behave like reads and writes on pipes when it comes to signals.
.SS "ETH Functions"
.PP
.ft B
ioctl(\fIfd\fP, NWIOGETHSTAT, &struct nwio_ethstat)
.ft R
.PP
The
.B NWIOGETHSTAT
ioctl
returns the Ethernet address and some statistics of the Ethernet server of
the channel
.IR fd .
The result is returned in the nwio_ethstat structure.
The \fBstruct nwio_ethstat\fP is defined in <net/gen/eth_io.h>:
.PP
.RS
.nf
.if t .ft C
typedef struct nwio_ethstat
{
        ether_addr_t nwes_addr;
        eth_stat_t nwes_stat;
} nwio_ethstat_t;
.SP
typedef struct eth_stat
{
    unsigned long ets_recvErr,  /* # receive errors */
	ets_sendErr,            /* # send error */
	ets_OVW,                /* # buffer overwrite warnings,
                                   (packets arrive faster than
                                    can be processed) */
	ets_CRCerr,             /* # crc errors of read */
	ets_frameAll,           /* # frames not aligned (# bits
                                   not a multiple of 8) */
	ets_missedP,            /* # packets missed due to too
                                   slow packet processing */
	ets_packetR,            /* # packets received */
	ets_packetT,            /* # packets transmitted */
	ets_transDef,           /* # transmission deferred (there
                                   was a transmission of an
                                   other station in progress */
	ets_collision,          /* # collisions */
	ets_transAb,            /* # transmissions aborted due
                                   to excessive collisions */
	ets_carrSense,          /* # carrier sense lost */
	ets_fifoUnder,          /* # fifo underruns (processor
                                   is too busy) */
	ets_fifoOver,           /* # fifo overruns (processor is
                                   too busy) */
	ets_CDheartbeat,        /* # times unable to transmit
                                   collision signal */
	ets_OWC;                /* # times out of window
                                   collision */
} eth_stat_t;
.if t .ft R
.fi
.RE
.PP
.ft B
ioctl(\fIfd\fP, NWIOSETHOPT, &struct nwio_ethopt)
.ft R
.PP
Before an Ethernet channel can be used to send or receive
Ethernet packets, it has to be configured using the
.B NWIOSETHOPT
ioctl.
The structure
.B nwio_ethopt
is defined in <net/gen/eth_io.h>:
.PP
.RS
.nf
.if t .ft C
typedef struct nwio_ethopt
{
	u32_t nweo_flags;
	ether_addr_t nweo_multi, nweo_rem;
	ether_type_t nweo_type;
} nwio_ethopt_t;
.SP
#define NWEO_NOFLAGS    0x0000L
#define NWEO_ACC_MASK   0x0003L
#       define NWEO_EXCL        0x00000001L
#       define NWEO_SHARED      0x00000002L
#       define NWEO_COPY        0x00000003L
#define NWEO_LOC_MASK   0x0010L
#       define NWEO_EN_LOC      0x00000010L
#       define NWEO_DI_LOC      0x00100000L
#define NWEO_BROAD_MASK 0x0020L
#       define NWEO_EN_BROAD    0x00000020L
#       define NWEO_DI_BROAD    0x00200000L
#define NWEO_MULTI_MASK 0x0040L
#       define NWEO_EN_MULTI    0x00000040L
#       define NWEO_DI_MULTI    0x00400000L
#define NWEO_PROMISC_MASK 0x0080L
#       define NWEO_EN_PROMISC  0x00000080L
#       define NWEO_DI_PROMISC  0x00800000L
#define NWEO_REM_MASK   0x0100L
#       define NWEO_REMSPEC     0x00000100L
#       define NWEO_REMANY      0x01000000L
#define NWEO_TYPE_MASK  0x0200L
#       define NWEO_TYPESPEC    0x00000200L
#       define NWEO_TYPEANY     0x02000000L
#define NWEO_RW_MASK    0x1000L
#       define NWEO_RWDATONLY   0x00001000L
#       define NWEO_RWDATALL    0x10000000L
.if t .ft R
.fi
.RE
.PP
The configuration is divided in a number of section (covered by the xx_MASK
macros).
Options can be set in the
.B nweo_flags
field.
The first section (\fBNWEO_ACC_MASK\fP) controls the access to a certain
Ethernet packet type.
If
.B NWEO_EXCL
is selected then this is the only channel that can send or
receive Ethernet packets of the selected type.
If
.B NWEO_SHARED
is selected then multiple channels (which all have to
select
.BR NWEO_SHARED )
can use the same Ethernet type, they all can send
packets but incoming packets will be delivered to at most one of them.
If
.B NWEO_COPY
is selected then multiple channels have access to the same
Ethernet type and all receive a copy of an incoming packet.
.LP
The
.B NWEO_LOC_MASK
flags control the delivery of packets with a destination
address equal to the Ethernet address of the machine.
If
.B NWEO_EN_LOC
is selected then these packets will be delivered and with
.B NWEO_DI_LOC
they will be discarded.
.PP
.BR NWEO_BROAD_MASK ,
.BR NWEO_MULTI_MASK ,
and
.B NWEO_PROMISC_MASK
do the same to broadcast packets,
multicast packets and promiscuous mode packets as
.B NWEO_LOC_MASK
does for local packets.
Except that the precise multicast address is taken from the \fBnweo_multi\fP
field.
.LP
The
.B NWEO_REM_MASK
flags control whether communication is restricted to
single destination or not.
.B NWEO_REMSPEC
restricts sending and receiving of packets to the single
remote computer specified in the \fBnweo_rem\fP field.
.B NWEO_REMANY
allows sending to and receiving from any remote computer.
.PP
.B NWEO_TYPESPEC
restricts sending and receiving of packets to the type
specified in \fBnweo_type\fP.
The type has to be in network byte order (using
.BR hton (3)).
.B NWEO_TYPEANY
allows any type.
.PP
If the Ethernet header is completely specified by the
.B nweo_flags
i.e., all of
.BR NWEO_EN_LOC ,
.BR NWEO_DI_BROAD ,
.BR NWEO_DI_MULTI ,
.BR NWEO_DI_PROMISC ,
.BR NWEO_REMSPEC
and
.B NWEO_TYPESPEC
are
specified, then
.B NWEO_RWDATONLY
can be used to send and receive only the data part of an Ethernet packet.
If
.B NWEO_RWDATALL
is specified then both Ethernet header and data are used.
.SS "PSIP Functions"
.PP
[[[No description available yet.]]]
.SS "IP Functions"
.PP
.ft B
ioctl(\fIfd\fP, NWIOGIPCONF, &struct nwio_ipconf)
.ft R
.PP
The
.B NWIOGIPCONF
ioctl reports the Internet Address and the netmask.
For the \fInwio_ipconf\fP structure see the \fBNWIOSIPCONF\fP ioctl below.
.PP
.ft B
ioctl(\fIfd\fP, NWIOGIPOROUTE, &struct nwio_route)
.ft R
.PP
The
.B NWIOGIPOROUTE
ioctl can be used to query an IP server about its routing table.
[[[NWIODIPOROUTE, NWIOGIPIROUTE, NWIODIPIROUTE?]]]
The structure \fBnwio_route\fP is defined in <net/gen/route.h>:
.PP
.RS
.nf
.if t .ft C
typedef struct nwio_route
{
        u32_t nwr_ent_no;
        u32_t nwr_ent_count;
        ipaddr_t nwr_dest;
        ipaddr_t nwr_netmask;
        ipaddr_t nwr_gateway;
        u32_t nwr_dist;
        u32_t nwr_flags;
        u32_t nwr_pref;
} nwio_route_t;
.SP
#define NWRF_EMPTY      0
#define NWRF_INUSE      1
#define NWRF_FIXED      2
.if t .ft R
.fi
.RE
.PP
The requested entry is taken from \fBnwr_ent_no\fP.
Entries are counted from 0, so the value 0 can be used for an initial query.
The size of the routing table is returned in \fBnwr_ent_count\fP.
The \fBnwr_flags\fP indicates if the entry is in use (\fBNWRF_INUSE\fP) and
if the entry was inserted manually (using \fBNWIOSIPOROUTE\fP) or generated
by the IP server itself.
The route is described by
.BR nwr_dest ,
.BR nwr_netmask ,
.BR nwr_gateway ,
.BR nwr_dist ,
and
.BR nwr_pref .
\fBNwr_dest\fP and \fBnwr_netmask\fP select the destination addresses.
A value of 0.0.0.0 (0x0) in both \fBnwr_dest\fP and \fBnwr_netmask\fP means
every host.
A value of 255.255.255.255 (0xffffffff) in \fBnwr_netmask\fP means a single
host.
Other values of \fBnwr_netmask\fP are netmasks for the network specified
by \fBnwr_dest\fP.
\fBNwr_gateway\fP is gateway that should be used.
\fBNwr_dist\fP is a minimal distance.
Packets with a time to live smaller than \fBnwr_dist\fP will not reach the
destination.
If two routes have equal netmask and distance fields but different
gateways then the gateway with highest value in \fBnwr_pref\fP is used.
.PP
.ft B
ioctl(\fIfd\fP, NWIOSIPCONF, &struct nwio_ipconf)
.ft R
.PP
The
.B NWIOSIPCONF
ioctl can be used to inform the IP server about its Internet Address
and/or its netmask.
Normally an IP server will discover its Internet Address using the RARP
protocol.
.B NWIOSIPCONF
can be used in the case that the RARP failed, or the netmask has to be changed.
Note that higher level protocols (TCP and UDP) assume that the Internet Address
of an IP device does not change, therefore TCP and UDP stop functioning if