os 包

介绍

os 包提供了对 Linux，macOS 与 Windows 平台操作系统 POSIX 、Process 与部分 OS 相关能力的支持。平台具体支持能力详见兼容性说明章节表格。 操作系统 OS 支持能力主要包括获取或操作当前进程相关信息(如进程参数、环境变量、目录信息等)，注册回调函数及退出当前进程，相关实现在 os 包中。操作系统 POSIX 相关能力实现在 os.posix 包中。Process 相关能力实现在 os.process 包中。

主要接口

func getArgs

public func getArgs(): Array<String>

功能：返回命令行参数列表，例如在命令行中执行 a.out ab cd ef，其中 a.out 是程序名，返回的列表包含三个元素 ab cd ef。 需要注意的是，使用 c 语言调用仓颉动态库方式时，通过 int SetCJCommandLineArgs(int argc, const char* argv[]) 设置的命令行参数，在使用 getArgs() 获取时将会被舍弃掉第一个参数。

返回值：返回命令行参数列表

func envVars

public func envVars(): HashMap<String, String>

功能：获取所有环境变量。 返回值为 HashMap，它以 key 和 value 的形式存储环境变量。

返回值：返回所有环境变量值

func getEnv

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

功能：获取指定名称的环境变量值。 返回 Option<String> 类型的字符串。

参数：

• k：环境变量名称

返回值：返回环境变量值

异常：

• IllegalArgumentException：如果 k 包含空字符则抛出异常

func setEnv

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

功能：用于设置一对环境变量。如果设置了同名环境变量，原始环境变量值将被覆盖。

参数：

• k：环境变量名称
• v：环境变量值

异常：

• IllegalArgumentException：如果 k 或 v 包含空字符则抛出异常

func removeEnv

public func removeEnv(k: String): Unit

功能：用于通过环境变量名称移除环境变量。

参数：

• k：环境变量名称

异常：

• IllegalArgumentException：如果 k 包含空字符则抛出异常

func currentDir

public func currentDir(): Directory

功能：获取当前工作目录。返回值为 Directory 类型，可以使用 Directory.info.path.toString() 获取路径的字符串。

返回值：返回 Directory 类型值

func homeDir

public func homeDir(): Directory

功能：获取 home 目录。

返回值：返回 Directory 类型值

func tempDir

public func tempDir(): Directory

功能：获取临时目录。从环境变量中获取 TMPDIR、TMP、TEMP 和 TEMPDIR 环境变量。如果以上值在环境变量中均不存在，则默认返回 /tmp 目录。

返回值：返回 Directory 类型值

func processorCount

public func processorCount(): Int64

功能：获取处理器数量。 返回值：处理器数量

示例

获取参数、环境变量及相关目录信息

from std import os.*
from std import fs.*
from std import collection.*

main(): Unit {
    let args: Array<String> = getArgs()
    let envs: HashMap<String, String> = envVars()
    let currentDir: Directory = currentDir()
    let homeDir: Directory = homeDir()
    let tempDir: Directory = tempDir()
    let processorCount: Int64 = processorCount()
    
    println("args: ${args}")
    println("envs: ${envs}")
    println("currentDir: ${currentDir.info.path.toString()}")
    println("homeDir: ${homeDir.info.path.toString()}")
    println("tempDir: ${tempDir.info.path.toString()}")
    println("processorCount: ${processorCount}")
    return 
}

运行结果如下（根据系统与运行环境不同返回结果可能不同）：

args: []
envs: [(USER, root),(PWD, /root/code/cangjie)]
currentDir: /root/code/cangjie
homeDir: /root
tempDir: /tmp
processorCount: 96

os.posix 包

介绍

本包主要适配 POSIX 系统接口，提供多平台统一操控能力，目前支持 Linux 平台，macOS 平台与 Windows 平台。

主要接口

常量具体说明详见常量信息说明章节。

AT_EMPTY_PATH

public const AT_EMPTY_PATH: Int32

AT_REMOVEDIR

public const AT_REMOVEDIR :Int32

F_OK

public const F_OK: Int32

O_CLOEXEC

public const O_CLOEXEC: Int32

O_DIRECTORY

public const O_DIRECTORY: Int32

O_EXCL

public const O_EXCL: Int32

O_NOFOLLOW

public const O_NOFOLLOW: Int32

O_RDONLY

public const O_RDONLY: Int32

O_RSYNC

public const O_RSYNC: Int32

O_TRUNC

public const O_TRUNC: Int32

R_OK

public const R_OK: Int32

SEEK_END

public const SEEK_END: Int32

SIGABRT

public const SIGABRT: Int32

SIGBUS

public const SIGBUS: Int32

SIGCONT

public const SIGCONT: Int32

SIGHUP

public const SIGHUP: Int32

SIGINT

public const SIGINT: Int32

SIGIOT

public const SIGIOT: Int32

SIGPIPE

public const SIGPIPE: Int32

SIGPWR

public const SIGPWR: Int32

SIGSEGV

public const SIGSEGV: Int32

SIGSTOP

public const SIGSTOP: Int32

SIGTERM

public const SIGTERM: Int32

SIGTSTP

public const SIGTSTP: Int32

SIGTTOU

public const SIGTTOU: Int32

SIGUSR1

public const SIGUSR1: Int32

SIGVTALRM

public const SIGVTALRM: Int32

SIGXCPU

public const SIGXCPU: Int32

S_IFBLK

public const S_IFBLK: UInt32

S_IFDIR

public const S_IFDIR: UInt32

S_IFLNK

public const S_IFLNK: UInt32

S_IFSOCK

public const S_IFSOCK: UInt32

S_IROTH

public const S_IROTH: UInt32

S_IRWXG

public const S_IRWXG: UInt32

S_IRWXU

public const S_IRWXU: UInt32

S_IWOTH

public const S_IWOTH: UInt32

S_IXGRP

public const S_IXGRP: UInt32

S_IXUSR

public const S_IXUSR: UInt32

X_OK

public const X_OK: Int32

func getos

public func getos(): String

功能：从 /proc/version 文件中获取 Linux 系统的信息。例如: Linux version 4.15.0-142-generic (buildd@lgw01-amd64-036) (gcc version 7.5.0 (Ubuntu 7.5.0-3ubuntu1~18.04)) #146-Ubuntu SMP Tue Apr 13 01:11:19 UTC 2021。

返回值：获取到的 Linux 系统的信息字符串

func gethostname

public func gethostname(): String

功能：获取主机名称，此名称通常是 TCP/IP 网络上主机的名称。

返回值：获取到的主机的名称字符串, 获取失败则返回空字符串

func sethostname

public func sethostname(buf: String): Int32

