diff --git a/man/fs/fs.3lua.scd b/man/fs/fs.3lua.scd new file mode 100644 index 0000000..5a7c6fc --- /dev/null +++ b/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) diff --git a/man/fs/fs.basename.3lua.scd b/man/fs/fs.basename.3lua.scd new file mode 100644 index 0000000..e369fc1 --- /dev/null +++ b/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) diff --git a/man/fs/fs.copy.3lua.scd b/man/fs/fs.copy.3lua.scd new file mode 100644 index 0000000..84f0b12 --- /dev/null +++ b/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) diff --git a/man/fs/fs.dirname.3lua.scd b/man/fs/fs.dirname.3lua.scd new file mode 100644 index 0000000..8a5a399 --- /dev/null +++ b/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) diff --git a/man/fs/fs.entries.3lua.scd b/man/fs/fs.entries.3lua.scd new file mode 100644 index 0000000..502c29e --- /dev/null +++ b/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) diff --git a/man/fs/fs.exists.3lua.scd b/man/fs/fs.exists.3lua.scd new file mode 100644 index 0000000..b7a9bad --- /dev/null +++ b/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) diff --git a/man/fs/fs.isdirectory.3lua.scd b/man/fs/fs.isdirectory.3lua.scd new file mode 100644 index 0000000..24bfba5 --- /dev/null +++ b/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) diff --git a/man/fs/fs.isfile.3lua.scd b/man/fs/fs.isfile.3lua.scd new file mode 100644 index 0000000..da24cda --- /dev/null +++ b/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) diff --git a/man/fs/fs.issymlink.3lua.scd b/man/fs/fs.issymlink.3lua.scd new file mode 100644 index 0000000..3451969 --- /dev/null +++ b/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) diff --git a/man/fs/fs.mkdir.3lua.scd b/man/fs/fs.mkdir.3lua.scd new file mode 100644 index 0000000..3af86a6 --- /dev/null +++ b/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) diff --git a/man/fs/fs.mkpath.3lua.scd b/man/fs/fs.mkpath.3lua.scd new file mode 100644 index 0000000..87edc5d --- /dev/null +++ b/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) diff --git a/man/fs/fs.move.3lua.scd b/man/fs/fs.move.3lua.scd new file mode 100644 index 0000000..65d3b8b --- /dev/null +++ b/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) diff --git a/man/fs/fs.remove.3lua.scd b/man/fs/fs.remove.3lua.scd new file mode 100644 index 0000000..66a5304 --- /dev/null +++ b/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) diff --git a/man/fs/fs.rmdir.3lua.scd b/man/fs/fs.rmdir.3lua.scd new file mode 100644 index 0000000..b55ee0b --- /dev/null +++ b/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) diff --git a/man/fs/fs.status.3lua.scd b/man/fs/fs.status.3lua.scd new file mode 100644 index 0000000..8d59f62 --- /dev/null +++ b/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) diff --git a/man/fs/fs.type.3lua.scd b/man/fs/fs.type.3lua.scd new file mode 100644 index 0000000..801032c --- /dev/null +++ b/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) diff --git a/man/fs/fs.workdir.3lua.scd b/man/fs/fs.workdir.3lua.scd new file mode 100644 index 0000000..0bd17c0 --- /dev/null +++ b/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)