Classes

class CurrentProcess ^(deprecated)

public class CurrentProcess <: Process

Description: Specifies the current process class, which inherits from the process class and provides functionalities related to operations on the current process.

The following functionalities are provided:

• Obtains the standard streams (stdIn, stdOut, and stdErr) of the current process.
• Executes a registered callback function when exiting the current process.
• Exits the current process and allows setting the exit status code.

NOTE

This class will be deprecated in future releases.

Parent types:

• Process

prop arguments

public prop arguments: Array<String>

Description: Returns the parameter list of the current process. For example, if the command line of the current process is a.out ab cd ef, in which a.out is the program name, the returned list contains three elements ab, cd, and ef.

NOTE

• When the C language is used to call the Cangjie dynamic library and the arguments property of the current process is used to obtain the command line parameters set by int SetCJCommandLineArgs(int argc, const char* argv[]), the first parameter is discarded.

Type: Array<String>

prop homeDirectory

public prop homeDirectory: Path

Description: Obtains the path of the home directory.

Type: Path

prop stdErr

public prop stdErr: OutputStream

Description: Obtains the standard error stream of the current process.

Type: OutputStream

prop stdIn

public prop stdIn: InputStream

Description: Obtains the standard input stream of the current process.

Type: InputStream

prop stdOut

public prop stdOut: OutputStream

Description: Obtains the standard output stream of the current process.

Type: OutputStream

prop tempDirectory

public prop tempDirectory: Path

Description: Obtains the path of the temporary directory. The values of TMPDIR, TMP, TEMP, and TEMPDIR are obtained from environment variables. If the preceding values do not exist in the environment variables, the /tmp directory is returned by default.

Type: Path

func atExit(() -> Unit)

public func atExit(callback: () -> Unit): Unit

Description: Registers a callback function. The registered function is executed when the current process exits.

NOTE

Do not use the atexit function in the C language to prevent unexpected problems.

Parameters:

• callback: () ->Unit: callback function to be registered

func exit(Int64)

public func exit(code: Int64): Nothing

Description: Specifies a process exit function which directly terminates the current process upon execution and sets the return status code through the input parameter code.

Parameters:

• code: Int64: exit status code of the current process

func getEnv(String)

public func getEnv(k: String): Option<String>

Description: Obtains the value of an environment variable with a specified name.

Parameters:

• k: String: environment variable name

Returns:

• Option<String>: value of the environment variable with the specified name

Throws:

• IllegalArgumentException: If the function parameter k contains null characters, this exception is thrown.

func removeEnv(String)

public func removeEnv(k: String): Unit

Description: Removes an environment variable by specifying its name.

Parameters:

• k: String: environment variable name

Throws:

• IllegalArgumentException: If the function parameter k contains null characters, this exception is thrown.

func setEnv(String, String)

public func setEnv(k: String, v: String): Unit

Description: Sets a pair of environment variables. If an environment variable with the same name is set, the original environment variable value is overwritten.

NOTE

On Windows, if the passed parameter v is an empty string, the variable k will be removed from the environment.

Parameters:

• k: String: environment variable name
• v: String: environment variable value

Throws:

• IllegalArgumentException: If the function parameter k or v contains null characters, this exception is thrown.

class Process

public open class Process

Description: Specifies a process class which provides functionalities related to process operations.

NOTE

The following functionalities are provided:

• Obtains the current process instance.
• Binds process instances based on process id.
• Creates a subprocess based on the input information.
• Obtains process information.
• Stops a process and allows setting whether to forcibly stop the process.

static prop current ^(deprecated)

public static prop current: CurrentProcess

Description: Obtains the current process instance.

NOTE

This property will be deprecated in future releases and the global function of the env package will be used instead.

Type: CurrentProcess

prop arguments ^(deprecated)

public open prop arguments: Array<String>

Description: Obtains the process parameters. This property cannot be obtained in non-privileged API mode on Windows.

NOTE

This property will be deprecated in future releases.

Type: Array<String>

Throws:

