Previous: Terminal Input, Up: Basic Input and Output

16.1.3 Simple File I/O

The save and load commands allow data to be written to and read from disk files in various formats. The default format of files written by the save command can be controlled using the built-in variables default_save_format and save_precision.

Note that Octave cannot yet save or load structure variables or any user-defined types.

— Command: save options file v1 v2 ...

Save the named variables v1, v2, ... in the file file. The special filename `-' can be used to write the output to your terminal. If no variable names are listed, Octave saves all the variables in the current scope. Valid options for the save command are listed in the following table. Options that modify the output format override the format specified by the built-in variable default_save_format.

-ascii
Save the data in Octave's text data format.

WARNING: the meaning of this option will change in a future version of Octave to be compatible with Matlab. To keep the meaning of your code the same across this change, use the -text option instead.

-binary
Save the data in Octave's binary data format.
-float-binary
Save the data in Octave's binary data format but only using single precision. You should use this format only if you know that all the values to be saved can be represented in single precision.
-mat
-mat-binary
Save the data in Matlab's binary data format.
-V4
-v4
-4
-mat4-binary
Save the data in the binary format written by Matlab version 4.
-hdf5
Save the data in HDF5 format. (HDF5 is a free, portable binary format developed by the National Center for Supercomputing Applications at the University of Illinois.)
-float-hdf5
Save the data in HDF5 format but only using single precision. You should use this format only if you know that all the values to be saved can be represented in single precision.
-save-builtins
Force Octave to save the values of built-in variables too. By default, Octave does not save built-in variables.

The list of variables to save may include wildcard patterns containing the following special characters:

?
Match any single character.
*
Match zero or more characters.
[ list ]
Match the list of characters specified by list. If the first character is ! or ^, match all characters except those specified by list. For example, the pattern `[a-zA-Z]' will match all lower and upper case alphabetic characters.
-text
Save the data in Octave's text data format.

Except when using the Matlab binary data file format, saving global variables also saves the global status of the variable, so that if it is restored at a later time using `load', it will be restored as a global variable.

The command 

          save -binary data a b*

saves the variable `a' and all variables beginning with `b' to the file data in Octave's binary format.

There are three variables that modify the behavior of save and three more that control whether variables are saved when Octave exits unexpectedly.

— Built-in Variable: crash_dumps_octave_core

If this variable is set to a nonzero value, Octave tries to save all current variables the the file "octave-core" if it crashes or receives a hangup, terminate or similar signal. The default value is 1.

— Built-in Variable: sighup_dumps_octave_core

If this variable is set to a nonzero value and crash_dumps_octave_core is also nonzero, Octave tries to save all current variables the the file "octave-core" if it receives a hangup signal. The default value is 1.

— Built-in Variable: sigterm_dumps_octave_core

If this variable is set to a nonzero value and crash_dumps_octave_core is also nonzero, Octave tries to save all current variables the the file "octave-core" if it receives a terminate signal. The default value is 1.

— Built-in Variable: default_save_format

This variable specifies the default format for the save command. It should have one of the following values: "ascii", "binary", float-binary, or "mat-binary". The initial default save format is Octave's text format.

— Built-in Variable: save_precision

This variable specifies the number of digits to keep when saving data in text format. The default value is 17.

— Built-in Variable: save_header_format_string

This variable specifies the the format string for the comment line that is written at the beginning of text-format data files saved by Octave. The format string is passed to strftime and should begin with the character `#' and contain no newline characters. If the value of save_header_format_string is the empty string, the header comment is omitted from text-format data files. The default value is 

          "# Created by Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@HOST>"

— Command: load options file v1 v2 ...

Load the named variables from the file file. As with save, you may specify a list of variables and load will only extract those variables with names that match. For example, to restore the variables saved in the file data, use the command 

          load data

If a variable that is not marked as global is loaded from a file when a global symbol with the same name already exists, it is loaded in the global symbol table. Also, if a variable is marked as global in a file and a local symbol exists, the local symbol is moved to the global symbol table and given the value from the file. Since it seems that both of these cases are likely to be the result of some sort of error, they will generate warnings.

If invoked with a single output argument, Octave returns data instead of inserting variables in the symbol table. If the data file contains only numbers (TAB- or space-delimited columns), a matrix of values is returned. Otherwise, load returns a structure with members corresponding to the names of the variables in the file.

The load command can read data stored in Octave's text and binary formats, and Matlab's binary format. It will automatically detect the type of file and do conversion from different floating point formats (currently only IEEE big and little endian, though other formats may added in the future).

Valid options for load are listed in the following table.

-force
The `-force' option is accepted but ignored for backward compatiability. Octave now overwrites variables currently in memeory with the same name as those found in the file.
-ascii
Force Octave to assume the file is in Octave's text format.

WARNING: the meaning of this option will change in a future version of Octave to be compatible with Matlab. To keep the meaning of your code the same across this change, use the -text option instead.

-binary
Force Octave to assume the file is in Octave's binary format.
-mat
-mat-binary
Force Octave to assume the file is in Matlab's version 6 binary format.
-V4
-v4
-4
-mat4-binary
Force Octave to assume the file is in the binary format written by Matlab version 4.
-hdf5
Force Octave to assume the file is in HDF5 format. (HDF5 is a free, portable binary format developed by the National Center for Supercomputing Applications at the University of Illinois.) Note that Octave can read HDF5 files not created by itself, but may skip some datasets in formats that it cannot support.
-import
The `-import' is accepted but ignored for backward compatiability. Octave can now support multi-dimensional HDF data and automatically modifies variable names if they are invalid Octave identifiers.
-text
Force Octave to assume the file is in Octave's text format.