From 66fb931217360a163b18d5f0e198eafb512184d3 Mon Sep 17 00:00:00 2001 From: Paul Ackersviller Date: Thu, 31 May 2007 05:06:21 +0000 Subject: Merge 21071 and 22360/22365: support version 2 of Yodl. --- Doc/Zsh/tcpsys.yo | 780 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 780 insertions(+) create mode 100644 Doc/Zsh/tcpsys.yo diff --git a/Doc/Zsh/tcpsys.yo b/Doc/Zsh/tcpsys.yo new file mode 100644 index 000000000..f8f65b634 --- /dev/null +++ b/Doc/Zsh/tcpsys.yo @@ -0,0 +1,780 @@ +texinode(TCP Function System)(Zftp Function System)(Zsh Modules)(Top) +chapter(TCP Function System) +cindex(TCP function system) +cindex(ztcp, function system based on) +sect(Description) + +A module tt(zsh/net/tcp) is provided to provide network I/O over +TCP/IP from within the shell; see its description in +ifzman(\ +zmanref(zshmodules) +)\ +ifnzman(\ +noderef(Zsh Modules) +). This manual page describes a function suite based on the module. +If the module is installed, the functions are usually installed at the +same time, in which case they will be available for +autoloading in the default function search path. In addition to the +tt(zsh/net/tcp) module, the tt(zsh/zselect) module is used to implement +timeouts on read operations. For troubleshooting tips, consult the +corresponding advice for the tt(zftp) functions described in +ifzman(\ +zmanref(zshftpsys) +)\ +ifnzman(\ +noderef(Zftp Function System) +). + +There are functions corresponding to the basic I/O operations open, close, +read and send, named tt(tcp_open) etc., as well as a function +tt(tcp_expect) for pattern match analysis of data read as input. The +system makes it easy to receive data from and send data to multiple named +sessions at once. In addition, it can be linked with the shell's line +editor in such a way that input data is automatically shown at the +terminal. Other facilities available including logging, filtering and +configurable output prompts. + +To use the system where it is available, it should be enough to +`tt(autoload -U tcp_open)' and run tt(tcp_open) as documented below to +start a session. The tt(tcp_open) function will autoload the remaining +functions. + +startmenu() +menu(TCP Functions) +menu(TCP Parameters) +menu(TCP Examples) +menu(TCP Bugs) +endmenu() + +texinode(TCP Functions)(TCP Parameters)()(TCP Function System) +sect(TCP User Functions) + +subsect(Basic I/O) + +startitem() +findex(tcp_open) +xitem(tt(tcp_open [-qz]) var(host port) tt([) var(sess) tt(])) +xitem(tt(tcp_open [-qz] [ -s) var(sess) tt(| -l) var(sess)tt(,... ] ... )) +item(tt(tcp_open [-qz] [-a) var(fd) tt(| -f) var(fd) tt(] [) var(sess) tt(]))( +Open a new session. In the first and simplest form, open a TCP connection +to host var(host) at port var(port); numeric and symbolic forms are +understood for both. + +If var(sess) is given, this becomes the name of the session which can be +used to refer to multiple different TCP connections. If var(sess) is +not given, the function will invent a numeric name value (note this is +em(not) the same as the file descriptor to which the session is attached). +It is recommended that session names not include `funny' characters, where +funny characters are not well-defined but certainly do not include +alphanumerics or underscores, and certainly do include whitespace. + +In the second case, one or more sessions to be opened are given by name. +A single session name is given after tt(-s) and a comma-separated list +after tt(-l); both options may be repeated as many times as necessary. +The host and port are read from the file tt(.ztcp_sessions) in the same +directory as the user's zsh initialisation files, i.e. usually the home +directory, but tt($ZDOTDIR) if that is set. The file consists of lines +each giving a session name and the corresponding host and port, in that +order (note the session name comes first, not last), separated by +whitespace. + +The third form allows passive and fake TCP connections. If the option +tt(-a) is used, its argument is a file descriptor open for listening for +connections. No function front-end is provided to open such a file +descriptor, but a call to `tt(ztcp -l) var(port)' will create one with the +file descriptor stored in the parameter tt($REPLY). The listening port can +be closed with `tt(ztcp -c) var(fd)'. A call to `tt(tcp_open -a) var(fd)' +will block until a remote TCP connection is made to var(port) on the local +machine. At this point, a session is created in the usual way and is +largely indistinguishable from an active connection created with one of the +first two forms. + +If the option tt(-f) is used, its argument is a file descriptor which is +used directly as if it were a TCP session. How well the remainder of the +TCP function system copes with this depends on what actually underlies this +file descriptor. A regular file is likely to be unusable; a FIFO (pipe) of +some sort will work better, but note that it is not a good idea for two +different sessions to attempt to read from the same FIFO at once. + +If the option tt(-q) is given with any of the three forms, tt(tcp_open) +will not print informational messages, although it will in any case exit +with an appropriate status. + +If the line editor (zle) is in use, which is typically the case if the +shell is interactive, tt(tcp_open) installs a handler inside tt(zle) which +will check for new data at the same time as it checks for keyboard input. +This is convenient as the shell consumes no CPU time while waiting; the +test is performed by the operating system. Giving the option tt(-z) to +any of the forms of tt(tcp_open) prevents the handler from being +installed, so data must be read explicitly. Note, however, this is not +necessary for executing complete sets of send and read commands from a +function, as zle is not active at this point. Generally speaking, the +handler is only active when the shell is waiting for input at a command +prompt or in the tt(vared) builtin. The option has no effect if zle is not +active; `tt([[ -o zle]])' will test for this. + +The first session to be opened becomes the current session and subsequent +calls to tt(tcp_open) do not change it. The current session is stored +in the parameter tt($TCP_SESS); see below for more detail about the +parameters used by the system. +) +findex(tcp_close) +item(tt(tcp_close [-qn] [ -a | -l) var(sess)tt(,... |) var(sess) tt(... ]))( +Close the named sessions, or the current session if none is given, +or all open sessions if tt(-a) is given. The options tt(-l) and tt(-s) are +both handled for consistency with tt(tcp_open), although the latter is +redundant. + +If the session being closed is the current one, tt($TCP_SESS) is unset, +leaving no current session, even if there are other sessions still open. + +If the session was opened with tt(tcp_open -f), the file descriptor is +closed so long as it is in the range 0 to 9 accessible directly from the +command line. If the option tt(-n) is given, no attempt will be made to +close file descriptors in this case. The tt(-n) option is not used for +genuine tt(ztcp) session; the file descriptors are always closed with the +session. + +If the option tt(-q) is given, no informational messages will be printed. +) +findex(tcp_read) +xitem(tt(tcp_read [-bdq] [ -t) var(TO) tt(] [ -T) var(TO) tt(])) +item( tt([ -a | -u) var(fd) tt(... | -l) var(sess)tt(,... | -s) var(sess) tt(...]))( +Perform a read operation on the current session, or on a list of +sessions if any are given with tt(-u), tt(-l) or tt(-s), or all open +sessions if the option tt(-a) is given. Any of the tt(-u), tt(-l) or +tt(-s) options may be repeated or mixed together. The tt(-u) option +specifies a file descriptor directly (only those managed by this system +are useful), the other two specify sessions as described for +tt(tcp_open) above. + +The function checks for new data available on all the sessions listed. +Unless the tt(-b) option is given, it will not block waiting for new data. +Any one line of data from any of the available sessions will be read, +stored in the parameter tt($TCP_LINE), and displayed to standard output +unless tt($TCP_SILENT) contains a non-empty string. When printed to +standard output the string tt($TCP_PROMPT) will be shown at the start of +the line; the default form for this includes the name of the session being +read. See below for more information on these parameters. In this mode, +tt(tcp_read) can be called repeatedly until it returns status 2 which +indicates all pending input from all specified sessions has been handled. + +With the option tt(-b), equivalent to an infinite timeout, the function +will block until a line is available to read from one of the specified +sessions. However, only a single line is returned. + +The option tt(-d) indicates that all pending input should be drained. In +this case tt(tcp_read) may process multiple lines in the manner given +above; only the last is stored in tt($TCP_LINE), but the complete set is +stored in the array tt($tcp_lines). This is cleared at the start of each +call to tt(tcp_read). + +The options tt(-t) and tt(-T) specify a timeout in seconds, which may be a +floating point number for increased accuracy. With tt(-t) the timeout is +applied before each line read. With tt(-T), the timeout applies to the +overall operation, possibly including multiple read operations if the +option tt(-d) is present; without this option, there is no distinction +between tt(-t) and tt(-T). + +The function does not print informational messages, but if the option +tt(-q) is given, no error message is printed for a non-existent session. + +A return status of 2 indicates a timeout or no data to read. Any other +non-zero return status indicates some error condition. + +See tt(tcp_log) for how to control where data is sent by tt(tcp_read). +) +findex(tcp_send) +xitem(tt(tcp_send [-nq] [ -s) var(sess) tt(| -l) var(sess)tt(,... ]) var(data) tt(...)) +item(tt(tcp_send [-nq] -a) var(data) tt(...))( +Send the supplied data strings to all the specified sessions in turn. The +underlying operation differs little from a `tt(print -r)' to the session's +file descriptor, although it attempts to prevent the shell from dying owing +to a tt(SIGPIPE) caused by an attempt to write to a defunct session. + +The option tt(-n) prevents tt(tcp_send) from putting a newline at the end +of the data strings. + +The remaining options all behave as for tt(tcp_read). + +The data arguments are not further processed once they have been passed to +tt(tcp_send); they are simply passed down to tt(print -r). + +If the parameter tt($TCP_OUTPUT) is a non-empty string and logging is +enabled then the data sent to each session will be echoed to the log +file+LPAR()s+RPAR() with tt($TCP_OUTPUT) in front where appropriate, much +in the manner of tt($TCP_PROMPT). +) +enditem() + +subsect(Session Management) + +startitem() +findex(tcp_alias) +xitem(tt(tcp_alias [-q]) var(alias)tt(=)var(sess) tt(...)) +xitem(tt(tcp_alias [-q] [) var(alias) tt(] ...)) +item(tt(tcp_alias -d [-q]) var(alias) tt(...))( +This function is not particularly well tested. + +The first form creates an alias for a session name; var(alias) can then be +used to refer to the existing session var(sess). As many aliases may be +listed as required. + +The second form lists any aliases specified, or all aliases if none. + +The third form deletes all the aliases listed. The underlying sessions are +not affected. + +The option tt(-q) suppresses an inconsistently chosen subset of error +messages. +) +findex(tcp_log) +item(tt(tcp_log [-asc] [ -n | -N ] [) var(logfile) tt(]))( +With an argument var(logfile), all future input from tt(tcp_read) will be +logged to the named file. Unless tt(-a) (append) is given, this file will +first be truncated or created empty. With no arguments, show the current +status of logging. + +With the option tt(-s), per-session logging is enabled. Input from +tt(tcp_read) is output to the file var(logfile).var(sess). As the +session is automatically discriminated by the filename, the contents are +raw (no tt($TCP_PROMPT)). The option tt(-a) applies as above. +Per-session logging and logging of all data in one file are not mutually +exclusive. + +The option tt(-c) closes all logging, both complete and per-session logs. + +The options tt(-n) and tt(-N) respectively turn off or restore output of +data read by tt(tcp_read) to standard output; hence `tt(tcp_log -cn)' turns +off all output by tt(tcp_read). + +The function is purely a convenient front end to setting the parameters +tt($TCP_LOG), tt($TCP_LOG_SESS), tt($TCP_SILENT), which are described below. +) +findex(tcp_rename) +item(tt(tcp_rename) var(old) var(new))( +Rename session var(old) to session var(new). The old name becomes invalid. +) +findex(tcp_sess) +item(tt(tcp_sess [) var(sess) tt([) var(command) tt(... ] ]))( +With no arguments, list all the open sessions and associated file +descriptors. The current session is marked with a star. For use in +functions, direct access to the parameters tt($tcp_by_name), tt($tcp_by_fd) +and tt($TCP_SESS) is probably more convenient; see below. + +With a var(sess) argument, set the current session to var(sess). +This is equivalent to changing tt($TCP_SESS) directly. + +With additional arguments, temporarily set the current session while +executing the string tt(command ...). The first argument is re-evaluated +so as to expand aliases etc., but the remaining arguments are passed +through as the appear to tt(tcp_sess). The original session is restored +when tt(tcp_sess) exits. +) +enditem() + +subsect(Advanced I/O) + +startitem() +findex(tcp_command) +item(tt(tcp_command) var(send-options) tt(...) var(send-arguments) tt(...))( +This is a convenient front-end to tt(tcp_send). All arguments are passed +to tt(tcp_send), then the function pauses waiting for data. While data is +arriving at least every tt($TCP_TIMEOUT) (default 0.3) seconds, data is +handled and printed out according to the current settings. Status 0 is +always returned. + +This is generally only useful for interactive use, to prevent the display +becoming fragmented by output returned from the connection. Within a +programme or function it is generally better to handle reading data by a +more explicit method. +) +findex(tcp_expect) +xitem(tt(tcp_expect [ -q ] [ -p) var(var) tt(] [ -t ) var(to) tt(| -T) var(TO)tt(])) +item(tt( [ -a | -s) var(sess) tt(... | -l) var(sess)tt(,... ]) var(pattern) ...)( +Wait for input matching any of the given var(pattern)s from any of the +specified sessions. Input is ignored until an input line matches one of +the given patterns; at this point status zero is returned, the matching +line is stored in tt($TCP_LINE), and the full set of lines read during the +call to tt(tcp_expect) is stored in the array tt($tcp_expect_lines). + +Sessions are specified in the same way as tt(tcp_read): the default is to +use the current session, otherwise the sessions specified by tt(-a), +tt(-s), or tt(-l) are used. + +Each var(pattern) is a standard zsh extended-globbing pattern; note that it +needs to be quoted to avoid it being expanded immediately by filename +generation. It must match the full line, so to match a substring there +must be a `tt(*)' at the start and end. The line matched against includes +the tt($TCP_PROMPT) added by tt(tcp_read). It is possible to include the +globbing flags `tt(#b)' or `tt(#m)' in the patterns to make backreferences +available in the parameters tt($MATCH), tt($match), etc., as described in +the base zsh documentation on pattern matching. + +Unlike tt(tcp_read), the default behaviour of tt(tcp_expect) is to block +indefinitely until the required input is found. This can be modified by +specifying a timeout with tt(-t) or tt(-T); these function as in +tt(tcp_read), specifying a per-read or overall timeout, respectively, in +seconds, as an integer or floating-point number. As tt(tcp_read), the +function returns status 2 if a timeout occurs. + +The function returns as soon as any one of the patterns given match. If +the caller needs to know which of the patterns matched, the option tt(-p) +var(var) can be used; on return, tt($var) is set to the number of the +pattern using ordinary zsh indexing, i.e. the first is 1, and so on. Note +the absence of a `tt($)' in front of var(var). To avoid clashes, the +parameter cannot begin with `tt(_expect)'. + +The option tt(-q) is passed directly down to tt(tcp_read). + +As all input is done via tt(tcp_read), all the usual rules about output of +lines read apply. One exception is that the parameter tt($tcp_lines) will +only reflect the line actually matched by tt(tcp_expect); use +tt($tcp_expect_lines) for the full set of lines read during the function +call. +) +findex(tcp_proxy) +item(tt(tcp_proxy))( +This is a simple-minded function to accept a TCP connection and execute a +command with I/O redirected to the connection. Extreme caution should be +taken as there is no security whatsoever and this can leave your computer +open to the world. Ideally, it should only be used behind a firewall. + +The first argument is a TCP port on which the function will listen. + +The remaining arguments give a command and its arguments to execute with +standard input, standard output and standard error redirected to the +file descriptor on which the TCP session has been accepted. +If no command is given, a new zsh is started. This gives everyone on +your network direct access to your account, which in many cases will be a +bad thing. + +The command is run in the background, so tt(tcp_proxy) can then accept new +connections. It continues to accept new connections until interrupted. +) +findex(tcp_spam) +item(tt(tcp_spam [-ertv] [ -a | -s ) var(sess) tt(| -l) var(sess)tt(,... ]) var(cmd) tt(...))( +Execute `var(cmd) tt(...)' for each session in turn. Note this executes +the command and arguments; it does not send the command line as data +unless the tt(-t) (transmit) option is given. + +The sessions may be selected explicitly with the standard tt(-a), tt(-s) or +tt(-l) options, or may be chosen implicitly. If none of the three options +is given the rules are: first, if the array tt($tcp_spam_list) is set, this +is taken as the list of sessions, otherwise all sessions are taken. +Second, any sessions given in the array tt($tcp_no_spam_list) are removed +from the list of sessions. + +Normally, any sessions added by the `tt(-a)' flag or when all sessions are +chosen implicitly are spammed in alphabetic order; sessions given by the +tt($tcp_spam_list) array or on the command line are spammed in the order +given. The tt(-r) flag reverses the order however it was arrived it. + +The tt(-v) flag specifies that a tt($TCP_PROMPT) will be output before each +session. This is output after any modification to TCP_SESS by the +user-defined tt(tcp_on_spam) function described below. (Obviously that +function is able to generate its own output.) + +If the option tt(-e) is present, the line given as var(cmd ...) is executed +using tt(eval), otherwise it is executed without any further processing. +) +findex(tcp_talk) +item(tt(tcp_talk))( +This is a fairly simple-minded attempt to force input to the line editor to +go straight to the default TCP_SESSION. + +An escape string, tt($TCP_TALK_ESCAPE), default `:', is used to allow +access to normal shell operation. If it is on its own at the start of the +line, or followed only by whitespace, the line editor returns to normal +operation. Otherwise, the string and any following whitespace are skipped +and the remainder of the line executed as shell input without any change of +the line editor's operating mode. + +The current implementation is somewhat deficient in terms of use of the +command history. For this reason, many users will prefer to use some form +of alternative approach for sending data easily to the current session. +One simple approach is to alias some special character (such as `tt(%)') to +`tt(tcp_command -)tt(-)'. +) +findex(tcp_wait) +item(tt(tcp_wait))( +The sole argument is an integer or floating point number which gives the +seconds to delay. The shell will do nothing for that period except wait +for input on all TCP sessions by calling tt(tcp_read -a). This is similar +to the interactive behaviour at the command prompt when zle handlers are +installed. +) +enditem() + +subsect(`One-shot' file transfer) +startitem() +xitem(tt(tcp_point) var(port)) +item(tt(tcp_shoot) var(host) var(port))( +This pair of functions provide a simple way to transfer a file between +two hosts within the shell. Note, however, that bulk data transfer is +currently done using tt(cat). tt(tcp_point) reads any data arriving at +var(port) and sends it to standard output; tt(tcp_shoot) connects to +var(port) on var(host) and sends its standard input. Any unused var(port) +may be used; the standard mechanism for picking a port is to think of a +random four-digit number above 1024 until one works. + +To transfer a file from host tt(woodcock) to host tt(springes), on +tt(springes): + +example(tcp_point 8091 >output_file) + +and on tt(woodcock): + +example(tcp_shoot springes 8091