• ProcessException: If the process parameters cannot be obtained because the process does not exist, the process is a zombie process, or the scenario is not supported on Windows, this exception is thrown.

prop command

public prop command: String

Description: Obtains the process command.

Type: String

Throws:

• ProcessException: If the process command cannot be obtained because the process does not exist or the process is a zombie process, this exception is thrown.

prop commandLine ^(deprecated)

public prop commandLine: Array<String>

Description: Obtains the process command line. This property of the current process can be obtained on Windows. In other scenarios, this property cannot be obtained in non-privileged API mode.

NOTE

This property will be deprecated in future releases and getcommandline() will be used instead.

Type: Array<String>

Throws:

• ProcessException: If the process command line cannot be obtained because the process does not exist, the process is a zombie process, or the scenario is not supported on Windows, this exception is thrown.

prop environment ^(deprecated)

public prop environment: Map<String, String>

Description: Obtains the environment variables of a process. This property of the current process can be obtained on Windows. In other scenarios, this property cannot be obtained in non-privileged API mode.

NOTE

This property will be deprecated in future releases and getVariables() will be used instead.

Type: Map<String, String>

Throws:

• ProcessException: If the environment variables of a process cannot be obtained because the process does not exist, the process is a zombie process, or the scenario is not supported on Windows, this exception is thrown.

prop name

public prop name: String

Description: Obtains the process name.

Type: String

Throws:

• ProcessException: If the process name cannot be obtained because the process does not exist or the process is a zombie process, this exception is thrown.

prop pid

public prop pid: Int64

Description: Obtains the process id.

Type: Int64

prop startTime

public prop startTime: DateTime

Description: Obtains the process start time. If the obtaining fails, DateTime.UnixEpoch is returned.

Type: DateTime

prop systemTime

public prop systemTime: Duration

Description: Obtains the process start time. If the time fails to be obtained, -1ms is returned.

Type: Duration

prop userTime

public prop userTime: Duration

Description: Obtains the process start time. If the time fails to be obtained, -1ms is returned.

Type: Duration

prop workingDirectory ^(deprecated)

public prop workingDirectory: Path

Description: Obtains the working path of a process. This property of the current process can be obtained on Windows. In other scenarios, this property cannot be obtained in non-privileged API mode.

NOTE

This property will be deprecated in future releases and getHomeDirectory() will be used instead.

Type: Path

Throws:

• ProcessException: If the working path of a process cannot be obtained because the process does not exist, the process is a zombie process, or the scenario is not supported on Windows, this exception is thrown.

func isAlive()

public func isAlive(): Bool

Description: Returns the process status (alive or not).

Returns:

• Bool: If the process is alive, the value is true. Otherwise, the value is false.

static func of(Int64) ^(deprecated)

public static func of(pid: Int64): Process

Description: Binds a process instance based on the input process id.

NOTE

This function will be deprecated in future releases and findProcess will be used instead.

Parameters:

• pid: Int64: process id

Returns:

• Process: process instance corresponding to the process id

Throws:

• IllegalArgumentException: If the input process id is greater than the maximum value of Int32 or less than 0, this exception is thrown.
• ProcessException: If memory allocation fails or the process specified by pid does not exist, this exception is thrown.

static func run(String, Array<String>, ?Path, ?Map<String, String>, ProcessRedirect, ProcessRedirect,ProcessRedirect, ?Duration) ^(deprecated)

public static func run(command: String,
                      arguments: Array<String>,
                      workingDirectory!: ?Path = None,
                      environment!: ?Map<String, String> = None,
                      stdIn!: ProcessRedirect = Inherit,
                      stdOut!: ProcessRedirect = Inherit,
                      stdErr!: ProcessRedirect = Inherit,
                      timeout!: ?Duration = None): Int64

Description: Creates and runs a subprocess based on input parameters, waits until the subprocess is complete, and returns the exit status of the subprocess.

NOTE

