Package os
import "os"
Package os provides a platform-independent interface to operating system functionality. The design is Unix-like. The os interface is intended to be uniform across all operating systems. Features not generally available appear in the system-specific package syscall.
Package files
dir_unix.go env.go env_unix.go error.go error_posix.go exec.go exec_posix.go exec_unix.go file.go file_posix.go file_unix.go getwd.go path.go path_unix.go proc.go stat_linux.go str.go sys_bsd.go sys_linux.go time.go types.goConstants
Options for Wait.
const (
WNOHANG = syscall.WNOHANG // Don't wait if no process has exited.
WSTOPPED = syscall.WSTOPPED // If set, status of stopped subprocesses is also reported.
WUNTRACED = syscall.WUNTRACED // Usually an alias for WSTOPPED.
WRUSAGE = 1 << 20 // Record resource usage.
)
const (
PathSeparator = '/' // OS-specific path separator
PathListSeparator = ':' // OS-specific path list separator
)
Flags to Open wrapping those of the underlying system. Not all flags may be implemented on a given system.
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_ASYNC int = syscall.O_ASYNC // generate a signal when I/O is available.
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_NOCTTY int = syscall.O_NOCTTY // do not make file the controlling tty.
O_NONBLOCK int = syscall.O_NONBLOCK // open in non-blocking mode.
O_NDELAY int = O_NONBLOCK // synonym for O_NONBLOCK
O_SYNC int = syscall.O_SYNC // open for synchronous I/O.
O_TRUNC int = syscall.O_TRUNC // if possible, truncate file when opened.
)
Seek whence values.
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
)
DevNull is the name of the operating system's “null device.” On Unix-like systems, it is "/dev/null"; on Windows, "NUL".
const DevNull = "/dev/null"
Variables
Stdin, Stdout, and Stderr are open Files pointing to the standard input, standard output, and standard error file descriptors.
var (
Stdin = NewFile(syscall.Stdin, "/dev/stdin")
Stdout = NewFile(syscall.Stdout, "/dev/stdout")
Stderr = NewFile(syscall.Stderr, "/dev/stderr")
)
var Args []string // provided by runtime
ENOENV is the Error indicating that an environment variable does not exist.
var ENOENV = NewError("no such environment variable")
var Envs []string // provided by runtime
func Chdir
func Chdir(dir string) Error
Chdir changes the current working directory to the named directory.
func Chmod
func Chmod(name string, mode uint32) Error
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.
func Chown
func Chown(name string, uid, gid int) Error
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.
func Chtimes
func Chtimes(name string, atime_ns int64, mtime_ns int64) Error
Chtimes changes the access and modification times of the named file, similar to the Unix utime() or utimes() functions.
The argument times are in nanoseconds, although the underlying filesystem may truncate or round the values to a more coarse time unit.
func Clearenv
func Clearenv()
Clearenv deletes all environment variables.
func Environ
func Environ() []string
Environ returns an array of strings representing the environment, in the form "key=value".
func Exec
func Exec(name string, argv []string, envv []string) Error
Exec replaces the current process with an execution of the named binary, with arguments argv and environment envv. If successful, Exec never returns. If it fails, it returns an Error.
To run a child process, see StartProcess (for a low-level interface) or the exec package (for higher-level interfaces).
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
func Expand(s string, mapping func(string) string) string
Expand replaces ${var} or $var in the string based on the mapping function. Invocations of undefined variables are replaced with the empty string.
func Getegid
func Getegid() int
Getegid returns the numeric effective group id of the caller.
func Getenv
func Getenv(key string) string
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 Getenverror
func Getenverror(key string) (value string, err Error)
Getenverror retrieves the value of the environment variable named by the key. It returns the value and an error, if any.
func Geteuid
func Geteuid() int
Geteuid returns the numeric effective user id of the caller.
func Getgid
func Getgid() int
Getgid returns the numeric group id of the caller.
func Getgroups
func Getgroups() ([]int, Error)
Getgroups returns a list of the numeric ids of groups that the caller belongs to.
func Getpagesize
func Getpagesize() int
Getpagesize returns the underlying system's memory page size.
func Getpid
func Getpid() int
Getpid returns the process id of the caller.
func Getppid
func Getppid() int
Getppid returns the process id of the caller's parent.
func Getuid
func Getuid() int
Getuid returns the numeric user id of the caller.
func Getwd
func Getwd() (string, Error)
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 Hostname
func Hostname() (name string, err Error)
Hostname returns the host name reported by the kernel.
func IsPathSeparator
func IsPathSeparator(c uint8) bool
IsPathSeparator returns true if c is a directory separator character.
func Lchown
func Lchown(name string, uid, gid int) Error
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.
func Link
func Link(oldname, newname string) Error
Link creates a hard link.
func Mkdir
func Mkdir(name string, perm uint32) Error
Mkdir creates a new directory with the specified name and permission bits. It returns an error, if any.
func MkdirAll
func MkdirAll(path string, perm uint32) Error
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 Readlink
func Readlink(name string) (string, Error)
Readlink reads the contents of a symbolic link: the destination of the link. It returns the contents and an Error, if any.
func Remove
func Remove(name string) Error
Remove removes the named file or directory.
func RemoveAll
func RemoveAll(path string) Error
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
func Rename(oldname, newname string) Error
Rename renames a file.
func Setenv
func Setenv(key, value string) Error
Setenv sets the value of the environment variable named by the key. It returns an Error, if any.
func ShellExpand
func ShellExpand(s string) string
ShellExpand replaces ${var} or $var in the string according to the values of the operating system's environment variables. References to undefined variables are replaced by the empty string.
func Symlink
func Symlink(oldname, newname string) Error
Symlink creates a symbolic link.
func TempDir
func TempDir() string
TempDir returns the default directory to use for temporary files.
func Time
func Time() (sec int64, nsec int64, err Error)
Time returns the current time, in whole seconds and fractional nanoseconds, plus an Error if any. The current time is thus 1e9*sec+nsec, in nanoseconds. The zero of time is the Unix epoch.
func Truncate
func Truncate(name string, size int64) Error
Truncate changes the size of the named file. If the file is a symbolic link, it changes the size of the link's target.
type Errno
Errno is the Unix error number. Names such as EINVAL are simple wrappers to convert the error number into an Error.
type Errno int64
func (Errno) String
func (e Errno) String() string
func (Errno) Temporary
func (e Errno) Temporary() bool
func (Errno) Timeout
func (e Errno) Timeout() bool
type Error
An Error can represent any printable error condition.
type Error interface {
String() string
}
Commonly known Unix errors.
var (
EPERM Error = Errno(syscall.EPERM)
ENOENT Error = Errno(syscall.ENOENT)
ESRCH Error = Errno(syscall.ESRCH)
EINTR Error = Errno(syscall.EINTR)
EIO Error = Errno(syscall.EIO)
ENXIO Error = Errno(syscall.ENXIO)
E2BIG Error = Errno(syscall.E2BIG)
ENOEXEC Error = Errno(syscall.ENOEXEC)
EBADF Error = Errno(syscall.EBADF)
ECHILD Error = Errno(syscall.ECHILD)
EDEADLK Error = Errno(syscall.EDEADLK)
ENOMEM Error = Errno(syscall.ENOMEM)
EACCES Error = Errno(syscall.EACCES)
EFAULT Error = Errno(syscall.EFAULT)
EBUSY Error = Errno(syscall.EBUSY)
EEXIST Error = Errno(syscall.EEXIST)
EXDEV Error = Errno(syscall.EXDEV)
ENODEV Error = Errno(syscall.ENODEV)
ENOTDIR Error = Errno(syscall.ENOTDIR)
EISDIR Error = Errno(syscall.EISDIR)
EINVAL Error = Errno(syscall.EINVAL)
ENFILE Error = Errno(syscall.ENFILE)
EMFILE Error = Errno(syscall.EMFILE)
ENOTTY Error = Errno(syscall.ENOTTY)
EFBIG Error = Errno(syscall.EFBIG)
ENOSPC Error = Errno(syscall.ENOSPC)
ESPIPE Error = Errno(syscall.ESPIPE)
EROFS Error = Errno(syscall.EROFS)
EMLINK Error = Errno(syscall.EMLINK)
EPIPE Error = Errno(syscall.EPIPE)
EAGAIN Error = Errno(syscall.EAGAIN)
EDOM Error = Errno(syscall.EDOM)
ERANGE Error = Errno(syscall.ERANGE)
EADDRINUSE Error = Errno(syscall.EADDRINUSE)
ECONNREFUSED Error = Errno(syscall.ECONNREFUSED)
ENAMETOOLONG Error = Errno(syscall.ENAMETOOLONG)
EAFNOSUPPORT Error = Errno(syscall.EAFNOSUPPORT)
ETIMEDOUT Error = Errno(syscall.ETIMEDOUT)
ENOTCONN Error = Errno(syscall.ENOTCONN)
)
EOF is the Error returned by Read when no more input is available. Functions should return EOF only to signal a graceful end of input. If the EOF occurs unexpectedly in a structured data stream, the appropriate error is either io.ErrUnexpectedEOF or some other error giving more detail.
var EOF Error = eofError(0)
func NewError
func NewError(s string) Error
// NewError returns a new error with error.String() == s.
func NewSyscallError
func NewSyscallError(syscall string, errno int) Error
NewSyscallError returns, as an Error, a new SyscallError with the given system call name and error details. As a convenience, if errno is 0, NewSyscallError returns nil.
type File
File represents an open file descriptor.
type File struct {
// contains filtered or unexported fields
}
func Create
func Create(name string) (file *File, err Error)
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. It returns the File and an Error, if any.
func NewFile
func NewFile(fd int, name string) *File
NewFile returns a new File with the given file descriptor and name.
func Open
func Open(name string) (file *File, err Error)
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. It returns the File and an Error, if any.
func OpenFile
func OpenFile(name string, flag int, perm uint32) (file *File, err Error)
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. It returns the File and an Error, if any.
func Pipe
func Pipe() (r *File, w *File, err Error)
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 (*File) Chdir
func (f *File) Chdir() Error
Chdir changes the current working directory to the file, which must be a directory.
func (*File) Chmod
func (f *File) Chmod(mode uint32) Error
Chmod changes the mode of the file to mode.
func (*File) Chown
func (f *File) Chown(uid, gid int) Error
Chown changes the numeric uid and gid of the named file.
func (*File) Close
func (file *File) Close() Error
Close closes the File, rendering it unusable for I/O. It returns an Error, if any.
func (*File) Fd
func (file *File) Fd() int
Fd returns the integer Unix file descriptor referencing the open file.
func (*File) Name
func (file *File) Name() string
Name returns the name of the file as presented to Open.
func (*File) Read
func (file *File) Read(b []byte) (n int, err Error)
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 EOF.
func (*File) ReadAt
func (file *File) ReadAt(b []byte, off int64) (n int, err Error)
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. EOF is signaled by a zero count with err set to EOF. ReadAt always returns a non-nil Error when n != len(b).
func (*File) Readdir
func (file *File) Readdir(n int) (fi []FileInfo, err Error)
Readdir reads the contents of the directory associated with file and returns an array of up to n FileInfo structures, 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 os.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 os.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
func (f *File) Readdirnames(n int) (names []string, err Error)
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 os.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 os.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
func (file *File) Seek(offset int64, whence int) (ret int64, err Error)
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
func (file *File) Stat() (fi *FileInfo, err Error)
Stat returns the FileInfo structure describing file. It returns the FileInfo and an error, if any.
func (*File) Sync
func (file *File) Sync() (err Error)
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
func (f *File) Truncate(size int64) Error
Truncate changes the size of the file. It does not change the I/O offset.
func (*File) Write
func (file *File) Write(b []byte) (n int, err Error)
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).
func (*File) WriteAt
func (file *File) WriteAt(b []byte, off int64) (n int, err Error)
WriteAt writes len(b) bytes to the File starting at byte offset off. It returns the number of bytes written and an Error, if any. WriteAt returns a non-nil Error when n != len(b).
func (*File) WriteString
func (file *File) WriteString(s string) (ret int, err Error)
WriteString is like Write, but writes the contents of string s rather than an array of bytes.
type FileInfo
A FileInfo describes a file and is returned by Stat, Fstat, and Lstat
type FileInfo struct {
Dev uint64 // device number of file system holding file.
Ino uint64 // inode number.
Nlink uint64 // number of hard links.
Mode uint32 // permission and mode bits.
Uid int // user id of owner.
Gid int // group id of owner.
Rdev uint64 // device type for special file.
Size int64 // length in bytes.
Blksize int64 // size of blocks, in bytes.
Blocks int64 // number of blocks allocated for file.
Atime_ns int64 // access time; nanoseconds since epoch.
Mtime_ns int64 // modified time; nanoseconds since epoch.
Ctime_ns int64 // status change time; nanoseconds since epoch.
Name string // base name of the file name provided in Open, Stat, etc.
FollowedSymlink bool // followed a symlink to get this information
}
func Lstat
func Lstat(name string) (fi *FileInfo, err Error)
Lstat returns the FileInfo structure describing the named file and an error, if any. If the file is a symbolic link, the returned FileInfo describes the symbolic link. Lstat makes no attempt to follow the link.
func Stat
func Stat(name string) (fi *FileInfo, err Error)
Stat returns a FileInfo structure describing the named file and an error, if any. If name names a valid symbolic link, the returned FileInfo describes the file pointed at by the link and has fi.FollowedSymlink set to true. If name names an invalid symbolic link, the returned FileInfo describes the link itself and has fi.FollowedSymlink set to false.
func (*FileInfo) IsBlock
func (f *FileInfo) IsBlock() bool
IsBlock reports whether the FileInfo describes a block special file.
func (*FileInfo) IsChar
func (f *FileInfo) IsChar() bool
IsChar reports whether the FileInfo describes a character special file.
func (*FileInfo) IsDirectory
func (f *FileInfo) IsDirectory() bool
IsDirectory reports whether the FileInfo describes a directory.
func (*FileInfo) IsFifo
func (f *FileInfo) IsFifo() bool
IsFifo reports whether the FileInfo describes a FIFO file.
func (*FileInfo) IsRegular
func (f *FileInfo) IsRegular() bool
IsRegular reports whether the FileInfo describes a regular file.
func (*FileInfo) IsSocket
func (f *FileInfo) IsSocket() bool
IsSocket reports whether the FileInfo describes a socket.
func (*FileInfo) IsSymlink
func (f *FileInfo) IsSymlink() bool
IsSymlink reports whether the FileInfo describes a symbolic link.
func (*FileInfo) Permission
func (f *FileInfo) Permission() uint32
Permission returns the file permission bits.
type LinkError
LinkError records an error during a link or symlink or rename system call and the paths that caused it.
type LinkError struct {
Op string
Old string
New string
Error Error
}
func (*LinkError) String
func (e *LinkError) String() string
type PathError
PathError records an error and the operation and file path that caused it.
type PathError struct {
Op string
Path string
Error Error
}
func (*PathError) String
func (e *PathError) String() string
type ProcAttr
ProcAttr holds the attributes that will be applied to a new process started by 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.
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 stores the information about a process created by StartProcess.
type Process struct {
Pid int
// contains filtered or unexported fields
}
func FindProcess
func FindProcess(pid int) (p *Process, err Error)
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.
func StartProcess
func StartProcess(name string, argv []string, attr *ProcAttr) (p *Process, err Error)
StartProcess starts a new process with the program, arguments and attributes specified by name, argv and attr.
StartProcess is a low-level interface. The exec package provides higher-level interfaces.
func (*Process) Kill
func (p *Process) Kill() Error
Kill causes the Process to exit immediately.
func (*Process) Release
func (p *Process) Release() Error
Release releases any resources associated with the Process.
func (*Process) Signal
func (p *Process) Signal(sig Signal) Error
Signal sends a signal to the Process.
func (*Process) Wait
func (p *Process) Wait(options int) (w *Waitmsg, err Error)
Wait waits for the Process to exit or stop, and then returns a Waitmsg describing its status and an Error, if any. The options (WNOHANG etc.) affect the behavior of the Wait call.
type Signal
A Signal can represent any operating system signal.
type Signal interface {
String() string
}
type SyscallError
SyscallError records an error from a specific system call.
type SyscallError struct {
Syscall string
Errno Errno
}
func (*SyscallError) String
func (e *SyscallError) String() string
type UnixSignal
type UnixSignal int32
func (UnixSignal) String
func (sig UnixSignal) String() string
type Waitmsg
Waitmsg stores the information about an exited process as reported by Wait.
type Waitmsg struct {
Pid int // The process's id.
syscall.WaitStatus // System-dependent status info.
Rusage *syscall.Rusage // System-dependent resource usage info.
}
func Wait
func Wait(pid int, options int) (w *Waitmsg, err Error)
Wait waits for process pid to exit or stop, and then returns a Waitmsg describing its status and an Error, if any. The options (WNOHANG etc.) affect the behavior of the Wait call. Wait is equivalent to calling FindProcess and then Wait and Release on the result.
func (*Waitmsg) String
func (w *Waitmsg) String() string
Need more packages? The Package Dashboard provides a list of goinstallable packages.
Subdirectories
| Name | Synopsis | |
|---|---|---|
| .. | ||
| inotify | Package inotify implements a wrapper for the Linux inotify system. | |
| signal | Package signal implements operating system-independent signal handling. | |
| user | Package user allows user account lookups by name or id. |