# Builtin - 进程

## `dbglocalcancel(id)`

声明：function

注销任务。该功能可以用来终止运行的WEB任务。

| 参数 | 类型    | 说明                                                              |
| ---- | ------- | ----------------------------------------------------------------- |
| `id` | integer | 为dbglocalrunning中返回信息中的id字段以十六进制模式转换为64位整数 |

返回：bool

### 示例

范例01：尝试注销指定的本地任务

```tsl
echo dbglocalcancel(0), "\n";
```

## `dbglocalrunning()`

声明：function

获得当前所有的任务列表以及堆栈信息，主要用于web等检查在运行中的任务。

返回：array,tablearray

### 示例

范例01：读取本地任务数量

```tsl
echo length(dbglocalrunning()), "\n";
```

## `sleep(milliseconds)`

声明：function

暂停执行。

| 参数           | 类型    | 说明                                                |
| -------------- | ------- | --------------------------------------------------- |
| `milliseconds` | integer | 整数，需要暂停的毫秒数。例如暂停一秒为Sleep(1000)。 |

返回：nil

### 示例

范例01：短暂暂停当前脚本

```tsl
echo "before\n";
sleep(10);
echo "after\n";
```

## `sysCloseHandle(handle)`

声明：function

关闭一个句柄，如互斥锁，文件句柄等。

| 参数     | 类型    | 说明           |
| -------- | ------- | -------------- |
| `handle` | integer | 整数，句柄编号 |

返回：bool

### 示例

范例01：关闭当前进程的临时句柄

```tsl
handle := sysHandleOfPid(sysProcessId(), 4096, 0);
echo sysCloseHandle(handle), "\n";
```

## `sysCmdLine()`

声明：function

获得解析器的真实命令行串。

返回：string

### 示例

范例01：读取当前解析器命令行

```tsl
echo sysCmdLine(), "\n";
```

## `sysCreateMutex(mutex_name)`

声明：function

创建一个互斥锁。

| 参数         | 类型   | 说明               |
| ------------ | ------ | ------------------ |
| `mutex_name` | string | 字符串，互斥锁名称 |

返回：integer

### 示例

范例01：创建并释放互斥锁

```tsl
mutex := sysCreateMutex("tsl-doc-create-mutex");
echo mutex, "\n";
sysReleaseMutex(mutex);
```

## `sysErrorMessage(code)`

声明：function

返回指定代码表示的系统错误信息。

| 参数   | 类型    | 说明           |
| ------ | ------- | -------------- |
| `code` | integer | 整数，提示代码 |

返回：string

### 示例

范例01：读取系统错误码对应的消息

```tsl
echo sysErrorMessage(2), "\n";
```

## `sysExec(prog, cmd_line, startup_dir, wait_exit, var return_code[, wait_ms])`

声明：function

创建子进程。wait_exit 为真时等待进程退出并写回退出码；wait_ms 可省略。返回的进程句柄使用后应关闭。

| 参数          | 类型           | 说明                                   |
| ------------- | -------------- | -------------------------------------- |
| `prog`        | string         | 可执行文件路径。                       |
| `cmd_line`    | string\|array  | 命令行字符串或参数数组。               |
| `startup_dir` | string\|nil    | 子进程工作目录。                       |
| `wait_exit`   | boolean\|array | 是否等待子进程退出，也可传入管道选项。 |
| `return_code` | integer\|array | 写回子进程退出码或管道输出。           |
| `wait_ms`     | integer        | 可选等待时间，单位为毫秒。             |

返回：integer

### 示例

范例01：基本用法

```tsl
pos := 0;
source := "value := 1;";
writeFile(rwRaw(), "", "child.tsl", pos, length(source), source);
exe_path := sysExecName();
handle := sysExec(exe_path, array(exe_path, "child.tsl"), nil, true, exit_code);
echo handle > 0 and exit_code = 0, "\n";
// 输出：1
sysCloseHandle(handle);
fileDelete("", "child.tsl");
```

## `sysexecdeletepipe(process_handle)`

声明：function

