OILS / doc / ref / chap-special-var.md View on Github | oilshell.org

336 lines, 182 significant
1---
2title: Special Variables (Oils Reference)
3all_docs_url: ..
4body_css_class: width40
5default_highlighter: oils-sh
6preserve_anchor_case: yes
7---
8
9<div class="doc-ref-header">
10
11[Oils Reference](index.html) &mdash;
12Chapter **Special Variables**
13
14</div>
15
16This chapter describes special variables for OSH and YSH.
17
18<span class="in-progress">(in progress)</span>
19
20<div id="dense-toc">
21</div>
22
23## YSH Vars
24
25### ARGV
26
27Replacement for `"$@"`
28
29### ENV
30
31TODO
32
33### _this_dir
34
35The directory the current script resides in. This knows about 3 situations:
36
37- The location of `oshrc` in an interactive shell
38- The location of the main script, e.g. in `osh myscript.sh`
39- The location of script loaded with the `source` builtin
40
41It's useful for "relative imports".
42
43## YSH Status
44
45### `_status`
46
47DEPRECATED: Use `_error.code` instead.
48
49### `_error`
50
51A `Dict` that's set by the `try` builtin.
52
53The integer `_error.code` is always present:
54
55 try {
56 ls /tmp
57 }
58 echo "status is $[_error.code]"
59
60Some errors also have a `message` field, like JSON/J8 encoding/decoding errors,
61and user errors from the [error][] builtin.
62
63 try {
64 echo $[toJson( /d+/ )] # invalid Eggex type
65 }
66 echo "failed: $[_error.message]" # => failed: Can't serialize ...
67
68[error]: chap-builtin-cmd.html#error
69
70
71### `_pipeline_status`
72
73After a pipeline of processes is executed, this array contains the exit code of
74each process.
75
76Each exit code is an [Int](chap-type-method.html#Int). Compare with
77[`PIPESTATUS`](#PIPESTATUS).
78
79### `_process_sub_status`
80
81The exit status of all the process subs in the last command.
82
83## YSH Tracing
84
85### SHX_indent
86
87### SHX_punct
88
89### SHX_pid_str
90
91## YSH Read
92
93### _reply
94
95YSH `read` sets this variable:
96
97 read --all < myfile
98 echo $_reply
99
100## Oils VM
101
102### `OILS_VERSION`
103
104The version of Oils that's being run, e.g. `0.23.0`.
105
106<!-- TODO: specify comparison algorithm. -->
107
108### `LIB_OSH`
109
110The string `///osh`, which you can use with the [source][] builtin.
111
112 source $LIB_OSH/two.sh
113
114[source]: chap-builtin-cmd.html#source
115
116### `LIB_YSH`
117
118The string `///ysh`, which you can use with the [source][] builtin.
119
120 source $LIB_YSH/yblocks.ysh
121
122[source]: chap-builtin-cmd.html#source
123
124### `OILS_GC_THRESHOLD`
125
126At a GC point, if there are more than this number of live objects, collect
127garbage.
128
129### `OILS_GC_ON_EXIT`
130
131Set `OILS_GC_ON_EXIT=1` to explicitly collect and `free()` before the process
132exits. By default, we let the OS clean up.
133
134Useful for ASAN testing.
135
136### `OILS_GC_STATS`
137
138When the shell process exists, print GC stats to stderr.
139
140### `OILS_GC_STATS_FD`
141
142When the shell process exists, print GC stats to this file descriptor.
143
144## Float
145
146### NAN
147
148The float value for "not a number".
149
150(The name is consistent with the C language.)
151
152### INFINITY
153
154The float value for "infinity". You can negate it to get "negative infinity".
155
156(The name is consistent with the C language.)
157
158## Shell Vars
159
160### IFS
161
162Used for word splitting. And the builtin `shSplit()` function.
163
164### LANG
165
166TODO: bash compat
167
168### GLOBIGNORE
169
170TODO: bash compat
171
172## Shell Options
173
174### SHELLOPTS
175
176bash compat: serialized options for the `set` builtin.
177
178### BASHOPTS
179
180bash compat: serialized options for the `shopt` builtin.
181
182## Other Env
183
184### HOME
185
186$HOME is used for:
187
1881. ~ expansion
1892. ~ abbreviation in the UI (the dirs builtin, \W in $PS1).
190
191Note: The shell doesn't set $HOME. According to POSIX, the program that
192invokes the login shell sets it based on /etc/passwd.
193
194### PATH
195
196A colon-separated string that's used to find executables to run.
197
198
199## POSIX Special
200
201## Other Special
202
203### BASH_REMATCH
204
205Result of regex evaluation `[[ $x =~ $pat ]]`.
206
207### PIPESTATUS
208
209After a pipeline of processes is executed, this array contains the exit code of
210each process.
211
212Each exit code is a [Str](chap-type-method.html#Str). Compare with
213[`_pipeline_status`](#_pipeline_status).
214
215## Platform
216
217### HOSTNAME
218
219The name of the "host" or machine that Oils is running on, determined by
220`gethostname()`.
221
222### OSTYPE
223
224The operating system that Oils is running on, determined by `uname()`.
225
226Examples: `linux darwin ...`
227
228## Call Stack
229
230### BASH_SOURCE
231
232### FUNCNAME
233
234### BASH_LINENO
235
236## Tracing
237
238### LINENO
239
240## Process State
241
242### BASHPID
243
244TODO
245
246### PPID
247
248TODO
249
250### UID
251
252### EUID
253
254## Process Stack
255
256## Shell State
257
258## Completion
259
260### COMP_WORDS
261
262An array of words, split by : and = for compatibility with bash. New
263completion scripts should use COMP_ARGV instead.
264
265### COMP_CWORD
266
267Discouraged; for compatibility with bash.
268
269### COMP_LINE
270
271Discouraged; for compatibility with bash.
272
273### COMP_POINT
274
275Discouraged; for compatibility with bash.
276
277### COMP_WORDBREAKS
278
279Discouraged; for compatibility with bash.
280
281### COMPREPLY
282
283User-defined completion functions should Fill this array with candidates. It
284is cleared on every completion request.
285
286### COMP_ARGV
287
288An array of partial command arguments to complete. Preferred over COMP_WORDS.
289The compadjust builtin uses this variable.
290
291(An OSH extension to bash.)
292
293## History
294
295### HISTFILE
296
297Override the default OSH history location.
298
299### YSH_HISTFILE
300
301Override the default YSH history location.
302
303## cd
304
305### PWD
306
307### OLDPWD
308
309### CDPATH
310
311## getopts
312
313### OPTIND
314
315### OPTARG
316
317### OPTERR
318
319## read
320
321### REPLY
322
323OSH read sets this:
324
325 read < myfile
326
327## Functions
328
329### RANDOM
330
331bash compat
332
333### SECONDS
334
335bash compat
336