os: add documentation for Windows users

Updates #18581
Updates #20858

Change-Id: I6b5ce0e255a42c028d46815fff5a5aca68690fd9
Reviewed-on: https://go-review.googlesource.com/47254
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/os/file.go b/src/os/file.go
index 876bffde6d203c784b4d6a712d61bbe6a3ebba5d..4b4d8fb0367158ab1f3cfa94b9e2e1eb42f0c3c9 100644 (file)
--- a/src/os/file.go
+++ b/src/os/file.go
@@ -292,3 +292,27 @@ func (f *File) wrapErr(op string, err error) error {
 func TempDir() string {
        return tempDir()
 }
+
+// Chmod changes the mode of the named file to mode.
+// If the file is a symbolic link, it changes the mode of the link's target.
+// If there is an error, it will be of type *PathError.
+//
+// A different subset of the mode bits are used, depending on the
+// operating system.
+//
+// On Unix, the mode's permission bits, ModeSetuid, ModeSetgid, and
+// ModeSticky are used.
+//
+// On Windows, the mode must be non-zero but otherwise only the 0200
+// bit (owner writable) of mode is used; it controls whether the
+// file's read-only attribute is set or cleared. attribute. The other
+// bits are currently unused. Use mode 0400 for a read-only file and
+// 0600 for a readable+writable file.
+//
+// On Plan 9, the mode's permission bits, ModeAppend, ModeExclusive,
+// and ModeTemporary are used.
+func Chmod(name string, mode FileMode) error { return chmod(name, mode) }
+
+// Chmod changes the mode of the file to mode.
+// If there is an error, it will be of type *PathError.
+func (f *File) Chmod(mode FileMode) error { return f.chmod(mode) }

diff --git a/src/os/file_plan9.go b/src/os/file_plan9.go
index d0d230ba667d756f853de95cf91b11f9d592617f..0f4a736c2691390f3926d4b90c3d63d282a1a367 100644 (file)
--- a/src/os/file_plan9.go
+++ b/src/os/file_plan9.go
@@ -196,9 +196,7 @@ func (f *File) Truncate(size int64) error {
 
 const chmodMask = uint32(syscall.DMAPPEND | syscall.DMEXCL | syscall.DMTMP | ModePerm)
 
-// Chmod changes the mode of the file to mode.
-// If there is an error, it will be of type *PathError.
-func (f *File) Chmod(mode FileMode) error {
+func (f *File) chmod(mode FileMode) error {
        if f == nil {
                return ErrInvalid
        }
@@ -375,10 +373,8 @@ func rename(oldname, newname string) error {
        return nil
 }
 
-// Chmod changes the mode of the named file to mode.
-// If the file is a symbolic link, it changes the mode of the link's target.
-// If there is an error, it will be of type *PathError.
-func Chmod(name string, mode FileMode) error {
+// See docs in file.go:Chmod.
+func chmod(name string, mode FileMode) error {
        var d syscall.Dir
 
        odir, e := dirstat(name)

diff --git a/src/os/file_posix.go b/src/os/file_posix.go
index 5ac0acdd3631a7ad0feeb4a873c6ac3c5c656d32..f38d43e43fe0d4abfa8ad0818558519e44810a2f 100644 (file)
--- a/src/os/file_posix.go
+++ b/src/os/file_posix.go
@@ -44,19 +44,16 @@ func syscallMode(i FileMode) (o uint32) {
        return
 }
 
-// Chmod changes the mode of the named file to mode.
-// If the file is a symbolic link, it changes the mode of the link's target.
-// If there is an error, it will be of type *PathError.
-func Chmod(name string, mode FileMode) error {
+// See docs in file.go:Chmod.
+func chmod(name string, mode FileMode) error {
        if e := syscall.Chmod(fixLongPath(name), syscallMode(mode)); e != nil {
                return &PathError{"chmod", name, e}
        }
        return nil
 }
 
-// Chmod changes the mode of the file to mode.
-// If there is an error, it will be of type *PathError.
-func (f *File) Chmod(mode FileMode) error {
+// See docs in file.go:(*File).Chmod.
+func (f *File) chmod(mode FileMode) error {
        if err := f.checkValid("chmod"); err != nil {
                return err
        }
@@ -69,6 +66,9 @@ func (f *File) Chmod(mode FileMode) error {
 // Chown changes the numeric uid and gid of the named file.
 // If the file is a symbolic link, it changes the uid and gid of the link's target.
 // If there is an error, it will be of type *PathError.
+//
+// On Windows, it always returns the syscall.EWINDOWS error, wrapped
+// in *PathError.
 func Chown(name string, uid, gid int) error {
        if e := syscall.Chown(name, uid, gid); e != nil {
                return &PathError{"chown", name, e}
@@ -79,6 +79,9 @@ func Chown(name string, uid, gid int) error {
 // Lchown changes the numeric uid and gid of the named file.
 // If the file is a symbolic link, it changes the uid and gid of the link itself.
 // If there is an error, it will be of type *PathError.
+//
+// On Windows, it always returns the syscall.EWINDOWS error, wrapped
+// in *PathError.
 func Lchown(name string, uid, gid int) error {
        if e := syscall.Lchown(name, uid, gid); e != nil {
                return &PathError{"lchown", name, e}
@@ -88,6 +91,9 @@ func Lchown(name string, uid, gid int) error {
 
 // Chown changes the numeric uid and gid of the named file.
 // If there is an error, it will be of type *PathError.
+//
+// On Windows, it always returns the syscall.EWINDOWS error, wrapped
+// in *PathError.
 func (f *File) Chown(uid, gid int) error {
        if err := f.checkValid("chown"); err != nil {
                return err

diff --git a/src/os/proc.go b/src/os/proc.go
index 33a8b26f78d3db7779b23dc2e883f6ef9c094311..804128a1da4bf5ae2932f26bbd36671fa12be098 100644 (file)
--- a/src/os/proc.go
+++ b/src/os/proc.go
@@ -25,18 +25,29 @@ func init() {
 func runtime_args() []string // in package runtime
 
 // Getuid returns the numeric user id of the caller.
+//
+// On Windows, it returns -1.
 func Getuid() int { return syscall.Getuid() }
 
 // Geteuid returns the numeric effective user id of the caller.
+//
+// On Windows, it returns -1.
 func Geteuid() int { return syscall.Geteuid() }
 
 // Getgid returns the numeric group id of the caller.
+//
+// On Windows, it returns -1.
 func Getgid() int { return syscall.Getgid() }
 
 // Getegid returns the numeric effective group id of the caller.
+//
+// On Windows, it returns -1.
 func Getegid() int { return syscall.Getegid() }
 
 // Getgroups returns a list of the numeric ids of groups that the caller belongs to.
+//
+// On Windows, it returns syscall.EWINDOWS. See the os/user package
+// for a possible alternative.
 func Getgroups() ([]int, error) {
        gids, e := syscall.Getgroups()
        return gids, NewSyscallError("getgroups", e)

diff --git a/src/os/types.go b/src/os/types.go
index c56548353f19b6dd1c3bd16930c93a4086d5ed07..db7848759cbd0a2c457c0c3013c4426f6970b1d3 100644 (file)
--- a/src/os/types.go
+++ b/src/os/types.go
@@ -45,7 +45,7 @@ const (
        ModeDir        FileMode = 1 << (32 - 1 - iota) // d: is a directory
        ModeAppend                                     // a: append-only
        ModeExclusive                                  // l: exclusive use
-       ModeTemporary                                  // T: temporary file (not backed up)
+       ModeTemporary                                  // T: temporary file; Plan 9 only
        ModeSymlink                                    // L: symbolic link
        ModeDevice                                     // D: device file
        ModeNamedPipe                                  // p: named pipe (FIFO)