删除指定进程的管道。参数缺省时，删除默认管道。

| 参数             | 类型 | 说明                   |
| ---------------- | ---- | ---------------------- |
| `process_handle` |      | 可选。数值，进程句柄。 |

返回：bool

### 示例

范例01：删除当前脚本创建的默认管道

```tsl
sysExecNewPipe(0);
echo sysExecDeletePipe(), "\n";
```

## `sysexecGetenvs()`

声明：function

获取子进程的环境变量，应用于Sysexec创建的子进程。

返回：array of string

### 示例

范例01：读取为子进程准备的环境变量

```tsl
sysExecSetEnvs(array("TSL_DOC_CHILD=value"), 2);
echo toStn(sysexecGetenvs()), "\n";
```

## `sysexecnewpipe(flag)`

声明：function

创建Sysexec进程的管道。参数缺省时，默认创建读写管道。创建之后会与第一次被用的进程进行绑定，当有多个Sysexec进程时，可以创建多个管道分别进行读写操作。

| 参数   | 类型    | 说明                                                                                             |
| ------ | ------- | ------------------------------------------------------------------------------------------------ |
| `flag` | integer | 可选。整数，控制创建管道的读写属性。Flag转换为二进制时，第0位表示是否可读，第1位表示是否可写。即 |

返回：bool

### 示例

范例01：创建并删除默认读写管道

```tsl
ok := sysExecNewPipe(0);
echo ok, "\n";
sysExecDeletePipe();
```

## `sysExecReadPipe([process_handle])`

声明：function

读取 SysExec 子进程的管道输出；process_handle 可省略，省略时读取默认管道。

| 参数             | 类型    | 说明             |
| ---------------- | ------- | ---------------- |
| `process_handle` | integer | 可选子进程句柄。 |

返回：string

### 示例

范例01：基本用法

```tsl
pos := 0;
source := 'sleep(100); echo "pipe-output";';
writeFile(rwRaw(), "", "child.tsl", pos, length(source), source);
sysExecNewPipe(0);
exe_path := sysExecName();
handle := sysExec(exe_path, array(exe_path, "child.tsl"), nil, false, exit_code);
output := "";
while output = "" do
begin
    output := sysExecReadPipe(handle);
    sleep(50);
end
echo trim(output), "\n";
// 输出：pipe-output
sysExecDeletePipe(handle);
sysCloseHandle(handle);
fileDelete("", "child.tsl");
```

## `sysExecSetEnvs(envs, add_system_env)`

声明：function

设置后续 SysExec 子进程使用的环境变量。add_system_env 为 0 时不合并系统环境，1 时追加系统环境，2 时将系统环境置于其后。

| 参数             | 类型       | 说明                                       |
| ---------------- | ---------- | ------------------------------------------ |
| `envs`           | array\|nil | 环境变量数组；nil 清除已设置的子进程环境。 |
| `add_system_env` | integer    | 系统环境变量的合并方式：0、1 或 2。        |

返回：integer

### 示例

范例01：基本用法

```tsl
result := sysExecSetEnvs(array("TSL_DOC_CHILD=value"), 2);
envs := sysExecGetEnvs();
echo result = 0 and pos("TSL_DOC_CHILD=value", toStn(envs)) > 0, "\n";
// 输出：1
sysExecSetEnvs(nil, 0);
```

## `sysExecWritePipe([process_handle,] content)`

声明：function

向 SysExec 子进程的管道写入内容；process_handle 可省略，省略时写入默认管道。成功时返回写入长度，失败时返回 -1。

| 参数             | 类型           | 说明             |
| ---------------- | -------------- | ---------------- |
| `process_handle` | integer        | 可选子进程句柄。 |
| `content`        | string\|binary | 请求或管道内容。 |

返回：integer

### 示例

范例01：基本用法

```tsl
sysExecNewPipe(0);
handle := sysExec("/bin/cat", "", nil, false, exit_code);
written := sysExecWritePipe(handle, "pipe-input\n");
sleep(100);
output := sysExecReadPipe(handle);
echo written > 0 and trim(output) = "pipe-input", "\n";
// 输出：1
sysTerminate(0, handle);
sysExecDeletePipe(handle);
sysCloseHandle(handle);
```

