matlab (MATLAB Function Reference)

Start MATLAB (UNIX systems only)

Syntax

matlab [-h|-help] | [-n] [-arch | -ext | -arch/ext]
[-c licensefile] [-display Xdisplay | -nodisplay]
[-nosplash] [-mwvisual visualid] [-debug]
[-nodesktop | -nojvm] [-runtime] [-check_malloc]
[-r MATLAB_command] [-Ddebugger [options]]

Description

matlab is a Bourne shell script that starts the MATLAB executable. (In this document, matlab refers to this script; MATLAB refers to the application program). The script determines, filters, and passes information to the executable through two mechanisms:

Arguments to the executable
Variables passed through the environment to the executable

There are three ways in which you can control these two mechanisms:

By specifying command-line options to the script
By assigning values in the MATLAB startup file .matlab6rc.sh
By assigning values to environment variables before executing the script

All arguments that ultimately get passed to the executable must be passed in as arguments to the script.

To affect the values of variables passed through the environment can be more complicated. Not all variables can be affected in the same way. The following decision hierarchy (from highest to lowest precedence) is used whenever possible to determine the final values of the environment variables passed to the MATLAB executable.

An argument has been passed to the script that controls the variable.
The variable is assigned in the .matlab6rc.sh startup file.
The variable is assigned in the environment before the script was executed.
The variable is assigned a default value in the script.

When invoked, matlab looks for the first occurrence of .matlab6rc.sh in the current directory, in the home directory ($HOME) and in the $MATLAB/bin directory, where the template version of .matlab6rc.sh is located.

You can edit the template file to redefine information used by the matlab script. If you do not want your changes applied system wide, copy the edited version of the script to your current or home directory. Ensure that you edit the section that applies to your machine architecture.

The following table lists essential environment variables and standard assignment behavior. See the comments and the code in the .matlab6rc.sh file for more information relevant to the affect this file has on these variables. Note that not all variables are referenced in the shipping .matlab6rc.sh.

Variable
Definition and Standard Assignment Behavior

ARCH
The machine architecture.
The value ARCH passed in with the -arch or -arch/ext argument to the script is tried first, then the value of the environment variable MATLAB_ARCH is tried next, and finally it is computed. The first one that gives a valid architecture is used.

AUTOMOUNT_MAP
Path prefix map for automounting.
The value set in .matlab6rc.sh (initially by the installer) is used unless the value differs from that determined by the script. In which case the value in the environment is used.

DISPLAY
The hostname of the X Window display MATLAB uses for output.
The value of Xdisplay passed with the -display argument to the script is used otherwise the value in the environment. DISPLAY is ignored by MATLAB if the -nodisplay argument is passed.

LD_LIBRARY_PATH
Final Load library path. The name LD_LIBRARY_PATH is platform dependent.
The final value is normally a colon separated list of five sublists each of which could be empty. The first sublist is defined in .matlab6rc.sh as LDPATH_PREFIX. The second sublist is computed in the script and includes directories inside the MATLAB root directory and relevant Java directories. The third sublist contains any nonempty value of LD_LIBRARY_PATH from the environment possibly augmented in .matlab6rc.sh. The fourth sublist contains system libraries. The final sublist is defined in .matlab6rc.sh as LDPATH_SUFFIX.

LM_LICENSE_FILE
The FLEXlm license variable.
The license file passed with the -c argument to the script is used, otherwise the value set in .matlab6rc.sh. In general, the final value is a colon separated list of license files and/or port@host entries. The shipping .matlab6rc.sh file starts out the value by prepending LM_LICENSE_FILE in the environment to a default license file.
Later in the MATLAB script, if the -c option is not used, the $MATLAB/etc directory is searched for the files that start with license.dat.DEMO. These files are assumed to contain demo licenses and are added automatically to end of the current list.

MATLAB
The MATLAB root directory.
The default computed by the script is used unless MATLABdefault is reset in .matlab6rc.sh.
MATLABdefault is not reset in the shipping .matlab6rc.sh.

MATLAB_DEBUG
Normally set to the name of debugger.
The -Ddebugger argument passed in to the script sets this variable. Otherwise, a nonempty value in the environment is used.

