Affected by 
Documentation
¶
Overview ¶
Package os provides a platform-independent interface to operating system functionality. The design is Unix-like, although the error handling is Go-like; failing calls return values of type error rather than error numbers. Often, more information is available within the error. For example, if a call that takes a file name fails, such as Open or Stat, the error will include the failing file name when printed and will be of type *PathError, which may be unpacked for more information.
The os interface is intended to be uniform across all operating systems. Features not generally available appear in the system-specific package syscall.
Here is a simple example, opening a file and reading some of it.
file, err := os.Open("file.go") // For read access.
if err != nil {
log.Fatal(err)
}
If the open fails, the error string will be self-explanatory, like
open file.go: no such file or directory
The file's data can then be read into a slice of bytes. Read and Write take their byte counts from the length of the argument slice.
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])
Index ¶
- Constants
- Variables
- func Chdir(dir string) error
- func Chmod(name string, mode FileMode) error
- func Clearenv()
- func Environ() []string
- func Executable() (string, error)
- func Exit(code int)
- func Expand(s string, mapping func(string) string) string
- func ExpandEnv(s string) string
- func Getegid() int
- func Getenv(key string) string
- func Geteuid() int
- func Getgid() int
- func Getgroups() ([]int, error)
- func Getpagesize() int
- func Getpid() int
- func Getppid() int
- func Getuid() int
- func Getwd() (dir string, err error)
- func Hostname() (name string, err error)
- func IsExist(err error) bool
- func IsNotExist(err error) bool
- func IsPermission(err error) bool
- func IsTimeout(err error) bool
- func LookupEnv(key string) (string, bool)
- func Mkdir(name string, perm FileMode) error
- func MkdirAll(path string, perm FileMode) error
- func NewSyscallError(syscall string, err error) error
- func RemoveAll(path string) error
- func Rename(oldpath, newpath string) error
- func SameFile(fi1, fi2 FileInfo) bool
- func Setenv(key, value string) error
- func TempDir() string
- func Unsetenv(key string) error
- type File
- func (f *File) Chmod(mode FileMode) error
- func (f *File) Name() string
- func (f *File) Read(b []byte) (n int, err error)
- func (f *File) ReadAt(b []byte, off int64) (n int, err error)
- func (f *File) Readdir(n int) ([]FileInfo, error)
- func (f *File) Readdirnames(n int) (names []string, err error)
- func (f *File) Seek(offset int64, whence int) (ret int64, err error)
- func (f *File) SetDeadline(t time.Time) error
- func (f *File) SetReadDeadline(t time.Time) error
- func (f *File) SetWriteDeadline(t time.Time) error
- func (f *File) Write(b []byte) (n int, err error)
- func (f *File) WriteAt(b []byte, off int64) (n int, err error)
- func (f *File) WriteString(s string) (n int, err error)
- type FileInfo
- type FileMode
- type LinkError
- type PathError
- type ProcAttr
- type Process
- type Signal
- type SyscallError
Examples ¶
Constants ¶
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 // if possible, truncate file when opened. )
Flags to OpenFile wrapping those of the underlying system. Not all flags may be implemented on a given system.
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 )
Seek whence values.
Deprecated: Use io.SeekStart, io.SeekCurrent, and io.SeekEnd.
Variables ¶
var ( ErrInvalid = errors.New("invalid argument") // methods on File will return this error when the receiver is nil ErrPermission = errors.New("permission denied") ErrExist = errors.New("file already exists") ErrNotExist = errors.New("file does not exist") ErrClosed = errors.New("file already closed") ErrNoDeadline = poll.ErrNoDeadline )
Portable analogs of some common system call errors.
var ( Stdin = NewFile(uintptr(syscall.Stdin), "/dev/stdin") Stdout = NewFile(uintptr(syscall.Stdout), "/dev/stdout") Stderr = NewFile(uintptr(syscall.Stderr), "/dev/stderr") )
Stdin, Stdout, and Stderr are open Files pointing to the standard input, standard output, and standard error file descriptors.
Note that the Go runtime writes to standard error for panics and crashes; closing Stderr may cause those messages to go elsewhere, perhaps to a file opened later.
var Args []string
Args hold the command-line arguments, starting with the program name.
Functions ¶
func Chdir ¶
Chdir changes the current working directory to the named directory. If there is an error, it will be of type *PathError.
func Chmod ¶ added in go1.9
Chmod changes the mode of the named file to mode. If the file is a symbolic link, it changes the mode of the link's target. If there is an error, it will be of type *PathError.
A different subset of the mode bits are used, depending on the operating system.
On Unix, the mode's permission bits, ModeSetuid, ModeSetgid, and ModeSticky are used.
On Windows, the mode must be non-zero but otherwise only the 0200 bit (owner writable) of mode is used; it controls whether the file's read-only attribute is set or cleared. attribute. The other bits are currently unused. Use mode 0400 for a read-only file and 0600 for a readable+writable file.
On Plan 9, the mode's permission bits, ModeAppend, ModeExclusive, and ModeTemporary are used.
Example ¶
package main
import (
"log"
"os"
)
func main() {
if err := os.Chmod("some-filename", 0644); err != nil {
log.Fatal(err)
}
}
func Environ ¶
func Environ() []string
Environ returns a copy of strings representing the environment, in the form "key=value".
func Executable ¶ added in go1.8
Executable returns the path name for the executable that started the current process. There is no guarantee that the path is still pointing to the correct executable. If a symlink was used to start the process, depending on the operating system, the result might be the symlink or the path it pointed to. If a stable result is needed, path/filepath.EvalSymlinks might help.
Executable returns an absolute path unless an error occurred.
The main use case is finding resources located relative to an executable.
Executable is not supported on nacl.
func Exit ¶
func Exit(code int)
Exit causes the current program to exit with the given status code. Conventionally, code zero indicates success, non-zero an error. The program terminates immediately; deferred functions are not run.
func Expand ¶
Expand replaces ${var} or $var in the string based on the mapping function. For example, os.ExpandEnv(s) is equivalent to os.Expand(s, os.Getenv).
func ExpandEnv ¶
ExpandEnv replaces ${var} or $var in the string according to the values of the current environment variables. References to undefined variables are replaced by the empty string.
Example ¶
package main
import (
"fmt"
"os"
)
func main() {
fmt.Println(os.ExpandEnv("$USER lives in ${HOME}."))
}
Output: gopher lives in /usr/gopher.
func Getegid ¶
func Getegid() int
Getegid returns the numeric effective group id of the caller.
On Windows, it returns -1.
func Getenv ¶
Getenv retrieves the value of the environment variable named by the key. It returns the value, which will be empty if the variable is not present. To distinguish between an empty value and an unset value, use LookupEnv.
Example ¶
package main
import (
"fmt"
"os"
)
func main() {
fmt.Printf("%s lives in %s.\n", os.Getenv("USER"), os.Getenv("HOME"))
}
Output: gopher lives in /usr/gopher.
func Geteuid ¶
func Geteuid() int
Geteuid returns the numeric effective user id of the caller.
On Windows, it returns -1.
func Getgid ¶
func Getgid() int
Getgid returns the numeric group id of the caller.
On Windows, it returns -1.
func Getgroups ¶
Getgroups returns a list of the numeric ids of groups that the caller belongs to.
On Windows, it returns syscall.EWINDOWS. See the os/user package for a possible alternative.
func Getpagesize ¶
func Getpagesize() int
Getpagesize returns the underlying system's memory page size.
func Getuid ¶
func Getuid() int
Getuid returns the numeric user id of the caller.
On Windows, it returns -1.
func Getwd ¶
Getwd returns a rooted path name corresponding to the current directory. If the current directory can be reached via multiple paths (due to symbolic links), Getwd may return any one of them.
func IsExist ¶
IsExist returns a boolean indicating whether the error is known to report that a file or directory already exists. It is satisfied by ErrExist as well as some syscall errors.
func IsNotExist ¶
IsNotExist returns a boolean indicating whether the error is known to report that a file or directory does not exist. It is satisfied by ErrNotExist as well as some syscall errors.
Example ¶
package main
import (
"fmt"
"os"
)
func main() {
filename := "a-nonexistent-file"
if _, err := os.Stat(filename); os.IsNotExist(err) {
fmt.Printf("file does not exist")
}
}
Output: file does not exist
func IsPermission ¶
IsPermission returns a boolean indicating whether the error is known to report that permission is denied. It is satisfied by ErrPermission as well as some syscall errors.
func IsTimeout ¶ added in go1.10
IsTimeout returns a boolean indicating whether the error is known to report that a timeout occurred.
func LookupEnv ¶ added in go1.5
LookupEnv retrieves the value of the environment variable named by the key. If the variable is present in the environment the value (which may be empty) is returned and the boolean is true. Otherwise the returned value will be empty and the boolean will be false.
Example ¶
package main
import (
"fmt"
"os"
)
func main() {
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)
}
}
show("USER")
show("GOPATH")
}
Output: USER=gopher GOPATH not set
func Mkdir ¶
Mkdir creates a new directory with the specified name and permission bits (before umask). If there is an error, it will be of type *PathError.
func MkdirAll ¶
MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error. The permission bits perm (before umask) are used for all directories that MkdirAll creates. If path is already a directory, MkdirAll does nothing and returns nil.
func NewSyscallError ¶
NewSyscallError returns, as an error, a new SyscallError with the given system call name and error details. As a convenience, if err is nil, NewSyscallError returns nil.
func RemoveAll ¶
RemoveAll removes path and any children it contains. It removes everything it can but returns the first error it encounters. If the path does not exist, RemoveAll returns nil (no error).
func Rename ¶ added in go1.3
Rename renames (moves) oldpath to newpath. If newpath already exists and is not a directory, Rename replaces it. OS-specific restrictions may apply when oldpath and newpath are in different directories. If there is an error, it will be of type *LinkError.
func SameFile ¶
SameFile reports whether fi1 and fi2 describe the same file. For example, on Unix this means that the device and inode fields of the two underlying structures are identical; on other systems the decision may be based on the path names. SameFile only applies to results returned by this package's Stat. It returns false in other cases.
func Setenv ¶
Setenv sets the value of the environment variable named by the key. It returns an error, if any.
func TempDir ¶ added in go1.9
func TempDir() string
TempDir returns the default directory to use for temporary files.
On Unix systems, it returns $TMPDIR if non-empty, else /tmp. On Windows, it uses GetTempPath, returning the first non-empty value from %TMP%, %TEMP%, %USERPROFILE%, or the Windows directory. On Plan 9, it returns /tmp.
The directory is neither guaranteed to exist nor have accessible permissions.
Types ¶
type File ¶ added in go1.8
type File struct {
// contains filtered or unexported fields
}
File represents an open file descriptor.
func Create ¶ added in go1.8
Create creates the named file with mode 0666 (before umask), truncating it if it already exists. If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR. If there is an error, it will be of type *PathError.
func Open ¶ added in go1.8
Open opens the named file for reading. If successful, methods on the returned file can be used for reading; the associated file descriptor has mode O_RDONLY. If there is an error, it will be of type *PathError.
func OpenFile ¶ added in go1.10
OpenFile is the generalized open call; most users will use Open or Create instead. It opens the named file with specified flag (O_RDONLY etc.) and perm (before umask), if applicable. If successful, methods on the returned File can be used for I/O. If there is an error, it will be of type *PathError.
Example ¶
package main
import (
"log"
"os"
)
func main() {
f, err := os.OpenFile("notes.txt", os.O_RDWR|os.O_CREATE, 0755)
if err != nil {
log.Fatal(err)
}
if err := f.Close(); err != nil {
log.Fatal(err)
}
}
Example (Append) ¶
package main
import (
"log"
"os"
)
func main() {
// 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 {
log.Fatal(err)
}
if err := f.Close(); err != nil {
log.Fatal(err)
}
}
func (*File) Chmod ¶ added in go1.9
Chmod changes the mode of the file to mode. If there is an error, it will be of type *PathError.
func (*File) Read ¶ added in go1.8
Read reads up to len(b) bytes from the File. It returns the number of bytes read and any error encountered. At end of file, Read returns 0, io.EOF.
func (*File) ReadAt ¶ added in go1.8
ReadAt reads len(b) bytes from the File starting at byte offset off. It returns the number of bytes read and the error, if any. ReadAt always returns a non-nil error when n < len(b). At end of file, that error is io.EOF.
func (*File) Readdir ¶ added in go1.8
Readdir reads the contents of the directory associated with file and returns a slice of up to n FileInfo values, as would be returned by Lstat, in directory order. Subsequent calls on the same file will yield further FileInfos.
If n > 0, Readdir returns at most n FileInfo structures. In this case, if Readdir returns an empty slice, it will return a non-nil error explaining why. At the end of a directory, the error is io.EOF.
If n <= 0, Readdir returns all the FileInfo from the directory in a single slice. In this case, if Readdir succeeds (reads all the way to the end of the directory), it returns the slice and a nil error. If it encounters an error before the end of the directory, Readdir returns the FileInfo read until that point and a non-nil error.
func (*File) Readdirnames ¶ added in go1.8
Readdirnames reads and returns a slice of names from the directory f.
If n > 0, Readdirnames returns at most n names. In this case, if Readdirnames returns an empty slice, it will return a non-nil error explaining why. At the end of a directory, the error is io.EOF.
If n <= 0, Readdirnames returns all the names from the directory in a single slice. In this case, if Readdirnames succeeds (reads all the way to the end of the directory), it returns the slice and a nil error. If it encounters an error before the end of the directory, Readdirnames returns the names read until that point and a non-nil error.
func (*File) Seek ¶ added in go1.8
Seek sets the offset for the next Read or Write on file to offset, interpreted according to whence: 0 means relative to the origin of the file, 1 means relative to the current offset, and 2 means relative to the end. It returns the new offset and an error, if any. The behavior of Seek on a file opened with O_APPEND is not specified.
func (*File) SetDeadline ¶ added in go1.10
SetDeadline sets the read and write deadlines for a File. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.
Only some kinds of files support setting a deadline. Calls to SetDeadline for files that do not support deadlines will return ErrNoDeadline. On most systems ordinary files do not support deadlines, but pipes do.
A deadline is an absolute time after which I/O operations fail with an error instead of blocking. The deadline applies to all future and pending I/O, not just the immediately following call to Read or Write. After a deadline has been exceeded, the connection can be refreshed by setting a deadline in the future.
An error returned after a timeout fails will implement the Timeout method, and calling the Timeout method will return true. The PathError and SyscallError types implement the Timeout method. In general, call IsTimeout to test whether an error indicates a timeout.
An idle timeout can be implemented by repeatedly extending the deadline after successful Read or Write calls.
A zero value for t means I/O operations will not time out.
func (*File) SetReadDeadline ¶ added in go1.10
SetReadDeadline sets the deadline for future Read calls and any currently-blocked Read call. A zero value for t means Read will not time out. Not all files support setting deadlines; see SetDeadline.
func (*File) SetWriteDeadline ¶ added in go1.10
SetWriteDeadline sets the deadline for any future Write calls and any currently-blocked Write call. Even if Write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out. Not all files support setting deadlines; see SetDeadline.
func (*File) Write ¶ added in go1.8
Write writes len(b) bytes to the File. It returns the number of bytes written and an error, if any. Write returns a non-nil error when n != len(b).
type FileInfo ¶
type FileInfo interface {
Name() string // base name of the file
Size() int64 // length in bytes for regular files; system-dependent for others
Mode() FileMode // file mode bits
ModTime() time.Time // modification time
IsDir() bool // abbreviation for Mode().IsDir()
Sys() interface{} // underlying data source (can return nil)
}
A FileInfo describes a file and is returned by Stat and Lstat.
type FileMode ¶
type FileMode uint32
A FileMode represents a file's mode and permission bits. The bits have the same definition on all systems, so that information about files can be moved from one system to another portably. Not all bits apply to all systems. The only required bit is ModeDir for directories.
Example ¶
package main
import (
"fmt"
"log"
"os"
)
func main() {
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")
}
}
const ( // The single letters are the abbreviations // used by the String method's formatting. ModeDir FileMode = 1 << (32 - 1 - iota) // d: is a directory ModeAppend // a: append-only ModeExclusive // l: exclusive use ModeTemporary // T: temporary file; Plan 9 only ModeSymlink // L: symbolic link ModeDevice // D: device file ModeNamedPipe // p: named pipe (FIFO) ModeSocket // S: Unix domain socket ModeSetuid // u: setuid ModeSetgid // g: setgid ModeCharDevice // c: Unix character device, when ModeDevice is set ModeSticky // t: sticky // Mask for the type bits. For regular files, none will be set. ModeType = ModeDir | ModeSymlink | ModeNamedPipe | ModeSocket | ModeDevice ModePerm FileMode = 0777 // Unix permission bits )
The defined file mode bits are the most significant bits of the FileMode. The nine least-significant bits are the standard Unix rwxrwxrwx permissions. The values of these bits should be considered part of the public API and may be used in wire protocols or disk representations: they must not be changed, although new bits might be added.
func (FileMode) IsDir ¶
IsDir reports whether m describes a directory. That is, it tests for the ModeDir bit being set in m.
func (FileMode) IsRegular ¶ added in go1.1
IsRegular reports whether m describes a regular file. That is, it tests that no mode type bits are set.
type LinkError ¶
LinkError records an error during a link or symlink or rename system call and the paths that caused it.
type ProcAttr ¶
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.
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
}
ProcAttr holds the attributes that will be applied to a new process started by StartProcess.
type Process ¶
type Process struct {
Pid int
// contains filtered or unexported fields
}
Process stores the information about a process created by StartProcess.
func FindProcess ¶
FindProcess looks for a running process by its pid.
The Process it returns can be used to obtain information about the underlying operating system process.
On Unix systems, FindProcess always succeeds and returns a Process for the given pid, regardless of whether the process exists.
func StartProcess ¶
StartProcess starts a new process with the program, arguments and attributes specified by name, argv and attr. The argv slice will become os.Args in the new process, so it normally starts with the program name.
If the calling goroutine has locked the operating system thread with runtime.LockOSThread and modified any inheritable OS-level thread state (for example, Linux or Plan 9 name spaces), the new process will inherit the caller's thread state.
StartProcess is a low-level interface. The os/exec package provides higher-level interfaces.
If there is an error, it will be of type *PathError.
func (*Process) Release ¶
Release releases any resources associated with the Process p, rendering it unusable in the future. Release only needs to be called if Wait is not.
func (*Process) Signal ¶
Signal sends a signal to the Process. Sending Interrupt on Windows is not implemented.
type Signal ¶
type Signal interface {
String() string
Signal() // to distinguish from other Stringers
}
A Signal represents an operating system signal. The usual underlying implementation is operating system-dependent: on Unix it is syscall.Signal.
type SyscallError ¶
SyscallError records an error from a specific system call.
func (*SyscallError) Error ¶
func (e *SyscallError) Error() string
func (*SyscallError) Timeout ¶ added in go1.10
func (e *SyscallError) Timeout() bool
Timeout reports whether this error represents a timeout.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package exec runs external commands.
|
Package exec runs external commands. |
|
Package signal implements access to incoming signals.
|
Package signal implements access to incoming signals. |
|
internal/pty
Package pty is a simple pseudo-terminal package for Unix systems, implemented by calling C functions via cgo.
|
Package pty is a simple pseudo-terminal package for Unix systems, implemented by calling C functions via cgo. |
|
Package user allows user account lookups by name or id.
|
Package user allows user account lookups by name or id. |