Documentation ¶
Index ¶
- Constants
- Variables
- func Chdir(dir string) error
- func Chmod(name string, mode FileMode) error
- func Chown(name string, uid, gid int) error
- func Clearenv()
- func Environ() []string
- func Exit(code int)
- 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 IsExist(err error) bool
- func IsNotExist(err error) bool
- func IsPathSeparator(c uint8) bool
- func IsPermission(err error) bool
- func IsTimeout(err error) bool
- func Lchown(name string, uid, gid int) error
- func Link(oldname, newname string) error
- func LookupEnv(key string) (string, bool)
- func Mkdir(name 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 Rename(oldpath, newpath string) error
- func SameFile(fi1, fi2 FileInfo) bool
- func Setenv(key, value string) error
- func Symlink(oldname, newname string) error
- func Truncate(name string, size int64) error
- func Unsetenv(key string) error
- func UserCacheDir() (string, error)
- func UserConfigDir() (string, error)
- func UserHomeDir() (string, 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) ReadFrom(r io.Reader) (n int64, 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) Stat() (FileInfo, error)
- func (f *File) Sync() error
- func (f *File) SyscallConn() (syscall.RawConn, 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) (n int, err error)
- type FileInfo
- type FileMode
- type LinkError
- type PathError
- type ProcAttr
- type Process
- type ProcessState
- func (p *ProcessState) ExitCode() int
- func (p *ProcessState) Exited() bool
- func (p *ProcessState) Pid() int
- func (p *ProcessState) String() string
- func (p *ProcessState) Success() bool
- func (p *ProcessState) Sys() any
- func (p *ProcessState) SysUsage() any
- func (p *ProcessState) SystemTime() time.Duration
- func (p *ProcessState) UserTime() time.Duration
- type Signal
- type SyscallError
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 // truncate regular writable 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.
const ( PathSeparator = '/' // OS-specific path separator PathListSeparator = ':' // OS-specific path list separator )
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 )
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.
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".
const (
LLGoPackage = true
)
Variables ¶
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" )
Portable analogs of some common system call errors.
Errors returned from this package may be tested against these errors with errors.Is.
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.
var ErrProcessDone = errors.New("os: process already finished")
ErrProcessDone indicates a Process has finished.
Functions ¶
func Environ ¶ added in v0.9.1
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. The program terminates immediately; deferred functions are not run.
For portability, the status code should be in the range [0, 125].
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.
func Getgroups ¶ added in v0.9.2
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 ¶ added in v0.8.10
func Getpagesize() int
Getpagesize returns the underlying system's memory page size.
func IsExist ¶ added in v0.8.10
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.
This function predates errors.Is. It only supports errors returned by the os package. New code should use errors.Is(err, fs.ErrExist).
func IsNotExist ¶ added in v0.8.10
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.
This function predates errors.Is. It only supports errors returned by the os package. New code should use errors.Is(err, fs.ErrNotExist).
func IsPathSeparator ¶ added in v0.9.1
IsPathSeparator reports whether c is a directory separator character.
func IsPermission ¶ added in v0.8.10
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.
This function predates errors.Is. It only supports errors returned by the os package. New code should use errors.Is(err, fs.ErrPermission).
func IsTimeout ¶ added in v0.8.10
IsTimeout returns a boolean indicating whether the error is known to report that a timeout occurred.
This function predates errors.Is, and the notion of whether an error indicates a timeout can be ambiguous. For example, the Unix error EWOULDBLOCK sometimes indicates a timeout and sometimes does not. New code should use errors.Is with a value appropriate to the call returning the error, such as os.ErrDeadlineExceeded.
func LookupEnv ¶ added in v0.9.2
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.
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 ¶ added in v0.9.1
TODO(xsw): func MkdirAll(path string, perm FileMode) error func MkdirTemp(dir, pattern string) (string, error) func NewSyscallError(syscall string, err error) error
func SameFile ¶ added in v0.8.10
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 UserCacheDir ¶ added in v0.8.10
UserCacheDir returns the default root directory to use for user-specific cached data. Users should create their own application-specific subdirectory within this one and use that.
On Unix systems, it returns $XDG_CACHE_HOME as specified by https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html if non-empty, else $HOME/.cache. On Darwin, it returns $HOME/Library/Caches. On Windows, it returns %LocalAppData%. On Plan 9, it returns $home/lib/cache.
If the location cannot be determined (for example, $HOME is not defined), then it will return an error.
func UserConfigDir ¶ added in v0.8.10
UserConfigDir returns the default root directory to use for user-specific configuration data. Users should create their own application-specific subdirectory within this one and use that.
On Unix systems, it returns $XDG_CONFIG_HOME as specified by https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html if non-empty, else $HOME/.config. On Darwin, it returns $HOME/Library/Application Support. On Windows, it returns %AppData%. On Plan 9, it returns $home/lib.
If the location cannot be determined (for example, $HOME is not defined), then it will return an error.
func UserHomeDir ¶ added in v0.8.10
UserHomeDir returns the current user's home directory.
On Unix, including macOS, it returns the $HOME environment variable. On Windows, it returns %USERPROFILE%. On Plan 9, it returns the $home environment variable.
If the expected variable is not set in the environment, UserHomeDir returns either a platform-specific default value or a non-nil error.
Types ¶
type File ¶ added in v0.8.10
type File struct {
// contains filtered or unexported fields
}
File represents an open file descriptor.
func Create ¶ added in v0.9.1
Create creates or truncates the named file. If the file already exists, it is truncated. If the file does not exist, it is created with mode 0666 (before umask). 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 NewFile ¶ added in v0.8.10
NewFile returns a new File with the given file descriptor and name. The returned value will be nil if fd is not a valid file descriptor. On Unix systems, if the file descriptor is in non-blocking mode, NewFile will attempt to return a pollable File (one for which the SetDeadline methods work).
After passing it to NewFile, fd may become invalid under the same conditions described in the comments of the Fd method, and the same constraints apply.
func Open ¶ added in v0.9.1
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 v0.9.1
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.). If the file does not exist, and the O_CREATE flag is passed, it is created with mode perm (before umask). 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 ¶ added in v0.8.10
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 ¶ added in v0.8.10
Chmod changes the mode of the file to mode. If there is an error, it will be of type *PathError.
func (*File) Chown ¶ added in v0.8.10
Chown changes the numeric uid and gid of the named file. If there is an error, it will be of type *PathError.
On Windows, it always returns the syscall.EWINDOWS error, wrapped in *PathError.
func (*File) Close ¶ added in v0.8.10
Close closes the File, rendering it unusable for I/O. On files that support SetDeadline, any pending I/O operations will be canceled and return immediately with an ErrClosed error. Close will return an error if it has already been called.
func (*File) Fd ¶ added in v0.9.1
Fd returns the integer Unix file descriptor referencing the open file. If f is closed, the file descriptor becomes invalid. If f is garbage collected, a finalizer may close the file descriptor, making it invalid; see runtime.SetFinalizer for more information on when a finalizer might be run. On Unix systems this will cause the SetDeadline methods to stop working. Because file descriptors can be reused, the returned file descriptor may only be closed through the Close method of f, or by its finalizer during garbage collection. Otherwise, during garbage collection the finalizer may close an unrelated file descriptor with the same (reused) number.
As an alternative, see the f.SyscallConn method.
func (*File) Read ¶ added in v0.8.10
Read reads up to len(b) bytes from the File and stores them in b. 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 v0.8.10
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) Seek ¶ added in v0.8.10
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 v0.8.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.
If the deadline is exceeded a call to Read or Write or to other I/O methods will return an error that wraps ErrDeadlineExceeded. This can be tested using errors.Is(err, os.ErrDeadlineExceeded). That error implements the Timeout method, and calling the Timeout method will return true, but there are other possible errors for which the Timeout will return true even if the deadline has not been exceeded.
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 v0.8.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 v0.8.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) Stat ¶ added in v0.9.1
Stat returns the FileInfo structure describing file. If there is an error, it will be of type *PathError.
func (*File) Sync ¶ added in v0.8.10
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) SyscallConn ¶ added in v0.8.10
SyscallConn returns a raw file. This implements the syscall.Conn interface.
func (*File) Truncate ¶ added in v0.8.10
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 ¶ added in v0.8.10
Write writes len(b) bytes from b 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 ¶ added in v0.8.10
A FileInfo describes a file and is returned by Stat and Lstat.
type FileMode ¶
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.
type LinkError ¶
LinkError records an error during a link or symlink or rename system call and the paths that caused it.
type ProcAttr ¶ added in v0.9.1
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 }
ProcAttr holds the attributes that will be applied to a new process started by StartProcess.
type Process ¶ added in v0.9.1
type Process struct { Pid int // contains filtered or unexported fields }
Process stores the information about a process created by StartProcess.
func FindProcess ¶ added in v0.9.1
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. To test whether the process actually exists, see whether p.Signal(syscall.Signal(0)) reports an error.
func StartProcess ¶ added in v0.9.1
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) Kill ¶ added in v0.9.1
Kill causes the Process to exit immediately. Kill does not wait until the Process has actually exited. This only kills the Process itself, not any other processes it may have started.
func (*Process) Release ¶ added in v0.9.1
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 ¶ added in v0.9.1
Signal sends a signal to the Process. Sending Interrupt on Windows is not implemented.
func (*Process) Wait ¶ added in v0.9.1
func (p *Process) Wait() (*ProcessState, error)
Wait waits for the Process to exit, and then returns a ProcessState describing its status and an error, if any. Wait releases any resources associated with the Process. On most operating systems, the Process must be a child of the current process or an error will be returned.
type ProcessState ¶ added in v0.9.1
type ProcessState struct {
// contains filtered or unexported fields
}
ProcessState stores information about a process, as reported by Wait.
func (*ProcessState) ExitCode ¶ added in v0.9.1
func (p *ProcessState) ExitCode() int
ExitCode returns the exit code of the exited process, or -1 if the process hasn't exited or was terminated by a signal.
func (*ProcessState) Exited ¶ added in v0.9.1
func (p *ProcessState) Exited() bool
Exited reports whether the program has exited. On Unix systems this reports true if the program exited due to calling exit, but false if the program terminated due to a signal.
func (*ProcessState) Pid ¶ added in v0.9.1
func (p *ProcessState) Pid() int
Pid returns the process id of the exited process.
func (*ProcessState) String ¶ added in v0.9.1
func (p *ProcessState) String() string
func (*ProcessState) Success ¶ added in v0.9.1
func (p *ProcessState) Success() bool
Success reports whether the program exited successfully, such as with exit status 0 on Unix.
func (*ProcessState) Sys ¶ added in v0.9.1
func (p *ProcessState) Sys() any
Sys returns system-dependent exit information about the process. Convert it to the appropriate underlying type, such as syscall.WaitStatus on Unix, to access its contents.
func (*ProcessState) SysUsage ¶ added in v0.9.1
func (p *ProcessState) SysUsage() any
SysUsage returns system-dependent resource usage information about the exited process. Convert it to the appropriate underlying type, such as *syscall.Rusage on Unix, to access its contents. (On Unix, *syscall.Rusage matches struct rusage as defined in the getrusage(2) manual page.)
func (*ProcessState) SystemTime ¶ added in v0.9.1
func (p *ProcessState) SystemTime() time.Duration
SystemTime returns the system CPU time of the exited process and its children.
func (*ProcessState) UserTime ¶ added in v0.9.1
func (p *ProcessState) UserTime() time.Duration
UserTime returns the user CPU time of the exited process and its children.
type Signal ¶ added in v0.9.1
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.
The only signal values guaranteed to be present in the os package on all systems are os.Interrupt (send the process an interrupt) and os.Kill (force the process to exit). On Windows, sending os.Interrupt to a process with os.Process.Signal is not implemented; it will return an error instead of sending a signal.
type SyscallError ¶
SyscallError records an error from a specific system call.
func (*SyscallError) Error ¶
func (e *SyscallError) Error() string
func (*SyscallError) Timeout ¶
func (e *SyscallError) Timeout() bool
Timeout reports whether this error represents a timeout.
func (*SyscallError) Unwrap ¶
func (e *SyscallError) Unwrap() error