MATLAB_JAVA
The path to the root of the Java Runtime Environment.
The default set in the script is used unless MATLAB_JAVA is already set. Any nonempty value from .matlab6rc.sh is used first then any nonempty value from the environment. There is no value set in the shipping .matlab6rc.sh so that environment alone is used.

MATLAB_MEM_MGR
Turns on MATLAB memory integrity checking.
The -check_malloc argument passed in to the script sets this variable to 'debug'. Otherwise, a nonempty value set in .matlab6rc.sh is used, or a nonempty value in the environment is used. If a nonempty value is not found, the variable is not exported to the environment.

MATLABPATH
The MATLAB search path.
The final value is a colon separated list with the MATLABPATH from the environment prepended to a list of computed defaults.

SHELL
The shell to use when "!" or a Unix command is issued in MATLAB.
This is taken from the environment unless SHELL is reset in .matlab6rc.sh. SHELL is not reset in the shipping .matlab6rc.sh. If SHELL is empty or not defined then MATLAB uses /bin/sh internally.

TOOLBOX
Path of the toolbox directory.
A nonempty value in the environment is used first. Otherwise, $MATLAB/toolbox, computed by the script is used, unless TOOLBOX is reset in .matlab6rc.sh. TOOLBOX is not reset in the shipping .matlab6rc.sh.

XAPPLRESDIR
The X application resource directory.
A nonempty value in the environment is used first unless XAPPLRESDIR is reset in .matlab6rc.sh. Otherwise,
$MATLAB/X11/app-defaults, computed by the script is used.

XKEYSYMDB
The X keysym database file.
A nonempty value in the environment is used first unless XKEYSYMDB is reset in .matlab6rc.sh. Otherwise,
$MATLAB/X11/app-defaults/XKeysymDB, computed by the script is used.

Variable	Definition and Standard Assignment Behavior
`ARCH`	The machine architecture. The value ARCH passed in with the `-arch` or `-arch/ext` argument to the script is tried first, then the value of the environment variable `MATLAB_ARCH` is tried next, and finally it is computed. The first one that gives a valid architecture is used.
`AUTOMOUNT_MAP`	Path prefix map for automounting. The value set in `.matlab6rc.sh` (initially by the installer) is used unless the value differs from that determined by the script. In which case the value in the environment is used.
`DISPLAY`	The hostname of the X Window display MATLAB uses for output. The value of `Xdisplay` passed with the `-display` argument to the script is used otherwise the value in the environment. `DISPLAY` is ignored by MATLAB if the -nodisplay argument is passed.
`LD_LIBRARY_PATH`	Final Load library path. The name `LD_LIBRARY_PATH` is platform dependent. The final value is normally a colon separated list of five sublists each of which could be empty. The first sublist is defined in `.matlab6rc.sh` as `LDPATH_PREFIX`. The second sublist is computed in the script and includes directories inside the MATLAB root directory and relevant Java directories. The third sublist contains any nonempty value of `LD_LIBRARY_PATH` from the environment possibly augmented in `.matlab6rc.sh`. The fourth sublist contains system libraries. The final sublist is defined in `.matlab6rc.sh` as `LDPATH_SUFFIX`.
`LM_LICENSE_FILE`	The FLEXlm license variable. The license file passed with the `-c` argument to the script is used, otherwise the value set in `.matlab6rc.sh`. In general, the final value is a colon separated list of license files and/or port@host entries. The shipping `.matlab6rc.sh` file starts out the value by prepending `LM_LICENSE_FILE` in the environment to a default license file. Later in the MATLAB script, if the `-c` option is not used, the `$MATLAB/etc` directory is searched for the files that start with `license.dat.DEMO`. These files are assumed to contain demo licenses and are added automatically to end of the current list.
`MATLAB`	The MATLAB root directory. The default computed by the script is used unless `MATLABdefault` is reset in `.matlab6rc.sh`. MATLABdefault is not reset in the shipping `.matlab6rc.sh`.
`MATLAB_DEBUG`	Normally set to the name of debugger. The `-Ddebugger` argument passed in to the script sets this variable. Otherwise, a nonempty value in the environment is used.
`MATLAB_JAVA`	The path to the root of the Java Runtime Environment. The default set in the script is used unless `MATLAB_JAVA` is already set. Any nonempty value from `.matlab6rc.sh` is used first then any nonempty value from the environment. There is no value set in the shipping `.matlab6rc.sh` so that environment alone is used.
`MATLAB_MEM_MGR`	Turns on MATLAB memory integrity checking. The `-check_malloc` argument passed in to the script sets this variable to `'debug'`. Otherwise, a nonempty value set in `.matlab6rc.sh` is used, or a nonempty value in the environment is used. If a nonempty value is not found, the variable is not exported to the environment.
`MATLABPATH`	The MATLAB search path. The final value is a colon separated list with the `MATLABPATH` from the environment prepended to a list of computed defaults.
`SHELL`	The shell to use when "!" or a Unix command is issued in MATLAB. This is taken from the environment unless `SHELL` is reset in `.matlab6rc.sh`. `SHELL` is not reset in the shipping `.matlab6rc.sh`. If `SHELL` is empty or not defined then MATLAB uses `/bin/sh` internally.
`TOOLBOX`	Path of the toolbox directory. A nonempty value in the environment is used first. Otherwise, `$MATLAB/toolbox`, computed by the script is used, unless `TOOLBOX` is reset in `.matlab6rc.sh`. `TOOLBOX` is not reset in the shipping `.matlab6rc.sh`.
`XAPPLRESDIR`	The X application resource directory. A nonempty value in the environment is used first unless `XAPPLRESDIR` is reset in `.matlab6rc.sh`. Otherwise, `$MATLAB/X11/app-defaults`, computed by the script is used.
`XKEYSYMDB`	The X keysym database file. A nonempty value in the environment is used first unless `XKEYSYMDB` is reset in `.matlab6rc.sh`. Otherwise, `$MATLAB/X11/app-defaults/XKeysymDB`, computed by the script is used.

