io/fs: document that Sub does not check for existence

Also recommend os.Root for constraining access.

Fixes #77447

Change-Id: Id8d178163438e9264fe19ed37ba03e1ee5d0bd35
Reviewed-on: https://go-review.googlesource.com/c/go/+/742284
Reviewed-by: Damien Neil <dneil@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Michael Pratt <mpratt@google.com>

diff --git a/src/io/fs/sub.go b/src/io/fs/sub.go
index 376d561bad84470c32a87ab6eda81d49fd82f126..63c7a3cf77ce92dd501b5caa5eb7b40a964e1293 100644 (file)
--- a/src/io/fs/sub.go
+++ b/src/io/fs/sub.go
@@ -24,7 +24,8 @@ type SubFS interface {
 // Otherwise, Sub returns a new [FS] implementation sub that,
 // in effect, implements sub.Open(name) as fsys.Open(path.Join(dir, name)).
 // The implementation also translates calls to ReadDir, ReadFile,
-// ReadLink, Lstat, and Glob appropriately.
+// ReadLink, Lstat, and Glob appropriately. Sub does not check if the
+// directory currently exists.
 //
 // Note that Sub(os.DirFS("/"), "prefix") is equivalent to os.DirFS("/prefix")
 // and that neither of them guarantees to avoid operating system
@@ -32,6 +33,7 @@ type SubFS interface {
 // does not check for symbolic links inside "/prefix" that point to
 // other directories. That is, [os.DirFS] is not a general substitute for a
 // chroot-style security mechanism, and Sub does not change that fact.
+// Use [os.Root] to constrain access to particular directory trees.
 func Sub(fsys FS, dir string) (FS, error) {
        if !ValidPath(dir) {
                return nil, &PathError{Op: "sub", Path: dir, Err: ErrInvalid}