476 lines
12 KiB
Plaintext
476 lines
12 KiB
Plaintext
<!--
|
|
;; $Id: vars.docbook,v 1.1 2012/08/25 07:19:03 gdr Exp $
|
|
-->
|
|
|
|
<chapter id="gsh-shellvars">
|
|
<title>Shell Variables</title>
|
|
|
|
<sect1>
|
|
<title>Using Shell Variables</title>
|
|
|
|
<para>
|
|
<command>gsh</command> supports variables in the
|
|
shell environment. These variables can be used by any shell
|
|
utility or script. Many EXE files and shell scripts predefine
|
|
certain shell variables that contain formatting options or other
|
|
options for a specific utility. As an example, the <command>ls</command>
|
|
utility looks for the variable TERM that defines the
|
|
terminal type currently being used. When <command>ls</command> is started, it
|
|
reads the value of the TERM variable and avoids printing Apple II specific
|
|
MouseText characters if the set terminal type does not support them.
|
|
</para>
|
|
|
|
<para>
|
|
<command>gsh</command> has set aside certain variables
|
|
for its specific use. Shell utilities should be aware of these
|
|
variables and use them appropriately. Use caution when changing
|
|
shell variables, because the change could affect more than just
|
|
the shell.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="gsh-shellvars-scope">
|
|
<title>Scope of Shell Variables</title>
|
|
|
|
<para>
|
|
There are two types of processes that are
|
|
involved in any discussion of a multitasking system. The original
|
|
process, <command>gsh</command> for example, is called a parent process.
|
|
If <command>gsh</command>
|
|
invokes a process, such as
|
|
<command>ls</command>,
|
|
<command>cp</command>, or
|
|
<command>mv</command>,
|
|
that process is called a child process. It is possible for any
|
|
process to define a variable. These variables will not be made
|
|
available to other processes unless the program that defined the
|
|
variable specifically makes them available.
|
|
</para>
|
|
|
|
<para>
|
|
The <command>export</command> command makes variables
|
|
defined by one process available to its children. See the example
|
|
<filename>gshrc</filename> shell script shown in
|
|
<xref linkend="gsh-start-custom"/>.
|
|
In the case of the shell, most of its
|
|
variables are exported and, therefore, all shell utilities can
|
|
read the value of a shell variable. However, programs cannot
|
|
change the value of a shell variable. In general, executables
|
|
share their environment with that of the shell, so that a utility
|
|
can change variables in its parent's environment. This allows
|
|
communication between programs and the shell.
|
|
<!-- tribby: that last paragraph seems to be self contradictory;
|
|
can a child process affect the parent's environment variables or not? -->
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="gsh-shellvars-predef">
|
|
<title>Description of Predefined Shell Variables</title>
|
|
|
|
<para>
|
|
The following variables have special meaning to <command>gsh</command>.
|
|
Shell variable names are not case sensitive.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$0, $1, $2, ...
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
String values that contain the arguments to
|
|
a shell script. Variable 0 contains the name of the
|
|
script. The first argument begins with variable 1 and so
|
|
on.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$<
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
When encountered, the variable is expanded
|
|
using a value obtained from standard input. This provides
|
|
a means of obtaining user input in script files. Note
|
|
that the shell variables are expanded before the
|
|
command-line is executed
|
|
(See <xref linkend="gsh-shellvars-access"/>.)
|
|
When prompting the user for input,
|
|
be sure that the prompt is in a separate command-line
|
|
than the $<. Also, if the user wishes to enter a value
|
|
with spaces, he must quote what he types with
|
|
double-quotes.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$ECHO
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A boolean value that, if defined, will
|
|
cause commands in a shell script to be echoed to standard
|
|
output.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$FIGNORE
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This variable, if set, contains a list of
|
|
filename suffixes. When doing command or filename
|
|
completion, <command>gsh</command> will ignore any filename with a
|
|
suffix listed in FIGNORE. For example, you might want to
|
|
<command>set fignore=".A .ROOT .SYM"</command>
|
|
to ignore object files and other compiler droppings.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$HISTORY
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A numeric value that contains the number of
|
|
history commands (command-lines) remembered. If the value
|
|
is 0 or HISTORY is undefined, all commands will be
|
|
remembered. Previous command-lines can be called back
|
|
with the UP-ARROW and DOWN-ARROW.
|
|
(See <xref linkend="gsh-interact-hist"/>.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$HOME
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The HOME directory is the main directory of the
|
|
shell; it is the directory <command>gsh</command> defaults to when it
|
|
starts. The tilde ("~") character can be used
|
|
as a shorthand method of accessing the HOME directory
|
|
(as discussed in <xref linkend="gsh-product-expand"/>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$IGNOREEOF
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A boolean value that, if enabled, will
|
|
prevent <command>^D</command> from exiting the shell.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$NOBEEP
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A boolean value that, if set, will prevent <command>gsh</command>
|
|
from sounding the speaker when errors occur while editing
|
|
a command-line.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$NODIREXEC
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A boolean value that, if set, will disable <command>gsh</command>'s
|
|
feature of treating directory names as commands; i.e. if
|
|
a directory is specified as a command, <command>gsh</command> will
|
|
move to that directory as though the cd command was being
|
|
used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$NOGLOB
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A boolean value that, if set, will
|
|
disable filename globbing. Command arguments will be
|
|
passed to their commands "as-is", without any
|
|
wildcard expansion.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$NONEWLINE
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A boolean value that, if set, will disable
|
|
extraneous carriage returns being output before and after command
|
|
execution. Examples given in this manual have
|
|
this option set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$PATH
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A string value that defines the pathnames
|
|
where shell scripts, EXE utilities, and SYS16 programs
|
|
can be found
|
|
(See <xref linkend="gsh-product-locate"/>).
|
|
Because GS/OS uses colons as separators in pathnames, <command>gsh</command>
|
|
cannot allow colons to be used as separators in the PATH
|
|
variable, as UNIX does. If one of the path entries has a
|
|
space within it (which is possible with the HFS FST),
|
|
then the space should be quoted with a backslash, "\".
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$PRECMD
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This is actually a special <emphasis>alias</emphasis> and not an environment
|
|
variable.
|
|
If PRECMD is defined then its value is taken as a a command to be executed
|
|
just before gsh prints the prompt for a command line. For example,
|
|
<command>alias precmd qtime</command> will print the time in English
|
|
text before every prompt.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$PROMPT
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
When <command>gsh</command> prompts you to enter a
|
|
command, the prompt that appears before the cursor can be
|
|
customized for your <command>gsh</command> environment. If PROMPT
|
|
is undefined, the default prompt of "% " is
|
|
used. The prompt string recognizes certain character
|
|
sequences in the PROMPT variable and interprets them accordingly.
|
|
The following are the special characters:
|
|
</para>
|
|
<para>
|
|
<table colsep="1" frame="all" rowsep="1" tocentry="1" shortentry="0"
|
|
orient="land" pgwide="0">
|
|
<title>Prompt Special Characters</title>
|
|
<tgroup cols="2">
|
|
<colspec align="left"/>
|
|
<tbody>
|
|
<row>
|
|
<entry>%h, %!, !</entry>
|
|
<entry>current history number</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%t, %@</entry>
|
|
<entry>current time of day in 12 hour am/pm format</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%d, %/</entry>
|
|
<entry>current working directory</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%~</entry>
|
|
<entry>current working directory with tilde replacement</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%c, %C, %.</entry>
|
|
<entry>trailing component of current working directory</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%S, %s</entry>
|
|
<entry>inverse mode on (%s) and off (%S)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%U, %u</entry>
|
|
<entry>
|
|
begin and end underline mode (only on terminals that support
|
|
underline; gnocon will use inverse mode instead)
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%%</entry>
|
|
<entry>the single "%" character</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%n</entry>
|
|
<entry>user name (as defined by $USER)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%W</entry>
|
|
<entry>date in mm/dd/yy format</entry>
|
|
</row>
|
|
<row>
|
|
<entry>%D</entry>
|
|
<entry>date in yy-mm-dd format</entry>
|
|
</row>
|
|
<row>
|
|
<entry>\n</entry>
|
|
<entry>newline</entry>
|
|
</row>
|
|
<row>
|
|
<entry>\r</entry>
|
|
<entry>carriage return</entry>
|
|
</row>
|
|
<row>
|
|
<entry>\t</entry>
|
|
<entry>horizontal tab</entry>
|
|
</row>
|
|
<row>
|
|
<entry>\b</entry>
|
|
<entry>bell</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$PUSHDSILENT
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If this variable is defined, <command>gsh</command>
|
|
will not print the directory stack after any of the
|
|
directory stack commands.
|
|
(See <command>pushd</command> and <command>popd</command> in
|
|
<xref linkend="gsh-commands-builtin"/>.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$SAVEHIST
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A numeric value that contains the number of
|
|
commands to save to disk when exiting <command>gsh</command>. These
|
|
commands are then read back in when <command>gsh</command> is
|
|
restarted which allows old commands to be reused. If the
|
|
value is 0 or SAVEHIST is undefined, no commands will be saved to disk.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$TERM
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This variable contains the name of the
|
|
terminal emulation that the shell and other applications
|
|
should use. By default, it is "gnocon". When
|
|
the shell encounters a <command>set term</command> command,
|
|
it automatically calls the the <command>tset</command> to reload the
|
|
termcap information.
|
|
See also <xref linkend="gsh-app-termcap"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$TERMCAP
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This variable specifies the location of the <filename>termcap</filename>
|
|
file. The shell and other applications look for <filename>termcap</filename>
|
|
in the <filename>/etc</filename> directory, but if TERMCAP is set,
|
|
the fully specified termcap file is used instead. This
|
|
allows users to install custom termcap entries.
|
|
See also <xref linkend="gsh-app-termcap"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
$USER
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A string that represents the login name of the
|
|
current user. This variable is usually set by <command>login</command>(8).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="gsh-shellvars-access">
|
|
<title>Accessing Shell Variables</title>
|
|
|
|
<para>
|
|
Shell variables are defined or changed with the
|
|
<command>set</command> command. The <command>unset</command> command
|
|
is used to delete a variable.
|
|
See <xref linkend="gsh-commands-environ"/>
|
|
for more information on the <command>set</command> and
|
|
<command>unset</command> commands.
|
|
</para>
|
|
|
|
<para>
|
|
To access shell variables from the command
|
|
line or a shell script, use the character "$" followed
|
|
by the variable name. The dollar sign character will expand the
|
|
variable to its value. If you wish to use the dollar sign
|
|
character in a string from the command line, remember to enclose
|
|
it in single quotes or use the "\" escape character. If
|
|
you use double quotes, the shell will try to expand the variable.
|
|
To differentiate the variable name from characters that may
|
|
immediately follow it, the variable name may be optionally
|
|
surrounded with braces, "{" and "}".This
|
|
provides a very powerful way of user interaction with shell
|
|
scripts.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|