The matlab script determines the path of the MATLAB root directory as one level up the directory tree from the location of the script. Information in the AUTOMOUNT_MAP variable is used to fix the path so that it is correct to force a mount. This may involve deleting part of the pathname from the front of the MATLAB root path. The MATLAB variable is then used to locate all files within the MATLAB directory tree.

Options

The following table describes matlab command line options, grouped by function.

Option
Function

Diagnostic Options

-h |-help
Display matlab command usage. MATLAB is not started when you specify this option.

-n
Display all the final values of the environment variables and arguments passed to the MATLAB executable as well as other diagnostic information.
MATLAB is not started when you specify this option.

Select Which MATLAB Executable to Run

-arch
Run MATLAB assuming architecture arch.

-ext
Run the version of MATLAB with extension ext, if it exists.

-arch/ext
Run the version of MATLAB with extension ext, if it exists, assuming arch identifies the architecture.

Affect the Environment Variables Passed to the MATLAB Executable

-c licensefile
Set the value of the LM_LICENSE_FILE environment variable to licensefile. licensefile can be a colon separated list of files or port@host entries, or both. For more information, see LM_LICENSE_FILE in the variable table.

-check_malloc
Set the value of the MATLAB_MEM_MGR environment variable to 'debug'. This turns on MATLAB memory integrity checking. For more information, see MATLAB_MEM_MGR in the variable table.

-display Xserver
Define the X display used for MATLAB output, Xserver has the form hostname:display. For example,
matlab -display falstaff:0
causes MATLAB output to be displayed on the host named falstaff. This setting supersedes the value of the DISPLAY environment variable and the value of the DISPLAY variable defined in .matlab5rc.sh.

Passed Without Change to the MATLAB Executable

-debug
Provide debugging information, especially for X-based problems. Note that you should use this option only in conjunction with a Technical Support representative from The MathWorks, Inc.

-mwvisual visualid
The default X visual to use for figure windows.

-nodesktop
Do not start the MATLAB desktop. Use the current window for commands. The Java Virtual Machine (JVM) will be started.

-nojvm
Shut off all Java support by not starting the Java Virtual Machine (JVM). In particular, the MATLAB desktop will not be started.

