package b0
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=dadde8cfa62be9dabd805fc190b415427b4699ffe3458c153e2f3f9cc5c9b9b4
md5=f96ac96fb0182f2b97dbe9ded452544b
doc/b0.std/B0_std/Os/Dir/index.html
Module Os.Dir
Directory operations.
This module operates on directories, most functions error if they are applied to other file kinds.
Existence
exists dir
is Ok true
if dir
is a directory in the file system and Ok false
otherwise. Symbolic links are followed.
must_exist dir
is Ok ()
if dir
is a directory in the file system and an error otherwise. Symbolic links are followed.
Creating
create ~mode ~make_path dir
creates the directory dir
.
mode
are the file permission ofdir
. They default to0o755
(readable and traversable by everyone, writeable by the user).- If
make_path
istrue
and the parent directory ofp
does not exist the whole path to the parent is created as needed with permission0o755
(readable and traversable by everyone, writable by the user)
The result is:
Ok true
ifdir
did not exist and was created.Ok false
ifdir
did exist as (possibly a symlink to) a directory. In this case the mode ofdir
and any other directory is kept unchanged.Error _
otherwise and in particular ifdir
exists as a non-directory.
Contents
val fold :
?rel:bool ->
?dotfiles:bool ->
?follow_symlinks:bool ->
?prune:(Unix.stats -> string -> Fpath.t -> bool) ->
recurse:bool ->
(Unix.stats -> string -> Fpath.t -> 'a -> 'a) ->
Fpath.t ->
'a ->
('a, string) result
fold ~rel ~dotfiles ~follow_symlinks ~prune ~recurse f dir acc
folds f
over the contents of dir
starting with acc
. If dir
does not exist the function errors.
f st name p acc
is called with each pathp
folded over withst
its stat information,name
its filename andacc
the accumulator.- If
recurse
istrue
sub-directoriesdir
are folded over recursively moduloprune
(see below). Ifrecurse
is false only the direct contents ofdir
is folded over. prune
is called only whenrecurse
istrue
asprune st d
withd
any sub-directory to be folded over andst
its stat information. If the result istrue
d
and its contents are not folded over. Defaults tofun _ _ _ -> false
follow_symlinks
iftrue
(default), symbolic links are followed. Iffalse
symbolic links are not followed and the stat information given toprune
andf
is given byPath.symlink_stat
.- If
dotfiles
isfalse
(default) elements whose filename start with a.
are not folded over - If
rel
isfalse
(default) the paths given tof
andprune
havedir
prepended, iftrue
they are relative todir
.
Fold order. The fold order is generally undefined. The only guarantee is that directory paths are folded over before their content.
Warning. Given the raciness of the POSIX file API it cannot be guaranteed that really all existing files will be folded over in presence of other processes.
val fold_files :
?rel:bool ->
?dotfiles:bool ->
?follow_symlinks:bool ->
?prune:(Unix.stats -> string -> Fpath.t -> bool) ->
recurse:bool ->
(Unix.stats -> string -> Fpath.t -> 'a -> 'a) ->
Fpath.t ->
'a ->
('a, string) result
fold_files
is like fold
but f
is only applied to non-directory files.
val fold_dirs :
?rel:bool ->
?dotfiles:bool ->
?follow_symlinks:bool ->
?prune:(Unix.stats -> string -> Fpath.t -> bool) ->
recurse:bool ->
(Unix.stats -> string -> Fpath.t -> 'a -> 'a) ->
Fpath.t ->
'a ->
('a, string) result
fold_dirs
is like fold
but f
is only applied to directory files.
val path_list : Unix.stats -> string -> Fpath.t -> Fpath.t list -> Fpath.t list
path_list
is a folding function to get a (reverse w.r.t. folding order) list of paths.
Copying
val copy :
?rel:bool ->
?atomic:bool ->
?allow_hardlinks:bool ->
?follow_symlinks:bool ->
?prune:(Unix.stats -> string -> Fpath.t -> bool) ->
make_path:bool ->
recurse:bool ->
src:Fpath.t ->
Fpath.t ->
(unit, string) result
copy ~rel ~atomic ~prune ~follow_symlinks ~make_path ~recurse ~src dst
copies the directory src
to dst
. File modes of src
and its contents are preserved in dst
. The function errors if dst
exists.
- If
recurse
istrue
sub-directories ofdir
are also copied recursively, unless they areprune
d (see below). Iffalse
only the files ofsrc
are copied moduloprune
. FIXME I think this is weird - If
make_path
istrue
and the parent directory ofdst
does not exist the whole path to the parent is created as needed with permission0o755
(readable and traversable by everyone, writable by the user). prune st name p
is called on each pathp
to copy withst
its stat information andname
its filename. If the function returnstrue
the directory or file is not copied over. Defaults tofun _ _ _ -> false
.- If
follow_symlinks
istrue
(default), symlinks are followed. Iffalse
symbolic links are not followed, the actual symlinks are copied and the stat information given toprune
is given byOs.Path.symlink_stat
. allow_hardlinks
iftrue
, tries to hard link files fromsrc
at the destination, falling back to copying if that's not possible. Defaults tofalse
.atomic
if atomic istrue
and the function errors thendst
should not exist. To write atomically, a temporary directoryt
in the parent directory ofdst
is created. On copy successt
is renamed todst
. On errort
is deleted anddst
left intact. This means the user needs write permissions in the parent directory ofdst
, in practice this is almost always the case but fails for some directories (e.g. writing in/sys
on Linux®).- If
rel
isfalse
(default) the paths given toprune
havesrc
prepended. Iftrue
they are relative tosrc
.
Current working directory (cwd)
cwd ()
is the current working directory. The resulting path is guaranteed to be absolute.
set_cwd dir
sets the current working directory to dir
.
with_cwd dir f
is f ()
with the current working directory bound to dir
. After the function returns the current working directory is back to its initial value.
Default temporary directory
val default_tmp : unit -> Fpath.t
default_tmp ()
is a default directory that can be used as a default directory for creating temporary files and directories. If set_default_tmp
hasn't been called this is:
- On POSIX, the value of the
TMPDIR
environment variable orFpath.v "/tmp"
if the variable is not set or empty. - On Windows, the value of the
TEMP
environment variable orFpath.v "."
if it is not set or empty.
val set_default_tmp : Fpath.t -> unit
set_default_tmp p
sets the value returned by default_tmp
to p
.
Temporary directories
val with_tmp :
?mode:int ->
?make_path:bool ->
?dir:Fpath.t ->
?name:Path.tmp_name ->
(Fpath.t -> 'a) ->
('a, string) result
with_tmp ~mode ~make_path ~dir ~name f
creates a temporary empty directory t
and returns Ok (f t). After the function returns (normally or via an exception) t
and its content are deleted.
name
is used to construct the filename of the directory, seeFile.tmp_name
for details. It defaults to"tmp-%s"
.dir
is the directory in which the temporary file is created. It defaults toDir.default_tmp()
.- If
make_path
istrue
(default) anddir
doesn't exist the whole path to it is created as needed with permission0o755
(readable and traversable by everyone, writable by the user). mode
are the permissions of the temporary directory; they default to0o700
, only readable, writeable and traversable by the user
val tmp :
?mode:int ->
?make_path:bool ->
?dir:Fpath.t ->
?name:Path.tmp_name ->
unit ->
(Fpath.t, string) result
tmp
is like with_tmp
except the directory and its content is only deleted at the end of program execution if the client doesn't do it before.
Base directories
The directories returned by these functions are not guaranteed to exist.
user ()
is the home directory of the user executing the process. Determined by consulting passwd
database with the user if of the process. If this fails or on Windows falls back to parse a path from the HOME
environment variables.
config ()
is the directory used to store user-specific program configurations. This is in order:
- If set the value of
XDG_CONFIG_HOME
. - If set and on Windows® the value of
%LOCALAPPDATA%
. - If
user ()
isOk home
,Fpath.(home / ".config")
.
data ()
is the directory used to store user-specific program data. This is in order:
- If set the value of
XDG_DATA_HOME
. - If set and on Windows® the value of
%LOCALAPPDATA%
. - If
user ()
isOk home
,Fpath.(home / ".local" / "share")
.
cache ()
is the directory used to store user-specific non-essential data. This is in order:
- If set the value of
XDG_CACHE_HOME
. - If set and on Windows® the value of
%TEMP%
- If
user ()
isOk home
,Fpath.(home / ".cache")
runtime ()
is the directory used to store user-specific runtime files. This is in order:
- If set the value of
XDG_RUNTIME_HOME
. - The value of
default_tmp
.