Struct openat_ct::Dir [−][src]
pub struct Dir(_);
Expand description
A safe wrapper around directory file descriptor
Construct it either with Dir::cwd()
or Dir::open(path)
Implementations
👎 Deprecated since 0.1.15: Use Dir::open(".")
instead. Dir::cwd() doesn’t open actual file descriptor and uses magic value instead which resolves to current dir on any syscall invocation. This is usually counter-intuitive and yields a broken file descriptor when using Dir::as_raw_fd
. Will be removed in version v0.2 of the library.
Use Dir::open(".")
instead. Dir::cwd() doesn’t open actual file descriptor and uses magic value instead which resolves to current dir on any syscall invocation. This is usually counter-intuitive and yields a broken file descriptor when using Dir::as_raw_fd
. Will be removed in version v0.2 of the library.
Creates a directory descriptor that resolves paths relative to current working directory (AT_FDCWD)
Create a flags builder for Dir objects. Initial flags default to `O_CLOEXEC’. More flags can be set added by ‘with()’ and existing/default flags can be removed by ‘without()’. The flags builder can the be used to ‘open()’ to create a Dir handle.
Open a directory descriptor at specified path with O_PATH when available. A descriptor obtained with this flag is restricted to do only certain operations:
- It may be used as anchor for opening sub-objects
- One can query metadata of this directory
This handle is not suitable for a ‘Dir::list()’ call and may yield a runtime error. Use ‘Dir::flags().open()’ to get a handle without O_PATH defined or use ‘Dir::list_self()’ which clone-upgrades the handle it used for the iteration.
Checks if the fd associated with the Dir object is really a directory. There are subtle differences in how directories can be opened and what properties the resulting file handles have. On some platforms it is possible that Dir::open(“somefile”) succeeds. This will usually raise errors later when one tries to do Directory operations on this. While checking if such an handle comes with cost of a potential expensive ‘stat()’ operation. This library makes the assumption that in the ‘usual’ case Dir objects are only created on directories and operations on Dir handles handle errors properly. Still in some cases one may check a freshly created handle explicitly. Thats what ‘is_dir()’ is for. Returns ‘true’ when the underlying handles represents a directory and false otherwise.
List subdirectory of this dir
You can list directory itself with list_self
.
Create a DirIter from a Dir Dir must not be a handle opened with O_PATH.
Create a flags builder for member methods. Defaults to O_CLOEXEC | O_NOFOLLOW
plus
the given flags. Further flags can be added/removed by the ‘with()’/‘without()’
members. And finally be used by ‘sub_dir()’ and the different ‘open()’ calls.
Create a flags builder for member methods. Defaults to O_CLOEXEC | O_NOFOLLOW
with
the given flags (which may O_CLOEXEC or O_NOFOLLOW) removed. Further flags can be
added/removed by the ‘with()’/‘without()’ members. And finally be used by ‘sub_dir()’
and the different ‘open()’ calls.
Open subdirectory with O_PATH when available. A descriptor obtained with this flag is restricted to do only certain operations:
- It may be used as anchor for opening sub-objects
- One can query metadata of this directory
This handle is not suitable for a ‘Dir::list()’ call and may yield a runtime error. Use ‘Dir::with(0).sub_dir()’ to get a handle without O_PATH defined or use ‘Dir::list_dir()’ which clone-upgrades the handle it used for the iteration.
Note that this method does not resolve symlinks by default, so you may have to call
read_link
to resolve the real path first or create a handle
‘without(libc::O_NOFOLLOW)’.
Open file for reading in this directory
Note that this method does not resolve symlinks by default, so you may have to call
read_link
to resolve the real path first.
Open file for writing, create if necessary, truncate on open
If there exists a symlink at the destination path, this method will fail. In that case, you
will need to remove the symlink before calling this method. If you are on Linux, you can
alternatively create an unnamed file with new_unnamed_file
and then rename it,
clobbering the symlink at the destination.
Open file for append, create if necessary
If there exists a symlink at the destination path, this method will fail. In that case, you
will need to call read_link
to resolve the real path first.
👎 Deprecated since 0.1.7: please use write_file
instead
please use write_file
instead
Create file for writing (and truncate) in this directory
Deprecated alias for write_file
If there exists a symlink at the destination path, this method will fail. In that case, you
will need to remove the symlink before calling this method. If you are on Linux, you can
alternatively create an unnamed file with new_unnamed_file
and then rename it,
clobbering the symlink at the destination.
Create a tmpfile in this directory which isn’t linked to any filename
This works by passing O_TMPFILE
into the openat call. The flag is
supported only on linux. So this function always returns error on
such systems.
WARNING! On glibc < 2.22 file permissions of the newly created file may be arbitrary. Consider chowning after creating a file.
Note: It may be unclear why creating unnamed file requires a dir. There are two reasons:
- It’s created (and occupies space) on a real filesystem, so the directory is a way to find out which filesystem to attach file to
- This method is mostly needed to initialize the file then link it
using
link_file_at
to the real directory entry. When linking it must be linked into the same filesystem. But because for most programs finding out filesystem layout is an overkill the rule of thumb is to create a file in the the target directory.
Currently, we recommend to fallback on any error if this operation can’t be accomplished rather than relying on specific error codes, because semantics of errors are very ugly.
Link open file to a specified path
This is used with new_unnamed_file()
to create and initialize the
file before linking it into a filesystem. This requires /proc
to be
mounted and works only on linux.
On systems other than linux this always returns error. It’s expected
that in most cases this methos is not called if new_unnamed_file
fails. But in obscure scenarios where /proc
is not mounted this
method may fail even on linux. So your code should be able to fallback
to a named file if this method fails too.
Create file if not exists, fail if exists
This function checks existence and creates file atomically with respect to other threads and processes.
Technically it means passing O_EXCL
flag to open.
Open file for reading and writing without truncation, create if needed
If there exists a symlink at the destination path, this method will fail. In that case, you
will need to call read_link
to resolve the real path first.
Make a symlink in this directory
Note: the order of arguments differ from symlinkat
Create a subdirectory in this directory
Rename a file in this directory to another name (keeping same dir)
Similar to local_rename
but atomically swaps both paths
Only supported on Linux.
Remove a subdirectory in this directory
Note only empty directory may be removed
Remove a file in this directory
Get the path of this directory (if possible)
This uses symlinks in /proc/self
, they sometimes may not be
available so use with care.
Returns metadata of an entry in this directory
If the destination path is a symlink, this will return the metadata of the symlink itself.
If you would like to follow the symlink and return the metadata of the target, you will
have to call read_link
to resolve the real path first.
Returns the metadata of the directory itself.
Constructs a new Dir
from a given raw file descriptor,
ensuring it is a directory file descriptor first.
This function consumes ownership of the specified file
descriptor. The returned Dir
will take responsibility for
closing it when it goes out of scope.
Creates a new independently owned handle to the underlying directory. The new handle has the same (Normal/O_PATH) semantics as the original handle.
Creates a new ‘Normal’ independently owned handle to the underlying directory.
Creates a new ‘O_PATH’ restricted independently owned handle to the underlying directory.
Trait Implementations
The user must guarantee that the passed in RawFd
is in fact
a directory file descriptor.