zshparam

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

       zshparam - zsh parameters


DESCRIPTIONS

       A  parameter  has  a  name,  a  value,  and  a  number  of
       attributes.  A name may be any  sequence  of  alphanumeric
       characters  and  _'s, or the single characters *, @, #, ?,
       -, $, or !.  The value may be either a scalar (a  string),
       an  integer,  or  an array.  To assign a scalar or integer
       value to a parameter, use the typeset builtin.  To  assign
       an array value, use set -A name value ....  The value of a
       parameter may also be assigned by writing:

              name=value ...

       If the integer attribute, -i, is set for name,  the  value
       is subject to arithmetic evaluation.

       The  value  of an array parameter may be assigned by writ-
       ing:

              name=(value ...) ...
       Individual elements of an array may be  selected  using  a
       subscript.  A subscript of the form [exp] selects the sin-
       gle element exp, where exp  is  an  arithmetic  expression
       which  will  be  subject  to arithmetic expansion as if it
       were surrounded by "$((...))".  The elements are  numbered
       beginning  with  1.   A  subscript  of the form [*] or [@]
       evaluates to all elements of an array; there is no differ-
       ence between the two except when they appear within double
       quotes.  "$foo[*]" evaluates  to  "$foo[1]  $foo[2]  ...",
       while  "$foo[@]" evaluates to "$foo[1]" "$foo[2]", etc.  A
       subscript of the form [exp1,exp2] selects all elements  in
       the  range  exp1  to  exp2, inclusive.  If one of the sub-
       scripts evaluates to a negative number, say -n,  then  the
       nth  element  from  the  end  of  the array is used.  Thus
       "$foo[-3]" is the third element from the end of the  array
       foo, and "$foo[1,-1]" is the same as "$foo[*]".

       Subscripting may also be performed on non-array values, in
       which case  the  subscripts  specify  a  substring  to  be
       extracted.   For  example,  if  FOO is set to foobar, then
       echo $FOO[2,5] prints ooba.

       If a subscript is used on the left side of  an  assignment
       the  selected  range  is replaced by the expression on the
       right side.

       If the opening bracket or the comma is  directly  followed
       by  an  opening  parentheses the string up to the matching
       closing one is considered to be a list of flags. The flags
       currently understood are:


              e      the  argument  is  expanded using full shell
                     expansion first

              w      if the parameter  subscripted  is  a  scalar
                     than  this flag makes subscription work on a
                     per-word basis instead of characters

              s:string:
                     this gives the string that  separates  words
                     (for use with the w flag)

              r      if  this flag is given the exp is taken as a
                     pattern and the result is the first matching
                     array  element,  substring  or  word (if the
                     parameter is an array, if it is a scalar, or
                     if  it  is a scalar and the w flag is given,
                     respectively); note that this is like giving
                     a       number:       $foo[(r)??,3]      and
                     $foo[(r)??,(r)f*] work

              R      like r, but gives the last match

              i      like r, but gives the  index  of  the  match
                     instead;  this  may  not  be combined with a
                     second argument

              I      like i, but gives  the  index  of  the  last
                     match

              n:expr:
                     if  combined  with  r, R, , or I, makes them
                     give the n'th or n'th last  match  (if  expr
                     evaluates to n)

   Positional Parameters
       Positional  parameters are set by the shell on invocation,
       by the set builtin, or by direct assignment.  The  parame-
       ter  n, where n is a number, is the nth positional parame-
       ter.  The parameters *, @, and argv are arrays  containing
       all  the  positional  parameters;  thus  argv[n],  etc. is
       equivalent to simply n.


   Special Parameters
       The following parameters  are  automatically  set  by  the
       shell:

              !      The  process  id of the last background com-
                     mand invoked.
              #      The number of positional parameters in deci-
                     mal.
              ARGC   Same as #.
              $      The process id of this shell.
              -      Flags supplied to the shell on invocation or
                     by the set or setopt commands.
              *      An array containing the  positional  parame-
                     ters.
              argv   Same as *.
              @      Same as argv[@].
              ?      The exit value returned by the last command.
              status Same as ?.
              _      The last argument of the  previous  command.
                     Also,  this parameter is set in the environ-
                     ment of every command executed to  the  full
                     pathname of the command.
              EGID   The effective group id of the shell process.
                     If you have sufficient privileges,  you  may
                     change  the  effective group id of the shell
                     process  by  assigning  to  this  parameter.
                     Also  (assuming  sufficient privileges), you
                     may start a single command with a  different
                     effective group id by:
                     EGID=egid command
              EUID   The  effective user id of the shell process.
                     If you have sufficient privileges,  you  may
                     change  the  effective  user id of the shell
                     process  by  assigning  to  this  parameter.
                     Also  (assuming  sufficient privileges), you
                     may start a single command with a  different
                     effective user id by:
                     EUID=euid command
              ERRNO  The  value  of  errno  as  set  by  the most
                     recently failed system call.  This value  is
                     system  dependent and is intended for debug-
                     ging purposes.
              GID    The group id of the shell process.   If  you
                     have  sufficient  privileges, you may change
                     the group id of the shell process by assign-
                     ing  to this parameter.  Also (assuming suf-
                     ficient privileges), you may start a  single
                     command under a different group id by:
                     GID=gid command
              HOST   The current hostname.
              HOSTTYPE
                     A  string  corresponding  to the type of the
                     host the shell is running on.  This variable
                     is  obselete  and may be removed in a future
                     version.
              LINENO The line number of the current  line  within
                     the current script being executed.
              LOGNAME
                     The username corresponding to the user id of
                     the shell process at the time of login.
              MACHTYPE
                     The machine type  (microprocessor  class  or
                     machine  model),  as  determined  at compile
                     time.
              OLDPWD The previous working directory.
              OPTARG The value of the last option  argument  pro-
                     cessed by the getopts command.
              OPTIND The  index  of the last option argument pro-
                     cessed by the getopts command.
              OSTYPE The operating system, as determined at  com-
                     pile time.
              PPID   The process id of the parent of the shell.
              PWD    The present working directory.
              RANDOM A random integer from 0 to 32767, newly gen-
                     erated each time this  parameter  is  refer-
                     enced.   The  random number generator can be
                     seeded by assigning a numeric value to  RAN-
                     DOM.
              SECONDS
                     The  number  of  seconds since shell invoca-
                     tion.   If  this  parameter  is  assigned  a
                     value,  then  the value returned upon refer-
                     ence will be the  value  that  was  assigned
                     plus the number of seconds since the assign-
                     ment.
              SHLVL  Incremented by one each time a new shell  is
                     started.
              signals
                     An  array  containing  the names of the sig-
                     nals.
              TTY    The name of  the  tty  associated  with  the
                     shell, if any.
              UID    The  user  id  of the shell process.  If you
                     have sufficient privileges, you  may  change
                     the  user  id  of  the shell by assigning to
                     this parameter.  Also  (assuming  sufficient
                     privileges),  you may start a single command
                     under a different user id by:
                     UID=uid command
              USERNAME
                     The username corresponding to the user id of
                     the  shell  process.  If you have sufficient
                     privileges, you may change the username (and
                     also  the user id and group id) of the shell
                     by  assigning  to  this   parameter.    Also
                     (assuming  sufficient  privileges),  you may
                     start a single  command  under  a  different
                     username (and user id and group id) by:
                     USERNAME=username command
              VENDOR The vendor, as determined at compile time.
              ZSH_NAME
                     Expands  to the basename of the command used
                     to invoke this instance of zsh.
              ZSH_VERSION
                     The version number of this zsh.

       The following parameters are used by the shell:

              ARGV0  If exported, it's value is used  as  argv[0]
                     of  external commands.  Usually used in con-
                     structs like 'ARGV0=emacs nethack'.
              BAUD   The baud rate  of  the  current  connection.
                     Used  by the line editor update mechanism to
                     compensate for a slow terminal  by  delaying
                     updates  until necessary.  This may be prof-
                     itably set to a lower value in some  circum-
                     stances,  e.g.  for slow modems dialing into
                     a communications server which  is  connected
                     to  a  host  via  a fast link; in this case,
                     this variable would be set by default to the
                     speed  of  the fast link, and not the modem.
                     This parameter should be  set  to  the  baud
                     rate  of  the  slowest  part of the link for
                     best performance. The compensation mechanism
                     can be turned off by setting the variable to
                     zero.
              cdpath (CDPATH)
                     An array (colon-separated list) of  directo-
                     ries  specifying  the search path for the cd
                     command.
              COLUMNS
                     The number of columns for this terminal ses-
                     sion.   Used  for  printing select lists and
                     for the line editor.
              DIRSTACKSIZE
                     The maximum size of the directory stack.  If
                     the  stack gets larger than this, it will be
                     truncated  automatically.   This  is  useful
                     with the AUTO_PUSHD option.
              FCEDIT The default editor for the fc builtin.
              fignore (FIGNORE)
                     An  array  (colon separated list) containing
                     the suffixes of files to be  ignored  during
                     filename  completion.  But if the completion
                     generates only files which  would  match  if
                     this  variable  would be ignored, than these
                     files are completed anyway.
              fpath (FPATH)
                     An array (colon separated list) of  directo-
                     ries specifying the search path for function
                     definitions.  This path is searched  when  a
                     function  with  the  -u  attribute is refer-
                     enced.  If an executable file is found, then
                     it is read and executed in the current envi-
                     ronment.
              histchars
                     Three characters used by the shell's history
                     and  lexical  analysis mechanism.  The first
                     character signals the  start  of  a  history
                     substitution   (default  `!').   The  second
                     character signals the start of a quick  his-
                     tory  substitution (default `^').  The third
                     character is the comment character  (default
                     `#').
              HISTFILE
                     The  file  to  save  the  history in when an
                     interactive shell exits.  If unset, the his-
                     tory is not saved.
              HISTSIZE
                     The maximum size of the history list.
              HOME   The default argument for the cd command.
              IFS    Internal  field  separators, normally space,
                     tab, and newline, that are used to  separate
                     words which result from command or parameter
                     substitution and  words  read  by  the  read
                     builtin.
              KEYTIMEOUT
                     The  time  the shell waits, in hundredths of
                     seconds, for another key to be pressed  when
                     reading bound multi-character sequences.
              LINES  The  number  of lines for this terminal ses-
                     sion.  Used for printing  select  lists  and
                     for the line editor.
              LISTMAX
                     In  the line editor, the number of filenames
                     to list without asking  first.   If  set  to
                     zero,  the shell asks only if the top of the
                     listing would scroll off the screen.
              LITHISTSIZE
                     The maximum size of the literal history list
                     (before history expansion).
              LOGCHECK
                     The  interval  in seconds between checks for
                     login/logout activity using the watch param-
                     eter.
              MAIL   If this parameter is set and mailpath is not
                     set, the shell looks for mail in the  speci-
                     fied  file.   By  default  it  is set to the
                     user's system mailbox.
              MAILCHECK
                     The interval in seconds between  checks  for
                     new mail.
              mailpath (MAILPATH)
                     An array (colon-separated list) of filenames
                     to check for new mail.  Each filename can be
                     followed  by  a ? and a message that will be
                     printed.  The sequence  $_  in  the  message
                     will  be  replaced  by  the name of the mail
                     file.  The default message is "You have  new
                     mail."  If an element is a directory instead
                     of a file the shell will  recursively  check
                     every file in every subdirectory of the ele-
                     ment.
              manpath (MANPATH)
                     An array (colon-separated list) whose  value
                     is not used by the shell.  The manpath array
                     can be useful,  however,  since  setting  it
                     also sets MANPATH, and vice versa.
              NULLCMD
                     The  command name to assume if a redirection
                     is specified with no command.   Defaults  to
                     cat.   For sh/ksh-like behavior, change this
                     to :.  For  csh-like  behavior,  unset  this
                     parameter;  the  shell  will  print an error
                     message if null commands are entered.
              path (PATH)
                     An array (colon-separated list) of  directo-
                     ries  to  search  for  commands.   When this
                     parameter is set, each directory is  scanned
                     and all files found are put in a hash table.
              POSTEDIT
                     This string is output whenever the line edi-
                     tor  exits.   It  usually  contains  termcap
                     strings to reset the terminal.
              PROMPT The primary prompt string, printed before  a
                     command is read; the default is "%m%# ".  If
                     the escape sequence takes an optional  inte-
                     ger,  it  should  appear between the '%' and
                     the next character  of  the  sequence.   The
                     following escape sequences are recognized:

                      %d
                      %/     Present working directory ($PWD).
                      %~     $PWD.   If  it has a named directory
                             as its prefix, that part is replaced
                             by  a  ~ followed by the name of the
                             directory.  If it starts with $HOME,
                             that part is replaced by a ~.
                      %c
                      %.
                      %C     Trailing   component  of  $PWD.   An
                             integer may follow the  '%'  to  get
                             more  than one component.  Unless %C
                             is used,  tilde  expansion  is  per-
                             formed first.
                      !
                      %h
                      %!     Current history event number
                      %M     The full machine hostname.
                      %m     The  hostname  up  to the first '.'.
                             An integer may  follow  the  '%'  to
                             specify  how  many components of the
                             hostname are desired.
                      %S (%s)
                             Start (stop) standout mode.
                      %U (%u)
                             Start (stop) underline mode.
                      %B (%b)
                             Start (stop) boldface mode.
                      %t
                      %@     Current time  of  day,  in  12-hour,
                             am/pm format.
                      %T     Current time of day, in 24-hour for-
                             mat.
                      %*     Current time of day in 24-hour  for-
                             mat, with seconds.
                      %n     $USERNAME.
                      %w     The date in day-dd format.
                      %W     The date in mm/dd/yy format.
                      %D     The date in yy-mm-dd format.
                      %D{string}
                             string  is formatted using the strf-
                             time function.  See strftime(3)  for
                             more details, if your system has it.
                      %l     The line (tty) the user is logged in
                             on.
                      %?     The  return code of the last command
                             executed just before the prompt.
                      %_     The status of the parser,  i.e.  the
                             shell   constructs  (like  `if'  and
                             `for') that have been started on the
                             command  line.  If  given an integer
                             number that  many  strings  will  be
                             printed.
                      %E     Clears to end of line.
                      %#     A  '#'  if  the  shell is running as
                             root, a '%' if not.   Equivalent  to
                             %(#.#.%%).
                      %v     The  value  of  the first element of
                             the $psvar array parameter.  Follow-
                             ing  the  '%'  with an integer gives
                             that element of the array.
                      %{...%}
                             Include a string as a literal escape
                             sequence.   The  string  within  the
                             braces should not change the  cursor
                             position.
                      %(x.true-text.false-text)
                             Specifies a ternary expression.  The
                             character following the x  is  arbi-
                             trary; the same character is used to
                             separate the  text  for  the  "true"
                             result  from  that  for  the "false"
                             result.  Both the separator and  the
                             right  parenthesis  may  be  escaped
                             with  a  backslash.   True-text  and
                             false-text  may  both  contain arbi-
                             trarily-nested   escape   sequences,
                             including  further  ternary  expres-
                             sions.  The left parenthesis may  be
                             preceded  or  followed by a positive
                             integer n, which defaults  to  zero.
                             The  test  character x may be any of
                             the following:

                             c
                             .
                             ~      True  if  the  current  path,
                                    with  prefix replacement, has
                                    at least n elements.
                             /
                             C      True if the current  absolute
                                    path has at least n elements.
                             t      True if the time  in  minutes
                                    is equal to n.
                             T      True  if the time in hours is
                                    equal to n.
                             d      True if the day of the  month
                                    is equal to n.
                             D      True if the month is equal to
                                    n (January = 0).
                             w      True if the day of  the  week
                                    is equal to n (Sunday = 0).
                             ?      True  if  the  exit status of
                                    the last command was n.
                             #      True if the effective uid  of
                                    the current process is n.
                             g      True  if the effective gid of
                                    the current process is n.
                             L      True if the  SHLVL  parameter
                                    is at least n.
                             S      True if the SECONDS parameter
                                    is at least n.
                             v      True if the array  psvar  has
                                    at least n elements.
                             _      True if at least n shell con-
                                    structs were started.

              PROMPT2
                     The secondary prompt, printed when the shell
                     needs  more  information  to complete a com-
                     mand.  Recognizes the same escape  sequences
                     as $PROMPT.  The default is "> ".
              PROMPT3
                     Selection  prompt used within a select loop.
                     Recognizes  the  same  escape  sequences  as
                     $PROMPT.  The default is "?# ".
              PROMPT4
                     The  execution  trace prompt.  Default is "+
                     ".
              PS1
              PS2
              PS3
              PS4    Same  as  PROMPT,  PROMPT2,   PROMPT3,   and
                     PROMPT4, respectively.
              psvar (PSVAR)
                     An  array (colon-separated list) whose first
                     nine values can be used in  PROMPT  strings.
                     Setting  psvar  also  sets  PSVAR,  and vice
                     versa.
              prompt Same as PROMPT.
              READNULLCMD
                     The command name to assume if a single input
                     redirection  is  specified  with no command.
                     Defaults to more.
              REPORTTIME
                     If nonnegative, commands whose combined user
                     and system execution times (measured in sec-
                     onds) are greater than this value have  tim-
                     ing statistics printed for them.
              RPROMPT
              RPS1   This  prompt  is displayed on the right-hand
                     side of the screen when the  primary  prompt
                     is  being  displayed on the left.  This does
                     not work if the SINGLELINEZLE option is set.
                     Recognizes  the  same  escape  sequences  as
                     PROMPT.
              SAVEHIST
                     The maximum number of history events to save
                     in the history file.
              SPROMPT
                     The  prompt  used  for  spelling correction.
                     The sequence %R expands to the string  which
                     presumably needs spelling correction, and %r
                     expands to  the  proposed  correction.   All
                     other PROMPT escapes are also allowed.
              STTY   If  this  parameter  is  set  in a command's
                     environment, the shell runs the stty command
                     with  the  value  of this parameter as argu-
                     ments in order to set up the terminal before
                     executing  the command. The modes apply only
                     to the command, and are reset when  it  fin-
                     ishes  or  is  suspended.  If the command is
                     suspended and continued later with the fg or
                     wait  builtins  it will see the modes speci-
                     fied by STTY, as if it were  not  suspended.
                     This  (intentionally)  does not apply if the
                     command is continued via "kill -CONT".  STTY
                     is  ignored  if  the  command  is run in the
                     background, or if it is in  the  environment
                     of  the shell but not explicitly assigned to
                     in the input line. This avoids running  stty
                     at  every  external  command by accidentally
                     exporting it.  Also note  that  STTY  should
                     not  be used for window size specifications;
                     these will not be local to the command.
              TIMEFMT
                     The format of process time reports with  the
                     time  keyword.   The default is "%E real  %U
                     user  %S system   %P  %J".   Recognizes  the
                     following escape sequences:

                      %U     CPU seconds spent in user mode.
                      %S     CPU seconds spent in kernel mode.
                      %E     Elapsed time in seconds.
                      %P     The   CPU  percentage,  computed  as
                             (%U+%S)/%E.
                      %J     The name of this job.

              A star may be inserted between the percent sign and
              flags  printing  time.   This  cause the time to be
              printed in hh:mm:ss.ttt format (hours  and  minutes
              are only printed if they are not zero).
              TMOUT  If this parameter is nonzero, the shell will
                     terminate if a command is not entered within
                     the  specified number of seconds after issu-
                     ing a prompt.
              TMPPREFIX
                     A pathname prefix which the shell  will  use
                     for  all  temporary  files.   Note that this
                     should include an initial part for the  file
                     name  as  well  as any directory names.  The
                     default is /tmp/zsh.
              watch (WATCH)
                     An   array   (colon-separated    list)    of
                     login/logout  events  to report.  If it con-
                     tains  the  single  word  "all",  then   all
                     login/logout  events  are  reported.   If it
                     contains the single word "notme",  then  all
                     events  are  reported  as  with "all" except
                     $USERNAME.  An entry in this list  may  con-
                     sist  of  a  username,  an `@' followed by a
                     remote hostname, and a  `%'  followed  by  a
                     line  (tty).  Any or all of these components
                     may  be  present   in   an   entry;   if   a
                     login/logout  event  matches all of them, it
                     is reported.
              WATCHFMT
                     The format of login/logout  reports  if  the
                     watch  parameter is set.  Default is "%n has
                     %a %l from %m."   Recognizes  the  following
                     escape sequences:

                      %n     The  name  of  the  user that logged
                             in/out.
                      %a     The observed  action,  i.e.  "logged
                             on" or "logged off".
                      %l     The line (tty) the user is logged in
                             on.
                      %M     The  full  hostname  of  the  remote
                             host.
                      %m     The  hostname  up  to the first ".".
                             If only the ip address is  available
                             or  the utmp field contains the name
                             of an X-windows display,  the  whole
                             name is printed.
                      NOTE:  The %m and %M escapes will work only
                             if there is a host name field in the
                             utmp  on  your  machine.   Otherwise
                             they   are   treated   as   ordinary
                             strings.
                      %S (%s)
                             Start (stop) standout mode.
                      %U (%u)
                             Start (stop) underline mode.
                      %B (%b)
                             Start (stop) boldface mode.
                      %t
                      %@     The  time, in 12-hour, am/pm format.
                      %T     The time, in 24-hour format.
                      %w     The date in day-dd format.
                      %W     The date in mm/dd/yy format.
                      %D     The date in yy-mm-dd format.
                      %(x:true-text:false-text)
                             Specifies a ternary expression.  The
                             character  following  the x is arbi-
                             trary; the same character is used to
                             separate  the  text  for  the "true"
                             result from  that  for  the  "false"
                             result.   Both the separator and the
                             right  parenthesis  may  be  escaped
                             with  a  backslash.  Ternary expres-
                             sions may be nested.

                             The test character x may be any  one
                             of  l,  n, m, or M, which indicate a
                             "true" result if  the  corresponding
                             escape  sequence would return a non-
                             empty value;  or  may  be  a,  which
                             indicates  a  "true"  result  if the
                             watched  user  has  logged  in,   or
                             "false" if he has logged out.  Other
                             characters evaluate to neither  true
                             nor  false; the entire expression is
                             omitted in this case.

                             If the result is  "true",  then  the
                             true-text  is formatted according to
                             the rules above and printed, and the
                             false-text  is skipped.  If "false",
                             the true-text  is  skipped  and  the
                             false-text is formatted and printed.
                             Either or both of the  branches  may
                             be  empty,  but both separators must
                             be present in any case.

              WORDCHARS
                     A list of nonalphanumeric characters consid-
                     ered part of a word by the line editor.
              ZDOTDIR
                     The  directory  to  search for shell startup
                     files (.zshrc, etc), if not $HOME.
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.