Utils::ProcessArgs Class | Extending Qt Creator Manual
Description: Handles shell-quoted process arguments.

- Extending Qt Creator Manual
- QtCreator
- ProcessArgs
- Extending Qt Creator Manual 19.0.0

# Utils::ProcessArgs Class

class Utils::ProcessArgs

Handles shell-quoted process arguments. More...

Header: | `#include <ProcessArgs>`

- List of all members, including inherited members

## Static Public Members

bool | expandMacros(QString *cmd, const Utils::ProcessArgs::FindMacro &findMacro, Utils::OsType osType)

## Detailed Description

## Member Function Documentation

### `[static]` bool ProcessArgs::expandMacros(QString *cmd, const Utils::ProcessArgs::FindMacro &findMacro, Utils::OsType osType)

Searches macros with the function findMacro and performs in-place macro expansion (substitution) on the string cmd, which is expected to contain a shell command. osType specifies the syntax, which is Bourne Shell compatible for Unix and `cmd` compatible for Windows.

Returns `false` if substitution cannot be performed safely, because the command cannot be parsed – for example due to quoting errors.

Note: This function is designed to be safe to use with expando objects that contain shell meta-characters. However, placing expandos in the wrong place of the command may defeat the expander's efforts to quote their contents, which will likely result in incorrect command execution. In particular, expandos that contain untrusted data might expose the end-user of the application to critical shell code injection vulnerabilities. To avoid these issues, follow the guidelines in Unix security considerations and Windows security considerations. Generally, it is a better idea to invoke shell scripts rather than to assemble complex one-line commands.

#### Unix notes

Explicitly supported shell constructs: \ '' "" {} () $(()) ${} $() ``

Implicitly supported shell constructs: (())

Unsupported shell constructs that will cause problems:

- Shortened `case $v in pat)` syntax. Use `case $v in (pat)` instead.
- Bash-style `$""` and `$''` string quoting syntax.

The rest of the shell syntax (including bash syntax) should not cause problems and is ignored.

##### Unix security considerations

- Backslash-escaping an expando is treated as a quoting error.
- Do not put expandos into double quoted substitutions as this may trigger parser bugs in some shells:

       "${VAR:-%{macro}}"

- Do not put expandos into command line arguments that are nested shell commands. For example, the following is unsafe:

       su %{user} -c 'foo %{file}'

  Instead you can assign the macro to an environment variable and pass that into the call:

       file=%{file} su %{user} -c 'foo "$file"'

#### Windows notes

All quoting syntax supported by `splitArgs()` is supported here as well. Additionally, command grouping via parentheses is recognized – but note that the parser is much stricter about unquoted parentheses than `cmd` itself. The rest of the `cmd` syntax should not cause problems and is ignored.

##### Windows security considerations

- Circumflex-escaping an expando is treated as a quoting error.
- Closing double quotes right before expandos and opening double quotes right after expandos are treated as quoting errors.
- Do not put expandos into nested commands. For example, the following is unsafe:

       for /f "usebackq" \%v in (`foo \%{file}`) do \@echo \%v

- A macro's value must not contain anything which may be interpreted as an environment variable expansion. A solution is replacing any percent signs with a fixed string like `\%PERCENT_SIGN\%` and injecting `PERCENT_SIGN=\%` into the shell's environment.
- Enabling delayed environment variable expansion (`cmd /v:on`) should have no security implications. But it might still cause issues because the parser is not prepared for the fact that literal exclamation marks in the command need to be circumflex-escaped, and pre-existing circumflexes need to be doubled.