variables.html 17 KB

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