From 938b6c15e92e6a80b8368798a350a1a811487d88 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Olivier=20Mengu=C3=A9?= Date: Thu, 6 Mar 2025 13:23:52 +0100 Subject: [PATCH] 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 LUCI-TryBot-Result: Go LUCI Reviewed-by: Ian Lance Taylor Auto-Submit: Ian Lance Taylor --- src/os/file.go | 34 +++++++++++++++++----------------- src/os/file_plan9.go | 22 +++++++++++----------- src/os/file_posix.go | 6 +++--- src/os/file_unix.go | 4 ++-- src/os/file_windows.go | 2 +- src/os/root.go | 4 ++-- 6 files changed, 36 insertions(+), 36 deletions(-) diff --git a/src/os/file.go b/src/os/file.go index 1aeb0d2864..36c8e202d6 100644 --- a/src/os/file.go +++ b/src/os/file.go @@ -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. // 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) { if err := f.checkValid("write"); err != nil { 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 // relative to the current offset, and 2 means relative to the end. // 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) { if err := f.checkValid("seek"); err != nil { 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 // 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 { longName := fixLongPath(name) e := ignoringEINTR(func() error { @@ -338,7 +338,7 @@ func setStickyBit(name string) error { } // 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 { if e := syscall.Chdir(dir); e != nil { 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 // the returned file can be used for reading; the associated file -// descriptor has mode O_RDONLY. -// If there is an error, it will be of type *PathError. +// descriptor has mode [O_RDONLY]. +// If there is an error, it will be of type [*PathError]. func Open(name string) (*File, error) { 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, // 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 -// 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. -// 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) { return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666) } // OpenFile is the generalized open call; most users will use Open // 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); // the containing directory must exist. If successful, // 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) { testlog.Open(name) 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. -// 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 // 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. // 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 // operating system. // -// On Unix, the mode's permission bits, ModeSetuid, ModeSetgid, and -// ModeSticky are used. +// On Unix, the mode's permission bits, [ModeSetuid], [ModeSetgid], and +// [ModeSticky] are used. // // 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. @@ -623,12 +623,12 @@ func UserHomeDir() (string, error) { // and earlier, use a non-zero mode. Use mode 0o400 for a read-only // file and 0o600 for a readable+writable file. // -// On Plan 9, the mode's permission bits, ModeAppend, ModeExclusive, -// and ModeTemporary are used. +// 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. +// If there is an error, it will be of type [*PathError]. func (f *File) Chmod(mode FileMode) error { return f.chmod(mode) } // SetDeadline sets the read and write deadlines for a File. diff --git a/src/os/file_plan9.go b/src/os/file_plan9.go index 73df3b086d..448dd3993c 100644 --- a/src/os/file_plan9.go +++ b/src/os/file_plan9.go @@ -180,7 +180,7 @@ func (file *file) destroy() error { } // 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) { if f == nil { return nil, ErrInvalid @@ -194,7 +194,7 @@ func (f *File) Stat() (FileInfo, error) { // Truncate changes the size of the file. // 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 { if f == nil { 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. // 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 { var d syscall.Dir @@ -375,7 +375,7 @@ func Truncate(name string, size int64) error { } // 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 { if e := syscall.Remove(name); e != nil { 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 // 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 { 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. // 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. -// 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 -// EPLAN9 error, wrapped in *PathError. +// On Windows or Plan 9, Chown always returns the [syscall.EWINDOWS] or +// [syscall.EPLAN9] error, wrapped in [*PathError]. func Chown(name string, uid, gid int) error { return &PathError{Op: "chown", Path: name, Err: syscall.EPLAN9} } // 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. +// If there is an error, it will be of type [*PathError]. func Lchown(name string, uid, gid int) error { return &PathError{Op: "lchown", Path: name, Err: syscall.EPLAN9} } // 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 { if f == nil { return ErrInvalid @@ -542,7 +542,7 @@ func tempDir() string { // Chdir changes the current working directory to the file, // 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 { if err := f.incref("chdir"); err != nil { return err diff --git a/src/os/file_posix.go b/src/os/file_posix.go index f0cdfdae5c..8b06227d42 100644 --- a/src/os/file_posix.go +++ b/src/os/file_posix.go @@ -101,7 +101,7 @@ func (f *File) chmod(mode FileMode) error { // If there is an error, it will be of type [*PathError]. // // 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 { e := ignoringEINTR(func() error { 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]. // // On Windows, it always returns the [syscall.EWINDOWS] error, wrapped -// in *PathError. +// in [*PathError]. func Lchown(name string, uid, gid int) error { e := ignoringEINTR(func() error { 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]. // // On Windows, it always returns the [syscall.EWINDOWS] error, wrapped -// in *PathError. +// in [*PathError]. func (f *File) Chown(uid, gid int) error { if err := f.checkValid("chown"); err != nil { return err diff --git a/src/os/file_unix.go b/src/os/file_unix.go index bb99b5279d..6ddeae3bd3 100644 --- a/src/os/file_unix.go +++ b/src/os/file_unix.go @@ -351,7 +351,7 @@ func (f *File) seek(offset int64, whence int) (ret int64, err error) { // 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 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 { e := ignoringEINTR(func() error { return syscall.Truncate(name, size) @@ -363,7 +363,7 @@ func Truncate(name string, size int64) error { } // 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 { // System call interface forces us to know // whether name is a file or directory. diff --git a/src/os/file_windows.go b/src/os/file_windows.go index 07984be5c4..d55790f208 100644 --- a/src/os/file_windows.go +++ b/src/os/file_windows.go @@ -164,7 +164,7 @@ func Truncate(name string, size int64) error { } // 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 { p, e := syscall.UTF16PtrFromString(fixLongPath(name)) if e != nil { diff --git a/src/os/root.go b/src/os/root.go index 0d2c79640d..2edf5c27f2 100644 --- a/src/os/root.go +++ b/src/os/root.go @@ -77,7 +77,7 @@ const ( // OpenRoot opens the named directory. // 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) { testlog.Open(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. -// 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) { r.logOpen(name) return openRootInRoot(r, name) -- 2.51.0