## GRASS variables and environment variables

There are two types of variables:

- environment variables,
- GRASS gisenv variables.

Any setting which needs to be modifiable by a GRASS program (e.g. MONITOR) has to be a GRASS variable.

## GRASS-related Files

GRASS maintains some settings in a number of files on the system. They are detailed below.

## Setting environment variables

Setting environment variables depends on the shell being used:
Bash: `export VARIABLE=value`
or
Csh: `setenv VARIABLE value`

## Setting environment variables permanently

- To get personal BASH shell definitions (aliases, color listing option, ...) into GRASS, store them in:
  `$HOME/.grass.bashrc`
- To get personal CSH shell definitions (aliases, color listing option, ...) into GRASS, store them in:
  `$HOME/.grass.cshrc`

## Setting GRASS variables

Use "g.gisenv" within GRASS. This permanently predefines GRASS variables in the `.grassrc6` file.

Usage:

    g.gisenv set="VARIABLE=VALUE"

It looks unusual with two equals signs, but g.gisenv serves dual duty for getting and setting GRASS variables.

If the user just specifies a variable name, it defaults to "get" mode. For example:

    GRASS ~> g.gisenv GRASS_GUI
    text

## List of selected (GRASS related) environment variables

> [ To be set from the terminal shell or startup scripts ]

GISBASE
directory where GRASS lives. This is set automatically by the startup script.

GISRC
name of .grassrc6 file. GISRCRC defines the system wide value while in a GRASS session.

GRASS_ADDON_PATH
[grass startup script]
allows to specify additional paths to local GRASS modules extra to standard distribution

GRASS_ERROR_MAIL
set to any value to send user mail on an error or warning that happens while stderr is being redirected.

GRASS_GNUPLOT
[i.spectral]
program to use for plotting "gnuplot" data

GRASS_HEIGHT
[d.mon]
defines the height of GRASS monitor, see also GRASS_WIDTH

GRASS_HTML_BROWSER
[init.sh, d.m]
defines name of HTML browser

GRASS_INT_ZLIB
[libgis]
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.
Obviously, decompression is controlled by the raster's "compressed" value, not the environment variable.

GRASS_MESSAGE_FORMAT
[various modules]
Maybe set to either "standard" or "gui" (normally GRASS takes care)

GRASS_MOUSE_BUTTON
[various modules]
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).

GRASS_PAGER
[various modules]
Maybe set to either "less" or "more"

GRASS_PERL
set perl with path

GRASS_TCLSH
[nviz]
set tclsh shell name to override 'tclsh'

GRASS_TERM
lib/init/grass-xterm-wrapper
set to any value (e.g. rxvt, aterm, gnome-terminal, konsole) to substitute 'x-terminal-emulator' or 'xterm'

GRASS_UI_TERM
set to any value to use the terminal based parser

GRASS_VERSION
reports the current version number (used by R-stats interface etc);
should not be changed by user

GRASS_WIDTH
[d.mon]
defines the width of GRASS monitor, see also GRASS_HEIGHT

GRASS_WISH
[d.m, nviz]
set wish shell name to override 'wish'

GRASS_GLX_PBUFFERS
[nviz]
set to any value to enable the use of OpenGL Pixel Buffers

GRASS_GLX_PIXMAPS
[nviz]
set to any value to enable the use of OpenGL Pixmaps

### List of selected GRASS PNG driver environment variables

> [ These variables control the function of the PNG Driver. ]

GRASS_PNGFILE
name of PNG output file

GRASS_WIDTH
defines the width of GRASS monitor, see also GRASS_HEIGHT

GRASS_HEIGHT
defines the height of GRASS monitor, see also GRASS_WIDTH

GRASS_BACKGROUNDCOLOR
defines the background color of the image created by the PNG driver

GRASS_TRANSPARENT
if "TRUE", the image created by the PNG driver will have a transparent background

GRASS_PNG_COMPRESSION
compression level of PNG files (0 = none, 1 = fastest, 9 = best)

GRASS_TRUECOLOR
if "TRUE", the PNG driver generates a true-color image

GRASS_PNG_AUTO_WRITE
tells the PNG driver to write the image to a file whenever a client disconnects, rather than waiting until you stop the monitor

GRASS_RENDER_IMMEDIATE
tells the raster library to use its built-in PNG 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`"

### List of selected internal GRASS environment variables

> [ These variables are intended for internal use only 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. ]

GRASS_OVERWRITE
[all modules]
toggles map overwrite.
With 0 maps are protected (default),
With 1 maps with identical names will be overwritten.
This variable is automatically created by g.parser so that "--o" 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.

GRASS_REGION
[libgis]
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.

WIND_OVERRIDE
[libgis]
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.
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.

## List of selected GRASS gisenv variables

> [ Use `g.gisenv` to get/set/unset/change them ]

DEBUG
[entire GRASS]
sets level of debug message output (0: no debug messages)
`g.gisenv set=DEBUG=0`

DM_FORM_MODE
[d.m]
sets default form mode (txt or gui)
`g.gisenv set=DM_FORM_MODE=txt`

GISDBASE
initial database

GIS_LOCK
lock ID to prevent parallel GRASS use,
process id of the start-up shell script

GRASS_DB_ENCODING
[d.what.vect/forms library]
encoding of query form (utf-8, ascii, iso8859-1, koi8-r)

GRASS_GUI
either "text" or "tcltk" to define non-/graphical startup

LOCATION
full path to location directory

LOCATION_NAME
initial location name

MAPSET
initial mapset

OVERWRITE
[all modules]
toggles map overwrite.
With 0 maps are protected (default),
With 1 maps with identical names will be overwritten.
Example: `g.gisenv set="OVERWRITE=0"`
You can force an overwrite for an individual command by adding "--o" to the command:
`r.in.gdal --o output=existing_map ...`

## GRASS-related Files

$HOME/.grassrc6
stores the GRASS variables (but not environment variables)

$HOME/GIS_ERROR_LOG
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`

$GISBASE/GIS_ERROR_LOG
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)

Note: Error and warning messages encountered while using the GUI menus are not logged.

### SEE ALSO

g.gisenv

Last changed: $Date: 2006/09/20 06:09:43 $

Help Index