# Built-in Variables

Most Octave variables are available for you to use for your own purposes; they never change except when your program assigns values to them, and never affect anything except when your program examines them.

A few variables have special built-in meanings. Some of them, like `pi` and `eps` provide useful predefined constant values. Others, like `do_fortran_indexing` and `page_screen_output` are examined automatically by Octave, so that you can to tell Octave how to do certain things. There are also two special variables, `ans` and `PWD`, that are set automatically by Octave and carry information from the internal workings of Octave to your program.

This chapter documents all the built-in variables of Octave. Most of them are also documented in the chapters that describe functions that use them, or are affected by their values.

## Predefined Constants

`I, i, J, j`
A pure imaginary number, defined as The `I` and `J` forms are true constants, and cannot be modified. The `i` and `j` forms are like ordinary variables, and may be used for other purposes. However, unlike other variables, they once again assume their special predefined values if they are cleared See section Miscellaneous Utilities.
`Inf, inf`
Infinity. This is the result of an operation like 1/0, or an operation that results in a floating point overflow.
`NaN, nan`
Not a number. This is the result of an operation like `0/0', or `Inf - Inf', or any operation with a NaN.
`SEEK_SET`
`SEEK_CUR`
`SEEK_END`
These variables may be used as the optional third argument for the function `fseek`.
`eps`
The machine precision. More precisely, `eps` is the smallest value such that `1+eps' is not equal to 1. This number is system-dependent. On machines that support 64 bit IEEE floating point arithmetic, `eps` is approximately
`pi`
The ratio of the circumference of a circle to its diameter. Internally, `pi` is computed as `4.0 * atan (1.0)'.
`realmax`
The largest floating point number that is representable. The actual value is system-dependent. On machines that support 64 bit IEEE floating point arithmetic, `realmax` is approximately
`realmin`
The smallest floating point number that is representable. The actual value is system-dependent. On machines that support 64 bit IEEE floating point arithmetic, `realmin` is approximately
`stdin`
`stdout`
`stderr`
These variables are the file numbers corresponding to the standard input, standard output, and standard error streams. These streams are preconnected and available when Octave starts.

## User Preferences

This section describes the variables that you can use to customize Octave's behavior.

