From 92ad8df5d10b08ae73e8104f3202f458616853f1 Mon Sep 17 00:00:00 2001 From: Brad Fitzpatrick Date: Thu, 29 Jun 2017 22:47:29 +0000 Subject: [PATCH] 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 TryBot-Result: Gobot Gobot Reviewed-by: Ian Lance Taylor --- src/os/file.go | 24 ++++++++++++++++++++++++ src/os/file_plan9.go | 10 +++------- src/os/file_posix.go | 20 +++++++++++++------- src/os/proc.go | 11 +++++++++++ src/os/types.go | 2 +- 5 files changed, 52 insertions(+), 15 deletions(-) diff --git a/src/os/file.go b/src/os/file.go index 876bffde6d2..4b4d8fb0367 100644 --- 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 d0d230ba667..0f4a736c269 100644 --- 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 5ac0acdd363..f38d43e43fe 100644 --- 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 33a8b26f78d..804128a1da4 100644 --- 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 c56548353f1..db7848759cb 100644 --- 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)