Skip to content

API Filesystem

Jump to bottom
Vexatos edited this page Jul 13, 2014 · 4 revisions

For those that don't like images: the wiki has moved to a new place, http://ocdoc.cil.li/.
This wiki will no longer be updated.

This library allows a general way of interacting with file system components. While each component is it's own "folder", these folders can be "mounted" somewhere into a global directory tree. This allows seamlessly interacting on multiple file system components.

  • filesystem.isAutorunEnabled(): boolean
    Returns whether autorun is currently enabled. If this is true, newly mounted file systems will be checked for a file named autorun[.lua] in their root directory. If such a file exists, it is executed.
  • filesystem.setAutorunEnabled(value: boolean)
    Sets whether autorun files should be ran on startup.
  • filesystem.canonical(path: string): string
    Returns the canonical form of the specified path, i.e. a path containing no "indirections" such as . or ... For example, the paths /tmp/../bin/ls.lua and /bin/./ls.lua are equivalent, and their canonical form is /bin/ls.lua.
    Note that this function truncates relative paths to their topmost "known" directory. For example, ../bin/ls.lua becomes bin/ls.lua. It stays a relative path, however - mind the lack of a leading slash.
  • filesystem.concat(pathA: string, pathB: string[, ...]): string
    Concatenates two or more paths. Note that all paths other than the first are treated as relative paths, even if they begin with a slash. The canonical form of the resulting concatenated path is returned, so fs.concat("a", "..") results in an empty string.
  • filesystem.path(path: string): string
    Returns the path component of a path to a file, i.e. everything before the last slash in the canonical form of the specified path.
  • filesystem.name(path: string): string
    Returns the file name component of a path to a file, i.e. everything after the last slash in the canonical form of the specified path.
  • filesystem.proxy(filter: string): table or nil, string
    This is similar to component.proxy, except that the specified string may also be a file system component's label. We check for the label first, if no file system has the specified label we fall back to component.proxy. Returns the proxy of the specified file system, or nil and an error message if no file system matching the specified filter was found.
  • filesystem.mount(fs: table or string, path: string): boolean or nil, string
    Mounts a file system at the specified path. The first parameter can be either a file system component's proxy, its address or its label. The second is a path into the global directory tree. Returns true if the file system was successfully mounted, nil and an error message otherwise.
  • filesystem.mounts(): function -> table, string
    Returns an iterator function over all currently mounted file system component's proxies and the paths at which they are mounted. This means the same proxy may appear multiple times, but with different mount paths.
  • filesystem.umount(fsOrPath: table or string): boolean
    Unmounts a file system. The parameter can either be a file system component's proxy or (abbreviated) address, in which case all mount points of this file system will be removed, or a path into the global directory structure, in which case the file system mount containing that directory will be unmounted.
  • filesystem.get(path: string): table, string or nil, string
    Gets the file system component's proxy that contains the specified path. Returns the proxy and mount path, or nil and an error message.
  • filesystem.exists(path: string): boolean
    Checks whether a file or folder exist at the specified path.
  • filesystem.size(path: string): number
    Gets the file size of the file at the specified location. Returns 0 if the path points to anything other than a file.
  • filesystem.isDirectory(path: string): boolean
    Gets whether the path points to a directory. Returns false if not, either because the path points to a file, or file.exists(path) is false.
  • filesystem.lastModified(path: string): number
    Returns the real world unicode timestamp of the last time the file at the specified path was modified. For directories this is usually the time of their creation.
  • filesystem.list(path: string): function -> string or nil, string
    Returns an iterator over all elements in the directory at the specified path. Returns nil and an error messages if the path is invalid or some other error occurred.
    Note that directories usually are postfixed with a slash, to allow identifying them without an additional call to fs.isDirectory.
  • filesystem.makeDirectory(path: string): boolean or nil, string
    Creates a new directory at the specified path. Creates any parent directories that do not extist yet, if necessary. Returns true on success, nil and an error message otherwise.
  • filesystem.remove(path: string): boolean or nil, string
    Deletes a file or folder. If the path specifies a folder, deletes all files and subdirectories in the folder, recursively. Return true on success, nil and an error message otherwise.
  • filesystem.rename(oldPath: string, newPath: string): boolean or nil, string
    Renames a file or folder. If the paths point to different file system components this will only work for files, because it actually perform a copy operation, followed by a deletion if the copy succeeds.
    Returns true on success, nil and an error message otherwise.
  • filesystem.copy(fromPath: string, toPath: string): boolean or nil, string
    Copies a file to the specified location. The target path has to contain the target file name. Does not support folders.
  • filesystem.open(path: string[, mode: string]): table or nil, string
    Opens a file at the specified path for reading or writing. If mode is not specified it defaults to "r". Possible modes are: r, rb, w, wb, a and ab.
    Returns a file stream (see below) on success, nil and an error message otherwise.
    Note that you can only open a limited number of files per file system at the same time. Files will be automatically closed when the garbage collection kicks in, but it is generally a good idea to call close on the file stream when done with the file.
    Important: it is generally recommended to use io.open instead of this function, to get a buffered wrapper for the file stream.

When opening files directly via the file system API you will get a file stream, a table with four functions. These functions are thin wrappers to the file system proxy's callbacks, which also means that read/write operations are not buffered, and can therefore be slow when reading few bytes often. You'll usually want to use io.open instead.

  • file:close()
    Closes the file stream, releasing the handle on the underlying file system.
  • file:read(n: number): string or nil, string
    Tries to read the specified number of bytes from the file stream. Returns the read string, which may be shorter than the specified number. Returns nil when the end of the stream was reached. Returns nil and an error message if some error occurred.
  • file:seek(whence: string[, offset: number]): number or nil, string
    Jumps to the specified position in the file stream, if possible. Only supported by file streams opened in read mode. The first parameter determines the relative location to seek from and can be cur for the current position, set for the beginning of the stream and end for the end of the stream. The second parameter is the offset by which to modify the position. Returns the new position or nil and an error message if some error occurred.
    The default value for the second parameter is 0, so f:seek("set") will reset the position to the start of the file, f:seek("cur") will return the current position in the file.
  • file:write(str: value): boolean or nil, string
    Writes the specified data to the stream. Returns true on success, nil and an error message otherwise.
Clone this wiki locally