escapeshellcmd

Escape shell metacharacters

&reftitle.description; `string` `escapeshellcmd` `string` `command`

`escapeshellcmd` escapes any characters in a string that might be used to trick a shell command into executing arbitrary commands. This function should be used to make sure that any data coming from user input is escaped before this data is passed to the `exec` or `system` functions, or to the backtick operator.

Following characters are preceded by a backslash: `&#;`|*?~<>^()[]{}$\`, `\x0A` and `\xFF`. `'` and `"` are escaped only if they are not paired. On Windows, all these characters plus `%` and `!` are preceded by a caret (`^`).

&reftitle.parameters;

`command`

- The command that will be escaped.

&reftitle.returnvalues;

The escaped string.

&reftitle.examples;

### `escapeshellcmd` example

    <?php
    // We allow arbitrary number of arguments intentionally here.
    $command = './configure '.$_POST['configure_options'];

    $escaped_command = escapeshellcmd($command);

    system($escaped_command);
    ?>

&reftitle.notes;

`escapeshellcmd` should be used on the whole command string, and it still allows the attacker to pass arbitrary number of arguments. For escaping a single argument `escapeshellarg` should be used instead.

Spaces will not be escaped by `escapeshellcmd` which can be problematic on Windows with paths like: `C:\Program Files\ProgramName\program.exe`. This can be mitigated using the following code snippet:

    <?php
    $cmd = preg_replace('`(?<!^) `', '^ ', escapeshellcmd($cmd));

&reftitle.seealso;

- `escapeshellarg`
- `exec`
- `popen`
- `system`
- backtick operator