build: Better Build System

1 files changed, 926 insertions, 0 deletions

diff --git a/static/plan9-4e/man3/ip.3 b/static/plan9-4e/man3/ip.3
new file mode 100644
index 00000000..84be502f
--- /dev/null
+++ b/static/plan9-4e/man3/ip.3
@@ -0,0 +1,926 @@
+.TH IP 3 
+.SH NAME
+ip \- network protocols over IP
+.SH SYNOPSIS
+.nf
+.B bind -a #I\fIspec\fP /net
+
+.B /net/ipifc
+.B /net/ipifc/clone
+.B /net/ipifc/stats
+.BI /net/ipifc/ n 
+.BI /net/ipifc/ n /status
+.BI /net/ipifc/ n /ctl
+\&...
+
+.B /net/arp
+.B /net/log
+.B /net/ndb
+.B /net/iproute
+.B /net/ipselftab
+
+.B /net/esp
+.B /net/gre
+.B /net/icmp
+.B /net/il
+.B /net/ipmux
+.B /net/rudp
+.B /net/tcp
+.B /net/udp
+
+.B /net/tcp/clone
+.B /net/tcp/stats
+.BI /net/tcp/ n 
+.BI /net/tcp/ n /data
+.BI /net/tcp/ n /ctl
+.BI /net/tcp/ n /local
+.BI /net/tcp/ n /remote
+.BI /net/tcp/ n /status
+.BI /net/tcp/ n /listen
+\&...
+.fi
+.SH DESCRIPTION
+The IP device provides the interface to Internet protocol stacks.
+.I Spec
+is an integer from 0 to 15 identifying a stack.
+Each stack is physically independent of all others:
+the only information transfer between them is via programs that
+mount multiple stacks.
+Normally a system uses only one stack.
+However multiple stacks can be used for debugging
+new IP networks or implementing firewalls or proxy
+services.
+.PP
+All addresses used are 16-byte IPv6 addresses.  Though
+we currently implement only IPv4, the IPv6 format is intended to
+prepare the way for an IPv6 implementation.  IPv4 addresses
+are a subset of the IPv6 addresses and both standard
+.SM ASCII
+formats
+are accepted.  In binary, all v4 addresses start with the
+12 bytes:
+.EX
+	00 00 00 00 00 00 00 00 00 00 ff ff
+.EE
+.SS "Configuring interfaces
+.PP
+Each stack may have multiple interfaces and each interface
+may have multiple addresses.
+The
+.B /net/ipifc
+directory contains a
+.B clone
+file, a
+.B stats
+file, and numbered subdirectories for each physical interface.
+.PP
+Opening the
+.B clone
+file reserves an interface.
+The file descriptor returned from the
+.IR open (2)
+will point to the control file,
+.BR ctl ,
+of the newly allocated interface.
+Reading
+.B ctl
+returns a text string representing the number of the interface.
+Writing
+.B ctl
+alters aspects of the interface.
+The possible
+.I ctl
+messages are:
+.TP
+.BI "bind ether " path
+Treat the device mounted at
+.I path
+as an Ethernet medium carrying IP and ARP packets
+and associate it with this interface.
+The kernel will
+.IR dial (2)
+.IR path !0x800
+and
+.IR path !0x806
+and use the two connections for IP and
+ARP respectively.
+.TP
+.B "bind pkt
+Treat this interface as a packet interface.  Assume
+a user program will read and write the
+.I data
+file to receive and transmit IP packets to the kernel.
+This is used by programs such as
+.IR ppp (8)
+to mediate IP packet transfer between the kernel and
+a PPP encoded device.
+.TP
+.BI "bind netdev " path
+Treat this interface as a packet interface.
+The kernel will open
+.I path
+and read and write the resulting file descriptor
+to receive and transmit IP packets.
+.TP
+.BI "bind loopback "
+Treat this interface as a local loopback.  Anything
+written to it will be looped back.
+.TP
+.B "unbind
+Disassociate the physical device from an IP interface.
+.TP
+.BI add\  "local mask remote mtu " proxy
+Add a local IP address to the interface.  The
+.IR mask ,
+.IR remote ,
+.IR mtu ,
+and
+.B proxy
+arguments are all optional.  The default mask is
+the class mask for the local address.  The default
+remote address is
+.I local
+ANDed with
+.IR mask .
+The default mtu is 1514 for Ethernet and 4096 for packet
+media.
+.IR Proxy ,
+if specified, means that this machine should answer
+ARP requests for the remote address.
+.IR Ppp (8)
+does this to make remote machines appear
+to be connected to the local Ethernet.
+.TP
+.BI remove\  "local mask"
+Remove a local IP address from an interface.
+.TP
+.BI mtu\  n
+Set the maximum transfer unit for this device to
+.IR n .
+The mtu is the maximum size of the packet including any
+medium-specific headers.
+.TP
+.BI reassemble
+Reassemble IP fragments before forwarding to this interface
+.TP
+.BI iprouting\  n
+Allow
+.RI ( n is missing
+or non-zero) or disallow
+.RI ( n
+is 0) forwarding packets between this interface and
+others.
+.TP
+.BI addmulti\  addr
+Treat the multicast
+.I addr
+on this interface as a local address.
+.TP
+.BI remmulti\  addr
+Remove the multicast address
+.I addr
+from this interface.
+.PP
+Reading the interface's
+.I status
+file returns information about the interface, one line for each
+local address on that interface.  The first line
+has 9 white-space-separated fields: device, mtu, local address,
+mask, remote or network address, packets in, packets out, input errors,
+output errors.  Each subsequent line contains all but the device and mtu.
+See
+.B readipifc
+in
+.IR ip (2).
+.SS "Routing
+.PP
+The file
+.I iproute
+controls information about IP routing.
+When read, it returns one line per routing entry.
+Each line contains six white-space-separated fields:
+target address, target mask, address of next hop, flags,
+tag, and interface number.
+The entry used for routing an IP packet is the one with
+the longest mask for which destination address ANDed with
+target mask equals the target address.
+The one character flags are:
+.TP
+.B 4
+IPv4 route
+.TP
+.B 6
+IPv6 route
+.TP
+.B i
+local interface
+.TP
+.B b
+broadcast address
+.TP
+.B u
+local unicast address
+.TP
+.B m
+multicast route
+.TP
+.B p
+point-to-point route
+.PP
+The tag is an arbitrary, up to 4 character, string.  It is normally used to
+indicate what routing protocol originated the route.
+.PP
+Writing to
+.B /net/iproute
+changes the route table.  The messages are:
+.TP
+.B flush
+Remove all routes.
+.TP
+.BI tag\  string
+Associate the tag,
+.IR string ,
+with all subsequent routes added via this file descriptor.
+.TP
+.BI add\  "target mask nexthop"
+Add the route to the table.  If one already exists with the
+same target and mask, replace it.
+.TP
+.BI remove\  "target mask"
+Remove a route with a matching target and mask.
+.SS "Address resolution
+.PP
+The file
+.B /net/arp
+controls information about address resolution.
+The kernel automatically updates the ARP information for Ethernet
+interfaces.
+When read, the file returns one line per address containing the
+type of medium, the status of the entry (OK, WAIT), the IP
+address, and the medium address.
+Writing to
+.B /net/arp
+administers the ARP information.  The control messages are:
+.TP
+.B flush
+Remove all entries.
+.TP
+.BI add\  "type IP-addr Media-addr"
+Add an entry or replace an existing one for the
+same IP address.
+.PP
+ARP entries do not time out.  The ARP table is a
+cache with an LRU replacement policy.  The IP stack
+listens for all ARP requests and, if the requester is in
+the table, the entry is updated.
+Also, whenever a new address is configured onto an
+Ethernet, an ARP request is sent to help
+update the table on other systems.
+.PP
+Currently, the only medium type is
+.BR ether .
+.SS "Debugging and stack information
+.PP
+If any process is holding
+.B /net/log
+open, the IP stack queues debugging information to it.
+This is intended primarily for debugging the IP stack.
+The information provided is implementation-defined;
+see the source for details.  Generally, what is returned is error messages
+about bad packets.
+.PP
+Writing to
+.B /net/log
+controls debugging.  The control messages
+are:
+.TP
+.BI set\  arglist
+.I Arglist
+is a space-separated list of items for which to enable debugging.
+The possible items are:
+.BR ppp ,
+.BR ip ,
+.BR fs ,
+.BR tcp ,
+.BR il ,
+.BR icmp ,
+.BR udb ,
+.BR compress ,
+.BR ilmsg ,
+.BR gre ,
+.BR tcpmsg ,
+.BR udpmsg ,
+.BR ipmsg ,
+and
+.BR esp .
+.TP
+.BI clear\  arglist
+.I Arglist
+is a space-separated list of items for which to disable debugging.
+.TP
+.BI only\  addr
+If
+.I addr
+is non-zero, restrict debugging to only those
+packets whose source or destination is that
+address.
+.PP
+The file
+.B /net/ndb
+can be read or written by
+programs.  It is normally used by
+.IR ipconfig (8)
+to leave configuration information for other programs
+such as
+.B dns
+and
+.B cs
+(see
+.IR ndb (8)).
+.B /net/ndb
+may contain up tp 1024 bytes.
+.PP
+The file
+.B /net/ipselftab
+is a read-only file containing all the IP addresses
+considered local.  Each line in the file contains
+three white-space-separated fields: IP address, usage count,
+and flags.  The usage count is the number of interfaces to which
+the address applies.  The flags are the same as for routing
+entries.
+.SS "Protocol directories
+.PP
+The
+.I ip
+device
+supports IP as well as several protocols that run over it:
+TCP, IL, UDP, GRE, ESP, ICMP, and RUDP.
+TCP and UDP provide the standard Internet
+protocols for reliable stream and unreliable datagram
+communication.
+IL provides a reliable datagram service for communication
+between Plan 9 machines.
+GRE is a general encapsulation protocol.
+ESP is the encapsulation protocol for IPSEC.
+ICMP is IP's catch-all control protocol used to send
+low level error messages and to implement
+.IR ping (8).
+RUDP is a locally developed reliable datagram protocol based on
+UDP.
+.PP
+Each protocol is a subdirectory of the IP stack.
+The top level directory of each protocol contains a
+.B clone
+file, a
+.B stats
+file, and subdirectories numbered from zero to the number of connections
+opened for this protocol.
+.PP
+Opening the
+.B clone
+file reserves a connection.  The file descriptor returned from the
+.IR open (2)
+will point to the control file,
+.BR ctl ,
+of the newly allocated connection.
+Reading
+.B ctl
+returns a text
+string representing the number of the
+connection.
+Connections may be used either to listen for incoming calls
+or to initiate calls to other machines.
+.PP
+A connection is controlled by writing text strings to the associated
+.B ctl
+file.
+After a connection has been established data may be read from
+and written to
+.BR data .
+A connection can be actively established using the
+.B connect
+message (see also
+.IR dial (2)).
+A connection can be established passively by first
+using an
+.B announce
+message (see
+.IR dial (2))
+to bind to a local port and then
+opening the
+.B listen
+file (see
+.IR dial (2))
+to receive incoming calls.
+.PP
+The following control messages are supported:
+.TP
+.BI connect\  ipaddress ! port "!r " local
+Establish a connection to the remote address
+.I ipaddress
+and remote port
+.IR port .
+If
+.I local
+is specified, it is used as the local port number.
+If
+.I local
+is not specified but
+.B !r
+is, the system will allocate
+a restricted port number (less than 1024) for the connection to allow communication
+with Unix  
+.B login
+and
+.B exec
+services.
+Otherwise a free port number starting at 5000 is chosen.
+The connect fails if the combination of local and remote address/port pairs
+are already assigned to another port.
+.TP
+.BI announce\  X
+.I X
+is a decimal port number or
+.LR * .
+Set the local port
+number to
+.I X
+and accept calls to
+.IR X .
+If
+.I X
+is
+.LR * ,
+accept
+calls for any port that no process has explicitly announced.
+The local IP address cannot be set.
+.B Announce
+fails if the connection is already announced or connected.
+.TP
+.BI bind\  X
+.I X
+is a decimal port number or
+.LR * .
+Set the local port number to
+.IR X .
+This exists to support emulation
+of BSD sockets by the APE libraries (see
+.IR pcc (1))
+and is not otherwise used.
+.TP
+.BI backlog\  n
+Set the maximum number of unanswered (queued) incoming
+connections to an announced port to
+.IR n .
+By default
+.I n
+is set to five.  If more than
+.I n
+connections are pending,
+further requests for a service will be rejected.
+.TP
+.BI ttl\  n
+Set the time to live IP field in outgoing packets to
+.IR n .
+.TP
+.BI tos\  n
+Set the service type IP field in outgoing packets to
+.IR n .
+.PP
+Port numbers must be in the range 1 to 32767.
+.PP
+Several files report the status of a
+connection.
+The
+.B remote
+and
+.B local
+files contain the IP address and port number for the remote and local side of the
+connection.  The
+.B status
+file contains protocol-dependent information to help debug network connections.
+On receiving and error or EOF reading or writing the
+.B data
+file, the
+.B err
+file contains the reason for error.
+.PP
+A process may accept incoming connections by
+.IR open (2)ing
+the
+.B listen
+file.
+The
+.B open
+will block until a new connection request arrives.
+Then
+.B open
+will return an open file descriptor which points to the control file of the
+newly accepted connection.
+This procedure will accept all calls for the
+given protocol.
+See
+.IR dial (2).
+.SS TCP
+.PP
+TCP connections are reliable point-to-point byte streams; there are no
+message delimiters.
+A connection is determined by the address and port numbers of the two
+ends.
+TCP 
+.B ctl
+files support the following additional messages:
+.TP
+.B hangup
+close down a TCP connection
+.TP
+.BI keepalive \ n
+turn on keep alive messages.
+.IR N ,
+if given, is the milliseconds between keepalives
+(default 30000).
+.SS UDP
+.PP
+UDP connections carry unreliable and unordered datagrams.  A read from
+.B data
+will return the next datagram, discarding anything
+that doesn't fit in the read buffer.
+A write is sent as a single datagram.
+.PP
+By default, a UDP connection is a point-to-point link.
+Either a
+.B connect
+establishes a local and remote address/port pair or
+after an
+.BR announce ,
+each datagram coming from a different remote address/port pair
+establishes a new incoming connection.
+However, many-to-one semantics is also possible.
+.PP
+If, after an
+.BR announce ,
+one of the following messages is written to
+.BR ctl ,
+then all messages sent to the announced port
+are received on the announced connection prefixed with the given structure.
+.TP
+.B headers4
+.EX
+typedef struct Udphdr4 Udphdr4;
+struct Udphdr
+{
+	uchar	raddr[4];		/* v4 remote address and port */
+	uchar	laddr[4];		/* v4 local address and port */
+	uchar	rport[2];
+	uchar	lport[2];
+};
+.EE
+.TP
+.B headers
+.EX
+typedef struct Udphdr Udphdr;
+struct Udphdr
+{
+	uchar	raddr[16];	/* v6 remote address and port */
+	uchar	laddr[16];	/* v6 local address and port */
+	uchar	rport[2];
+	uchar	lport[2];
+};
+.EE
+.PP
+The only difference in the two is the type of address, IPv4 or IPv6.
+Before a write, a user must prefix a similar structure to each message.
+The system overrides the user specified local port with the announced
+one.  If the user specifies an address that isn't a unicast address in
+.BR /net/ipselftab ,
+that too is overridden.
+Since the prefixed structure is the same in read and write, it is relatively
+easy to write a server that responds to client requests by just copying new
+data into the message body and then writing back the same buffer that was
+written.
+.SS RUDP
+.PP
+RUDP is a reliable datagram protocol based on UDP.
+Packets are delivered in order.
+RUDP does not support
+.BR listen .
+One must use either
+.B connect
+or
+.B announce
+followed immediately by
+.B headers
+or
+.BR headers4 .
+.PP
+Unlike IL or TCP, the reboot of one end of a connection does
+not force a closing of the connection.  Communications will
+resume when the rebooted machine resumes talking.  Any unacknowledged
+packets queued before the reboot will be lost.  A reboot can
+be detected by reading the
+.B err
+file.  It will have the message
+.IP
+.BI hangup\  address ! port
+.PP
+where
+.I address
+and
+.I port
+are of the far side of the connection.
+Retransmitting a datagram more than 10 times
+is treated like a reboot:
+all queued messages are dropped, an error is queued to the
+.B err
+file, and the conversation resumes.
+.SS IL
+.PP
+IL is a reliable point-to-point datagram protocol.  Like TCP, IL delivers datagrams
+reliably and in order. Also like TCP, a connection is
+determined by the address and port numbers of the two ends.
+Like UDP, each read and write transfers a single datagram.
+.PP
+IL is efficient for LANs but doesn't have the
+congestion control features needed for use through
+the Internet.
+.SS GRE
+.PP
+GRE is the encapsulation protocol used by PPTP.
+The kernel implements just enough of the protocol
+to multiplex it.
+.B Announce
+is not allowed in GRE, only
+.BR connect .
+Since GRE has no port numbers, the port number in the connect
+is actually the 16 bit
+.B eproto
+field in the GRE header.
+.PP
+Reads and writes transfer a
+GRE datagram starting at the GRE header.
+On write, the kernel fills in the
+.B eproto
+field with the port number specified
+in the connect message.
+.SS ESP
+.PP
+ESP is the Encapsulating Security Payload (RFC 1827).
+It is used to set up an encrypted tunnel between machines.
+Like GRE, ESP has no port numbers.  Instead, the
+port number in the
+.B connect
+message is the SPI (Security Association Identifier (sic)).
+IP packets are written to and read from
+.BR data .
+The kernel encrypts any packets written to
+.BR data ,
+appends a MAC, and prefixes an ESP header before
+sending to the other end of the tunnel.
+Received packets are checked against their MAC's,
+decrypted, and queued for reading from
+.BR data .
+The control messages are:
+.TP
+.BI esp\  "alg secret
+Encrypt with the algorithm,
+.IR alg ,
+using
+.I secret
+as the key.
+Possible algorithms are:
+.BR null ,
+.BR des_56_cbc ,
+and
+.BR rc4_128 .
+.TP
+.BI ah\  "alg secret
+Use the hash algorithm,
+.IR alg ,
+with
+.I secret
+as the key for generating the MAC.
+Possible algorithms are:
+.BR null ,
+.BR hmac_sha1_96 ,
+and
+.BR hmac_md5_96 .
+.TP
+.B header
+Turn on header mode.  Every buffer read from
+.B data
+starts with 4 unsued bytes, and the first 4 bytes
+of every buffer written to
+.B data
+are ignored.
+.TP
+.B noheader
+Turn off header mode.
+.SS "IP packet filter
+.PP
+The directory
+.B /net/ipmux
+looks like another protocol directory.
+It is a packet filter built on top of IP.  Each numbered
+subdirectory represents a different filter.
+The connect messages written to the
+.I ctl
+file describe the filter. Packets matching the filter can be read on the
+.B data
+file.  Packets written to the
+.B data
+file are routed to an interface and transmitted.
+.PP
+A filter is a semicolon-separated list of
+relations.  Each relation describes a portion
+of a packet to match.  The possible relations are:
+.TP
+.BI proto= n
+the IP protocol number must be
+.IR n .
+.TP
+.BI dat[ n : m ]= expr
+bytes
+.I n
+through
+.I m
+following the IP packet must match
+.IR expr .
+.TP
+.BI ifc= expr
+the packet must have been received on an interface whose address
+matches
+.IR expr .
+.TP
+.BI src= expr
+The source address in the packet must match
+.IR expr .
+.TP
+.BI dst= expr
+The destination address in the packet must match
+.IR expr .
+.PP
+.I Expr
+is of the form:
+.TP
+.I \	value
+.TP
+.IB \	value | value | ...
+.TP
+.IB \	value & mask
+.TP
+.IB \	value | value & mask
+.PP
+If a mask is given, the relevant field is first ANDed with
+the mask.  The result is compared against the value or list
+of values for a match.  In the case of
+.BR ifc ,
+.BR dst ,
+and
+.B src
+the value is a dot-formatted IP address and the mask is a dot-formatted
+IP mask.  In the case of
+.BR dat ,
+both value and mask are strings of 2 character hexadecimal digits representing
+8 bit values.
+.PP
+A packet is delivered to only one filter.
+The filters are merged into a single comparison tree.
+If two filters match the same packet, the following
+rules apply in order (here '>' means is preferred to):
+.IP 1)
+protocol > data > source > destination > interface
+.IP 2)
+lower data offsets > higher data offsets
+.IP 3)
+longer matches > shorter matches
+.IP 4)
+older > younger
+.PP
+So far this has just been used to implement a version of
+OSPF in Inferno.
+.SS Statistics
+.PP
+The
+.B stats
+files are read only and contain statistics useful to network
+monitoring.
+.PP
+Reading
+.B /net/ipifc/stats
+returns a list of 19 tagged and new line separated fields representing:
+.EX
+.ft 1
+	forwarding status (0 and 2 mean forwarding off, 1 means on)
+	default TTL
+	input packets
+	input header errors
+	input address errors
+	packets forwarded
+	input packets for unknown protocols
+	input packets discarded
+	input packets delivered to higher level protocols
+	output packets
+	output packets discarded
+	output packets with no route
+	timed out fragments in reassembly queue
+	requested reassemblies
+	successful reassemblies
+	failed reassemblies
+	successful fragmentations
+	unsuccessful fragmentations
+	fragments created
+.ft
+.EE
+.PP
+Reading
+.B /net/icmp/stats
+returns a list of 25 tagged and new line separated fields representing:
+.EX
+.ft 1
+	messages received 
+	bad received messages
+	unreachables received
+	time exceededs received
+	input parameter problems received
+	source quenches received
+	redirects received
+	echo requests received
+	echo replies received
+	timestamps received
+	timestamp replies received
+	address mask requests received
+	address mask replies received
+	messages sent
+	transmission errors
+	unreachables sent
+	time exceededs sent
+	input parameter problems sent
+	source quenches sent
+	redirects sent
+	echo requests sent
+	echo replies sent
+	timestamps sent
+	timestamp replies sent
+	address mask requests sent
+	address mask replies sent
+.EE
+.PP
+Reading
+.B /net/tcp/stats
+returns a list of 11 tagged and new line separated fields representing:
+.EX
+.ft 1
+	maximum number of connections
+	total outgoing calls
+	total incoming calls
+	number of established connections to be reset
+	number of currently established connections
+	segments received
+	segments sent
+	segments retransmitted
+	retransmit timeouts
+	bad received segments
+	transmission failures
+.EE
+.PP
+Reading
+.B /net/udp/stats
+returns a list of 4 tagged and new line separated fields representing:
+.EX
+.ft 1
+	datagrams received
+	datagrams received for bad ports
+	malformed datagrams received
+	datagrams sent
+.EE
+.PP
+Reading
+.B /net/il/stats
+returns a list of 7 tagged and new line separated fields representing:
+.EX
+.ft 1
+	checksum errors
+	header length errors
+	out of order messages
+	retransmitted messages
+	duplicate messages
+	duplicate bytes
+.EE
+.PP
+Reading
+.B /net/gre/stats
+returns a list of 1 tagged number representing:
+.EX
+.ft 1
+	header length errors
+.EE
+.SH "SEE ALSO"
+.IR listen (8),
+.IR dial (2),
+.IR ndb (6)
+.SH SOURCE
+.B /sys/src/9/ip
+.SH BUGS
+.I Ipmux
+has not been heavily used and should be considered experimental.
+It may disappear in favor of a more traditional packet filter in the future.