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 Chown(name string, uid, gid int) error
- func Chtimes(name string, atime time.Time, mtime time.Time) error
- func Clearenv()
- func Environ() []string
- 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() (pwd string, err error)
- func Hostname() (name string, err error)
- func IsExist(err error) bool
- func IsNotExist(err error) bool
- func IsPathSeparator(c uint8) bool
- func IsPermission(err error) bool
- func Lchown(name string, uid, gid int) error
- func Link(oldname, newname string) error
- func Mkdir(name string, perm FileMode) error
- func MkdirAll(path string, perm FileMode) error
- func NewSyscallError(syscall string, err error) error
- func Pipe() (r *File, w *File, err error)
- func Readlink(name string) (string, error)
- func Remove(name string) error
- func RemoveAll(path string) error
- func Rename(oldname, newname string) error
- func SameFile(fi1, fi2 FileInfo) bool
- func Setenv(key, value string) error
- func Symlink(oldname, newname string) error
- func TempDir() string
- func Truncate(name string, size int64) error
- type File
- func (f *File) Chdir() error
- func (f *File) Chmod(mode FileMode) error
- func (f *File) Chown(uid, gid int) error
- func (f *File) Close() error
- func (f *File) Fd() uintptr
- 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) (fi []FileInfo, err 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) Stat() (fi FileInfo, err error)
- func (f *File) Sync() (err error)
- func (f *File) Truncate(size int64) 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) (ret int, err error)
- type FileInfo
- type FileMode
- type LinkError
- type PathError
- type ProcAttr
- type Process
- type ProcessState
- func (p *ProcessState) Exited() bool
- func (p *ProcessState) Pid() int
- func (p *ProcessState) String() string
- func (p *ProcessState) Success() bool
- func (p *ProcessState) Sys() interface{}
- func (p *ProcessState) SysUsage() interface{}
- func (p *ProcessState) SystemTime() time.Duration
- func (p *ProcessState) UserTime() time.Duration
- type Signal
- type SyscallError
Constants ¶
const ( 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. 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 Open 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.
const ( PathSeparator = '/' // OS-specific path separator PathListSeparator = ':' // OS-specific path list separator )
const DevNull = "/dev/null"
DevNull is the name of the operating system's “null device.” On Unix-like systems, it is "/dev/null"; on Windows, "NUL".
Variables ¶
var ( ErrInvalid = errors.New("invalid argument") ErrPermission = errors.New("permission denied") ErrExist = errors.New("file already exists") ErrNotExist = errors.New("file does not exist") )
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.
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 ¶
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.
func Chown ¶
Chown changes the numeric uid and gid of the named file. If the file is a symbolic link, it changes the uid and gid of the link's target. If there is an error, it will be of type *PathError.
func Chtimes ¶
Chtimes changes the access and modification times of the named file, similar to the Unix utime() or utimes() functions.
The underlying filesystem may truncate or round the values to a less precise time unit. If there is an error, it will be of type *PathError.
func Environ ¶
func Environ() []string
Environ returns a copy of strings representing the environment, in the form "key=value".
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.
func Expand ¶
Expand replaces ${var} or $var in the string based on the mapping function. Invocations of undefined variables are replaced with the empty string.
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.
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.
func Getpagesize ¶
func Getpagesize() int
Getpagesize returns the underlying system's memory page size.
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 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 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.
func IsPathSeparator ¶
IsPathSeparator returns true if c is a directory separator character.
func IsPermission ¶
IsPermission returns whether the error is known to report that permission is denied. It is satisfied by ErrPermission as well as some syscall errors.
func Lchown ¶
Lchown changes the numeric uid and gid of the named file. If the file is a symbolic link, it changes the uid and gid of the link itself. If there is an error, it will be of type *PathError.
func Link ¶
Link creates newname as a hard link to the oldname file. If there is an error, it will be of type *LinkError.
func Mkdir ¶
Mkdir creates a new directory with the specified name and permission bits. 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 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 Pipe ¶
Pipe returns a connected pair of Files; reads from r return bytes written to w. It returns the files and an error, if any.
func Readlink ¶
Readlink returns the destination of the named symbolic link. If there is an error, it will be of type *PathError.
func Remove ¶
Remove removes the named file or directory. If there is an error, it will be of type *PathError.
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 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 Symlink ¶
Symlink creates newname as a symbolic link to oldname. If there is an error, it will be of type *LinkError.
Types ¶
type File ¶
type File struct {
// contains filtered or unexported fields
}
File represents an open file descriptor.
func Create ¶
Create creates the named file 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 ¶
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 ¶
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, (0666 etc.) 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.
func (*File) Chdir ¶
Chdir changes the current working directory to the file, which must be a directory. If there is an error, it will be of type *PathError.
func (*File) Chmod ¶
Chmod changes the mode of the file to mode. If there is an error, it will be of type *PathError.
func (*File) Chown ¶
Chown changes the numeric uid and gid of the named file. If there is an error, it will be of type *PathError.
func (*File) Close ¶
Close closes the File, rendering it unusable for I/O. It returns an error, if any.
func (*File) Read ¶
Read reads up to len(b) bytes from the File. It returns the number of bytes read and an error, if any. EOF is signaled by a zero count with err set to io.EOF.
func (*File) ReadAt ¶
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 ¶
Readdir reads the contents of the directory associated with file and returns an array 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 ¶
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 ¶
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.
func (*File) Stat ¶
Stat returns the FileInfo structure describing file. If there is an error, it will be of type *PathError.
func (*File) Sync ¶
Sync commits the current contents of the file to stable storage. Typically, this means flushing the file system's in-memory copy of recently written data to disk.
func (*File) Truncate ¶
Truncate changes the size of the file. It does not change the I/O offset. If there is an error, it will be of type *PathError.
func (*File) Write ¶
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.
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 (not backed up) 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 // 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.