Direct-BT v3.3.0-1-gc2d430c
Direct-BT - Direct Bluetooth Programming.
Classes | Public Types | Public Member Functions | List of all members
jau::fs::file_stats Class Reference

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_timespecatime () const noexcept
 Returns the last access time of this element since Unix Epoch. More...
 
const fraction_timespecbtime () const noexcept
 Returns the birth time of this element since Unix Epoch, i.e. More...
 
const fraction_timespecctime () 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_statsfinal_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_itemitem () 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_timespecmtime () 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
paththe 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
dirfdfile descriptor of given dir_item item's directory, dir_item::dirname(), or AT_FDCWD for the current working directory of the calling process
paththe 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
itemthe 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
dirfdfile descriptor of given dir_item item's directory, dir_item::dirname(), or AT_FDCWD for the current working directory of the calling process
itemthe dir_item to produce stats for
dirfd_is_item_dirnameif 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
fdfile 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_countoptional 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: