...
Run Format

Source file src/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	//
    50	// Note that the Go runtime writes to standard error for panics and crashes;
    51	// closing Stderr may cause those messages to go elsewhere, perhaps
    52	// to a file opened later.
    53	var (
    54		Stdin  = NewFile(uintptr(syscall.Stdin), "/dev/stdin")
    55		Stdout = NewFile(uintptr(syscall.Stdout), "/dev/stdout")
    56		Stderr = NewFile(uintptr(syscall.Stderr), "/dev/stderr")
    57	)
    58	
    59	// Flags to OpenFile wrapping those of the underlying system. Not all
    60	// flags may be implemented on a given system.
    61	const (
    62		O_RDONLY int = syscall.O_RDONLY // open the file read-only.
    63		O_WRONLY int = syscall.O_WRONLY // open the file write-only.
    64		O_RDWR   int = syscall.O_RDWR   // open the file read-write.
    65		O_APPEND int = syscall.O_APPEND // append data to the file when writing.
    66		O_CREATE int = syscall.O_CREAT  // create a new file if none exists.
    67		O_EXCL   int = syscall.O_EXCL   // used with O_CREATE, file must not exist
    68		O_SYNC   int = syscall.O_SYNC   // open for synchronous I/O.
    69		O_TRUNC  int = syscall.O_TRUNC  // if possible, truncate file when opened.
    70	)
    71	
    72	// Seek whence values.
    73	//
    74	// Deprecated: Use io.SeekStart, io.SeekCurrent, and io.SeekEnd.
    75	const (
    76		SEEK_SET int = 0 // seek relative to the origin of the file
    77		SEEK_CUR int = 1 // seek relative to the current offset
    78		SEEK_END int = 2 // seek relative to the end
    79	)
    80	
    81	// LinkError records an error during a link or symlink or rename
    82	// system call and the paths that caused it.
    83	type LinkError struct {
    84		Op  string
    85		Old string
    86		New string
    87		Err error
    88	}
    89	
    90	func (e *LinkError) Error() string {
    91		return e.Op + " " + e.Old + " " + e.New + ": " + e.Err.Error()
    92	}
    93	
    94	// Read reads up to len(b) bytes from the File.
    95	// It returns the number of bytes read and an error, if any.
    96	// EOF is signaled by a zero count with err set to io.EOF.
    97	func (f *File) Read(b []byte) (n int, err error) {
    98		if f == nil {
    99			return 0, ErrInvalid
   100		}
   101		n, e := f.read(b)
   102		if n == 0 && len(b) > 0 && e == nil {
   103			return 0, io.EOF
   104		}
   105		if e != nil {
   106			err = &PathError{"read", f.name, e}
   107		}
   108		return n, err
   109	}
   110	
   111	// ReadAt reads len(b) bytes from the File starting at byte offset off.
   112	// It returns the number of bytes read and the error, if any.
   113	// ReadAt always returns a non-nil error when n < len(b).
   114	// At end of file, that error is io.EOF.
   115	func (f *File) ReadAt(b []byte, off int64) (n int, err error) {
   116		if f == nil {
   117			return 0, ErrInvalid
   118		}
   119		for len(b) > 0 {
   120			m, e := f.pread(b, off)
   121			if m == 0 && e == nil {
   122				return n, io.EOF
   123			}
   124			if e != nil {
   125				err = &PathError{"read", f.name, e}
   126				break
   127			}
   128			n += m
   129			b = b[m:]
   130			off += int64(m)
   131		}
   132		return
   133	}
   134	
   135	// Write writes len(b) bytes to the File.
   136	// It returns the number of bytes written and an error, if any.
   137	// Write returns a non-nil error when n != len(b).
   138	func (f *File) Write(b []byte) (n int, err error) {
   139		if f == nil {
   140			return 0, ErrInvalid
   141		}
   142		n, e := f.write(b)
   143		if n < 0 {
   144			n = 0
   145		}
   146		if n != len(b) {
   147			err = io.ErrShortWrite
   148		}
   149	
   150		epipecheck(f, e)
   151	
   152		if e != nil {
   153			err = &PathError{"write", f.name, e}
   154		}
   155		return n, err
   156	}
   157	
   158	// WriteAt writes len(b) bytes to the File starting at byte offset off.
   159	// It returns the number of bytes written and an error, if any.
   160	// WriteAt returns a non-nil error when n != len(b).
   161	func (f *File) WriteAt(b []byte, off int64) (n int, err error) {
   162		if f == nil {
   163			return 0, ErrInvalid
   164		}
   165		for len(b) > 0 {
   166			m, e := f.pwrite(b, off)
   167			if e != nil {
   168				err = &PathError{"write", f.name, e}
   169				break
   170			}
   171			n += m
   172			b = b[m:]
   173			off += int64(m)
   174		}
   175		return
   176	}
   177	
   178	// Seek sets the offset for the next Read or Write on file to offset, interpreted
   179	// according to whence: 0 means relative to the origin of the file, 1 means
   180	// relative to the current offset, and 2 means relative to the end.
   181	// It returns the new offset and an error, if any.
   182	// The behavior of Seek on a file opened with O_APPEND is not specified.
   183	func (f *File) Seek(offset int64, whence int) (ret int64, err error) {
   184		if f == nil {
   185			return 0, ErrInvalid
   186		}
   187		r, e := f.seek(offset, whence)
   188		if e == nil && f.dirinfo != nil && r != 0 {
   189			e = syscall.EISDIR
   190		}
   191		if e != nil {
   192			return 0, &PathError{"seek", f.name, e}
   193		}
   194		return r, nil
   195	}
   196	
   197	// WriteString is like Write, but writes the contents of string s rather than
   198	// a slice of bytes.
   199	func (f *File) WriteString(s string) (n int, err error) {
   200		if f == nil {
   201			return 0, ErrInvalid
   202		}
   203		return f.Write([]byte(s))
   204	}
   205	
   206	// Mkdir creates a new directory with the specified name and permission bits.
   207	// If there is an error, it will be of type *PathError.
   208	func Mkdir(name string, perm FileMode) error {
   209		e := syscall.Mkdir(name, syscallMode(perm))
   210	
   211		if e != nil {
   212			return &PathError{"mkdir", name, e}
   213		}
   214	
   215		// mkdir(2) itself won't handle the sticky bit on *BSD and Solaris
   216		if !supportsCreateWithStickyBit && perm&ModeSticky != 0 {
   217			Chmod(name, perm)
   218		}
   219	
   220		return nil
   221	}
   222	
   223	// Chdir changes the current working directory to the named directory.
   224	// If there is an error, it will be of type *PathError.
   225	func Chdir(dir string) error {
   226		if e := syscall.Chdir(dir); e != nil {
   227			return &PathError{"chdir", dir, e}
   228		}
   229		return nil
   230	}
   231	
   232	// Chdir changes the current working directory to the file,
   233	// which must be a directory.
   234	// If there is an error, it will be of type *PathError.
   235	func (f *File) Chdir() error {
   236		if f == nil {
   237			return ErrInvalid
   238		}
   239		if e := syscall.Fchdir(f.fd); e != nil {
   240			return &PathError{"chdir", f.name, e}
   241		}
   242		return nil
   243	}
   244	
   245	// Open opens the named file for reading. If successful, methods on
   246	// the returned file can be used for reading; the associated file
   247	// descriptor has mode O_RDONLY.
   248	// If there is an error, it will be of type *PathError.
   249	func Open(name string) (*File, error) {
   250		return OpenFile(name, O_RDONLY, 0)
   251	}
   252	
   253	// Create creates the named file with mode 0666 (before umask), truncating
   254	// it if it already exists. If successful, methods on the returned
   255	// File can be used for I/O; the associated file descriptor has mode
   256	// O_RDWR.
   257	// If there is an error, it will be of type *PathError.
   258	func Create(name string) (*File, error) {
   259		return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
   260	}
   261	
   262	// lstat is overridden in tests.
   263	var lstat = Lstat
   264	
   265	// Rename renames (moves) oldpath to newpath.
   266	// If newpath already exists, Rename replaces it.
   267	// OS-specific restrictions may apply when oldpath and newpath are in different directories.
   268	// If there is an error, it will be of type *LinkError.
   269	func Rename(oldpath, newpath string) error {
   270		return rename(oldpath, newpath)
   271	}
   272	
   273	// Many functions in package syscall return a count of -1 instead of 0.
   274	// Using fixCount(call()) instead of call() corrects the count.
   275	func fixCount(n int, err error) (int, error) {
   276		if n < 0 {
   277			n = 0
   278		}
   279		return n, err
   280	}
   281	

View as plain text