第 12.00.01 章、os 包

总览

os 包通过平了一个平台无关的接口，来操作系统功能
设计风格是 Unix-like 的，但错误处理时 Go-like 的；失败返回的是 error 类型的值，而非错误号
大部分时候，使用 error 可以包含更多信息
举例来说，若一个调用产生了 文件名失败，比如在 Open 或者 Stat 中，
那么在打印时， error 就会包含失败的文件名，
在 error 中，就会具有 *PathError 类型的值，在解包后可以提供更多的信息

os 接口意在再跨所有操作系统来提供统一的接口
在系统特定的 syscall 包中提供的特性，并不会出现在这个包中


下面就是一个简单的例子，

file, err := os.Open("file.go") // For read access.
if err != nil {
	log.Fatal(err)
}

若操作失败，则错误字符串将自解释，例如

open file.go: no such file or directory

接着文件数据就可以被读入 []byte 中
Read 和 Write 都从参数 slice 的长度来获取 byte 计数

data := make([]byte, 100)
count, err := file.Read(data)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("read %d bytes: %q\n", count, data[:count])



常量

OpenFile 所使用的 flag，从底层系统包装而来
并非所有的 flag 都在给定的系统上实现了

const (
	O_RDONLY int = syscall.O_RDONLY // 只读方式打开文件
	O_WRONLY int = syscall.O_WRONLY // 只写方式打开文件
	O_RDWR   int = syscall.O_RDWR   // 读写方式打开文件
	O_APPEND int = syscall.O_APPEND // 写入时，将数据追加至文件
	O_CREATE int = syscall.O_CREAT  // 若文件不存在，则创建新文件
	O_EXCL   int = syscall.O_EXCL   // 与 O_EXCL 连用，文件必然不存在
	O_SYNC   int = syscall.O_SYNC   // 为同步 I/O 打开文件
	O_TRUNC  int = syscall.O_TRUNC  // 若可行，则在打开文件时截断文件
)

注： O_TRUNC 在系统调用时的含义为：

If the file already exists and is a regular file and the access mode allows writing it will be truncated to length 0

也就是：

若文件已经存在，且是一个普通文件，同时允许写入，则它将被截短至长度为 0


查找值的位置

废弃：io.SeekStart io.SeekCurrent io.SeekEnd

const (
	SEEK_SET int = 0 // 相对文件开头处
	SEEK_CUR int = 1 // 相对当前偏移
	SEEK_END int = 2 // 相对文件尾部
)

const (
	PathSeparator     = '/' // 系统特定的路径隔断符
	PathListSeparator = ':' // 系统特定的路径列表隔断符
)

DevNull 操作系统 “null device” 的名字
在 Unix-like 系统上，它是 "/dev/null"；在 Windows 上，它是 “NUL”

const DevNull = "/dev/null"



变量

一些可移植的等同的通用系统调用错误

var (
	ErrInvalid    = errors.New("invalid argument") // 当接受者为 nil 时，针对 File 的方法将返回的错误
	ErrPermission = errors.New("permission denied")
	ErrExist      = errors.New("file already exists")
	ErrNotExist   = errors.New("file does not exist")
	ErrClosed     = errors.New("file already closed")
)


Stdin Stdout Stderr 是 指向 标准输入、标准输出、标准错误 文件描述符 的 打开的 File

注意， Go 运行时 会使用 标准错误 来写入 panic 和 crash
关闭 Stderr 会导致这些信息写入其他地方，有可能是其后打开的某个文件中

var (
        Stdin  = NewFile(uintptr(syscall.Stdin), "/dev/stdin")
        Stdout = NewFile(uintptr(syscall.Stdout), "/dev/stdout")
        Stderr = NewFile(uintptr(syscall.Stderr), "/dev/stderr")
)

Args 持有命令行参数，第一元素是程序名

var Args []string



Chdir(dir string) error
修改当前工作路径至指定目录
若有一个错误，则类型为 *PathError


Chmod(name string, mode FileMode) error
修改文件名的 mode 至 指定的 mode
若文件是符号链接，则修改链接指向的文件的 mode
若有一个错误，则类型为 *PathError

依据系统的不同，将使用不同的 mode bit 的子集

