.TH variables 1grass "" "GRASS 6.4.4" "Grass User's Manual"
.SH NAME
variables \- GRASS variables and environment variables 

GRASS variables and environment variables 
.SH GRASS variables and environment variables
There are two types of variables:
.RS
.IP
shell environment variables,
.IP
GRASS gisenv variables.
.RE
There are a number of \fIshell\fR environment variable groups:
.RS
.IP
PNG driver
.IP
PS driver (PostScript)
.IP
HTMLMAP driver
.IP
variables for direct rendering
.IP
variables for internal use
.RE
Any setting which needs to be modifiable by a GRASS program (e.g. MONITOR)
has to be a GRASS \fIgisenv\fR variable.
.SH GRASS-related Files
GRASS maintains some settings in a number of files on the system. They are
detailed below.
.SH Setting environment variables
Setting environment variables depends on the shell being used:
.br
Bash:
\fC
.DS
.br
export VARIABLE=value
.br
.DE
\fR
Csh:
\fC
.DS
.br
setenv VARIABLE value
.br
.DE
\fR
Cmd.exe (Windows):
\fC
.DS
.br
set VARIABLE=value
.br
.DE
\fR
.SH Setting environment variables permanently
.RS
.IP
To get personal BASH shell definitions (aliases, color listing option, ...)
into GRASS, store them in:
.br
$HOME/.grass.bashrc
.IP
To get personal CSH shell definitions (aliases, color listing option, ...)
into GRASS, store them in:
.br
$HOME/.grass.cshrc
.RE
.SH Setting GRASS gisenv variables
Use \fIg.gisenv\fR within GRASS. This permanently
predefines GRASS variables in the .grassrc6 file.
.br
Usage:
\fC
.DS
.br
g.gisenv set="VARIABLE=VALUE"
.br
.DE
\fR
It looks unusual with two equals signs, but \fIg.gisenv\fR serves dual duty for
getting and setting GRASS variables.
.PP
If the user just specifies a variable name, it defaults to \fBget\fR mode.
For example:
\fC
.DS
.br
g.gisenv GRASS_GUI
.br
text
.br
.DE
\fR
.SH List of selected (GRASS related) environment variables
[ To be set from the terminal shell or startup scripts ]
.IP "GISBASE" 4m
.br
directory where GRASS lives. This is set automatically by the
startup script.
.IP "GISRC" 4m
.br
name of .grassrc6 file. Defines the system wide value
while in a GRASS session.
.IP "GRASS_ADDON_PATH" 4m
.br
[grass startup script, g.extension]
.br
specifies additional path(s) containing local and/or custom GRASS
modules extra to the standard distribution.
.IP "GRASS_ADDON_ETC" 4m
.br
[libgis, g.findetc]
.br
specify paths where support files (etc/) may be found external to
standard distribution.
.IP "GRASS_BATCH_JOB" 4m
.br
defines the name (path) of a shell script to be processed as
batch job.
.IP "GIS_ERROR_LOG" 4m
.br
If set, GIS_ERROR_LOG should be the absolute path to the log
file (a relative path will be interpreted relative to the process'
cwd, not the cwd at the point the user set the variable). If not
set, $HOME/GIS_ERROR_LOG is used instead. The file will
only be used if it already exists.
.IP "GRASS_ERROR_MAIL" 4m
.br
set to any value to send user mail on an error or warning that 
happens while stderr is being redirected.
.IP "GRASS_GNUPLOT" 4m
.br
[i.spectral]
.br
program to use for plotting \fIgnuplot\fR data.
.IP "GRASS_GUI" 4m
.br
either text or gui to define non-/graphical startup.
.br
Can also specify the name of the GUI to use, e.g. tcltk
(\fIgis.m\fR), oldtcltk
(\fId.m\fR) or wxpython
(\fIwxGUI\fR). 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.
.IP "GRASS_FONT_CAP" 4m
.br
[g.mkfontcap, d.font, display drivers]
.br
specifies an alternative location (to $GISBASE/etc/fontcap) for 
the font configuration file.
.IP "GRASS_HEIGHT" 4m
.br
[d.mon]
.br
defines the height of GRASS monitor, see also GRASS_WIDTH.
.IP "GRASS_HTML_BROWSER" 4m
.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, i.e. 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
     \fIgrep -A 1