## `sysgetenv(name)`

声明：function

获取当前运行环境下指定环境变量的值。

| 参数   | 类型   | 说明                 |
| ------ | ------ | -------------------- |
| `name` | string | 字符串，环境变量名。 |

返回：string

### 示例

范例01：读取当前进程的环境变量

```tsl
sysputenv("TSL_DOC_EXAMPLE=value");
echo sysgetenv("TSL_DOC_EXAMPLE"), "\n";
```

## `sysGetenvs()`

声明：function

获取当前运行环境的全部环境变量串。

返回：array of string

### 示例

范例01：读取当前进程的环境变量数量

```tsl
echo length(sysGetenvs()), "\n";
```

## `sysGetLastError()`

声明：function

获得系统操作的最后一个返回代码。

返回：integer

### 示例

范例01：读取最近一次系统操作的错误码

```tsl
echo sysGetLastError(), "\n";
```

## `sysGetProcessCmdLine(pid)`

声明：function

取得指定进程的命令行；失败时返回空字符串。

| 参数  | 类型    | 说明      |
| ----- | ------- | --------- |
| `pid` | integer | 进程 ID。 |

返回：string

### 示例

范例01：基本用法

```tsl
echo length(sysGetProcessCmdLine(sysProcessId())) > 0, "\n";
// 输出：1
```

## `sysGetProcessCmdLinew(pid)`

声明：function

取得指定进程的宽字符串命令行；失败时返回空字符串。

| 参数  | 类型    | 说明      |
| ----- | ------- | --------- |
| `pid` | integer | 进程 ID。 |

返回：string

### 示例

范例01：基本用法

```tsl
echo length(sysGetProcessCmdLinew(sysProcessId())) > 0, "\n";
// 输出：1
```

## `sysGetProcessList()`

声明：function

获取当前进程列表信息

返回：array,tablearray

### 示例

范例01：读取当前进程列表数量

```tsl
echo length(sysGetProcessList()), "\n";
```

## `sysGetProcessListw()`

声明：function

获取当前进程列表信息，信息中字符串为宽字节字符串

返回：array,tablearray

### 示例

范例01：读取宽字符串进程列表数量

```tsl
echo length(sysGetProcessListw()), "\n";
```

## `sysGetProcessNamePath(pid)`

声明：function

取得指定进程的可执行文件路径；无法取得路径时返回进程名，失败时返回空字符串。

| 参数  | 类型    | 说明      |
| ----- | ------- | --------- |
| `pid` | integer | 进程 ID。 |

返回：string

### 示例

范例01：基本用法

```tsl
echo length(sysGetProcessNamePath(sysProcessId())) > 0, "\n";
// 输出：1
```

## `sysGetProcessNamePathw(pid)`

声明：function

取得指定进程的宽字符串可执行文件路径；失败时返回空字符串。

| 参数  | 类型    | 说明      |
| ----- | ------- | --------- |
| `pid` | integer | 进程 ID。 |

返回：string

### 示例

范例01：基本用法

```tsl
echo length(sysGetProcessNamePathw(sysProcessId())) > 0, "\n";
// 输出：1
```

## `sysGetProcessPriority(var priority[, pid])`

声明：function

取得进程优先级并写入 priority。pid 可省略，缺省为当前进程；成功返回 0。

| 参数       | 类型    | 说明                           |
| ---------- | ------- | ------------------------------ |
| `priority` | integer | 进程优先级；读取时为写回参数。 |
| `pid`      | integer | 进程 ID。                      |

返回：integer

### 示例

范例01：基本用法

```tsl
result := sysGetProcessPriority(priority);
echo result = 0, "\n";
// 输出：1
```

## `sysGetSubProcesses(pid)`

声明：function

获得进程的子进程列表

| 参数  | 类型    | 说明                                                       |
| ----- | ------- | ---------------------------------------------------------- |
| `pid` | integer | 可选。整数，进程ID。未指定时默认获取当前进程内的子进程列表 |