在 Unix 上，使用 permission bits, ModeSetuid, ModeSetgid, ModeSticky

在 Windows 上，mode 必须非 0，或者仅为 0200（所有者可写）
它控制了一个文件只读属性是否被设置
其他的 bit 当前未使用
使用 0400 来只读一个文件
或者 0600 来表示可读写文件

在 Plan9 上，使用 permission bits, ModeAppend, ModeExclusive, ModeTemporary


Chown(name string, uid, gid int) error
修改文件的 以数字形式表示的 UID 和 GID
若文件是符号链接，则修改链接指向的文件的 mode
若有一个错误，则类型为 *PathError

在 Windows 上，它永远返回 syscall.EWINDOWS 错误，包裹在 *PathError 中


Chtimes(name string, atime time.Time, mtime time.Time) error
修改文件的 获取时间 和 修改时间，与 Unix 的 utime() 和 utimes() 函数类似

底层的文件系统可能会截断或者四舍五入该值至一个不那么精确的时间单位
若有一个错误，则类型为 *PathError


Clearenv()
删除全部的全局变量


Environ() []string
返回字符串表示的环境变量，以 “key=value” 的形式表示


Executable() (string, error)
返回启动当前进程的可执行文件的路径
它并不保证路径依旧指向正确的可执行文件
若一个符号链接用于启动进程，那么抑郁操作系统的不同，结果可能是符号链接本身或者其指向的文件
若一个需要一个稳定的结果，则 path/filepath.EvalSymlinks 可能有所帮助

本函数返回一个绝对路径，除非遇到一个错误
主要使用的情况是，寻找与可执行文件路径具有相对路径的资源

本函数在 nacl 上不被支持


Exit(code int)
导致当前程序退出，并给出一个退出状态号
惯例来说，0 表示成功，非 0 值表示一个错误
程序会立刻终止，被 defer 的函数不会运行


Expand(s string, mapping func(string) string) string
通过 mapping 函数，替换 字符串 中的 ${var} 或者 $var
举例来说，os.ExpandEnv(s) 等价于 os.Expand(s, os.GetEnv)


ExpandEnv(s string) string
根据当前环境变量的值，替换字符串中的 ${var} 或者 $var
参考至未定义的值被替换为空字符串

EG.
fmt.Println(os.ExpandEnv("$USER lives in ${HOME}."))


Getegid() int
返回用数字表示的调用者的 effective group
在 Windows 上，返回 -1


Getenv(key string) string
检索名字为 key 的环境变量的值
若变量没有出现，则返回空值
想区分 空值 和 未设置 的值，使用 LookupEnv


Geteuid() int
返回用数字表示的调用者的 effective uid
在 Windows 上，返回 -1


Getgid() int
返回用数字表示的调用者的 gid
在 Windows 上，返回 -1


Getgroups() ([]int, error)
返回用数字表示的调用者所在的 group
在 Windows 上，返回 syscall.EWINDOWS
查看 os/user 包来寻找可能的替代


Getpagesize() int
返回底层系统的内存页大小


Getpid() int
返回调用者进程的 pid


Getppid() int
返回调用者进程的父进程的 pid


Getuid() int
返回用数字表示的调用者的 uid
在 Windows 上，返回 -1


Getwd() (dir string, err error)
返回当前目录相对根目录的路径
若当前目录可以通过多种路径得到（由于符号链接的带来的），则本函数会返回其中的任意一个


Hostname() (name string, err error)
返回内核反馈的 hostname 信息


IsExist(err error) bool
返回一个 bool 值，指示了一个错误是否报告了一个文件或者目录已经存在
它通过 ErrExist 变量，以及一些系统调用 error 满足


IsNotExist(err error) bool
返回一个 bool 值，指示了一个错误是否报告了一个文件或者目录并未存在
它通过 ErrNotExist 变量，以及一些系统调用 error 满足

EG.

filename := "a-nonexistent-file"
if _, err := os.Stat(filename); os.IsNotExist(err) {
    fmt.Printf("file does not exist")
}

返回

file does not exist


IsPathSepqrator(c uint8) bool
报告 c 是否是一个目录分隔字符


