IP(3) IP(3)
NAME
ip - TCP, UDP, IL network protocols over IP
SYNOPSIS
bind -a #Itcp /net
bind -a #Iudp /net
bind -a #Iil /net
/net/tcp/clone
/net/tcp/n
/net/tcp/n/data
/net/tcp/n/ctl
/net/tcp/n/local
/net/tcp/n/remote
/net/tcp/n/status
/net/tcp/n/listen
...
DESCRIPTION
The IP device provides the interface for several protocols
that run over IP on an Ethernet. TCP and UDP provide the
standard Internet protocols for reliable stream and unreli-
able datagram communication. IL provides a reliable data-
gram service for communication between Plan 9 machines. IL
is the protocol of choice for most Plan 9 services.
Each of the protocols is served by the IP device, which rep-
resents each connection by a set of device files. The top
level directory of each protocol contains a clone file and
subdirectories numbered from zero to the number of connec-
tions configured for this protocol.
Opening the clone file reserves a connection. The file
descriptor returned from the open(2) will point to the con-
trol file, ctl, of the newly allocated connection. Reading
the ctl file 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.
A connection is controlled by writing text strings to the
associated ctl file. After a connection has been estab-
lished data may be read from and written to the data file.
For the datagram services, IL and UDP, a read of less than
the length of a datagram will cause the entire datagram to
be consumed. Each write to the data file will send a single
datagram on the network. The TCP protocol provides a stream
connection that does not preserve read/write boundaries.
Prior to sending data, remote and local addresses must be
set for the connection. For outgoing calls the local port
Page 1 Plan 9 (printed 12/21/24)
IP(3) IP(3)
number will be allocated randomly if none is set. Addresses
are set by writing control messages to the ctl file of the
connection. The connection is not established until the
data file is opened. For IL and TCP the process will block
until the remote host has acknowledged the connection. UDP
opens always succeed.
The following control messages are supported:
connect ipaddress!port[!r]
Set the remote IP address and port number for the con-
nection. If the r flag is supplied and no local
address has been specified the system will allocate a
restricted port number (less than 1024) for the connec-
tion to allow communication with Unix machines' login
and exec services.
disconnect
(UDP only) Clear the remote address of a UDP connec-
tion.
announce X
X is a decimal port number or `*'. Set the local port
number to X and accept calls to X. If X is `*', accept
calls for any port that no process has explicitly
announced. The local IP address cannot be set.
Announce fails if the connection is already announced
or connnected.
bind X
X is a decimal port number or `*'. Set the local port
number to X. This exists to support library emulation
of BSD sockets and is not otherwise used.
backlog n
(IL and TCP only) Set the maximum number of pending
requests for a given service to n. By default n is set
to five. If more than n connections are pending, fur-
ther requests for a service will be rejected.
Port numbers must be in the range 1 to 32767. If a local
port has not been announced prior to a connect a local port
number will be allocated automatically. Local ports are
allocated from 5000 up.
Several files report the status of a connection. The remote
and local files contain the IP address and port number for
the remote and local side of the connection. The status
file contains protocol-dependent information to help debug
network connections.
A process may accept incoming connections by calling open on
Page 2 Plan 9 (printed 12/21/24)
IP(3) IP(3)
the listen file. The open will block until a new connection
request arrives. Then 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 ALSO
listen(8), dial(2), ndb(6)
SOURCE
/sys/src/9/port/devip.c
/sys/src/9/port/stil.c
/sys/src/9/port/stip.c
/sys/src/9/port/tcp*.c
Page 3 Plan 9 (printed 12/21/24)