# process process library

## Function

process(program) Creates a command builder that supports parameters, environment variables, working directory, stdio configuration, synchronous execution and subprocess handle operations.

## API List

| API | Description |
| ------ | ------ |
| [process.arg](/en/docs/process/arg) | Append a command line argument. |
| [process.args](/en/docs/process/args) | Append command line parameters in batches. |
| [process.env](/en/docs/process/env) | Set a child process environment variable. |
| [process.envs](/en/docs/process/envs) | Set child process environment variables in batches. |
| [process.current_dir](/en/docs/process/current_dir) | Set the working directory of the child process. |
| [process.stdin](/en/docs/process/stdin) | Set the text to be written to the standard input of the child process. |
| [process.inherit_stdio](/en/docs/process/inherit_stdio) | Let the child process inherit the current process stdio. |
| [process.null_stdio](/en/docs/process/null_stdio) | Discard child process stdio. |
| [process.window_hidden](/en/docs/process/window_hidden) | Hide the console child process window under Windows. |
| [process.pipe_limit](/en/docs/process/pipe_limit) | Set the stdout/stderr unread buffer limit of the current Process object. |
| [process.env_clear](/en/docs/process/env_clear) | Clear the inherited environment variables before starting the child process. |
| [process.env_remove](/en/docs/process/env_remove) | Removes a key from a configured environment variable. |
| [process.get_args](/en/docs/process/get_args) | Read the configured parameter array of the current builder. |
| [process.get_current_dir](/en/docs/process/get_current_dir) | Read the current builder working directory configuration. |
| [process.get_envs](/en/docs/process/get_envs) | Read the current builder environment variable configuration. |
| [process.get_program](/en/docs/process/get_program) | Read the current builder program path. |
| [process.status](/en/docs/process/status) | Execute the command synchronously and return the exit code. |
| [process.output](/en/docs/process/output) | Execute the command synchronously and return the output object. |
| [process.child](/en/docs/process/child) | Start the child process and save the handle in the current Process object. |
| [process.pid](/en/docs/process/pid) | Read the PID of the started child process. |
| [process.kill](/en/docs/process/kill) | Kill the started child process. |
| [process.suspend](/en/docs/process/suspend) | Suspend the started child process and its child process tree under Windows. |
| [process.resume](/en/docs/process/resume) | Resume a suspended child process and its child process tree under Windows. |
| [process.wait](/en/docs/process/wait) | Wait for the started child process to exit. |
| [process.try_wait](/en/docs/process/try_wait) | Non-blocking check whether the started child process has exited. |
| [process.stdout](/en/docs/process/stdout) | Read the started subprocess stdout pipe status. |
| [process.stdout_read](/en/docs/process/stdout_read) | Read the currently available text of stdout of a started child process. |
| [process.stdout_read_lines](/en/docs/process/stdout_read_lines) | Read the currently available text of the started subprocess stdout line by line. |
| [process.stderr_read](/en/docs/process/stderr_read) | Read the currently available text of stderr of a started subprocess. |
| [process.stderr_read_lines](/en/docs/process/stderr_read_lines) | Read the currently available text of a started subprocess stderr line by line. |
| [process.child_running](/en/docs/process/child_running) | Determine whether the current Process object saves the child process handle. |

## Examples

```bt
ret = process('cmd').args(['/C', 'echo BT']).output()
result = ret.stdout.trim()

// Output: BT
print result
```

## Notes

- The example uses Windows cmd as an example; Linux/macOS can use sh -c.
- status, output, and wait will block the current process and should be used with caution in resident services.
-Reject status, output, child, wait in the Web request context to avoid synchronously waiting for external processes or forking long-term child processes; for complete rules, see: [Web blocking API policy ](/en/docs/web/io-policy).
- The child process will inherit the BT runtime environment variable overlay; if the current Process object sets a variable with the same name through env/envs, the explicit configuration of the Process object shall prevail.
 - The default non-inherit_stdio() scenario does not inherit the parent process stdin; the child process receives a closed stdin when stdin(text) is not called.
- The default non-inherit_stdio() scenario under Windows will hide the console child process window; call inherit_stdio() when explicit interaction with the console is required.
- child() opens the stdout/stderr pipe by default; inherit_stdio() or null_stdio() will turn off the script-side pipe reading capability.
- Pipe reading uses background threads and bounded unread buffers. The default BT_PROCESS_PIPE_LIMIT is 1048576 bytes, BT_PROCESS_PIPE_READ_CHUNK is 8192 bytes, and BT_PROCESS_PIPE_TIMEOUT_MS is 100 milliseconds; a single Process can be overridden by pipe_limit(bytes).
- Exceeding BT_PROCESS_PIPE_LIMIT or pipe_limit(bytes) will return a runtime error; return empty when the subprocess is not started, there is no corresponding pipe, there is no data within the timeout, or the pipe has been read.
- When the Process object is finally released, it will terminate the still running managed sub-process; under Windows, kill() and release cleanup will try to recursively terminate the sub-process tree.
- suspend()/resume() is for Windows desktop batch processing scenarios, controlling the sub-process tree through thread-level suspension and resumption; Linux/macOS is not supported yet.