IsPermission(err error) bool
返回一个 bool 值，指示了一个错误是否报告了权限受阻
它通过 ErrPermission 变量，以及一些系统调用 error 满足


Lchown(name string, uid, gid int) error
修改指定文件的 uid 和 gid
若文件是符号链接，则修改符号链接本身的 uid 和 gid
若产生错误，则其类型是 *PathError

在 Windows，它用于返回 syscall.EWINDOWS 错误，包裹在 *PathError 中


Link(oldname, newname string) error
用 newname 创建一个硬链接至老的文件
若产生错误，则其类型是 *PathError


LookupEnv(key string) (string, bool)
检索环境变量中，指定 key 的值
若变量存在于环境中（即便可能为空值），函数也返回这个值，且 bool 为 true
除此之外，函数返回空值，且 bool 为 false


Mkdir(name string, perm FileMode) error
使用指定的名称和权限创建一个新的目录
若产生一个错误，则其类型是 *PathError


MkdirAll(path string, per FileMode) error
使用指定的路径和权限创建目录，并补全该目录所需的所有父级目录，并返回 nil，或者返回错误
权限针对该函数创建的所有目录上
若 path 已经是一个已存在的目录，则该函数不会执行任何操作，并返回 nil


NewSyscallErrror(syscall string, err error) error
本函数将一个新的 SyscallError 作为 error 返回
新的 error 包含了系统调用的名称，以及错误的详细信息
作为惯例，若 err 是 nil，则本函数返回 nil


Readlink(name string) (string, error)
返回指定的符号链接所指向的目标
若产生一个错误，则其类型是 *PathError


Remove(name string) error
移除指定的文件或目录
若产生一个错误，则其类型是 *PathError


RemoveAll(path string) error
移除一个路径，以及它所包含的任何子对象
它移除任何它可以移除的东西，但返回第一个遇到的错误
若 path 不存在，本函数返回 nil（并非 error）


Rename(oldpath, newpath string) error
重命名（移动）旧路径至新路径
若新路径已存在，且不是目录，本函数将替代它
当新旧目录不相同时，系统特殊限制会出现


SameFile(fi1, fi2 FileInfo) bool
报告 fi1 和 fi2 是否描述了相同的文件
举例来说，
在 Unix 上，这意味着设备和 inode 的两个底层的构架是相同的
在其他系统上，可能基于相同的路径名

本函数仅适用于本包 Stat 函数/方法 的返回值
在其他情况下，均返回 false


Setenv(key, value string) error
通过键名设置一个环境变量的值
若有错误则返回


Symlink(oldname, newname string) error
创建一个指向老名称的新软链接
若有一个错误，则其类型为 *LinkError


TempDir() string
返回临时文件所使用的默认目录

在 Unix 系统，若 $TMPDIR 非空，则返回该值，否则返回 /tmp
在 Windows 上，使用 syscall.GetTempPath 函数，从 %TMP%，%TEMP%，%USERPROFILE% 中返回第一个非空的值，或者 Windows 目录
在 Plan9 上，返回 /tmp

不保证目录真实存在，或者具有读写权利


Truncate(name string, size int64) error
修改指定文件的大小
若文件是一个软链接，则修改其指向的目标的大小
若有一个错误，则其类型为 *PathError


Unsetenv(key string) error
unset 单个环境变量



File struct 类型

该类型表示一个打开的文件描述符

Create(name string) (*File, error)
创建一个以 name 命名的文件，并赋予权限0666（在 umask 之前），若文件已经存在则截断它
若成功，对返回的 File 对象使用方法可以用于 I/O，相关联的文件描述符模式为 O_RDWR
若有一个错误，则其类型为 *PathError


NewFile(fd uintptr, name string) *File
返回具有给定的文件描述符和名称的 File 对象
若 fd 不是有效的文件描述符，则返回值将为 nil


Open(name string) (*File, error)
打开指定的文件来读取
若成功，则对返回的 File 对象使用的方法可以用于 读取，相关联的文件描述符模式为 O_RDONLY
若有一个错误，则其类型为 *PathError


OpenFile(name string, flag int, perm FileMode) (*File, error)
通用的 打开 调用，大多数用户会使用 Open 和 Create 函数
若可用的话，它以特定的 flag（O_RDONLY 等） 和 权限（0666 等）打开文件
若成功，则对返回的 File 对象使用的方法可以用于 I/O
若有一个错误，则其类型为 *PathError

