Platform agnostic representation of POSIX ::lstat() and ::stat() for a given pathname. More...

#include <file_util.hpp>

Collaboration diagram for jau::fs::file_stats:

Public Types
enum class	field_t : uint32_t { none = 0 , type = 0b0000000000000001 , mode = 0b0000000000000010 , nlink = 0b0000000000000100 , uid = 0b0000000000001000 , gid = 0b0000000000010000 , atime = 0b0000000000100000 , mtime = 0b0000000001000000 , ctime = 0b0000000010000000 , ino = 0b0000000100000000 , size = 0b0000001000000000 , blocks = 0b0000010000000000 , btime = 0b0000100000000000 , fd = 0b0001000000000000 }
	Field identifier which bit-mask indicates field_t fields. More...

typedef uint32_t	gid_t

typedef uint32_t	uid_t

Public Member Functions
	file_stats () noexcept
	Instantiate an empty file_stats with fmode_t::not_existing set. More...

	file_stats (const ctor_cookie &cc, int dirfd, const dir_item &item, const bool dirfd_is_item_dirname) noexcept
	Private ctor for private make_shared<file_stats>() intended for friends. More...

	file_stats (const dir_item &item) noexcept
	Instantiates a file_stats for the given dir_item. More...

	file_stats (const int dirfd, const dir_item &item, const bool dirfd_is_item_dirname=true) noexcept
	Instantiates a file_stats for the given dir_item. More...

	file_stats (const int dirfd, const std::string &path) noexcept
	Instantiates a file_stats for the given `path`. More...

	file_stats (const int fd) noexcept
	Instantiates a file_stats for the given `fd` file descriptor. More...

	file_stats (const std::string &path) noexcept
	Instantiates a file_stats for the given `path`. More...

const fraction_timespec &	atime () const noexcept
	Returns the last access time of this element since Unix Epoch. More...

const fraction_timespec &	btime () const noexcept
	Returns the birth time of this element since Unix Epoch, i.e. More...

const fraction_timespec &	ctime () const noexcept
	Returns the last status change time of this element since Unix Epoch. More...

constexpr int	errno_res () const noexcept
	Returns the `errno` value occurred to produce this instance, or zero for no error. More...

constexpr bool	exists () const noexcept
	Returns true if entity does not exist, exclusive bit. More...

int	fd () const noexcept
	Returns the file descriptor if has_fd(), otherwise -1 for no file descriptor. More...

constexpr field_t	fields () const noexcept
	Returns the retrieved field_t fields. More...

const file_stats *	final_target (size_t *link_count=nullptr) const noexcept
	Returns the final target element, either a pointer to this instance if not a symbolic-link or the final link-target a symbolic-link (chain) points to. More...

gid_t	gid () const noexcept
	Returns the group id, owning the element. More...

bool	has (const field_t fields) const noexcept
	Returns true if the given field_t fields were retrieved, otherwise false. More...

constexpr bool	has_access () const noexcept
	Returns true if entity gives no access to user, exclusive bit. More...

constexpr bool	has_fd () const noexcept
	Returns true if entity has a file descriptor. More...

constexpr bool	is_block () const noexcept
	Returns true if entity is a block device, might be in combination with is_link(). More...

constexpr bool	is_char () const noexcept
	Returns true if entity is a character device, might be in combination with is_link(). More...

constexpr bool	is_dir () const noexcept
	Returns true if entity is a directory, might be in combination with is_link(). More...

constexpr bool	is_fifo () const noexcept
	Returns true if entity is a fifo/pipe, might be in combination with is_link(). More...

constexpr bool	is_file () const noexcept
	Returns true if entity is a file, might be in combination with is_link(). More...

constexpr bool	is_link () const noexcept
	Returns true if entity is a symbolic link, might be in combination with is_file(), is_dir(), is_fifo(), is_char(), is_block(), is_socket(). More...

constexpr bool	is_socket () const noexcept
	Returns true if entity is a socket, might be in combination with is_link(). More...

const dir_item &	item () const noexcept
	Returns the dir_item. More...

const std::shared_ptr< file_stats > &	link_target () const noexcept
	Returns the link-target this symbolic-link points to if instance is a symbolic-link, otherwise nullptr. More...

const std::shared_ptr< std::string > &	link_target_path () const noexcept
	Returns the stored link-target path this symbolic-link points to if instance is a symbolic-link, otherwise nullptr. More...

fmode_t	mode () const noexcept
	Returns the fmode_t, file type and mode. More...

const fraction_timespec &	mtime () const noexcept
	Returns the last modification time of this element since Unix Epoch. More...

constexpr bool	ok () const noexcept
	Returns true if no error occurred. More...

bool	operator!= (const file_stats &rhs) const noexcept