功能：设置主机名，仅超级用户可以调用。

参数：

• buf：需要设置的主机名

返回值：设置成功，返回 0，设置失败, 返回 -1

异常：

• IllegalArgumentException：如果参数 buf 包含空字符则抛出异常

func getlogin

public func getlogin(): String

功能：获取当前登录名。

返回值：如果操作成功，则返回 String 类型的登录名，失败时返回空的 String

func chdir

public func chdir(path: String): Int32

功能：通过指定路径的方式，更改调用进程的当前工作目录。

参数：

• path：改变后的路径

返回值：设置成功，返回 0，设置失败, 返回 -1

func fchdir

public func fchdir(fd: Int32): Int32

功能：通过指定文件路径的描述符，更改调用进程的当前工作目录。

参数：

• fd：改变后的文件路径的描述符

返回值：设置成功，返回 0，设置失败, 返回 -1

func getcwd

public func getcwd(): String

功能：获取当前执行进程工作目录的绝对路径。

返回值：操作成功，返回包含路径信息的字符串，操作失败则返回空字符串

func getgid

public func getgid(): UInt32

功能：获取用户组 ID。

返回值：当前用户组 ID

func getuid

public func getuid(): UInt32

功能：获取调用进程的真实用户 ID。

返回值：当前真实用户 ID

func setgid

public func setgid(id: UInt32): Int32

功能：设置调用进程的有效组 ID，需要适当的权限。

参数：

• id：调用进程的有效组 ID 号

返回值：设置成功，返回 0，设置失败, 返回 -1

func setuid

public func setuid(id: UInt32): Int32

功能：设置调用进程的有效用户 ID，需要适当的权限。

参数：

• id：调用进程的有效用户 ID 号

返回值：设置成功，返回 0，设置失败, 返回 -1

func getpgid

public func getpgid(pid: Int32): Int32

功能：获取 pid 指定的进程的 PGID，如果 pid 为零，返回调用进程的进程 ID。

参数：

• pid：目标进程 ID

返回值：执行成功，返回进程组 ID，执行失败, 返回 -1

func getgroups

public unsafe func getgroups(size: Int32, gidArray: CPointer<UInt32>): Int32

功能：该函数用于获取当前用户所属组的代码。size 的值为 gidArray 可以容纳的 gid 的数量，gidArray 存放 gid，如果参数大小的值为零，则此函数仅返回表示用户所属的组数，不会像 gidArray 中放入 gid。获取当前用户所属组的代码。

参数：

• size：gidArray 可以容纳的 gid 的数量
• gidArray：组信息

返回值：执行成功，返回组代码，执行失败, 返回 -1

func getpid

public func getpid(): Int32

功能：获取调用进程的进程 ID (PID)。

返回值：返回调用进程的进程 ID (PID)

func getppid

public func getppid(): Int32

功能：此函数获取调用进程的父进程 ID。

返回值：返回调用进程的父进程 ID

func getpgrp

public func getpgrp(): Int32

功能：此函数用于获取当前进程所属的组 ID。 此函数等效于调用 getpgid(0)；返回值返回当前进程所属的组 ID。

返回值：返回调用进程父级的进程 ID

func setpgrp

public func setpgrp(): Int32

功能：此函数将当前进程所属的组 ID 设置为当前进程的进程 ID。 此函数相当于调用 setpgid(0, 0)。

返回值：执行成功，返回当前进程的组 ID，执行失败, 返回 -1

func setpgid

public func setpgid(pid: Int32, pgrp: Int32): Int32

功能：此函数将参数 pid 指定的组 ID 设置为参数 pgrp 指定的组 ID。 如果 pid 为 0，则使用当前进程的组 ID。

参数：

• pid：进程 id
• pgrp：进程组 id

返回值：执行成功，返回组 id，执行失败, 返回 -1

func `open`

public func `open`(path: String, oflag: Int32, flag: UInt32): Int32

功能：此函数功能为打开文件并为其返回新的文件描述符，或在失败时返回 -1。当文件打开方式参数设置为 O_CREAT 时，可以通过参数设置文件权限。path 代表文件路径，oflag 代表文件打开的方式，其中 O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 进程 | 操作。如果 oflag 中设置了 O_CREAT，且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限。

参数：

• path：文件路径
• oflag：文件打开的方式，O_RDONLY、O_RDWR、O_WRONLY 是一个互斥的条件
• flag：如果 oflag 设置了 O_CREAT 并且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限

返回值：返回新的文件描述符，执行失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func `open`