EG.

// 若文件不存在，则创建它，否则在其后追加
f, err := os.OpenFile("access.log", os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
if err != nil {
    log.Fatal(err)
}
if _, err := f.Write([]byte("appended some data\n")); err != nil {
    log.Fatal(err)
}
if err := f.Close(); err != nil {
    log.Fatal(err)
}


Pipe() (r *File, w *File, err error)
返回一堆连接上的 File 对象
从 r 读取，写入 w 的数据
若有一个错误，则其类型为 *PathError


(f *File) Chdir() error
将当前的工作目录切换至 File 所在位置， File 必须是一个 目录
若有一个错误，则其类型为 *PathError


(f *File) Chmod() error
修改文件的 mode
若有一个错误，则其类型为 *PathError


(f *File) Chown(uid, gid int) error
修改文件的 uid 和 gid（数字形式表示）
若有一个错误，则其类型为 *PathError

在 Windows 上，永远返回 syscall.EWINDOWS 错误，包裹在 *PathError


(f *File) Close() error
关闭一个文件，并使其无法做 I/O 使用
若有错误则返回


(f *File) Fd() uintptr
返回一个参照代打开的文件的 Unix 文件描述符
仅在 f.Close 被调用，或者 f 被垃圾回收前才是合法的


(f *File) Name() string
返回文件的名称（如同提供给 Open 函数的一样）


(f *File) Read(b []byte) (n int, err error)
从 File 中，读取最多 len(b) 个字节
返回已经读取到的字节数，并返回任何遇到的错误


(f *File) ReadAt(b []byte, off int64) (n int, err error)
从 File 中指定的偏移字节数开始，读取最多 len(b) 个字节
返回已经读取到的字节数，并返回任何遇到的错误
若遇到文件尾，则返回 0, io.EOF


(f *File) Readdir(n int) ([]FileInfo, error)
读取文件 f 所关联的文件夹的内容，并返回一个最多包含 n 个 FileInfo 值的 slice
就像被 Lstat 返回的那样，以目录的顺序
其后的调用将继续返回新的 FileInfo 值

若 n > 0，本方法但会最多 n 个 FileInfo 结构体
在这种情况下，若本方法返回空 slice，它会返回一个非空错误来解释为什么
到达目录尾部时，得到的错误时 io.EOF

若 n < 0，本方法将目录下所有的内容作为单个 []FileInfo 返回
在这种情况下，若本方法成功执行（从头读至尾部），则它返回一个 slice 和 nil error
若在读到目录尾部前出现错误，则返回已获得的 []FileInfo，以及一个 非 nil error


(f *File) Readdirnames(n int) (names []string, err error)
从目录 f 中读取并返回一个 文件名 的 slice

若 n > 0，本方法但会最多 n 个 文件名
在这种情况下，若本方法返回空 slice，它会返回一个非空错误来解释为什么
到达目录尾部时，得到的错误时 io.EOF

若 n < 0，本方法将目录下所有的文件名作为单个 []string 返回
在这种情况下，若本方法成功执行（从头读至尾部），则它返回一个 slice 和 nil error
若在读到目录尾部前出现错误，则返回已获得的 []string，以及一个 非 nil error


(f *File) Seek(offset int64, whence int) (ret int64, err error)
本方法设置下一个 Read 或 Write 方法至偏移处
参照 whence 的含义：
	0 表示相对文件的开头
	1 表示相对当前的偏移
	2 表示相对文件的结尾
返回新的偏移值，若有错误，则一同返回
对以 O_APPEND 打开的文件，该方法的行为未定义


(f *File) Stat() (FileInfo, error)
返回描述文件的 FileInfo 结构体
若有一个错误，则其类型是 *PathError


(f *File) Sync() error
本方法提交文件的当前内容至稳定存储中
典型地，这意味着将系统内存中最近写入的的数据刷写入磁盘


(f *File) Truncate(size int64) error
修改文件的大小
它并不修改 I/O 偏移值
若有一个错误，则其类型是 *PathError


(f *File) Write(b []byte) (n int, err error)
将 len(b) 字节的数据写入 File 中
它返回写入的字节数，以及任何出现的错误
当 n != len(b)，本方法返回一个非 nil 的 error


(f *File) WriteString(s string) (n int, err error)
与 Write 相似，但写入的是字符串 s 而非 []byte



FileInfo interface 类型

本类型描述了一个文件，本类型被 Stat 和 Lstat 函数返回

type FileInfo interface {
	Name() string		// 文件的基础名称
	Size() int64		// 普通文件的字节长度；其它与所在系统相关
	Mode() FileMode		// 文件的 mode bit
	ModTime() time.time	// 修改时间
	IsDir() bool		// Mode().IsDir() 的缩写
	Sys() interface{}	// 底层数据源（可能返回 nil）
}


Lstat(name string) (FileInfo, error)
返回一个描述文件的 FileInfo 结构体
若文件是一个符号链接，则返回符号链接本身的 FileInfo
Lstat 不会回溯链接
若有一个错误，则其类型为 *PathError


Stat(name string) (FileInfo, error)
返回一个描述文件的 FileInfo 结构体
若有一个错误，则其类型为 *PathError



FileMode uint32 类型

一个 FileMode 表示了一个文件的 mode 和 权限 bit
由于在所有系统下，这些 bit 的定义都相同，所以文件的信息可以从一个系统移植入里另一个系统
并非有所的 bit 都适用于所有的系统
必须要存在的 bit 为目录的 ModeDir

定义的 file mode bit 是最高位的 FileMode
九位个最低位为标准的 Unix rwxrwxrwx 权限
这些 bit 的值应该被考虑为 公开 API 的部分，也可能会用在 wire protocols 或者磁盘表示中：
它们不可以被修改，但是新的 bit 可以被加入其中

const (
    // 单字母作为简写，被用于在
    // String 方法的格式化中
    ModeDir        FileMode = 1 << (32 - 1 - iota) // d: 是一个目录
    ModeAppend                                     // a: 仅追加
    ModeExclusive                                  // l: 排他用法
    ModeTemporary                                  // T: 临时文件；仅用于 Plan 9
    ModeSymlink                                    // L: 符号链接
    ModeDevice                                     // D: 设备文件
    ModeNamedPipe                                  // p: 命名的管道（FIFO）
    ModeSocket                                     // S: Unix 域套字节
    ModeSetuid                                     // u: setuid
    ModeSetgid                                     // g: setgid
    ModeCharDevice                                 // c: Unix 字符流设备，当 ModeDevice 设定时
    ModeSticky                                     // t: sticky

    // 类型的遮罩。对于普通文件，不会被设置
    ModeType = ModeDir | ModeSymlink | ModeNamedPipe | ModeSocket | ModeDevice

    ModePerm FileMode = 0777 // Unix 权限 bits
)


EG.

fi, err := os.Lstat("some-filename")
if err != nil {
    log.Fatal(err)
}

switch mode := fi.Mode(); {
case mode.IsRegular():
    fmt.Println("regular file")
case mode.IsDir():
    fmt.Println("directory")
case mode&os.ModeSymlink != 0:
    fmt.Println("symbolic link")
case mode&os.ModeNamedPipe != 0:
    fmt.Println("named pipe")
}


(m FileMode) IsDir() bool
报告 m 是否描述了一个目录
也就是，测试 ModeDir 这个 bit 是否在 m 中被设置了


(m FileMode) IsRegular() bool
报告 m 是否描述了一个普通文件
也就是，没有任何的 mode bit 被设置


(m FileMode) Perm() FileMode
返回 m 所具有的 Unix 权限 bit


(m FileMode) String() string
满足了 fmt.Stringer 接口



LinkError struct 类型

记录了一个在 链接系统调用 或者 符号链接系统调用 或者 重命名系统调用 时的错误，且包含产生该错误的路径

type LinkError struct {
	Op string
	Old string
	New string
	Err error
}


(e *LinkError) Error() string
满足了 error 内建接口类型



PathError struct 类型

记录了一个错误，以及产生这个错误的操作和文件路径

type PathError struct {
	Op string
	Path string
	Err error
}


func (e *PathError) Error() string
满足了 error 内建借口类型



ProcAttr struct 类型

持有一些属性，这些属性会被运用于即将被 StartProcess 函数启动的新进程上

type ProcAttr struct {
	// 若 Dir 非空，则子进程移动至该目录中后，再创建进程
	Dir string

	// 若 Env 非 nil，则基于新进程以环境变量
	// 该环境变量参考 Environ 函数的返回值的形式
	Env []string

	// 该字段指定新进程将要继承的打开的文件
	// 头三个条目为 标准输入/标准输出/标准错误
	// 鉴于不同的系统实现，会支持更多的附加条目
	// 一个用 nil 表示的条目，意味着对应的文件在进程启动时被关闭
	Files []*File

	// 操作系统特定的进程创建属性
	// 注意该字段的设置可能意味着你的程序在某些操作系统上，并不能正常运行，甚至正常编译
	Sys *syscall.SysProcAttr
}



Process struct 类型

该类型保存了 StartProcess 函数创建的新进程的信息

type Process struct {
	Pid int

	// 包含过滤掉或未导出的字段
}


FindProcess(pid int) (*Process, error)
通过 pid 查找一个运行中的进程

返回的 Process 可以用于持有底层操作系统的进程的信息

在 Unix 系统中，无论进程是否存在，FindProcess 总是成功，且返回给出 pid 的 Process 对象


StartProcess(name string, argv []string, attr *ProcAttr) (*Process, error)
启动一个新的进程，该进程的程序/参数/属性由 name argv attr 定义

本函数是一个底层的接口
os/exec 包提供了一个更高级的接口

若有一个错误，则其类型为 *PathError


(p *Process) Kill() error
立刻终止一个进程


(p *Process) Release() error
释放与 Process p 相关的任何资源，让它在未来展示为不可用状态
本方法仅在 Wait 无法调用，或调用失败时才需使用


(p *Process) Singnal(sig Signal) error
向 Process中传入一个信号
传送 Interrupt 在 Windows 上未实现


(p *Process) Wait() (*ProcessState, error)
等待一个 Process 退出，并返回一个描述进程状态的 ProcessState，以及任何产生的错误
本方法会释放任何与 Process 关联的资源
在大多数操作系统中，Process 必须是当前进程的一个子进程，否则会返回一个错误



ProcessState struct 类型

本类型存储了一个进程相关的信息，其被 Wait 所反馈

type ProcessState struct {
	// 包含过滤的或未导出的字段
}


(p *ProcessState) Exited() bool
报告程序是否已经退出


(p *ProcessState) Pid() int
返回退出的进程的 pid


(p *ProcessState) String() string
满足了 fmt.Stringer 接口


(p *ProcessState) Success() bool
报告程序是否成功退出
比如 Unix 上的 0 退出状态


(p *ProcessState) Sys() interface{}
返回系统相关的进程退出信息
转换其至适当的底层类型，比如在 Unix 上的 syscall.WaitStatus，来获取其内容


(p *ProcessState) SysUsage() interface{}
返回系统相关的退出进程的资源使用信息
转换其至适当的底层类型，比如在 Unix 上的 *syscall.Rusage，来获取其内容
（在 Unix 上， *syscall.Rusage 与 getrusage(2) 帮助手册中定义的 rusage 结构所匹配）


(p *ProcessState) SystemTime() time.Duration
返回退出的进程和其子进程的 系统 CPU 时间


(p *ProcessState) UserTime() time.Duration
返回退出的进程和其子进程的 用户 CPU 时间



Signal interface 类型

本类型表示系统信号
通常情况下，底层的实现是系统相关的：在 Unix 上，是 syscall.Signal

type Signal interface {
	String() string
	Signal() // 与其他的 Stringer 有所区分
}

仅有两个信号保证在全系统上都出现：Interrupt（向进程发送一个中断）以及 Kill（强制进程退出）

var (
	Interrupt	Signal = syscall.SIGINT
	Kill		Signal = syscall.SigKILL
)



SyscallError struct 类型

本类型从特定的系统调用中记录特定的错误

type SyscallError struct {
	Syscall string
	Err error
}


(e *SyscallError) Error() string
满足了 error 内建类型接口