Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"
Traveller''s Lunchbox

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Glossary
MoreInfo
Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
FAQ
Copyright Info
Terms of Use
Privacy Info
Disclaimer
WorkBoard
Thanks
Donations
Advertising
Masthead / Impressum
Your Account

Communication
Feedback
Forums
Private Messages
Surveys

Features
HOWTOs
News Archive
Submit News
Topics
User Articles
Web Links

Google
Google


The Web
linux-tutorial.info

Who's Online
There are currently, 165 guest(s) and 0 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here

  

zshtcpsys



DESCRIPTION

       A  module  zsh/net/tcp  is provided to provide network I/O
       over TCP/IP from within the shell; see its description  in
       zshmodules(1)  .   This  manual  page describes a function
       suite based on the module.  The functions will usually  be
       installed  at  the same time as the module if that is pre­
       sent on your system, in which case they will be  available
       for  autoloading  in the default function search path.  In
       addition to the zsh/net/tcp module, the zsh/zselect module
       is  used  to  implement  timeouts on read operations.  For
       troubleshooting tips, consult the corresponding advice for
       the zftp functions described in zshftpsys(1) .

       There  are functions corresponding to the basic I/O opera­
       tions open, close, read and send, named tcp_open etc.,  as
       well  as  a function 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 includ­
       ing logging, filtering and configurable output prompts.

       To  use  the  system  where  it is available, it should be
       enough to `autoload -U tcp_open' and run tcp_open as docu­
       mented  below  to  start a session.  The tcp_open function
       will autoload the remaining functions.


TCP USER FUNCTIONS

   Basic I/O
       tcp_open [-qz] host port [ sess ]
       tcp_open [-qz] [ -s sess | -l sess,... ] ...
       tcp_open [-qz] [-a fd | -f fd ] [ sess ]
              Open a new session.   In  the  first  and  simplest
              form,  open  a  TCP connection to host host at port
              port; numeric and symbolic forms are understood for
              both.

              If sess is given, this becomes the name of the ses­
              sion which can be used to refer to multiple differ­
              ent  TCP  connections.   If  sess is not given, the
              function will invent a  numeric  name  value  (note
              this  is  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 under­
              scores, and certainly do include whitespace.

              In the second case, one  or  more  sessions  to  be
              file descriptor open for listening for connections.
              No function front-end is provided to  open  such  a
              file  descriptor, but a call to `ztcp -l port' will
              create one with the file descriptor stored  in  the
              parameter $REPLY.  The listening port can be closed
              with `ztcp -c fd'.  A call to `tcp_open -a fd' will
              block until a remote TCP connection is made to port
              on the local machine.  At this point, a session  is
              created  in  the usual way and is largely indistin­
              guishable from an active  connection  created  with
              one of the first two forms.

              If  the  option  -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  -q  is given with any of the three
              forms, tcp_open will not print  informational  mes­
              sages,  although  it  will in any case exit with an
              appropriate status.

              If the line editor (zle) is in use, which  it  usu­
              ally  is  if  and only if the shell is interactive,
              tcp_open installs a handler inside 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 systems.  However, if
              incoming  data  is  only to be read explicitly, the
              option -z to any of the forms of tcp_open  prevents
              the  handler  from  being installed.   Note 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 han­
              dler  is  only active when the shell is waiting for
              input at a command prompt or in the vared  builtin.
              The  option has no effect if zle is not active; `[[
              -o zle]]' will test for this.

              The first session to be opened becomes the  current
              session;  subsequent  calls  to  tcp_open  will not
              change this.  The current session is stored in  the
              parameter  $TCP_SESS;  see  below  for  more detail
              about the parameters used by the system.

       tcp_close [-qn] [ -a | -l sess,... | sess ... ]
              be made to close file  descriptors  in  this  case.
              The -n option is not used for genuine ztcp session;
              the file descriptors are  always  closed  with  the
              session.

              If  the  option  -q is given, no informational mes­
              sages will be printed.

       tcp_read [-bdq] [ -t TO ] [ -T TO ]
           [ -a | -u fd ... | -l sess,... | -s sess ...]
              Perform a read operation on the current session, or
              on  a  list of sessions if any are given (the first
              form), or all open sessions (the second form).  Any
              of  the  -u,  -l  or  -s options may be repeated or
              mixed together.  The -u  option  specifies  a  file
              descriptor  directly  (only  those  managed by this
              system are useful), the other two specify  sessions
              as  described  for tcp_open above.  If -a is given,
              all sessions ares examined for new data.

              The function checks for new data available  on  all
              the  sessions  listed.   Unless  the  -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  $TCP_LINE,
              and displayed to standard output unless $TCP_SILENT
              contains a non-empty string.  When printed to stan­
              dard output the string $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, 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 -b, equivalent to an infinite time­
              out, the function will block until a line is avail­
              able to read from one of  the  specified  sessions.
              However, only a single line is returned.

              The  option  -d  indicates  that  all pending input
              should be drained.  In this case tcp_read may  pro­
              cess multiple lines in the manner given above; only
              the last is stored in $TCP_LINE, but  the  complete
              set  is  stored  in  the array $tcp_lines.  This is
              cleared at the start of each call to tcp_read.

              The options -t and -T specify a timeout in seconds,
              which  may be a floating point number for increased
              accuracy.  With -t the timeout  is  applied  before
              each  line  read.   With -T, the timeout applies to
              the overall operation, possibly including  multiple

       tcp_send [-nq] [ -s sess | -l sess,... ] data ...
       tcp_send [-nq] -a data ...
              Send the supplied data strings to all the specified
              sessions in turn.  The underlying operation differs
              little from a `print  -r'  to  the  session's  file
              descriptor,  although  it  attempts  to prevent the
              shell from dying owing to a SIGPIPE  caused  by  an
              attempt to write to a defunct session.

              The option -n prevents tcp_send from putting a new­
              line at the end of the data strings.

              The remaining options all behave as for tcp_read.

              The data arguments are not further  processed  once
              they  have been passed to tcp_send; they are simply
              passed down to print -r.

              If the parameter $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(s)  with
              $TCP_OUTPUT in front where appropriate, much in the
              manner of $TCP_PROMPT.

   Session Management
       tcp_alias [-q] alias=sess ...
       tcp_alias [-q] [ alias ] ...
       tcp_alias -d [-q] alias ...
              This function is not particularly well tested.

              The first form creates an alias for a session name;
              alias  can  then  be  used to refer to the existing
              session 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  -q suppresses an inconsistently chosen
              subset of error messages.

       tcp_log [-asc] [ -n | -N ] [ logfile ]
              With an argument logfile,  all  future  input  from
              tcp_read  will be logged to the named file.  Unless
              -a (append) is given, this file will first be trun­
              cated  or  created  empty.  With no arguments, show
              the current status of logging.
              output; hence `tcp_log -cn' turns off all output by
              tcp_read.

              The function is purely a convenient  front  end  to
              setting  the  parameters  $TCP_LOG,  $TCP_LOG_SESS,
              $TCP_SILENT, which are described below.

       tcp_rename old new
              Rename session old to session new.   The  old  name
              becomes invalid.

       tcp_sess [ sess [ command  ... ] ]
              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   $tcp_by_name,
              $tcp_by_fd  and  $TCP_SESS  is probably more conve­
              nient; see below.

              With a sess argument, set the  current  session  to
              sess.   This  is  equivalent  to changing $TCP_SESS
              directly.

              With additional arguments, temporarily set the cur­
              rent  session  while  executing  the string command
              ....  The first argument is re-evaluated so  as  to
              expand  aliases  etc.,  but the remaining arguments
              are passed through as the appear to tcp_sess.   The
              original session is restored when tcp_sess exits.

   Advanced I/O
       tcp_command send-options ... send-arguments ...
              This  is  a  convenient front-end to tcp_send.  All
              arguments are passed to tcp_send, then the function
              pauses waiting for data.  While data is arriving at
              least every  $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 out­
              put returned from the connection.   Within  a  pro­
              gramme or function it is generally better to handle
              reading data by a more explicit method.

       tcp_expect [ -q ] [ -p var ] [ -t  to | -T TO]
           [ -a | -s sess ... | -l sess,... ] pattern ...
              Wait for input matching any of the  given  patterns
              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
              substring there must be a `*' at the start and end.
              The  line  matched against includes the $TCP_PROMPT
              added by tcp_read.  It is possible to  include  the
              globbing flags `#b' or `#m' in the patterns to make
              backreferences available in the parameters  $MATCH,
              $match, etc., as described in the base zsh documen­
              tation on pattern matching.

              Unlike   tcp_read,   the   default   behaviour   of
              tcp_expect  is  to  block  indefinitely  until  the
              required input is found.  This can be  modified  by
              specifying  a timeout with -t or -T; these function
              as in tcp_read, specifying a  per-read  or  overall
              timeout, respectively, in seconds, as an integer or
              floating-point number.  As tcp_read,  the  function
              returns status 2 if a timeout occurs.

              The function returns as soon as any one of the pat­
              terns given match.  If the  caller  needs  to  know
              which  of  the  patterns matched, the option -p var
              can be used; on return, $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
              `$' in front of var.  To avoid clashes, the parame­
              ter cannot begin with `_expect'.

              The option -q is passed directly down to  tcp_read.

              As  all  input  is done via tcp_read, all the usual
              rules about output of lines read apply.  One excep­
              tion  is  that  the  parameter $tcp_lines will only
              reflect the line actually  matched  by  tcp_expect;
              use  $tcp_expect_lines  for  the  full set of lines
              read during the function call.

       tcp_proxy
              This is a simple-minded function to  accept  a  TCP
              connection  and  execute  a  command with I/O redi­
              rected 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 func­
              tion 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
              standard -a, -s or -l options,  or  may  be  chosen
              implicitly.   If none of the three options is given
              the rules are: first, if the  array  $tcp_spam_list
              is set, this is taken as the list of sessions, oth­
              erwise all sessions are taken.   Second,  any  ses­
              sions  given  in  the  array  $tcp_no_spam_list are
              removed from the list of sessions.

              Normally, any sessions added by the  `-a'  flag  or
              when all sessions are chosen implicitly are spammed
              in  alphabetic  order;  sessions   given   by   the
              $tcp_spam_list  array  or  on  the command line are
              spammed in the order given.  The -r  flag  reverses
              the order however it was arrived it.

              The  -v  flag  specifies that a $TCP_PROMPT will be
              output before each session.  This is  output  after
              any  modification  to  TCP_SESS by the user-defined
              tcp_on_spam function described  below.   (Obviously
              that  function is able to generate its own output.)

       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, $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  fol­
              lowed  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 rea­
              son,  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 `%')  to  `tcp_com­
              mand --'.

       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  tcp_read  -a.
              This is similar to the interactive behaviour at the
              command prompt when zle handlers are installed.

              called with two arguments: the name of  the  alias,
              and  the  file descriptor of the corresponding ses­
              sion.

       tcp_on_close sess fd
              This is called with the name  of  a  session  being
              closed  and  the file descriptor which corresponded
              to that session.  Both will be invalid by the  time
              the function is called.

       tcp_on_open sess fd
              This is called after a new session has been defined
              with the session name and file descriptor as  argu­
              ments.

       tcp_on_rename oldsess fd newsess
              This  is  called  after  a session has been renamed
              with the three arguments  old  session  name,  file
              descriptor, new session name.

       tcp_on_spam sess command ...
              This  is called once for each session spammed, just
              before a command  is  executed  for  a  session  by
              tcp_spam.   The arguments are the session name fol­
              lowed by the  command  list  to  be  executed.   If
              tcp_spam  was  called with the option -t, the first
              command will be tcp_send.

              This function is called after $TCP_SESS is  set  to
              reflect  the  session to be spammed, but before any
              use of it is made.  Hence it is possible  to  alter
              the  value  of $TCP_SESS within this function.  For
              example, the session arguments  to  tcp_spam  could
              include  extra  information  to be stripped off and
              processed in tcp_on_spam.

              If  the  function  sets  the  parameter  $REPLY  to
              `done',  the command line is not executed; in addi­
              tion, no prompt is printed for  the  -v  option  to
              tcp_spam.

       tcp_on_unalias alias fd
              This  is  called  with the name of an alias and the
              corresponding session's file  descriptor  after  an
              alias has been deleted.


TCP UTILITY FUNCTIONS

       The  following functions are used by the TCP function sys­
       tem but will rarely if ever need to be called directly.

       tcp_fd_handler
              replaced by a single `%'.

              The option -q suppresses output to standard output,
              but not to any log files which are configured.

              The -S and -F options are used to pass in the  ses­
              sion name and file descriptor for possible replace­
              ment in the prompt.


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, which are noted explicitly.  Other  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'  speci­
       fies  that  data read during the function call will not be
       printed to standard output, regardless of the setting out­
       side the function.  Likewise, `local TCP_SESS=sess' sets a
       session for the duration of a 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_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  corre­
              sponding session name.

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

              not an absolute  path  name,  it  will  follow  the
              user's current directory.

       tcp_nospam_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.
              The prompt has the same format  as  TCP_PROMPT  and
              the  same rules for its use apply:  it is used in a
              file specified by $TCP_LOG, but not in a file  gen­
              erated from $TCP_LOG_SESS.

       TCP_PROMPT
              May  be  set directly.  Used as the prefix for data
              read by tcp_read which is printed to standard  out­
              put  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 ses­
              sion's underlying file descriptor, or a single `%',
              respectively.

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

              descriptors;  each  value  is the name of that ses­
              sion.

       tcp_by_name
              Associative array.  The keys are the names of  ses­
              sions; each value is the file descriptor associated
              with that session.