返回：array,tablearray

### 示例

范例01：读取当前进程的子进程列表

```tsl
echo toStn(sysGetSubProcesses(sysProcessId())), "\n";
```

## `sysGetThreadName(tid)`

声明：function

获取线程名称

| 参数  | 类型    | 说明                                             |
| ----- | ------- | ------------------------------------------------ |
| `tid` | integer | 可选。整数，线程ID。未指定时默认获取当前线程名称 |

返回：string

### 示例

范例01：读取当前线程名称

```tsl
sysSetThreadName("TslDocExample");
echo sysGetThreadName(), "\n";
```

## `sysGetThreadPriority(pri, tid)`

声明：function

获取线程优先级

| 参数  | 类型    | 说明                                               |
| ----- | ------- | -------------------------------------------------- |
| `pri` | integer | 变参，整数，线程优先级                             |
| `tid` | integer | 可选。整数，线程ID。未指定时默认获取当前线程优先级 |

返回：integer

### 示例

范例01：读取当前线程优先级

```tsl
status := sysGetThreadPriority(priority);
echo status, ":", priority, "\n";
```

## `sysGetThreads(pid)`

声明：function

获取进程内的线程列表

| 参数  | 类型    | 说明                                                     |
| ----- | ------- | -------------------------------------------------------- |
| `pid` | integer | 可选。整数，进程ID。未指定时默认获取当前进程内的线程列表 |

返回：array,tablearray

### 示例

范例01：读取当前进程的线程列表

```tsl
echo toStn(sysGetThreads(sysProcessId())), "\n";
```

## `sysHandleOfPid(pid, rights, inherithandle)`

声明：function

Windows上获取进程id对应的句柄，Linux上获取指定文件ID的复制ID。得到的句柄可用函数FAQ：SysCloseHandle进行关闭。

| 参数            | 类型    | 说明                                                                |
| --------------- | ------- | ------------------------------------------------------------------- |
| `pid`           | integer | 整数，进程ID                                                        |
| `rights`        | integer | 可选。整数，设置进程句柄权限，Linux上无效。常见的权限设置值见下表。 |
| `inherithandle` | integer | 可选。布尔值，是否继承，Linux上无效                                 |

常见权限值：

| 值       | 十进制值 | 访问权限                                    | 可操作范围                            |
| -------- | -------- | ------------------------------------------- | ------------------------------------- |
| `0x0010` | 16       | PROCESS_VM_READ                             | 读取进程内存内容                      |
| `0x0400` | 1024     | PROCESS_QUERY_INFORMATION                   | 查询完整进程信息（令牌、优先级等）    |
| `0x1000` | 4096     | PROCESS_QUERY_LIMITED_INFORMATION（缺省值） | 仅查询进程基础信息（PID、退出代码等） |
| `0xFFFF` | 65535    | PROCESS_ALL_ACCESS                          | 所有权限（包括终止、内存写入等）      |

返回：integer

### 示例

范例01：获取并关闭当前进程句柄

```tsl
handle := sysHandleOfPid(sysProcessId(), 4096, 0);
echo handle, "\n";
sysCloseHandle(handle);
```

## `sysKill(pid[, code])`

声明：function

按进程 ID 终止进程。code 可省略，用于指定进程退出码。

| 参数   | 类型    | 说明               |
| ------ | ------- | ------------------ |
| `pid`  | integer | 进程 ID。          |
| `code` | integer | 可选子进程退出码。 |

返回：boolean

### 示例

范例01：基本用法

```tsl
exe_path := sysExecName();
handle := sysExec(exe_path, array(exe_path, "tsl"), nil, false, exit_code);
pid := sysPidOfHandle(handle);
killed := sysKill(pid, 0);
echo handle > 0 and pid > 0 and killed, "\n";
// 输出：1
sysCloseHandle(handle);
```

## `syslinuxkrnlclosemutex(name, isprivate)`

声明：function

支持在LINUX上手动删除掉因互斥支持产生的系统信号量以及临时目录的文件

