mirror
/
go
mirror of https://github.com/golang/go.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

os: more godoc links 

Add missing links to *PathError.

Also a few links to O_ flags and Mode and syscall constants.

Change-Id: Ic6ec5780a44942050a83ed07dbf16d6fa9f83eb9
Reviewed-on: https://go-review.googlesource.com/c/go/+/655375
Reviewed-by: Junyang Shao <shaojunyang@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
This commit is contained in:
Olivier Mengué 2025-03-06 13:23:52 +01:00 committed by Gopher Robot
parent 66b7640354
commit 938b6c15e9
6 changed files with 36 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
src/os/file.go
View File

@ -216,7 +216,7 @@ var errWriteAtInAppendMode = errors.New("os: invalid use of WriteAt on file open
// It returns the number of bytes written and an error, if any. // It returns the number of bytes written and an error, if any.
// WriteAt returns a non-nil error when n != len(b). // WriteAt returns a non-nil error when n != len(b).
// //
// If file was opened with the O_APPEND flag, WriteAt returns an error. // If file was opened with the [O_APPEND] flag, WriteAt returns an error.
func (f *File) WriteAt(b []byte, off int64) (n int, err error) { func (f *File) WriteAt(b []byte, off int64) (n int, err error) {
if err := f.checkValid("write"); err != nil { if err := f.checkValid("write"); err != nil {
return 0, err return 0, err
@ -280,7 +280,7 @@ func genericWriteTo(f *File, w io.Writer) (int64, error) {
// according to whence: 0 means relative to the origin of the file, 1 means // 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. // relative to the current offset, and 2 means relative to the end.
// It returns the new offset and an error, if any. // It returns the new offset and an error, if any.
// The behavior of Seek on a file opened with O_APPEND is not specified. // The behavior of Seek on a file opened with [O_APPEND] is not specified.
func (f *File) Seek(offset int64, whence int) (ret int64, err error) { func (f *File) Seek(offset int64, whence int) (ret int64, err error) {
if err := f.checkValid("seek"); err != nil { if err := f.checkValid("seek"); err != nil {
return 0, err return 0, err
@ -304,7 +304,7 @@ func (f *File) WriteString(s string) (n int, err error) {
// Mkdir creates a new directory with the specified name and permission // Mkdir creates a new directory with the specified name and permission
// bits (before umask). // bits (before umask).
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Mkdir(name string, perm FileMode) error { func Mkdir(name string, perm FileMode) error {
longName := fixLongPath(name) longName := fixLongPath(name)
e := ignoringEINTR(func() error { e := ignoringEINTR(func() error {
@ -338,7 +338,7 @@ func setStickyBit(name string) error {
} }
// Chdir changes the current working directory to the named directory. // Chdir changes the current working directory to the named directory.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Chdir(dir string) error { func Chdir(dir string) error {
if e := syscall.Chdir(dir); e != nil { if e := syscall.Chdir(dir); e != nil {
testlog.Open(dir) // observe likely non-existent directory testlog.Open(dir) // observe likely non-existent directory
@ -365,8 +365,8 @@ func Chdir(dir string) error {
// Open opens the named file for reading. If successful, methods on // Open opens the named file for reading. If successful, methods on
// the returned file can be used for reading; the associated file // the returned file can be used for reading; the associated file
// descriptor has mode O_RDONLY. // descriptor has mode [O_RDONLY].
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Open(name string) (*File, error) { func Open(name string) (*File, error) {
return OpenFile(name, O_RDONLY, 0) return OpenFile(name, O_RDONLY, 0)
} }
@ -374,20 +374,20 @@ func Open(name string) (*File, error) {
// Create creates or truncates the named file. If the file already exists, // Create creates or truncates the named file. If the file already exists,
// it is truncated. If the file does not exist, it is created with mode 0o666 // it is truncated. If the file does not exist, it is created with mode 0o666
// (before umask). If successful, methods on the returned File can // (before umask). If successful, methods on the returned File can
// be used for I/O; the associated file descriptor has mode O_RDWR. // be used for I/O; the associated file descriptor has mode [O_RDWR].
// The directory containing the file must already exist. // The directory containing the file must already exist.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Create(name string) (*File, error) { func Create(name string) (*File, error) {
return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666) return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
} }
// OpenFile is the generalized open call; most users will use Open // OpenFile is the generalized open call; most users will use Open
// or Create instead. It opens the named file with specified flag // or Create instead. It opens the named file with specified flag
// (O_RDONLY etc.). If the file does not exist, and the O_CREATE flag // ([O_RDONLY] etc.). If the file does not exist, and the [O_CREATE] flag
// is passed, it is created with mode perm (before umask); // is passed, it is created with mode perm (before umask);
// the containing directory must exist. If successful, // the containing directory must exist. If successful,
// methods on the returned File can be used for I/O. // methods on the returned File can be used for I/O.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func OpenFile(name string, flag int, perm FileMode) (*File, error) { func OpenFile(name string, flag int, perm FileMode) (*File, error) {
testlog.Open(name) testlog.Open(name)
f, err := openFileNolog(name, flag, perm) f, err := openFileNolog(name, flag, perm)
@ -423,7 +423,7 @@ func Rename(oldpath, newpath string) error {
} }
// Readlink returns the destination of the named symbolic link. // Readlink returns the destination of the named symbolic link.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
// //
// If the link destination is relative, Readlink returns the relative path // If the link destination is relative, Readlink returns the relative path
// without resolving it to an absolute one. // without resolving it to an absolute one.
@ -609,13 +609,13 @@ func UserHomeDir() (string, error) {
// Chmod changes the mode of the named file to mode. // 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 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. // If there is an error, it will be of type [*PathError].
// //
// A different subset of the mode bits are used, depending on the // A different subset of the mode bits are used, depending on the
// operating system. // operating system.
// //
// On Unix, the mode's permission bits, ModeSetuid, ModeSetgid, and // On Unix, the mode's permission bits, [ModeSetuid], [ModeSetgid], and
// ModeSticky are used. // [ModeSticky] are used.
// //
// On Windows, only the 0o200 bit (owner writable) of mode is used; it // On Windows, only the 0o200 bit (owner writable) of mode is used; it
// controls whether the file's read-only attribute is set or cleared. // controls whether the file's read-only attribute is set or cleared.
@ -623,12 +623,12 @@ func UserHomeDir() (string, error) {
// and earlier, use a non-zero mode. Use mode 0o400 for a read-only // and earlier, use a non-zero mode. Use mode 0o400 for a read-only
// file and 0o600 for a readable+writable file. // file and 0o600 for a readable+writable file.
// //
// On Plan 9, the mode's permission bits, ModeAppend, ModeExclusive, // On Plan 9, the mode's permission bits, [ModeAppend], [ModeExclusive],
// and ModeTemporary are used. // and [ModeTemporary] are used.
func Chmod(name string, mode FileMode) error { return chmod(name, mode) } func Chmod(name string, mode FileMode) error { return chmod(name, mode) }
// Chmod changes the mode of the file to mode. // Chmod changes the mode of the file to mode.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func (f *File) Chmod(mode FileMode) error { return f.chmod(mode) } func (f *File) Chmod(mode FileMode) error { return f.chmod(mode) }
// SetDeadline sets the read and write deadlines for a File. // SetDeadline sets the read and write deadlines for a File.

22
src/os/file_plan9.go
View File

@ -180,7 +180,7 @@ func (file *file) destroy() error {
} }
// Stat returns the FileInfo structure describing file. // Stat returns the FileInfo structure describing file.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func (f *File) Stat() (FileInfo, error) { func (f *File) Stat() (FileInfo, error) {
if f == nil { if f == nil {
return nil, ErrInvalid return nil, ErrInvalid
@ -194,7 +194,7 @@ func (f *File) Stat() (FileInfo, error) {
// Truncate changes the size of the file. // Truncate changes the size of the file.
// It does not change the I/O offset. // It does not change the I/O offset.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func (f *File) Truncate(size int64) error { func (f *File) Truncate(size int64) error {
if f == nil { if f == nil {
return ErrInvalid return ErrInvalid
@ -356,7 +356,7 @@ func (f *File) seek(offset int64, whence int) (ret int64, err error) {
// Truncate changes the size of the named file. // Truncate changes the size of the named file.
// If the file is a symbolic link, it changes the size of the link's target. // If the file is a symbolic link, it changes the size of the link's target.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Truncate(name string, size int64) error { func Truncate(name string, size int64) error {
var d syscall.Dir var d syscall.Dir
@ -375,7 +375,7 @@ func Truncate(name string, size int64) error {
} }
// Remove removes the named file or directory. // Remove removes the named file or directory.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Remove(name string) error { func Remove(name string) error {
if e := syscall.Remove(name); e != nil { if e := syscall.Remove(name); e != nil {
return &PathError{Op: "remove", Path: name, Err: e} return &PathError{Op: "remove", Path: name, Err: e}
@ -448,7 +448,7 @@ func chmod(name string, mode FileMode) error {
// //
// The underlying filesystem may truncate or round the values to a // The underlying filesystem may truncate or round the values to a
// less precise time unit. // less precise time unit.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Chtimes(name string, atime time.Time, mtime time.Time) error { func Chtimes(name string, atime time.Time, mtime time.Time) error {
var d syscall.Dir var d syscall.Dir
@ -508,23 +508,23 @@ func readlink(name string) (string, error) {
// Chown changes the numeric uid and gid of the named file. // 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 the file is a symbolic link, it changes the uid and gid of the link's target.
// A uid or gid of -1 means to not change that value. // A uid or gid of -1 means to not change that value.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
// //
// On Windows or Plan 9, Chown always returns the syscall.EWINDOWS or // On Windows or Plan 9, Chown always returns the [syscall.EWINDOWS] or
// EPLAN9 error, wrapped in *PathError. // [syscall.EPLAN9] error, wrapped in [*PathError].
func Chown(name string, uid, gid int) error { func Chown(name string, uid, gid int) error {
return &PathError{Op: "chown", Path: name, Err: syscall.EPLAN9} return &PathError{Op: "chown", Path: name, Err: syscall.EPLAN9}
} }
// Lchown changes the numeric uid and gid of the named file. // 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 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. // If there is an error, it will be of type [*PathError].
func Lchown(name string, uid, gid int) error { func Lchown(name string, uid, gid int) error {
return &PathError{Op: "lchown", Path: name, Err: syscall.EPLAN9} return &PathError{Op: "lchown", Path: name, Err: syscall.EPLAN9}
} }
// Chown changes the numeric uid and gid of the named file. // Chown changes the numeric uid and gid of the named file.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func (f *File) Chown(uid, gid int) error { func (f *File) Chown(uid, gid int) error {
if f == nil { if f == nil {
return ErrInvalid return ErrInvalid
@ -542,7 +542,7 @@ func tempDir() string {
// Chdir changes the current working directory to the file, // Chdir changes the current working directory to the file,
// which must be a directory. // which must be a directory.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func (f *File) Chdir() error { func (f *File) Chdir() error {
if err := f.incref("chdir"); err != nil { if err := f.incref("chdir"); err != nil {
return err return err

6
src/os/file_posix.go
View File

@ -101,7 +101,7 @@ func (f *File) chmod(mode FileMode) error {
// If there is an error, it will be of type [*PathError]. // If there is an error, it will be of type [*PathError].
// //
// On Windows or Plan 9, Chown always returns the [syscall.EWINDOWS] or // On Windows or Plan 9, Chown always returns the [syscall.EWINDOWS] or
// EPLAN9 error, wrapped in *PathError. // [syscall.EPLAN9] error, wrapped in [*PathError].
func Chown(name string, uid, gid int) error { func Chown(name string, uid, gid int) error {
e := ignoringEINTR(func() error { e := ignoringEINTR(func() error {
return syscall.Chown(name, uid, gid) return syscall.Chown(name, uid, gid)
@ -117,7 +117,7 @@ func Chown(name string, uid, gid int) error {
// If there is an error, it will be of type [*PathError]. // If there is an error, it will be of type [*PathError].
// //
// On Windows, it always returns the [syscall.EWINDOWS] error, wrapped // On Windows, it always returns the [syscall.EWINDOWS] error, wrapped
// in *PathError. // in [*PathError].
func Lchown(name string, uid, gid int) error { func Lchown(name string, uid, gid int) error {
e := ignoringEINTR(func() error { e := ignoringEINTR(func() error {
return syscall.Lchown(name, uid, gid) return syscall.Lchown(name, uid, gid)
@ -132,7 +132,7 @@ func Lchown(name string, uid, gid int) error {
// If there is an error, it will be of type [*PathError]. // If there is an error, it will be of type [*PathError].
// //
// On Windows, it always returns the [syscall.EWINDOWS] error, wrapped // On Windows, it always returns the [syscall.EWINDOWS] error, wrapped
// in *PathError. // in [*PathError].
func (f *File) Chown(uid, gid int) error { func (f *File) Chown(uid, gid int) error {
if err := f.checkValid("chown"); err != nil { if err := f.checkValid("chown"); err != nil {
return err return err

4
src/os/file_unix.go
View File

@ -351,7 +351,7 @@ func (f *File) seek(offset int64, whence int) (ret int64, err error) {
// Truncate changes the size of the named file. // Truncate changes the size of the named file.
// If the file is a symbolic link, it changes the size of the link's target. // If the file is a symbolic link, it changes the size of the link's target.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Truncate(name string, size int64) error { func Truncate(name string, size int64) error {
e := ignoringEINTR(func() error { e := ignoringEINTR(func() error {
return syscall.Truncate(name, size) return syscall.Truncate(name, size)
@ -363,7 +363,7 @@ func Truncate(name string, size int64) error {
} }
// Remove removes the named file or (empty) directory. // Remove removes the named file or (empty) directory.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Remove(name string) error { func Remove(name string) error {
// System call interface forces us to know // System call interface forces us to know
// whether name is a file or directory. // whether name is a file or directory.

2
src/os/file_windows.go
View File

@ -164,7 +164,7 @@ func Truncate(name string, size int64) error {
} }
// Remove removes the named file or directory. // Remove removes the named file or directory.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func Remove(name string) error { func Remove(name string) error {
p, e := syscall.UTF16PtrFromString(fixLongPath(name)) p, e := syscall.UTF16PtrFromString(fixLongPath(name))
if e != nil { if e != nil {

4
src/os/root.go
View File

@ -77,7 +77,7 @@ const (
// OpenRoot opens the named directory. // OpenRoot opens the named directory.
// It follows symbolic links in the directory name. // It follows symbolic links in the directory name.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func OpenRoot(name string) (*Root, error) { func OpenRoot(name string) (*Root, error) {
testlog.Open(name) testlog.Open(name)
return openRootNolog(name) return openRootNolog(name)
@ -127,7 +127,7 @@ func (r *Root) OpenFile(name string, flag int, perm FileMode) (*File, error) {
} }
// OpenRoot opens the named directory in the root. // OpenRoot opens the named directory in the root.
// If there is an error, it will be of type *PathError. // If there is an error, it will be of type [*PathError].
func (r *Root) OpenRoot(name string) (*Root, error) { func (r *Root) OpenRoot(name string) (*Root, error) {
r.logOpen(name) r.logOpen(name)
return openRootInRoot(r, name) return openRootInRoot(r, name)