Пакет os
Обзор
Пакет os предоставляет платформонезависимый интерфейс к функциям операционной системы. Его дизайн похож на Unix, хотя обработка ошибок характерна для Go: вызовы, завершившиеся ошибкой, возвращают значения типа error, а не номера ошибок. Часто в ошибке содержится дополнительная информация. Например, если завершается ошибкой вызов, принимающий имя файла, такой как Open или Stat, при выводе ошибка будет содержать имя файла, вызвавшего ошибку, и иметь тип *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
Затем данные файла можно прочитать в срез байтов. Read и Write получают количество байтов из длины среза-аргумента.
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])
Параллельное выполнение
Методы File соответствуют операциям файловой системы. Все они безопасны для параллельного использования. Максимальное число параллельных операций с File может быть ограничено ОС или системой. Обычно это число велико, но его превышение может снизить производительность или вызвать другие проблемы.
Указатель
Примеры
Файлы пакета
dir.go dir_unix.go dirent_linux.go eloop_other.go env.go error.go error_errno.go exec.go exec_linux.go exec_posix.go exec_unix.go executable.go executable_procfs.go file.go file_open_unix.go file_posix.go file_unix.go getwd.go path.go path_unix.go pidfd_linux.go pipe2_unix.go proc.go rawconn.go removeall_at.go removeall_unix.go root.go root_nonwindows.go root_openat.go root_unix.go stat.go stat_linux.go stat_unix.go statat.go statat_unix.go sticky_notbsd.go sys.go sys_linux.go sys_unix.go tempfile.go types.go types_unix.go wait_waitid.go zero_copy_linux.go zero_copy_posix.go
Константы
Флаги для OpenFile, оборачивающие флаги нижележащей системы. Не все флаги могут поддерживаться в конкретной системе.
const (
// Exactly one of O_RDONLY, O_WRONLY, or O_RDWR must be specified.
O_RDONLY int = syscall.O_RDONLY // open the file read-only.
O_WRONLY int = syscall.O_WRONLY // open the file write-only.
O_RDWR int = syscall.O_RDWR // open the file read-write.
// The remaining values may be or'ed in to control behavior.
O_APPEND int = syscall.O_APPEND // append data to the file when writing.
O_CREATE int = syscall.O_CREAT // create a new file if none exists.
O_EXCL int = syscall.O_EXCL // used with O_CREATE, file must not exist.
O_SYNC int = syscall.O_SYNC // open for synchronous I/O.
O_TRUNC int = syscall.O_TRUNC // truncate regular writable file when opened.
) Значения whence для Seek.
Устарело: используйте io.SeekStart, io.SeekCurrent и io.SeekEnd.
const (
SEEK_SET int = 0 // seek relative to the origin of the file
SEEK_CUR int = 1 // seek relative to the current offset
SEEK_END int = 2 // seek relative to the end
) const (
PathSeparator = '/' // OS-specific path separator
PathListSeparator = ':' // OS-specific path list separator
) Определенные биты режима файла являются старшими битами FileMode. Девять младших битов соответствуют стандартным разрешениям Unix rwxrwxrwx. Эти значения следует считать частью публичного API; они могут использоваться в сетевых протоколах или представлениях на диске, поэтому их нельзя изменять, хотя могут быть добавлены новые биты.
const (
// The single letters are the abbreviations
// used by the String method's formatting.
ModeDir = fs.ModeDir // d: is a directory
ModeAppend = fs.ModeAppend // a: append-only
ModeExclusive = fs.ModeExclusive // l: exclusive use
ModeTemporary = fs.ModeTemporary // T: temporary file; Plan 9 only
ModeSymlink = fs.ModeSymlink // L: symbolic link
ModeDevice = fs.ModeDevice // D: device file
ModeNamedPipe = fs.ModeNamedPipe // p: named pipe (FIFO)
ModeSocket = fs.ModeSocket // S: Unix domain socket
ModeSetuid = fs.ModeSetuid // u: setuid
ModeSetgid = fs.ModeSetgid // g: setgid
ModeCharDevice = fs.ModeCharDevice // c: Unix character device, when ModeDevice is set
ModeSticky = fs.ModeSticky // t: sticky
ModeIrregular = fs.ModeIrregular // ?: non-regular file; nothing else is known about this file
// Mask for the type bits. For regular files, none will be set.
ModeType = fs.ModeType
ModePerm = fs.ModePerm // Unix permission bits, 0o777
) DevNull — это имя «нулевого устройства» операционной системы. В Unix-подобных системах это "/dev/null", а в Windows — "NUL".
const DevNull = "/dev/null"
Переменные
Переносимые аналоги некоторых распространенных ошибок системных вызовов.
Ошибки, возвращаемые этим пакетом, можно проверять на соответствие этим ошибкам с помощью errors.Is.
var (
// ErrInvalid indicates an invalid argument.
// Methods on File will return this error when the receiver is nil.
ErrInvalid = fs.ErrInvalid // "invalid argument"
ErrPermission = fs.ErrPermission // "permission denied"
ErrExist = fs.ErrExist // "file already exists"
ErrNotExist = fs.ErrNotExist // "file does not exist"
ErrClosed = fs.ErrClosed // "file already closed"
ErrNoDeadline = errNoDeadline() // "file type does not support deadline"
ErrDeadlineExceeded = errDeadlineExceeded() // "i/o timeout"
) var (
// ErrProcessDone indicates a [Process] has finished.
ErrProcessDone = errors.New("os: process already finished")
// ErrNoHandle indicates a [Process] does not have a handle.
ErrNoHandle = errors.New("os: process handle unavailable")
) Stdin, Stdout и Stderr — это открытые Files, указывающие на дескрипторы стандартного ввода, стандартного вывода и стандартного вывода ошибок.
Обратите внимание, что среда выполнения Go записывает сообщения о паниках и аварийном завершении в стандартный поток ошибок; закрытие 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
func Chdir(dir string) error
Chdir изменяет текущий рабочий каталог на указанный каталог. В случае ошибки она будет иметь тип *PathError.
функция Chmod
func Chmod(name string, mode FileMode) error
Chmod изменяет режим указанного файла на mode. Если файл является символической ссылкой, функция изменяет режим целевого объекта ссылки. В случае ошибки она будет иметь тип *PathError.
В зависимости от операционной системы используется разный набор битов режима.
В Unix используются биты разрешений mode, ModeSetuid, ModeSetgid и ModeSticky.
В Windows используется только бит 0o200 (запись владельцем) параметра mode; он управляет установкой или снятием атрибута файла «только для чтения». Остальные биты в настоящее время не используются. Для совместимости с Go 1.12 и более ранними версиями используйте ненулевое значение mode. Используйте mode 0o400 для файла только для чтения и 0o600 для файла, доступного для чтения и записи.
В Plan 9 используются биты разрешений mode, ModeAppend, ModeExclusive и ModeTemporary.
Пример
Код:
if err := os.Chmod("some-filename", 0644); err != nil {
log.Fatal(err)
}
функция Chown
func Chown(name string, uid, gid int) error
Chown изменяет числовые uid и gid указанного файла. Если файл является символической ссылкой, функция изменяет uid и gid целевого объекта ссылки. Значение uid или gid, равное -1, означает, что это значение не нужно изменять. В случае ошибки она будет иметь тип *PathError.
В Windows или Plan 9 Chown всегда возвращает ошибку syscall.EWINDOWS или syscall.EPLAN9, обернутую в *PathError.
функция Chtimes
func Chtimes(name string, atime time.Time, mtime time.Time) error
Chtimes изменяет время доступа и время модификации указанного файла, аналогично функциям Unix utime() или utimes(). Нулевое значение time.Time оставляет соответствующее время файла неизменным.
Нижележащая файловая система может усекать или округлять значения до менее точной единицы времени. В случае ошибки она будет иметь тип *PathError.
Пример
Код:
mtime := time.Date(2006, time.February, 1, 3, 4, 5, 0, time.UTC)
atime := time.Date(2007, time.March, 2, 4, 5, 6, 0, time.UTC)
if err := os.Chtimes("some-filename", atime, mtime); err != nil {
log.Fatal(err)
}
функция Clearenv
func Clearenv()
Clearenv удаляет все переменные окружения.
функция CopyFS 1.23
func CopyFS(dir string, fsys fs.FS) error
CopyFS копирует файловую систему fsys в каталог dir, создавая dir при необходимости.
Файлы создаются с режимом 0o666 и всеми разрешениями на выполнение из источника, а каталоги — с режимом 0o777 (до применения umask).
CopyFS не перезаписывает существующие файлы. Если имя файла из fsys уже существует в каталоге назначения, CopyFS вернет ошибку, для которой errors.Is(err, fs.ErrExist) будет истинным.
Символические ссылки в dir обрабатываются по целевым объектам.
Не гарантируется копирование новых файлов, добавленных в fsys во время выполнения CopyFS (в том числе если dir является подкаталогом fsys).
Копирование прекращается при первой обнаруженной ошибке и возвращает ее.
функция DirFS 1.16
func DirFS(dir string) fs.FS
DirFS возвращает файловую систему (fs.FS) для дерева файлов, корнем которого является каталог dir.
Обратите внимание: DirFS("/prefix") гарантирует только, что вызовы Open, выполняемые ею в операционной системе, будут начинаться с "/prefix": DirFS("/prefix").Open("file") эквивалентен os.Open("/prefix/file"). Поэтому, если /prefix/file — символическая ссылка, указывающая за пределы дерева /prefix, использование DirFS не ограничивает доступ сильнее, чем использование os.Open. Кроме того, корень fs.FS, возвращаемой для относительного пути DirFS("prefix"), будет зависеть от последующих вызовов Chdir. Поэтому DirFS не является универсальной заменой механизма безопасности в стиле chroot, если дерево каталогов содержит произвольное содержимое.
Используйте Root.FS, чтобы получить fs.FS, которая предотвращает выход за пределы дерева через символические ссылки.
Каталог dir не должен быть равен "".
Результат реализует интерфейсы io/fs.StatFS, io/fs.ReadFileFS, io/fs.ReadDirFS и io/fs.ReadLinkFS.
функция Environ
func Environ() []string
Environ возвращает копию строк, представляющих окружение в формате "key=value".
функция Executable 1.8
func Executable() (string, error)
Executable возвращает путь к исполняемому файлу, запустившему текущий процесс. Нет гарантии, что этот путь по-прежнему указывает на правильный исполняемый файл. Если для запуска процесса использовалась символическая ссылка, то в зависимости от операционной системы результатом может быть сама ссылка или путь, на который она указывает. Если требуется стабильный результат, может помочь path/filepath.EvalSymlinks.
Executable возвращает абсолютный путь, если не произошла ошибка.
Основной вариант использования — поиск ресурсов, расположенных относительно исполняемого файла.
функция Exit
func Exit(code int)
Exit завершает работу текущей программы с указанным кодом состояния. По соглашению нулевой код означает успех, а ненулевой — ошибку. Программа завершается немедленно; отложенные функции не выполняются.
Для переносимости код состояния должен находиться в диапазоне [0, 125].
функция Expand
func Expand(s string, mapping func(string) string) string
Expand заменяет в строке ${var} или $var, используя функцию сопоставления. Например, os.ExpandEnv(s) эквивалентно os.Expand(s, os.Getenv).
Пример
Код:
mapper := func(placeholderName string) string {
switch placeholderName {
case "DAY_PART":
return "morning"
case "NAME":
return "Gopher"
}
return ""
}
fmt.Println(os.Expand("Good ${DAY_PART}, $NAME!", mapper))
Вывод:
Good morning, Gopher!
функция ExpandEnv
func ExpandEnv(s string) string
ExpandEnv заменяет в строке ${var} или $var значениями текущих переменных окружения. Ссылки на неопределенные переменные заменяются пустой строкой.
Пример
Код:
os.Setenv("NAME", "gopher")
os.Setenv("BURROW", "/usr/gopher")
fmt.Println(os.ExpandEnv("$NAME lives in ${BURROW}."))
Вывод:
gopher lives in /usr/gopher.
функция Getegid
func Getegid() int
Getegid возвращает числовой эффективный идентификатор группы вызывающего процесса.
В Windows возвращается -1.
функция Getenv
func Getenv(key string) string
Getenv получает значение переменной окружения с именем key. Функция возвращает значение, которое будет пустым, если переменная отсутствует. Чтобы отличить пустое значение от неустановленного, используйте LookupEnv.
Пример
Код:
os.Setenv("NAME", "gopher")
os.Setenv("BURROW", "/usr/gopher")
fmt.Printf("%s lives in %s.\n", os.Getenv("NAME"), os.Getenv("BURROW"))
Вывод:
gopher lives in /usr/gopher.
функция Geteuid
func Geteuid() int
Geteuid возвращает числовой эффективный идентификатор пользователя вызывающего процесса.
В Windows возвращается -1.
функция Getgid
func Getgid() int
Getgid возвращает числовой идентификатор группы вызывающего процесса.
В Windows возвращается -1.
функция Getgroups
func Getgroups() ([]int, error)
Getgroups возвращает список числовых идентификаторов групп, к которым принадлежит вызывающий процесс.
В Windows возвращается syscall.EWINDOWS. Возможную альтернативу см. в пакете os/user.
функция Getpagesize
func Getpagesize() int
Getpagesize возвращает размер страницы памяти нижележащей системы.
функция Getpid
func Getpid() int
Getpid возвращает идентификатор вызывающего процесса.
функция Getppid
func Getppid() int
Getppid возвращает идентификатор родительского процесса вызывающего процесса.
функция Getuid
func Getuid() int
Getuid возвращает числовой идентификатор пользователя вызывающего процесса.
В Windows возвращается -1.
функция Getwd
func Getwd() (dir string, err error)
Getwd возвращает абсолютный путь к текущему каталогу. Если к текущему каталогу можно обратиться по нескольким путям (из-за символических ссылок), Getwd может вернуть любой из них.
На платформах Unix возвращается абсолютное имя из переменной окружения PWD, если оно задано и обозначает текущий каталог.
функция Hostname
func Hostname() (name string, err error)
Hostname возвращает имя хоста, сообщаемое ядром.
функция IsExist
func IsExist(err error) bool
IsExist возвращает логическое значение, указывающее, известно ли, что его аргумент сообщает о существовании файла или каталога. Функция возвращает true для ErrExist, а также для некоторых ошибок системных вызовов.
Эта функция появилась до errors.Is. Она поддерживает только ошибки, возвращаемые пакетом os. В новом коде следует использовать errors.Is(err, fs.ErrExist).
функция IsNotExist
func IsNotExist(err error) bool
IsNotExist возвращает логическое значение, указывающее, известно ли, что его аргумент сообщает об отсутствии файла или каталога. Функция возвращает true для ErrNotExist, а также для некоторых ошибок системных вызовов.
Эта функция появилась до errors.Is. Она поддерживает только ошибки, возвращаемые пакетом os. В новом коде следует использовать errors.Is(err, fs.ErrNotExist).
функция IsPathSeparator
func IsPathSeparator(c uint8) bool
IsPathSeparator сообщает, является ли c символом-разделителем каталогов.
функция IsPermission
func IsPermission(err error) bool
IsPermission возвращает логическое значение, указывающее, известно ли, что его аргумент сообщает об отказе в разрешении. Функция возвращает true для ErrPermission, а также для некоторых ошибок системных вызовов.
Эта функция появилась до errors.Is. Она поддерживает только ошибки, возвращаемые пакетом os. В новом коде следует использовать errors.Is(err, fs.ErrPermission).
функция IsTimeout 1.10
func IsTimeout(err error) bool
IsTimeout возвращает логическое значение, указывающее, известно ли, что его аргумент сообщает о возникновении тайм-аута.
Эта функция появилась до errors.Is, а понятие ошибки, указывающей на тайм-аут, может быть неоднозначным. Например, ошибка Unix EWOULDBLOCK иногда означает тайм-аут, а иногда нет. В новом коде следует использовать errors.Is со значением, подходящим для вызова, вернувшего ошибку, например os.ErrDeadlineExceeded.
функция Lchown
func Lchown(name string, uid, gid int) error
Lchown изменяет числовые uid и gid указанного файла. Если файл является символической ссылкой, функция изменяет uid и gid самой ссылки. В случае ошибки она будет иметь тип *PathError.
В Windows функция всегда возвращает ошибку syscall.EWINDOWS, обернутую в *PathError.
функция Link
func Link(oldname, newname string) error
Link создает newname как жесткую ссылку на файл oldname. В случае ошибки она будет иметь тип *LinkError.
функция LookupEnv 1.5
func LookupEnv(key string) (string, bool)
LookupEnv получает значение переменной окружения с именем key. Если переменная присутствует в окружении, возвращаются ее значение (которое может быть пустым) и логическое значение true. В противном случае возвращаются пустое значение и логическое значение false.
Пример
Код:
show := func(key string) {
val, ok := os.LookupEnv(key)
if !ok {
fmt.Printf("%s not set\n", key)
} else {
fmt.Printf("%s=%s\n", key, val)
}
}
os.Setenv("SOME_KEY", "value")
os.Setenv("EMPTY_KEY", "")
show("SOME_KEY")
show("EMPTY_KEY")
show("MISSING_KEY")
Вывод:
SOME_KEY=value EMPTY_KEY= MISSING_KEY not set
функция Mkdir
func Mkdir(name string, perm FileMode) error
Mkdir создает каталог с указанным именем и битами разрешений (до применения umask). В случае ошибки она будет иметь тип *PathError.
Пример
Код:
err := os.Mkdir("testdir", 0750)
if err != nil && !os.IsExist(err) {
log.Fatal(err)
}
err = os.WriteFile("testdir/testfile.txt", []byte("Hello, Gophers!"), 0660)
if err != nil {
log.Fatal(err)
}
функция MkdirAll
func MkdirAll(path string, perm FileMode) error
MkdirAll создает каталог с именем path вместе со всеми необходимыми родительскими каталогами и возвращает nil либо ошибку. Биты разрешений perm (до применения umask) используются для всех каталогов, создаваемых MkdirAll. Если path уже является каталогом, MkdirAll ничего не делает и возвращает nil.
Пример
Код:
err := os.MkdirAll("test/subdir", 0750)
if err != nil {
log.Fatal(err)
}
err = os.WriteFile("test/subdir/testfile.txt", []byte("Hello, Gophers!"), 0660)
if err != nil {
log.Fatal(err)
}
функция MkdirTemp 1.16
func MkdirTemp(dir, pattern string) (string, error)
MkdirTemp создает новый временный каталог в каталоге dir и возвращает путь к нему. Имя нового каталога генерируется добавлением случайной строки в конец pattern. Если pattern содержит "*", случайная строка заменяет последнюю "*". Каталог создается с режимом 0o700 (до применения umask). Если dir — пустая строка, MkdirTemp использует каталог для временных файлов по умолчанию, возвращаемый TempDir. Несколько программ или горутин, одновременно вызывающих MkdirTemp, не выберут один и тот же каталог. Вызывающий код должен удалить каталог, когда он больше не нужен.
Пример
Код:
dir, err := os.MkdirTemp("", "example")
if err != nil {
log.Fatal(err)
}
defer os.RemoveAll(dir) // clean up
file := filepath.Join(dir, "tmpfile")
if err := os.WriteFile(file, []byte("content"), 0666); err != nil {
log.Fatal(err)
}
Пример (суффикс)
Код:
logsDir, err := os.MkdirTemp("", "*-logs")
if err != nil {
log.Fatal(err)
}
defer os.RemoveAll(logsDir) // clean up
// Logs can be cleaned out earlier if needed by searching
// for all directories whose suffix ends in *-logs.
globPattern := filepath.Join(os.TempDir(), "*-logs")
matches, err := filepath.Glob(globPattern)
if err != nil {
log.Fatalf("Failed to match %q: %v", globPattern, err)
}
for _, match := range matches {
if err := os.RemoveAll(match); err != nil {
log.Printf("Failed to remove %q: %v", match, err)
}
}
функция NewSyscallError
func NewSyscallError(syscall string, err error) error
NewSyscallError возвращает в виде ошибки новый SyscallError с указанным именем системного вызова и сведениями об ошибке. Для удобства, если err равен nil, NewSyscallError возвращает nil.
функция Pipe
func Pipe() (r *File, w *File, err error)
Pipe возвращает пару связанных Files: чтение из r возвращает байты, записанные в w. Функция возвращает файлы и, если возникла ошибка, эту ошибку.
функция ReadFile 1.16
func ReadFile(name string) ([]byte, error)
ReadFile считывает указанный файл и возвращает его содержимое. При успешном вызове возвращается err == nil, а не err == EOF. Поскольку ReadFile считывает файл целиком, EOF, полученный от Read, не считается ошибкой, о которой нужно сообщать. Если возникает ошибка, она будет иметь тип *PathError.
Пример
Код:
data, err := os.ReadFile("testdata/hello")
if err != nil {
log.Fatal(err)
}
os.Stdout.Write(data)
Вывод:
Hello, Gophers!
func Readlink
func Readlink(name string) (string, error)
Readlink возвращает назначение указанной символической ссылки. Если возникает ошибка, она будет иметь тип *PathError.
Если назначение ссылки является относительным, Readlink возвращает относительный путь, не преобразуя его в абсолютный.
Пример
Код:
// First, we create a relative symlink to a file.
d, err := os.MkdirTemp("", "")
if err != nil {
log.Fatal(err)
}
defer os.RemoveAll(d)
targetPath := filepath.Join(d, "hello.txt")
if err := os.WriteFile(targetPath, []byte("Hello, Gophers!"), 0644); err != nil {
log.Fatal(err)
}
linkPath := filepath.Join(d, "hello.link")
if err := os.Symlink("hello.txt", filepath.Join(d, "hello.link")); err != nil {
if isOSSymlinkUnsupportedError(err) {
// Allow the example to run on platforms that do not support symbolic links.
fmt.Printf("%s links to %s\n", filepath.Base(linkPath), "hello.txt")
return
}
log.Fatal(err)
}
// Readlink returns the relative path as passed to os.Symlink.
dst, err := os.Readlink(linkPath)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s links to %s\n", filepath.Base(linkPath), dst)
var dstAbs string
if filepath.IsAbs(dst) {
dstAbs = dst
} else {
// Symlink targets are relative to the directory containing the link.
dstAbs = filepath.Join(filepath.Dir(linkPath), dst)
}
// Check that the target is correct by comparing it with os.Stat
// on the original target path.
dstInfo, err := os.Stat(dstAbs)
if err != nil {
log.Fatal(err)
}
targetInfo, err := os.Stat(targetPath)
if err != nil {
log.Fatal(err)
}
if !os.SameFile(dstInfo, targetInfo) {
log.Fatalf("link destination (%s) is not the same file as %s", dstAbs, targetPath)
}
Вывод:
hello.link links to hello.txt
func Remove
func Remove(name string) error
Remove удаляет указанный файл или (пустой) каталог. Если возникает ошибка, она будет иметь тип *PathError.
func RemoveAll
func RemoveAll(path string) error
RemoveAll удаляет путь и все его дочерние элементы. Функция удаляет всё, что может, но возвращает первую обнаруженную ошибку. Если путь не существует, RemoveAll возвращает nil (ошибки нет). Если возникает ошибка, она будет иметь тип *PathError.
func Rename
func Rename(oldpath, newpath string) error
Rename переименовывает (перемещает) oldpath в newpath. Если newpath уже существует и не является каталогом, Rename заменяет его. Если newpath уже существует и является каталогом, Rename возвращает ошибку. Если oldpath и newpath находятся в разных каталогах, могут применяться ограничения, зависящие от ОС. Даже в пределах одного каталога Rename не является атомарной операцией на платформах, отличных от Unix. Если возникает ошибка, она будет иметь тип *LinkError.
func SameFile
func SameFile(fi1, fi2 FileInfo) bool
SameFile сообщает, описывают ли fi1 и fi2 один и тот же файл. Например, в Unix это означает, что поля устройства и inode в двух соответствующих структурах идентичны; в других системах решение может основываться на именах путей. SameFile применима только к результатам, возвращаемым функцией Stat этого пакета. В остальных случаях она возвращает false.
func Setenv
func Setenv(key, value string) error
Setenv задаёт значение переменной окружения, указанной ключом. Функция возвращает ошибку, если она возникла.
func Symlink
func Symlink(oldname, newname string) error
Symlink создаёт newname как символическую ссылку на oldname. В Windows символическая ссылка на несуществующий oldname создаёт файловую символическую ссылку; если позднее oldname будет создан как каталог, ссылка работать не будет. Если возникает ошибка, она будет иметь тип *LinkError.
func TempDir
func TempDir() string
TempDir возвращает каталог по умолчанию для временных файлов.
В системах Unix функция возвращает $TMPDIR, если он не пуст, иначе /tmp. В Windows она использует GetTempPath и возвращает первое непустое значение из %TMP%, %TEMP%, %USERPROFILE% или каталога Windows. В Plan 9 она возвращает /tmp.
Не гарантируется, что каталог существует или что к нему есть доступ.
func Truncate
func Truncate(name string, size int64) error
Truncate изменяет размер указанного файла. Если файл является символической ссылкой, функция изменяет размер её целевого файла. Если возникает ошибка, она будет иметь тип *PathError.
func Unsetenv 1.4
func Unsetenv(key string) error
Unsetenv удаляет одну переменную окружения.
Пример
Код:
os.Setenv("TMPDIR", "/my/tmp")
defer os.Unsetenv("TMPDIR")
func UserCacheDir 1.11
func UserCacheDir() (string, error)
UserCacheDir возвращает корневой каталог по умолчанию для кэшированных данных пользователя. Пользователям следует создать в нём собственный подкаталог для конкретного приложения и использовать его.
В системах Unix функция возвращает $XDG_CACHE_HOME, указанный в https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html, если он не пуст, иначе $HOME/.cache. В Darwin она возвращает $HOME/Library/Caches. В Windows она возвращает %LocalAppData%. В Plan 9 она возвращает $home/lib/cache.
Если расположение невозможно определить (например, если $HOME не задан) или путь в $XDG_CACHE_HOME является относительным, функция вернёт ошибку.
Пример
Код:
dir, dirErr := os.UserCacheDir()
if dirErr == nil {
dir = filepath.Join(dir, "ExampleUserCacheDir")
}
getCache := func(name string) ([]byte, error) {
if dirErr != nil {
return nil, &os.PathError{Op: "getCache", Path: name, Err: os.ErrNotExist}
}
return os.ReadFile(filepath.Join(dir, name))
}
var mkdirOnce sync.Once
putCache := func(name string, b []byte) error {
if dirErr != nil {
return &os.PathError{Op: "putCache", Path: name, Err: dirErr}
}
mkdirOnce.Do(func() {
if err := os.MkdirAll(dir, 0700); err != nil {
log.Printf("can't create user cache dir: %v", err)
}
})
return os.WriteFile(filepath.Join(dir, name), b, 0600)
}
// Read and store cached data.
// …
_ = getCache
_ = putCache
func UserConfigDir 1.13
func UserConfigDir() (string, error)
UserConfigDir возвращает корневой каталог по умолчанию для данных конфигурации пользователя. Пользователям следует создать в нём собственный подкаталог для конкретного приложения и использовать его.
В системах Unix функция возвращает $XDG_CONFIG_HOME, указанный в https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html, если он не пуст, иначе $HOME/.config. В Darwin она возвращает $HOME/Library/Application Support. В Windows она возвращает %AppData%. В Plan 9 она возвращает $home/lib.
Если расположение невозможно определить (например, если $HOME не задан) или путь в $XDG_CONFIG_HOME является относительным, функция вернёт ошибку.
Пример
Код:
dir, dirErr := os.UserConfigDir()
var (
configPath string
origConfig []byte
)
if dirErr == nil {
configPath = filepath.Join(dir, "ExampleUserConfigDir", "example.conf")
var err error
origConfig, err = os.ReadFile(configPath)
if err != nil && !os.IsNotExist(err) {
// The user has a config file but we couldn't read it.
// Report the error instead of ignoring their configuration.
log.Fatal(err)
}
}
// Use and perhaps make changes to the config.
config := bytes.Clone(origConfig)
// …
// Save changes.
if !bytes.Equal(config, origConfig) {
if configPath == "" {
log.Printf("not saving config changes: %v", dirErr)
} else {
err := os.MkdirAll(filepath.Dir(configPath), 0700)
if err == nil {
err = os.WriteFile(configPath, config, 0600)
}
if err != nil {
log.Printf("error saving config changes: %v", err)
}
}
}
func UserHomeDir 1.12
func UserHomeDir() (string, error)
UserHomeDir возвращает домашний каталог текущего пользователя.
В Unix, включая macOS, функция возвращает переменную окружения $HOME. В Windows она возвращает %USERPROFILE%. В Plan 9 она возвращает переменную окружения $home.
Если ожидаемая переменная не задана в окружении, UserHomeDir возвращает либо значение по умолчанию, зависящее от платформы, либо ненулевую ошибку.
func WriteFile 1.16
func WriteFile(name string, data []byte, perm FileMode) error
WriteFile записывает данные в указанный файл, создавая его при необходимости. Если файл не существует, WriteFile создаёт его с разрешениями perm (до применения umask); в противном случае WriteFile очищает его перед записью, не изменяя разрешения. Поскольку для выполнения WriteFile требуется несколько системных вызовов, сбой в процессе операции может оставить файл записанным лишь частично.
Пример
Код:
err := os.WriteFile("testdata/hello", []byte("Hello, Gophers!"), 0666)
if err != nil {
log.Fatal(err)
}
type DirEntry 1.16
DirEntry — это запись, полученная из каталога (с помощью функции ReadDir или метода File.ReadDir).
type DirEntry = fs.DirEntry
func ReadDir 1.16
func ReadDir(name string) ([]DirEntry, error)
ReadDir считывает указанный каталог и возвращает все его записи, отсортированные по имени файла. Если при чтении каталога возникает ошибка, ReadDir возвращает записи, которые удалось прочитать до её возникновения, вместе с ошибкой.
Пример
Код:
files, err := os.ReadDir(".")
if err != nil {
log.Fatal(err)
}
for _, file := range files {
fmt.Println(file.Name())
}
type File
File представляет открытый файловый дескриптор.
Методы File безопасны для одновременного использования.
type File struct {
// contains filtered or unexported fields
}
func Create
func Create(name string) (*File, error)
Create создаёт указанный файл или очищает его содержимое. Если файл уже существует, его содержимое очищается. Если файл не существует, он создаётся с режимом 0o666 (до применения umask). При успехе методы возвращённого File можно использовать для ввода-вывода; связанный файловый дескриптор имеет режим O_RDWR. Каталог, содержащий файл, уже должен существовать. Если возникает ошибка, она будет иметь тип *PathError.
func CreateTemp 1.16
func CreateTemp(dir, pattern string) (*File, error)
CreateTemp создаёт новый временный файл в каталоге dir, открывает его для чтения и записи и возвращает созданный файл. Имя файла формируется добавлением случайной строки в конец pattern. Если pattern содержит символ "*", случайная строка заменяет последний "*". Файл создаётся с режимом 0o600 (до применения umask). Если dir — пустая строка, CreateTemp использует каталог временных файлов по умолчанию, возвращаемый функцией TempDir. Несколько программ или горутин, одновременно вызывающих CreateTemp, не выберут один и тот же файл. Вызывающий код может использовать метод Name файла, чтобы получить путь к нему. Вызывающий код отвечает за удаление файла, когда он больше не нужен.
Пример
Код:
f, err := os.CreateTemp("", "example")
if err != nil {
log.Fatal(err)
}
defer os.Remove(f.Name()) // clean up
if _, err := f.Write([]byte("content")); err != nil {
log.Fatal(err)
}
if err := f.Close(); err != nil {
log.Fatal(err)
}
Пример (суффикс)
Код:
f, err := os.CreateTemp("", "example.*.txt")
if err != nil {
log.Fatal(err)
}
defer os.Remove(f.Name()) // clean up
if _, err := f.Write([]byte("content")); err != nil {
f.Close()
log.Fatal(err)
}
if err := f.Close(); err != nil {
log.Fatal(err)
}
func NewFile
func NewFile(fd uintptr, name string) *File
NewFile возвращает новый File с заданными файловым дескриптором и именем. Возвращаемое значение будет равно nil, если fd не является допустимым файловым дескриптором.
Поведение NewFile различается на некоторых платформах:
- В Unix, если fd работает в неблокирующем режиме, NewFile попытается вернуть опрашиваемый файл.
- В Windows, если fd открыт для асинхронного ввода-вывода (то есть в вызове syscall.CreateFile был указан syscall.FILE_FLAG_OVERLAPPED), NewFile попытается вернуть опрашиваемый файл, связав fd с портом завершения операций ввода-вывода среды выполнения Go. Если связать их не удастся, операции ввода-вывода будут выполняться синхронно.
Только опрашиваемые файлы поддерживают File.SetDeadline, File.SetReadDeadline и File.SetWriteDeadline.
После передачи fd в NewFile он может стать недействительным при тех же условиях, что описаны в комментариях к File.Fd; действуют те же ограничения.
func Open
func Open(name string) (*File, error)
Open открывает указанный файл для чтения. При успехе методы возвращённого файла можно использовать для чтения; связанный файловый дескриптор имеет режим O_RDONLY. Если возникает ошибка, она будет иметь тип *PathError.
func OpenFile
func OpenFile(name string, flag int, perm FileMode) (*File, error)
OpenFile — это универсальный вызов для открытия файлов; большинство пользователей будут использовать вместо него Open или Create. Функция открывает указанный файл с заданным флагом (O_RDONLY и т. д.). Если файл не существует и передан флаг O_CREATE, он создаётся с режимом perm (до применения umask); содержащий его каталог должен существовать. При успехе методы возвращённого File можно использовать для ввода-вывода. Если возникает ошибка, она будет иметь тип *PathError.
Пример
Код:
f, err := os.OpenFile("notes.txt", os.O_RDWR|os.O_CREATE, 0644)
if err != nil {
log.Fatal(err)
}
if err := f.Close(); err != nil {
log.Fatal(err)
}
Пример (добавление в конец)
Код:
// If the file doesn't exist, create it, or append to the file
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 {
f.Close() // ignore error; Write error takes precedence
log.Fatal(err)
}
if err := f.Close(); err != nil {
log.Fatal(err)
}
func OpenInRoot 1.24
func OpenInRoot(dir, name string) (*File, error)
OpenInRoot открывает файл с именем name в каталоге dir. Это эквивалентно вызову OpenRoot(dir), а затем открытию файла в корневом каталоге.
OpenInRoot возвращает ошибку, если какой-либо компонент имени указывает на расположение за пределами dir.
Подробности и ограничения см. в описании Root.
func (*File) Chdir
func (f *File) Chdir() error
Chdir изменяет текущий рабочий каталог на каталог, представленный файлом. Файл должен быть каталогом. Если возникает ошибка, она будет иметь тип *PathError.
func (*File) Chmod
func (f *File) Chmod(mode FileMode) error
Chmod изменяет режим файла на mode. Если возникает ошибка, она будет иметь тип *PathError.
func (*File) Chown
func (f *File) Chown(uid, gid int) error
Chown изменяет числовые uid и gid указанного файла. Если возникает ошибка, она будет иметь тип *PathError.
В Windows функция всегда возвращает ошибку syscall.EWINDOWS, обёрнутую в *PathError.
func (*File) Close
func (f *File) Close() error
Close закрывает File, делая его непригодным для ввода-вывода. Для файлов, поддерживающих File.SetDeadline, все ожидающие операции ввода-вывода будут отменены и немедленно вернут ошибку ErrClosed. Close вернёт ошибку, если метод уже вызывался.
func (*File) Fd
func (f *File) Fd() uintptr
Fd возвращает системный файловый дескриптор или дескриптор, ссылающийся на открытый файл. Если f закрыт, дескриптор становится недействительным. Если f будет удалён сборщиком мусора, финализатор может закрыть дескриптор, сделав его недействительным; дополнительные сведения о том, когда может быть запущен финализатор, см. в описании runtime.SetFinalizer.
Не закрывайте возвращённый дескриптор: это может привести к тому, что при последующем закрытии f будет закрыт другой, не связанный с ним дескриптор.
Поведение Fd различается на некоторых платформах:
- В Unix и Windows методы File.SetDeadline перестанут работать.
- В Windows файловый дескриптор будет отвязан от порта завершения операций ввода-вывода среды выполнения Go, если с файлом не выполняются параллельные операции ввода-вывода.
Для большинства задач предпочтительно использовать метод f.SyscallConn.
func (*File) Name
func (f *File) Name() string
Name возвращает имя файла в том виде, в котором оно было передано в Open.
Метод Name можно безопасно вызывать после [Close].
func (*File) Read
func (f *File) Read(b []byte) (n int, err error)
Read считывает из File до len(b) байт и сохраняет их в b. Метод возвращает количество прочитанных байт и возникшую ошибку, если она есть. В конце файла Read возвращает 0, io.EOF.
func (*File) ReadAt
func (f *File) ReadAt(b []byte, off int64) (n int, err error)
ReadAt считывает len(b) байт из File, начиная со смещения off в байтах. Метод возвращает количество прочитанных байт и ошибку, если она есть. ReadAt всегда возвращает ненулевую ошибку, если n < len(b). В конце файла этой ошибкой будет io.EOF.
func (*File) ReadDir 1.16
func (f *File) ReadDir(n int) ([]DirEntry, error)
ReadDir считывает содержимое каталога, связанного с файлом f, и возвращает срез значений DirEntry в порядке следования записей в каталоге. Последующие вызовы для того же файла будут возвращать более поздние записи DirEntry из каталога.
Если n > 0, ReadDir возвращает не более n записей DirEntry. В этом случае, если ReadDir возвращает пустой срез, метод также вернёт ошибку с объяснением причины. В конце каталога ошибкой будет io.EOF.
Если n <= 0, ReadDir возвращает все оставшиеся записи DirEntry из каталога. При успешном выполнении метод возвращает nil в качестве ошибки (а не io.EOF).
func (*File) ReadFrom 1.15
func (f *File) ReadFrom(r io.Reader) (n int64, err error)
ReadFrom реализует io.ReaderFrom.
func (*File) Readdir
func (f *File) Readdir(n int) ([]FileInfo, error)
Readdir считывает содержимое каталога, связанного с файлом, и возвращает срез из не более чем n значений FileInfo в порядке следования записей в каталоге, как если бы они были возвращены функцией Lstat. Последующие вызовы для того же файла будут возвращать следующие значения FileInfo.
Если n > 0, Readdir возвращает не более n структур FileInfo. В этом случае, если Readdir возвращает пустой срез, метод вернёт ненулевую ошибку с объяснением причины. В конце каталога ошибкой будет io.EOF.
Если n <= 0, Readdir возвращает все значения FileInfo из каталога в одном срезе. В этом случае при успешном выполнении Readdir (если чтение дошло до конца каталога) метод возвращает срез и nil в качестве ошибки. Если ошибка возникает до конца каталога, Readdir возвращает значения FileInfo, прочитанные до этого момента, и ненулевую ошибку.
Для большинства клиентов более эффективный метод ReadDir будет предпочтительнее.
func (*File) Readdirnames
func (f *File) Readdirnames(n int) (names []string, err error)
Readdirnames считывает содержимое каталога, связанного с файлом, и возвращает срез из не более чем n имён файлов в каталоге в порядке следования записей. Последующие вызовы для того же файла будут возвращать следующие имена.
Если n > 0, Readdirnames возвращает не более n имён. В этом случае, если Readdirnames возвращает пустой срез, метод вернёт ненулевую ошибку с объяснением причины. В конце каталога ошибкой будет io.EOF.
Если n <= 0, Readdirnames возвращает все имена из каталога в одном срезе. В этом случае при успешном выполнении Readdirnames (если чтение дошло до конца каталога) метод возвращает срез и nil в качестве ошибки. Если ошибка возникает до конца каталога, Readdirnames возвращает имена, прочитанные до этого момента, и ненулевую ошибку.
func (*File) Seek
func (f *File) Seek(offset int64, whence int) (ret int64, err error)
Seek задаёт смещение для следующего вызова Read или Write для файла; значение offset интерпретируется в соответствии с whence: 0 означает относительно начала файла, 1 — относительно текущего смещения, а 2 — относительно конца файла. Метод возвращает новое смещение и ошибку, если она возникла. Поведение Seek для файла, открытого с флагом O_APPEND, не определено.
func (*File) SetDeadline 1.10
func (f *File) SetDeadline(t time.Time) error
SetDeadline задаёт сроки ожидания чтения и записи для File. Это эквивалентно вызову SetReadDeadline и SetWriteDeadline.
Задание сроков ожидания поддерживается только для некоторых типов файлов. Вызовы SetDeadline для файлов, не поддерживающих сроки ожидания, вернут ErrNoDeadline. В большинстве систем обычные файлы не поддерживают сроки ожидания, но каналы поддерживают.
Срок ожидания — это абсолютный момент времени, после которого операции ввода-вывода завершаются с ошибкой вместо блокировки. Срок применяется ко всем будущим и ожидающим операциям ввода-вывода, а не только к следующему вызову Read или Write. После истечения срока соединение можно восстановить, задав срок в будущем.
Если срок истёк, вызов Read, Write или другого метода ввода-вывода вернёт ошибку, оборачивающую ErrDeadlineExceeded. Её можно проверить с помощью errors.Is(err, os.ErrDeadlineExceeded). Эта ошибка реализует метод Timeout, и вызов Timeout вернёт true, однако существуют и другие ошибки, для которых Timeout также вернёт true, даже если срок не истёк.
Тайм-аут простоя можно реализовать, неоднократно продлевая срок ожидания после успешных вызовов Read или Write.
Нулевое значение t означает, что у операций ввода-вывода не будет тайм-аута.
func (*File) SetReadDeadline 1.10
func (f *File) SetReadDeadline(t time.Time) error
SetReadDeadline задаёт срок ожидания для будущих вызовов Read и для текущего заблокированного вызова Read. Нулевое значение t означает, что у Read не будет тайм-аута. Не все файлы поддерживают задание сроков ожидания; см. SetDeadline.
func (*File) SetWriteDeadline 1.10
func (f *File) SetWriteDeadline(t time.Time) error
SetWriteDeadline задаёт срок ожидания для будущих вызовов Write и для текущего заблокированного вызова Write. Даже если время ожидания Write истечёт, метод может вернуть n > 0, что указывает на успешную запись части данных. Нулевое значение t означает, что у Write не будет тайм-аута. Не все файлы поддерживают задание сроков ожидания; см. SetDeadline.
func (*File) Stat
func (f *File) Stat() (FileInfo, error)
Stat возвращает структуру FileInfo, описывающую файл. Если возникает ошибка, она будет иметь тип *PathError.
func (*File) Sync
func (f *File) Sync() error
Sync сохраняет текущее содержимое файла в постоянное хранилище. Обычно это означает сброс находящейся в памяти копии недавно записанных данных файловой системы на диск.
func (*File) SyscallConn 1.12
func (f *File) SyscallConn() (syscall.RawConn, error)
SyscallConn возвращает дескриптор файла низкого уровня. Он реализует интерфейс syscall.Conn.
func (*File) Truncate
func (f *File) Truncate(size int64) error
Truncate изменяет размер файла. Метод не изменяет смещение ввода-вывода. Если возникает ошибка, она будет иметь тип *PathError.
func (*File) Write
func (f *File) Write(b []byte) (n int, err error)
Write записывает len(b) байт из b в File. Метод возвращает количество записанных байт и ошибку, если она возникла. Write возвращает ненулевую ошибку, если n != len(b).
func (*File) WriteAt
func (f *File) WriteAt(b []byte, off int64) (n int, err error)
WriteAt записывает len(b) байт в File, начиная со смещения off в байтах. Метод возвращает количество записанных байт и ошибку, если она возникла. WriteAt возвращает ненулевую ошибку, если n != len(b).
Если файл был открыт с флагом O_APPEND, WriteAt возвращает ошибку.
func (*File) WriteString
func (f *File) WriteString(s string) (n int, err error)
WriteString похож на Write, но записывает содержимое строки s, а не срез байт.
func (*File) WriteTo 1.22
func (f *File) WriteTo(w io.Writer) (n int64, err error)
WriteTo реализует io.WriterTo.
type FileInfo
FileInfo описывает файл и возвращается функциями Stat и Lstat.
type FileInfo = fs.FileInfo
func Lstat
func Lstat(name string) (FileInfo, error)
Lstat возвращает FileInfo, описывающий указанный файл. Если файл является символической ссылкой, возвращённый FileInfo описывает саму символическую ссылку. Lstat не пытается перейти по ссылке. Если возникает ошибка, она будет иметь тип *PathError.
В Windows, если файл является точкой повторной обработки, представляющей другой именованный объект (например, символическую ссылку или подключённую папку), возвращённый FileInfo описывает точку повторной обработки и не пытается её разрешить.
func Stat
func Stat(name string) (FileInfo, error)
Stat возвращает FileInfo, описывающий указанный файл. Если возникает ошибка, она будет иметь тип *PathError.
type FileMode
FileMode представляет режим файла и биты разрешений. Определения битов одинаковы во всех системах, благодаря чему сведения о файлах можно переносить между системами. Не все биты применимы ко всем системам. Единственный обязательный бит — ModeDir для каталогов.
type FileMode = fs.FileMode
Пример
Код:
fi, err := os.Lstat("some-filename")
if err != nil {
log.Fatal(err)
}
fmt.Printf("permissions: %#o\n", fi.Mode().Perm()) // 0o400, 0o777, etc.
switch mode := fi.Mode(); {
case mode.IsRegular():
fmt.Println("regular file")
case mode.IsDir():
fmt.Println("directory")
case mode&fs.ModeSymlink != 0:
fmt.Println("symbolic link")
case mode&fs.ModeNamedPipe != 0:
fmt.Println("named pipe")
}
type LinkError
LinkError содержит сведения об ошибке, возникшей при системном вызове link, symlink или rename, и о путях, которые её вызвали.
type LinkError struct {
Op string
Old string
New string
Err error
}
func (*LinkError) Error
func (e *LinkError) Error() string
func (*LinkError) Unwrap 1.13
func (e *LinkError) Unwrap() error
type PathError
PathError содержит сведения об ошибке, а также об операции и пути к файлу, которые её вызвали.
type PathError = fs.PathError
type ProcAttr
ProcAttr содержит атрибуты, которые будут применены к новому процессу, запущенному функцией StartProcess.
type ProcAttr struct {
// If Dir is non-empty, the child changes into the directory before
// creating the process.
Dir string
// If Env is non-nil, it gives the environment variables for the
// new process in the form returned by Environ.
// If it is nil, the result of Environ will be used.
Env []string
// Files specifies the open files inherited by the new process. The
// first three entries correspond to standard input, standard output, and
// standard error. An implementation may support additional entries,
// depending on the underlying operating system. A nil entry corresponds
// to that file being closed when the process starts.
// On Unix systems, StartProcess will change these File values
// to blocking mode, which means that SetDeadline will stop working
// and calling Close will not interrupt a Read or Write.
Files []*File
// Operating system-specific process creation attributes.
// Note that setting this field means that your program
// may not execute properly or even compile on some
// operating systems.
Sys *syscall.SysProcAttr
}
type Process
Process хранит сведения о процессе, созданном функцией StartProcess.
type Process struct {
// Pid is the operating system process ID.
Pid int
// contains filtered or unexported fields
}
func FindProcess
func FindProcess(pid int) (*Process, error)
FindProcess ищет работающий процесс по его pid.
Возвращённый Process можно использовать для получения сведений о соответствующем процессе операционной системы.
В системах Unix FindProcess всегда завершается успешно и возвращает Process для указанного pid независимо от того, существует ли процесс. Чтобы проверить, существует ли процесс на самом деле, проверьте, возвращает ли p.Signal(syscall.Signal(0)) ошибку.
func StartProcess
func StartProcess(name string, argv []string, attr *ProcAttr) (*Process, error)
StartProcess запускает новый процесс с программой, аргументами и атрибутами, заданными параметрами name, argv и attr. Срез argv станет значением os.Args в новом процессе, поэтому обычно его первым элементом является имя программы.
Если вызывающая горутина закрепила поток операционной системы с помощью runtime.LockOSThread и изменила какое-либо наследуемое состояние потока на уровне ОС (например, пространства имён Linux или Plan 9), новый процесс унаследует состояние потока вызывающей стороны.
StartProcess — низкоуровневый интерфейс. Пакет os/exec предоставляет интерфейсы более высокого уровня.
Если возникает ошибка, она будет иметь тип *PathError.
func (*Process) Kill
func (p *Process) Kill() error
Kill немедленно завершает Process. Kill не ожидает фактического завершения Process. Этот метод завершает только сам Process, но не другие процессы, которые он мог запустить.
func (*Process) Release
func (p *Process) Release() error
Release освобождает все ресурсы, связанные с Process p, после чего его нельзя будет использовать. Вызывать Release требуется только в том случае, если метод Process.Wait не вызывается.
func (*Process) Signal
func (p *Process) Signal(sig Signal) error
Signal отправляет сигнал процессу Process. Отправка Interrupt в Windows не реализована.
func (*Process) Wait
func (p *Process) Wait() (*ProcessState, error)
Wait ожидает завершения Process, а затем возвращает ProcessState с описанием его состояния и ошибку, если она возникла. Wait освобождает все ресурсы, связанные с Process. В большинстве операционных систем Process должен быть дочерним процессом текущего процесса, иначе будет возвращена ошибка.
func (*Process) WithHandle 1.26
func (p *Process) WithHandle(f func(handle uintptr)) error
WithHandle вызывает переданную функцию f, передавая ей в качестве аргумента действительный дескриптор процесса. Гарантируется, что дескриптор будет ссылаться на процесс p до завершения f, даже если p завершится. Эту функцию нельзя использовать после вызова Process.Release или Process.Wait.
Если дескрипторы процессов не поддерживаются или дескриптор недоступен, функция возвращает ErrNoHandle. В настоящее время дескрипторы процессов поддерживаются в Linux 5.4 и более поздних версиях (pidfd) и в Windows.
type ProcessState
ProcessState хранит сведения о процессе, полученные методом Wait.
type ProcessState struct {
// contains filtered or unexported fields
}
func (*ProcessState) ExitCode 1.12
func (p *ProcessState) ExitCode() int
ExitCode возвращает код завершения завершившегося процесса или -1, если процесс ещё не завершился либо был остановлен сигналом.
func (*ProcessState) Exited
func (p *ProcessState) Exited() bool
Exited сообщает, завершилась ли программа. В системах Unix метод возвращает true, если программа завершилась в результате вызова exit, но false, если программа завершилась из-за сигнала.
func (*ProcessState) Pid
func (p *ProcessState) Pid() int
Pid возвращает идентификатор завершившегося процесса.
func (*ProcessState) String
func (p *ProcessState) String() string
func (*ProcessState) Success
func (p *ProcessState) Success() bool
Success сообщает, завершилась ли программа успешно, например с кодом завершения 0 в Unix.
func (*ProcessState) Sys
func (p *ProcessState) Sys() any
Sys возвращает зависящие от системы сведения о завершении процесса. Чтобы получить доступ к содержимому, преобразуйте результат к соответствующему базовому типу, например к syscall.WaitStatus в Unix.
func (*ProcessState) SysUsage
func (p *ProcessState) SysUsage() any
SysUsage возвращает зависящие от системы сведения об использовании ресурсов завершившимся процессом. Чтобы получить доступ к содержимому, преобразуйте результат к соответствующему базовому типу, например к *syscall.Rusage в Unix. (В Unix тип *syscall.Rusage соответствует struct rusage, определённой на странице руководства getrusage(2).)
func (*ProcessState) SystemTime
func (p *ProcessState) SystemTime() time.Duration
SystemTime возвращает системное процессорное время завершившегося процесса и его дочерних процессов.
func (*ProcessState) UserTime
func (p *ProcessState) UserTime() time.Duration
UserTime возвращает пользовательское процессорное время завершившегося процесса и его дочерних процессов.
type Root 1.24
Root можно использовать для доступа только к файлам в пределах одного дерева каталогов.
Методы Root могут обращаться только к файлам и каталогам внутри корневого каталога. Если какой-либо компонент имени файла, переданного методу Root, указывает на расположение за пределами корневого каталога, метод возвращает ошибку. Имена файлов могут указывать на сам каталог (.).
Методы Root переходят по символическим ссылкам, но символические ссылки не могут указывать на расположение за пределами корневого каталога. Символические ссылки не должны быть абсолютными.
Методы Root не запрещают пересечение границ файловых систем, bind-монтирования Linux, доступ к специальным файлам /proc или доступ к устройствам Unix.
Методы Root безопасно использовать одновременно из нескольких горутин.
На большинстве платформ создание Root открывает файловый дескриптор или дескриптор, ссылающийся на каталог. Если каталог перемещён, методы Root будут обращаться к исходному каталогу в его новом расположении.
Поведение Root различается на некоторых платформах:
- При GOOS=windows имена файлов не должны совпадать с зарезервированными именами устройств Windows, такими как NUL и COM1.
- В Unix Root.Chmod, Root.Chown и Root.Chtimes уязвимы к состоянию гонки. Если во время выполнения операции цель изменится с обычного файла на символическую ссылку, операция может быть выполнена над ссылкой, а не над целью ссылки.
- При GOOS=js Root уязвим к атакам TOCTOU (time-of-check-time-of-use) при проверке символических ссылок и не может гарантировать, что операции не выйдут за пределы корневого каталога.
- При GOOS=plan9 или GOOS=js Root не отслеживает каталоги при переименовании. На этих платформах Root ссылается на имя каталога, а не на файловый дескриптор.
- WASI preview 1 (GOOS=wasip1) не поддерживает Root.Chmod.
type Root struct {
// contains filtered or unexported fields
}
func OpenRoot 1.24
func OpenRoot(name string) (*Root, error)
OpenRoot открывает указанный каталог. При этом следуют символическим ссылкам в имени каталога. В случае ошибки она будет иметь тип *PathError.
func (*Root) Chmod 1.25
func (r *Root) Chmod(name string, mode FileMode) error
Chmod изменяет режим доступа к указанному файлу в корневом каталоге на mode. Подробнее см. Chmod.
func (*Root) Chown 1.25
func (r *Root) Chown(name string, uid, gid int) error
Chown изменяет числовые uid и gid указанного файла в корневом каталоге. Подробнее см. Chown.
func (*Root) Chtimes 1.25
func (r *Root) Chtimes(name string, atime time.Time, mtime time.Time) error
Chtimes изменяет время доступа и изменения указанного файла в корневом каталоге. Подробнее см. Chtimes.
func (*Root) Close 1.24
func (r *Root) Close() error
Close закрывает Root. После вызова Close методы Root возвращают ошибки.
func (*Root) Create 1.24
func (r *Root) Create(name string) (*File, error)
Create создает указанный файл в корневом каталоге или обнуляет его содержимое. Подробнее см. Create.
func (*Root) FS 1.24
func (r *Root) FS() fs.FS
FS возвращает файловую систему (fs.FS) для дерева файлов в корневом каталоге.
Результат реализует интерфейсы io/fs.StatFS, io/fs.ReadFileFS, io/fs.ReadDirFS и io/fs.ReadLinkFS.
func (*Root) Lchown 1.25
func (r *Root) Lchown(name string, uid, gid int) error
Lchown изменяет числовые uid и gid указанного файла в корневом каталоге. Подробнее см. Lchown.
func (*Root) Link 1.25
func (r *Root) Link(oldname, newname string) error
Link создает newname как жесткую ссылку на файл oldname. Оба пути являются относительными к корневому каталогу. Подробнее см. Link.
Если oldname — символическая ссылка, Link создает новую ссылку на oldname, а не на ее цель. На некоторых платформах это поведение может отличаться от поведения Link.
При GOOS=js Link возвращает ошибку, если oldname — символическая ссылка.
func (*Root) Lstat 1.24
func (r *Root) Lstat(name string) (FileInfo, error)
Lstat возвращает FileInfo с описанием указанного файла в корневом каталоге. Если файл является символической ссылкой, возвращенный FileInfo описывает символическую ссылку. Подробнее см. Lstat.
func (*Root) Mkdir 1.24
func (r *Root) Mkdir(name string, perm FileMode) error
Mkdir создает в корневом каталоге новый каталог с указанным именем и битами разрешений (до применения umask). Подробнее см. Mkdir.
Если perm содержит биты помимо девяти младших битов (0o777), Mkdir возвращает ошибку.
func (*Root) MkdirAll 1.25
func (r *Root) MkdirAll(name string, perm FileMode) error
MkdirAll создает новый каталог в корневом каталоге вместе со всеми необходимыми родительскими каталогами. Подробнее см. MkdirAll.
Если perm содержит биты помимо девяти младших битов (0o777), MkdirAll возвращает ошибку.
func (*Root) Name 1.24
func (r *Root) Name() string
Name возвращает имя каталога, переданное в OpenRoot.
Безопасно вызывать Name после [Close].
func (*Root) Open 1.24
func (r *Root) Open(name string) (*File, error)
Open открывает указанный файл в корневом каталоге для чтения. Подробнее см. Open.
func (*Root) OpenFile 1.24
func (r *Root) OpenFile(name string, flag int, perm FileMode) (*File, error)
OpenFile открывает указанный файл в корневом каталоге. Подробнее см. OpenFile.
Если perm содержит биты помимо девяти младших битов (0o777), OpenFile возвращает ошибку.
func (*Root) OpenRoot 1.24
func (r *Root) OpenRoot(name string) (*Root, error)
OpenRoot открывает указанный каталог в корневом каталоге. В случае ошибки она будет иметь тип *PathError.
func (*Root) ReadFile 1.25
func (r *Root) ReadFile(name string) ([]byte, error)
ReadFile читает указанный файл в корневом каталоге и возвращает его содержимое. Подробнее см. ReadFile.
func (*Root) Readlink 1.25
func (r *Root) Readlink(name string) (string, error)
Readlink возвращает путь назначения указанной символической ссылки в корневом каталоге. Подробнее см. Readlink.
func (*Root) Remove 1.24
func (r *Root) Remove(name string) error
Remove удаляет указанный файл или (пустой) каталог в корневом каталоге. Подробнее см. Remove.
func (*Root) RemoveAll 1.25
func (r *Root) RemoveAll(name string) error
RemoveAll удаляет указанный файл или каталог, а также все содержащиеся в нем элементы. Подробнее см. RemoveAll.
func (*Root) Rename 1.25
func (r *Root) Rename(oldname, newname string) error
Rename переименовывает (перемещает) oldname в newname. Оба пути являются относительными к корневому каталогу. Подробнее см. Rename.
func (*Root) Stat 1.24
func (r *Root) Stat(name string) (FileInfo, error)
Stat возвращает FileInfo с описанием указанного файла в корневом каталоге. Подробнее см. Stat.
func (*Root) Symlink 1.25
func (r *Root) Symlink(oldname, newname string) error
Symlink создает newname как символическую ссылку на oldname. Подробнее см. Symlink.
Symlink не проверяет oldname, который может ссылаться на расположение за пределами корневого каталога.
В Windows создается ссылка на каталог, если oldname указывает на каталог внутри корневого каталога. В противном случае создается ссылка на файл.
func (*Root) WriteFile 1.25
func (r *Root) WriteFile(name string, data []byte, perm FileMode) error
WriteFile записывает данные в указанный файл в корневом каталоге, создавая его при необходимости. Подробнее см. WriteFile.
type Signal
Signal представляет сигнал операционной системы. Обычно используемая реализация зависит от операционной системы: в Unix это syscall.Signal.
type Signal interface {
String() string
Signal() // to distinguish from other Stringers
} Единственные значения сигналов, присутствие которых гарантировано во всех системах в пакете os, — это os.Interrupt (посылает процессу сигнал прерывания) и os.Kill (принудительно завершает процесс). В Windows отправка os.Interrupt процессу с помощью os.Process.Signal не реализована; вместо отправки сигнала будет возвращена ошибка.
var (
Interrupt Signal = syscall.SIGINT
Kill Signal = syscall.SIGKILL
) type SyscallError
SyscallError сохраняет информацию об ошибке конкретного системного вызова.
type SyscallError struct {
Syscall string
Err error
}
func (*SyscallError) Error
func (e *SyscallError) Error() string
func (*SyscallError) Timeout 1.10
func (e *SyscallError) Timeout() bool
Timeout сообщает, означает ли эта ошибка истечение времени ожидания.
func (*SyscallError) Unwrap 1.13
func (e *SyscallError) Unwrap() error
Подкаталоги
| Имя | Краткое описание |
|---|---|
| .. | |
| exec | Пакет exec выполняет внешние команды. |
| signal | Пакет signal обеспечивает доступ к поступающим сигналам. |
| user | Пакет user позволяет искать учетные записи пользователей по имени или идентификатору. |
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/os/