TCP EXAMPLES

       Here is a trivial example using a remote calculator.

       TO create a calculator server on port  7337  (see  the  dc
       manual  page for quite how infuriating the underlying com­
       mand is):

              tcp_proxy 7337 dc

       To connect to this from the same host with a session  also
       named `dc':

              tcp_open localhost 7337 dc

       To  send  a command to the remote session and wait a short
       while for output (assuming dc is the current session):

              tcp_command 2 4 + p

       To close the session:

              tcp_close

       The tcp_proxy needs to be killed to be stopped.  Note this
       will  not  usually kill any connections which have already
       been accepted, and also that the port is  not  immediately
       available for reuse.

       The  following  chunk of code puts a list of sessions into
       an xterm header, with the current session  followed  by  a
       star.

              print -n "\033]2;TCP:" ${(k)tcp_by_name:/$TCP_SESS/$TCP_SESS\*} "\a"


TCP BUGS

       The   function  tcp_read  uses  the  shell's  normal  read
       builtin.  As this reads a  complete  line  at  once,  data
       arriving without a terminating newline can cause the func­
       tion to block indefinitely.

       Though the function suite works well for  interactive  use
       and  for  data  arriving in small amounts, the performance
  
Show your Support for the Linux Tutorial

Purchase one of the products from our new online shop. For each product you purchase, the Linux Tutorial gets a portion of the proceeds to help keep us going.


Login
Nickname

Password

Security Code
Security Code
Type Security Code


Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!


Amazon Wish List

Did You Know?
The Linux Tutorial can use your help.


Friends



Tell a Friend About Us

Bookmark and Share



Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.09 Seconds