-nosplash
Do not display the splash screen during startup.

-r MATLAB_command
Start MATLAB and execute the MATLAB command. An arbitrary MATLAB command string can be used here. You will have to use proper quoting to make the input legal for both the shell and MATLAB.

-runtime
Run MATLAB in Runtime Server mode. Required only if MATLAB is run from the Runtime Development Kit.

Debugging

-Ddebugger [options]

Start MATLAB with the specified debugger (e.g. dbx, gdb, dde, xdb, cvd). A full path can be specified for debugger. The options cover ONLY those that go after the executable to be debugged in the syntax of the actual debug command and for most debuggers this is very limited. To customize your debugging session use a startup file. See your debugger documentation for details. The MATLAB_DEBUG environment variable is set to the filename part of the debugger argument. For more information, see MATLAB_DEBUG in the variable table above.

Option	Function
Diagnostic Options
`-h \|-help`	Display `matlab` command usage. MATLAB is not started when you specify this option.
`-n`	Display all the final values of the environment variables and arguments passed to the MATLAB executable as well as other diagnostic information. MATLAB is not started when you specify this option.
Select Which MATLAB Executable to Run
`-arch`	Run MATLAB assuming architecture `arch`.
`-ext`	Run the version of MATLAB with extension `ext`, if it exists.
`-arch/ext`	Run the version of MATLAB with extension `ext,` if it exists, assuming `arch` identifies the architecture.
Affect the Environment Variables Passed to the MATLAB Executable
`-c licensefile`	Set the value of the `LM_LICENSE_FILE` environment variable to `licensefile`. `licensefile` can be a colon separated list of files or `port@host` entries, or both. For more information, see `LM_LICENSE_FILE` in the variable table.
`-check_malloc`	Set the value of the `MATLAB_MEM_MGR` environment variable to 'debug'. This turns on MATLAB memory integrity checking. For more information, see `MATLAB_MEM_MGR` in the variable table.
`-display` `Xserver`	Define the X display used for MATLAB output, `Xserver` has the form `hostname:display`. For example, `matlab -display falstaff:0` causes MATLAB output to be displayed on the host named falstaff. This setting supersedes the value of the `DISPLAY` environment variable and the value of the `DISPLAY` variable defined in `.matlab5rc.sh`.
Passed Without Change to the MATLAB Executable
`-debug`	Provide debugging information, especially for X-based problems. Note that you should use this option only in conjunction with a Technical Support representative from The MathWorks, Inc.
`-mwvisual visualid`	The default X visual to use for figure windows.
`-nodesktop`	Do not start the MATLAB desktop. Use the current window for commands. The Java Virtual Machine (JVM) will be started.
`-nojvm`	Shut off all Java support by not starting the Java Virtual Machine (JVM). In particular, the MATLAB desktop will not be started.
`-nosplash`	Do not display the splash screen during startup.
`-r MATLAB_command`	Start MATLAB and execute the MATLAB command. An arbitrary MATLAB command string can be used here. You will have to use proper quoting to make the input legal for both the shell and MATLAB.
`-runtime`	Run MATLAB in Runtime Server mode. Required only if MATLAB is run from the Runtime Development Kit.
Debugging
`-Ddebugger` `[options]`	Start MATLAB with the specified `debugger` (e.g. dbx, gdb, dde, xdb, cvd). A full path can be specified for debugger. The options cover ONLY those that go after the executable to be debugged in the syntax of the actual debug command and for most debuggers this is very limited. To customize your debugging session use a startup file. See your debugger documentation for details. The `MATLAB_DEBUG` environment variable is set to the filename part of the debugger argument. For more information, see `MATLAB_DEBUG` in the variable table above.

Any arguments that the matlab script cannot recognize are passed without change to the MATLAB executable. If the MATLAB executable does not recognize the arguments they will be ignored without warning.

If you are debugging, these arguments should be used as part of a command inside the debugger like run and not used when running the matlab script. If any of the options are placed before the -Ddebugger argument, they will be handled as if they were part of the options after the -Ddebugger argument and will be treated as illegal options by most debuggers.

See Also

mex

material matlabrc