zsh: The zsh/net/tcp Module

Next: The zsh/termcap Module, Previous: The zsh/system Module, Up: Zsh Modules [Contents][Index]

### 22.27 The zsh/net/tcp Module

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:

  File descriptor

    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`’.

  Connection type

    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 ...’.

  The local host

    This is usually set to an all-zero IP address as the address of the localhost is irrelevant.

  The local port

    This is likely to be zero unless the connection is for listening.

  The remote host

    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.

  The remote port

    This is zero for a connection opened for listening.

#### 22.27.1 Outbound Connections

`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`.

#### 22.27.2 Inbound Connections

`ztcp` `-l` [ `-v` ] [ `-d` fd ] port

  `ztcp -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 ] listenfd

  `ztcp -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`.

#### 22.27.3 Closing Connections

`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`.

#### 22.27.4 Example

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

Next: The zsh/termcap Module, Previous: The zsh/system Module, Up: Zsh Modules [Contents][Index]