system - Execute operating system command and return output - MATLAB (original) (raw)

Execute operating system command and return output

Syntax

Description

[status](#btnrzs7-1%5Fsep%5Fshared-status) = system([command](#btnrzs7-1-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, executescommand, exits the process, and returns to the MATLAB® process. Updates to the system environment made bycommand are not visible to MATLAB.

[[status](#btnrzs7-1%5Fsep%5Fshared-status),[cmdout](#btnrzs7-1%5Fsep%5Fshared-cmdout)] = system([command](#btnrzs7-1-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.

example

[[status](#btnrzs7-1%5Fsep%5Fshared-status),[cmdout](#btnrzs7-1%5Fsep%5Fshared-cmdout)] = system([command](#btnrzs7-1-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](#btnrzs7-1%5Fsep%5Fshared-status),[cmdout](#btnrzs7-1%5Fsep%5Fshared-cmdout)] = system(___,[EnvName](#mw%5Ff0b0e756-050c-4383-a8a0-fb4758775308)1,[EnvVal](#mw%5Fee24b0ae-0250-4658-abf0-243fb383729f)1,...,[EnvName](#mw%5Ff0b0e756-050c-4383-a8a0-fb4758775308)N,[EnvVal](#mw%5Fee24b0ae-0250-4658-abf0-243fb383729f)N) sets the values of operating system environment variables. IfEnvName exists as an environment variable, thensystem replaces its current value withEnvVal. If EnvName does not exist, then system creates an environment variable calledEnvName and assigns EnvVal to it.

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

Examples

collapse all

Windows: Display Operating System Command Status and Output

Display the current folder using the cd command. Astatus 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 themkdir command and save the exit status to a variable. A status of zero indicates that themynew 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 andresults 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

Input Arguments

collapse all

command — Operating system command

string | character vector

Operating system command, specified as a string or a character vector. Thecommand executes in a system shell, which might not be the shell from which you started MATLAB. To specify multiple operating system commands, usecmdsep 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 215 – 2, or 32,766. Ifname 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

collapse all

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.

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

collapse all

Windows Tips and Limitations

• MS-DOS® does not support UNC path names. Therefore, if the current folder uses a UNC path name, then runningsystem with a DOS command that relies on the current folder fails. To work around this limitation, change the folder to a mapped drive before callingsystem.
• You can override an environment variable in thesystem command. For example, the following code sets the PATH variable to_myPath, then calls the system commanddosCommand_ with that value.
  system(['set PATH=' myPath ' && ' dosCommand])
• To execute the operating system command in the background, include the trailing character, &, in thecommand 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, thencmdout is empty.
• The system command uses the same credentials as the credentials used to start MATLAB. To set credentials for programmyprogram.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 checksSHELL. If SHELL is also empty or not defined, MATLAB uses /bin/sh.
• The system function redirectsstdin 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 whensystem 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 thesystem 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 commandcommand_ with that value.
  system(['export PATH=' myPath ' ; ' command])
• To execute the operating system command in the background, include the trailing character, &, in thecommand 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, thencmdout 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 tostdout of the calling process. If the number of arguments is 1, the output from the pipe is sent tostdout. Otherwise, it is stored in a variable.

Version History

Introduced before R2006a

expand all

R2023a: Remove environment variables using missing

Remove an environment variable by setting its value tomissing.