Namespace: go.std.io.fs

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms
• Types

Summary

Provides a low-level interface to the io/fs package.

Package fs defines basic interfaces to a file system.
A file system can be provided by the host operating system
but also by other packages.

Index

• *FileMode
• *PathError
• *WalkDirFunc
• DirEntry
• ErrClosed
• ErrExist
• ErrInvalid
• ErrNotExist
• ErrPermission
• FS
• File
• FileInfo
• FileInfoToDirEntry
• FileMode
• Glob
• GlobFS
• ModeAppend
• ModeCharDevice
• ModeDevice
• ModeDir
• ModeExclusive
• ModeIrregular
• ModeNamedPipe
• ModePerm
• ModeSetgid
• ModeSetuid
• ModeSocket
• ModeSticky
• ModeSymlink
• ModeTemporary
• ModeType
• PathError
• ReadDir
• ReadDirFS
• ReadDirFile
• ReadFile
• ReadFileFS
• SkipDir
• Stat
• StatFS
• Sub
• SubFS
• ValidPath
• WalkDir
• WalkDirFunc
• arrayOfDirEntry
• arrayOfFS
• arrayOfFile
• arrayOfFileInfo
• arrayOfFileMode
• arrayOfGlobFS
• arrayOfPathError
• arrayOfReadDirFS
• arrayOfReadDirFile
• arrayOfReadFileFS
• arrayOfStatFS
• arrayOfSubFS
• arrayOfWalkDirFunc

Legend

Constant Variable Function Macro Special form Type GoVar Receiver/Method

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

(None.)

Variables

• ErrClosed

  Var v1.0

  "file already closed"
  

• ErrExist

  Var v1.0

  "file already exists"
  

• ErrInvalid

  Var v1.0

  "invalid argument"
  

• ErrNotExist

  Var v1.0

  "file does not exist"
  

• ErrPermission

  Var v1.0

  "permission denied"
  

• ModeAppend

  GoObject v1.0

  a: append-only
  

• ModeCharDevice

  GoObject v1.0

  c: Unix character device, when ModeDevice is set
  

• ModeDevice

  GoObject v1.0

  D: device file
  

• ModeDir

  GoObject v1.0

  The single letters are the abbreviations
  used by the String method's formatting.
  

• ModeExclusive

  GoObject v1.0

  l: exclusive use
  

• ModeIrregular

  GoObject v1.0

  ?: non-regular file; nothing else is known about this file
  

• ModeNamedPipe

  GoObject v1.0

  p: named pipe (FIFO)
  

• ModePerm

  GoObject v1.0

  Unix permission bits
  

• ModeSetgid

  GoObject v1.0

  g: setgid
  

• ModeSetuid

  GoObject v1.0

  u: setuid
  

• ModeSocket

  GoObject v1.0

  S: Unix domain socket
  

• ModeSticky

  GoObject v1.0

  t: sticky
  

• ModeSymlink

  GoObject v1.0

  L: symbolic link
  

• ModeTemporary

  GoObject v1.0

  T: temporary file; Plan 9 only
  

• ModeType

  GoObject v1.0

  Mask for the type bits. For regular files, none will be set.
  

• SkipDir

  Var v1.0

  SkipDir is used as a return value from WalkDirFuncs to indicate that
  the directory named in the call is to be skipped. It is not returned
  as an error by any function.
  

Functions, Macros, and Special Forms

• FileInfoToDirEntry

  Function v1.0

  (FileInfoToDirEntry info)
  

  FileInfoToDirEntry returns a DirEntry that returns information from info.
  If info is nil, FileInfoToDirEntry returns nil.
  
  Go input arguments: (info FileInfo)
  
  Go returns: DirEntry
  
  Joker input arguments: [^FileInfo info]
  
  Joker returns: ^DirEntry

