fs(3lua): init man pages

Initialise man pages for the fs module.

man/fs/fs.3lua.scd

@@ -0,0 +1,15 @@
+FS(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs* - file system and path manipulation library
+
+# SYNOPSIS
+.Syn
+
+# DESCRIPTION
+The *fs* library provides routines to manipulate
+files, directories, and other parts of the file system,
+as well as path strings.
+
+# SEE ALSO
+callisto(3lua)

man/fs/fs.basename.3lua.scd

@@ -0,0 +1,29 @@
+FS.BASENAME(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.basename* - get the last component of a path
+
+# SYNOPSIS
+*fs.basename*(_path_: *string*)
+
+# DESCRIPTION
+*fs.basename* returns the last component of _path_,
+removing any trailing slash "/" characters.
+If _path_ consists entirely of slash characters, the string "/" is
+returned.
+If _path_ is an empty string, the string "." is returned.
+
+This is purely a string manipulation function
+and depends on no outside state.
+
+# EXAMPLES
+Print the name of the currently running script file:
+
+	print("name of script file is " .. fs.basename(arg[0]))
+
+Output example:
+
+	assert(fs.basename("/etc/fstab") == "fstab")
+
+# SEE ALSO
+callisto(3lua), fs(3lua)

man/fs/fs.copy.3lua.scd

@@ -0,0 +1,44 @@
+FS.COPY(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.copy* - copy a file
+
+# SYNOPSIS
+*fs.copy*(_source_: *string*, _target_: *string*)
+
+# DESCRIPTION
+*fs.copy* copies the contents of the _source_ file to the _target_ file,
+overwriting any existing contents of the _target_ file.
+
+It can be considered analogous to the *cp* shell command.
+
+The call _fs.copy("src", "trg")_ is roughly equivalent to the following
+Lua code:
+
+```
+local sf, se = assert(io.open("src", 'r'))
+local tf, te = assert(io.open("trg", 'w'))
+
+repeat
+	local readbuf = readbuf or ""
+	tf:write(readbuf)
+	readbuf = sf:read(512)
+until not readbuf
+```
+
+# EXAMPLES
+Create a file _tel_ and write some data to it,
+and copy its contents to the file _tel2_:
+
+```
+local contents = [[
+maja    0501-1136285
+peter   0136-7399214
+]]
+io.output("tel"):write(contents)
+fs.copy("tel", "tel2")
+assert(io.input("tel2"):read("a") == contents)
+```
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.move(3lua)

man/fs/fs.dirname.3lua.scd

@@ -0,0 +1,30 @@
+FS.DIRNAME(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.dirname* - get the parent directory of a path
+
+# SYNOPSIS
+*fs.dirname*(_path_: *string*)
+
+# DESCRIPTION
+*fs.dirname* returns the parent directory of _path_.
+
+Any trailing "/" characters found in _path_
+are not counted as part of the directory name.
+If _path_ is an empty string or contains no "/" characters,
+the string "." is returned.
+
+This is purely a string manipulation function
+and depends on no outside state.
+
+# EXAMPLES
+Print the directory containing the current script file:
+
+	print(fs.dirname(arg[0]))
+
+Output example:
+
+	assert(fs.dirname("/usr/local/bin") == "/usr/local")
+
+# SEE ALSO
+callisto(3lua), fs(3lua)

man/fs/fs.entries.3lua.scd

@@ -0,0 +1,36 @@
+FS.ENTRIES(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.entries* - iterate over a directory
+
+# SYNOPSIS
+*fs.entries*([_directory_: *string*])
+
+# DESCRIPTION
+*fs.entries* returns an iterator function which can be used to iterate
+over the contents of a directory, so that the idiom
+
+	for entry in fs.entries(_directory_)
+		_code..._
+	end
+
+will run the code inside the loop for every directory entry.
+
+Without any arguments *fs.entries* will iterate over the current
+working directory but an argument can be provided to use a different
+directory instead.
+
+On each iteration, the iterator will return a table retrieved from
+fs.status(3lua), containing information about the next file in the
+directory such as its path, mode, owner, and modify date.
+
+# EXAMPLES
+List every file and directory in _/etc_ and its type as retrieved from
+fs.type(3lua):
+
+	for entry in fs.entries("/etc") do
+		print(fs.type("/etc/" .. entry.path), entry.path)
+	end
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.status(3lua)

man/fs/fs.exists.3lua.scd

@@ -0,0 +1,21 @@
+FS.EXISTS(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.exists* - check existence of a path in the file system
+
+# SYNOPSIS
+*fs.exists*(_path_: *string*)
+
+# DESCRIPTION
+*fs.exists* returns whether the pathname _path_ exists
+in the file system.
+
+# EXAMPLES
+Check whether _tel_ exists:
+
+	if not fs.exists("tel") then
+		print("tel does not exist")
+	end
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.isfile(3lua)

man/fs/fs.isdirectory.3lua.scd

@@ -0,0 +1,27 @@
+FS.ISDIRECTORY(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.isdirectory* - check whether a path points to a directory
+
+# SYNOPSIS
+*fs.isdirectory*(_path_: *string*)
+
+# DESCRIPTION
+*fs.isdirectory* returns whether _path_ points to a directory.
+
+If an error occurs,
+*fs.isdirectory* returns nil, an error message and
+a platform-dependent error code.
+Usually this only happens when passing a nonexistent path,
+or a path to a file which you do not have permission to read.
+See lstat(2) for a complete list.
+
+# EXAMPLES
+Check whether /bin is a directory:
+
+	if not fs.isdirectory("/bin") then
+		print("something's wrong...")
+	end
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.isfile(3lua)

man/fs/fs.isfile.3lua.scd

@@ -0,0 +1,28 @@
+FS.ISFILE(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.isfile* - check whether a path points to a regular file
+
+# SYNOPSIS
+*fs.isfile*(_path_: *string*)
+
+# DESCRIPTION
+*fs.isfile* returns whether _path_ points to a regular file
+(i.e. not a directorym symbolic link, or character/block device).
+
+If an error occurs,
+*fs.isfile* returns nil, an error message and
+a platform-dependent error code.
+Usually this only happens when passing a nonexistent path,
+or a path to a file which you do not have permission to read.
+See lstat(2) for a complete list.
+
+# EXAMPLES
+Make sure _tel_ is a regular file:
+
+	if not fs.isfile("tel") then
+		print("tel is not a regular file")
+	end
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.isdirectory(3lua), fs.issymlink(3lua)

man/fs/fs.issymlink.3lua.scd

@@ -0,0 +1,28 @@
+FS.ISSYMLINK(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.issymlink* - check whether a path points to a symbolic link
+
+# SYNOPSIS
+*fs.issymlink*(_path_: *string*)
+
+# DESCRIPTION
+*fs.issymlink* returns whether _path_ points to a symbolic link
+(see symlink(7)).
+
+If an error occurs,
+*fs.issymlink* returns nil, an error message and
+a platform-dependent error code.
+Usually this only happens when passing a nonexistent path,
+or a path to a file which you do not have permission to read.
+See lstat(2) for a complete list.
+
+# EXAMPLES
+Check whether /bin is a symbolic link:
+
+	if fs.issymlink("/bin") then
+		print("most likely merged /usr")
+	end
+
+# SEE ALSO
+callisto(3lua), fs(3lua), symlink(7)

man/fs/fs.mkdir.3lua.scd

@@ -0,0 +1,27 @@
+FS.MKDIR(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.mkdir* - create a directory
+
+# SYNOPSIS
+*fs.mkdir*(_path_: *string*)
+
+# DESCRIPTION
+*fs.mkdir* creates a new directory at _path_.
+
+If you're trying to create multiple directories at once,
+you should use fs.mkpath(3lua) instead.
+
+If an error occurs,
+*fs.mkdir* returns nil, an error message and
+a platform-dependent error code.
+There are many reasons *fs.mkdir* can fail;
+see mkdir(2) for a list of possible error values.
+
+# EXAMPLES
+Create the user's home directory:
+
+	fs.mkdir(environ["HOME"])
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.mkpath(3lua), mkdir(2)

man/fs/fs.mkpath.3lua.scd

@@ -0,0 +1,32 @@
+FS.MKPATH(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.mkpath* - create a tree of directories
+
+# SYNOPSIS
+*fs.mkpath*(_path_: *string*)
+
+# DESCRIPTION
+*fs.mkpath* creates multiple directories specified by one path.
+For example, _fs.mkpath("/usr/local/share/man/man3lua")_ would first
+check that _/usr_ is a directory, and if not attempt to create it, and
+then repeat that same process for each following component of the path,
+similar to the behaviour of mkdir(1)'s *-p* option.
+
+For creating single directories without this advanced functionality,
+it might better suit you to use fs.mkdir(3lua) instead.
+
+If an error occurs,
+*fs.mkpath* returns nil, an error message and
+a platform-dependent error code.
+There are many reasons *fs.mkpath* can fail;
+see mkdir(2) and stat(2) for possible error values.
+
+# EXAMPLES
+Create the directory _/usr/local/include/callisto_, creating
+intermediate directories as required:
+
+	fs.mkpath("/usr/local/include/callisto")
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.mkdir(3lua), mkdir(2)

man/fs/fs.move.3lua.scd

@@ -0,0 +1,31 @@
+FS.MOVE(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.move* - move a file
+
+# SYNOPSIS
+*fs.move*(_src_: *string*, _dst_: *string*)
+
+# DESCRIPTION
+*fs.move* moves the file _src_ to the path _dst_,
+overwriting _dst_ if it exists.
+Both _src_ and _dst_ must be of the same type
+(that is, both directories or both non-directories)
+and must reside on the same file system.
+
+If you need to move files across different file systems,
+consider using fs.copy(3lua) instead.
+
+If an error occurs,
+*fs.move* returns nil, an error message and
+a platform-dependent error code.
+There are many reasons *fs.move* can fail;
+see rename(2) for a list of possible error values.
+
+# EXAMPLES
+Rename the file _tel_ to _tel1_:
+
+	fs.move("tel", "tel1")
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.copy(3lua), rename(2)

man/fs/fs.remove.3lua.scd

@@ -0,0 +1,35 @@
+FS.REMOVE(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.remove* - remove a file or directory
+
+# SYNOPSIS
+*fs.remove*(_path_: *string*)
+
+# DESCRIPTION
+*fs.remove* removes the file or directory at _path_.
+
+If _path_ specifies a file, *fs.remove* removes the file.
+If _path_ specifies a directory, *fs.remove* recursively removes any
+other files or directories inside the directory given,
+and then removes the directory itself once it is empty.
+
+If an error occurs,
+*fs.remove* returns nil, an error message and
+a platform-dependent error code.
+There are many reasons *fs.remove* can fail;
+see rmdir(2) and unlink(2) for possible error values.
+
+## Warning
+This function is capable of destroying large amounts of data on a disk
+very quickly.
+In case of data damage using *fs.remove* or other means, consider
+using data recovery software such as testdisk(8).
+
+# EXAMPLES
+Remove the _tel2_ file:
+
+	fs.remove("tel2")
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.rmdir(3lua), unlink(2), rmdir(2)

man/fs/fs.rmdir.3lua.scd

@@ -0,0 +1,30 @@
+FS.RMDIR(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.rmdir* - remove an empty directory
+
+# SYNOPSIS
+*fs.rmdir*(_dir_: *string*)
+
+# DESCRIPTION
+*fs.rmdir* removes the empty directory _dir_.
+
+If you need to recursively remove a directory containing other files
+or directories, you should use fs.remove(3lua) instead.
+
+If an error occurs,
+*fs.rmdir* returns nil, an error message and
+a platform-dependent error code.
+There are many reasons *fs.rmdir* can fail;
+see rmdir(2) for a list of possible error values.
+
+# EXAMPLES
+Remove the empty directory _mydir_:
+
+```
+assert(fs.mkdir("mydir"))
+fs.rmdir("mydir")
+```
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.remove(3lua), rmdir(2)

man/fs/fs.status.3lua.scd

@@ -0,0 +1,76 @@
+FS.STATUS(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.status* - get the status of a file
+
+# SYNOPSIS
+*fs.status*(_path_: *string*)
+
+# DESCRIPTION
+*fs.status* retrieves information about the file pointed to by _path_
+and returns a table with fields representing this information.
+No prior permission is required on _path_ itself,
+but all directories in the pathname leading to the file
+must be searchable.
+
+The returned table has the following fields:
+
+- *path* (*string*): The path provided to *fs.status*.
+- *mode* (*integer*): The file's mode; see *Modes* below.
+- *uid* (*integer*): UID of the file's owner.
+- *gid* (*integer*): GID of the file's group.
+- *accessdate* (*integer*): Time the file's data was last accessed.
+- *modifydate* (*integer*): Time the file's data was last modified.
+- *chdate* (*integer*): Time the file's status last changed.
+
+Times are in the form of integers representing the amount of seconds
+passed since January 1, 1970.
+
+## Modes
+The _mode_ field of the returned structure is a bitmask created by
+ORing different mode values found in chmod(2).
+These mode values are made available to Lua through constants
+in the *fs* table, with the _S\__ prefix removed.
+For example, the _S\_IXOTH_ constant mentioned in chmod(2)
+can be referenced in Lua with _fs.IXOTH_.
+
+To find the type of a file from its mode, bitwise AND the mode with
+_fs.IFMT_ and compare the result with one of the following constants
+in the *fs* library:
+
+- *IFBLK*: Block special.
+- *IFCHR*: Character special.
+- *IFIFO*: FIFO special.
+- *IFREG*: Regular.
+- *IFDIR*: Directory.
+- *IFLNK*: Symbolic link.
+- *IFSOCK*: Socket.
+
+## Errors
+If an error occurs,
+*fs.status* returns nil, an error message and
+a platform-dependent error code.
+There are many reasons *fs.status* can fail;
+see lstat(2) for a list of possible error values.
+
+# EXAMPLES
+Print the UIDs of every file in a table:
+
+```
+files = {"tel1", "tel2"}
+for file in ipairs(files) do
+	local st = fs.status(file)
+	print(st.uid, st.path)
+end
+```
+
+Output whether _/sbin_ is a directory:
+
+	print(fs.status("/sbin").mode & fs.IFMT == fs.IFDIR)
+
+On some systems with a merged /usr, this will output false.
+Changing _IFDIR_ to _IFLNK_ in this example should output true
+in that case. 
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.type(3lua), lstat(2)

man/fs/fs.type.3lua.scd

@@ -0,0 +1,35 @@
+FS.TYPE(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.type* - get a file's type
+
+# SYNOPSIS
+*fs.type*(_path_: *string*)
+
+# DESCRIPTION
+*fs.type* returns a string describing the type of the file
+pointed to by _path_.
+
+The following strings can be returned:
+
+- *"block"*: _path_ is a block device
+- *"character"*: _path_ is a character device
+- *"directory"*: _path_ is a directory
+- *"fifo"*: _path_ is a FIFO
+- *"file"*: _path_ is a regular file
+- *"socket"*: _path_ is a Unix domain socket
+- *"symlink"*: _path_ is a symbolic link
+
+If an error occurs,
+*fs.type* returns nil, an error message and
+a platform-dependent error code.
+There are many reasons *fs.type* can fail;
+see lstat(2) for a list of possible error values.
+
+# EXAMPLES
+Print the type of /dev/urandom (on Linux and OpenBSD):
+
+	print(fs.type("/dev/urandom")) --> character
+
+# SEE ALSO
+callisto(3lua), fs(3lua), fs.status(3lua), lstat(2)

man/fs/fs.workdir.3lua.scd

@@ -0,0 +1,37 @@
+FS.WORKDIR(3lua) "3lua" "Callisto manual pages"
+
+# NAME
+*fs.workdir* - get or set the current working directory
+
+# SYNOPSIS
+*fs.workdir*([_dir_: *string*])
+
+# DESCRIPTION
+If _dir_ is not nil, *fs.workdir* sets the current working directory
+to the path _dir_.
+This means the starting point of all pathnames not beginning with a
+slash ('/') will be set to _dir_ until the working directory is
+changed again by a call to *fs.workdir* or chdir(2).
+
+If _dir_ is nil, *fs.workdir* returns the current working directory.
+
+If an error occurs,
+*fs.workdir* returns nil, an error message and
+a platform-dependent error code.
+There are many reasons *fs.workdir* can fail;
+see chdir(2) for possible error values
+when setting the current working directory,
+and getcwd(2) for possible error values
+when getting the current working directory.
+
+# EXAMPLES
+Get the current working directory:
+
+	local wd = fs.workdir()
+
+Set the current working directory to the user's home directory:
+
+	fs.workdir(environ["HOME"])
+
+# SEE ALSO
+callisto(3lua), fs(3lua), chdir(2), getcwd(2)