bool	operator== (const file_stats &rhs) const noexcept

std::string	path () const noexcept
	Returns the unix path representation. More...

fmode_t	prot_mode () const noexcept
	Returns the POSIX protection bit portion of fmode_t, i.e. More...

uint64_t	size () const noexcept
	Returns the size in bytes of this element if is_file(), otherwise zero. More...

std::string	to_string () const noexcept
	Returns a comprehensive string representation of this element. More...

fmode_t	type_mode () const noexcept
	Returns the type bit portion of fmode_t, i.e. More...

uid_t	uid () const noexcept
	Returns the user id, owning the element. More...

Detailed Description

Platform agnostic representation of POSIX ::lstat() and ::stat() for a given pathname.

Implementation follows the symbolic link, i.e. first opens the given pathname with ::lstat() and if identifying as a symbolic link opens it via ::stat() to retrieve the actual properties like size, time and ownership.

Implementation supports named file descriptor, see is_fd().

On GNU/Linux implementation uses ::statx().

Definition at line 406 of file file_util.hpp.

Member Typedef Documentation

◆ uid_t

typedef uint32_t jau::fs::file_stats::uid_t

Definition at line 431 of file file_util.hpp.

◆ gid_t

typedef uint32_t jau::fs::file_stats::gid_t

Definition at line 432 of file file_util.hpp.

Member Enumeration Documentation

◆ field_t

enum class jau::fs::file_stats::field_t : uint32_t

strong

Field identifier which bit-mask indicates field_t fields.

Enumerator
none	No mode bit set.
type	File type mode bits.
mode	POSIX file protection mode bits.
nlink
uid
gid
atime
mtime
ctime
ino
size
blocks
btime
fd

Definition at line 411 of file file_util.hpp.

Constructor & Destructor Documentation

◆ file_stats() [1/7]

file_stats::file_stats ( )

noexcept

Instantiate an empty file_stats with fmode_t::not_existing set.

Definition at line 444 of file file_util.cpp.

◆ file_stats() [2/7]

file_stats::file_stats	(	const ctor_cookie &	cc,
		int	dirfd,
		const dir_item &	item,
		const bool	dirfd_is_item_dirname
	)

noexcept

Private ctor for private make_shared<file_stats>() intended for friends.

Definition at line 454 of file file_util.cpp.

◆ file_stats() [3/7]

file_stats::file_stats ( const std::string & path )

noexcept

Instantiates a file_stats for the given path.

The dir_item will be constructed without parent_dir

Parameters

path	the path to produce stats for

Definition at line 807 of file file_util.cpp.

◆ file_stats() [4/7]

file_stats::file_stats	(	const int	dirfd,
		const std::string &	path
	)

noexcept

Instantiates a file_stats for the given path.

The dir_item will be constructed without parent_dir

Parameters

dirfd	file descriptor of given dir_item item's directory, dir_item::dirname(), or AT_FDCWD for the current working directory of the calling process
path	the path to produce stats for

Definition at line 811 of file file_util.cpp.

◆ file_stats() [5/7]

file_stats::file_stats ( const dir_item & item )

noexcept

Instantiates a file_stats for the given dir_item.

Parameters

item	the dir_item to produce stats for

Definition at line 799 of file file_util.cpp.

◆ file_stats() [6/7]

file_stats::file_stats	(	const int	dirfd,
		const dir_item &	item,
		const bool	dirfd_is_item_dirname = `true`
	)

noexcept

Instantiates a file_stats for the given dir_item.

Parameters

dirfd	file descriptor of given dir_item item's directory, dir_item::dirname(), or AT_FDCWD for the current working directory of the calling process
item	the dir_item to produce stats for
dirfd_is_item_dirname	if true, dir_item::basename() is relative to dirfd (default), otherwise full dir_item::path() is relative to dirfd.

Definition at line 803 of file file_util.cpp.

◆ file_stats() [7/7]

file_stats::file_stats ( const int fd )

noexcept

Instantiates a file_stats for the given fd file descriptor.

Parameters

fd	file descriptor of an opened file

Definition at line 815 of file file_util.cpp.

Member Function Documentation

◆ item()

const dir_item & jau::fs::file_stats::item ( ) const

inlinenoexcept

Returns the dir_item.

In case this instance is created by following a symbolic link instance, it represents the resolved path relative to the used symbolic link's dirname.

See also: is_link(); path()

Definition at line 519 of file file_util.hpp.

Here is the caller graph for this function:

◆ path()

std::string jau::fs::file_stats::path ( ) const

inlinenoexcept

Returns the unix path representation.

In case this instance is created by following a symbolic link instance, it represents the resolved path relative to the used symbolic link's dirname.

See also: is_link(); item()

Definition at line 530 of file file_util.hpp.

