{
    "content": [
        {
            "type": "text",
            "text": "# zshtcpsys(1) (man)\n\n**Summary:** zshtcpsys - zsh tcp system\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **DESCRIPTION** (19 lines)\n- **TCP USER FUNCTIONS** (1 lines) — 4 subsections\n  - Basic I/O (139 lines)\n  - Session Management (50 lines)\n  - Advanced I/O (117 lines)\n  - `One-shot' file transfer (20 lines)\n- **TCP USER-DEFINED FUNCTIONS** (62 lines)\n- **TCP UTILITY FUNCTIONS** (34 lines)\n- **TCP USER PARAMETERS** (110 lines)\n- **TCP USER-DEFINED PARAMETERS** (18 lines)\n- **TCP UTILITY PARAMETERS** (15 lines)\n- **TCP EXAMPLES** (29 lines)\n- **TCP BUGS** (11 lines)\n\n## Full Content\n\n### NAME\n\nzshtcpsys - zsh tcp system\n\n### DESCRIPTION\n\nA  module  zsh/net/tcp  is provided to provide network I/O over TCP/IP from within the shell;\nsee its description in zshmodules(1).  This manual page describes a function suite  based  on\nthe  module.   If  the  module  is installed, the functions are usually installed at the same\ntime, in which case they will be available for autoloading in  the  default  function  search\npath.   In  addition  to  the zsh/net/tcp module, the zsh/zselect module is used to implement\ntimeouts on read operations.  For troubleshooting tips, consult the corresponding advice  for\nthe zftp functions described in zshzftpsys(1).\n\nThere  are  functions  corresponding  to the basic I/O operations open, close, read and send,\nnamed tcpopen etc., as well as a function tcpexpect for pattern match analysis of data read\nas input.  The system makes it easy to receive data from and send data to multiple named ses‐\nsions at once.  In addition, it can be linked with the shell's line editor in such a way that\ninput data is automatically shown at the terminal.  Other facilities available including log‐\nging, filtering and configurable output prompts.\n\nTo use the system where it is available, it should be enough to `autoload  -U  tcpopen'  and\nrun tcpopen as documented below to start a session.  The tcpopen function will autoload the\nremaining functions.\n\n### TCP USER FUNCTIONS\n\n#### Basic I/O\n\ntcpopen [ -qz ] host port [ sess ]\ntcpopen [ -qz ] [ -s sess | -l sess[,...] ] ...\ntcpopen [ -qz ] [ -a fd | -f fd ] [ sess ]\nOpen a new session.  In the first and simplest form, open a  TCP  connection  to  host\nhost at port port; numeric and symbolic forms are understood for both.\n\nIf  sess  is given, this becomes the name of the session which can be used to refer to\nmultiple different TCP connections.  If sess is not given, the function will invent  a\nnumeric name value (note this is not the same as the file descriptor to which the ses‐\nsion is attached).  It is recommended that session names not include  `funny'  charac‐\nters,  where  funny  characters  are not well-defined but certainly do not include al‐\nphanumerics or underscores, and certainly do include whitespace.\n\nIn the second case, one or more sessions to be opened are given  by  name.   A  single\nsession  name  is given after -s and a comma-separated list after -l; both options may\nbe repeated as many times as necessary.  A failure to open any session causes tcpopen\nto  abort.  The host and port are read from the file .ztcpsessions in the same direc‐\ntory as the user's zsh initialisation files, i.e.  usually  the  home  directory,  but\n$ZDOTDIR  if  that  is set.  The file consists of lines each giving a session name and\nthe corresponding host and port, in that order (note the session name comes first, not\nlast), separated by whitespace.\n\nThe third form allows passive and fake TCP connections.  If the option -a is used, its\nargument is a file  descriptor  open  for  listening  for  connections.   No  function\nfront-end  is  provided  to  open such a file descriptor, but a call to `ztcp -l port'\nwill create one with the file descriptor stored in the parameter $REPLY.  The  listen‐\ning port can be closed with `ztcp -c fd'.  A call to `tcpopen -a fd' will block until\na remote TCP connection is made to port on the local machine.  At this point,  a  ses‐\nsion  is created in the usual way and is largely indistinguishable from an active con‐\nnection created with one of the first two forms.\n\nIf the option -f is used, its argument is a file descriptor which is used directly  as\nif  it  were  a  TCP session.  How well the remainder of the TCP function system copes\nwith this depends on what actually underlies this file descriptor.  A regular file  is\nlikely  to  be unusable; a FIFO (pipe) of some sort will work better, but note that it\nis not a good idea for two different sessions to attempt to read from the same FIFO at\nonce.\n\nIf  the option -q is given with any of the three forms, tcpopen will not print infor‐\nmational messages, although it will in any case exit with an appropriate status.\n\nIf the line editor (zle) is in use, which is typically the case if the shell is inter‐\nactive,  tcpopen  installs  a handler inside zle which will check for new data at the\nsame time as it checks for keyboard input.  This is convenient as the  shell  consumes\nno  CPU time while waiting; the test is performed by the operating system.  Giving the\noption -z to any of the forms of tcpopen prevents the handler from  being  installed,\nso  data  must be read explicitly.  Note, however, this is not necessary for executing\ncomplete sets of send and read commands from a function, as zle is not active at  this\npoint.   Generally  speaking, the handler is only active when the shell is waiting for\ninput at a command prompt or in the vared builtin.  The option has no effect if zle is\nnot active; `[[ -o zle]]' will test for this.\n\nThe  first  session  to  be opened becomes the current session and subsequent calls to\ntcpopen do not change it.  The current session is stored in the parameter  $TCPSESS;\nsee below for more detail about the parameters used by the system.\n\nThe function tcponopen, if defined, is called when a session is opened.  See the de‐\nscription below.\n\ntcpclose [ -qn ] [ -a | -l sess[,...] | sess ... ]\nClose the named sessions, or the current session if none is given, or  all  open  ses‐\nsions  if  -a  is  given.  The options -l and -s are both handled for consistency with\ntcpopen, although the latter is redundant.\n\nIf the session being closed is the current one, $TCPSESS is unset, leaving no current\nsession, even if there are other sessions still open.\n\nIf  the  session was opened with tcpopen -f, the file descriptor is closed so long as\nit is in the range 0 to 9 accessible directly from the command line.  If the option -n\nis  given, no attempt will be made to close file descriptors in this case.  The -n op‐\ntion is not used for genuine ztcp session; the file descriptors are always closed with\nthe session.\n\nIf the option -q is given, no informational messages will be printed.\n\n\ntcpread [ -bdq ] [ -t TO ] [ -T TO ]\n[ -a | -u fd[,...] | -l sess[,...] | -s sess ... ]\nPerform  a  read operation on the current session, or on a list of sessions if any are\ngiven with -u, -l or -s, or all open sessions if the option -a is given.  Any  of  the\n-u,  -l  or  -s  options may be repeated or mixed together.  The -u option specifies a\nfile descriptor directly (only those managed by this system are useful), the other two\nspecify sessions as described for tcpopen above.\n\nThe  function checks for new data available on all the sessions listed.  Unless the -b\noption is given, it will not block waiting for new data.  Any one line  of  data  from\nany  of  the  available  sessions will be read, stored in the parameter $TCPLINE, and\ndisplayed to standard output unless $TCPSILENT contains  a  non-empty  string.   When\nprinted  to  standard  output the string $TCPPROMPT will be shown at the start of the\nline; the default form for this includes the name of the session being read.  See  be‐\nlow  for  more  information on these parameters.  In this mode, tcpread can be called\nrepeatedly until it returns status 2 which indicates all pending input from all speci‐\nfied sessions has been handled.\n\nWith the option -b, equivalent to an infinite timeout, the function will block until a\nline is available to read from one of the specified sessions.  However, only a  single\nline is returned.\n\nThe  option  -d  indicates  that  all  pending  input should be drained.  In this case\ntcpread may process multiple lines in the manner given above; only the last is stored\nin $TCPLINE, but the complete set is stored in the array $tcplines.  This is cleared\nat the start of each call to tcpread.\n\nThe options -t and -T specify a timeout in seconds, which may be a floating point num‐\nber  for  increased  accuracy.   With -t the timeout is applied before each line read.\nWith -T, the timeout applies to the overall  operation,  possibly  including  multiple\nread operations if the option -d is present; without this option, there is no distinc‐\ntion between -t and -T.\n\nThe function does not print informational messages, but if the option -q is given,  no\nerror message is printed for a non-existent session.\n\nA  return  status of 2 indicates a timeout or no data to read.  Any other non-zero re‐\nturn status indicates some error condition.\n\nSee tcplog for how to control where data is sent by tcpread.\n\ntcpsend [ -cnq ] [ -s sess | -l sess[,...] ] data ...\ntcpsend [ -cnq ] -a data ...\nSend the supplied data strings to all the specified sessions in turn.  The  underlying\noperation  differs little from a `print -r' to the session's file descriptor, although\nit attempts to prevent the shell from dying owing to a SIGPIPE caused by an attempt to\nwrite to a defunct session.\n\nThe  option -c causes tcpsend to behave like cat.  It reads lines from standard input\nuntil end of input and sends them in turn to the specified session(s)  exactly  as  if\nthey were given as data arguments to individual tcpsend commands.\n\nThe option -n prevents tcpsend from putting a newline at the end of the data strings.\n\nThe remaining options all behave as for tcpread.\n\nThe  data  arguments are not further processed once they have been passed to tcpsend;\nthey are simply passed down to print -r.\n\nIf the parameter $TCPOUTPUT is a non-empty string and logging  is  enabled  then  the\ndata  sent to each session will be echoed to the log file(s) with $TCPOUTPUT in front\nwhere appropriate, much in the manner of $TCPPROMPT.\n\n#### Session Management\n\ntcpalias [ -q ] alias=sess ...\ntcpalias [ -q ] [ alias ... ]\ntcpalias -d [ -q ] alias ...\nThis function is not particularly well tested.\n\nThe first form creates an alias for a session name; alias can then be used to refer to\nthe existing session sess.  As many aliases may be listed as required.\n\nThe second form lists any aliases specified, or all aliases if none.\n\nThe  third  form  deletes all the aliases listed.  The underlying sessions are not af‐\nfected.\n\nThe option -q suppresses an inconsistently chosen subset of error messages.\n\ntcplog [ -asc ] [ -n | -N ] [ logfile ]\nWith an argument logfile, all future input from tcpread will be logged to  the  named\nfile.   Unless  -a  (append)  is  given,  this file will first be truncated or created\nempty.  With no arguments, show the current status of logging.\n\nWith the option -s, per-session logging is enabled.  Input from tcpread is output  to\nthe file logfile.sess.  As the session is automatically discriminated by the filename,\nthe contents are raw (no $TCPPROMPT).  The option  -a applies as above.   Per-session\nlogging and logging of all data in one file are not mutually exclusive.\n\nThe option -c closes all logging, both complete and per-session logs.\n\nThe options -n and -N respectively turn off or restore output of data read by tcpread\nto standard output; hence `tcplog -cn' turns off all output by tcpread.\n\nThe function is purely a convenient front end  to  setting  the  parameters  $TCPLOG,\n$TCPLOGSESS, $TCPSILENT, which are described below.\n\ntcprename old new\nRename session old to session new.  The old name becomes invalid.\n\ntcpsess [ sess [ command [ arg ... ] ] ]\nWith  no  arguments,  list all the open sessions and associated file descriptors.  The\ncurrent session is marked with a star.  For use in functions, direct access to the pa‐\nrameters  $tcpbyname,  $tcpbyfd and $TCPSESS is probably more convenient; see be‐\nlow.\n\nWith a sess argument, set the current session to sess.  This is equivalent to changing\n$TCPSESS directly.\n\nWith  additional  arguments, temporarily set the current session while executing `com‐\nmand arg ...'.  command is re-evaluated so as to expand aliases etc., but the  remain‐\ning  args  are passed through as that appear to tcpsess.  The original session is re‐\nstored when tcpsess exits.\n\n#### Advanced I/O\n\ntcpcommand send-option ... send-argument ...\nThis is a convenient front-end to tcpsend.  All arguments  are  passed  to  tcpsend,\nthen  the  function  pauses  waiting  for data.  While data is arriving at least every\n$TCPTIMEOUT (default 0.3) seconds, data is handled and printed out according  to  the\ncurrent settings.  Status 0 is always returned.\n\nThis  is  generally  only  useful for interactive use, to prevent the display becoming\nfragmented by output returned from the connection.  Within a programme or function  it\nis generally better to handle reading data by a more explicit method.\n\n\ntcpexpect [ -q ] [ -p var | -P var ] [ -t TO | -T TO ]\n[ -a | -s sess | -l sess[,...] ] pattern ...\nWait  for input matching any of the given patterns from any of the specified sessions.\nInput is ignored until an input line matches one of the given patterns; at this  point\nstatus zero is returned, the matching line is stored in $TCPLINE, and the full set of\nlines read during the call to tcpexpect is stored in the array $tcpexpectlines.\n\nSessions are specified in the same way as tcpread: the default is to use the  current\nsession, otherwise the sessions specified by -a, -s, or -l are used.\n\nEach  pattern  is  a  standard zsh extended-globbing pattern; note that it needs to be\nquoted to avoid it being expanded immediately by filename generation.  It  must  match\nthe  full line, so to match a substring there must be a `*' at the start and end.  The\nline matched against includes the $TCPPROMPT added by tcpread.  It  is  possible  to\ninclude  the globbing flags `#b' or `#m' in the patterns to make backreferences avail‐\nable in the parameters $MATCH, $match, etc., as described in the base  zsh  documenta‐\ntion on pattern matching.\n\nUnlike  tcpread,  the  default behaviour of tcpexpect is to block indefinitely until\nthe required input is found.  This can be modified by specifying a timeout with -t  or\n-T;  these  function as in tcpread, specifying a per-read or overall timeout, respec‐\ntively, in seconds, as an integer or floating-point number.  As tcpread, the function\nreturns status 2 if a timeout occurs.\n\nThe  function  returns  as soon as any one of the patterns given match.  If the caller\nneeds to know which of the patterns matched, the option -p var can be used; on return,\n$var  is  set to the number of the pattern using ordinary zsh indexing, i.e. the first\nis 1, and so on.  Note the absence of a `$' in front of var.  To  avoid  clashes,  the\nparameter cannot begin with `expect'.  The index -1 is used if there is a timeout and\n0 if there is no match.\n\nThe option -P var works similarly to -p, but instead of numerical indexes the  regular\narguments  must begin with a prefix followed by a colon: that prefix is then used as a\ntag to which var is set when the argument matches.  The tag timeout is used  if  there\nis  a  timeout  and  the empty string if there is no match.  Note it is acceptable for\ndifferent arguments to start with the same prefix if the matches do  not  need  to  be\ndistinguished.\n\nThe option -q is passed directly down to tcpread.\n\nAs  all input is done via tcpread, all the usual rules about output of lines read ap‐\nply.  One exception is that the parameter $tcplines will only reflect the line  actu‐\nally  matched by tcpexpect; use $tcpexpectlines for the full set of lines read dur‐\ning the function call.\n\ntcpproxy\nThis is a simple-minded function to accept a TCP connection and execute a command with\nI/O  redirected to the connection.  Extreme caution should be taken as there is no se‐\ncurity whatsoever and this can leave your computer open to  the  world.   Ideally,  it\nshould only be used behind a firewall.\n\nThe first argument is a TCP port on which the function will listen.\n\nThe  remaining arguments give a command and its arguments to execute with standard in‐\nput, standard output and standard error redirected to the file descriptor on which the\nTCP  session  has  been accepted.  If no command is given, a new zsh is started.  This\ngives everyone on your network direct access to your account, which in many cases will\nbe a bad thing.\n\nThe  command  is  run in the background, so tcpproxy can then accept new connections.\nIt continues to accept new connections until interrupted.\n\ntcpspam [ -ertv ] [ -a | -s sess | -l sess[,...] ] cmd [ arg ... ]\nExecute `cmd [ arg ... ]' for each session in turn.  Note this  executes  the  command\nand  arguments; it does not send the command line as data unless the -t (transmit) op‐\ntion is given.\n\nThe sessions may be selected explicitly with the standard -a, -s or -l options, or may\nbe  chosen implicitly.  If none of the three options is given the rules are: first, if\nthe array $tcpspamlist is set, this is taken as the list of sessions, otherwise  all\nsessions are taken.  Second, any sessions given in the array $tcpnospamlist are re‐\nmoved from the list of sessions.\n\nNormally, any sessions added by the `-a' flag or when all sessions are chosen  implic‐\nitly are spammed in alphabetic order; sessions given by the $tcpspamlist array or on\nthe command line are spammed in the order given.  The -r flag reverses the order  how‐\never it was arrived it.\n\nThe  -v flag specifies that a $TCPPROMPT will be output before each session.  This is\noutput after any modification to TCPSESS by the user-defined tcponspam function de‐\nscribed below.  (Obviously that function is able to generate its own output.)\n\nIf  the  option  -e  is present, the line given as `cmd [ arg ... ]' is executed using\neval, otherwise it is executed without any further processing.\n\ntcptalk\nThis is a fairly simple-minded attempt to  force  input  to  the  line  editor  to  go\nstraight to the default TCPSESS.\n\nAn  escape  string,  $TCPTALKESCAPE,  default `:', is used to allow access to normal\nshell operation.  If it is on its own at the start of the line, or  followed  only  by\nwhitespace,  the  line  editor returns to normal operation.  Otherwise, the string and\nany following whitespace are skipped and the remainder of the line executed  as  shell\ninput without any change of the line editor's operating mode.\n\nThe  current  implementation is somewhat deficient in terms of use of the command his‐\ntory.  For this reason, many users will prefer to use some  form  of  alternative  ap‐\nproach  for  sending  data  easily  to the current session.  One simple approach is to\nalias some special character (such as `%') to `tcpcommand --'.\n\ntcpwait\nThe sole argument is an integer or floating point number which gives  the  seconds  to\ndelay.   The  shell  will  do nothing for that period except wait for input on all TCP\nsessions by calling tcpread -a.  This is similar to the interactive behaviour at  the\ncommand prompt when zle handlers are installed.\n\n#### `One-shot' file transfer\n\ntcppoint port\ntcpshoot host port\nThis  pair  of  functions  provide  a  simple way to transfer a file between two hosts\nwithin the shell.  Note, however, that bulk data transfer is currently done using cat.\ntcppoint  reads  any data arriving at port and sends it to standard output; tcpshoot\nconnects to port on host and sends its standard input.  Any unused port may  be  used;\nthe  standard  mechanism  for picking a port is to think of a random four-digit number\nabove 1024 until one works.\n\nTo transfer a file from host woodcock to host springes, on springes:\n\ntcppoint 8091 >outputfile\n\nand on woodcock:\n\ntcpshoot springes 8091 <inputfile\n\nAs these two functions do not require tcpopen to set up a TCP connection first,  they\nmay need to be autoloaded separately.\n\n### TCP USER-DEFINED FUNCTIONS\n\nCertain  functions,  if defined by the user, will be called by the function system in certain\ncontexts.  This facility depends on the module zsh/parameter, which is usually  available  in\ninteractive shells as the completion system depends on it.  None of the functions need be de‐\nfined; they simply provide convenient hooks when necessary.\n\nTypically, these are called after the requested action has been taken, so  that  the  various\nparameters will reflect the new state.\n\ntcponalias alias fd\nWhen an alias is defined, this function will be called with two arguments: the name of\nthe alias, and the file descriptor of the corresponding session.\n\ntcponawol sess fd\nIf the function tcpfdhandler is handling input from the line editor and detects that\nthe  file  descriptor is no longer reusable, by default it removes it from the list of\nfile descriptors handled by this  method  and  prints  a  message.   If  the  function\ntcponawol is defined it is called immediately before this point.  It may return sta‐\ntus 100, which indicates that the normal handling should still be performed; any other\nreturn  status indicates that no further action should be taken and the tcpfdhandler\nshould return immediately with the given status.  Typically the action of  tcponawol\nwill be to close the session.\n\nThe  variable  TCPINVALIDATEZLE will be a non-empty string if it is necessary to in‐\nvalidate the line editor display using `zle -I' before printing output from the  func‐\ntion.\n\n(`AWOL'  is  military  jargon for `absent without leave' or some variation.  It has no\npre-existing technical meaning known to the author.)\n\ntcponclose sess fd\nThis is called with the name of a session being closed and the file  descriptor  which\ncorresponded  to  that  session.   Both  will  be  invalid by the time the function is\ncalled.\n\ntcponopen sess fd\nThis is called after a new session has been defined with the session name and file de‐\nscriptor  as  arguments.   If it returns a non-zero status, opening the session is as‐\nsumed to fail and the session is closed again; however, tcpopen will continue to  at‐\ntempt to open any remaining sessions given on the command line.\n\ntcponrename oldsess fd newsess\nThis  is  called after a session has been renamed with the three arguments old session\nname, file descriptor, new session name.\n\ntcponspam sess command ...\nThis is called once for each session spammed, just before a command is executed for  a\nsession  by tcpspam.  The arguments are the session name followed by the command list\nto be executed.  If tcpspam was called with the option -t, the first command will  be\ntcpsend.\n\nThis  function  is called after $TCPSESS is set to reflect the session to be spammed,\nbut before any use of it is made.   Hence  it  is  possible  to  alter  the  value  of\n$TCPSESS  within this function.  For example, the session arguments to tcpspam could\ninclude extra information to be stripped off and processed in tcponspam.\n\nIf the function sets the parameter $REPLY to `done', the command line is not executed;\nin addition, no prompt is printed for the -v option to tcpspam.\n\ntcponunalias alias fd\nThis is called with the name of an alias and the corresponding session's file descrip‐\ntor after an alias has been deleted.\n\n### TCP UTILITY FUNCTIONS\n\nThe following functions are used by the TCP function system but will rarely if ever  need  to\nbe called directly.\n\ntcpfdhandler\nThis is the function installed by tcpopen for handling input from within the line ed‐\nitor, if that is required.  It is in the format documented for the builtin `zle -F' in\nzshzle(1) .\n\nWhile  active,  the  function sets the parameter TCPHANDLERACTIVE to 1.  This allows\nshell code called internally (for example, by setting tcponread) to tell if is being\ncalled when the shell is otherwise idle at the editor prompt.\n\ntcpoutput [ -q ] -P prompt -F fd -S sess\nThis  function  is  used for both logging and handling output to standard output, from\nwithin tcpread and (if $TCPOUTPUT is set) tcpsend.\n\nThe prompt to use is specified by -P; the default is the empty string.   It  can  con‐\ntain:\n%c     Expands  to  1  if  the session is the current session, otherwise 0.  Used with\nternary expressions such as `%(c.-.+)' to output `+' for  the  current  session\nand `-' otherwise.\n\n%f     Replaced by the session's file descriptor.\n\n%s     Replaced by the session name.\n\n%%     Replaced by a single `%'.\n\nThe option -q suppresses output to standard output, but not to any log files which are\nconfigured.\n\nThe -S and -F options are used to pass in the session name  and  file  descriptor  for\npossible replacement in the prompt.\n\n### TCP USER PARAMETERS\n\nParameters follow the usual convention that uppercase is used for scalars and integers, while\nlowercase is used for normal and associative array.  It is always safe for user code to  read\nthese  parameters.   Some parameters may also be set; these are noted explicitly.  Others are\nincluded in this group as they are set by the function system for the  user's  benefit,  i.e.\nsetting them is typically not useful but is benign.\n\nIt is often also useful to make settable parameters local to a function.  For example, `local\nTCPSILENT=1' specifies that data read during the function call will not be printed to  stan‐\ndard output, regardless of the setting outside the function.  Likewise, `local TCPSESS=sess'\nsets a session for the duration of a function, and  `local  TCPPROMPT='  specifies  that  no\nprompt is used for input during the function.\n\ntcpexpectlines\nArray.   The  set of lines read during the last call to tcpexpect, including the last\n($TCPLINE).\n\ntcpfilter\nArray. May be set directly.  A set of extended globbing patterns which, if matched  in\ntcpoutput,  will  cause  the line not to be printed to standard output.  The patterns\nshould be defined as described for the arguments to tcpexpect.  Output of line to log\nfiles is not affected.\n\nTCPHANDLERACTIVE\nScalar.   Set  to  1 within tcpfdhandler to indicate to functions called recursively\nthat they have been called during an editor session.  Otherwise unset.\n\nTCPLINE\nThe last line read by tcpread, and hence also tcpexpect.\n\nTCPLINEFD\nThe file descriptor from which $TCPLINE was  read.   ${tcpbyfd[$TCPLINEFD]}  will\ngive the corresponding session name.\n\ntcplines\nArray.  The  set  of  lines  read during the last call to tcpread, including the last\n($TCPLINE).\n\nTCPLOG\nMay be set directly, although it is also controlled by tcplog.  The name of a file to\nwhich  output  from  all  sessions will be sent.  The output is proceeded by the usual\n$TCPPROMPT.  If it is not an absolute path name, it will follow  the  user's  current\ndirectory.\n\nTCPLOGSESS\nMay  be set directly, although it is also controlled by tcplog.  The prefix for a set\nof files to which output from each session separately will be sent; the full  filename\nis  ${TCPLOGSESS}.sess.   Output  to each file is raw; no prompt is added.  If it is\nnot an absolute path name, it will follow the user's current directory.\n\ntcpnospamlist\nArray.  May be set directly.  See tcpspam for how this is used.\n\nTCPOUTPUT\nMay be set directly.  If a non-empty string, any data sent to a  session  by  tcpsend\nwill  be  logged.   This  parameter gives the prompt to be used in a file specified by\n$TCPLOG but not in a file generated from $TCPLOGSESS.  The prompt  string  has  the\nsame format as TCPPROMPT and the same rules for its use apply.\n\nTCPPROMPT\nMay be set directly.  Used as the prefix for data read by tcpread which is printed to\nstandard output or to the log file given by $TCPLOG, if any.  Any `%s', `%f' or  `%%'\noccurring in the string will be replaced by the name of the session, the session's un‐\nderlying file descriptor, or a single `%', respectively.  The expression `%c'  expands\nto  1 if the session being read is the current session, else 0; this is most useful in\nternary expressions such as `%(c.-.+)' which outputs `+' if the session is the current\none, else `-'.\n\nIf the prompt starts with %P, this is stripped and the complete result of the previous\nstage is passed through standard prompt %-style formatting before being output.\n\nTCPREADDEBUG\nMay be set directly.  If this has non-zero length, tcpread will give some limited di‐\nagnostics about data being read.\n\nTCPSECONDSSTART\nThis value is created and initialised to zero by tcpopen.\n\nThe  functions tcpread and tcpexpect use the shell's SECONDS parameter for their own\ntiming purposes.  If that parameter is not of floating point type on entry to  one  of\nthe  functions,  it  will create a local parameter SECONDS which is floating point and\nset the parameter TCPSECONDSSTART to the previous value of $SECONDS.  If the parame‐\nter  is  already  floating  point,  it  is used without a local copy being created and\nTCPSECONDSSTART is not set.  As the global value is zero, the shell elapsed time  is\nguaranteed to be the sum of $SECONDS and $TCPSECONDSSTART.\n\nThis can be avoided by setting SECONDS globally to a floating point value using `type‐‐\nset -F SECONDS'; then the TCP functions will never make a local  copy  and  never  set\nTCPSECONDSSTART to a non-zero value.\n\nTCPSESS\nMay  be  set  directly.  The current session; must refer to one of the sessions estab‐\nlished by tcpopen.\n\nTCPSILENT\nMay be set directly, although it is  also  controlled  by  tcplog.   If  of  non-zero\nlength, data read by tcpread will not be written to standard output, though may still\nbe written to a log file.\n\ntcpspamlist\nArray.  May be set directly.  See the description of the  function  tcpspam  for  how\nthis is used.\n\nTCPTALKESCAPE\nMay  be  set  directly.   See the description of the function tcptalk for how this is\nused.\n\nTCPTIMEOUT\nMay be set directly.  Currently this is only used by  the  function  tcpcommand,  see\nabove.\n\n### TCP USER-DEFINED PARAMETERS\n\nThe following parameters are not set by the function system, but have a special effect if set\nby the user.\n\ntcponread\nThis should be an associative array; if it is not, the behaviour is  undefined.   Each\nkey is the name of a shell function or other command, and the corresponding value is a\nshell pattern (using EXTENDEDGLOB).  Every line read from a TCP session  directly  or\nindirectly  using  tcpread  (which  includes  lines  read  by tcpexpect) is compared\nagainst the pattern.  If the line matches, the command given in the key is called with\ntwo  arguments: the name of the session from which the line was read, and the line it‐\nself.\n\nIf any function called to handle a line returns a non-zero status,  the  line  is  not\noutput.   Thus a tcponread handler containing only the instruction `return 1' can be\nused to suppress output of particular lines (see, however,  tcpfilter  above).   How‐\never,  the  line  is  still  stored  in  TCPLINE and tcplines; this occurs after all\ntcponread processing.\n\n### TCP UTILITY PARAMETERS\n\nThese parameters are controlled by the function system; they may be read directly, but should\nnot usually be set by user code.\n\ntcpaliases\nAssociative array.  The keys are the names of sessions established with tcpopen; each\nvalue is a space-separated list of aliases which refer to that session.\n\ntcpbyfd\nAssociative array.  The keys are session file descriptors; each value is the  name  of\nthat session.\n\ntcpbyname\nAssociative  array.   The  keys  are the names of sessions; each value is the file de‐\nscriptor associated with that session.\n\n### TCP EXAMPLES\n\nHere is a trivial example using a remote calculator.\n\nTo create a calculator server on port 7337 (see the dc manual page for quite how  infuriating\nthe underlying command is):\n\ntcpproxy 7337 dc\n\nTo connect to this from the same host with a session also named `dc':\n\ntcpopen localhost 7337 dc\n\nTo send a command to the remote session and wait a short while for output (assuming dc is the\ncurrent session):\n\ntcpcommand 2 4 + p\n\nTo close the session:\n\ntcpclose\n\nThe tcpproxy needs to be killed to be stopped.  Note this will not usually kill any  connec‐\ntions  which  have already been accepted, and also that the port is not immediately available\nfor reuse.\n\nThe following chunk of code puts a list of sessions into an xterm header,  with  the  current\nsession followed by a star.\n\nprint -n \"\\033]2;TCP:\" ${(k)tcpbyname:/$TCPSESS/$TCPSESS\\*} \"\\a\"\n\n### TCP BUGS\n\nThe function tcpread uses the shell's normal read builtin.  As this reads a complete line at\nonce, data arriving without a terminating newline can cause the  function  to  block  indefi‐\nnitely.\n\nThough  the  function  suite  works  well  for interactive use and for data arriving in small\namounts, the performance when large amounts of data are being exchanged is likely to  be  ex‐\ntremely poor.\n\n\n\nzsh 5.8.1                                 February 12, 2022                             ZSHTCPSYS(1)\n\n"
        }
    ],
    "structuredContent": {
        "command": "zshtcpsys",
        "section": "1",
        "mode": "man",
        "summary": "zshtcpsys - zsh tcp system",
        "synopsis": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 19,
                "subsections": []
            },
            {
                "name": "TCP USER FUNCTIONS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Basic I/O",
                        "lines": 139
                    },
                    {
                        "name": "Session Management",
                        "lines": 50
                    },
                    {
                        "name": "Advanced I/O",
                        "lines": 117
                    },
                    {
                        "name": "`One-shot' file transfer",
                        "lines": 20
                    }
                ]
            },
            {
                "name": "TCP USER-DEFINED FUNCTIONS",
                "lines": 62,
                "subsections": []
            },
            {
                "name": "TCP UTILITY FUNCTIONS",
                "lines": 34,
                "subsections": []
            },
            {
                "name": "TCP USER PARAMETERS",
                "lines": 110,
                "subsections": []
            },
            {
                "name": "TCP USER-DEFINED PARAMETERS",
                "lines": 18,
                "subsections": []
            },
            {
                "name": "TCP UTILITY PARAMETERS",
                "lines": 15,
                "subsections": []
            },
            {
                "name": "TCP EXAMPLES",
                "lines": 29,
                "subsections": []
            },
            {
                "name": "TCP BUGS",
                "lines": 11,
                "subsections": []
            }
        ]
    }
}