libgo/go/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 }