• Glob

  Function v1.0

  (Glob fsys pattern)
  

  Glob returns the names of all files matching pattern or nil
  if there is no matching file. The syntax of patterns is the same
  as in path.Match. The pattern may describe hierarchical names such as
  usr/*/bin/ed.
  
  Glob ignores file system errors such as I/O errors reading directories.
  The only possible returned error is path.ErrBadPattern, reporting that
  the pattern is malformed.
  
  If fs implements GlobFS, Glob calls fs.Glob.
  Otherwise, Glob uses ReadDir to traverse the directory tree
  and look for matches for the pattern.
  
  Go input arguments: (fsys FS, pattern string)
  
  Go returns: (matches []string, err error)
  
  Joker input arguments: [^FS fsys, ^String pattern]
  
  Joker returns: [^arrayOfString matches, ^Error err]

• ReadDir

  Function v1.0

  (ReadDir fsys name)
  

  ReadDir reads the named directory
  and returns a list of directory entries sorted by filename.
  
  If fs implements ReadDirFS, ReadDir calls fs.ReadDir.
  Otherwise ReadDir calls fs.Open and uses ReadDir and Close
  on the returned file.
  
  Go input arguments: (fsys FS, name string)
  
  Go returns: ([]DirEntry, error)
  
  Joker input arguments: [^FS fsys, ^String name]
  
  Joker returns: [^arrayOfDirEntry, ^Error]

• ReadFile

  Function v1.0

  (ReadFile fsys name)
  

  ReadFile reads the named file from the file system fs and returns its contents.
  A successful call returns a nil error, not io.EOF.
  (Because ReadFile reads the whole file, the expected EOF
  from the final Read is not treated as an error to be reported.)
  
  If fs implements ReadFileFS, ReadFile calls fs.ReadFile.
  Otherwise ReadFile calls fs.Open and uses Read and Close
  on the returned file.
  
  Go input arguments: (fsys FS, name string)
  
  Go returns: ([]byte, error)
  
  Joker input arguments: [^FS fsys, ^String name]
  
  Joker returns: [^arrayOfByte, ^Error]

• Stat

  Function v1.0

  (Stat fsys name)
  

  Stat returns a FileInfo describing the named file from the file system.
  
  If fs implements StatFS, Stat calls fs.Stat.
  Otherwise, Stat opens the file to stat it.
  
  Go input arguments: (fsys FS, name string)
  
  Go returns: (FileInfo, error)
  
  Joker input arguments: [^FS fsys, ^String name]
  
  Joker returns: [^FileInfo, ^Error]

• Sub

  Function v1.0

  (Sub fsys dir)
  

  Sub returns an FS corresponding to the subtree rooted at fsys's dir.
  
  If dir is ".", Sub returns fsys unchanged.
  Otherwise, if fs implements SubFS, Sub returns fsys.Sub(dir).
  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, and Glob appropriately.
  
  Note that Sub(os.DirFS("/"), "prefix") is equivalent to os.DirFS("/prefix")
  and that neither of them guarantees to avoid operating system
  accesses outside "/prefix", because the implementation of os.DirFS
  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.
  
  Go input arguments: (fsys FS, dir string)
  
  Go returns: (FS, error)
  
  Joker input arguments: [^FS fsys, ^String dir]
  
  Joker returns: [^FS, ^Error]

• ValidPath

  Function v1.0

  (ValidPath name)
  

  ValidPath reports whether the given path name
  is valid for use in a call to Open.
  
  Path names passed to open are UTF-8-encoded,
  unrooted, slash-separated sequences of path elements, like “x/y/z”.
  Path names must not contain an element that is “.” or “..” or the empty string,
  except for the special case that the root directory is named “.”.
  Paths must not start or end with a slash: “/x” and “x/” are invalid.
  
  Note that paths are slash-separated on all systems, even Windows.
  Paths containing other characters such as backslash and colon
  are accepted as valid, but those characters must never be
  interpreted by an FS implementation as path element separators.
  
  Go input arguments: (name string)
  
  Go returns: bool
  
  Joker input arguments: [^String name]
  
  Joker returns: ^Boolean

• WalkDir

  Function v1.0

  (WalkDir fsys root fn)
  

  WalkDir walks the file tree rooted at root, calling fn for each file or
  directory in the tree, including root.
  
  All errors that arise visiting files and directories are filtered by fn:
  see the fs.WalkDirFunc documentation for details.
  
  The files are walked in lexical order, which makes the output deterministic
  but requires WalkDir to read an entire directory into memory before proceeding
  to walk that directory.
  
  WalkDir does not follow symbolic links found in directories,
  but if root itself is a symbolic link, its target will be walked.
  
  Go input arguments: (fsys FS, root string, fn WalkDirFunc)
  
  Go returns: error
  
  Joker input arguments: [^FS fsys, ^String root, ^WalkDirFunc fn]
  
  Joker returns: ^Error

Types

• *FileMode

  Concrete Type v1.0

  A FileMode represents a file's mode and permission bits.
  The bits have the same definition on all systems, so that
  information about files can be moved from one system
  to another portably. Not all bits apply to all systems.
  The only required bit is ModeDir for directories.
  

• *PathError

  Concrete Type v1.0

  PathError records an error and the operation and file path that caused it.
  

• Error

  Receiver for *PathError v1.0

  ([])
  

• Timeout

  Receiver for *PathError v1.0

  ([])
  

  Timeout reports whether this error represents a timeout.
  

• Unwrap

  Receiver for *PathError v1.0

  ([])
  

• *WalkDirFunc

  Concrete Type v1.0

  WalkDirFunc is the type of the function called by WalkDir to visit
  each file or directory.
  
  The path argument contains the argument to WalkDir as a prefix.
  That is, if WalkDir is called with root argument "dir" and finds a file
  named "a" in that directory, the walk function will be called with
  argument "dir/a".
  
  The d argument is the fs.DirEntry for the named path.
  
  The error result returned by the function controls how WalkDir
  continues. If the function returns the special value SkipDir, WalkDir
  skips the current directory (path if d.IsDir() is true, otherwise
  path's parent directory). Otherwise, if the function returns a non-nil
  error, WalkDir stops entirely and returns that error.
  
  The err argument reports an error related to path, signaling that
  WalkDir will not walk into that directory. The function can decide how
  to handle that error; as described earlier, returning the error will
  cause WalkDir to stop walking the entire tree.
  
  WalkDir calls the function with a non-nil err argument in two cases.
  
  First, if the initial fs.Stat on the root directory fails, WalkDir
  calls the function with path set to root, d set to nil, and err set to
  the error from fs.Stat.
  
  Second, if a directory's ReadDir method fails, WalkDir calls the
  function with path set to the directory's path, d set to an
  fs.DirEntry describing the directory, and err set to the error from
  ReadDir. In this second case, the function is called twice with the
  path of the directory: the first call is before the directory read is
  attempted and has err set to nil, giving the function a chance to
  return SkipDir and avoid the ReadDir entirely. The second call is
  after a failed ReadDir and reports the error from ReadDir.
  (If ReadDir succeeds, there is no second call.)
  
  The differences between WalkDirFunc compared to filepath.WalkFunc are:
  
  - The second argument has type fs.DirEntry instead of fs.FileInfo.
  - The function is called before reading a directory, to allow SkipDir
  to bypass the directory read entirely.
  - If a directory read fails, the function is called a second time
  for that directory to report the error.
  

• DirEntry

  Abstract Type v1.0

  A DirEntry is an entry read from a directory
  (using the ReadDir function or a ReadDirFile's ReadDir method).
  

• Info

  Method for DirEntry v1.0

  ([])
  

• IsDir

  Method for DirEntry v1.0

  ([])
  

• Name

  Method for DirEntry v1.0

  ([])
  

• Type

  Method for DirEntry v1.0

  ([])
  

• FS

  Abstract Type v1.0

  An FS provides access to a hierarchical file system.
  
  The FS interface is the minimum implementation required of the file system.
  A file system may implement additional interfaces,
  such as ReadFileFS, to provide additional or optimized functionality.
  

• Open

  Method for FS v1.0

  ([name])
  

• File

  Abstract Type v1.0

  A File provides access to a single file.
  The File interface is the minimum implementation required of the file.
  Directory files should also implement ReadDirFile.
  A file may implement io.ReaderAt or io.Seeker as optimizations.
  

• Close

  Method for File v1.0

  ([])
  

• Read

  Method for File v1.0

  ([arg1])
  

• Stat

  Method for File v1.0

  ([])
  

• FileInfo

  Abstract Type v1.0

  A FileInfo describes a file and is returned by Stat.
  

• IsDir

  Method for FileInfo v1.0

  ([])
  

• ModTime

  Method for FileInfo v1.0

  ([])
  

• Mode

  Method for FileInfo v1.0

  ([])
  

• Name

  Method for FileInfo v1.0

  ([])
  

• Size

  Method for FileInfo v1.0

  ([])
  

• Sys

  Method for FileInfo v1.0

  ([])
  

• FileMode

  Concrete Type v1.0

  A FileMode represents a file's mode and permission bits.
  The bits have the same definition on all systems, so that
  information about files can be moved from one system
  to another portably. Not all bits apply to all systems.
  The only required bit is ModeDir for directories.
  

• IsDir

  Receiver for FileMode v1.0

  ([])
  

  IsDir reports whether m describes a directory.
  That is, it tests for the ModeDir bit being set in m.
  

• IsRegular

  Receiver for FileMode v1.0

  ([])
  

  IsRegular reports whether m describes a regular file.
  That is, it tests that no mode type bits are set.
  

• Perm

  Receiver for FileMode v1.0

  ([])
  

  Perm returns the Unix permission bits in m (m & ModePerm).
  

• String

  Receiver for FileMode v1.0

  ([])
  

• Type

  Receiver for FileMode v1.0

  ([])
  

  Type returns type bits in m (m & ModeType).
  

• GlobFS

  Abstract Type v1.0

  A GlobFS is a file system with a Glob method.
  

• Glob

  Method for GlobFS v1.0

  ([pattern])
  

• Open

  Method for GlobFS v1.0

  ([name])
  

• PathError

  Concrete Type v1.0

  PathError records an error and the operation and file path that caused it.
  

• ReadDirFS

  Abstract Type v1.0

  ReadDirFS is the interface implemented by a file system
  that provides an optimized implementation of ReadDir.
  

• Open

  Method for ReadDirFS v1.0

  ([name])
  

• ReadDir

  Method for ReadDirFS v1.0

  ([name])
  

• ReadDirFile

  Abstract Type v1.0

  A ReadDirFile is a directory file whose entries can be read with the ReadDir method.
  Every directory file should implement this interface.
  (It is permissible for any file to implement this interface,
  but if so ReadDir should return an error for non-directories.)
  

• Close

  Method for ReadDirFile v1.0

  ([])
  

• Read

  Method for ReadDirFile v1.0

  ([arg1])
  

• ReadDir

  Method for ReadDirFile v1.0

  ([n])
  

• Stat

  Method for ReadDirFile v1.0

  ([])
  

• ReadFileFS

  Abstract Type v1.0

  ReadFileFS is the interface implemented by a file system
  that provides an optimized implementation of ReadFile.
  

• Open

  Method for ReadFileFS v1.0

  ([name])
  

• ReadFile

  Method for ReadFileFS v1.0

  ([name])
  

• StatFS

  Abstract Type v1.0

  A StatFS is a file system with a Stat method.
  

• Open

  Method for StatFS v1.0

  ([name])
  

• Stat

  Method for StatFS v1.0

  ([name])
  

• SubFS

  Abstract Type v1.0

  A SubFS is a file system with a Sub method.
  

• Open

  Method for SubFS v1.0

  ([name])
  

• Sub

  Method for SubFS v1.0

  ([dir])
  

• WalkDirFunc

  Concrete Type v1.0

  WalkDirFunc is the type of the function called by WalkDir to visit
  each file or directory.
  
  The path argument contains the argument to WalkDir as a prefix.
  That is, if WalkDir is called with root argument "dir" and finds a file
  named "a" in that directory, the walk function will be called with
  argument "dir/a".
  
  The d argument is the fs.DirEntry for the named path.
  
  The error result returned by the function controls how WalkDir
  continues. If the function returns the special value SkipDir, WalkDir
  skips the current directory (path if d.IsDir() is true, otherwise
  path's parent directory). Otherwise, if the function returns a non-nil
  error, WalkDir stops entirely and returns that error.
  
  The err argument reports an error related to path, signaling that
  WalkDir will not walk into that directory. The function can decide how
  to handle that error; as described earlier, returning the error will
  cause WalkDir to stop walking the entire tree.
  
  WalkDir calls the function with a non-nil err argument in two cases.
  
  First, if the initial fs.Stat on the root directory fails, WalkDir
  calls the function with path set to root, d set to nil, and err set to
  the error from fs.Stat.
  
  Second, if a directory's ReadDir method fails, WalkDir calls the
  function with path set to the directory's path, d set to an
  fs.DirEntry describing the directory, and err set to the error from
  ReadDir. In this second case, the function is called twice with the
  path of the directory: the first call is before the directory read is
  attempted and has err set to nil, giving the function a chance to
  return SkipDir and avoid the ReadDir entirely. The second call is
  after a failed ReadDir and reports the error from ReadDir.
  (If ReadDir succeeds, there is no second call.)
  
  The differences between WalkDirFunc compared to filepath.WalkFunc are:
  
  - The second argument has type fs.DirEntry instead of fs.FileInfo.
  - The function is called before reading a directory, to allow SkipDir
  to bypass the directory read entirely.
  - If a directory read fails, the function is called a second time
  for that directory to report the error.
  

• arrayOfDirEntry

  Concrete Type v1.0

  A DirEntry is an entry read from a directory
  (using the ReadDir function or a ReadDirFile's ReadDir method).
  

• arrayOfFS

  Concrete Type v1.0

  An FS provides access to a hierarchical file system.
  
  The FS interface is the minimum implementation required of the file system.
  A file system may implement additional interfaces,
  such as ReadFileFS, to provide additional or optimized functionality.
  

• arrayOfFile

  Concrete Type v1.0

  A File provides access to a single file.
  The File interface is the minimum implementation required of the file.
  Directory files should also implement ReadDirFile.
  A file may implement io.ReaderAt or io.Seeker as optimizations.
  

• arrayOfFileInfo

  Concrete Type v1.0

  A FileInfo describes a file and is returned by Stat.
  

• arrayOfFileMode

  Concrete Type v1.0

  A FileMode represents a file's mode and permission bits.
  The bits have the same definition on all systems, so that
  information about files can be moved from one system
  to another portably. Not all bits apply to all systems.
  The only required bit is ModeDir for directories.
  

• arrayOfGlobFS

  Concrete Type v1.0

  A GlobFS is a file system with a Glob method.
  

• arrayOfPathError

  Concrete Type v1.0

  PathError records an error and the operation and file path that caused it.
  

• arrayOfReadDirFS

  Concrete Type v1.0

  ReadDirFS is the interface implemented by a file system
  that provides an optimized implementation of ReadDir.
  

• arrayOfReadDirFile

  Concrete Type v1.0

  A ReadDirFile is a directory file whose entries can be read with the ReadDir method.
  Every directory file should implement this interface.
  (It is permissible for any file to implement this interface,
  but if so ReadDir should return an error for non-directories.)
  

• arrayOfReadFileFS

  Concrete Type v1.0

  ReadFileFS is the interface implemented by a file system
  that provides an optimized implementation of ReadFile.
  

• arrayOfStatFS

  Concrete Type v1.0

  A StatFS is a file system with a Stat method.
  

• arrayOfSubFS

  Concrete Type v1.0

  A SubFS is a file system with a Sub method.
  

• arrayOfWalkDirFunc

  Concrete Type v1.0

  WalkDirFunc is the type of the function called by WalkDir to visit
  each file or directory.
  
  The path argument contains the argument to WalkDir as a prefix.
  That is, if WalkDir is called with root argument "dir" and finds a file
  named "a" in that directory, the walk function will be called with
  argument "dir/a".
  
  The d argument is the fs.DirEntry for the named path.
  
  The error result returned by the function controls how WalkDir
  continues. If the function returns the special value SkipDir, WalkDir
  skips the current directory (path if d.IsDir() is true, otherwise
  path's parent directory). Otherwise, if the function returns a non-nil
  error, WalkDir stops entirely and returns that error.
  
  The err argument reports an error related to path, signaling that
  WalkDir will not walk into that directory. The function can decide how
  to handle that error; as described earlier, returning the error will
  cause WalkDir to stop walking the entire tree.
  
  WalkDir calls the function with a non-nil err argument in two cases.
  
  First, if the initial fs.Stat on the root directory fails, WalkDir
  calls the function with path set to root, d set to nil, and err set to
  the error from fs.Stat.
  
  Second, if a directory's ReadDir method fails, WalkDir calls the
  function with path set to the directory's path, d set to an
  fs.DirEntry describing the directory, and err set to the error from
  ReadDir. In this second case, the function is called twice with the
  path of the directory: the first call is before the directory read is
  attempted and has err set to nil, giving the function a chance to
  return SkipDir and avoid the ReadDir entirely. The second call is
  after a failed ReadDir and reports the error from ReadDir.
  (If ReadDir succeeds, there is no second call.)
  
  The differences between WalkDirFunc compared to filepath.WalkFunc are:
  
  - The second argument has type fs.DirEntry instead of fs.FileInfo.
  - The function is called before reading a directory, to allow SkipDir
  to bypass the directory read entirely.
  - If a directory read fails, the function is called a second time
  for that directory to report the error.