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.
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.
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.
16 // Here is a simple example, opening a file and reading some of it.
18 // file, err := os.Open("file.go") // For read access.
23 // If the open fails, the error string will be self-explanatory, like
25 // open file.go: no such file or directory
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.
30 // data := make([]byte, 100)
31 // count, err := file.Read(data)
35 // fmt.Printf("read %d bytes: %q\n", count, data[:count])
44 // Name returns the name of the file as presented to Open.
45 func (f
*File
) Name() string { return f
.name
}
47 // Stdin, Stdout, and Stderr are open Files pointing to the standard input,
48 // standard output, and standard error file descriptors.
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.
54 Stdin
= NewFile(uintptr(syscall
.Stdin
), "/dev/stdin")
55 Stdout
= NewFile(uintptr(syscall
.Stdout
), "/dev/stdout")
56 Stderr
= NewFile(uintptr(syscall
.Stderr
), "/dev/stderr")
59 // Flags to OpenFile wrapping those of the underlying system. Not all
60 // flags may be implemented on a given system.
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.
72 // Seek whence values.
74 // Deprecated: Use io.SeekStart, io.SeekCurrent, and io.SeekEnd.
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
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 {
90 func (e
*LinkError
) Error() string {
91 return e
.Op
+ " " + e
.Old
+ " " + e
.New
+ ": " + e
.Err
.Error()
94 // Read reads up to len(b) bytes from the File.
95 // It returns the number of bytes read and any error encountered.
96 // At end of file, Read returns 0, io.EOF.
97 func (f
*File
) Read(b
[]byte) (n
int, err error
) {
98 if err
:= f
.checkValid("read"); err
!= nil {
102 if n
== 0 && len(b
) > 0 && e
== nil {
106 err
= &PathError
{"read", f
.name
, e
}
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 err
:= f
.checkValid("read"); err
!= nil {
120 m
, e
:= f
.pread(b
, off
)
121 if m
== 0 && e
== nil {
125 err
= &PathError
{"read", f
.name
, e
}
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 err
:= f
.checkValid("write"); err
!= nil {
147 err
= io
.ErrShortWrite
153 err
= &PathError
{"write", f
.name
, e
}
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 err
:= f
.checkValid("write"); err
!= nil {
166 m
, e
:= f
.pwrite(b
, off
)
168 err
= &PathError
{"write", f
.name
, e
}
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 err
:= f
.checkValid("seek"); err
!= nil {
187 r
, e
:= f
.seek(offset
, whence
)
188 if e
== nil && f
.dirinfo
!= nil && r
!= 0 {
192 return 0, &PathError
{"seek", f
.name
, e
}
197 // WriteString is like Write, but writes the contents of string s rather than
199 func (f
*File
) WriteString(s
string) (n
int, err error
) {
200 return f
.Write([]byte(s
))
203 // Mkdir creates a new directory with the specified name and permission bits.
204 // If there is an error, it will be of type *PathError.
205 func Mkdir(name
string, perm FileMode
) error
{
206 e
:= syscall
.Mkdir(fixLongPath(name
), syscallMode(perm
))
209 return &PathError
{"mkdir", name
, e
}
212 // mkdir(2) itself won't handle the sticky bit on *BSD and Solaris
213 if !supportsCreateWithStickyBit
&& perm
&ModeSticky
!= 0 {
220 // Chdir changes the current working directory to the named directory.
221 // If there is an error, it will be of type *PathError.
222 func Chdir(dir
string) error
{
223 if e
:= syscall
.Chdir(dir
); e
!= nil {
224 return &PathError
{"chdir", dir
, e
}
229 // Chdir changes the current working directory to the file,
230 // which must be a directory.
231 // If there is an error, it will be of type *PathError.
232 func (f
*File
) Chdir() error
{
233 if err
:= f
.checkValid("chdir"); err
!= nil {
236 if e
:= syscall
.Fchdir(f
.fd
); e
!= nil {
237 return &PathError
{"chdir", f
.name
, e
}
242 // Open opens the named file for reading. If successful, methods on
243 // the returned file can be used for reading; the associated file
244 // descriptor has mode O_RDONLY.
245 // If there is an error, it will be of type *PathError.
246 func Open(name
string) (*File
, error
) {
247 return OpenFile(name
, O_RDONLY
, 0)
250 // Create creates the named file with mode 0666 (before umask), truncating
251 // it if it already exists. If successful, methods on the returned
252 // File can be used for I/O; the associated file descriptor has mode
254 // If there is an error, it will be of type *PathError.
255 func Create(name
string) (*File
, error
) {
256 return OpenFile(name
, O_RDWR|O_CREATE|O_TRUNC
, 0666)
259 // lstat is overridden in tests.
262 // Rename renames (moves) oldpath to newpath.
263 // If newpath already exists and is not a directory, Rename replaces it.
264 // OS-specific restrictions may apply when oldpath and newpath are in different directories.
265 // If there is an error, it will be of type *LinkError.
266 func Rename(oldpath
, newpath
string) error
{
267 return rename(oldpath
, newpath
)
270 // Many functions in package syscall return a count of -1 instead of 0.
271 // Using fixCount(call()) instead of call() corrects the count.
272 func fixCount(n
int, err error
) (int, error
) {
279 // checkValid checks whether f is valid for use.
280 // If not, it returns an appropriate error, perhaps incorporating the operation name op.
281 func (f
*File
) checkValid(op
string) error
{
286 return &PathError
{op
, f
.name
, ErrClosed
}