const type: popenFile

File implementation type for operating system pipes.

const type: popen8File

File implementation type for UTF-8 encoded operating system pipes.

const func integer: shell (in string: command, in array string: parameters, in string: redirectStdin, in string: redirectStdout, in string: redirectStderr)

Use the shell to execute a command with parameters. Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the shell function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shell function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Array of argument strings passed to the shell command.

redirectStdin - Name of a file to be used as standard input of the shell command. Use "" to do no redirection.

redirectStdout - Name of a file to be used as standard output of the shell command. Use "" to do no redirection.

redirectStderr - Name of a file to be used as standard error output of the shell command. Use "" to do no redirection.

Returns:

the return code of the executed command or of the shell.

const func integer: shell (in string: command, in array string: parameters)

Use the shell to execute a command with parameters. Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the shell function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shell function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Array of argument strings passed to the shell command.

Returns:

the return code of the executed command or of the shell.

const func integer: shell (in string: command, in var string: parameters, in string: redirectStdin, in string: redirectStdout, in string: redirectStderr)

Use the shell to execute a command with parameters. Parameters which contain a space must be either enclosed in double quotes (E.g.: shell("aCmd", "\"do it\" x", "", "", ""); ) or the spaces in the parameter must be preceded by a backslash (E.g.: shell("aCmd", "do\\ it x", "", "", ""); ). Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the shell function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shell function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Space separated list of parameters for the command, or "" if there are no parameters.

redirectStdin - Name of a file to be used as standard input of the shell command. Use "" to do no redirection.

redirectStdout - Name of a file to be used as standard output of the shell command. Use "" to do no redirection.

redirectStderr - Name of a file to be used as standard error output of the shell command. Use "" to do no redirection.

Raises:

FILE_ERROR - The shell command returns an error.

const func integer: shell (in string: command, in string: parameters)

Use the shell to execute a command with parameters. Parameters which contain a space must be either enclosed in double quotes (E.g.: shell("aCommand", "\"do it\" param2"); ) or the spaces in the parameter must be preceded by a backslash (E.g.: shell("aCommand", "do\\ it param2"); ). Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the shell function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shell function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Space separated list of parameters for the command, or "" if there are no parameters.

Raises:

FILE_ERROR - The shell command returns an error.

const func integer: shell (in string: cmdAndParams)

Executes a command using the shell of the operating system. The command path must use the standard path representation. If the command or a parameter contains a space it must be either enclosed in double quotes (E.g.: shell("aCmd \"do it\" par2"); ) or the spaces in the command or parameter must be preceded by a backslash (E.g.: shell("aCommand do\\ it param2"); ). Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the shell function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shell function.

Parameters:

cmdAndParams - Command to be executed and optional space separated list of parameters. Command and parameters must be space separated.

Returns:

the return code of the executed command or of the shell.

const proc: shellCmd (in string: command, in string: parameters)

Use the shell to execute a command with parameters. Parameters which contain a space must be either enclosed in double quotes (E.g.: shell("aCommand", "\"do it\" param2"); ) or the spaces in the parameter must be preceded by a backslash (E.g.: shell("aCommand", "do\\ it param2"); ). Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the shellCmd function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shellCmd function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Space separated list of parameters for the command, or "" if there are no parameters.

Raises:

FILE_ERROR - The shell command returns an error.

const proc: shellCmd (in string: cmdAndParams)

Executes a command using the shell of the operating system. The command path must use the standard path representation. If the command or a parameter contains a space it must be either enclosed in double quotes (E.g.: shell("aCmd \"do it\" par2"); ) or the spaces in the command or parameter must be preceded by a backslash (E.g.: shell("aCommand do\\ it param2"); ). Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the shellCmd function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shellCmd function.

Parameters:

cmdAndParams - Command to be executed and optional space separated list of parameters. Command and parameters must be space separated.

Raises:

FILE_ERROR - The shell command returns an error.

const func string: shellEscape (in string: stri)

Change a string in a way the operating system shell would require. The function adds escape characters or quotations to a string. Note that the functions shell, shellCmd, popen and popen8 already add escape characters and quotations to their command and all their parameters. Don't use shellEscape for the commands and parameters of shell, shellCmd, popen and popen8. This would lead to wrong results.

Returns:

a string which is escaped or quoted in a shell specific way.

Raises:

MEMORY_ERROR - Not enough memory to convert 'stri'.

RANGE_ERROR - An illegal character is in 'stri'.

const func string: toOsPath (in string: standardPath)

Convert a standard path to the path of the operating system. The result can be used as parameter for the functions shell, shellCmd, popen, popen8, startProcess and startPipe. The function toOsPath should only be used for parameters which represent a path. Don't use toOsPath for the command of a shell or process function. Note that shellEscape should never be used for a command or parameter of a shell or process function. Using shellEscape for shell and process functions leads to wrong results.

