.. _intro_zsh_shell_parameters:

Shell Parameters
================

The shell has many predefined parameters that may be accessed.  Here are some examples:

.. code-block:: text
   :caption: Job and status parameters
   :name: shell_params_job_status

   % sleep 10 &
   [1] 3820
   % echo $!
   3820
   % set a b c
   % echo $#
   3
   % echo $ARGC
   3
   % ( exit 20 ) ; echo $?
   20
   % false; echo $status
   1

(\ :literal:`$?` and :literal:`$status` are equivalent.)

.. code-block:: text
   :caption: Host UID and directories
   :name: shell_params_host_dirs

   % echo $HOST $HOSTTYPE
   dendrite sun4
   % echo $UID $GID
   701 60
   % cd /tmp
   % cd /home
   % echo $PWD $OLDPWD
   /home /tmp
   % ls $OLDPWD/.getwd 
   /tmp/.getwd

:literal:`~+` and :literal:`~-` are short for :literal:`$PWD` and :literal:`$OLDPWD`, respectively.

.. code-block:: text
   :caption: Tilde shortcuts and misc
   :name: shell_params_tilde_misc

   % ls ~-/.getwd
   /tmp/.getwd
   % ls -d ~+/learning
   /home/learning
   % echo $RANDOM
   4880
   % echo $RANDOM
   11785
   % echo $RANDOM
   2062
   % echo $TTY
   /dev/ttyp4
   % echo $VERSION
   zsh v2.00.03
   % echo $USERNAME
   pf

The :literal:`cdpath` variable sets the search path for the :literal:`cd` command. If you do not specify :literal:`.` somewhere in the path, it is assumed to be the first component.

.. code-block:: text
   :caption: cdpath directory search
   :name: shell_params_cdpath

   % cdpath=( /usr ~ ~/zsh )
   % ls /usr
   5bin         dict         lang         net          sccs         sys
   5include     etc          lector       nserve       services     tmp
   5lib         export       lib          oed          share        ucb
   adm          games        local        old          skel         ucbinclude
   bin          geac         lost+found   openwin      spool        ucblib
   boot         hosts        macsyma_417  pat          src          xpg2bin
   demo         include      man          princeton    stand        xpg2include
   diag         kvm          mdec         pub          swap         xpg2lib
   % cd spool
   /usr/spool
   % cd bin
   /usr/bin
   % cd func
   ~/func
   % cd 
   % cd pub
   % pwd
   /u/pfalstad/pub
   % ls -d /usr/pub
   /usr/pub

:literal:`PATH` and :literal:`path` both set the search path for commands. These two variables are equivalent, except that one is a string and one is an array.  If the user modifies :literal:`PATH`, the shell changes :literal:`path` as well, and vice versa.

.. code-block:: text
   :caption: PATH and path linked
   :name: shell_params_path_sync

   % PATH=/bin:/usr/bin:/tmp:.
   % echo $path
   /bin /usr/bin /tmp .
   % path=( /usr/bin . /usr/local/bin /usr/ucb )
   % echo $PATH
   /usr/bin:.:/usr/local/bin:/usr/ucb

The same is true of :literal:`CDPATH` and :literal:`cdpath`:

.. code-block:: text
   :caption: CDPATH and cdpath linked
   :name: shell_params_cdpath_sync

   % echo $CDPATH
   /usr:/u/pfalstad:/u/pfalstad/zsh
   % CDPATH=/u/subbarao:/usr/src:/tmp
   % echo $cdpath
   /u/subbarao /usr/src /tmp

In general, predefined parameters with names in all lowercase are arrays; assignments to them take the form:

.. code-block:: text
   :caption: Array assignment form
   :name: shell_params_array_form

   name=( elem ... )

Predefined parameters with names in all uppercase are strings.  If there is both an array and a string version of the same parameter, the string version is a colon-separated list, like :literal:`PATH`. You can use

.. code-block:: text
   :caption: typeset tied parameters
   :name: shell_params_typeset_t

   % typeset -T FOO foo

to create more of these yourself.

.. code-block:: text
   :caption: Tied array and string
   :name: shell_params_tied_demo

   % foo=( a b c )
   % echo $FOO
   a:b:c

:literal:`HISTFILE` is the name of the history file, where the history is saved when a shell exits.

.. code-block:: text
   :caption: History file and size
   :name: shell_params_histfile

   % zsh
   phoenix% HISTFILE=/tmp/history
   phoenix% SAVEHIST=20
   phoenix% echo foo
   foo
   phoenix% date
   Fri May 24 05:39:35 EDT 1991
   phoenix% uptime
     5:39am  up 4 days, 20:02,  40 users,  load average: 2.30, 2.20, 2.00
   phoenix% exit
   % cat /tmp/history
   HISTFILE=/tmp/history
   SAVEHIST=20
   echo foo
   date
   uptime
   exit
   % HISTSIZE=3
   % history
      28  rm /tmp/history
      29  HISTSIZE=3
      30  history

.. _APPEND_HISTORY:

.. index:: single: APPEND_HISTORY

If you have several instances of :literal:`zsh` running at the same time, like when using the X window system, it might be preferable to append the history of each shell to a file when a shell exits instead of overwriting the old contents of the file.  You can get this behaviour by setting the :literal:`APPEND_HISTORY` option.

In :literal:`zsh`, if you say

.. code-block:: text
   :caption: Bare redirection alone
   :name: shell_params_bare_redir

   % >file

the command :literal:`cat` is normally assumed:

.. code-block:: text
   :caption: NULLCMD cat by default
   :name: shell_params_nullcmd_cat

   % >file
   foo!    
   ^D
   % cat file
   foo!

Thus, you can view a file simply by typing:

.. code-block:: text
   :caption: Bare input shows file
   :name: shell_params_read_file

   % <file
   foo!

However, this is not csh or sh compatible.  To correct this, change the value of the parameter :literal:`NULLCMD`, which is :literal:`cat` by default.

.. code-block:: text
   :caption: NULLCMD as no-op
   :name: shell_params_nullcmd_colon

   % NULLCMD=:
   % >file
   % ls -l file
   -rw-r--r--  1 pfalstad        0 May 24 05:41 file

If :literal:`NULLCMD` is unset, the shell reports an error if no command is specified (like csh).

.. code-block:: text
   :caption: Unset NULLCMD errors
   :name: shell_params_nullcmd_unset

   % unset NULLCMD
   % >file
   zsh: redirection with no command

Actually, :literal:`READNULLCMD` is used whenever you have a null command reading input from a single file.  Thus, you can set :literal:`READNULLCMD` to :literal:`more` or :literal:`less` rather than :literal:`cat`.  Also, if you set :literal:`NULLCMD` to :literal:`:` for sh compatibility, you can still read files with :literal:`< file` if you leave :literal:`READNULLCMD` set to :literal:`more`.
