From: Damien Neil Date: Tue, 6 Jan 2026 23:57:00 +0000 (-0800) Subject: os/exec: move platform-specific LookPath docs to a common comment X-Git-Tag: go1.26rc3~11^2~16 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=c16402d15b42cf494774796e606aba66c90d3d6b;p=gostls13.git os/exec: move platform-specific LookPath docs to a common comment We have four different LookPath variations (unix, windows, plan9, wasm), each with slightly different doc comments. Unify the documentation and move it to a single, common LookPath. Change-Id: I56bae57e80887a73ef0f6933258ee0a48dbccdcf Reviewed-on: https://go-review.googlesource.com/c/go/+/734320 Reviewed-by: Roland Shoemaker Reviewed-by: Brad Fitzpatrick LUCI-TryBot-Result: Go LUCI --- diff --git a/src/os/exec/lookpath.go b/src/os/exec/lookpath.go new file mode 100644 index 0000000000..71f86b994f --- /dev/null +++ b/src/os/exec/lookpath.go @@ -0,0 +1,30 @@ +// Copyright 2026 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package exec + +// LookPath searches for an executable named file in the current path, +// following the conventions of the host operating system. +// If file contains a slash, it is tried directly and the default path is not consulted. +// Otherwise, on success the result is an absolute path. +// +// LookPath returns an error satisfying [errors.Is](err, [ErrDot]) +// if the resolved path is relative to the current directory. +// See the package documentation for more details. +// +// LookPath looks for an executable named file in the +// directories named by the PATH environment variable, +// except as described below. +// +// - On Windows, the file must have an extension named by +// the PATHEXT environment variable. +// When PATHEXT is unset, the file must have +// a ".com", ".exe", ".bat", or ".cmd" extension. +// - On Plan 9, LookPath consults the path environment variable. +// If file begins with "/", "#", "./", or "../", it is tried +// directly and the path is not consulted. +// - On Wasm, LookPath always returns an error. +func LookPath(file string) (string, error) { + return lookPath(file) +} diff --git a/src/os/exec/lp_plan9.go b/src/os/exec/lp_plan9.go index f713a6905c..711aad11bd 100644 --- a/src/os/exec/lp_plan9.go +++ b/src/os/exec/lp_plan9.go @@ -26,16 +26,7 @@ func findExecutable(file string) error { return fs.ErrPermission } -// LookPath searches for an executable named file in the -// directories named by the path environment variable. -// If file begins with "/", "#", "./", or "../", it is tried -// directly and the path is not consulted. -// On success, the result is an absolute path. -// -// In older versions of Go, LookPath could return a path relative to the current directory. -// As of Go 1.19, LookPath will instead return that path along with an error satisfying -// [errors.Is](err, [ErrDot]). See the package documentation for more details. -func LookPath(file string) (string, error) { +func lookPath(file string) (string, error) { if err := validateLookPath(filepath.Clean(file)); err != nil { return "", &Error{file, err} } diff --git a/src/os/exec/lp_unix.go b/src/os/exec/lp_unix.go index e5fddbafe2..d3b10cc43d 100644 --- a/src/os/exec/lp_unix.go +++ b/src/os/exec/lp_unix.go @@ -41,15 +41,7 @@ func findExecutable(file string) error { return fs.ErrPermission } -// LookPath searches for an executable named file in the -// directories named by the PATH environment variable. -// If file contains a slash, it is tried directly and the PATH is not consulted. -// Otherwise, on success, the result is an absolute path. -// -// In older versions of Go, LookPath could return a path relative to the current directory. -// As of Go 1.19, LookPath will instead return that path along with an error satisfying -// [errors.Is](err, [ErrDot]). See the package documentation for more details. -func LookPath(file string) (string, error) { +func lookPath(file string) (string, error) { // NOTE(rsc): I wish we could use the Plan 9 behavior here // (only bypass the path if file begins with / or ./ or ../) // but that would not match all the Unix shells. diff --git a/src/os/exec/lp_wasm.go b/src/os/exec/lp_wasm.go index 3c819049ba..1de9076e53 100644 --- a/src/os/exec/lp_wasm.go +++ b/src/os/exec/lp_wasm.go @@ -17,7 +17,7 @@ var ErrNotFound = errors.New("executable file not found in $PATH") // directories named by the PATH environment variable. // If file contains a slash, it is tried directly and the PATH is not consulted. // The result may be an absolute path or a path relative to the current directory. -func LookPath(file string) (string, error) { +func lookPath(file string) (string, error) { // Wasm can not execute processes, so act as if there are no executables at all. return "", &Error{file, ErrNotFound} } diff --git a/src/os/exec/lp_windows.go b/src/os/exec/lp_windows.go index 74537dec68..f58aabc19f 100644 --- a/src/os/exec/lp_windows.go +++ b/src/os/exec/lp_windows.go @@ -56,22 +56,12 @@ func findExecutable(file string, exts []string) (string, error) { return "", ErrNotFound } -// LookPath searches for an executable named file in the -// directories named by the PATH environment variable. -// LookPath also uses PATHEXT environment variable to match -// a suitable candidate. -// If file contains a slash, it is tried directly and the PATH is not consulted. -// Otherwise, on success, the result is an absolute path. -// -// In older versions of Go, LookPath could return a path relative to the current directory. -// As of Go 1.19, LookPath will instead return that path along with an error satisfying -// [errors.Is](err, [ErrDot]). See the package documentation for more details. -func LookPath(file string) (string, error) { +func lookPath(file string) (string, error) { if err := validateLookPath(file); err != nil { return "", &Error{file, err} } - return lookPath(file, pathExt()) + return lookPathExts(file, pathExt()) } // lookExtensions finds windows executable by its dir and path. @@ -101,17 +91,17 @@ func lookExtensions(path, dir string) (string, error) { } } if dir == "" { - return lookPath(path, exts) + return lookPathExts(path, exts) } if filepath.VolumeName(path) != "" { - return lookPath(path, exts) + return lookPathExts(path, exts) } if len(path) > 1 && os.IsPathSeparator(path[0]) { - return lookPath(path, exts) + return lookPathExts(path, exts) } dirandpath := filepath.Join(dir, path) // We assume that LookPath will only add file extension. - lp, err := lookPath(dirandpath, exts) + lp, err := lookPathExts(dirandpath, exts) if err != nil { return "", err } @@ -138,8 +128,8 @@ func pathExt() []string { return exts } -// lookPath implements LookPath for the given PATHEXT list. -func lookPath(file string, exts []string) (string, error) { +// lookPathExts implements LookPath for the given PATHEXT list. +func lookPathExts(file string, exts []string) (string, error) { if strings.ContainsAny(file, `:\/`) { f, err := findExecutable(file, exts) if err == nil {