.. include:: ../header.txt

.. _variables:

Shell Variables
===========================

.. index:: variables

Several system defined variables are set for you when you log in.  

================   =================================
Name                 Meaning
================   =================================
:envvar:`$HOME`     Absolute pathname to your home directory.
:envvar:`$PATH`     List of directories to search for commands.
:envvar:`$USER`     Your user name.
:envvar:`$SHELL`    Absolute pathname of your login shell.
:envvar:`$TERM`     The type of your terminal.
================   =================================

You may also define new variables within your shell or shell script program.
Variables to the shell are created using a simple assignment statement with
no spaces::

    variableName=value
    
    me=$(whoami)

    echo "Hi, my name is $(getent passwd $me | cut -d: -f5)."

.. sidebar:: Something to think about ...

   Why might you want to use the command :command:`whoami` to set the `$me`
   variable instead of using the shell provided variable `$USER`?

.. note::

    * Variables are by default strings.  Holding numbers in variables
      and math on variables is covered later. (see :ref:`math`)

    * When assigning a value to a variable, do not use the $.  But use the $
      when assessing the variable.

.. _export:

:command:`export`
------------------

.. index:: export
.. program:: export
.. describe:: export

    NAMEs are marked for automatic export to the environment of
    subsequently executed commands.
    

SYNOPSIS

    :command:`export` [name[=value] ...]

Existing variables may be exported.
Variables may also exported as their value is assigned.
::

    me=$(whoami)

    export me
    
    export today=$(date)

.. seealso:: 

    :ref:`source`


.. _env:

:command:`env`
------------------

.. index:: env
.. program:: env
.. describe:: env

    Display a list of the shell environment variables or run a command
    with modified environment variables.

SYNOPSIS

    :command:`env`

    :command:`env` [OPTION]... [-] [NAME=VALUE]... COMMAND [ARG]... 

OPTIONS

    .. option:: -i, --ignore-environment

       start with an empty environment. A  mere `-` implies `-i`.

    .. option:: -u, --unset=NAME

       remove variable from the environment before running the command.

If no COMMAND, print the current environment variables.

Command Line Arguments
-----------------------

.. index:: command line arguments, arguments

Arguments or variables may be passed to a shell script.  Simply list the
arguments on the command line when running a shell script. In the shell
script, :envvar:`$0` is the name of the command run (usually the name of the shell
script file); :envvar:`$1` is the first argument, :envvar:`$2` is the second argument, 
:envvar:`$3` is the third argument, etc...

**Now for something subtle...**

The commands ``echo $*``  and ``echo $@`` both print the same thing,
the list of all command line arguments, but ":envvar:`$*`" is one string, 
and ":envvar:`$@`" is a list of separate strings for each parameter.
Consider the following two examples to see how these two
similar variables differ.  In both cases, the shell script file is ran
with three simple command line arguments as ``./myscript a b c``.

::

   for i in "$*"
   do
      echo $i
   done

Results in::

    a b c

Now here is::

   for i in "$@"
   do
      echo $i
   done

which displays::

    a
    b
    c

.. note::

   The variable :envvar:`$#` reports the number of command line arguments
   passed to the shell script program.

.. _shift:

:command:`shift`
------------------

.. index:: shift
.. program:: shift
.. describe:: shift

    Cause all of the positional parameters `$2` to `$n` to be renamed
    `$1` to `$(n-1)`, and `$1` to be lost.

SYNOPSIS

    :command:`shift` 

Here is an example that just displays all of the command line arguments::

    while [ ! -z $1 ]
    do
        echo $1
        shift
    done
    
.. note:: 

    Testing of string variables and shell script control constructs are
    covered later.

.. _exit:

Exit Code
------------

.. index:: exit code

:title:`Linux for Programmers and Users`, Section 5.21.

When a program is ran, the success or failure of the program may be
determined by evaluating the variable `$?`.  An exit value of 0 (zero) means
the program was successful, and a nonzero exit value (usually 1) indicates
failure.

.. program:: exit
.. describe:: exit

    Return an exit value from a shell script.

SYNOPSIS

    :command:`exit` [n]

.. note::

    When writing programs in C for Unix, it is customary for
    `main()` to return an integer (int) value.  Zero (0) for success and 
    1 for failure.