Here is the caller graph for this function:

◆ link_target_path()

const std::shared_ptr< std::string > & jau::fs::file_stats::link_target_path ( ) const

inlinenoexcept

Returns the stored link-target path this symbolic-link points to if instance is a symbolic-link, otherwise nullptr.

See also: is_link(); link_target(); final_target()

Definition at line 539 of file file_util.hpp.

Here is the caller graph for this function:

◆ link_target()

const std::shared_ptr< file_stats > & jau::fs::file_stats::link_target ( ) const

inlinenoexcept

Returns the link-target this symbolic-link points to if instance is a symbolic-link, otherwise nullptr.

nullptr is also returned for an erroneous symbolic-links, i.e. non-existing link-targets or recursive loop-errors.

See also: is_link(); link_target_path(); final_target()

Definition at line 550 of file file_util.hpp.

Here is the caller graph for this function:

◆ final_target()

const file_stats * file_stats::final_target ( size_t * link_count = nullptr ) const

noexcept

Returns the final target element, either a pointer to this instance if not a symbolic-link or the final link-target a symbolic-link (chain) points to.

Parameters

link_count optional size_t pointer to store the number of symbolic links leading to the final target, excluding the final instance. 0 indicates no symbolic-link;

See also: is_link(); link_target_path(); link_target()

Definition at line 819 of file file_util.cpp.

Here is the caller graph for this function:

◆ has()

bool file_stats::has ( const field_t fields ) const

noexcept

Returns true if the given field_t fields were retrieved, otherwise false.

Definition at line 834 of file file_util.cpp.

Here is the caller graph for this function:

◆ fields()

constexpr field_t jau::fs::file_stats::fields ( ) const

inlineconstexprnoexcept

Returns the retrieved field_t fields.

Definition at line 568 of file file_util.hpp.

Here is the caller graph for this function:

◆ mode()

fmode_t jau::fs::file_stats::mode ( ) const

inlinenoexcept

Returns the fmode_t, file type and mode.

Definition at line 571 of file file_util.hpp.

Here is the caller graph for this function:

◆ prot_mode()

fmode_t jau::fs::file_stats::prot_mode ( ) const

inlinenoexcept

Returns the POSIX protection bit portion of fmode_t, i.e.

mode() & fmode_t::protection_mask.

Definition at line 574 of file file_util.hpp.

Here is the caller graph for this function:

◆ type_mode()

fmode_t jau::fs::file_stats::type_mode ( ) const

inlinenoexcept

Returns the type bit portion of fmode_t, i.e.

mode() & fmode_t::type_mask.

Definition at line 577 of file file_util.hpp.

Here is the caller graph for this function:

◆ fd()

int jau::fs::file_stats::fd ( ) const

inlinenoexcept

Returns the file descriptor if has_fd(), otherwise -1 for no file descriptor.

See also: has_fd()

Definition at line 584 of file file_util.hpp.

Here is the caller graph for this function:

◆ uid()

uid_t jau::fs::file_stats::uid ( ) const

inlinenoexcept

Returns the user id, owning the element.

Definition at line 587 of file file_util.hpp.

Here is the caller graph for this function:

◆ gid()

gid_t jau::fs::file_stats::gid ( ) const

inlinenoexcept

Returns the group id, owning the element.

Definition at line 590 of file file_util.hpp.

Here is the caller graph for this function:

◆ size()

uint64_t jau::fs::file_stats::size ( ) const

inlinenoexcept

Returns the size in bytes of this element if is_file(), otherwise zero.

If the element also is_link(), the linked target size is returned.

Definition at line 597 of file file_util.hpp.

Here is the caller graph for this function:

◆ btime()

const fraction_timespec & jau::fs::file_stats::btime ( ) const

inlinenoexcept

Returns the birth time of this element since Unix Epoch, i.e.

its creation time.

Definition at line 600 of file file_util.hpp.

Here is the caller graph for this function:

◆ atime()

const fraction_timespec & jau::fs::file_stats::atime ( ) const

inlinenoexcept

Returns the last access time of this element since Unix Epoch.

Definition at line 602 of file file_util.hpp.

Here is the caller graph for this function:

◆ ctime()

const fraction_timespec & jau::fs::file_stats::ctime ( ) const

inlinenoexcept

Returns the last status change time of this element since Unix Epoch.

Definition at line 604 of file file_util.hpp.

◆ mtime()

const fraction_timespec & jau::fs::file_stats::mtime ( ) const

inlinenoexcept

Returns the last modification time of this element since Unix Epoch.

Definition at line 606 of file file_util.hpp.

Here is the caller graph for this function:

◆ errno_res()

constexpr int jau::fs::file_stats::errno_res ( ) const

inlineconstexprnoexcept