\(dqCFBundleIdentifier"\fR \fI/path/to/application.app\fR\fI/Contents/Info.plist\fR
.br
The signature is the  following the ,
without the bracketing  tags.
.IP "G_INFO_FORMAT_STANDARD" 4m
.br
[init.sh, wxgui]
.br
sets percentage output and message formatting style to standard formatting.
.IP "G_INFO_FORMAT_GUI" 4m
.br
[init.sh, wxgui]
.br
sets percentage output and message formatting style to GUI formatting.
.IP "G_INFO_FORMAT_SILENT" 4m
.br
[init.sh, wxgui]
.br
disables percentage output and error messages.
.IP "G_INFO_FORMAT_PLAIN" 4m
.br
[init.sh, wxgui]
.br
sets percentage output and message formatting style to ASCII output without rewinding control characters.
.IP "GRASS_INT_ZLIB" 4m
.br
[libgis]
.br
if the environment variable GRASS_INT_ZLIB exists, new compressed \fIinteger\fR (CELL type)
raster maps 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.
.IP "GRASS_MESSAGE_FORMAT" 4m
.br
[various modules, wxGUI]
.br
it may be set to either
.RS
.IP
standard - sets percentage output and message
formatting style to standard formatting,
.IP
gui - sets percentage output and message formatting
style to GUI formatting,
.IP
silent - disables percentage output and error
messages,
.IP
plain - sets percentage output and message
formatting style to ASCII output without rewinding control
characters.
.RE
.IP "GRASS_MOUSE_BUTTON" 4m
.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).
.IP "GRASS_PAGER" 4m
.br
[various modules]
.br
it may be set to either less, more, or cat.
.IP "GRASS_PERL" 4m
.br
[used during install process for generating man pages]
.br
set Perl with path.
.IP "GRASS_RND_SEED" 4m
.br
set random seed
for \fIr.mapcalc\fR rand()
function.
.IP "GRASS_SKIP_MAPSET_OWNER_CHECK" 4m
.br
By default it is not possible to work with MAPSETs that are
not owned by current user. Setting this variable to any non-empty value
allows the check to be skipped.
.IP "GRASS_SH" 4m
.br
[shell scripts on Windows]
.br
path to bourne shell interpreter used to run shell scripts.
.IP "GRASS_PYTHON" 4m
.br
[wxGUI, Python scripting]
.br
set to override Python executable.
.br
On Mac OS X this should be the pythonw executable for the
wxGUI to work.
.IP "GRASS_WXBUNDLED" 4m
.br
[wxGUI]
.br
set to tell wxGUI that a bundled wxPython will be used.
.br
When set, the wxGUI will not check the wxPython version, as this
function is incompatible with a bundled wxPython.  It is up to the
packager to make sure that a compatible wxPython version is bundled.
.IP "GRASS_TCLSH" 4m
.br
[nviz]
.br
set tclsh shell name to override 'tclsh'.
.IP "GRASS_XTERM" 4m
.br
[lib/init/grass-xterm-wrapper, 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.
.IP "GRASS_UI_TERM" 4m
.br
set to any value to use the terminal based parser.
.IP "GRASS_VERSION" 4m
.br
reports the current version number (used by R-stats interface etc);
should not be changed by user.
.IP "GRASS_WIDTH" 4m
.br
[d.mon]
.br
defines the width of GRASS monitor, see also GRASS_HEIGHT.
.IP "GRASS_WISH" 4m
.br
[d.m, nviz]
.br
set wish shell name to override 'wish'.
.IP "GRASS_NO_GLX_PBUFFERS" 4m
.br
[nviz]
.br
set to any value to disable the use of GLX Pbuffers.
.IP "GRASS_NO_GLX_PIXMAPS" 4m
.br
[nviz]
.br
Set to any value to disable the use of GLX Pixmaps.
.IP "TMPDIR, TEMP, TMP" 4m
.br
[Various GRASS GIS commands and wxGUI]
.br
The default wxGUI temporary directory is chosen from a 
platform-dependent list, but the user can control the selection of
this directory by setting one of the TMPDIR, TEMP or TMP
environment variables Hence the wxGUI uses $TMPDIR if it is set,
then $TEMP, otherwise /tmp.
.PP
.SS List of selected GRASS PNG driver environment variables
[ These variables control the function of the PNG driver ]
See PNG driver manual page for detailed
list of the variables.
.SS List of selected GRASS PS driver environment variables
[ These variables control the function of the PS driver ]
See PS driver manual page for detailed
list of the variables.
.SS List of selected HTMLMAP driver environment variables
[ These variables control the function of the HTMLMAP driver ]
See HTMLMAP driver manual page for
detailed list of the variables.
.SS List of selected GRASS environment variables for direct rendering
[ In addition to those which are understood by the
PNG driver, the following variables
affect direct rendering. ]
.IP "GRASS_RENDER_IMMEDIATE" 4m
.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 
d.mon start=PNG.
.IP "GRASS_FONT" 4m
.br
specifies the font as either the name of a font from
$GISBASE/etc/fontcap (or alternative fontcap file specified by GRASS_FONT_CAP),
or alternatively the full path to a FreeType font file.
.IP "GRASS_ENCODING" 4m
.br
the encoding to be assumed for text which is drawn using a
freetype font; may be any encoding know to \fIiconv\fR.
.PP
.SS List of selected internal GRASS environment variables
[ These variables are intended \fBfor internal use only\fR by the GRASS
software to facilitate communication 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. ]
.IP "GRASS_OVERWRITE" 4m
.br
[all modules]
.br
toggles map overwrite.
.RS
.IP
0 - maps are protected (default),
.IP
1 - maps with identical names will be overwritten.
.RE
This variable is automatically created
by \fIg.parser\fR so that the
--overwrite option will
be inherited by dependent 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.
.IP "GRASS_VERBOSE" 4m
.br
[all modules]
.br
toggles verbosity level
.RS
.IP
0 - only errors and warnings are printed
.IP
1 - progress messages are printed (percent complete)
.IP
2 - all module messages are printed
.IP
3 - additional verbose messages are printed
.RE
This variable is automatically created by \fIg.parser\fR
so that the \-\-verbose or \-\-quiet flags will be inherited
by dependent modules as the script runs.
.IP "GRASS_REGION" 4m
.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.
.IP "WIND_OVERRIDE" 4m
.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.
.PP
.SH List of selected GRASS gisenv variables
[ Use \fIg.gisenv\fR to get/set/unset/change them ]
.IP "DEBUG" 4m
.br
[entire GRASS]
.br
sets level of debug message output (0: no debug messages)
\fC
.DS
.br
g.gisenv set=DEBUG=0
.br
.DE
\fR
.IP "WX_DEBUG" 4m
.br
[wxGUI]
.br
sets level of debug message output for \fIwxGUI\fR (0: no debug messages, 1-5 debug levels)
.IP "DM_FORM_MODE" 4m
.br
[d.m]
.br
sets default form mode (txt or gui)
.IP "GISDBASE" 4m
.br
initial database
.IP "GIS_LOCK" 4m
.br
lock ID to prevent parallel GRASS use,
.br
process id of the start-up shell script
.IP "GRASS_DB_ENCODING" 4m
.br
[d.what.vect/forms library]
.br
encoding of query form (utf-8, ascii, iso8859-1, koi8-r)
.IP "GRASS_GUI" 4m
.br
either text or gui to define non-/graphical startup.
.br
 Can also specify the name of the GUI to use,
e.g. tcltk
(\fIgis.m\fR), oldtcltk
(\fId.m\fR) or wxpython
(\fIwxGUI\fR). Also exists as a shell
environment variable. 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.
.IP "LOCATION" 4m
.br
full path to location directory
.IP "LOCATION_NAME" 4m
.br
initial location name
.IP "MAPSET" 4m
.br
initial mapset
.IP "OVERWRITE" 4m
.br
[all modules]
.br
toggles map overwrite.
.RS
.IP
0 - maps are protected (default),
.IP
1 - maps with identical names will be overwritten.
.RE
This variable is automatically created
by \fIg.parser\fR so that the
--overwrite option will
be inherited by dependent 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.
.PP
.SH GRASS-related Files
.IP "$HOME/.grassrc6" 4m
.br
stores the GRASS gisenv variables (but not environment variables)
.IP "$HOME/.grasslogin6" 4m
.br
stores the DBMI passwords in this hidden file.
Only the file owner can access this file.
.IP "$HOME/GIS_ERROR_LOG" 4m
.br
if this file exists then all GRASS error and warning messages are 
logged here. Applies to current user. To generate the file, use:
touch $HOME/GIS_ERROR_LOG
.br
See also GIS_ERROR_LOG variable.
.PP
.SH SEE ALSO
\fI
Display drivers
g.gisenv,
g.parser
\fR
.PP
\fILast changed: $Date: 2014-04-30 15:58:17 +0200 (Wed, 30 Apr 2014) $\fR
.PP
Help Index
.PP
© 2008-2012 GRASS Development Team