variables.html 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2. <html>
  3. <head>
  4. <title>GRASS variables and environment variables</title>
  5. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  6. <link rel="stylesheet" href="grassdocs.css" type="text/css">
  7. </head>
  8. <body bgcolor="white">
  9. <!-- file source: lib/init/variables.html -->
  10. <img src="grass_logo.png" alt="_\|/_ GRASS logo"><hr align=center size=6 noshade>
  11. <!-- meta page description: GRASS variables and environment variables -->
  12. <h2>GRASS variables and environment variables</h2>
  13. There are two types of variables:
  14. <ul>
  15. <li><a href="#enviro">shell environment</a> variables,</li>
  16. <li><a href="#gisenv">GRASS gisenv</a> variables.</li>
  17. </ul>
  18. There are a number of <i>shell</i> environment variable groups:
  19. <ul>
  20. <li><a href="#rendering">variables for rendering</a></li>
  21. <li><a href="#internal">variables for internal use</a></li>
  22. </ul>
  23. <i>Note:</i> Any setting which needs to be modifiable by a GRASS module
  24. (e.g. MONITOR by <em><a href="d.mon.html">d.mon</a></em>) has to be a GRASS
  25. gisenv variable.
  26. <h2>Setting shell environment variables</h2>
  27. Setting shell environment variables depends on the shell being used:
  28. <br><br>
  29. Bash:
  30. <div class="code"><pre>
  31. export VARIABLE=value
  32. </pre></div>
  33. Csh:
  34. <div class="code"><pre>
  35. setenv VARIABLE value
  36. </pre></div>
  37. Cmd.exe (Windows):
  38. <div class="code"><pre>
  39. set VARIABLE=value
  40. </pre></div>
  41. To set up shell environment variables permanently:
  42. <ul>
  43. <li>
  44. To get personal BASH shell definitions (aliases, color listing option, ...)
  45. into GRASS, store them in:<br>
  46. <tt>$HOME/.grass.bashrc</tt></li>
  47. <li>
  48. To get personal CSH shell definitions (aliases, color listing option, ...)
  49. into GRASS, store them in:<br>
  50. <tt>$HOME/.grass.cshrc</tt></li>
  51. </ul>
  52. <h2>Setting GRASS gisenv variables</h2>
  53. Use <em><a href="g.gisenv.html">g.gisenv</a></em> within GRASS. This permanently
  54. predefines GRASS variables in the <tt>.grass7/rc</tt> file.
  55. <br><br>
  56. Usage:
  57. <div class="code"><pre>
  58. g.gisenv set="VARIABLE=VALUE"
  59. </pre></div>
  60. It looks unusual with two equals signs, but <em>g.gisenv</em> serves dual duty for
  61. getting and setting GRASS variables.
  62. <p>If the user just specifies a variable name, it defaults to <b>get</b> mode.
  63. For example:
  64. <div class="code"><pre>
  65. g.gisenv MAPSET
  66. PERMANENT
  67. </pre></div>
  68. <a name="enviro"></a>
  69. <h2>List of selected (GRASS related) shell environment variables</h2>
  70. <blockquote>
  71. [ To be set from the terminal shell or startup scripts ]
  72. </blockquote>
  73. <dl>
  74. <dt>GISBASE</dt>
  75. <dd>directory where GRASS lives. This is set automatically by the
  76. startup script.</dd>
  77. <dt>GISRC</dt>
  78. <dd>name of <tt>.grass7/rc</tt> file. Defines the system wide value
  79. while in a GRASS session.</dd>
  80. <dt>GRASS_ADDON_PATH</dt>
  81. <dd>[grass startup script]<br> allows to specify additional paths to
  82. local GRASS modules or user scripts extra to standard GRASS
  83. distribution.</dd>
  84. <dt>GRASS_ADDON_BASE</dt>
  85. <dd>[grass startup script]<br> allows to specify additional GISBASE
  86. for local GRASS modules (normally installed as GRASS Addons
  87. by <tt>g.extension</tt> module) extra to standard
  88. distribution. The default on GNU/Linux
  89. is <tt>$HOME/.grass7/addons</tt>, on MS
  90. Windows <tt>$APPDATA\GRASS7\addons</tt>.</dd>
  91. <dt>GRASS_ADDON_ETC</dt>
  92. <dd>[libgis, g.findetc]<br>
  93. specify paths where support files (etc/) may be found external to
  94. standard distribution.</dd>
  95. <dt>GRASS_BATCH_JOB</dt>
  96. <dd>defines the name (path) of a shell script to be processed as
  97. batch job.</dd>
  98. <dt>GIS_ERROR_LOG</dt>
  99. <dd>If set, GIS_ERROR_LOG should be the absolute path to the log
  100. file (a relative path will be interpreted relative to the process'
  101. cwd, not the cwd at the point the user set the variable). If not
  102. set, <tt>$HOME/GIS_ERROR_LOG</tt> is used instead. The file will
  103. only be used if it already exists.</dd>
  104. <dt>GRASS_ERROR_MAIL</dt>
  105. <dd>set to any value to send user mail on an error or warning that
  106. happens while stderr is being redirected.</dd>
  107. <dt>GRASS_FONT</dt>
  108. <dd>[display drivers]<br>
  109. specifies the font as either the name of a font from
  110. <tt>$GISBASE/etc/fontcap</tt> (or alternative fontcap file
  111. specified by GRASS_FONT_CAP), or alternatively the full path to a
  112. FreeType font file.</dd>
  113. <dt>GRASS_ENCODING</dt>
  114. <dd>[display drivers]<br>
  115. the encoding to be assumed for text which is drawn using a
  116. freetype font; may be any encoding know to <em>iconv</em>.</dd>
  117. <dt>GRASS_FONT_CAP</dt>
  118. <dd>[g.mkfontcap, d.font, display drivers]<br>
  119. specifies an alternative location (to <tt>$GISBASE/etc/fontcap</tt>) for
  120. the font configuration file.</dd>
  121. <dt>GRASS_GNUPLOT</dt>
  122. <dd>[<!-- m.svfit, s.probplt, s.sv -->i.spectral]<br>
  123. program to use for plotting <em>gnuplot</em> data.</dd>
  124. <dt>GRASS_GUI</dt>
  125. <dd>either <tt>text</tt> or <tt>gui</tt> to define non-/graphical startup.
  126. <br><br> Can also specify the name of the GUI to use,
  127. e.g. <tt>wxpython</tt>
  128. (<em><a href="wxGUI.html">wxGUI</a></em>). Also exists as a GRASS
  129. gisenv variable (see below). If this shell variable exists at
  130. GRASS startup, it will determine the GUI used. If it is not
  131. defined startup will default to the last GUI used.</dd>
  132. <dt>GRASS_HTML_BROWSER</dt>
  133. <dd>[init.sh, wxgui]<br> defines name of HTML browser. For most
  134. platforms this should be an executable in your PATH, or the full
  135. path to an executable.<br> Mac OS X runs applications differently
  136. from the CLI. Therefore, GRASS_HTML_BROWSER should be the
  137. application's signature, which is a domain-like name, just
  138. reversed, i.e. com.apple.Safari. To find an application's
  139. signature, type the following in a Terminal (fill in the path to
  140. the application you are interested in, for example:
  141. /Applications/Safari.app):<br> &nbsp; &nbsp; <code>grep -A 1
  142. &quot;CFBundleIdentifier&quot;</code> <i>/path/to/application.app</i><code>/Contents/Info.plist</code><br>
  143. &nbsp; The signature is the &lt;string&gt; following the
  144. &lt;key&gt;, without the bracketing &lt;string&gt; tags.</dd>
  145. <dt>GRASS_INT_ZLIB</dt>
  146. <dd>[libgis]<br> if the environment variable GRASS_INT_ZLIB exists,
  147. new compressed <i>integer</i> (CELL type) raster maps will be compressed
  148. using zlib instead of RLE compression. Such rasters will have a <tt>compressed</tt>
  149. value of 2 in the cellhd file.
  150. <br><br>
  151. Obviously, decompression is controlled by the
  152. raster's <tt>compressed</tt> value, not the environment variable.</dd>
  153. <dt>GRASS_MESSAGE_FORMAT</dt>
  154. <dd>[various modules, wxGUI]<br> maybe set to either
  155. <ul>
  156. <li><tt>standard</tt> - sets percentage output and message
  157. formatting style to standard formatting,</li>
  158. <li><tt>gui</tt> - sets percentage output and message formatting
  159. style to GUI formatting,</li>
  160. <li><tt>silent</tt> - disables percentage output and error
  161. messages,</li>
  162. <li><tt>plain</tt> - sets percentage output and message
  163. formatting style to ASCII output without rewinding control
  164. characters.</li>
  165. </ul></dd>
  166. <dt>GRASS_MOUSE_BUTTON</dt>
  167. <dd>[various modules]<br> swaps mouse buttons for two-button or
  168. left-handed mice. Its value has three digits 1, 2, and 3, which
  169. represent default left, middle, and right buttons
  170. respectively. Setting to <tt>132</tt> will swap middle and right
  171. buttons. Note that this variable should be set before a display
  172. driver is initialized (e.g.,
  173. <tt>d.mon x0</tt>).</dd>
  174. <dt>GRASS_PAGER</dt>
  175. <dd>[various modules]<br>
  176. maybe set to either <tt>less</tt> or <tt>more</tt>.</dd>
  177. <dt>GRASS_PERL</dt>
  178. <dd>[used during install process for generating man pages]<br>
  179. set Perl with path.</dd>
  180. <dt>GRASS_RND_SEED</dt>
  181. <dd>set random seed
  182. for <em><a href="r.mapcalc.html">r.mapcalc</a></em> rand()
  183. function.</dd>
  184. <!-- HB Sept 2005: I don't think this exists anymore:
  185. <p>GRASS_STDERR
  186. <br>&nbsp; set to any value to prevent user mail on error
  187. -->
  188. <dt>GRASS_SH</dt>
  189. <dd>[shell scripts on Windows]<br>
  190. path to bourne shell interpreter used to run shell scripts.</dd>
  191. <dt>GRASS_SIGSEGV_ON_ERROR</dt>
  192. <dd>Raise SIGSEGV if an error occures]<br>
  193. This variable can be set for debugging purpose. The call
  194. of G_fatal_error() will end in a segmentation violation. GDB can be used
  195. to trace the source of the error.</dd>
  196. <dt>GRASS_PYTHON</dt>
  197. <dd>[wxGUI, Python Ctypes]<br>
  198. set to override Python executable.<br>
  199. On Mac OS X this should be the pythonw executable for the wxGUI to work.</dd>
  200. <dt>GRASS_VECTOR_LOWMEM</dt>
  201. <dd>[vectorlib]<br>
  202. If the environment variable GRASS_VECTOR_LOWMEM exists, memory
  203. consumption will be reduced when building vector topology
  204. support structures. Recommended for creating large vectors.</dd>
  205. <dt>GRASS_WXBUNDLED</dt>
  206. <dd>[wxGUI]<br>
  207. set to tell wxGUI that a bundled wxPython will be used.<br>
  208. When set, the wxGUI will not check the wxPython version, as this
  209. function is incompatible with a bundled wxPython. It is up to the
  210. packager to make sure that a compatible wxPython version is bundled.</dd>
  211. <dt>GRASS_XTERM</dt>
  212. <dd>[lib/init/grass-xterm-wrapper, lib/init/grass-xterm-mac]<br>
  213. set to any value (e.g. rxvt, aterm, gnome-terminal, konsole) to
  214. substitute 'x-terminal-emulator' or 'xterm'. The Mac OS X app
  215. startup defaults to an internal '$GISBASE/etc/grass-xterm-mac',
  216. which emulates the necessary xterm functionality in
  217. Terminal.app.</dd>
  218. <dt>GRASS_UI_TERM</dt>
  219. <dd>set to any value to use the terminal based parser.</dd>
  220. <dt>GRASS_VERSION</dt>
  221. <dd>reports the current version number (used by R-stats interface etc);
  222. should not be changed by user.</dd>
  223. <dt>GRASS_NO_GLX_PBUFFERS</dt>
  224. <dd>[nviz]<br>
  225. set to any value to disable the use of GLX Pbuffers.</dd>
  226. <dt>GRASS_NO_GLX_PIXMAPS</dt>
  227. <dd>[nviz]<br>
  228. Set to any value to disable the use of GLX Pixmaps.</dd>
  229. <dt>OMP_NUM_THREADS</dt>
  230. <dd>[OpenMP]<br>
  231. If OpenMP support is enabled this limits the number of threads.
  232. The default is set to the number of CPUs on the system.
  233. Setting to '1' effectively disables parallel processing.</dd>
  234. </dl>
  235. <a name="rendering"></a>
  236. <h3>List of selected GRASS environment variables for rendering</h3>
  237. <blockquote>
  238. [ In addition to those which are understood by specific <em>GRASS display
  239. drivers</em>, the following variables affect rendering. ]
  240. </blockquote>
  241. <dl>
  242. <dt>GRASS_RENDER_IMMEDIATE</dt>
  243. <dd>tells the display library which driver to use; possible
  244. values: <em><a href="cairodriver.html">cairo</a></em>, <em><a href="pngdriver.html">png</a></em>, <em><a href="psdriver.html">ps</a></em>
  245. or <em><a href="htmldriver.html">html</a></em></dd>
  246. <dt>GRASS_WIDTH</dt>
  247. <dd>defines the width of output image (default is 640).</dd>
  248. <dt>GRASS_HEIGHT</dt>
  249. <dd>defines the height of output image (default is 480).</dd>
  250. <dt>GRASS_FRAME</dt>
  251. <dd>contains 4 coordinates, <em>top,bottom,left,right</em>, defining the initial frame.</dd>
  252. <dt>GRASS_LINE_WIDTH</dt>
  253. <dd>defines default line width.</dd>
  254. <dt>GRASS_TEXT_SIZE</dt>
  255. <dd>defines default text size.</dd>
  256. </dl>
  257. For specific driver-related variables see:
  258. <ul>
  259. <li><em><a href="cairodriver.html">Cairo driver</a></em></li>
  260. <li><em><a href="pngdriver.html">PNG driver</a></em></li>
  261. <li><em><a href="psdriver.html">PS (Postscript) driver</a></em></li>
  262. <li><em><a href="htmldriver.html">HTML driver</a></em></li>
  263. </ul>
  264. <a name="internal"></a>
  265. <h3>List of selected internal GRASS environment variables</h3>
  266. <blockquote>
  267. [ These variables are intended <b>for internal use only</b> by the GRASS
  268. software to facilitate communication between the GIS engine, GRASS scripts,
  269. and the GUI.
  270. The user should not set these in a GRASS session. They are meant to be set
  271. locally for specific commands. ]
  272. </blockquote>
  273. <dl>
  274. <dt>GRASS_OVERWRITE</dt>
  275. <dd>[all modules]<br>
  276. toggles map overwrite.
  277. <ul>
  278. <li>0 - maps are protected (default),</li>
  279. <li>1 - maps with identical names will be overwritten.</li>
  280. </ul>
  281. This variable is automatically created
  282. by <em><a href="g.parser.html">g.parser</a></em> so that the
  283. <tt>--overwrite</tt> option will
  284. be inherited by dependent modules as the script runs. Setting either the
  285. GRASS_OVERWRITE environment variable or the OVERWRITE gisenv variable detailed
  286. below will cause maps with identical names to be overwritten.</dd>
  287. <dt>GRASS_VERBOSE</dt>
  288. <dd>[all modules]<br>
  289. toggles verbosity level
  290. <ul>
  291. <li>0 - only errors and warnings are printed</li>
  292. <li>1 - progress messages are printed (percent complete)</li>
  293. <li>2 - all module messages are printed</li>
  294. <li>3 - additional verbose messages are printed</li>
  295. </ul>
  296. This variable is automatically created by <em><a href="g.parser.html">g.parser</a></em>
  297. so that the <tt>--verbose</tt> or <tt>--quiet</tt> flags will be inherited
  298. by dependent modules as the script runs.</dd>
  299. <dt>GRASS_REGION</dt>
  300. <dd>[libgis]<br>
  301. override region settings, separate parameters with a ";". Format
  302. is the same as in the WIND region settings file. Otherwise use is the same as
  303. WIND_OVERRIDE.</dd>
  304. <dt>WIND_OVERRIDE</dt>
  305. <dd>[libgis]<br>
  306. it causes programs to use the specified named region (created with
  307. e.g. <tt>g.region save=...</tt>) to be used as the current region, instead of
  308. the region from the WIND file.<br><br>
  309. This allows programs such as the GUI to run external commands on an
  310. alternate region without having to modify the WIND file then change it
  311. back afterwards.</dd>
  312. </dl>
  313. <a name="gisenv"></a>
  314. <h2>List of selected GRASS gisenv variables</h2>
  315. <blockquote>
  316. [ Use <em><a href="g.gisenv.html">g.gisenv</a></em> to get/set/unset/change them ]
  317. </blockquote>
  318. <dl>
  319. <dt>DEBUG</dt>
  320. <dd>[entire GRASS]<br>
  321. sets level of debug message output (0: no debug messages)
  322. <div class="code"><pre>
  323. g.gisenv set=DEBUG=0
  324. </pre></div>
  325. <dt>WX_DEBUG</dt>
  326. <dd>[wxGUI]<br>
  327. sets level of debug message output for <em><a href="wxGUI.html">wxGUI</a></em> (0: no debug messages, 1-5 debug levels)
  328. <dt>GISDBASE</dt>
  329. <dd>initial database</dd>
  330. <dt>GIS_LOCK</dt>
  331. <dd>lock ID to prevent parallel GRASS use,
  332. <br>process id of the start-up shell script</dd>
  333. <dt>GRASS_DB_ENCODING</dt>
  334. <dd>[d.what.vect/forms library]<br>
  335. encoding of query form (utf-8, ascii, iso8859-1, koi8-r)</dd>
  336. <dt>GUI</dt>
  337. <dd>either <tt>text</tt> or <tt>gui</tt> to define non-/graphical startup.
  338. <br><br> Can also specify the name of the GUI to use,
  339. e.g. <tt>wxpython</tt>
  340. (<em><a href="wxGUI.html">wxGUI</a></em>). Also exists as a shell
  341. environment variable. If this shell variable exists at GRASS
  342. startup, it will determine the GUI used. If it is not defined
  343. startup will default to the last GUI used.</dd>
  344. <dt>LOCATION</dt>
  345. <dd>full path to location directory</dd>
  346. <dt>LOCATION_NAME</dt>
  347. <dd>initial location name</dd>
  348. <dt>MAPSET</dt>
  349. <dd>initial mapset</dd>
  350. <dt>OVERWRITE</dt>
  351. <dd>[all modules]<br>
  352. toggles map overwrite.
  353. <ul>
  354. <li>0 - maps are protected (default),</li>
  355. <li>1 - maps with identical names will be overwritten.</li>
  356. </ul>
  357. This variable is automatically created
  358. by <em><a href="g.parser.html">g.parser</a></em> so that the
  359. <tt>--overwrite</tt> option will
  360. be inherited by dependent modules as the script runs. Setting either the
  361. GRASS_OVERWRITE environment variable or the OVERWRITE gisenv variable detailed
  362. below will cause maps with identical names to be overwritten.</dd>
  363. </dl>
  364. <h2>GRASS-related Files</h2>
  365. <dl>
  366. <dt><tt>$HOME/.grass7/rc</tt></dt>
  367. <dd>stores the GRASS gisenv variables (not shell environment variables)</dd>
  368. <dt><tt>$HOME/.grass7/login</tt></dt>
  369. <dd>stores the DBMI passwords in this hidden file.
  370. Only the file owner can access this file.</dd>
  371. <dt><tt>$HOME/GIS_ERROR_LOG</tt></dt>
  372. <dd>if this file exists then all GRASS error and warning messages are
  373. logged here. Applies to current user. To generate the file, use:
  374. <tt>touch $HOME/GIS_ERROR_LOG</tt><br>
  375. See also GIS_ERROR_LOG variable.</dd>
  376. </dl>
  377. <h2>SEE ALSO</h2>
  378. <em>
  379. <a href="g.gisenv.html">g.gisenv</a>,
  380. <a href="g.parser.html">g.parser</a>
  381. </em>
  382. <p><i>Last changed: $Date$</i>
  383. <hr>
  384. <p><a href=index.html>Help Index</a>
  385. <p>&copy; 2008-2011 <a href="http://grass.osgeo.org">GRASS Development Team</a>
  386. </body>
  387. </html>