The zsh/net/tcp
module makes available one builtin command:
ztcp
[ -acflLtv
] [ -d
fd ] [ args ]ztcp
is implemented as a builtin to allow full use of shell
command line editing, file I/O, and job control mechanisms.
If ztcp
is run with no options, it will output
the contents of its session table.
If it is run with only the option -L
, it will output the contents of
the session table in a format suitable for automatic parsing. The option
is ignored if given with a command to open or close a session. The output
consists of a set of lines, one per session, each containing the following
elements separated by spaces:
The file descriptor in use for the connection. For normal inbound (I
)
and outbound (O
) connections this may be read and written by the usual
shell mechanisms. However, it should only be close with ‘ztcp -c
’.
A letter indicating how the session was created:
Z
A session created with the zftp
command.
L
A connection opened for listening with ‘ztcp -l
’.
I
An inbound connection accepted with ‘ztcp -a
’.
O
An outbound connection created with ‘ztcp
host ...’.
This is usually set to an all-zero IP address as the address of the localhost is irrelevant.
This is likely to be zero unless the connection is for listening.
This is the fully qualified domain name of the peer, if available, else an IP address. It is an all-zero IP address for a session opened for listening.
This is zero for a connection opened for listening.
ztcp
[ -v
] [ -d
fd ] host [ port ]Open a new TCP connection to host. If the port is
omitted, it will default to port 23. The connection will
be added to the session table and the shell parameter
REPLY
will be set to the file descriptor associated
with that connection.
If -d
is specified, its argument will be taken as the target file
descriptor for the connection.
In order to elicit more verbose output, use -v
.
ztcp
-l
[ -v
] [ -d
fd ] portztcp -l
will open a socket listening on TCP
port. The socket will be added to the
session table and the shell parameter REPLY
will be set to the file descriptor associated
with that listener.
If -d
is specified, its argument will be taken as the target file
descriptor for the connection.
In order to elicit more verbose output, use -v
.
ztcp
-a
[ -tv
] [ -d
targetfd ] listenfdztcp -a
will accept an incoming connection
to the port associated with listenfd.
The connection will be added to the session
table and the shell parameter REPLY
will
be set to the file descriptor associated with
the inbound connection.
If -d
is specified, its argument
will be taken as the target file descriptor for the
connection.
If -t
is specified, ztcp
will return
if no incoming connection is pending. Otherwise
it will wait for one.
In order to elicit more verbose output, use -v
.
ztcp
-cf
[ -v
] [ fd ]ztcp
-c
[ -v
] [ fd ]ztcp -c
will close the socket associated
with fd. The socket will be removed from the
session table. If fd is not specified,
ztcp
will close everything in the session table.
Normally, sockets registered by zftp (see
The zsh/zftp Module
) cannot be closed this way. In order
to force such a socket closed, use -f
.
In order to elicit more verbose output, use -v
.
Here is how to create a TCP connection between two instances of zsh. We need to pick an unassigned port; here we use the randomly chosen 5123.
On host1
,
zmodload zsh/net/tcp ztcp -l 5123 listenfd=$REPLY ztcp -a $listenfd fd=$REPLY
The second from last command blocks until there is an incoming connection.
Now create a connection from host2
(which may, of course, be the same
machine):
zmodload zsh/net/tcp ztcp host1 5123 fd=$REPLY
Now on each host, $fd
contains a file descriptor for talking to the
other. For example, on host1
:
print This is a message >&$fd
and on host2
:
read -r line <&$fd; print -r - $line
prints ‘This is a message
’.
To tidy up, on host1
:
ztcp -c $listenfd ztcp -c $fd
and on host2
ztcp -c $fd