• This function will be deprecated in future releases and execute will be used instead.
• On Windows, if the executable file of a subprocess is deleted immediately after the subprocess is executed, the deletion may fail and an exception is thrown. The exception information is Access is denied. If this problem occurs, the file can be deleted again after a short delay. For details, see the example.

Parameters:

• command: String: subprocess command. The value of command cannot contain null characters.
• arguments: Array<String>: subprocess parameters. The strings in the arguments array cannot contain null characters.
• workingDirectory!: ?Path: a named optional parameter specifying the working path of the subprocess, which inherits the working path of the current process by default. The path must exist and cannot be empty or contain null characters.
• environment!: ?Map<String, String>: a named optional parameter specifying the environment variables of the subprocess, which inherit the environment variables of the current process by default. The key string cannot contain null characters or '=', and the value string cannot contain null characters.
• stdIn!: ProcessRedirect: a named optional parameter specifying the redirected standard input of the subprocess, which inherits the standard input of the current process by default.
• stdOut!: ProcessRedirect: a named optional parameter specifying the redirected standard output of the subprocess, which inherits the standard output of the current process by default.
• stdErr!: ProcessRedirect: a named optional parameter specifying the redirected standard error of the subprocess, which inherits the standard error of the current process by default.
• timeout!: ?Duration: a named optional parameter specifying the timeout interval for waiting for the subprocess to complete. The default setting is no timeout. When timeout is set to 0 or a negative value, no timeout occurs.

Returns:

• Int64: exit status of the subprocess. If the subprocess exits normally, the exit code of the subprocess is returned. If the subprocess is killed by a signal, the number of the signal that causes the subprocess to terminate is returned.

Throws:

• IllegalArgumentException: This exception is thrown when the input parameter command contains null characters, the string in the arguments array contains null characters, workingDirectory does not exist, is an empty path, or contains null characters, the key string in the environment table contains null characters or '=', the value string contains null characters, or the stdIn, stdOut, and stdErr input is in file mode and the input file has been closed or deleted.
• ProcessException: If memory allocation fails, the command specified by command does not exist, or the waiting times out, this exception is thrown.

static func runOutput(String, Array<String>, ?Path, ?Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect) ^(deprecated)

public static func runOutput(command: String,
                            arguments: Array<String>,
                            workingDirectory!: ?Path = None,
                            environment!: ?Map<String, String> = None,
                            stdIn!: ProcessRedirect = Inherit,
                            stdOut!: ProcessRedirect = Pipe,
                            stdErr!: ProcessRedirect = Pipe): (Int64, Array<Byte>, Array<Byte>)

Description: Creates and runs a subprocess based on input parameters, waits until the subprocess is complete, and returns the exit status, standard output, and standard error of the subprocess. This function is not applicable to the scenario where the output stream and error stream contain a large amount of output. It is recommended that the standard stream properties provided in SubProcess and the wait function be used together to process the output stream and error stream.

NOTE

This function will be deprecated in future releases and executeWithOutput will be used instead.

Parameters:

• command: String: subprocess command. The value of command cannot contain null characters.
• arguments: Array<String>: subprocess parameters. The strings in the arguments array cannot contain null characters.
• workingDirectory!: ?Path: a named optional parameter specifying the working path of the subprocess, which inherits the working path of the current process by default. The path must exist and cannot be empty or contain null characters.
• environment!: ?Map<String, String>: a named optional parameter specifying the environment variables of the subprocess, which inherit the environment variables of the current process by default. The key string cannot contain null characters or '=', and the value string cannot contain null characters.
• stdIn!: ProcessRedirect: a named optional parameter specifying the redirected standard input of the subprocess, which inherits the standard input of the current process by default.
• stdOut!: ProcessRedirect: a named optional parameter specifying the redirected standard output of the subprocess, which inherits the standard output of the current process by default.
• stdErr!: ProcessRedirect: a named optional parameter specifying the redirected standard error of the subprocess, which inherits the standard error of the current process by default.

Returns:

• (Int64, Array<Byte>, Array<Byte>): subprocess execution result, including the subprocess exit status (if the subprocess exits normally, the exit code of the subprocess is returned; if the subprocess is killed by a signal, the number of the signal that causes the subprocess to terminate is returned), standard process output result, and process error result.