Normally, preferences are set in the file `~/.octaverc', so that you can customize your environment in the same way each time you use Octave without having to remember and retype all the necessary commands. See section Startup Files for more information.

`EDITOR`
A string naming the editor to use with the `edit_history` command. If the environment variable `EDITOR` is set when Octave starts, its value is used as the default. Otherwise, `EDITOR` is set to `"vi"`.
`IMAGEPATH`
A colon separated list of directories in which to search for image files. See section Image Processing for a description of Octave's image processing capabilities.
`INFO_FILE`
A string naming the location of the Octave info file. The default value is `"/usr/local/info/octave.info"`.
`LOADPATH`
A colon separated list of directories in which to search for function files. See section Functions and Script Files. The value of `LOADPATH` overrides the environment variable `OCTAVE_PATH`. See section Installing Octave. `LOADPATH` is now handled in the same way as TeX handles `TEXINPUTS`. If the path starts with `:', the standard path is prepended to the value of `LOADPATH`. If it ends with `:' the standard path is appended to the value of `LOADPATH`. In addition, if any path element ends in `//', that directory and all subdirectories it contains are searched recursively for function files. This can result in a slight delay as Octave caches the lists of files found in the `LOADPATH` the first time Octave searches for a function. After that, searching is usually much faster because Octave normally only needs to search its internal cache for files. To improve performance of recursive directory searching, it is best for each directory that is to be searched recursively to contain either additional subdirectories or function files, but not a mixture of both. See section Organization of Functions Distributed with Octave for a description of the function file directories that are distributed with Octave.
`OCTAVE_VERSION`
The version number of Octave, as a string.
`PAGER`
The default value is `"less"`, or, if `less` is not available on your system, `"more"`. See section Installing Octave, and section Input and Output.
`PS1`
The primary prompt string. When executing interactively, Octave displays the primary prompt `PS1` when it is ready to read a command. Octave allows the prompt to be customized by inserting a number of backslash-escaped special characters that are decoded as follows:
`\t'
The time.
`\d'
The date.
`\n'
Begins a new line by printing the equivalent of a carriage return followed by a line feed.
`\s'
The name of the program (usually just `octave`).
`\w'
The current working directory.
`\W'
The basename of the current working directory.
`\u'
The username of the current user.
`\h'
The hostname.
`\#'
The command number of this command, counting from when Octave starts.
`\!'
The history number of this command. This differs from `\#' by the number of commands in the history list when Octave starts.
`\\$'
If the effective UID is 0, a #, otherwise a \$.
`\nnn'
The character whose character code in octal is `nnn'.
`\\'
A backslash.
The default value of `PS1` is `"\s:\#> "`. To change it, use a command like
```octave:13> PS1 = "\\u@\\h> "
```
which will result in the prompt `boris@kremvax> ' for the user `boris' logged in on the host `kremvax'. Note that two backslashes are required to enter a backslash into a string. See section String Constants.
`PS2`
The secondary prompt string, which is printed when Octave is expecting additional input to complete a command. For example, when defining a function over several lines, Octave will print the value of `PS1` at the beginning of each line after the first. Octave allows `PS2` to be customized in the same way as `PS1`. The default value of `PS2` is `"> "`.
`PS4`
If Octave is invoked with the `--echo-input` option, the value of `PS4` is printed before each line of input that is echoed. Octave allows `PS4` to be customized in the same way as `PS1`. The default value of `PS4` is `"+ "`. See section Invoking Octave, for a description of `--echo-input`.
`automatic_replot`
If this variable is `"true"`, Octave will automatically send a `replot` command to `gnuplot` each time the plot changes. Since this is fairly inefficient, the default value is `"false"`.
`default_return_value`
The value given to otherwise unitialized return values if `define_all_return_values` is `"true"`. The default value is `[]`.
`default_save_format`
Specify the default format used by the `save` command. Options are `"ascii"`, `"binary"`, `"mat-binary"`, or `"float-binary"`. The default value is `ascii`.
`define_all_return_values`
If the value of `define_all_return_values` is `"true"`, Octave will substitute the value specified by `default_return_value` for any return values that remain undefined when a function returns. The default value is `"false"`.
`do_fortran_indexing`
If the value of `do_fortran_indexing` is `"true"`, Octave allows you to select elements of a two-dimensional matrix using a single index by treating the matrix as a single vector created from the columns of the matrix. The default value is `"false"`.
`empty_list_elements_ok`
This variable controls whether Octave ignores empty matrices in a matrix list. For example, if the value of `empty_list_elements_ok` is `"true"`, Octave will ignore the empty matrices in the expression
```a = [1, [], 3, [], 5]
```
and the variable `a' will be assigned the value `[ 1 3 5 ]'. The default value is `"warn"`.
`gnuplot_binary`
The name of the program invoked by the plot command. The default value is `"gnuplot"`. See section Installing Octave.
`ignore_function_time_stamp`
This variable variable can be used to prevent Octave from making the system call `stat()` each time it looks up functions defined in function files. If `ignore_function_time_stamp` to `"system"`, Octave will not automatically recompile function files in subdirectories of `/usr/local/lib/1.1.1` if they have changed since they were last compiled, but will recompile other function files in the `LOADPATH` if they change. If set to `"all"`, Octave will not recompile any function files unless their definitions are removed with `clear`. For any other value of `ignore_function_time_stamp`, Octave will always check to see if functions defined in function files need to recompiled. The default value of `ignore_function_time_stamp` is `"system"`.
`implicit_str_to_num_ok`
If the value of `implicit_str_to_num_ok` is `"true"`, implicit conversions of strings to their numeric ASCII equivalents are allowed. Otherwise, an error message is printed and control is returned to the top level. The default value is `"false"`.
`ok_to_lose_imaginary_part`
If the value of `ok_to_lose_imaginary_part` is `"true"`, implicit conversions of complex numbers to real numbers are allowed (for example, by fsolve). If the value is `"warn"`, the conversion is allowed, but a warning is printed. Otherwise, an error message is printed and control is returned to the top level. The default value is `"warn"`.
`output_max_field_width`
This variable specifies the maximum width of a numeric output field. The default value is 10. It is possible to achieve a wide range of output styles by using different values of `output_precision` and `output_max_field_width`. Reasonable combinations can be set using the `format` function. See section Basic Input and Output.
`output_precision`
This variable specifies the minimum number of significant figures to display for numeric output. The default value is 5. It is possible to achieve a wide range of output styles by using different values of `output_precision` and `output_max_field_width`. Reasonable combinations can be set using the `format` function. See section Basic Input and Output.
`page_screen_output`
If the value of `page_screen_output` is `"true"`, all output intended for the screen that is longer than one page is sent through a pager. This allows you to view one screenful at a time. Some pagers (such as `less`---see section Installing Octave) are also capable of moving backward on the output. The default value is `"true"`. See section Input and Output. You can choose the program to use as the pager by setting the variable `PAGER`.
`prefer_column_vectors`
If `prefer_column_vectors` is `"true"`, operations like
```for i = 1:10
a (i) = i;
endfor
```
(for `a' previously undefined) produce column vectors. Otherwise, row vectors are preferred. The default value is `"false"`. If a variable is already defined to be a vector (a matrix with a single row or column), the original orientation is respected, regardless of the value of `prefer_column_vectors`.
`prefer_zero_one_indexing`
If the value of `prefer_zero_one_indexing` is `"true"`, Octave will perform zero-one style indexing when there is a conflict with the normal indexing rules. See section Index Expressions. For example, given a matrix
```a = [1, 2, 3, 4]
```
with `prefer_zero_one_indexing` is set to `"true"`, the expression
```a ([1, 1, 1, 1])
```
results in the matrix `[ 1 2 3 4 ]'. If the value of `prefer_zero_one_indexing` set to `"false"`, the result would be the matrix `[ 1 1 1 1 ]'. In the first case, Octave is selecting each element corresponding to a `1' in the index vector. In the second, Octave is selecting the first element multiple times. The default value for `prefer_zero_one_indexing` is `"false"`.
`print_answer_id_name`
If the value of `print_answer_id_name` is `"true"`, variable names are printed along with the result. Otherwise, only the result values are printed. The default value is `"true"`.
`print_empty_dimensions`
If the value of `print_empty_dimensions` is `"true"`, the dimensions of empty matrices are printed along with the empty matrix symbol, `[]'. For example, the expression
```zeros (3, 0)
```
will print
```ans =

[](3x0)
```
`propagate_empty_matrices`
If the value of `propagate_empty_matrices` is `"true"`, functions like `inverse` and `svd` will return an empty matrix if they are given one as an argument. The default value is `"true"`. See section Empty Matrices.
`resize_on_range_error`
If the value of `resize_on_range_error` is `"true"`, expressions like
```for i = 1:10
a (i) = i;
endfor
```
(for `a' previously undefined) result in the variable `a' being resized to be just large enough to hold the new value. Otherwise uninitialized elements are set to zero. If the value of `resize_on_range_error` is `"false"`, an error message is printed and control is returned to the top level. The default value is `"true"`.
`return_last_computed_value`
If the value of `return_last_computed_value` is true, and a function is defined without explicitly specifying a return value, the function will return the value of the last expression. Otherwise, no value will be returned. The default value is `"false"`. For example, the function
```function f ()
2 + 2;
endfunction
```
will either return nothing, if `return_last_computed_value` is `"false"`, or 4, if it is `"true"`.
`save_precision`
This variable specifies the number of digits to keep when saving data with the `save` command. The default value is 17.
`silent_functions`
If the value of `silent_functions` is `"true"`, internal output from a function is suppressed. Otherwise, the results of expressions within a function body that are not terminated with a semicolon will have their values printed. The default value is `"false"`. For example, if the function
```function f ()
2 + 2
endfunction
```
is executed, Octave will either print `ans = 4' or nothing depending on the value of `silent_functions`.
`split_long_rows`
For large matrices, Octave may not be able to display all the columns of a given row on one line of your screen. This can result in missing information or output that is nearly impossible to decipher, depending on whether your terminal truncates or wraps long lines. If the value of `split_long_rows` is `"true"`, Octave will display the matrix in a series of smaller pieces, each of which can fit within the limits of your terminal width. Each set of rows is labeled so that you can easily see which columns are currently being displayed. For example:
```octave:13> rand (2, 9)
ans =

Columns 1 through 7:

0.92205  0.72628  0.99841  0.62590  0.82422  0.77486  0.30258
0.15999  0.79484  0.75443  0.86995  0.91430  0.23980  0.64591

Columns 8 and 9:

0.08894  0.13266
0.28008  0.65575
```
The default value of `split_long_rows` is `"true"`.
`suppress_verbose_help_message`
If the value of `suppress_verbose_help_message` is `"true"`, Octave will not add additional help information to the end of the output from the `help` command and usage messages for built-in commands.
`treat_neg_dim_as_zero`
If the value of `treat_neg_dim_as_zero` is `"true"`, expressions like
```eye (-1)
```
produce an empty matrix (i.e., row and column dimensions are zero). Otherwise, an error message is printed and control is returned to the top level. The default value is `"false"`.
`warn_assign_as_truth_value`
If the value of `warn_assign_as_truth_value` is `"true"`, a warning is issued for statements like
```if (s = t)
...
```
since such statements are not common, and it is likely that the intent was to write
```if (s == t)
...
```
instead. There are times when it is useful to write code that contains assignments within the condition of a `while` or `if` statement. For example, statements like
```while (c = getc())
...
```
are common in C programming. It is possible to avoid all warnings about such statements by setting `warn_assign_as_truth_value` to `"false"`, but that may also let real errors like
```if (x = 1)  # intended to test (x == 1)!
...
```
slip by. In such cases, it is possible suppress errors for specific statements by writing them with an extra set of parentheses. For example, writing the previous example as
```while ((c = getc()))
...
```
will prevent the warning from being printed for this statement, while allowing Octave to warn about other assignments used in conditional contexts. The default value of `warn_assign_as_truth_value` is `"true"`.
`warn_comma_in_global_decl`
If the value of `warn_comma_in_global_decl` is `"true"`, a warning is issued for statements like
```global a = 1, b
```
which makes the variables `a' and `b' global and assigns the value 1 to the variable `a', because in this context, the comma is not interpreted as a statement separator. The default value of `warn_comma_in_global_decl` is `"true"`.
`warn_divide_by_zero`
If the value of `warn_divide_by_zero` is `"true"`, a warning is issued when Octave encounters a division by zero. If the value is `"false"`, the warning is omitted. The default value is `"true"`.
`warn_function_name_clash`
If the value of `warn_function_name_clash` is `"true"`, a warning is issued when Octave finds that the name of a function defined in a function file differs from the name of the file. If the value is `"false"`, the warning is omitted. The default value is `"true"`.
`whitespace_in_literal_matrix`
This variable allows some control over how Octave decides to convert spaces to commas and semicolons in matrix expressions like `[m (1)]' or
```[ 1, 2,
3, 4 ]
```
If the value of `whitespace_in_literal_matrix` is `"ignore"`, Octave will never insert a comma or a semicolon in a literal matrix list. For example, the expression `[1 2]' will result in an error instead of being treated the same as `[1, 2]', and the expression
```[ 1, 2,
3, 4 ]
```
will result in the vector [1 2 3 4] instead of a matrix. If the value of `whitespace_in_literal_matrix` is `"traditional"`, Octave will convert spaces to a comma between identifiers and `('. For example, given the matrix
```m = [3 2]
```
the expression
```[m (1)]
```
will be parsed as
```[m, (1)]
```
and will result in
```[3 2 1]
```
and the expression
```[ 1, 2,
3, 4 ]
```
will result in a matrix because the newline character is converted to a semicolon (row separator) even though there is a comma at the end of the first line (trailing commas or semicolons are ignored). This is apparently how MATLAB behaves. Any other value for `whitespace_in_literal_matrix` results in behavior that is the same as traditional, except that Octave does not convert spaces to a comma between identifiers and `('. For example, the expression
```[m (1)]
```
will produce `3'. This is the way Octave has always behaved.

## Other Built-in Variables

In addition to these variables, there are two other special built-in variables whose values are automatically updated.

`ans`
This variable holds the most recently computed result that was not explicitly assigned to a variable. For example, after the expression
```3^2 + 4^2
```
is evaluated, the value of `ans` is `25'.
`PWD`
The current working directory. The value of `PWD` is updated each time the current working directory is changed with the `cd' command. See section System Utilities.

## Summary of Preference Variables

Here is a summary of all of Octave's preference variables and their default values. In the following table `OCTAVE_HOME` stands for the root directory where Octave is installed, and `VERSION` stands for the Octave version number.

```EDITOR                        EDITOR environment variable, or "vi"
INFO_FILE                     "OCTAVE_HOME/info/octave.info"
".:OCTAVE_HOME/lib/VERSION"
PAGER                         "less", or "more"
PS1                           "\s:\#> "
PS2                           "> "
PS4                           "+ "
automatic_replot              "false"
default_return_value          []
do_fortran_indexing           "false"
define_all_return_values      "false"
empty_list_elements_ok        "warn"
gnuplot_binary                "gnuplot"
ignore_function_time_stamp    "system"
implicit_str_to_num_ok        "false"
ok_to_lose_imaginary_part     "warn"
output_max_field_width        10
output_precision              5
page_screen_output            "true"
prefer_column_vectors         "false"
prefer_zero_one_indexing      "false"
print_empty_dimensions        "true"
resize_on_range_error         "true"
return_last_computed_value    "false"
save_precision                17
silent_functions              "false"
split_long_rows               "true"
suppress_verbose_help_message "true"
treat_neg_dim_as_zero         "false"
warn_assign_as_truth_value    "true"
warn_comma_in_global_decl     "true"
warn_divide_by_zero           "true"
warn_function_name_clash      "true"
whitespace_in_literal_matrix  ""
```