| 参数        | 类型   | 说明               |
| ----------- | ------ | ------------------ |
| `name`      | string | 字符串，互斥锁名称 |
| `isprivate` | bool   | 是否私有           |

返回：any

### 示例

范例01：清理当前脚本创建的 Linux 互斥锁

```tsl
mutex_name := "tsl-doc-linux-mutex";
mutex := sysCreateMutex(mutex_name);
sysReleaseMutex(mutex);
echo syslinuxkrnlclosemutex(mutex_name, 0), "\n";
```

## `sysParamcount()`

声明：function

获得命令行参数个数。（不包括执行的自身.TSL参数）

返回：integer

### 示例

范例01：读取额外命令行参数数量

```tsl
echo sysParamcount(), "\n";
```

## `sysParamStr(index)`

声明：function

获得命令行的指定索引的参数值。

| 参数    | 类型 | 说明                                                                                                                   |
| ------- | ---- | ---------------------------------------------------------------------------------------------------------------------- |
| `index` |      | 整数，命令行参数的索引号。Index=0，返回值为当前天软脚本文件名称；Index>0，返回值为额外传入的命令行参数值（字符串类型） |

返回：string

### 示例

范例01：读取当前脚本文件名参数

```tsl
echo sysParamStr(0), "\n";
```

## `sysPidOfHandle(handle)`

声明：function

根据进程句柄获取进程ID。在Linux上，返回和进程句柄值相同的整数

| 参数     | 类型    | 说明     |
| -------- | ------- | -------- |
| `handle` | integer | 进程句柄 |

返回：integer

### 示例

范例01：从当前进程句柄读取进程 ID

```tsl
handle := sysHandleOfPid(sysProcessId(), 4096, 0);
echo sysPidOfHandle(handle), "\n";
sysCloseHandle(handle);
```

## `sysPidOfTid(tid)`

声明：function

获取线程所属进程ID

| 参数  | 类型    | 说明         |
| ----- | ------- | ------------ |
| `tid` | integer | 整数，线程ID |

返回：integer

### 示例

范例01：读取当前线程所属的进程 ID

```tsl
echo sysPidOfTid(sysThreadId()), "\n";
```

## `sysPPid(pid)`

声明：function

获得进程的父进程ID

| 参数  | 类型    | 说明                                                   |
| ----- | ------- | ------------------------------------------------------ |
| `pid` | integer | 可选。整数，进程ID。未指定时默认获取当前进程的父进程ID |

返回：integer

### 示例

范例01：读取当前进程的父进程 ID

```tsl
echo sysPPid(sysProcessId()), "\n";
```

## `sysProcessId()`

声明：function

获得运行的进程ID。

返回：integer

### 示例

范例01：读取当前进程 ID

```tsl
echo sysProcessId(), "\n";
```

## `sysputenv(env_value)`

声明：function

设置当前运行环境的指定环境变量的值。

| 参数        | 类型   | 说明                        |
| ----------- | ------ | --------------------------- |
| `env_value` | string | 字符串，环境变量名=变量值。 |

返回：integer

### 示例

范例01：设置当前进程的环境变量

```tsl
sysputenv("TSL_DOC_EXAMPLE=value");
echo sysgetenv("TSL_DOC_EXAMPLE"), "\n";
```

## `sysReleaseMutex(mutex)`

声明：function

释放一个互斥锁。

| 参数    | 类型    | 说明             |
| ------- | ------- | ---------------- |
| `mutex` | integer | 整数，互斥锁编号 |

返回：bool

### 示例

范例01：释放当前脚本创建的互斥锁

```tsl
mutex := sysCreateMutex("tsl-doc-release-mutex");
echo sysReleaseMutex(mutex), "\n";
```

## `sysSetProcessPriority(priority[, pid])`

声明：function

设置进程优先级。pid 可省略，缺省为当前进程；成功返回 0。

| 参数       | 类型    | 说明                           |
| ---------- | ------- | ------------------------------ |
| `priority` | integer | 进程优先级；读取时为写回参数。 |
| `pid`      | integer | 进程 ID。                      |

