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 number of 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 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 sqrt (-1). 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 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.

argv
     The command line arguments passed to Octave are available in this variable.  For example, if you invoked Octave using the command

          octave --no-line-editing --silent

     argv would be a string vector with the elements --no-line-editing and --silent.  The following code will print the command line arguments:

          for i = 1:nargin
            printf ("argv(%d) = %s\n", i, argv(i,:));
          endfor

     See Index Expressions for an explanation of how to properly index arrays of strings and substrings in Octave.

eps
     The machine precision.  More precisely, eps is the largest relative spacing between any two adjacent numbers in the machine's floating point system.  This number is obviously system-dependent.  On machines that support 64 bit IEEE floating point arithmetic, eps is approximately 2.2204e-16.

nargin
     The value of nargin is automatically set to the number of command line arguments.  It is also used in the context of user-defined functions to indicate the number of arguments that were passed to the function.  If you need to know the number of command line arguments inside a function, you must define a global variable and save the initial value of nargin in the global variable.

pi
     The ratio of the circumference of a circle to its diameter. Internally, pi is computed as 4.0 * atan (1.0).

program_invocation_name
program_name
     When Octave starts, the value of program_invocation_name is automatically set to the name that was typed at the shell prompt to run Octave, and the value of program_name is automatically set to the final component of program_invocation_name.  For example, if you typed /usr/local/bin/octave to start Octave, program_invocation_name would have the value /usr/local/bin/octave, and program_name would have the value octave.

     If executing a script from the command line (e.g., octave foo.m or using an executable Octave script, the program name is set to the name of the script.  See Executable Octave Programs for an example of how to create an executable Octave script.

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 1.7977e+308

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 2.2251e-308

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 Startup Files for more information.

XXX FIXME XXX -- say something here to explain "true", "false", etc.

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".

EXEC_PATH
     The variable EXEC_PATH is a colon separated list of directories to search when executing subprograms.  Its initial value is taken from the environment variable OCTAVE_EXEC_PATH (if it exists) or PATH, but that value can be overridden by the the command line argument --exec-path PATH, or by setting the value of EXEC_PATH in a startup script.  If the value of EXEC_PATH begins (ends) with a colon, the directories OCTAVE_HOME/libexec/octave/VERSION/exec/ARCH and OCTAVE_HOME/bin are prepended (appended) to EXEC_PATH (if you don't specify a value for EXEC_PATH explicitly, these special directories are prepended to your shell path).

IMAGEPATH
     A colon separated list of directories in which to search for image files.  See Image Processing for a description of Octave's image processing capabilities.

INFO_FILE
     The variable INFO_FILE names the location of the Octave info file. The default value is "OCTAVEHOME/info/octave.info".

INFO_PROGRAM
     The variable INFO_PROGRAM names the info program to run.  Its initial value is OCTAVEHOME/libexec/octave/VERSION/exec/ARCH/info, but that value can be overridden by the environment variable OCTAVE_INFO_PROGRAM, or the command line argument --info-program NAME, or by setting the value of INFO_PROGRAM in a startup script.

LOADPATH
     A colon separated list of directories in which to search for function files.  See Functions and Scripts.  The value of LOADPATH overrides the environment variable OCTAVE_PATH.  See Installation.

     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 Organization of Functions 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 Installation, and 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.

     \H
          The hostname, up to the first `.'.

     \#
          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.kgb.su.  Note that two backslashes are required to enter a backslash into a string. See 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 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".

beep_on_error
     If the value of beep_on_error is "true", Octave will try to ring your terminal's bell before printing an error message.  The default value is "false".

completion_append_char
     The value of completion_append_char is used as the character to append to successful command-line completion attempts.  The default value is " " (a single space).

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 Installation.

gnuplot_has_multiplot
     If the value of this variable is nonzero, Octave assumes that your copy of gnuplot has the multiplot support that is included in recent 3.6beta releases.  It's initial value is determined by configure, but it can be changed in your startup script or at the command line in case configure got it wrong, or if you upgrade your gnuplot installation.

history_file
     This variable specifies the name of the file used to store command history.  The default value is "~/.octave_hist", but may be overridden by the environment variable OCTAVE_HISTFILE.

history_size
     This variable specifies how many entries to store in the history file. The default value is 1024, but may be overridden by the environment variable OCTAVE_HISTSIZE.

ignore_function_time_stamp
     This 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 OCTAVEHOME/lib/VERSION 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 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 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 Installation) are also capable of moving backward on the output.  The default value is "true". See 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 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 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.

saving_history
     If the value of saving_history is "true", command entered on the command line are saved in the file specified by the variable history_file.

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".

struct_levels_to_print
     This variable controls the depth of nested structures to print. The default is 2.

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".

warn_missing_semicolon
     If the value of this variable is nonzero, Octave will warn when statements in function definitions don't end in semicolons.  The default value is 0.

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 predefined constants and preference 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 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 OCT_HOME stands for the root directory where Octave is installed, VERSION stands for the Octave version number, and SYS stands for the type of system for which Octave was compiled (for example, alpha-dec-osf3.2).

     EDITOR                        "vi"
     EXEC_PATH                     ":$PATH"
     INFO_FILE                     "OCT_HOME/info/octave.info"
     INFO_PROGRAM                  "OCT_HOME/libexec/octave/VERSION/exec/SYS/info"
     LOADPATH                      ".:OCT_HOME/lib/VERSION"
     PAGER                         "less", or "more"
     PS1                           "\s:\#> "
     PS2                           "> "
     PS4                           "+ "
     automatic_replot              0
     beep_on_error                 0
     completion_append_char        " "
     default_return_value          []
     do_fortran_indexing           0
     define_all_return_values      0
     empty_list_elements_ok        "warn"
     gnuplot_binary                "gnuplot"
     history_file                  "~/.octave_hist"
     history_size                  1024
     ignore_function_time_stamp    "system"
     implicit_str_to_num_ok        0
     ok_to_lose_imaginary_part     "warn"
     output_max_field_width        10
     output_precision              5
     page_screen_output            1
     prefer_column_vectors         0
     prefer_zero_one_indexing      0
     print_answer_id_name          1
     print_empty_dimensions        1
     resize_on_range_error         1
     return_last_computed_value    0
     save_precision                17
     saving_history                1
     silent_functions              0
     split_long_rows               1
     struct_levels_to_print        2
     suppress_verbose_help_message 1
     treat_neg_dim_as_zero         0
     warn_assign_as_truth_value    1
     warn_comma_in_global_decl     1
     warn_divide_by_zero           1
     warn_function_name_clash      1
     whitespace_in_literal_matrix  ""

The following variables may be set from the environment or by a command line option.

     Variable        Environment Variable        Option
     --------        --------------------        ------
     EDITOR          EDITOR
     EXEC_PATH       OCTAVE_EXEC_PATH            --exec-path PATH
     LOADPATH        OCTAVE_PATH                 --path PATH
     INFO_FILE       OCTAVE_INFO_FILE            --info-file FILE
     INFO_PROGRAM    OCTAVE_INFO_PROGRAM         --info-program PROGRAM
     history_size    OCTAVE_HISTSIZE
     history_file    OCTAVE_HISTFILE