system

Execute operating system command and return output

Syntax

status = system(command)

[status,cmdout] = system(command)

[status,cmdout] = system(command,'-echo')

[status,cmdout] = system(___,EnvName1,EnvVal1,...,EnvNameN,EnvValN)

Description

status = system(command) calls the operating system to execute the specified command. The operation waits for the command to finish execution before returning the exit status of the command to the status variable.

The function starts a new cmd/shell process, executes command, exits the process, and returns to the MATLAB^® process. Updates to the system environment made by command are not visible to MATLAB.

[status,cmdout] = system(command) also returns the output of the command to cmdout. This syntax is most useful for commands that do not require user input, such as dir.

[status,cmdout] = system(command,'-echo') also displays (echoes) the command output in the MATLAB Command Window. This syntax is most useful for commands that require user input and that run correctly in the MATLAB Command Window.

[status,cmdout] = system(___,EnvName1,EnvVal1,...,EnvNameN,EnvValN) sets the values of operating system environment variables. If EnvName exists as an environment variable, then system replaces its current value with EnvVal. If EnvName does not exist, then system creates an environment variable called EnvName and assigns EnvVal to it.

system passes EnvName and EnvVal to the operating system unchanged. Special characters, such as ;, /, :, $, and %, are unexpanded in EnvVal.

Examples

Windows: Display Operating System Command Status and Output

Display the current folder using the cd command. A status of zero indicates that the command completed successfully. MATLAB returns a character vector containing the current folder in cmdout.

command = 'cd';
[status,cmdout] = system(command)

Windows: Save Command Exit Status

To create a folder named mynew, call the mkdir command and save the exit status to a variable. A status of zero indicates that the mynew folder was created successfully.

command = 'mkdir mynew';
status = system(command)

Windows: Open and Run a UI Command

Open Microsoft^® Notepad and immediately return the exit status to MATLAB by appending an ampersand (&) to the notepad command. A status of zero indicates that Notepad successfully started.

status = system('notepad &')

Windows: Save Command Output

Execute the dir command and view the exit status and command output. cmdout contains the command output.

[~,cmdout] = system('dir');

Windows: Save Unsuccessful Command Status and Error Message

Attempt to execute a command called badcmd. Then, view the status and results output arguments. When you call an invalid command, status indicates failure and results contains the DOS error message.

[status,results] = system('badcmd')

UNIX: Save Command Exit Status and Output

List all users who are currently logged in, and save the command exit status and output. Then, view the status. A status of zero indicates that the command completed successfully. MATLAB® returns a list of users in cmdout.

command = 'who';
[status,cmdout] = system(command);
status

status = 
0

Input Arguments

command — Operating system command

string | character vector

Operating system command, specified as a string or a character vector. The command executes in a system shell, which might not be the shell from which you started MATLAB. To specify multiple operating system commands, use cmdsep to provide the platform-specific command separator character.

Example: "dir"

Example: "ls"

EnvName — Environment variable name

string scalar | character vector

Environment variable name, specified as a string scalar or character vector.

The maximum number of characters in name is 2¹⁵ – 2, or 32,766. If name contains the = character, then system throws an error. The behavior of environment variables with = in the name is not well defined.

Example: "PATH"

EnvVal — Environment variable value

string scalar | character vector | missing

Environment variable value, specified as a string scalar, character vector, or missing. Remove an environment variable by setting its value to missing.

Example: "C:\TEMP"

Output Arguments

status — Command exit status

0 | nonzero integer

Command exit status, returned as either 0 or a nonzero integer. When the command is successful, status is 0. Otherwise, status is a nonzero integer.

• If command includes the ampersand character (&), then status is the exit status when command starts

• If command does not include the ampersand character (&), then status is the exit status upon command completion.

cmdout — Output of operating system command

character vector

Output of the operating system command, returned as a character vector. The system shell might not properly represent non-Unicode^® characters.

Limitations

• MATLAB converts characters to the encoding that your operating system shell accepts. Output from the command is converted to the MATLAB encoding to be displayed in the command window. If you get unexpected results from the command, enter the command argument directly at the operating system prompt to see how the operating system treats your input.

• Callback functions are not called while the system command is executing.

More About

Windows Tips and Limitations

• MS-DOS^® does not support UNC path names. Therefore, if the current folder uses a UNC path name, then running system with a DOS command that relies on the current folder fails. To work around this limitation, change the folder to a mapped drive before calling system.

• You can override an environment variable in the system command. For example, the following code sets the PATH variable to myPath, then calls the system command dosCommand with that value.

  system(['set PATH=' myPath ' && ' dosCommand])

• To execute the operating system command in the background, include the trailing character, &, in the command argument. For example, type 'notepad &'. The exit status is immediately returned to the status variable. This syntax is useful for console programs that require interactive user command input while they run, and that do not run correctly in the MATLAB Command Window.

  If command includes the trailing & character, then cmdout is empty.

• The system command uses the same credentials as the credentials used to start MATLAB. To set credentials for program myprogram.exe to require admin privileges, type:

  system('cmd /C myprogram.exe');

UNIX Tips and Limitations

• MATLAB uses a shell program to execute the given command. It determines which shell program to use by checking environment variables on your system. MATLAB first checks the MATLAB_SHELL variable, and if either empty or not defined, then checks SHELL. If SHELL is also empty or not defined, MATLAB uses /bin/sh.

• The system function redirects stdin to command by default. This redirection also passes MATLAB script commands and the keyboard type-ahead buffer to the invoked command while the system function executes. This behavior can lead to corrupted output when system does not complete execution immediately. To disable stdin and type-ahead redirection, include the formatted text < /dev/null in the call to the invoked command.

• You can override an environment variable in the system command. The syntax depends on the UNIX^® shell. For example, using the BASH shell, the following code sets the PATH variable to myPath, then calls the system command command with that value.

  system(['export PATH=' myPath ' ; ' command])

• To execute the operating system command in the background, include the trailing character, &, in the command argument. For example, type 'emacs &'. The exit status is immediately returned to the status variable. This syntax is useful for console programs that require interactive user command input while they run, and that do not run correctly in the MATLAB Command Window.

  If command includes the trailing & character, then cmdout is empty.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™. (since R2024b)

Usage notes and limitations:

• The -echo flag must be compile constant.

• stdin of the calling process is inherited on Windows^® and UNIX.

• On UNIX, if a second output is requested, stdout is redirected to a pipe. Otherwise, stdout is inherited from the calling process.

• On Windows, the nargout determines whether the output read from the pipe is stored in a variable or sent to stdout of the calling process. If the number of arguments is 1, the output from the pipe is sent to stdout. Otherwise, it is stored in a variable.

Version History

Introduced before R2006a

R2023a: Remove environment variables using missing

Remove an environment variable by setting its value to missing.