Returns the errno value occurred to produce this instance, or zero for no error.

Definition at line 609 of file file_util.hpp.

◆ ok()

constexpr bool jau::fs::file_stats::ok ( ) const

inlineconstexprnoexcept

Returns true if no error occurred.

Definition at line 612 of file file_util.hpp.

Here is the caller graph for this function:

◆ has_fd()

constexpr bool jau::fs::file_stats::has_fd ( ) const

inlineconstexprnoexcept

Returns true if entity has a file descriptor.

See also: fd(); jau::fs::from_named_fd(); jau::fs::to_named_fd()

Definition at line 621 of file file_util.hpp.

Here is the caller graph for this function:

◆ is_socket()

constexpr bool jau::fs::file_stats::is_socket ( ) const

inlineconstexprnoexcept

Returns true if entity is a socket, might be in combination with is_link().

Definition at line 624 of file file_util.hpp.

Here is the caller graph for this function:

◆ is_block()

constexpr bool jau::fs::file_stats::is_block ( ) const

inlineconstexprnoexcept

Returns true if entity is a block device, might be in combination with is_link().

Definition at line 627 of file file_util.hpp.

Here is the caller graph for this function:

◆ is_char()

constexpr bool jau::fs::file_stats::is_char ( ) const

inlineconstexprnoexcept

Returns true if entity is a character device, might be in combination with is_link().

Definition at line 630 of file file_util.hpp.

Here is the caller graph for this function:

◆ is_fifo()

constexpr bool jau::fs::file_stats::is_fifo ( ) const

inlineconstexprnoexcept

Returns true if entity is a fifo/pipe, might be in combination with is_link().

Definition at line 633 of file file_util.hpp.

Here is the caller graph for this function:

◆ is_dir()

constexpr bool jau::fs::file_stats::is_dir ( ) const

inlineconstexprnoexcept

Returns true if entity is a directory, might be in combination with is_link().

Definition at line 636 of file file_util.hpp.

Here is the caller graph for this function:

◆ is_file()

constexpr bool jau::fs::file_stats::is_file ( ) const

inlineconstexprnoexcept

Returns true if entity is a file, might be in combination with is_link().

Definition at line 639 of file file_util.hpp.

Here is the caller graph for this function:

◆ is_link()

constexpr bool jau::fs::file_stats::is_link ( ) const

inlineconstexprnoexcept

Returns true if entity is a symbolic link, might be in combination with is_file(), is_dir(), is_fifo(), is_char(), is_block(), is_socket().

Definition at line 642 of file file_util.hpp.

Here is the caller graph for this function:

◆ has_access()

constexpr bool jau::fs::file_stats::has_access ( ) const

inlineconstexprnoexcept

Returns true if entity gives no access to user, exclusive bit.

Definition at line 645 of file file_util.hpp.

Here is the caller graph for this function:

◆ exists()

constexpr bool jau::fs::file_stats::exists ( ) const

inlineconstexprnoexcept

Returns true if entity does not exist, exclusive bit.

Definition at line 648 of file file_util.hpp.

Here is the caller graph for this function:

◆ operator==()

bool file_stats::operator== ( const file_stats & rhs ) const

noexcept

Definition at line 838 of file file_util.cpp.

◆ operator!=()

bool jau::fs::file_stats::operator!= ( const file_stats & rhs ) const

inlinenoexcept

Definition at line 652 of file file_util.hpp.

◆ to_string()

std::string file_stats::to_string ( ) const

noexcept

Returns a comprehensive string representation of this element.

Definition at line 859 of file file_util.cpp.

Here is the caller graph for this function:

The documentation for this class was generated from the following files:

jaulib/include/jau/file_util.hpp
jaulib/src/file_util.cpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ uid_t

◆ gid_t

Member Enumeration Documentation

◆ field_t

Constructor & Destructor Documentation

◆ file_stats() [1/7]

◆ file_stats() [2/7]

◆ file_stats() [3/7]

◆ file_stats() [4/7]

◆ file_stats() [5/7]

◆ file_stats() [6/7]

◆ file_stats() [7/7]

Member Function Documentation

◆ item()

◆ path()

◆ link_target_path()

◆ link_target()

◆ final_target()

◆ has()

◆ fields()

◆ mode()

◆ prot_mode()

◆ type_mode()

◆ fd()

◆ uid()

◆ gid()

◆ size()

◆ btime()

◆ atime()

◆ ctime()

◆ mtime()

◆ errno_res()

◆ ok()

◆ has_fd()

◆ is_socket()

◆ is_block()

◆ is_char()

◆ is_fifo()

◆ is_dir()

◆ is_file()

◆ is_link()

◆ has_access()

◆ exists()

◆ operator==()

◆ operator!=()

◆ to_string()