public func `open`(path: String, oflag: Int32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

参数：

• path：文件路径
• oflag：文件打开的方式，O_RDONLY、O_RDWR、O_WRONLY 是一个互斥的条件

返回值：返回新的文件描述符，执行失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func open64

public func open64(path: String, oflag: Int32, flag: UInt32): Int32

功能：此函数功能为打开文件并为其返回新的文件描述符，或在失败时返回 -1。当文件打开方式参数设置为 O_CREAT 时，可以通过参数设置文件权限。path 代表文件路径，oflag 代表文件打开的方式，其中 O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 进程 | 操作。如果 oflag 中设置了 O_CREAT，且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限。

参数：

• path：文件路径
• oflag：文件打开的方式，O_RDONLY、O_RDWR、O_WRONLY 是一个互斥的条件
• flag：如果 oflag 设置了 O_CREAT 并且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限

返回值：返回新的文件描述符，执行失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func open64

public func open64(path: String, oflag: Int32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

参数：

• path：文件路径
• oflag：文件打开的方式，O_RDONLY、O_RDWR、O_WRONLY 是一个互斥的条件

返回值：返回新的文件描述符，执行失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func openat

public func openat(fd: Int32, path: String, oflag: Int32, flag: UInt32): Int32

功能：此函数功能为打开文件并为其返回新的文件描述符，或在失败时返回 -1。当文件打开方式参数设置为 O_CREAT 时，可以通过参数设置文件权限。path 代表文件路径，oflag 代表文件打开的方式，其中 O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 进程 | 操作。如果 oflag 中设置了 O_CREAT，且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限。

参数：

• fd：路径的文件描述符
• path：文件路径
• oflag：文件打开的方式，O_RDONLY、O_RDWR、O_WRONLY 是一个互斥的条件
• flag：如果 oflag 设置了 O_CREAT 并且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限

返回值：返回新的文件描述符，执行失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func openat

public func openat(fd: Int32, path: String, oflag: Int32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

参数：

• fd：路径的文件描述符
• path：文件路径
• oflag：文件打开的方式，O_RDONLY、O_RDWR、O_WRONLY 是一个互斥的条件

返回值：返回新的文件描述符，执行失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func openat64

public func openat64(fd: Int32, path: String, oflag: Int32, flag: UInt32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

参数：

• fd：路径的文件描述符
• path：文件路径
• oflag：文件打开的方式，O_RDONLY、O_RDWR、O_WRONLY 是一个互斥的条件
• flag：如果 oflag 设置了 O_CREAT 并且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限

返回值：返回新的文件描述符，执行失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func openat64

public func openat64(fd: Int32, path: String, oflag: Int32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。 参数：

• fd：路径的文件描述符
• path：文件路径
• oflag：文件打开的方式，O_RDONLY、O_RDWR、O_WRONLY 是一个互斥的条件

返回值：返回新的文件描述符，执行失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func creat

public func creat(path: String, flag: UInt32): Int32

功能：创建文件并为其返回文件描述符，或在失败时返回 -1。

参数：

• path：文件路径
• flag：创建文件的权限

返回值：返回文件描述符，执行失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func close

public func close(fd: Int32): Int32

功能：关闭文件，close 将会触发数据写回磁盘，并释放文件占用的资源。

参数：

• fd：文件描述符

返回值：成功时返回 0，失败时返回 -1

func lseek

public func lseek(fd: Int32, offset: Int64, whence: Int32): Int64

功能：当文件进行读或写时，读 / 写位置相应增加。本函数用于控制文件的读 / 写位置。调用成功时，返回当前读写位置，即从文件开头开始的字节数。 如果发生错误，返回 -1。

参数：

• fd：打开文件的文件描述符
• offset：偏移量
• whence：表示控制模式

返回值：调用成功时，返回当前读写位置，即从文件开头开始的字节数

func read

public unsafe func read(fd: Int32, buffer: CPointer<UInt8>, nbyte: UIntNative): IntNative

功能：将 fd 指向的文件的 nbyte 字节传输到 buffer 指向的内存中。如果 nbyte 为 0，则函数无效果，并返回 0。返回值是实际读取的字节数。返回值为 0 表示到达文件末尾或无法读取数据。 此外，文件的读写位置随着读取字节的变化而变化。 注意: 建议 nbyte 的大小与 buffer 的大小相同，且 buffer 的大小小于或等于 150000 字节。

参数：

• fd：待读取文件的文件描述符
• buffer：缓冲区容器
• nbyte：读取字节数，建议采用buffer.size

返回值：返回实际读取字节数，读取无效时返回 -1

func pread

public unsafe func pread(fd: Int32, buffer: CPointer<UInt8>, nbyte: UIntNative, offset: Int32): IntNative

功能：将 fd 指向的文件从指定偏移位置开始的 nbyte 字节传输到 buffer 指向的内存中。offset 表示读取位置的偏移量。如果 nbyte 为 0，则函数无效果，并返回 0。返回值是实际读取的字节数。返回值为 0 表示到达文件末尾或无法读取数据。此外，文件的读写位置随着读取字节的变化而变化。 注意: 建议 nbyte 的大小与 buffer 的大小相同，且 buffer 的大小小于或等于 150000 字节。

参数：

• fd：待读取文件的文件描述符
• buffer：缓冲区容器
• nbyte：读取字节数，建议采用buffer.size
• offset：读取位置的偏移量

返回值：返回实际读取数，执行失败时返回 -1

func write

public unsafe func write(fd: Int32, buffer: CPointer<UInt8>, nbyte: UIntNative): IntNative

功能：将 buffer 指向的内存中 nbyte 字节写入到 fd 指向的文件。指定文件的读写位置会随之移动。 注意: 建议 nbyte 的大小与 buffer 的大小相同，且 buffer 的大小小于或等于 150000 字节。

参数：

• fd：待写入文件的文件描述符
• buffer：缓冲区容器
• nbyte：写入字节数，建议采用buffer.size

返回值：返回实际写入数，执行失败时返回 -1

func pwrite

public unsafe func pwrite(fd: Int32, buffer: CPointer<UInt8>, nbyte: UIntNative, offset: Int32): IntNative

功能：将 buffer 指向的内存中 nbyte 字节从指定偏移位置开始写入到 fd 指向的文件。指定文件的读写位置会随之移动。 注意: 建议 nbyte 的大小与 buffer 的大小相同，且 buffer 的大小小于或等于 150000 字节。

参数：

• fd：待写入文件的文件描述符
• buffer：缓冲区容器
• nbyte：写入字节数，建议采用buffer.size
• offset：写入位置的偏移量

返回值：返回实际写入数，执行失败时返回 -1

func dup

public func dup(fd: Int32): Int32

功能：用于复制旧 fd 参数指定的文件描述符并返回。此新文件描述符和旧的参数 fd 引用同一文件，共享文件各种状态。共享所有的锁定、读写位置和各项权限或标志等。

参数：

• fd：文件描述符

返回值：返回最小且未使用的文件描述符，执行失败时返回 -1

func dup2

public func dup2(fd: Int32, fd2: Int32): Int32

功能：用于复制 oldfd 参数指定的文件描述符，并将其返回到 newfd 参数。如果参数 newfd 是打开的文件描述符，则 newfd 指定的文件将首先关闭。

参数：

• fd：oldfd 参数指定的文件描述符
• fd2：newfd 参数指定的文件描述符

返回值：fd2 文件描述符

func isType

public func isType(path: String, mode: UInt32): Bool

功能：检查文件是否为指定模式的文件。如果是，返回 ture，否则返回 false。根据模式的不同值确定不同的类型。

参数：

• path：文件路径
• mode：判断参数

返回值：如果是指定模式的文件，返回 true，否则返回 false

func isReg

public func isReg(path: String): Bool

功能：检查传入对象是否为普通文件，返回布尔类型。

参数：

• path：文件路径

返回值：如果是，返回 true，否则返回 false

func isDir

public func isDir(path: String): Bool

功能：检查传入对象是否为文件夹，返回布尔类型。

参数：

• path：文件路径

返回值：如果是，返回 true，否则返回 false

func isChr

public func isChr(path: String): Bool

功能：检查传入对象是否为字符设备，返回布尔类型。

参数：

• path：文件路径

返回值：如果是，返回 true，否则返回 false

func isBlk

public func isBlk(path: String): Bool

功能：检查传入对象是否为块设备，并返回布尔类型。

参数：

• path：文件路径

返回值：如果是，返回 true，否则返回 false

func isFIFO

public func isFIFO(path: String): Bool

功能：检查传入对象是否为 FIFO 文件，返回布尔类型。

参数：

• path：文件路径

返回值：如果是，返回 true，否则返回 false

func isLnk

public func isLnk(path: String): Bool

功能：检查传入对象是否为软链路，返回布尔类型。

参数：

• path：文件路径

返回值：如果是，返回 true，否则返回 false

func isSock

public func isSock(path: String): Bool

功能：检查传入对象是否为套接字文件，返回布尔类型。

参数：

• path：文件路径

返回值：如果是，返回 true，否则返回 false

func access

public func access(path: String, mode: Int32): Int32

功能：判断某个文件是否具有某种权限，具有返回 0，否则返回 -1。 mode 为指定权限，传入类型 R_OK、W_OK、X_OK、F_OK。

参数：

• path：文件路径
• mode：待检查的权限

返回值：文件具有待检查的权限返回 0，否则返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func faccessat

public func faccessat(fd: Int32, path: String, mode: Int32, flag: Int32): Int32

功能：判断 fd 对应的文件是否具有某种权限，具有返回 0，否则返回 -1 mode 为指定权限，传入类型 R_OK、W_OK、X_OK、F_OK。 如果操作成功，返回 0；否则，返回 -1。

参数：

• fd：文件描述符
• path：文件路径
• mode：待检查的权限
• flag：将以下一个或多个值按位或运算获取。（512）使用有效的用户和组 ID 执行访问检查，默认情况下使用有效 ID；（256）如果路径名是符号链接，不会取消引用而是返回有关链接本身信息

返回值：文件具有待检查的权限返回 0，否则返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func umask

public func umask(cmask: UInt32): UInt32

功能：设置权限掩码。

参数：

• cmask：文件权限参数

返回值：返回文件上一个掩码的值

func chown

public func chown(path: String, owner: UInt32, group: UInt32): Int32

功能：修改文件所有者和文件所有者所属组。

参数：

• path：文件路径
• owner：所有者 uid
• group：指定 gid 参数

返回值：操作成功时返回 0，失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func fchown

public func fchown(fd: Int32, owner: UInt32, group: UInt32): Int32

功能：修改 fd 对应的文件所有者和文件所有者所属组。

参数：

• fd：文件描述符
• owner：所有者 uid
• group：指定 gid 参数

返回值：操作成功时返回 0，失败时返回 -1

func lchown

public func lchown(path: String, owner: UInt32, group: UInt32): Int32

功能：修改文件链接本身所有者和所有者所属组。 成功时返回零，失败时返回 -1，错误号设置为指示错误。

参数：

• path：字符串类型的文件路径
• owner：所有者 uid
• group：指定 gid 参数

返回值：操作成功时返回 0，失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func fchownat

public func fchownat(fd: Int32, path: String, owner: UInt32, group: UInt32, flag: Int32): Int32

功能：修改文件描述符对应的文件所有者和文件所有者所属组。

• path 为相对路径且 fd 为特殊值 AT_FDCWD 时，则路径将相对于调用进程的当前工作目录
• path 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录
• path 为绝对路径时 fd 参数将被忽略

参数：

• fd：文件描述符
• path：文件路径
• owner：所有者 uid
• group：指定 gid 参数
• flag：取值可为 0，或（256）如果路径名是符号链接，不会取消引用它，而是返回有关链接本身的信息

返回值：操作成功时返回 0，失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func chmod

public func chmod(path: String, mode: UInt32): Int32

功能：修改文件访问权限。在 Windows 环境下， chmod() 函数使用说明：1. 所有文件和目录都是可读的，chmod() 不能更改文件的可读权限；2. 文件的可执行权限通过文件扩展名设置，所有目录都是可执行的，chmod() 不能更改文件和目录的可执行权限。

参数：

• path：文件路径
• mode：要修改的权限

返回值：成功时返回 0,失败时返回 -1；当 mode 为非法参数时，chmod 会忽略该参数，返回 0

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func fchmod

public func fchmod(fd: Int32, mode: UInt32): Int32

功能：修改文件描述符对应的文件访问权限。

参数：

• fd：文件描述符
• mode：要修改的权限

返回值：操作成功时返回 0，失败时返回 -1

func fchmodat

public func fchmodat(fd: Int32, path: String, mode: UInt32, flag: Int32): Int32

功能：修改文件描述符对应的文件访问权限。

• path 为相对路径且 fd 为特殊值 AT_FDCWD 时，则路径将相对于调用进程的当前工作目录
• path 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录
• path 为绝对路径时 fd 参数将被忽略

参数：

• fd：文件描述符
• path：文件路径
• mode：要修改的权限
• flag：取值可为 0，或（256）如果路径名是符号链接，不会取消引用它，而是返回有关链接本身的信息

返回值：操作成功时返回 0，失败时返回 -1

异常：

• IllegalArgumentException：如果 path 包含空字符则抛出异常

func nice

public func nice(inc: Int32): Int32

功能：更改当前线程的优先级。 只有超级用户才能使用负的 inc 值，表示优先级高，进程执行得更快。 inc 代表当前进程的优先级，取值的范围是 + 19（低优先级）到 - 20。 成功时返回新值，失败时返回 -1。 inc 在值大于 19 时，返回最大值 19。

参数：

• inc：当前进程的优先级, 值的范围是 + 19（低优先级）到 - 20

返回值：返回新优先级值

func kill

public func kill(pid: Int32, sig: Int32): Int32

功能：系统调用可用于向任何进程组或进程发送任何信号。

• 如果 pid 大于 0，则信号 sig 将发送到 pid 对应的进程
• 如果 pid 等于 0，然后 sig 被发送到调用进程的进程组中的每个进程
• 如果 pid 等于 -1，则 sig 被发送到调用进程有权发送信号的每个进程
• 如果 pid 小于 -1，则将 sig 发送到 ID 为 - pid 的进程组中的每个进程

参数：

• pid：进程 ID
• sig：信号 ID

返回值：操作成功时返回 0，否则返回 -1

func killpg

public func killpg(pgid: Int32, sig: Int32): Int32

功能：将信号 sig 发送到进程组 pgrp，如果 pgrp 为 0，则 killpg() 将信号发送到调用进程的进程组。

参数：

• pgid：组 ID
• sig：信号 ID

返回值：执行成功，返回 0，如果失败，返回 -1

func ttyname

public func ttyname(fd: Int32): String

功能：返回终端名称。

参数：

• fd：文件描述符

返回值：操作成功时返回指向路径名的指针，失败时，返回 NULL

func isatty

public func isatty(fd: Int32): Bool

功能：用于测试文件描述符是否引用终端，成功时返回 true，否则返回 false。

参数：

• fd：文件描述符

返回值：操作成功时返回 true，否则返回 false

func link

public func link(path: String, newpath: String): Int32

功能：为存在的文件创建链接，一个文件可以有多个指向其 i-node 的目录条目。

参数：

• path：文件路径
• newpath：其他文件路径

返回值：成功返回 0，错误返回 -1

异常：

• IllegalArgumentException：在 path 或 newPath 包含空字符时抛出异常

func linkat

public func linkat(fd: Int32, path: String, nfd: Int32, newPath: String, lflag: Int32): Int32

功能：创建相对于目录文件描述符的文件链接。

• path 为相对路径且 fd 为特殊值 AT_FDCWD 时，则路径将相对于调用进程的当前工作目录
• path 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录
• path 为绝对路径时 fd 参数将被忽略
• newPath 的场景与 path 相同，只是当 newPath 为相对路径时是相对于 nfd 引用的文件所属目录

参数：

• fd：文件描述符
• path：文件路径
• nfd：其他文件描述符
• newPath：其他文件路径，如果 newpath 存在，则不会覆盖
• lflag：AT_EMPTY_PATH 或 AT_SYMLINK_FOLLOW 或 0

返回值：成功返回 0，错误返回 -1

异常：

• IllegalArgumentException：在 path 或 newPath 包含空字符时抛出异常

func remove

public func remove(path: String): Int32

功能：删除文件或目录。对于文件，remove() 等同于 unlink()。对于目录，remove() 等同于 rmdir()。

参数：

• path：文件路径

返回值：成功返回 0，错误返回 -1

异常：

• IllegalArgumentException：在 path 包含空字符时抛出异常

func rename

public func rename(oldName: String, newName: String): Int32

功能：重命名文件，如果需要将会移动文件所在目录。文件的任何其他硬链接不受影响。旧路径打开的文件描述符也不受影响。 各种限制将决定重命名操作是否成功，具体场景如下：

• 如果 newName 已经存在，它将被原子替换，这样另一个尝试访问 newName 的进程就不会发现它丢失，但是，可能会有一个窗口，其中旧路径和新路径都引用要重命名的文件
• 如果旧路径和新路径是引用同一文件的现有硬链接，则重命名不做任何操作，并返回成功状态
• 如果 newName 存在，但操作因某种原因失败，则重命名保证保留 newName 的实例
• oldName 可以指定目录。在这种情况下，newName 必须不存在，或者它必须指定空目录
• 如果旧路径引用符号链接，则链接将重命名；如果新路径引用符号链接，则链接将被覆盖

参数：

• oldName：文件名(含路径)
• newName：文件名(含路径)

返回值：成功返回 0，错误返回 -1

异常：

• IllegalArgumentException：在 oldName 或 newName 包含空字符时抛出异常

func renameat

public func renameat(oldfd: Int32, oldName: String, newfd: Int32, newName: String): Int32

功能：重命名文件，如果需要将会移动文件所在目录。renameat() 与 rename() 处理相同，此处仅描述两者差异点：

• oldName 为相对路径且 oldfd 为特殊值 AT_FDCWD 时，则路径将相对于调用进程的当前工作目录
• oldName 为相对路径且 oldfd 非 AT_FDCWD 时，则路径将相对于 oldfd 引用的文件所属目录
• oldName 为绝对路径时 oldfd 参数将被忽略
• newName 的场景与 oldName 相同，只是当 newName 为相对路径时是相对于 newfd 引用的文件所属目录

参数：

• oldfd：文件描述符
• oldName：文件名
• newName：文件名
• newfd：文件描述符

返回值：成功返回 0，错误返回 -1

异常：

• IllegalArgumentException：在 oldName 或 newName 包含空字符时抛出异常

func symlink

public func symlink(path: String, symPath: String): Int32

功能：创建一个名为 symPath 链接到 path 所指定的文件。

• 符号链接在运行时被解释为链接的内容已被替换到要查找文件或目录的路径中
• 符号链接可能包含..路径组件，这些组件（如果在链接的开头使用）引用链接所在目录的父目录
• 符号链接（也称为软链接）可以指向现有文件或不存在的文件，后者被称为悬空链接
• 符号链接的权限是不相关的，在跟踪链接时，所有权将被忽略，但当请求删除或重命名链接并且链接位于设置了粘滞位的目录中时，所有权将被检查
• 如果 symPath 已存在，则不会被覆盖

参数：

• path：文件路径
• symPath：链接文件路径

返回值：成功返回 0，错误返回 -1

异常：

• IllegalArgumentException：在 path 或 symPath 包含空字符时抛出异常

func symlinkat

public func symlinkat(path: String, fd: Int32, symPath: String): Int32

功能：创建一个名为 symPath 链接到 path 与 fd 所指定的文件。

• symPath 为相对路径且 fd 为特殊值 AT_FDCWD 时，则路径将相对于调用进程的当前工作目录
• symPath 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录
• symPath 为绝对路径时 fd 参数将被忽略

参数：

• path：文件路径
• fd：文件描述符
• symPath：链接文件路径

返回值：成功返回 0，错误返回 -1

异常：

• IllegalArgumentException：在 path 或 symPath 包含空字符时抛出异常

func unlink

public func unlink(path: String): Int32

功能：从文件系统中删除文件。

• 如果 path 是指向文件的最后一个链接，并且没有进程打开该文件，则该文件将被删除，它使用的空间可供重复使用
• 如果 path 是指向文件的最后一个链接，但仍然有进程打开该文件，该文件将一直存在，直到引用它的最后一个文件描述符关闭
• 如果 path 引用了符号链接，则该链接将被删除
• 如果 path 引用了套接字、FIFO 或设备，则该文件将被删除，但打开对象的进程可能会继续使用它

参数：

• path：文件路径

返回值：成功返回 0，错误返回 -1

异常：

• IllegalArgumentException：在 path 包含空字符时抛出异常

func unlinkat

public func unlinkat(fd: Int32, path: String, ulflag: Int32): Int32

功能：该函数系统调用的操作方式与 unlink 函数完全相同，但此处描述的差异除外：

• path 为相对路径且 fd 为特殊值 AT_FDCWD 时，则路径将相对于调用进程的当前工作目录
• path 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录
• path 为绝对路径时 fd 参数将被忽略

参数：

• fd：文件描述符
• path：文件路径
• ulflag：可以指定为 0，或者可以设置为控制 unlinkat() 操作的标志值按位或运算。标志值当前取值仅支持 AT_REMOVEDIR

返回值：成功返回 0，错误返回 -1

异常：

• IllegalArgumentException：在 path 包含空字符时抛出异常

常量信息说明

示例

获取各类系统信息

下面是获取各类系统信息示例。

代码如下:

from std import os.posix.*

main(): Int64 {
    /* 系统名称相关 */
    var os_info = getos()
    println("os info ==> ${os_info}")
    var hostname = gethostname()
    println("hostname ==> ${hostname}")
    var logname: String = getlogin()
    println("logname ==> ${logname}")

    /* 程序运行路径相关函数 */
    var chagePath = "/"
    var chdir_restlt = chdir(chagePath)
    println("chdir_restlt ==> ${chdir_restlt}")
    var cwd_path: String = getcwd()
    println("cwd_path ==> ${cwd_path}")

    /* 系统 id 相关函数 getpgid */
    var arr: CString = unsafe { LibC.mallocCString(" ") }
    var a: CPointer<UInt8> = arr.getChars()
    var cp: CPointer<UInt32> = CPointer<UInt32>(a)
    var getg = unsafe{ getgroups(0, cp)}
    var s: String = " "
    for (_ in 0..getg) {
        s = s + "\0"
    }
    println(getg)
    var local: UInt32 = 0
    for (temp in 0..getg) {
        unsafe { local = cp.read(Int64(temp)) }
        println("getgroups ==> ${local.toString()}")
    }
    unsafe { LibC.free(arr)}
    return 0
}

运行结果如下（根据系统不同返回结果可能不同）：

Linux version 4.15.0-159-generic (buildd@lgw01-amd64-055) (gcc version 7.5.0 (Ubuntu 7.5.0-3ubuntu1~18.04)) #167-Ubuntu SMP Tue Sep 21 08:55:05 UTC 2021
hostname ==> e124e6e0fe0f
logname ==> root
chdir_restlt ==> 0
cwd_path ==> /
1
getgroups ==> 1309868064

文件内容相关操作

下面是文件内容相关操作示例。

代码如下:

from std import os.posix.*

main(): Int64 {
    var fd = `open`("textcase.txt", O_RDWR | O_APPEND | O_CREAT, S_IRWXU)
    println("fd ==> ${fd}")
    close(fd)
    var fd2 = `open`("textcase.txt", O_RDWR)
    var len = lseek(fd2, 0, SEEK_END)
    println("len ==> ${len}")
    close(fd2)
    var str1 = unsafe{LibC.mallocCString(" ")}
    var buf = str1.getChars()
    var fd3 = `open`("textcase.txt", O_RDWR)
    var readNum = unsafe { read(fd3, buf, 2) }
    unsafe{ LibC.free(str1)}
    println("readNum ==> ${readNum}")
    close(fd3)
    var str2 = unsafe{LibC.mallocCString("123456")}
    var buf2 = str2.getChars()

    var fd4 = `open`("textcase.txt", O_RDWR)
    var fd5 = dup(fd4)
    var writeNum = unsafe { write(fd5, buf2, UIntNative(str2.size())) }
    unsafe { LibC.free(str2)}
    println("writeNum ==> ${writeNum}")
    close(fd4)
    return 0
}

可能出现的运行结果如下:

fd ==> 3
len ==> 6
readNum ==> 2
writeNum ==> 6

文件信息相关操作

下面是文件信息相关操作示例。

代码如下:

from std import os.posix.*

main(): Int64 {
    var result1: Bool = isType("/notdirs", S_IFDIR)
    println("result ==> ${result1}")
    var result2: Bool = isDir("/dev")
    println("result ==> ${result2}")
    var result3 = access("./oscfg.cfg", F_OK)
    println("result ==> ${result3}")
    var result4 = chmod("oscfg.cfg", UInt32(S_IXUSR))
    println("result ==> ${result4}")
    return 0
}

运行结果如下:

result ==> false
result ==> true
result ==> -1
result ==> -1

进程相关信息操作

下面是进程相关信息操作示例。

代码如下:

from std import os.posix.*

main(): Int64 {
    var result = nice(200)
    print("${result}")
    var result1 = kill(0, SIGCHLD)
    println(result1)
    var result2 = killpg(0, SIGURG)
    println("result ==> ${result2}")
    if (isatty(0) && isatty(1) && isatty(2)) {
            print("true01 ")
        } else {
            print("false01 ")
        }
        if (isatty(-23) || isatty(4) || isatty(455) || isatty(43332)) {
            print("true02 ")
        } else {
            println("false02")
        }
        return 0
}

运行结果如下:

190
result ==> 0
true01 false02

os.process 包

介绍

本包主要提供 Process 进程操作接口，主要包括进程创建，标准流获取，进程等待，进程信息查询等，提供多平台统一操控能力，支持 Linux 平台、 Windows 平台。

主要接口

class Process

public open class Process

此类为进程类，提供进程操作相关功能。

使用 Process 类需要导入 os.process 包。

提供功能具体如下：

• 提供获取当前进程实例的功能；
• 提供根据进程 id 绑定进程实例的功能；
• 提供根据输入信息创建子进程的功能；
• 提供获取进程信息的功能；
• 提供关闭进程的功能，允许设置是否强制关闭进程；

prop current

public static prop current: CurrentProcess

功能：获取当前进程实例。

prop pid

public prop pid: Int64

功能：获取进程 id。

prop name

public prop name: String

功能：获取进程名。

异常：

• ProcessException：如果进程不存在或对应进程为僵尸进程，无法获取进程名，则抛出异常

prop command

public prop command: String

功能：获取进程命令。

异常：

• ProcessException：如果进程不存在或对应进程为僵尸进程，无法获取进程命令，则抛出异常

prop arguments

public prop arguments: Array<String>

功能：获取进程参数。Windows 平台下无法在非特权 API 下获取到本属性，暂不支持获取。

异常：

• ProcessException：如果进程不存在或对应进程为僵尸进程，或在 Windows 平台下暂不支持场景，无法获取进程参数，则抛出异常

prop commandLine

public prop commandLine: Array<String>

功能：获取进程命令行。Windows 平台当前进程可获取，其他场景下无法在非特权 API 下获取到本属性，暂不支持获取。

异常：

• ProcessException：如果进程不存在或对应进程为僵尸进程，或在 Windows 平台下暂不支持场景，无法获取进程命令行，则抛出异常

prop workingDirectory

public prop workingDirectory: Path

功能：获取进程工作路径。Windows 平台当前进程可获取，其他场景下无法在非特权 API 下获取到本属性，暂不支持获取。

异常：

• ProcessException：如果进程不存在或对应进程为僵尸进程，或在 Windows 平台下暂不支持场景，无法获取进程工作路径，则抛出异常

prop environment

public prop environment: Map<String, String>

功能：获取进程环境变量。Windows 平台当前进程可获取，其他场景下无法在非特权 API 下获取到本属性，暂不支持获取。

异常：

• ProcessException：如果进程不存在或对应进程为僵尸进程，或在 Windows 平台下暂不支持场景，无法获取进程环境变量，则抛出异常

func of

public static func of(pid: Int64): Process

功能：根据输入进程 id 绑定一个进程实例。

参数：

• pid： 进程 id

返回值：

• Process：返回进程 id 对应的进程实例

异常：

• IllegalArgumentException：当输入进程 id 大于 Int32 最大值或小于 0，抛出异常

• ProcessException：如果内存分配失败或 pid 对应的进程不存在，则抛出异常

func start

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

功能：根据输入参数创建并运行一个子进程，并返回一个子进程实例。调用该函数创建子进程后，需要调用 wait 或 waitOutput 函数，否则该子进程结束后成为的僵尸进程的资源不会被回收。

参数：

• command：指定子进程命令，command 不允许包含空字符

• arguments：指定子进程参数，arguments 不允许数组中字符串中包含空字符

• workingDirectory：命名可选参数，指定子进程的工作路径，默认继承当前进程工作路径，路径必须为存在的目录且不允许为空路径或包含空字符

• environment：命名可选参数，指定子进程环境变量，默认继承当前进程环境变量，key 不允许字符串中包含空字符或 '='，value 不允许字符串中包含空字符

• stdIn：命名可选参数，指定子进程重定向标准输入，默认继承当前进程标准输入

• stdOut：命名可选参数，指定子进程重定向标准输出，默认继承当前进程标准输出

• stdErr：命名可选参数，指定子进程重定向标准错误，默认继承当前进程标准错误

返回值：

• SubProcess：返回一个子进程实例

异常：

• IllegalArgumentException：如果 command 包含空字符，或者 arguments 数组中字符串中包含空字符，或者 workingDirectory 不是存在的目录或为空路径或包含空字符，或者 environment 表中 key 字符串中包含空字符或 '='，或 value 字符串中包含空字符，或者 stdIn、stdOut、stdErr 输入为文件模式时，输入的文件已被关闭或删除，则抛出异常

• ProcessException：如果内存分配失败或 command 对应的命令不存在，则抛出异常

func run

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

功能：根据输入参数创建并运行一个子进程，等待该子进程运行完毕并返回子进程退出状态。

参数：

• command：指定子进程命令，command 不允许包含空字符

• arguments：指定子进程参数，arguments 不允许数组中字符串中包含空字符

• workingDirectory：命名可选参数，指定子进程的工作路径，默认继承当前进程工作路径，路径必须为存在的目录且不允许为空路径或包含空字符

• environment：命名可选参数，指定子进程环境变量，默认继承当前进程环境变量，key 不允许字符串中包含空字符或 '='，value 不允许字符串中包含空字符

• stdIn：命名可选参数，指定子进程重定向标准输入，默认继承当前进程标准输入

• stdOut：命名可选参数，指定子进程重定向标准输出，默认继承当前进程标准输出

• stdErr：命名可选参数，指定子进程重定向标准错误，默认继承当前进程标准错误

• timeout：命名可选参数，指定等待子进程超时时间，默认为不超时, timeout 指定为 0 或负值时表示不超时

返回值：

• Int64：返回子进程退出状态，若子进程正常退出，返回子进程退出码，若子进程被信号杀死，返回导致子进程终止的信号编号

异常：

• IllegalArgumentException：如果 command 包含空字符，或者 arguments 数组中字符串中包含空字符，或者 workingDirectory 不是存在的目录或为空路径或包含空字符，或者 environment 表中 key 字符串中包含空字符或 '='，或 value 字符串中包含空字符，或者 stdIn、stdOut、stdErr 输入为文件模式时，输入的文件已被关闭或删除，则抛出异常

• ProcessException：如果内存分配失败或 command 对应的命令不存在或等待超时，则抛出异常

func runOutput

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>)

功能：根据输入参数创建并运行一个子进程，等待该子进程运行完毕并返回子进程退出状态、标准输出和标准错误。输出流、错误流中包含大量输出的场景不适用于本函数，建议通过 SubProcess 中提供的标准流属性结合 wait 函数自行处理。

参数：

• command：指定子进程命令，command 不允许包含空字符

• arguments：指定子进程参数，arguments 不允许数组中字符串中包含空字符

• workingDirectory：命名可选参数，指定子进程的工作路径，默认继承当前进程工作路径，路径必须为存在的目录且不允许为空路径或包含空字符

• environment：命名可选参数，指定子进程环境变量，默认继承当前进程环境变量，key 不允许字符串中包含空字符或 '='，value 不允许字符串中包含空字符

• stdIn：命名可选参数，指定子进程重定向标准输入，默认继承当前进程标准输入

• stdOut：命名可选参数，指定子进程重定向标准输出，默认继承当前进程标准输出

• stdErr：命名可选参数，指定子进程重定向标准错误，默认继承当前进程标准错误

返回值：

• (Int64, Array<Byte>, Array<Byte>)：子进程执行返回结果，包含子进程退出状态（若子进程正常退出，返回子进程退出码，若子进程被信号杀死，返回导致子进程终止的信号编号），进程标准输出结果和进程错误结果

异常：

• IllegalArgumentException：如果 command 包含空字符，或者 arguments 数组中字符串中包含空字符，或者 workingDirectory 不是存在的目录或为空路径或包含空字符，或者 environment 表中 key 字符串中包含空字符或 '='，或 value 字符串中包含空字符，或者 stdIn、stdOut、stdErr 输入为文件模式时，输入的文件已被关闭或删除，则抛出异常

• ProcessException：如果内存分配失败，或者 command 对应的命令不存在，或者子进程不存在，或者标准流读取异常，则抛出异常

func terminate

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

功能：终止进程

参数：

• force：命名可选参数，指定是否强制关闭进程，默认为 false，若设置为 false，对应进程可以在释放资源后结束；若设置为 true，对应进程将被直接杀死。Windows 平台实现为强制关闭进程。

异常：

• ProcessException：如果进程不存在，不允许终止，则抛出异常

enum ProcessRedirect

public enum ProcessRedirect

此 enum 类用于在创建进程时设置子进程标准流的重定向模式。

Inherit

Inherit

功能：构造一个标准流重定向枚举实例，表示子进程标准流将继承当前进程的标准流。此模式下标准流属性不可读取或写入

Pipe

Pipe

功能：构造一个标准流重定向枚举实例，表示子进程标准流将被重定向至管道，并通过管道与当前进程连接。重定向标准输入流可通过管道向子进程写入数据，重定向标准输出流或标准错误流可通过管道读取子进程输出结果。此模式下可通过标准流属性读取或写入数据

FromFile

FromFile(File)

功能：构造一个标准流重定向枚举实例，表示子进程标准流将被重定向至指定的文件。重定向标准输入流将从指定文件读取，重定向标准输出流或标准错误流将写入至指定文件。重定向文件需保证存在且未关闭，否则不允许重定向。此模式下标准流属性不可读取或写入

参数：

• File：指定存在且未关闭文件实例，创建子进程时，重定向标准流至该指定文件

Discard

Discard

功能：构造一个标准流重定向枚举实例，表示子进程标准流将被丢弃。此模式下标准流属性不可读取或写入

class CurrentProcess

public class CurrentProcess <: Process

此类为当前进程类，继承 Process 类，提供对当前进程操作相关功能。

使用 CurrentProcess 类需要导入 os.process 包。

提供功能具体如下：

• 提供获取当前进程标准流（stdIn、stdOut、stdErr）机制；
• 提供当前进程退出注册回调函数机制；
• 提供当前进程退出机制，允许设置退出状态码。

prop stdIn

public prop stdIn: InputStream

功能：获取当前进程标准输入流。

prop stdOut

public prop stdOut: OutputStream

功能：获取当前进程标准输出流。

prop stdErr

public prop stdErr: OutputStream

功能：获取当前进程标准错误流。

func atExit

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

功能：注册回调函数，当前进程退出时执行注册函数。注意请不要使用C语言 atexit 函数，避免出现不可期问题。

参数：

• () -> Unit：需要被注册回调的函数

func exit

public func exit(code: Int64): Nothing

功能：进程退出函数，执行到此函数直接结束当前进程，并且通过入参 code 设置返回状态码。

参数：

• Int64：当前进程退出状态码

class SubProcess

public class SubProcess <: Process

此类为子进程类，继承 Process 类，提供对子进程操作相关功能。

使用 SubProcess 类需要导入 os.process 包。

提供功能具体如下：

• 提供获取子进程标准流（stdIn、stdOut、stdErr）机制；
• 提供等待子进程执行返回退出状态码机制，允许设置等待超时时长；
• 提供等待子进程执行返回输出结果(包含运行正常、异常结果)机制，允许设置等待超时时长。

prop stdIn

public prop stdIn: OutputStream

功能：获取输出流，连接到子进程标准输入流。

prop stdOut

public prop stdOut: InputStream

功能：获取输入流，连接到子进程标准输出流。

prop stdErr

public prop stdErr: InputStream

功能：获取输入流，连接到子进程标准错误流。

func wait

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

功能：阻塞当前进程等待子进程任务执行完成并返回子进程退出状态码，允许指定等待超时时间。对于需要操作标准流的场景(Pipe 模式)，使用者需要优先处理标准流，避免子进程标准流缓冲区满后调用本函数产生死锁。

超时时间处理机制：

• 未传参、 timeout 值为 None 或值小于等于 Duration.Zero 时，阻塞等待直至子进程执行返回。
• timeout 值大于 Duration.Zero 时，阻塞等待子进程执行返回或等待超时后抛出超时异常。

参数：

• timeout：命名可选参数，设置等待子进程超时时间，默认为 None

返回值：

• Int64：返回子进程退出状态。若子进程正常退出，返回子进程退出码，若子进程被信号杀死，返回导致子进程终止的信号编号

异常：

• ProcessException：如果等待超时，子进程未退出，则抛出异常

func waitOutput

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

功能：阻塞当前进程等待子进程任务执行完成，并返回子进程退出状态码、返回结果(包含输出流和错误流返回结果)。输出流、错误流中包含大量输出的场景不适用于本函数，建议通过 SubProcess 中提供的标准流属性结合 wait 函数自行处理。

返回值：

• (Int64, Array<Byte>, Array<Byte>)：子进程执行返回结果，包含子进程退出状态（若子进程正常退出，返回子进程退出码，若子进程被信号杀死，返回导致子进程终止的信号编号），进程标准输出结果和进程错误结果

异常：

• ProcessException：如果子进程不存在，或者标准流读取异常，则抛出异常

class ProcessException

public class ProcessException <: Exception

os.process 包的异常类。

init

public init(message: String)

功能：创建 ProcessException 实例。

参数：

• message：异常提示信息

示例

子进程相关操作

下面是子进程相关操作示例。

代码如下：

from std import os.process.*
from std import io.*
from std import fs.*

// 以Linux平台相关命令举例说明, 以下用例需要提前创建 “/root/code/Process/test” 目录
main(): Int64 {
    let sleepProcess: SubProcess = Process.start("sleep", "10s", workingDirectory: Path("/root/code/Process/test"))
    println(sleepProcess.pid)
    println(sleepProcess.name)
    println(sleepProcess.command)
    println(sleepProcess.arguments.toString())
    println(sleepProcess.commandLine.toString())
    println(sleepProcess.workingDirectory.toString())
    sleepProcess.terminate(force: true)
    let rtnCode = sleepProcess.wait()
    println("sleepProcess rtnCode: ${rtnCode}")
    
    let echoProcess: SubProcess = Process.start("echo", "hello cangjie!", stdOut: ProcessRedirect.Pipe)
    let strReader: StringReader<InputStream> = StringReader(echoProcess.stdOut)
    println(strReader.readToEnd())
    return 0
}

运行结果可能如下：

45090
sleep 10s
sleep
[10s]
[sleep, 10s]
/root/code/Process/test
sleepProcess rtnCode: 9
hello cangjie!

当前进程相关操作

下面是当前进程相关操作示例。

代码如下：

from std import os.process.*

main(): Int64 {
    let curProcess = Process.current
    println(curProcess.pid)
    println(curProcess.name)
    println(curProcess.command)
    println(curProcess.arguments.toString())
    println(curProcess.commandLine.toString())
    println(curProcess.workingDirectory.toString())
    curProcess.atExit(printText)
    curProcess.exit(0)
    return 0
}

func printText(): Unit {
    println("hello cangjie!")
}

运行结果可能如下（输出结果中mian为当前进程执行命令名，回调执行完成后当前进程会退出）：

75590
./main
./main
[]
[./main]
/root/code/Process/test
hello cangjie!

任意进程相关操作

下面是任意进程相关操作示例。

代码如下：

from std import os.process.*
from std import fs.*

main(): Int64 {
    let echoProcess: SubProcess = Process.start("sleep", "10s")
    let ofProcess: Process = Process.of(echoProcess.pid)
    println(ofProcess.pid)
    println(ofProcess.name)
    println(ofProcess.command)
    println(ofProcess.arguments.toString())
    println(ofProcess.commandLine.toString())
    ofProcess.terminate(force: true)
    return 0
}

运行结果可能如下：

78980
sleep
sleep
[10s]
[sleep, 10s]

兼容性说明

os

os.posix

os.process

public open class Process

class CurrentProcss

class SubProcess