### 13.6 Function Files

Except for simple one-shot programs, it is not practical to have to define all the functions you need each time you need them. Instead, you will normally want to save them in a file so that you can easily edit them, and save them for use at a later time.

Octave does not require you to load function definitions from files before using them. You simply need to put the function definitions in a place where Octave can find them.

When Octave encounters an identifier that is undefined, it first looks for variables or functions that are already compiled and currently listed in its symbol table. If it fails to find a definition there, it searches the list of directories specified by the built-in variable `LOADPATH` for files ending in `.m` that have the same base name as the undefined identifier.1 Once Octave finds a file with a name that matches, the contents of the file are read. If it defines a single function, it is compiled and executed. See Script Files, for more information about how you can define more than one function in a single file.

When Octave defines a function from a function file, it saves the full name of the file it read and the time stamp on the file. After that, it checks the time stamp on the file every time it needs the function. If the time stamp indicates that the file has changed since the last time it was read, Octave reads it again.

Checking the time stamp allows you to edit the definition of a function while Octave is running, and automatically use the new function definition without having to restart your Octave session. Checking the time stamp every time a function is used is rather inefficient, but it has to be done to ensure that the correct function definition is used.

To avoid degrading performance unnecessarily by checking the time stamps on functions that are not likely to change, Octave assumes that function files in the directory tree `octave-home/share/octave/version/m` will not change, so it doesn't have to check their time stamps every time the functions defined in those files are used. This is normally a very good assumption and provides a significant improvement in performance for the function files that are distributed with Octave.

If you know that your own function files will not change while you are running Octave, you can improve performance by setting the variable `ignore_function_time_stamp` to `"all"`, so that Octave will ignore the time stamps for all function files. Setting it to `"system"` gives the default behavior. If you set it to anything else, Octave will check the time stamps on all function files.

— Built-in Variable: DEFAULT_LOADPATH

> A colon separated list of directories in which to search for function files. The value of this variable is automatically substituted for leading, trailing, or doubled colons that appear in the built-in variable `LOADPATH`.

— Built-in Variable: 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`. Leading, trailing, or doubled colons that appear in `LOADPATH` are replaced by the value of `DEFAULT_LOADPATH`. The default value of `LOADPATH` is `":"`, which tells Octave to search in the directories specified by `DEFAULT_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.

— Built-in Function: rehash ()

> Reinitialize Octave's `LOADPATH` directory cache.

— Built-in Function: file_in_loadpath (file)
— Built-in Function: file_in_loadpath (file, "all")

> Return the absolute name name of file if it can be found in the list of directories specified by `LOADPATH`. If no file is found, return an empty matrix.

> If the first argument is a cell array of of strings, search each directory of the loadpath for element of the cell array and return the first that matches.

> If the second optional argument `"all"` is supplied, return a cell array containing the list of all files that have the same name in the path. If no files are found, return an empty cell array.

— Built-in Variable: 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 `octave-home/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"`.

— Built-in Variable: warn_function_name_clash

> If the value of `warn_function_name_clash` is nonzero, 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 names disagree, the name declared inside the file is ignored.) If the value is 0, the warning is omitted. The default value is 1.

— Built-in Variable: warn_future_time_stamp

> If the value of this variable is nonzero, Octave will print a warning if it finds a function file with a time stamp that is in the future.

#### Footnotes

[1] The ``.m`' suffix was chosen for compatibility with Matlab.