github.com/euank/go@v0.0.0-20160829210321-495514729181/src/os/file.go (about) 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 }