syscall: add available godoc link

Change-Id: I0fcb79f471cdb8b464924d9b04c675f120861f67
Reviewed-on: https://go-review.googlesource.com/c/go/+/539835
Reviewed-by: Ian Lance Taylor <[email protected]>
Run-TryBot: shuang cui <[email protected]>
Auto-Submit: Ian Lance Taylor <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
Reviewed-by: Carlos Amedee <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

src/syscall/dir_plan9.go

@@ -54,12 +54,12 @@ var nullDir = Dir{
 }
 
 // Null assigns special "don't touch" values to members of d to
-// avoid modifying them during syscall.Wstat.
+// avoid modifying them during [Wstat].
 func (d *Dir) Null() { *d = nullDir }
 
 // Marshal encodes a 9P stat message corresponding to d into b
 //
-// If there isn't enough space in b for a stat message, ErrShortStat is returned.
+// If there isn't enough space in b for a stat message, [ErrShortStat] is returned.
 func (d *Dir) Marshal(b []byte) (n int, err error) {
 	n = STATFIXLEN + len(d.Name) + len(d.Uid) + len(d.Gid) + len(d.Muid)
 	if n > len(b) {
@@ -92,9 +92,9 @@ func (d *Dir) Marshal(b []byte) (n int, err error) {
 
 // UnmarshalDir decodes a single 9P stat message from b and returns the resulting Dir.
 //
-// If b is too small to hold a valid stat message, ErrShortStat is returned.
+// If b is too small to hold a valid stat message, [ErrShortStat] is returned.
 //
-// If the stat message itself is invalid, ErrBadStat is returned.
+// If the stat message itself is invalid, [ErrBadStat] is returned.
 func UnmarshalDir(b []byte) (*Dir, error) {
 	if len(b) < STATFIXLEN {
 		return nil, ErrShortStat

src/syscall/dll_windows.go

@@ -24,22 +24,22 @@ func (e *DLLError) Unwrap() error { return e.Err }
 
 // Implemented in ../runtime/syscall_windows.go.
 
-// Deprecated: Use SyscallN instead.
+// Deprecated: Use [SyscallN] instead.
 func Syscall(trap, nargs, a1, a2, a3 uintptr) (r1, r2 uintptr, err Errno)
 
-// Deprecated: Use SyscallN instead.
+// Deprecated: Use [SyscallN] instead.
 func Syscall6(trap, nargs, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2 uintptr, err Errno)
 
-// Deprecated: Use SyscallN instead.
+// Deprecated: Use [SyscallN] instead.
 func Syscall9(trap, nargs, a1, a2, a3, a4, a5, a6, a7, a8, a9 uintptr) (r1, r2 uintptr, err Errno)
 
-// Deprecated: Use SyscallN instead.
+// Deprecated: Use [SyscallN] instead.
 func Syscall12(trap, nargs, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12 uintptr) (r1, r2 uintptr, err Errno)
 
-// Deprecated: Use SyscallN instead.
+// Deprecated: Use [SyscallN] instead.
 func Syscall15(trap, nargs, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15 uintptr) (r1, r2 uintptr, err Errno)
 
-// Deprecated: Use SyscallN instead.
+// Deprecated: Use [SyscallN] instead.
 func Syscall18(trap, nargs, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15, a16, a17, a18 uintptr) (r1, r2 uintptr, err Errno)
 
 func SyscallN(trap uintptr, args ...uintptr) (r1, r2 uintptr, err Errno)
@@ -59,7 +59,7 @@ type DLL struct {
 // Go, Windows will search for the named DLL in many locations, causing
 // potential DLL preloading attacks.
 //
-// Use LazyDLL in golang.org/x/sys/windows for a secure way to
+// Use [LazyDLL] in golang.org/x/sys/windows for a secure way to
 // load system DLLs.
 func LoadDLL(name string) (*DLL, error) {
 	namep, err := UTF16PtrFromString(name)
@@ -87,7 +87,7 @@ func LoadDLL(name string) (*DLL, error) {
 	return d, nil
 }
 
-// MustLoadDLL is like LoadDLL but panics if load operation fails.
+// MustLoadDLL is like [LoadDLL] but panics if load operation fails.
 func MustLoadDLL(name string) *DLL {
 	d, e := LoadDLL(name)
 	if e != nil {
@@ -96,7 +96,7 @@ func MustLoadDLL(name string) *DLL {
 	return d
 }
 
-// FindProc searches DLL d for procedure named name and returns *Proc
+// FindProc searches [DLL] d for procedure named name and returns [*Proc]
 // if found. It returns an error if search fails.
 func (d *DLL) FindProc(name string) (proc *Proc, err error) {
 	namep, err := BytePtrFromString(name)
@@ -119,7 +119,7 @@ func (d *DLL) FindProc(name string) (proc *Proc, err error) {
 	return p, nil
 }
 
-// MustFindProc is like FindProc but panics if search fails.
+// MustFindProc is like [DLL.FindProc] but panics if search fails.
 func (d *DLL) MustFindProc(name string) *Proc {
 	p, e := d.FindProc(name)
 	if e != nil {
@@ -128,12 +128,12 @@ func (d *DLL) MustFindProc(name string) *Proc {
 	return p
 }
 
-// Release unloads DLL d from memory.
+// Release unloads [DLL] d from memory.
 func (d *DLL) Release() (err error) {
 	return FreeLibrary(d.Handle)
 }
 
-// A Proc implements access to a procedure inside a DLL.
+// A Proc implements access to a procedure inside a [DLL].
 type Proc struct {
 	Dll  *DLL
 	Name string
@@ -151,28 +151,28 @@ func (p *Proc) Addr() uintptr {
 // The returned error is always non-nil, constructed from the result of GetLastError.
 // Callers must inspect the primary return value to decide whether an error occurred
 // (according to the semantics of the specific function being called) before consulting
-// the error. The error always has type syscall.Errno.
+// the error. The error always has type [Errno].
 //
 // On amd64, Call can pass and return floating-point values. To pass
 // an argument x with C type "float", use
 // uintptr(math.Float32bits(x)). To pass an argument with C type
 // "double", use uintptr(math.Float64bits(x)). Floating-point return
 // values are returned in r2. The return value for C type "float" is
-// math.Float32frombits(uint32(r2)). For C type "double", it is
-// math.Float64frombits(uint64(r2)).
+// [math.Float32frombits](uint32(r2)). For C type "double", it is
+// [math.Float64frombits](uint64(r2)).
 //
 //go:uintptrescapes
 func (p *Proc) Call(a ...uintptr) (uintptr, uintptr, error) {
 	return SyscallN(p.Addr(), a...)
 }
 
-// A LazyDLL implements access to a single DLL.
+// A LazyDLL implements access to a single [DLL].
 // It will delay the load of the DLL until the first
-// call to its Handle method or to one of its
-// LazyProc's Addr method.
+// call to its [LazyDLL.Handle] method or to one of its
+// [LazyProc]'s Addr method.
 //
 // LazyDLL is subject to the same DLL preloading attacks as documented
-// on LoadDLL.
+// on [LoadDLL].
 //
 // Use LazyDLL in golang.org/x/sys/windows for a secure way to
 // load system DLLs.
@@ -217,26 +217,26 @@ func (d *LazyDLL) Handle() uintptr {
 	return uintptr(d.dll.Handle)
 }
 
-// NewProc returns a LazyProc for accessing the named procedure in the DLL d.
+// NewProc returns a [LazyProc] for accessing the named procedure in the [DLL] d.
 func (d *LazyDLL) NewProc(name string) *LazyProc {
 	return &LazyProc{l: d, Name: name}
 }
 
-// NewLazyDLL creates new LazyDLL associated with DLL file.
+// NewLazyDLL creates new [LazyDLL] associated with [DLL] file.
 func NewLazyDLL(name string) *LazyDLL {
 	return &LazyDLL{Name: name}
 }
 
-// A LazyProc implements access to a procedure inside a LazyDLL.
-// It delays the lookup until the Addr, Call, or Find method is called.
+// A LazyProc implements access to a procedure inside a [LazyDLL].
+// It delays the lookup until the [LazyProc.Addr], [LazyProc.Call], or [LazyProc.Find] method is called.
 type LazyProc struct {
 	mu   sync.Mutex
 	Name string
 	l    *LazyDLL
 	proc *Proc
 }
 
-// Find searches DLL for procedure named p.Name. It returns
+// Find searches [DLL] for procedure named p.Name. It returns
 // an error if search fails. Find will not search procedure,
 // if it is already found and loaded into memory.
 func (p *LazyProc) Find() error {

src/syscall/exec_plan9.go

@@ -69,7 +69,7 @@ func StringSlicePtr(ss []string) []*byte {
 
 // SlicePtrFromStrings converts a slice of strings to a slice of
 // pointers to NUL-terminated byte arrays. If any string contains
-// a NUL byte, it returns (nil, EINVAL).
+// a NUL byte, it returns (nil, [EINVAL]).
 func SlicePtrFromStrings(ss []string) ([]*byte, error) {
 	var err error
 	bb := make([]*byte, len(ss)+1)
@@ -528,7 +528,7 @@ func ForkExec(argv0 string, argv []string, attr *ProcAttr) (pid int, err error)
 	return startProcess(argv0, argv, attr)
 }
 
-// StartProcess wraps ForkExec for package os.
+// StartProcess wraps [ForkExec] for package os.
 func StartProcess(argv0 string, argv []string, attr *ProcAttr) (pid int, handle uintptr, err error) {
 	pid, err = startProcess(argv0, argv, attr)
 	return pid, 0, err
@@ -581,7 +581,7 @@ func Exec(argv0 string, argv []string, envv []string) (err error) {
 // WaitProcess waits until the pid of a
 // running process is found in the queue of
 // wait messages. It is used in conjunction
-// with ForkExec/StartProcess to wait for a
+// with [ForkExec]/[StartProcess] to wait for a
 // running process to exit.
 func WaitProcess(pid int, w *Waitmsg) (err error) {
 	procs.Lock()

src/syscall/exec_unix.go

@@ -54,21 +54,21 @@ import (
 // The rules for which file descriptor-creating operations use the
 // ForkLock are as follows:
 //
-//   - Pipe. Use pipe2 if available. Otherwise, does not block,
+//   - [Pipe]. Use pipe2 if available. Otherwise, does not block,
 //     so use ForkLock.
-//   - Socket. Use SOCK_CLOEXEC if available. Otherwise, does not
+//   - [Socket]. Use SOCK_CLOEXEC if available. Otherwise, does not
 //     block, so use ForkLock.
-//   - Open. Use O_CLOEXEC if available. Otherwise, may block,
+//   - [Open]. Use [O_CLOEXEC] if available. Otherwise, may block,
 //     so live with the race.
-//   - Dup. Use F_DUPFD_CLOEXEC or dup3 if available. Otherwise,
+//   - [Dup]. Use [F_DUPFD_CLOEXEC] or dup3 if available. Otherwise,
 //     does not block, so use ForkLock.
 var ForkLock sync.RWMutex
 
 // StringSlicePtr converts a slice of strings to a slice of pointers
 // to NUL-terminated byte arrays. If any string contains a NUL byte
 // this function panics instead of returning an error.
 //
-// Deprecated: Use SlicePtrFromStrings instead.
+// Deprecated: Use [SlicePtrFromStrings] instead.
 func StringSlicePtr(ss []string) []*byte {
 	bb := make([]*byte, len(ss)+1)
 	for i := 0; i < len(ss); i++ {
@@ -80,7 +80,7 @@ func StringSlicePtr(ss []string) []*byte {
 
 // SlicePtrFromStrings converts a slice of strings to a slice of
 // pointers to NUL-terminated byte arrays. If any string contains
-// a NUL byte, it returns (nil, EINVAL).
+// a NUL byte, it returns (nil, [EINVAL]).
 func SlicePtrFromStrings(ss []string) ([]*byte, error) {
 	n := 0
 	for _, s := range ss {
@@ -120,7 +120,7 @@ func SetNonblock(fd int, nonblocking bool) (err error) {
 }
 
 // Credential holds user and group identities to be assumed
-// by a child process started by StartProcess.
+// by a child process started by [StartProcess].
 type Credential struct {
 	Uid         uint32   // User ID.
 	Gid         uint32   // Group ID.
@@ -129,7 +129,7 @@ type Credential struct {
 }
 
 // ProcAttr holds attributes that will be applied to a new process started
-// by StartProcess.
+// by [StartProcess].
 type ProcAttr struct {
 	Dir   string    // Current working directory.
 	Env   []string  // Environment.
@@ -249,7 +249,7 @@ func ForkExec(argv0 string, argv []string, attr *ProcAttr) (pid int, err error)
 	return forkExec(argv0, argv, attr)
 }
 
-// StartProcess wraps ForkExec for package os.
+// StartProcess wraps [ForkExec] for package os.
 func StartProcess(argv0 string, argv []string, attr *ProcAttr) (pid int, handle uintptr, err error) {
 	pid, err = forkExec(argv0, argv, attr)
 	return pid, 0, err

src/syscall/flock_aix.go

@@ -8,7 +8,7 @@ import "unsafe"
 
 // On AIX, there is no flock() system call.
 
-// FcntlFlock performs a fcntl syscall for the F_GETLK, F_SETLK or F_SETLKW command.
+// FcntlFlock performs a fcntl syscall for the [F_GETLK], [F_SETLK] or [F_SETLKW] command.
 func FcntlFlock(fd uintptr, cmd int, lk *Flock_t) (err error) {
 	_, _, e1 := syscall6(uintptr(unsafe.Pointer(&libc_fcntl)), 3, uintptr(fd), uintptr(cmd), uintptr(unsafe.Pointer(lk)), 0, 0, 0)
 	if e1 != 0 {

src/syscall/flock_bsd.go

@@ -8,7 +8,7 @@ package syscall
 
 import "unsafe"
 
-// FcntlFlock performs a fcntl syscall for the F_GETLK, F_SETLK or F_SETLKW command.
+// FcntlFlock performs a fcntl syscall for the [F_GETLK], [F_SETLK] or [F_SETLKW] command.
 func FcntlFlock(fd uintptr, cmd int, lk *Flock_t) error {
 	_, err := fcntlPtr(int(fd), cmd, unsafe.Pointer(lk))
 	return err

src/syscall/flock_linux.go

@@ -10,7 +10,7 @@ import "unsafe"
 // systems by flock_linux_32bit.go to be SYS_FCNTL64.
 var fcntl64Syscall uintptr = SYS_FCNTL
 
-// FcntlFlock performs a fcntl syscall for the F_GETLK, F_SETLK or F_SETLKW command.
+// FcntlFlock performs a fcntl syscall for the [F_GETLK], [F_SETLK] or [F_SETLKW] command.
 func FcntlFlock(fd uintptr, cmd int, lk *Flock_t) error {
 	_, _, errno := Syscall(fcntl64Syscall, fd, uintptr(cmd), uintptr(unsafe.Pointer(lk)))
 	if errno == 0 {

src/syscall/pwd_plan9.go

@@ -23,7 +23,7 @@ var (
 )
 
 // Ensure current working directory seen by this goroutine matches
-// the most recent Chdir called in any goroutine. It's called internally
+// the most recent [Chdir] called in any goroutine. It's called internally
 // before executing any syscall which uses a relative pathname. Must
 // be called with the goroutine locked to the OS thread, to prevent
 // rescheduling on a different thread (potentially with a different

src/syscall/route_bsd.go

@@ -325,7 +325,7 @@ func (m *InterfaceAddrMessage) sockaddr() ([]Sockaddr, error) {
 }
 
 // ParseRoutingMessage parses b as routing messages and returns the
-// slice containing the RoutingMessage interfaces.
+// slice containing the [RoutingMessage] interfaces.
 //
 // Deprecated: Use golang.org/x/net/route instead.
 func ParseRoutingMessage(b []byte) (msgs []RoutingMessage, err error) {
@@ -352,7 +352,7 @@ func ParseRoutingMessage(b []byte) (msgs []RoutingMessage, err error) {
 }
 
 // ParseRoutingSockaddr parses msg's payload as raw sockaddrs and
-// returns the slice containing the Sockaddr interfaces.
+// returns the slice containing the [Sockaddr] interfaces.
 //
 // Deprecated: Use golang.org/x/net/route instead.
 func ParseRoutingSockaddr(msg RoutingMessage) ([]Sockaddr, error) {

src/syscall/sockcmsg_unix.go

@@ -12,7 +12,7 @@ import (
 	"unsafe"
 )
 
-// CmsgLen returns the value to store in the Len field of the Cmsghdr
+// CmsgLen returns the value to store in the Len field of the [Cmsghdr]
 // structure, taking into account any necessary alignment.
 func CmsgLen(datalen int) int {
 	return cmsgAlignOf(SizeofCmsghdr) + datalen

src/syscall/syscall.go

@@ -16,7 +16,7 @@
 // the manuals for the appropriate operating system.
 // These calls return err == nil to indicate success; otherwise
 // err is an operating system error describing the failure.
-// On most systems, that error has type syscall.Errno.
+// On most systems, that error has type [Errno].
 //
 // NOTE: Most of the functions, types, and constants defined in
 // this package are also available in the [golang.org/x/sys] package.
@@ -44,7 +44,7 @@ func StringByteSlice(s string) []byte {
 
 // ByteSliceFromString returns a NUL-terminated slice of bytes
 // containing the text of s. If s contains a NUL byte at any
-// location, it returns (nil, EINVAL).
+// location, it returns (nil, [EINVAL]).
 func ByteSliceFromString(s string) ([]byte, error) {
 	if bytealg.IndexByteString(s, 0) != -1 {
 		return nil, EINVAL
@@ -58,12 +58,12 @@ func ByteSliceFromString(s string) ([]byte, error) {
 // If s contains a NUL byte this function panics instead of returning
 // an error.
 //
-// Deprecated: Use BytePtrFromString instead.
+// Deprecated: Use [BytePtrFromString] instead.
 func StringBytePtr(s string) *byte { return &StringByteSlice(s)[0] }
 
 // BytePtrFromString returns a pointer to a NUL-terminated array of
 // bytes containing the text of s. If s contains a NUL byte at any
-// location, it returns (nil, EINVAL).
+// location, it returns (nil, [EINVAL]).
 func BytePtrFromString(s string) (*byte, error) {
 	a, err := ByteSliceFromString(s)
 	if err != nil {

src/syscall/syscall_js.go

@@ -48,7 +48,7 @@ const PathMax = 256
 //		err = errno
 //	}
 //
-// Errno values can be tested against error values using errors.Is.
+// Errno values can be tested against error values using [errors.Is].
 // For example:
 //
 //	_, _, err := syscall.Syscall(...)
@@ -88,7 +88,7 @@ func (e Errno) Timeout() bool {
 }
 
 // A Signal is a number describing a process signal.
-// It implements the os.Signal interface.
+// It implements the [os.Signal] interface.
 type Signal int
 
 const (

src/syscall/syscall_linux.go

@@ -1107,7 +1107,7 @@ func runtime_doAllThreadsSyscall(trap, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2,
 //
 // AllThreadsSyscall is unaware of any threads that are launched
 // explicitly by cgo linked code, so the function always returns
-// ENOTSUP in binaries that use cgo.
+// [ENOTSUP] in binaries that use cgo.
 //
 //go:uintptrescapes
 func AllThreadsSyscall(trap, a1, a2, a3 uintptr) (r1, r2 uintptr, err Errno) {
@@ -1118,7 +1118,7 @@ func AllThreadsSyscall(trap, a1, a2, a3 uintptr) (r1, r2 uintptr, err Errno) {
 	return r1, r2, Errno(errno)
 }
 
-// AllThreadsSyscall6 is like AllThreadsSyscall, but extended to six
+// AllThreadsSyscall6 is like [AllThreadsSyscall], but extended to six
 // arguments.
 //
 //go:uintptrescapes