Throws:

• IllegalArgumentException: This exception is thrown when the input parameter command contains null characters, the string in the arguments array contains null characters, workingDirectory does not exist, is an empty path, or contains null characters, the key string in the environment table contains null characters or '=', the value string contains null characters, or the stdIn, stdOut, and stdErr input is in file mode and the input file has been closed or deleted.
• ProcessException: If memory allocation fails, the command specified by command does not exist, the subprocess does not exist, or an error occurs when the standard stream is read, this exception is thrown.

static func start(String, Array<String>, ?Path, ?Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect) ^(deprecated)

public static func start(command: String,
                        arguments: Array<String>,
                        workingDirectory!: ?Path = None,
                        environment!: ?Map<String, String> = None,
                        stdIn!: ProcessRedirect = Inherit,
                        stdOut!: ProcessRedirect = Inherit,
                        stdErr!: ProcessRedirect = Inherit): SubProcess

Description: Creates and runs a subprocess based on input parameters and returns a subprocess instance. After this function is called to create a subprocess, the wait or waitOutput function needs to be called. Otherwise, the resources of the zombie process formed after the subprocess ends will not be reclaimed.

NOTE

This function will be deprecated in future releases and launch will be used instead.

Parameters:

• command: String: subprocess command. The value of command cannot contain null characters.
• arguments: Array<String>: subprocess parameters. The strings in the arguments array cannot contain null characters.
• workingDirectory!: ?Path: a named optional parameter specifying the working path of the subprocess, which inherits the working path of the current process by default. The path must exist and cannot be empty or contain null characters.
• environment!: ?Map<String, String>: a named optional parameter specifying the environment variables of the subprocess, which inherit the environment variables of the current process by default. The key string cannot contain null characters or '=', and the value string cannot contain null characters.
• stdIn!: ProcessRedirect: a named optional parameter specifying the redirected standard input of the subprocess, which inherits the standard input of the current process by default.
• stdOut!: ProcessRedirect: a named optional parameter specifying the redirected standard output of the subprocess, which inherits the standard output of the current process by default.
• stdErr!: ProcessRedirect: a named optional parameter specifying the redirected standard error of the subprocess, which inherits the standard error of the current process by default.

Returns:

• SubProcess: a subprocess instance

Throws:

• IllegalArgumentException: This exception is thrown when the input parameter command contains null characters, the string in the arguments array contains null characters, workingDirectory does not exist, is an empty path, or contains null characters, the key string in the environment table contains null characters or '=', the value string contains null characters, or the stdIn, stdOut, and stdErr input is in file mode and the input file has been closed or deleted.
• ProcessException: If memory allocation fails or the command specified by command does not exist, this exception is thrown.

func terminate(Bool)

public func terminate(force!: Bool = false): Unit

Description: Terminates a process and returns the subprocess execution result, including the subprocess exit status (if the subprocess exits normally, the exit code of the subprocess is returned; if the subprocess is killed by a signal, the number of the signal that causes the subprocess to terminate is returned), standard process output result, and process error result.

Parameters:

• force!: Bool: a named optional parameter specifying whether to forcibly stop a process. The default value is false. If this parameter is set to false, the process can be stopped after resources are released. If this parameter is set to true, the process is directly killed. On Windows, the process is forcibly stopped.

Throws:

• ProcessException: If the process does not exist and cannot be terminated, this exception is thrown.

func terminateAliveProcess(Int32, Bool)

protected open func terminateAliveProcess(pid: Int32, force: Bool): Unit

Description: Terminates a specified process and returns the subprocess execution result, including the subprocess exit status (if the subprocess exits normally, the exit code of the subprocess is returned; if the subprocess is killed by a signal, the number of the signal that causes the subprocess to terminate is returned), standard process output result, and process error result.

Parameters:

• pid: Int32: ID of the process to be terminated

