summaryrefslogtreecommitdiff
path: root/doc/api/libstd/files.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/libstd/files.txt')
-rw-r--r--doc/api/libstd/files.txt369
1 files changed, 369 insertions, 0 deletions
diff --git a/doc/api/libstd/files.txt b/doc/api/libstd/files.txt
new file mode 100644
index 0000000..f75e765
--- /dev/null
+++ b/doc/api/libstd/files.txt
@@ -0,0 +1,369 @@
+{
+ title: File Handling
+ description: libstd: File Handling
+}
+
+File Handling
+-------------
+
+
+ pkg std =
+ type dir = struct
+ ;;
+
+ /* seek options */
+ const Seekset : whence
+ const Seekcur : whence
+ const Seekend : whence
+
+ /* open options */
+ const Ordonly : fdopt
+ const Owronly : fdopt
+ const Ordwr : fdopt
+ const Otrunc : fdopt
+ const Ocreat : fdopt
+ const Oappend : fdopt
+ const Odir : fdopt
+
+ /* directory handling */
+ const diropen : (p : byte[:] -> std.result(dir#, byte[:]))
+ const dirread : (d : dir# -> std.option(byte[:]))
+ const dirclose : (d : dir# -> void)
+ const dirname : (p : byte[:] -> byte[:])
+ const mkdir : (path : byte[:], mode : int64 -> int64)
+ const mkpath : (p : byte[:] -> bool)
+ const chdir : (path : byte[:] -> bool)
+
+ /* file handling */
+ const open : (path : byte[:], opts : fdopt -> std.result(fd, errno))
+ const openmode : (path : byte[:], opts : fdopt, mode : int64 -> std.result(fd, errno))
+ const mktemp : (base : byte[:], opts : fdopt, mode : int64 -> std.result((fd, byte[:]), errno)
+ const close : (fd : fd -> int64)
+ const creat : (path : byte[:], mode : int64 -> fd)
+ const read : (fd : fd, buf : byte[:] -> size)
+ const write : (fd : fd, buf : byte[:] -> size)
+ const seek : (fd : fd, delta : off, whence : whence -> off)
+ const pipe : (fds : fd[2]# -> int64)
+ const dup2 : (ofd : fd, nfd : fd -> fd)
+ const remove : (path : byte[:] -> bool)
+ const unlink : (path : byte[:] -> int)
+
+ /* path manipulation */
+ const basename : (p : byte[:] -> byte[:])
+ const pathcat : (a : byte[:], b : byte[:] -> byte[:])
+ const pathjoin : (p : byte[:][:] -> byte[:])
+ const pathnorm : (p : byte[:] -> byte[:])
+ const getcwd : (-> byte[:])
+
+ /* file properties */
+ const fmtime : (f : byte[:] -> result(time, errno))
+ const fsize : (f : byte[:] -> result(off, errno))
+ const fexists : (f : byte[:] -> bool)
+ const fisdir : (f : byte[:] -> bool)
+
+ /* convenience functions */
+ const slurp : (path : byte[:] -> result(byte[:], byte[:]))
+ const fslurp : (path : fd -> result(byte[:], byte[:]))
+ const blat : (path : byte[:], buf : byte[:], perm : int64 -> bool)
+ const fblat : (f : fd, buf : byte[:] -> bool)
+ ;;
+
+
+Data Types and Constants
+------------------------
+
+Libstd's file APIs are generally relatively thin wrappers around the host OS
+functions. They are a portable subset of this functionality, designed for both
+ease of use and portability.
+
+ type dir = struct
+ ;;
+
+The directory struct represents the current state of a directory walk.
+
+ /* seek options */
+ const Seekset : whence
+ const Seekcur : whence
+ const Seekend : whence
+
+These are a set of values which describe from where to seek within the file.
+
+ /* open options */
+ const Oread : fdopt
+ const Owrite : fdopt
+ const Ordwr : fdopt
+ const Otrunc : fdopt
+ const Ocreat : fdopt
+
+These are a set of options that are passed to the open variants describing
+what mode to open the file in. These are bit masks which be OR'ed together to
+combine them.
+
+`Oread` and `Owrite` request permission to read and write the file, respectively.
+`Ordwr` is a convenience flag which ors read and write together. `Otrunc`
+indicates that the file should be truncated to zero bytes in length before it
+is opened. `Ocreat` indicates that the file should be created if it does not
+exist instead of returning an error. `Odir` indicates that this file should
+be opened as a directory.
+
+`Ocreat` does not create the path leading to it, and will return an error if
+that path does not exist.
+
+
+Directories
+-----------
+
+ const diropen : (p : byte[:] -> std.result(dir#, byte[:]))
+
+The `diropen` function opens a path as a directory, and returns a pointer
+to an object which tracks the state of the directory, allowing for reading
+file names one by one from this directory.
+
+Returns: Either a directory wrapped up in the `\`Ok` branch of the result,
+or a string describing the failure reason in the `\`Fail` branch.
+
+ const dirread : (d : dir# -> result(option(byte[:]), errno)
+
+The `dirread` reads a single entry from the directory, opened with `diropen`,
+returning it as a string.
+
+Returns `\`Some entry`, or `\`None` at the end of the directory.
+
+ const dirclose : (d : dir# -> void)
+
+`dirclose` closes a directory for reading. This frees all associated
+resources, returning them to the system. The directory passed in must have
+been opened with `diropen`.
+
+Returns: Nothing.
+
+ const mkdir : (path : byte[:], mode : int64 -> errno)
+
+`mkdir` creates the directory specified in `path`. with the mode `mode`. It
+requires the parent directory to exist and be writable. Absolute paths will
+be created relative to the root of the file system, and relative paths will
+be created relative to the current working directory, as usual.
+
+If the directory already exists, this is counted as a failure to create the
+directory.
+
+Returns: Enone on success, or the error that caused the failure if it fails.
+
+ const mkpath : (path : byte[:] -> errno)
+
+`mkpath` creates a full path specified by `path`. It creates all of the
+path components required to create the full path specified. It requires
+the parent of the first directory entry that is not currently in existence
+to be writable.
+
+Absolute paths will be created relative to the root of the file system, and
+relative paths will be created relative to the current working directory, as
+usual.
+
+Returns: Enone on success, or the error that caused the directory creation
+to fail on failure.
+
+ const chdir : (path : byte[:] -> bool)
+
+Chdir changes the current working directory to the path specified in `path`.
+
+Returns: True on success, false on failure.
+
+Files
+-----
+
+ const open : (path : byte[:], opts : fdopt -> result(fd, errno))
+ const openmode : (path : byte[:], opts : fdopt, mode : int64 -> result(fd, errno))
+
+Open opens the file `path` for I/O according to the flags reqeusted in `opts`,
+and returns a result containing the file descriptor or error. The mode is a
+combination of the modes specified above: `Oread`, `Owrite`, `Ordwr`,
+`Otrunc`, or `Ocreat`.
+
+Openmode is similar to open, however, if Ocreate is passed, it the file
+requested will be created with the permissions passed in.
+
+Returns: either a valid file descriptor on success, or an error describing why
+the open failed on failure.
+
+ const mktemp : (base : byte[:], opts : fdopt, mode : int64 -> std.result((fd, byte[:]), errno)
+
+Mktemp is similar to openmode, however instead of taking a full path as
+its first argument, it generates a unique name for a file in temporary
+storage by appending a random string to the base name `base`. The mode
+provided is in addition to the implicit Ocreat | Oexcl.
+
+Returns: Either a successful result containing the tuple of file descriptor
+opened and path generated, or an error describing the failure. The path
+is allocated with `std.slalloc`, and must be freed by the caller using
+`std.slfree`. The file descriptor must be closed as ususal.
+
+
+ const close : (fd : fd -> void)
+
+Closes closes the file descriptor. If the file descriptor is valid, close
+is guaranteed to close it. If it is not valid, this is a no-op.
+
+ const read : (fd : fd, buf : byte[:] -> result(size, errno))
+
+Reads up to the length of `buf` from the file descriptor `fd`, at the current
+offset within the file, advancing the offset by the count of bytes read. The
+buffer may not be filled entirely when the read completes. For example, when
+reading from a console, often only one line will be returned at a time.
+
+Conventionally, `0` bytes are returned at the end of the file.
+
+Returns: Either the number of bytes read on success, or the error that caused
+a failure reading on failure.
+
+ const write : (fd : fd, buf : byte[:] -> result(size, errno))
+
+Write writes up to the length of `buf` to the file descriptor, writing the
+bytes at the current offset. The offset is advanced by the number of bytes
+that were written, extending the file size if necessary. Write is not
+guaranteed to write the full buffer.
+
+Returns: The number of bytes written on success, or the error that caused
+the failure on error.
+
+ const seek : (fd : fd, delta : off, whence : whence -> result(off, errno))
+
+Seek changes the current offset within the file descriptor `fd` by `delta`.
+This delta can be treated in three different ways, depending on the value of
+`whence.
+
+If `whence` is Seekset, then `delta` is treated as an absolute value to seek
+to, and the offset is set to `delta`. If `whence` is `Seekcur`, then `delta`
+is added to the current offset. If `whence` is `Seekend`, then `delta` is
+added to the size of the file.
+
+Returns: Either the new offset within the file on success, or the error that
+occurred on failure.
+
+ const pipe : (fds : fd[2]# -> errno)
+
+Pipe creates a unidirectional channel for communication between processes.
+Two file descriptors are returned in the array fd. Data written to fd[1] is
+available in fd[0]. The pipe may or may not be buffered.
+
+Returns: Enone on success, otherwise, returns the error that caused this
+call to fail.
+
+ const dup2 : (ofd : fd, nfd : fd -> result(fd, errno))
+
+Dup2 copies the old fd `ofd` to the new fd `nfd`. If the file descriptor
+`nfd` is already open, then it is implicitly closed by this call before
+the fd is copied. This is done atomically.
+
+Returns: Either the new fd used, on success, or an error describing the
+failure.
+
+ const remove : (path : byte[:] -> errno)
+
+Remove removes the file specified from the directory in which it is contained.
+The user must have write permissions for the directory in order to remove
+files from it. If `path` is a directory, it must be empty.
+
+Returns: Enone on success, otherwise the error that caused the failure.
+
+Path Manipulation
+-----------------
+ const basename : (p : byte[:] -> byte[:])
+ const dirname : (p : byte[:] -> byte[:])
+
+Given a string of the form "foo/bar/baz", `dirname()` returns the directory
+component of it -- in other words, everything up to the final `/`. It ignores
+trailing slashes. It
+
+The caller is responsible for freeing the path with `slfree`.
+
+For example, `dirname("foo/bar//")` will return `"foo/bar"`.
+
+ const pathcat : (a : byte[:], b : byte[:] -> byte[:])
+
+Pathcat joins two paths together, using '/' as a directory
+separator. The paths are normalized before being returned. This
+call is shorthand for `std.pathjoin([a, b][:])`.
+
+The caller is responsible for freeing the path with `slfree`.
+
+Returns: A concatenated path.
+
+ const pathjoin : (p : byte[:][:] -> byte[:])
+
+Pathcat joins a list of paths together, using '/' as a directory
+separator. The paths are normalized before being returned. This
+call is shorthand for `std.pathjoin([a, b][:])`.
+
+The caller is responsible for freeing the path with `slfree`.
+
+Returns: A concatenated path.
+
+ const pathnorm : (p : byte[:] -> byte[:])
+
+Pathnorm does a purely lexical normalization of the path. It removes
+redundant components, doubled `/` characters, and similar. The returned
+path is equivalent to the original input path.
+
+The caller is responsible for freeing the path with `slfree`.
+
+Returns: A new normalized path.
+
+ const getcwd : (-> byte[:])
+
+Returns the current working directory of the program. The caller is
+responsible for freeing the path with `slfree`.
+
+Returns: A string representing the working directory.
+
+File Properties
+---------------
+
+ const fmtime : (f : byte[:] -> result(time, errno))
+
+Returns either the last modification time of the file `f`, or
+the error that was encountered extracting this information.
+
+ const fsize : (f : byte[:] -> result(off, errno))
+
+Returns either the size in bytes of the file `f`, or
+the error that was encountered extracting this information.
+
+ const fexists : (f : byte[:] -> bool)
+
+Returns `true` if the file is able to be `stat`ed, or `false`
+if this fails.
+
+ const fisdir : (f : byte[:] -> bool)
+
+Returns `true` if the file is a directory that is able to be `stat`ed, or
+`false` if this fails.
+
+Convenience Functions
+---------------------
+
+ const slurp : (path : byte[:] -> result(byte[:], errno))
+
+Reads all bytes from `path` until the end of file.
+
+Returns either the file data, or the failure encountered.
+
+ const fslurp : (fd : fd -> result(byte[:], errno))
+
+Reads all bytes from the file descriptor `fd` until the end of file.
+
+Returns either the file data, or the failure encountered.
+
+ const blat : (path : byte[:], buf : byte[:], perm : int64 -> bool)
+
+Creates the file `path` with permissions `perm`, and writes as much of
+`buf` as it can into it.
+
+Returns Enone if no errors were encountered. Otherwise, the error is returned.
+
+ const fblat : (f : fd, buf : byte[:] -> bool)
+
+Writes as much of `buf` as it can into the file descriptor `fd`.
+
+Returns Enone if no errors were encountered. Otherwise, the error is returned.
+