Interface Root

Root may be used to only access files within a single directory tree.

Methods on Root can only access files and directories beneath a root directory. If any component of a file name passed to a method of Root references a location outside the root, the method returns an error. File names may reference the directory itself (.).

Methods on Root will follow symbolic links, but symbolic links may not reference a location outside the root. Symbolic links must not be absolute.

Methods on Root do not prohibit traversal of filesystem boundaries, Linux bind mounts, /proc special files, or access to Unix device files.

Methods on Root are safe to be used from multiple goroutines simultaneously.

On most platforms, creating a Root opens a file descriptor or handle referencing the directory. If the directory is moved, methods on Root reference the original directory in its new location.

Root's behavior differs on some platforms:

  - When GOOS=windows, file names may not reference Windows reserved device names
    such as NUL and COM1.
  - When GOOS=js, Root is vulnerable to TOCTOU (time-of-check-time-of-use)
    attacks in symlink validation, and cannot ensure that operations will not
    escape the root.
  - When GOOS=plan9 or GOOS=js, Root does not track directories across renames.
    On these platforms, a Root references a directory name, not a file descriptor.
Copy