Parameters:

standardPath - Path in the standard path representation.

Returns:

a string containing an operating system path.

Raises:

MEMORY_ERROR - Not enough memory to convert standardPath.

RANGE_ERROR - standardPath is not representable as operating system path.

const func string: toShellPath (in string: path)

Convert a standard path in a way the operating system shell would require. Note that the functions shell, shellCmd, popen and popen8 already add escape characters and quotations to their command and all their parameters. Don't use toShellPath for the commands and parameters of shell, shellCmd, popen and popen8. This would lead to wrong results. Instead of toShellPath you should use toOsPath for parameters which represent a path.

Parameters:

standardPath - Path in the standard path representation.

Returns:

a string containing an escaped operating system path.

Raises:

MEMORY_ERROR - Not enough memory to convert standardPath.

RANGE_ERROR - standardPath is not representable as operating system path.

const func file: popen (in string: command, in array string: parameters, in string: mode)

Open a pipe to a shell command with parameters. The command reads, respectively writes with Latin-1 encoding. Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the popen function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Array of argument strings passed to the shell command.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - command is not representable as operating system path, or mode is illegal.

const func file: popen (in string: command, in var string: parameters, in string: mode)

Open a pipe to a shell command with parameters. The command reads, respectively writes with Latin-1 encoding. Parameters which contain a space must be either enclosed in double quotes (E.g.: popen("aCommand", "\"do it\" par2", "r"); ) or the spaces in the parameter must be preceded by a backslash (E.g.: popen("aCommand", "do\\ it par2", "r"); ). Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the popen function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Space separated list of parameters for the command, or "" if there are no parameters.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - command is not representable as operating system path, or mode is illegal.

const func file: popen (in string: cmdAndParams, in string: mode)

Open a pipe to a shell command. The command reads, respectively writes with Latin-1 encoding. The command path must use the standard path representation. If the command or a parameter contains a space it must be either enclosed in double quotes (E.g.: popen("aCmd \"do it\" x", "r"); ) or the spaces in the command or parameter must be preceded by a backslash (E.g.: popen("aCommand do\\ it x", "r"); ). Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the popen function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen function.

Parameters:

cmdAndParams - Command to be executed and optional space separated list of parameters. Command and parameters must be space separated.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - The command is not representable as operating system path, or mode is illegal.

const proc: close (in popenFile: aPipe)

Wait for the process associated with aPipe to terminate.

Parameters:

aFile - Pipe to be closed (created by 'popen').

Raises:

FILE_ERROR - A system function returned an error.

const func file: popen8 (in string: command, in array string: parameters, in string: mode)

Open an UTF-8 encoded pipe to a shell command with parameters. The command reads, respectively writes with UTF-8 encoding. Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the popen8 function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen8 function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Array of argument strings passed to the shell command.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - command is not representable as operating system path, or mode is illegal.

const func file: popen8 (in string: command, in var string: parameters, in string: mode)

Open an UTF-8 encoded pipe to a shell command. The command reads, respectively writes with UTF-8 encoding. Parameters which contain a space must be either enclosed in double quotes (E.g.: popen8("aCommand", "\"do it\" par2", "r"); ) or the spaces in the parameter must be preceded by a backslash (E.g.: popen8("aCommand", "do\\ it par2", "r"); ). Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the popen8 function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen8 function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Space separated list of parameters for the command, or "" if there are no parameters.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - command is not representable as operating system path, or mode is illegal.

const func file: popen8 (in string: cmdAndParams, in string: mode)

Open an UTF-8 encoded pipe to a shell command. The command reads, respectively writes with UTF-8 encoding. The command path must use the standard path representation. If the command or a parameter contains a space it must be either enclosed in double quotes (E.g.: popen8("aCmd \"do it\" x", "r"); ) or the spaces in the command or parameter must be preceded by a backslash (E.g.: popen8("aCommand do\\ it x", "r"); ). Escape characters and quotations are added to the command and all parameters before they are forwarded to the operating system shell. This way it is not possible to inject a command in a parameter. The commands supported and the format of the parameters are not covered by the description of the popen8 function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen8 function.

Parameters:

cmdAndParams - Command to be executed and optional space separated list of parameters. Command and parameters must be space separated.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - The command is not representable as operating system path, or mode is illegal.

const proc: close (in popen8File: aPipe)

Wait for the process associated with aPipe to terminate.

Parameters:

aPipe - UTF-8 encoded pipe to be closed (created by 'popen8').

Raises:

FILE_ERROR - A system function returned an error.