返回：integer

### 示例

范例01：基本用法

```tsl
get_result := sysGetProcessPriority(priority);
set_result := sysSetProcessPriority(priority);
echo get_result = 0 and set_result = 0, "\n";
// 输出：1
```

## `sysSetThreadName(name, tid)`

声明：function

设置线程名称

| 参数   | 类型    | 说明                                             |
| ------ | ------- | ------------------------------------------------ |
| `name` | string  | 字符串，要设置的名称                             |
| `tid`  | integer | 可选。整数，线程ID。未指定时默认设置当前线程名称 |

返回：integer

### 示例

范例01：设置当前线程名称

```tsl
status := sysSetThreadName("TslDocExample");
echo status, ":", sysGetThreadName(), "\n";
```

## `sysSetThreadPriority(pri, tid)`

声明：function

设置线程优先级

| 参数  | 类型    | 说明                                         |
| ----- | ------- | -------------------------------------------- |
| `pri` | integer | 线程优先级                                   |
| `tid` | integer | 可选。线程ID。未指定时默认设置当前线程优先级 |

返回：integer

### 示例

范例01：将当前线程保持为原优先级

```tsl
get_status := sysGetThreadPriority(priority);
if get_status = 0 then
    set_status := sysSetThreadPriority(priority);
else
    set_status := get_status;
echo set_status, "\n";
```

## `sysTerminate(ret_code, handle)`

声明：function

终止进程。

| 参数       | 类型    | 说明                                       |
| ---------- | ------- | ------------------------------------------ |
| `ret_code` | integer | 整数，终止进程返回的代码。                 |
| `handle`   | integer | 整数，终止进程的句柄。缺省为终止自身进程。 |

返回：any

### 示例

范例01：终止当前脚本启动的子进程

```tsl
handle := sysExec("/bin/sleep", "5", nil, false, exit_code);
result := sysTerminate(0, handle);
echo result, "\n";
sysCloseHandle(handle);
```

## `sysThreadId()`

声明：function

获得运行的线程ID。

返回：integer

### 示例

范例01：读取当前线程 ID

```tsl
echo sysThreadId(), "\n";
```

## `sysThreadSelf()`

声明：function

获取当前程序的线程ID。

返回：integer|int64

### 示例

范例01：读取当前线程标识

```tsl
echo sysThreadSelf(), "\n";
```

## `sysWaitForMultipleObjects(objects, b_wait_all, wait_ms)`

声明：function

等待占有多个对象,例如互斥对象。支持windows和linux的进程

| 参数         | 类型             | 说明                                                                       |
| ------------ | ---------------- | -------------------------------------------------------------------------- |
| `objects`    | array of integer | 一维数字数组，对象句柄数组                                                 |
| `b_wait_all` | bool             | 真假，是否等待所有的对象。为真等待所有的，为假则仅需任意一个对象等待成功。 |
| `wait_ms`    | integer          | 整数，等待的毫秒数，-1则为永远等待。                                       |

返回：integer

### 示例

范例01：等待两个本地子进程结束

```tsl
handle1 := sysExec("/bin/true", "", nil, false, exit_code1);
handle2 := sysExec("/bin/true", "", nil, false, exit_code2);
wait_result := sysWaitForMultipleObjects(array(handle1, handle2), 1, 5000);
echo wait_result, "\n";
sysCloseHandle(handle1);
sysCloseHandle(handle2);
```

## `sysWaitForSingleObject(object, wait_ms)`

声明：function

等待占有一个对象,例如互斥对象。支持windows和linux的进程

| 参数      | 类型    | 说明                                 |
| --------- | ------- | ------------------------------------ |
| `object`  | integer | 整数，对象名柄                       |
| `wait_ms` | integer | 整数，等待的毫秒数，-1则为永远等待。 |

返回：integer

### 示例

范例01：等待本地子进程结束

```tsl
handle := sysExec("/bin/true", "", nil, false, exit_code);
wait_result := sysWaitForSingleObject(handle, 5000);
echo wait_result, "\n";
sysCloseHandle(handle);
```