document os

R=rsc
DELTA=143  (96 added, 0 deleted, 47 changed)
OCL=25876
CL=25888

1 files changed, 70 insertions, 18 deletions

diff --git a/src/lib/os/file.go b/src/lib/os/file.go
index b41f2418e..1fb2a6409 100644
--- a/src/lib/os/file.go
+++ b/src/lib/os/file.go
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// The os package provides a platform-independent interface to operating
+// system functionality.  The design is Unix-like.
 package os
 
 import (
@@ -16,21 +18,25 @@ type dirInfo struct {	// TODO(r): 6g bug means this can't be private
 	bufp	int64;	// location of next record in buf.
 }
 
-// FDs are wrappers for file descriptors
+// FD represents an open file.
+// TODO(r): is FD the right name? Would File be better?
 type FD struct {
 	fd int64;
 	name	string;
 	dirinfo	*dirInfo;	// nil unless directory being read
 }
 
+// Fd returns the integer Unix file descriptor referencing the open file.
 func (fd *FD) Fd() int64 {
 	return fd.fd
 }
 
+// Name returns the name of the file as presented to Open.
 func (fd *FD) Name() string {
 	return fd.name
 }
 
+// NewFD returns a new FD with the given file descriptor and name.
 func NewFD(fd int64, name string) *FD {
 	if fd < 0 {
 		return nil
@@ -38,28 +44,35 @@ func NewFD(fd int64, name string) *FD {
 	return &FD{fd, name, nil}
 }
 
+// Stdin, Stdout, and Stderr are open FDs pointing to the standard input,
+// standard output, and standard error file descriptors.
 var (
 	Stdin = NewFD(0, "/dev/stdin");
 	Stdout = NewFD(1, "/dev/stdout");
 	Stderr = NewFD(2, "/dev/stderr");
 )
 
+// Flags to Open wrapping those of the underlying system. Not all flags
+// may be implemented on a given system.
 const (
-	O_RDONLY = syscall.O_RDONLY;
-	O_WRONLY = syscall.O_WRONLY;
-	O_RDWR = syscall.O_RDWR;
-	O_APPEND = syscall.O_APPEND;
-	O_ASYNC = syscall.O_ASYNC;
-	O_CREAT = syscall.O_CREAT;
-	O_NOCTTY = syscall.O_NOCTTY;
-	O_NONBLOCK = syscall.O_NONBLOCK;
-	O_NDELAY = O_NONBLOCK;
-	O_SYNC = syscall.O_SYNC;
-	O_TRUNC = syscall.O_TRUNC;
+	O_RDONLY = syscall.O_RDONLY;	// open the file read-only.
+	O_WRONLY = syscall.O_WRONLY;	// open the file write-only.
+	O_RDWR = syscall.O_RDWR;	// open the file read-write.
+	O_APPEND = syscall.O_APPEND;	// open the file append-only.
+	O_ASYNC = syscall.O_ASYNC;	// generate a signal when I/O is available.
+	O_CREAT = syscall.O_CREAT;	// create a new file if none exists.
+	O_NOCTTY = syscall.O_NOCTTY;	// do not make file the controlling tty.
+	O_NONBLOCK = syscall.O_NONBLOCK;	// open in non-blocking mode.
+	O_NDELAY = O_NONBLOCK;		// synonym for O_NONBLOCK
+	O_SYNC = syscall.O_SYNC;	// open for synchronous I/O.
+	O_TRUNC = syscall.O_TRUNC;	// if possible, truncate file when opened.
 )
 
-func Open(name string, mode int, flags int) (fd *FD, err *Error) {
-	r, e := syscall.Open(name, int64(mode), int64(flags | syscall.O_CLOEXEC));
+// Open opens the named file with specified flag (O_RDONLY etc.) and perm, (0666 etc.)
+// if applicable.  If successful, methods on the returned FD can be used for I/O.
+// It returns the FD and an Error, if any.
+func Open(name string, flag int, perm int) (fd *FD, err *Error) {
+	r, e := syscall.Open(name, int64(flag | syscall.O_CLOEXEC), int64(perm));
 	if e != 0 {
 		return nil, ErrnoToError(e);
 	}
@@ -73,6 +86,8 @@ func Open(name string, mode int, flags int) (fd *FD, err *Error) {
 	return NewFD(r, name), ErrnoToError(e)
 }
 
+// Close closes the FD, rendering it unusable for I/O.
+// It returns an Error, if any.
 func (fd *FD) Close() *Error {
 	if fd == nil {
 		return EINVAL
@@ -82,6 +97,10 @@ func (fd *FD) Close() *Error {
 	return ErrnoToError(e)
 }
 
+// Read reads up to len(b) bytes from the FD.
+// It returns the number of bytes read and an Error, if any.
+// EOF is signaled by a zero count with a nil Error.
+// TODO(r): Add Pread, Pwrite (maybe ReadAt, WriteAt).
 func (fd *FD) Read(b []byte) (ret int, err *Error) {
 	if fd == nil {
 		return 0, EINVAL
@@ -96,6 +115,9 @@ func (fd *FD) Read(b []byte) (ret int, err *Error) {
 	return int(r), ErrnoToError(e)
 }
 
+// Write writes len(b) bytes to the FD.
+// It returns the number of bytes written and an Error, if any.
+// If the byte count differs from len(b), it usually implies an error occurred.
 func (fd *FD) Write(b []byte) (ret int, err *Error) {
 	if fd == nil {
 		return 0, EINVAL
@@ -110,6 +132,10 @@ func (fd *FD) Write(b []byte) (ret int, err *Error) {
 	return int(r), ErrnoToError(e)
 }
 
+// Seek sets the offset for the next Read or Write on FD to offset, interpreted
+// according to whence: 0 means relative to the origin of the file, 1 means
+// relative to the current offset, and 2 means relative to the end.
+// It returns the new offset and an Error, if any.
 func (fd *FD) Seek(offset int64, whence int) (ret int64, err *Error) {
 	r, e := syscall.Seek(fd.fd, offset, int64(whence));
 	if e != 0 {
@@ -121,6 +147,8 @@ func (fd *FD) Seek(offset int64, whence int) (ret int64, err *Error) {
 	return r, nil
 }
 
+// WriteString is like Write, but writes the contents of string s rather than
+// an array of bytes.
 func (fd *FD) WriteString(s string) (ret int, err *Error) {
 	if fd == nil {
 		return 0, EINVAL
@@ -132,12 +160,14 @@ func (fd *FD) WriteString(s string) (ret int, err *Error) {
 	return int(r), ErrnoToError(e)
 }
 
-func Pipe() (fd1 *FD, fd2 *FD, err *Error) {
+// Pipe returns a connected pair of FDs; reads from r return bytes written to w.
+// It returns the FDs and an Error, if any.
+func Pipe() (r *FD, w *FD, err *Error) {
 	var p [2]int64;
 
 	// See ../syscall/exec.go for description of lock.
 	syscall.ForkLock.RLock();
-	r, e := syscall.Pipe(&p);
+	ret, e := syscall.Pipe(&p);
 	if e != 0 {
 		syscall.ForkLock.RUnlock();
 		return nil, nil, ErrnoToError(e)
@@ -149,11 +179,17 @@ func Pipe() (fd1 *FD, fd2 *FD, err *Error) {
 	return NewFD(p[0], "|0"), NewFD(p[1], "|1"), nil
 }
 
+// Mkdir creates a new directory with the specified name and permission bits.
+// It returns an error, if any.
 func Mkdir(name string, perm int) *Error {
 	r, e := syscall.Mkdir(name, int64(perm));
 	return ErrnoToError(e)
 }
 
+// Stat returns the Dir structure describing the named file. If the file
+// is a symbolic link, it returns information about the file the link
+// references.
+// It returns the Dir and an error, if any.
 func Stat(name string) (dir *Dir, err *Error) {
 	stat := new(syscall.Stat_t);
 	r, e := syscall.Stat(name, stat);
@@ -163,6 +199,8 @@ func Stat(name string) (dir *Dir, err *Error) {
 	return dirFromStat(name, new(Dir), stat), nil
 }
 
+// Fstat returns the Dir structure describing the file associated with the FD.
+// It returns the Dir and an error, if any.
 func Fstat(fd *FD) (dir *Dir, err *Error) {
 	stat := new(syscall.Stat_t);
 	r, e := syscall.Fstat(fd.fd, stat);
@@ -172,6 +210,9 @@ func Fstat(fd *FD) (dir *Dir, err *Error) {
 	return dirFromStat(fd.name, new(Dir), stat), nil
 }
 
+// Lstat returns the Dir structure describing the named file. If the file
+// is a symbolic link, it returns information about the link itself.
+// It returns the Dir and an error, if any.
 func Lstat(name string) (dir *Dir, err *Error) {
 	stat := new(syscall.Stat_t);
 	r, e := syscall.Lstat(name, stat);
@@ -181,10 +222,21 @@ func Lstat(name string) (dir *Dir, err *Error) {
 	return dirFromStat(name, new(Dir), stat), nil
 }
 
-// Non-portable function defined in operating-system-dependent file.
+// Readdirnames has a non-portable implemenation so its code is separated into an
+// operating-system-dependent file.
+
+// Readdirnames reads the contents of the directory associated with fd and
+// returns an array of up to count names, in directory order.  Subsequent
+// calls on the same fd will yield further names.
+// A negative count means to read until EOF.
+// It returns the array and an Error, if any.
 func Readdirnames(fd *FD, count int) (names []string, err *os.Error)
 
-// Negative count means read until EOF.
+// Readdir reads the contents of the directory associated with fd and
+// returns an array of up to count Dir structures, in directory order.  Subsequent
+// calls on the same fd will yield further Dirs.
+// A negative count means to read until EOF.
+// It returns the array and an Error, if any.
 func Readdir(fd *FD, count int) (dirs []Dir, err *os.Error) {
 	dirname := fd.name;
 	if dirname == "" {