<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>GRASS variables and environment variables</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
<body bgcolor="white">
<img src="grass_logo.png" alt="_\|/_ GRASS logo"><hr align=center size=6 noshade>
<H2>GRASS variables and environment variables</H2>
<!-- file source:
./lib/init/variables.html
-->
<P>
There are two types of variables:
<ul>
<li><a href="#enviro">shell environment</a> variables,</li>
<li><a href="#gisenv">GRASS gisenv</a> variables.</li>
</ul>
There are a number of shell environment variable groups:
<ul>
<li><a href="#png">PNG driver</a>
<li><a href="#ps">PS driver (PostScript)</a>
<li><a href="#dirrend">variables for direct rendering</a>
<li><a href="#internal">variables for internal use</a>
</ul>
Any setting which needs to be modifiable by a GRASS program (e.g. MONITOR)
has to be a GRASS <i>gisenv</i> variable.
<h2>GRASS-related Files</h2>
GRASS maintains some settings in a number of files on the system. They are
detailed <a href="#files">below</a>.
<h2>Setting environment variables</h2>
<br>Setting environment variables depends on the shell being used:
<br> Bash: <tt>export VARIABLE=value</tt>
<br> or
<br> Csh: <tt>setenv VARIABLE value</tt>
<br> or
<br> Cmd.exe (Windows): <tt>set VARIABLE=value</tt>
<h2>Setting environment variables permanently</h2>
<ul>
<li>
To get personal BASH shell definitions (aliases, color listing option, ...)
into GRASS, store them in:<br>
<tt>$HOME/.grass.bashrc</tt></li>
<li>
To get personal CSH shell definitions (aliases, color listing option, ...)
into GRASS, store them in:<br>
<tt>$HOME/.grass.cshrc</tt></li>
</ul>
<h2>Setting GRASS variables</h2>
Use "<a href="g.gisenv.html">g.gisenv</a>" within GRASS. This permanently
predefines GRASS variables in the <tt>.grassrc6</tt> file.<br>
<p>
Usage:<BR>
<div class="code"><pre>
g.gisenv set="VARIABLE=VALUE"
</pre></div>
<p>
It looks unusual with two equals signs, but g.gisenv serves dual duty for
getting and setting GRASS variables.
<P>
If the user just specifies a variable name, it defaults to "get" mode.
For example:<br>
<div class="code"><pre>
GRASS ~> g.gisenv GRASS_GUI
text
</pre></div>
<BR>
<hr>
<BR>
<a name="enviro"></a>
<h2>List of selected (GRASS related) environment variables</h2>
<blockquote>
[ To be set from the terminal shell or startup scripts ]
</blockquote>
<p>GISBASE
<br> directory where GRASS lives. This is set automatically by the startup script.
<p>GISRC
<br> name of .grassrc6 file. GISRCRC defines the system wide value
while in a GRASS session.
<p>GRASS_ADDON_PATH
<br>[grass startup script]
<br> allows to specify additional paths to local GRASS modules extra
to standard distribution.
<p>GRASS_ADDON_ETC
<br>[libgis, g.findetc]
<br> specify paths where support files (etc/) may be found external to
standard distribution.
<p>GRASS_BATCH_JOB
<br> defines the name (path) of a shell script to be processed as batch job.
<p>GRASS_ERROR_MAIL
<br> set to any value to send user mail on an error or warning that
happens while stderr is being redirected.
<p>GRASS_GNUPLOT
<br>[<!-- m.svfit, s.probplt, s.sv -->i.spectral]
<br> program to use for plotting "gnuplot" data
<p>GRASS_GUI
<br> either "text" or "tcltk" to define non-/graphical startup.
Can also specify the name of the GUI to use, e.g. "gis.m", "d.m" or
"wxpython" (<i>wx name subject to change</i>). Also exists as a GRASS
gisenv variable (see below). If this shell variable exists at GRASS startup,
it will determine the GUI used. If it is not defined startup will default
to the last GUI used.
<p>GRASS_FONT_CAP
<br>[g.mkfontcap, d.font, display drivers]
<br> Specifies an alternative location (to $GISBASE/etc/fontcap) for
the font configuration file.
<p>GRASS_HEIGHT
<br>[d.mon]
<br> defines the height of GRASS monitor, see also GRASS_WIDTH
<P>GRASS_HTML_BROWSER
<br>[init.sh, d.m, gis.m]
<br> defines name of HTML browser. For most platforms this should be
an executable in your PATH, or the full path to an executable.<br>
Mac OS X runs applications differently from the CLI. Therefore,
GRASS_HTML_BROWSER should be the application's signature, which is a domain-like
name, just reversed. ie: com.apple.Safari. To find an application's signature,
type the following in a Terminal (fill in the path to the application you are
interested in, for example: /Applications/Safari.app):<br>
<code>grep -A 1 "CFBundleIdentifier"</code> <i>/path/to/application.app</i><code>/Contents/Info.plist</code><br>
The signature is the <string>
following the <key>, without the bracketing <string> tags.
<P>GRASS_INT_ZLIB
<br>[libgis]
<br> If the environment variable GRASS_INT_ZLIB exists, new compressed
rasters will be compressed using zlib instead of RLE compression. Such
rasters will have a "compressed" value of 2 in the cellhd file.<br>
Obviously, decompression is controlled by the raster's "compressed"
value, not the environment variable.
<p>GRASS_MESSAGE_FORMAT
<br>[various modules]
<br>Maybe set to either "standard" or "gui" (normally GRASS takes care)
<p>GRASS_MOUSE_BUTTON
<br>[various modules]
<br> swaps mouse buttons for two-button or left-handed mice. Its value
has three digits 1, 2, and 3, which represent default left, middle, and right
buttons respectively. Setting to "132" will swap middle and right buttons. Note
that this variable should be set before a display driver is initialized (e.g.,
d.mon x0).
<p>GRASS_PAGER
<br>[various modules]
<br>Maybe set to either "less" or "more"
<p>GRASS_PERL
<br>[Used during install process for generating man pages]
<br> set perl with path
<p>GRASS_RND_SEED
<br> set random seed for r.mapcalc rand() function
<!-- HB Sept 2005: I don't think this exists anymore:
<p>GRASS_STDERR
<br> set to any value to prevent user mail on error
-->
<p>GRASS_SH
<br>[shell scripts on Windows]
<br>Path to bourne shell interpreter used to run shell scripts
<p>GRASS_TCLSH
<br>[nviz]
<br> set tclsh shell name to override 'tclsh'
<p>GRASS_XTERM
<br>lib/init/grass-xterm-wrapper
<br>lib/init/grass-xterm-mac
<br> set to any value (e.g. rxvt, aterm, gnome-terminal, konsole) to
substitute 'x-terminal-emulator' or 'xterm'. The Mac OS X app
startup defaults to an internal '$GISBASE/etc/grass-xterm-mac',
which emulates the necessary xterm functionality in Terminal.app.
<p>GRASS_UI_TERM
<br> set to any value to use the terminal based parser
<p>GRASS_VERSION
<br> reports the current version number (used by R-stats interface etc);
<br> should not be changed by user
<p>GRASS_WIDTH
<br>[d.mon]
<br> defines the width of GRASS monitor, see also GRASS_HEIGHT
<p>GRASS_WISH
<br>[d.m, nviz]
<br> set wish shell name to override 'wish'
<p>GRASS_NO_GLX_PBUFFERS
<br>[nviz]
<br> set to any value to disable the use of Pbuffers
<p>GRASS_NO_GLX_PIXMAPS
<br>[nviz]
<br> set to any value to disable the use of GLX Pixmaps
<a name="png"></a>
<h3>List of selected GRASS PNG driver environment variables</h3>
<blockquote>
[ These variables control the function of the
<a href="pngdriver.html">PNG Driver</a>. ]
</blockquote>
<P></P>
<p>GRASS_PNGFILE
<br> name of PNG output file. If it ends with ".ppm" a PPM file will be created.
<p>GRASS_WIDTH
<br> defines the width of GRASS monitor, see also GRASS_HEIGHT
<p>GRASS_HEIGHT
<br> defines the height of GRASS monitor, see also GRASS_WIDTH
<p>GRASS_BACKGROUNDCOLOR
<br> defines the background color of the image created by the PNG driver
<p>GRASS_TRANSPARENT
<br> if "TRUE", the image created by the PNG driver will have a
transparent background
<p>GRASS_PNG_COMPRESSION
<br> compression level of PNG files (0 = none, 1 = fastest, 9 = best)
<p>GRASS_TRUECOLOR
<br> if "TRUE", the PNG driver generates a true-color image
<p>GRASS_PNG_AUTO_WRITE
<br> tells the PNG driver to write the image to a file whenever a
client disconnects, rather than waiting until you stop the monitor
<p>GRASS_PNG_READ
<br> if "TRUE", the PNG driver will initialize the image from
the contents of $GRASS_PNGFILE
<p>GRASS_PNG_MAPPED
<br> if "TRUE", the PNG driver will map $GRASS_PNGFILE as its framebuffer,
rather than using memory; this only works with BMP files
<a name="ps"></a>
<h3>List of selected GRASS PS driver environment variables</h3>
<blockquote>
[ These variables control the function of the
<a href="psdriver.html">PS Driver</a>. ]
</blockquote>
<P></P>
<p>GRASS_PSFILE
<br> name of output file. If it ends with ".eps" an EPS file
will be created.
<p>GRASS_PAPER <br> sets the screen dimensions and margins to
fit a standard paper size, see also GRASS_WIDTH, GRASS_HEIGHT.
<p>GRASS_WIDTH
<br> defines the width of the screen, see also GRASS_HEIGHT
<p>GRASS_HEIGHT
<br> defines the height of the screen, see also GRASS_WIDTH
<p>GRASS_TRUECOLOR
<br> if "TRUE", the PS driver generates color output, otherwise
monochrome.
<p>GRASS_LANDSCAPE
<br> if "TRUE", the screen is rotated 90 degrees
counter-clockwise so that a "landscape" screen fits better on
"portrait" paper.
<p>GRASS_PS_HEADER
<br> if "FALSE", the output is appended to any existing file,
and no prolog or setup sections are generated.
<p>GRASS_PS_TRAILER
<br> if "FALSE", no trailer section is generated.
<a name="dirrend"></a>
<h3>List of selected GRASS environment variables for direct rendering</h3>
<blockquote>
[ In addition to those which are understood by the
<a href="pngdriver.html">PNG Driver</a>, the following variables
affect direct rendering. ]
</blockquote>
<P></P>
<p>GRASS_RENDER_IMMEDIATE
<br> tells the raster library to use its built-in PNG/PS driver rather
than connecting to an external monitor process using sockets. If
GRASS_RENDER_IMMEDIATE=TRUE is set, there is no need to run
"<tt>d.mon start=PNG</tt>"
<p>GRASS_FONT
<br> specifies the font as either the name of a font from
$GISBASE/etc/fontcap (or alternative fontcap file specifed by GRASS_FONT_CAP),
or alternatively the full path to a FreeType font file.
<p>GRASS_ENCODING
<br> the encoding to be assumed for text which is drawn using a
freetype font; may be any encoding know to "iconv".
<a name="internal"></a>
<h3>List of selected internal GRASS environment variables</h3>
<blockquote>
[ These variables are intended <b>for internal use only</b> by the GRASS
software to facilitate communiction between the GIS engine, GRASS scripts,
and the GUI.
The user should not set these in a GRASS session. They are meant to be set
locally for specific commands. ]
</blockquote>
<P></P>
<p>GRASS_OVERWRITE
<br>[all modules]
<br> toggles map overwrite.
<ul>
<li> 0 - maps are protected (default),
<li> 1 - maps with identical names will be overwritten.
</ul>
This variable is automatically created by g.parser so that the
"<tt>--overwrite</tt>" option will
be inherited by dependant modules as the script runs. Setting either the
GRASS_OVERWRITE environment variable or the OVERWRITE gisenv variable detailed
below will cause maps with identical names to be overwritten.
<p>GRASS_VERBOSE
<br>[all modules]
<br> toggles verbosity level
<ul>
<li> 0 - only errors and warnings are printed
<li> 1 - progress messages are printed (percent complete)
<li> 2 - all module messages are printed
<li> 3 - additional verbose messages are printed
</ul>
This variable is automatically created by <em><a href="g.parser.html">g.parser</a></em>
so that the "<tt>--verbose</tt>" or "<tt>--quiet</tt>" flags will be inherited
by dependant modules as the script runs.
<P>GRASS_REGION
<br>[libgis]
<br> Override region settings, separate parameters with a ";". Format
is the same as in the WIND region settings file. Otherwise use is the same as
WIND_OVERRIDE.
<p>WIND_OVERRIDE
<br>[libgis]
<br>
It causes programs to use the specified named region (created with
e.g. "g.region save=...") to be used as the current region, instead of
the region from the WIND file.<br>
This allows programs such as gis.m to run external commands on an
alternate region without having to modify the WIND file then change it
back afterwards.
<BR>
<BR><HR><BR>
<a name="gisenv"></a>
<h2>List of selected GRASS gisenv variables</h2>
<blockquote>
[ Use <tt>g.gisenv</tt> to get/set/unset/change them ]
</blockquote>
<p>DEBUG
<br>[entire GRASS]
<br> sets level of debug message output (0: no debug messages)
<br><tt>g.gisenv set=DEBUG=0</tt>
<p>DM_FORM_MODE
<br>[d.m]
<br> sets default form mode (txt or gui)
<br><tt>g.gisenv set=DM_FORM_MODE=txt</tt>
<p>GISDBASE
<br> initial database
<p>GIS_LOCK
<br> lock ID to prevent parallel GRASS use,
<br> process id of the start-up shell script
<p>GRASS_DB_ENCODING
<br>[d.what.vect/forms library]
<br> encoding of query form (utf-8, ascii, iso8859-1, koi8-r)
<p>GRASS_GUI
<br> either "text" or "tcltk" to define non-/graphical startup.
Can also specify the name of the GUI to use, e.g. "gis.m", "d.m" or
"wxpython" (<i>wx name subject to change</i>). Can also exist as a GRASS
startup shell variable. The gisenv setting defines what GUI GRASS will use
the next time it starts.
<p>LOCATION
<br> full path to location directory
<p>LOCATION_NAME
<br> initial location name
<p>MAPSET
<br> initial mapset
<p>OVERWRITE
<br>[all modules]
<br> toggles map overwrite.
<br> With 0 maps are protected (default),
<br> With 1 maps with identical names will be overwritten.
<br> Example: <tt>g.gisenv set="OVERWRITE=0"</tt>
<br> You can force an overwrite for an individual command by adding "--o" to the command:
<br> <tt>r.in.gdal --o output=existing_map ...</tt>
<BR><BR><HR><BR>
<a name="files"></a>
<h2>GRASS-related Files</h2>
<p>$HOME/.grassrc6
<br> stores the GRASS variables (but not environment variables)
<p>$HOME/.grasslogin6
<br> stores the DBMI passwords in this hidden file
Only the file owner can access this file.
<p>$HOME/GIS_ERROR_LOG
<br> If this file exists then all GRASS error and warning messages are
logged here. Applies to current user. To generate the file, use:
<br> <tt>touch $HOME/GIS_ERROR_LOG</tt>
<p>$GISBASE/GIS_ERROR_LOG
<br> If this file exists then all GRASS error and warning messages are
logged here. Applies to all users. (proper write permissions must be in place)
<P>
<i>Note:</i>
Error and warning messages encountered while using the GUI menus are not logged.
<h3>SEE ALSO</h3>
<em>
<a href="g.gisenv.html">g.gisenv</a>,
<a href="g.parser.html">g.parser</a>
</em>
<p>
<i>Last changed: $Date: 2008-04-15 19:10:05 +0200 (Tue, 15 Apr 2008) $</i>
<HR>
<P><a href=index.html>Help Index</a></p>
</body></html>
