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.
     7	// The os interface is intended to be uniform across all operating systems.
     8	// Features not generally available appear in the system-specific package syscall.
     9	package os
    10	
    11	import (
    12		"syscall"
    13	)
    14	
    15	// Name returns the name of the file as presented to Open.
    16	func (file *File) Name() string { return file.name }
    17	
    18	// Stdin, Stdout, and Stderr are open Files pointing to the standard input,
    19	// standard output, and standard error file descriptors.
    20	var (
    21		Stdin  = NewFile(syscall.Stdin, "/dev/stdin")
    22		Stdout = NewFile(syscall.Stdout, "/dev/stdout")
    23		Stderr = NewFile(syscall.Stderr, "/dev/stderr")
    24	)
    25	
    26	// Flags to Open wrapping those of the underlying system. Not all flags
    27	// may be implemented on a given system.
    28	const (
    29		O_RDONLY   int = syscall.O_RDONLY   // open the file read-only.
    30		O_WRONLY   int = syscall.O_WRONLY   // open the file write-only.
    31		O_RDWR     int = syscall.O_RDWR     // open the file read-write.
    32		O_APPEND   int = syscall.O_APPEND   // append data to the file when writing.
    33		O_ASYNC    int = syscall.O_ASYNC    // generate a signal when I/O is available.
    34		O_CREATE   int = syscall.O_CREAT    // create a new file if none exists.
    35		O_EXCL     int = syscall.O_EXCL     // used with O_CREATE, file must not exist
    36		O_NOCTTY   int = syscall.O_NOCTTY   // do not make file the controlling tty.
    37		O_NONBLOCK int = syscall.O_NONBLOCK // open in non-blocking mode.
    38		O_NDELAY   int = O_NONBLOCK         // synonym for O_NONBLOCK
    39		O_SYNC     int = syscall.O_SYNC     // open for synchronous I/O.
    40		O_TRUNC    int = syscall.O_TRUNC    // if possible, truncate file when opened.
    41	)
    42	
    43	// Seek whence values.
    44	const (
    45		SEEK_SET int = 0 // seek relative to the origin of the file
    46		SEEK_CUR int = 1 // seek relative to the current offset
    47		SEEK_END int = 2 // seek relative to the end
    48	)
    49	
    50	type eofError int
    51	
    52	func (eofError) String() string { return "EOF" }
    53	
    54	// EOF is the Error returned by Read when no more input is available.
    55	// Functions should return EOF only to signal a graceful end of input.
    56	// If the EOF occurs unexpectedly in a structured data stream,
    57	// the appropriate error is either io.ErrUnexpectedEOF or some other error
    58	// giving more detail.
    59	var EOF Error = eofError(0)
    60	
    61	// Read reads up to len(b) bytes from the File.
    62	// It returns the number of bytes read and an Error, if any.
    63	// EOF is signaled by a zero count with err set to EOF.
    64	func (file *File) Read(b []byte) (n int, err Error) {
    65		if file == nil {
    66			return 0, EINVAL
    67		}
    68		n, e := file.read(b)
    69		if n < 0 {
    70			n = 0
    71		}
    72		if n == 0 && !iserror(e) {
    73			return 0, EOF
    74		}
    75		if iserror(e) {
    76			err = &PathError{"read", file.name, Errno(e)}
    77		}
    78		return n, err
    79	}
    80	
    81	// ReadAt reads len(b) bytes from the File starting at byte offset off.
    82	// It returns the number of bytes read and the Error, if any.
    83	// EOF is signaled by a zero count with err set to EOF.
    84	// ReadAt always returns a non-nil Error when n != len(b).
    85	func (file *File) ReadAt(b []byte, off int64) (n int, err Error) {
    86		if file == nil {
    87			return 0, EINVAL
    88		}
    89		for len(b) > 0 {
    90			m, e := file.pread(b, off)
    91			if m == 0 && !iserror(e) {
    92				return n, EOF
    93			}
    94			if iserror(e) {
    95				err = &PathError{"read", file.name, Errno(e)}
    96				break
    97			}
    98			n += m
    99			b = b[m:]
   100			off += int64(m)
   101		}
   102		return
   103	}
   104	
   105	// Write writes len(b) bytes to the File.
   106	// It returns the number of bytes written and an Error, if any.
   107	// Write returns a non-nil Error when n != len(b).
   108	func (file *File) Write(b []byte) (n int, err Error) {
   109		if file == nil {
   110			return 0, EINVAL
   111		}
   112		n, e := file.write(b)
   113		if n < 0 {
   114			n = 0
   115		}
   116	
   117		epipecheck(file, e)
   118	
   119		if iserror(e) {
   120			err = &PathError{"write", file.name, Errno(e)}
   121		}
   122		return n, err
   123	}
   124	
   125	// WriteAt writes len(b) bytes to the File starting at byte offset off.
   126	// It returns the number of bytes written and an Error, if any.
   127	// WriteAt returns a non-nil Error when n != len(b).
   128	func (file *File) WriteAt(b []byte, off int64) (n int, err Error) {
   129		if file == nil {
   130			return 0, EINVAL
   131		}
   132		for len(b) > 0 {
   133			m, e := file.pwrite(b, off)
   134			if iserror(e) {
   135				err = &PathError{"write", file.name, Errno(e)}
   136				break
   137			}
   138			n += m
   139			b = b[m:]
   140			off += int64(m)
   141		}
   142		return
   143	}
   144	
   145	// Seek sets the offset for the next Read or Write on file to offset, interpreted
   146	// according to whence: 0 means relative to the origin of the file, 1 means
   147	// relative to the current offset, and 2 means relative to the end.
   148	// It returns the new offset and an Error, if any.
   149	func (file *File) Seek(offset int64, whence int) (ret int64, err Error) {
   150		r, e := file.seek(offset, whence)
   151		if !iserror(e) && file.dirinfo != nil && r != 0 {
   152			e = syscall.EISDIR
   153		}
   154		if iserror(e) {
   155			return 0, &PathError{"seek", file.name, Errno(e)}
   156		}
   157		return r, nil
   158	}
   159	
   160	// WriteString is like Write, but writes the contents of string s rather than
   161	// an array of bytes.
   162	func (file *File) WriteString(s string) (ret int, err Error) {
   163		if file == nil {
   164			return 0, EINVAL
   165		}
   166		return file.Write([]byte(s))
   167	}
   168	
   169	// Mkdir creates a new directory with the specified name and permission bits.
   170	// It returns an error, if any.
   171	func Mkdir(name string, perm uint32) Error {
   172		e := syscall.Mkdir(name, perm)
   173		if iserror(e) {
   174			return &PathError{"mkdir", name, Errno(e)}
   175		}
   176		return nil
   177	}
   178	
   179	// Chdir changes the current working directory to the named directory.
   180	func Chdir(dir string) Error {
   181		if e := syscall.Chdir(dir); iserror(e) {
   182			return &PathError{"chdir", dir, Errno(e)}
   183		}
   184		return nil
   185	}
   186	
   187	// Chdir changes the current working directory to the file,
   188	// which must be a directory.
   189	func (f *File) Chdir() Error {
   190		if e := syscall.Fchdir(f.fd); iserror(e) {
   191			return &PathError{"chdir", f.name, Errno(e)}
   192		}
   193		return nil
   194	}
   195	
   196	// Open opens the named file for reading.  If successful, methods on
   197	// the returned file can be used for reading; the associated file
   198	// descriptor has mode O_RDONLY.
   199	// It returns the File and an Error, if any.
   200	func Open(name string) (file *File, err Error) {
   201		return OpenFile(name, O_RDONLY, 0)
   202	}
   203	
   204	// Create creates the named file mode 0666 (before umask), truncating
   205	// it if it already exists.  If successful, methods on the returned
   206	// File can be used for I/O; the associated file descriptor has mode
   207	// O_RDWR.
   208	// It returns the File and an Error, if any.
   209	func Create(name string) (file *File, err Error) {
   210		return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
   211	}
The Go Programming Language

Source file src/pkg/os/file.go
