NAME

       g.gisenv  - Outputs and modifies the user's current GRASS variable settings.

KEYWORDS

       general, settings

SYNOPSIS

       g.gisenv
       g.gisenv help
       g.gisenv   [-sn]   [get=VARIABLE]    [set=VARIABLE=value]    [store=string]    [--verbose]
       [--quiet]

   Flags:
       -s
           Use shell syntax (for "eval")

       -n
           Don't use shell syntax

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       get=VARIABLE
           GRASS variable to get

       set=VARIABLE=value
           GRASS variable to set

       store=string
           Where GRASS variable is stored
           Options: gisrc,mapset
           Default: gisrc

DESCRIPTION

       When a user runs GRASS,  certain  variables  are  set  specifying  the  GRASS  data  base,
       location,  mapset,  peripheral  device  drivers,  etc.,  being  used  in the current GRASS
       session. These variable name settings are recognized as long as  the  user  is  running  a
       GRASS session.

OPTIONS

       No prompts are given to the user when running g.gisenv. If run without arguments, g.gisenv
       lists all of the user's current GRASS variable settings.  Results  are  sent  to  standard
       output, and may look like this:
       GISDBASE=/opt/grassdata/
       LOCATION_NAME=spearfish
       MAPSET=PERMANENT
        In this example, the full path name of the user's current location (i.e., $LOCATION_NAME)
       is /opt/grassdata/spearfish, and the full path name of the user's  current  mapset  (i.e.,
       $MAPSET) is /opt/grassdata/spearfish/PERMANENT.

       If  the  user  specifies a variable_name on the command line (e.g., g.gisenv MAPSET), only
       the value for that particular GRASS  variable  is  output  to  standard  output.  Possible
       variable names depend on the user's system, see variables list for details.

       While  other  variables  may  be  associated  with  each  GRASS  session (e.g., GRASS_GUI,
       GIS_LOCK, and other variables), those stated below are essential.

       GISDBASE
              The $GISDBASE is a directory in which all users' GRASS data are stored. Within  the
              $GISDBASE,  data  are  segregated into subdirectories (called "locations") based on
              the map coordinate system used  and  the  geographic  extent  of  the  data.   Each
              "location"   directory   itself  contains  subdirectories  called  "mapsets";  each
              "mapset" stores "data base elements" - the  directories  (e.g.,  the
              cell,  cellhd,  vector,  etc.,  directories) in which GRASS data files are actually
              stored.

       LOCATION_NAME
              The user must choose to work with the data under a single GRASS location within any
              given  GRASS  session; this location is then called the current GRASS location, and
              is specified by the variable $LOCATION_NAME. The $LOCATION_NAME is the  GRASS  data
              base  location  whose data will be affected by any GRASS commands issued during the
              user's current GRASS session, and is a subdirectory of the current $GISDBASE.  Each
              "location"  directory  can  contain  multiple  "mapset"  directories (including the
              special mapset PERMANENT).  Maps stored under the same GRASS $LOCATION_NAME (and/or
              within  the  same  MAPSET)  must  use the same coordinate system and typically fall
              within the boundaries of the same geographic region (aka, "location").

       MAPSET
              Each "mapset" contains a set of maps relevant to the  $LOCATION_NAME  directory  in
              which it appears.  Each $LOCATION_NAME can contain multiple mapsets. (Mapsets which
              fall under the same $LOCATION_NAME all contain data geographically relevant to  the
              $LOCATION_NAME,  and all store data in the same map coordinate system.  Frequently,
              maps are placed into different mapsets to distinguish file ownership -  e.g.,  each
              user  might  have  his  own mapset, storing any maps that he has created and/or are
              relevant to his work.) During each GRASS session, the user must choose  one  mapset
              to  be the current mapset; the current mapset setting is given by $MAPSET, and is a
              subdirectory of $LOCATION_NAME.  During a single GRASS session, the  user  can  use
              available  data  in  any  of  the  mapsets  stored under the current $LOCATION_NAME
              directory that are in the user's mapset search path and  accessible  by  the  user.
              However,  within  a  single  GRASS  session, the user only has write access to data
              stored under the current mapset (specified by the variable $MAPSET).

       Each "mapset" stores GRASS data base elements (i.e., the directories in which  GRASS  data
       files  are stored).  Any maps created or modified by the user in the current GRASS session
       will be stored here. The $MAPSET directory PERMANENT is generally reserved for the set  of
       maps that form the base set for all users working under each $LOCATION_NAME.

       Once within a GRASS session, GRASS users have access only to the data under a single GRASS
       data base directory (the current GRASS data base, specified by  the  variable  $GISDBASE),
       and  to a single GRASS location directory (the current location, specified by the variable
       $LOCATION_NAME).  Within a single session, the user  may  only  modify  the  data  in  the
       current mapset (specified by the variable $MAPSET), but may use data available under other
       mapsets under the same $LOCATION_NAME.

       All of these names must be legal names on the user's current system.

NOTES

       The output from g.gisenv when invoked without arguments is directly usable by  Bash.   The
       following command will cast each variable into the UNIX environment:
       eval `g.gisenv`
         This  works  only  for  Bash. The format of the output is not compatible with other UNIX
       shells.

   GRASS Debugging
       To print debugging messages, the variable DEBUG must be set to level equal or greater than
       0:
       g.gisenv set="DEBUG=3"
        Levels: (recommended levels)
       0  -  silence 1 - message is printed once or few times per module 3 - each row (raster) or
       line (vector) 5 - each cell (raster) or point (vector)
       To disable debugging messages, DEBUG must be set back to 0:
       g.gisenv set="DEBUG=0"

SEE ALSO

        g.access, g.filename, g.findfile, g.mapsets
        See also variables list

AUTHOR

       Michael Shapiro, U.S.Army Construction Engineering Research Laboratory

       Last changed: $Date: 2011-11-08 03:29:50 -0800 (Tue, 08 Nov 2011) $

       Full index

       © 2003-2013 GRASS Development Team