os

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 Exit(code int)
• func Getegid() int
• func Geteuid() int
• func Getgid() int
• func Getgroups() ([]int, error)
• func Getuid() int
• func IsPathSeparator(c uint8) bool
• func Mkdir(name string, perm FileMode) error
• func MkdirAll(path string, perm FileMode) error
• func RemoveAll(path string) error
• func Rename(oldpath, newpath string) error
• type File
  • func Create(name string) (file *File, err error)
  • func Open(name string) (file *File, err error)
  • func (f *File) Chdir() error
  • func (file *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) Seek(offset int64, whence int) (ret int64, err 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
  • func Stat(name string) (FileInfo, error)
• type LinkError
  • func (e *LinkError) Error() string

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
)

Variables

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

func Chdir(dir string) error

Chdir changes the current working directory to the named directory. If there is an error, it will be of type *PathError.

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 Getegid

func Getegid() int

Getegid returns the numeric effective group id of the caller.

On Windows, it returns -1.

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

func Getgroups() ([]int, error)

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 Getuid

func Getuid() int

Getuid returns the numeric user id of the caller.

On Windows, it returns -1.

func IsPathSeparator

func IsPathSeparator(c uint8) bool

IsPathSeparator reports whether c is a directory separator character.

func Mkdir

func Mkdir(name string, perm FileMode) error

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

func MkdirAll(path string, perm FileMode) 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 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(oldpath, newpath string) error

Rename renames (moves) a file. OS-specific restrictions might apply.

Types

type File

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. If there is an error, it will be of type *PathError.

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. If there is an error, it will be of type *PathError.

func (*File) Chdir

func (f *File) Chdir() error

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) Close

func (file *File) Close() error

func (*File) Fd

func (f *File) Fd() uintptr

Fd returns the integer Unix file descriptor referencing the open file. The file descriptor is valid only until f.Close is called or f is garbage collected.

func (*File) Name

func (f *File) Name() string

Name returns the name of the file as presented to Open.

func (*File) Read

func (f *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 io.EOF.

func (*File) ReadAt

func (f *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. ReadAt always returns a non-nil error when n < len(b). At end of file, that error is io.EOF.

func (*File) Seek

func (f *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) Write

func (f *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 (f *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 (f *File) WriteString(s string) (ret int, err error)

WriteString is like Write, but writes the contents of string s rather than a slice of bytes.

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.

func Stat

func Stat(name string) (FileInfo, error)

Stat returns a FileInfo describing the named file. If there is an error, it will be of type *PathError.

type LinkError

type LinkError struct {
	Op  string
	Old string
	New string
	Err error
}

LinkError records an error during a link or symlink or rename system call and the paths that caused it.

func (*LinkError) Error

func (e *LinkError) Error() string