• force!: Bool: a named optional parameter specifying whether to forcibly stop a process. The default value is false. If this parameter is set to false, the process can be stopped after resources are released. If this parameter is set to true, the process is directly killed. On Windows, the process is forcibly stopped.

Throws:

• ProcessException: If the process does not exist and cannot be terminated, this exception is thrown.

class SubProcess

public class SubProcess <: Process

Description: Specifies the subprocess class, which inherits from the process class and provides functionalities related to operations on the subprocess.

NOTE

The following functionalities are provided:

• Obtains the standard streams (stdIn, stdOut, and stdErr) of the subprocess.
• Waits for the subprocess to return the exit status code after execution, and allows setting the waiting timeout interval.
• Waits for the subprocess to return the output result (including normal running and exception) after execution, and allows setting the waiting timeout interval.

Parent types:

• Process

prop stdErr ^(deprecated)

public prop stdErr: InputStream

Description: Obtains the input stream and connects it to the standard error stream of the subprocess.

NOTE

This property will be deprecated in future releases and stdErrPipe will be used instead.

Type: InputStream

prop stdErrPipe

public prop stdErrPipe: InputStream

Description: Obtains the input stream and connects it to the standard error stream of the subprocess.

Type: InputStream

prop stdIn ^(deprecated)

public prop stdIn: OutputStream

Description: Obtains the output stream and connects it to the standard input stream of the subprocess.

NOTE

This property will be deprecated in future releases and stdInPipe will be used instead.

Type: OutputStream

prop stdInPipe

public prop stdInPipe: OutputStream

Description: Obtains the output stream and connects it to the standard input stream of the subprocess.

Type: OutputStream

prop stdOut ^(deprecated)

public prop stdOut: InputStream

Description: Obtains the input stream and connects it to the standard output stream of the subprocess.

NOTE

This property will be deprecated in future releases and stdOutPipe will be used instead.

Type: InputStream

prop stdOutPipe

public prop stdOutPipe: InputStream

Description: Obtains the input stream and connects it to the standard output stream of the subprocess.

Type: InputStream

func wait(?Duration)

public func wait(timeout!: ?Duration = None): Int64

Description: Blocks the current process until the subprocess task is complete, returns the exit status code of the subprocess, and allows setting the waiting timeout interval. In the scenarios where operations on standard streams are required (in pipe mode), the standard streams need to be processed first to prevent deadlock when this function is called after the standard stream buffer of the subprocess is full.

NOTE

Timeout processing mechanism:

• If no parameter is passed, the value of timeout is None, or the value is less than or equal to Duration.Zero, the current process is blocked until the subprocess execution result is returned.
• If the value of timeout is greater than Duration.Zero, the current process is blocked until the subprocess execution result is returned or a timeout exception is thrown after the waiting times out.

Parameters:

• timeout!: ?Duration: a named optional parameter specifying the timeout interval for waiting for the subprocess to complete. The default value is None.

Returns:

• Int64: subprocess exit status If the subprocess exits normally, the exit code of the subprocess is returned. If the subprocess is killed by a signal, the number of the signal that causes the subprocess to terminate is returned.

Throws:

• TimeoutException: If the waiting times out and the subprocess does not exit, this exception is thrown.

func waitOutput()

public func waitOutput(): (Int64, Array<Byte>, Array<Byte>)

Description: Blocks the current process until the subprocess task is complete, and returns the exit status code and execution result (including the output stream and error stream) of the subprocess. This function is not applicable to the scenario where the output stream and error stream contain a large amount of output. It is recommended that the standard stream properties provided in SubProcess and the wait function be used together to process the output stream and error stream.

Returns:

• (Int64, Array<Byte>, Array<Byte>): subprocess execution result, including the subprocess exit status (if the subprocess exits normally, the exit code of the subprocess is returned; if the subprocess is killed by a signal, the number of the signal that causes the subprocess to terminate is returned), standard process output result, and process error result.

Throws:

• ProcessException: If the subprocess does not exist or an error occurs when the standard stream is read, this exception is thrown.