BBN-Vax-TCP/doc/net.5.n

.TH NET  5                                       
.SH NAME
.IX network
.IX TCP
.IX IP
.IX "Transmission Control Protocol"
.IX "Internet Protocol"
tcp, ip, rawnet \- internet networking software
.SH SYNOPSIS
.B open ("/dev/net/net", ncon);
.sp
.B struct con *ncon;
.sp
.nf
.ta \w'struct 'u +\w'unsigned  'u +\w'struct tcb *utcb; 'u
.so /usr/src/sys.4/h/con.h    
.fi
.SH DESCRIPTION
The special file
.I /dev/net/net
is used to access ARPANET type packet-switched networks via the DoD standard
host-host Internetworking Protocols, 
.B TCP
(Transmission Control Protocol), and
.B IP
(Internet Protocol).  It also allows communication over the local network(s)
to which the system is connected with "raw" packets, enabling user software to
do its own communications processing.  Access to the network at this level
is the most direct form of use.  It is assumed that most users will use higher
level protocol programs, like 
.I ftp(1)
and
.I telnet(1)
to communicate over the network.  (This description assumes the reader is
familiar with ARPANET type communications protocols.)
.SH ESTABLISHING CONNECTIONS
To establish a connection via TCP or IP, or to communicate with raw packets,
the 
.I open(2)
call is given, with the usual mode argument replaced by a pointer to a
connection structure, defined in
.I /usr/include/con.h.
The 
.I c_mode
field of this structure specifies what type of connection is desired
(TCP, IP, or RAW), and whether or not the connection is to be active 
(specifying a specific foreign host address), or passive (with no foreign
address, implying that the connection will be established when any foreign
process tries to communicate with the opener).  
This field also specifies other attributes of raw connections (see, RAW
CONNECTIONS).
.PP
The
.I c_sbufs
and 
.I c_rbufs
fields specify buffer allocations for the send and receive sides of the
connection, respectively.  If either value is zero, the default allocation 
will be used for that direction
(currently 1K bytes).  The user can request up to 8K bytes each for send
and receive directions by varying these parameters between 1 and 8.  
.PP
For IP 
and RAW connections, the
.I c_hi
and
.I c_lo
fields specify a range of IP protocol numbers or local net dispatch numbers
(e.g., ARPANET link numbers) to watch for (see, RAW CONNECTIONS).  
.PP
The
.I c_timeo
parameter specifies a length of time in seconds to wait for connection
establishment before aborting (this does not apply to passive opens).  If
the field is zero, the default of 30 seconds is used.  
.PP
The remaining fields
specify local, and foreign ports for TCP, and foreign and local host addresses 
in network address format (see
.I libnet(3)).
The local port may be zero, in which case TCP assigns a unique port number to
the connection.  The foreign port and host address may only be zero for a
passive open.
The local host address may be zero, in which case a default local address
is chosen by the software.  On machines with multiple network interfaces
(and network addresses), this field may be used to specify which
interface/address to use.  It is an error to specify an unsupported local
address.
.SH READING AND WRITING
If the open succeeds, a file descriptor is returned which may be used in
subsequent reads and writes (see,
.I read(2), write(2)).
Reads and writes work as usual with a few
exceptions.  A read may return with error condition ENETSTAT, which indicates
that some exceptional condition has been detected.  
Further status may be determined with
.I ioctl(2).
(see, NETWORK STATUS).  If the condition is non-fatal, the read may be
re-issued.  Reads may return less data than requested, 
and will block if there is no data for the user.  Writes block if
the amount of send buffer resources for the connection is exceeded.  
Reads will return zero only when the foreign peer has closed the connection and
there is no remaining data to return to the user.  
.PP
In addition to normal TCP reads and writes, the user may wish to indicate EOL
and URGENT data on writes and receive notification of URGENT data sent by the
foreign peer.  EOL and URGENT are enabled by issueing the NETSETE or NETSETU
ioctl calls.
Once set, EOL is sent at the last byte of each subsequent write.  Similarly,
the URGENT pointer is set to start at the first byte of the next write, and
ends with the first byte sent after URGENT mode is disabled.  These modes are
disabled by the NETRSETE and NETRSETU ioctl calls.  URGENT data is
indicated by signal SIGURG when the first byte is received.  This signal is
normally ignored.  (A status flag is also set in the presence of urgent data.)
.SH CLOSING CONNECTIONS 
Normally, the 
.I close(2)
call is used to close a TCP, IP, or RAW connection.  In each case, it indicates
that the user will send or receive no more data.  For TCP connections, close
initiates the connection closing protocol, though it returns immediately.
Thus, the internal connection structures persist until the connection has
reached the CLOSED state.  For IP and RAW connections, the close is immediate
and deletes all internal structures.  
.PP
In addition to close for TCP connections, there is an ioctl call, NETCLOSE,
which indicates that the local connection will send no more data, but is still
able to receive data from the foreign peer.  In this case, subsequent writes
are illegal and will terminate with errors, but subsequent reads will work
until the connection is closed by the foreign peer.
.SH RAW CONNECTIONS
.PP
Raw IP and local network protocol packets may be sent and received by
specifying CONIP or CONRAW in the mode field of the open call.  These types
of opens do not set up connections in the sense of TCP opens (i.e., they do
not cause communication of a connection opening protocol), but the
resulting channel will be referred to as a "connection" for the sake of
brevity.  
.PP
To send raw IP or local network protocol packets, a connection is opened
and writes are issued on the resulting file descriptor.  The user may
specify parameters in the open call (such as destination host address, link
or protocol number) that are used by the software to construct leaders for
the data (RAWCOMP mode), or he may opt to supply the leaders (RAWASIS
mode).  A third option exists for IP connections, where the system fills in
the checksum field in the supplied leader (RAWVER mode).  In each case, one
packet is sent out for each write.  Writes do not block, and return as soon
as the packet has been queued for sending to the local network.  If for
some reason, the packet cannot be sent (the selected network interface is
unavailable), an error will be returned.
.PP
To receive raw IP or local network protocol packets, the user specifies a
range of link or protocol numbers and a foreign and local host address in
the open call.  The range is specified in the
.I c_hi
and
.I c_lo
fields.  The range must be unique (i.e., may not overlap other protocol or
link numbers in use), and 
.I c_lo 
must be less than or equal to 
.I c_hi, 
or an
ENETRNG error results.  If the foreign or local host addresses are
specified, only messages in the specified range with the corresponding
source and/or destination address are queued for the user.  If the
addresses are zero, all messages falling into the specified range are
returned.  Reads return no more than one packet, though they may return
less if a length shorter than the packet length is specified (subsequent
reads will return the remainder of the packet).  The entire packet,
including the header is returned.  If the read buffer limit is exceeded,
subsequent incoming messages in the specified range will be dropped.  Reads
block if there is no data to satisfy the request.  The user may optionally
receive ICMP or local network protocol error and control messages
associated with the range by specifying RAWERR mode in the open call.  
.SH NETWORK STATUS
There are several 
.I ioctl(2)
calls available for receiving network status information or initiating certain
modes or functions.  Most of these calls have been described above.  The status
call, NETGETS, takes a status buffer pointer, which points to a netstate
structure, illustrated above, which is filled in by the call.  
.PP
To summarize, the various ioctl calls are:
.IP NETGETS 10
Return network status information to the structure pointed at by third argument
of ioctl.
.IP NETSETU 10
Set urgent mode starting at next byte written (TCP only).
.IP NETRSETU 10
Reset urgent mode, urgent pointer ends at last byte written (TCP only).
.IP NETSETE 10
Set EOL mode, send EOL at last byte of each subsequent write (TCP only).
.IP NETRSETE 10
Terminate EOL mode (TCP only).
.IP NETCLOSE 10
Start TCP connection close.  User can continue to receive data (TCP only).
.IP NETABORT 10
Abort TCP connection.  Foreign peer is reset and no more data may be sent or
received (TCP only).
.IP NETTCPOPT 10
Set up an IP option string for a TCP connection.  The third parameter is a
pointer to a structure containing a pointer to the option string and the
length of the option string in bytes.   The option string is appended to the IP
leader of each subsequent TCP segment sent.  If the third parameter is zero, the
previous options are cancelled and no options will be sent on subsequent
packets.  The options are
specified in the Internet Protocol description, and are sent as is, with no
verification.  The option length may not exceed 40 bytes. (TCP only).
.PP
In addition, there is another class of ioctl calls that are associated with
network control functions and not with any specific connection.  These calls
may be issued from normal TCP, IP, or RAW connections.  There is also a special
control only connection which may be opened (with CONCTL passed to open, all
other fields are ignored).  This type of connection exists solely for the
purpose of issuing control ioctls without involving any network resources.  The
control ioctls are:
.IP NETSETD 10
Reset the debugging log to the file name pointed at by the third
argument.  The file must already exist.
If the argument is zero, turn off debug logging (see, DEBUGGING). Only the
super-user may issue this call.
.IP NETRESET 10
Cause the TCP connection specified by the tcb address given as the third
argument to be reset as if a connection clear request had been received from
the network.  Only the super-user may issue this call.
.IP NETDEBUG 10
Toggle the debugging flag for the TCP connection specified by the TCB address
given as the third argument.
.IP NETGINIT 10
Cause the gateway initialization file
.I /etc/net/gateway
to be read by the kernel, and the internal gateway forwarding table to be
reinitialized.  This file is in binary format and is generated from an
ASCII gateway table with
.I gateway(1).
.SH DEBUGGING
.IX "\*itrpt\*r usage"
.IX "\*i/etc/net/tcpdebug\*r"
.IX "network debugging"
The network software enables certain trace information to be recorded for TCP
connections.  This information is logged in a single debugging log file.  To
enable this feature, the CONDEBUG bit in the 
.I c_mode 
field of the open connection parameter structure must be set, or the NETDEBUG
ioctl call must issued.  The default debugging log is 
.I /etc/net/tcpdebug.
This may be changed or the feature may be disabled system wide with the NETSETD
ioctl call.  Only the super-user may do this.  The format of the debugging
information is several bytes of binary data per TCP transaction.  The log may
be printed in readable form with
.I trpt(1).
.SH DIAGNOSTICS
The following system error codes may be returned by network system calls:
.IP ENETSTAT 10
(35) Network status available (not a fatal error, see READS AND WRITES).
.IP ENETDOWN 10
(36) Open failed because specified network interface is unavailable.
.IP ENETCON 10
(37) Open failed because there were too many connections.
.IP ENETBUF 10
(38) Open, write, or ioctl failed because there was insufficient network 
buffer space.  
.IP ENETPARM 10
(39) Network parameter error.  On open, the mode field of the connection 
parameter structure is bad.  On ioctl, an unrecognized network ioctl type 
was specified.
.IP ENETRNG 10
(40) IP or RAW open failed because the protocol or dispatch number was out of
range or already in use.  TCP open failed because the user tried to open an
already existing connection (i.e., one with the identical foreign host address
and local and foreign ports).  NETDEBUG or NETRESET ioctls failed because the
connection with the specified TCB could not be found.
.IP ENETDED 10
(41) TCP open failed because the foreign host is dead.
.IP ERAWBAD 10
(42) IP or RAW write failed, packet was not sent.
.IP ENETERR 10
(43) Open failed for unknown reason.  TCP read or write was attempted on a 
closed connection.
.IP ENETREF 10
(44) TCP open failed because the destination host refused the connection.
.IP ENETUNR 10
(45) TCP open failed because the destination host was unreachable.
.IP ENETTIM 10
(46) TCP open failed because the foreign host did not respond on the specified
socket within the timeout period defined in the open request.
.SH FILES
/dev/net/net
.br
/etc/net/tcpdebug
.br
/etc/net/gateway
.SH SEE ALSO
ftp(1), gateway(1), telnet(1), trpt(1), read(2), write(2), open(2), close(2), 
ioctl(2), libnet(3)
.sp
R.F. Gurwitz, 
.I VAX-UNIX Networking Support Project Implementation Description,
DARPA Information Processing Techniques Office, IEN 168, January, 1981.
.sp
J. Postel (ed.), 
.I DoD Standard Internet Protocol,
DARPA Information Processing Techniques Office, RFC 791, September, 1981.
.sp
J. Postel (ed.),
.I DoD Standard Transmission Control Protocol,
DARPA Information Processing Techniques Office, RFC 793, September, 1981.