TCP Parameters (zsh)

### 24.5 TCP User Parameters ¶

Parameters follow the usual convention that uppercase is used for scalars and integers, while lowercase is used for normal and associative array. It is always safe for user code to read these parameters. Some parameters may also be set; these are noted explicitly. Others are included in this group as they are set by the function system for the user’s benefit, i.e. setting them is typically not useful but is benign.

It is often also useful to make settable parameters local to a function. For example, ‘`local TCP_SILENT=1`’ specifies that data read during the function call will not be printed to standard output, regardless of the setting outside the function. Likewise, ‘`local TCP_SESS=`sess’ sets a session for the duration of a function, and ‘`local TCP_PROMPT=`’ specifies that no prompt is used for input during the function.

`tcp_expect_lines` ¶

  Array. The set of lines read during the last call to `tcp_expect`, including the last (`$TCP_LINE`).

`tcp_filter` ¶

  Array. May be set directly. A set of extended globbing patterns which, if matched in `tcp_output`, will cause the line not to be printed to standard output. The patterns should be defined as described for the arguments to `tcp_expect`. Output of line to log files is not affected.

`TCP_HANDLER_ACTIVE` ¶

  Scalar. Set to 1 within `tcp_fd_handler` to indicate to functions called recursively that they have been called during an editor session. Otherwise unset.

`TCP_LINE` ¶

  The last line read by `tcp_read`, and hence also `tcp_expect`.

`TCP_LINE_FD` ¶

  The file descriptor from which `$TCP_LINE` was read. `${tcp_by_fd[$TCP_LINE_FD]}` will give the corresponding session name.

`tcp_lines` ¶

  Array. The set of lines read during the last call to `tcp_read`, including the last (`$TCP_LINE`).

`TCP_LOG` ¶

  May be set directly, although it is also controlled by `tcp_log`. The name of a file to which output from all sessions will be sent. The output is proceeded by the usual `$TCP_PROMPT`. If it is not an absolute path name, it will follow the user’s current directory.

`TCP_LOG_SESS` ¶

  May be set directly, although it is also controlled by `tcp_log`. The prefix for a set of files to which output from each session separately will be sent; the full filename is `${TCP_LOG_SESS}.`sess. Output to each file is raw; no prompt is added. If it is not an absolute path name, it will follow the user’s current directory.

`tcp_no_spam_list` ¶

  Array. May be set directly. See `tcp_spam` for how this is used.

`TCP_OUTPUT` ¶

  May be set directly. If a non-empty string, any data sent to a session by `tcp_send` will be logged. This parameter gives the prompt to be used in a file specified by `$TCP_LOG` but not in a file generated from `$TCP_LOG_SESS`. The prompt string has the same format as `TCP_PROMPT` and the same rules for its use apply.

`TCP_PROMPT` ¶

  May be set directly. Used as the prefix for data read by `tcp_read` which is printed to standard output or to the log file given by `$TCP_LOG`, if any. Any ‘`%s`’, ‘`%f`’ or ‘`%%`’ occurring in the string will be replaced by the name of the session, the session’s underlying file descriptor, or a single ‘`%`’, respectively. The expression ‘`%c`’ expands to 1 if the session being read is the current session, else 0; this is most useful in ternary expressions such as ‘`%(c.-.+)`’ which outputs ‘`+`’ if the session is the current one, else ‘`-`’.

  If the prompt starts with `%P`, this is stripped and the complete result of the previous stage is passed through standard prompt `%`-style formatting before being output.

`TCP_READ_DEBUG` ¶

  May be set directly. If this has non-zero length, `tcp_read` will give some limited diagnostics about data being read.

`TCP_SECONDS_START` ¶

  This value is created and initialised to zero by tcp_open.

  The functions `tcp_read` and `tcp_expect` use the shell’s `SECONDS` parameter for their own timing purposes. If that parameter is not of floating point type on entry to one of the functions, it will create a local parameter `SECONDS` which is floating point and set the parameter `TCP_SECONDS_START` to the previous value of `$SECONDS`. If the parameter is already floating point, it is used without a local copy being created and `TCP_SECONDS_START` is not set. As the global value is zero, the shell elapsed time is guaranteed to be the sum of `$SECONDS` and `$TCP_SECONDS_START`.

  This can be avoided by setting `SECONDS` globally to a floating point value using ‘`typeset -F SECONDS`’; then the TCP functions will never make a local copy and never set `TCP_SECONDS_START` to a non-zero value.

`TCP_SESS` ¶

  May be set directly. The current session; must refer to one of the sessions established by `tcp_open`.

`TCP_SILENT` ¶

  May be set directly, although it is also controlled by `tcp_log`. If of non-zero length, data read by `tcp_read` will not be written to standard output, though may still be written to a log file.

`tcp_spam_list` ¶

  Array. May be set directly. See the description of the function `tcp_spam` for how this is used.

`TCP_TALK_ESCAPE` ¶

  May be set directly. See the description of the function `tcp_talk` for how this is used.

`TCP_TIMEOUT` ¶

  May be set directly. Currently this is only used by the function `tcp_command`, see above.

### 24.6 TCP User-defined Parameters ¶

The following parameters are not set by the function system, but have a special effect if set by the user.

`tcp_on_read` ¶

  This should be an associative array; if it is not, the behaviour is undefined. Each key is the name of a shell function or other command, and the corresponding value is a shell pattern (using `EXTENDED_GLOB`). Every line read from a TCP session directly or indirectly using `tcp_read` (which includes lines read by `tcp_expect`) is compared against the pattern. If the line matches, the command given in the key is called with two arguments: the name of the session from which the line was read, and the line itself.

  If any function called to handle a line returns a non-zero status, the line is not output. Thus a `tcp_on_read` handler containing only the instruction ‘`return 1`’ can be used to suppress output of particular lines (see, however, `tcp_filter` above). However, the line is still stored in `TCP_LINE` and `tcp_lines`; this occurs after all `tcp_on_read` processing.

### 24.7 TCP Utility Parameters ¶

These parameters are controlled by the function system; they may be read directly, but should not usually be set by user code.

`tcp_aliases` ¶

  Associative array. The keys are the names of sessions established with `tcp_open`; each value is a space-separated list of aliases which refer to that session.

`tcp_by_fd` ¶

  Associative array. The keys are session file descriptors; each value is the name of that session.

`tcp_by_name` ¶

  Associative array. The keys are the names of sessions; each value is the file descriptor associated with that session.