Run Format

Source file src/pkg/os/file.go

     1	// Copyright 2009 The Go Authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style
     3	// license that can be found in the LICENSE file.
     4	
     5	// Package os provides a platform-independent interface to operating system
     6	// functionality. The design is Unix-like, although the error handling is
     7	// Go-like; failing calls return values of type error rather than error numbers.
     8	// Often, more information is available within the error. For example,
     9	// if a call that takes a file name fails, such as Open or Stat, the error
    10	// will include the failing file name when printed and will be of type
    11	// *PathError, which may be unpacked for more information.
    12	//
    13	// The os interface is intended to be uniform across all operating systems.
    14	// Features not generally available appear in the system-specific package syscall.
    15	//
    16	// Here is a simple example, opening a file and reading some of it.
    17	//
    18	//	file, err := os.Open("file.go") // For read access.
    19	//	if err != nil {
    20	//		log.Fatal(err)
    21	//	}
    22	//
    23	// If the open fails, the error string will be self-explanatory, like
    24	//
    25	//	open file.go: no such file or directory
    26	//
    27	// The file's data can then be read into a slice of bytes. Read and
    28	// Write take their byte counts from the length of the argument slice.
    29	//
    30	//	data := make([]byte, 100)
    31	//	count, err := file.Read(data)
    32	//	if err != nil {
    33	//		log.Fatal(err)
    34	//	}
    35	//	fmt.Printf("read %d bytes: %q\n", count, data[:count])
    36	//
    37	package os
    38	
    39	import (
    40		"io"
    41		"syscall"
    42	)
    43	
    44	// Name returns the name of the file as presented to Open.
    45	func (f *File) Name() string { return f.name }
    46	
    47	// Stdin, Stdout, and Stderr are open Files pointing to the standard input,
    48	// standard output, and standard error file descriptors.
    49	var (
    50		Stdin  = NewFile(uintptr(syscall.Stdin), "/dev/stdin")
    51		Stdout = NewFile(uintptr(syscall.Stdout), "/dev/stdout")
    52		Stderr = NewFile(uintptr(syscall.Stderr), "/dev/stderr")
    53	)
    54	
    55	// Flags to Open wrapping those of the underlying system. Not all flags
    56	// may be implemented on a given system.
    57	const (
    58		O_RDONLY int = syscall.O_RDONLY // open the file read-only.
    59		O_WRONLY int = syscall.O_WRONLY // open the file write-only.
    60		O_RDWR   int = syscall.O_RDWR   // open the file read-write.
    61		O_APPEND int = syscall.O_APPEND // append data to the file when writing.
    62		O_CREATE int = syscall.O_CREAT  // create a new file if none exists.
    63		O_EXCL   int = syscall.O_EXCL   // used with O_CREATE, file must not exist
    64		O_SYNC   int = syscall.O_SYNC   // open for synchronous I/O.
    65		O_TRUNC  int = syscall.O_TRUNC  // if possible, truncate file when opened.
    66	)
    67	
    68	// Seek whence values.
    69	const (
    70		SEEK_SET int = 0 // seek relative to the origin of the file
    71		SEEK_CUR int = 1 // seek relative to the current offset
    72		SEEK_END int = 2 // seek relative to the end
    73	)
    74	
    75	// LinkError records an error during a link or symlink or rename
    76	// system call and the paths that caused it.
    77	type LinkError struct {
    78		Op  string
    79		Old string
    80		New string
    81		Err error
    82	}
    83	
    84	func (e *LinkError) Error() string {
    85		return e.Op + " " + e.Old + " " + e.New + ": " + e.Err.Error()
    86	}
    87	
    88	// Read reads up to len(b) bytes from the File.
    89	// It returns the number of bytes read and an error, if any.
    90	// EOF is signaled by a zero count with err set to io.EOF.
    91	func (f *File) Read(b []byte) (n int, err error) {
    92		if f == nil {
    93			return 0, ErrInvalid
    94		}
    95		n, e := f.read(b)
    96		if n < 0 {
    97			n = 0
    98		}
    99		if n == 0 && len(b) > 0 && e == nil {
   100			return 0, io.EOF
   101		}
   102		if e != nil {
   103			err = &PathError{"read", f.name, e}
   104		}
   105		return n, err
   106	}
   107	
   108	// ReadAt reads len(b) bytes from the File starting at byte offset off.
   109	// It returns the number of bytes read and the error, if any.
   110	// ReadAt always returns a non-nil error when n < len(b).
   111	// At end of file, that error is io.EOF.
   112	func (f *File) ReadAt(b []byte, off int64) (n int, err error) {
   113		if f == nil {
   114			return 0, ErrInvalid
   115		}
   116		for len(b) > 0 {
   117			m, e := f.pread(b, off)
   118			if m == 0 && e == nil {
   119				return n, io.EOF
   120			}
   121			if e != nil {
   122				err = &PathError{"read", f.name, e}
   123				break
   124			}
   125			n += m
   126			b = b[m:]
   127			off += int64(m)
   128		}
   129		return
   130	}
   131	
   132	// Write writes len(b) bytes to the File.
   133	// It returns the number of bytes written and an error, if any.
   134	// Write returns a non-nil error when n != len(b).
   135	func (f *File) Write(b []byte) (n int, err error) {
   136		if f == nil {
   137			return 0, ErrInvalid
   138		}
   139		n, e := f.write(b)
   140		if n < 0 {
   141			n = 0
   142		}
   143	
   144		epipecheck(f, e)
   145	
   146		if e != nil {
   147			err = &PathError{"write", f.name, e}
   148		}
   149		return n, err
   150	}
   151	
   152	// WriteAt writes len(b) bytes to the File starting at byte offset off.
   153	// It returns the number of bytes written and an error, if any.
   154	// WriteAt returns a non-nil error when n != len(b).
   155	func (f *File) WriteAt(b []byte, off int64) (n int, err error) {
   156		if f == nil {
   157			return 0, ErrInvalid
   158		}
   159		for len(b) > 0 {
   160			m, e := f.pwrite(b, off)
   161			if e != nil {
   162				err = &PathError{"write", f.name, e}
   163				break
   164			}
   165			n += m
   166			b = b[m:]
   167			off += int64(m)
   168		}
   169		return
   170	}
   171	
   172	// Seek sets the offset for the next Read or Write on file to offset, interpreted
   173	// according to whence: 0 means relative to the origin of the file, 1 means
   174	// relative to the current offset, and 2 means relative to the end.
   175	// It returns the new offset and an error, if any.
   176	func (f *File) Seek(offset int64, whence int) (ret int64, err error) {
   177		if f == nil {
   178			return 0, ErrInvalid
   179		}
   180		r, e := f.seek(offset, whence)
   181		if e == nil && f.dirinfo != nil && r != 0 {
   182			e = syscall.EISDIR
   183		}
   184		if e != nil {
   185			return 0, &PathError{"seek", f.name, e}
   186		}
   187		return r, nil
   188	}
   189	
   190	// WriteString is like Write, but writes the contents of string s rather than
   191	// a slice of bytes.
   192	func (f *File) WriteString(s string) (ret int, err error) {
   193		if f == nil {
   194			return 0, ErrInvalid
   195		}
   196		return f.Write([]byte(s))
   197	}
   198	
   199	// Mkdir creates a new directory with the specified name and permission bits.
   200	// If there is an error, it will be of type *PathError.
   201	func Mkdir(name string, perm FileMode) error {
   202		e := syscall.Mkdir(name, syscallMode(perm))
   203		if e != nil {
   204			return &PathError{"mkdir", name, e}
   205		}
   206		return nil
   207	}
   208	
   209	// Chdir changes the current working directory to the named directory.
   210	// If there is an error, it will be of type *PathError.
   211	func Chdir(dir string) error {
   212		if e := syscall.Chdir(dir); e != nil {
   213			return &PathError{"chdir", dir, e}
   214		}
   215		return nil
   216	}
   217	
   218	// Chdir changes the current working directory to the file,
   219	// which must be a directory.
   220	// If there is an error, it will be of type *PathError.
   221	func (f *File) Chdir() error {
   222		if f == nil {
   223			return ErrInvalid
   224		}
   225		if e := syscall.Fchdir(f.fd); e != nil {
   226			return &PathError{"chdir", f.name, e}
   227		}
   228		return nil
   229	}
   230	
   231	// Open opens the named file for reading.  If successful, methods on
   232	// the returned file can be used for reading; the associated file
   233	// descriptor has mode O_RDONLY.
   234	// If there is an error, it will be of type *PathError.
   235	func Open(name string) (file *File, err error) {
   236		return OpenFile(name, O_RDONLY, 0)
   237	}
   238	
   239	// Create creates the named file mode 0666 (before umask), truncating
   240	// it if it already exists.  If successful, methods on the returned
   241	// File can be used for I/O; the associated file descriptor has mode
   242	// O_RDWR.
   243	// If there is an error, it will be of type *PathError.
   244	func Create(name string) (file *File, err error) {
   245		return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
   246	}
   247	
   248	// lstat is overridden in tests.
   249	var lstat = Lstat

View as plain text