Obtain and access file status information. More...

#include <FileStatus.hxx>

Public Member Functions
	FileStatus (const SysString path, const FollowSymlinks follow=FollowSymlinks{false})

	FileStatus (const FileDescriptor fd)

	FileStatus (const DirFD fd, const SysString path, const FollowSymlinks follow=FollowSymlinks{false})

void	updateFrom (const SysString path, const FollowSymlinks follow=FollowSymlinks{false})
	Obtains stat data for the file object at the given path (stat, lstat).

void	updateFrom (const FileDescriptor fd)
	Obtains stat data for the file object represented by the given FD (fstat).

void	updateFrom (const DirFD fd, const SysString path, const FollowSymlinks follow=FollowSymlinks{false})
	Obtains stat data for the `path` relative to `fd`.

void	reset ()

bool	valid () const

ModeT	rawMode () const
	Returns the composite ModeT for the file.

FileMode	mode () const
	Returns the file mode bitmask containing the permission bits for the file.

FileType	type () const
	Returns the FileType representation for the file.

DeviceID	device () const
	Returns the identifier for the block device this file resides on.

Inode	inode () const
	Returns the unique file inode for the file.

nlink_t	numLinks () const
	Returns the number of hard links for this file.

UserID	uid () const
	Returns the UID of the owner of the file.

GroupID	gid () const
	Returns the GID of the owner of the file.

off_t	size () const
	Returns the size of the file in bytes.

DeviceID	representedDevice () const
	Returns the identifier of the device this file represents.

blksize_t	blockSize () const
	Preferred block size for file system I/O.

blkcnt_t	allocatedBlocks () const
	Returns the number of blocks in 512 byte units allocated to the file.

const RealTime &	modTime () const
	Returns the time of the last modification of the file content.

const RealTime &	statusTime () const
	Returns the time of the last status (inode) modification.

const RealTime &	accessTime () const
	Returns the time of the last (read) access of the file content.

bool	isSameFile (const FileStatus &other) const
	Returns whether the two FileStatus objects refer to the same file.

bool	operator== (const FileStatus &other)
	Compares the two objects on raw data level.

bool	operator!= (const FileStatus &other)

Protected Member Functions
void	throwBadType (const std::string_view context) const

Protected Attributes
struct stat	m_st

Detailed Description

Obtain and access file status information.

The file status contains metadata information about a file object at a certain point in time. The information can be looked up either by path or directly from an already opened file descriptor.

The latter is the preferred method if you have to open the file anyway since it is race-free. Otherwise the file you obtained the status from and the file you're opening might end up referring to two different objects if the files on disk are changed (e.g. by an attacker). The file descriptor method is also faster, since the path doesn't have to be parsed and followed once again.

Definition at line 34 of file FileStatus.hxx.

Constructor & Destructor Documentation

◆ FileStatus() [1/4]

cosmos::FileStatus::FileStatus ( )

inline

Definition at line 37 of file FileStatus.hxx.

                     {
                reset();
        }

◆ FileStatus() [2/4]

cosmos::FileStatus::FileStatus	(	const SysString	path,
		const FollowSymlinks	follow = FollowSymlinks{false} )

inlineexplicit

Definition at line 41 of file FileStatus.hxx.

                                                                                              {false}) {
                updateFrom(path, follow);
        }

◆ FileStatus() [3/4]

cosmos::FileStatus::FileStatus ( const FileDescriptor fd )

inlineexplicit

Definition at line 45 of file FileStatus.hxx.

                                                     {
                updateFrom(fd);
        }

◆ FileStatus() [4/4]

cosmos::FileStatus::FileStatus	(	const DirFD	fd,
		const SysString	path,
		const FollowSymlinks	follow = FollowSymlinks{false} )

inlineexplicit

Definition at line 49 of file FileStatus.hxx.

                                                                                                              {false}) {
                updateFrom(fd, path, follow);
        }

Member Function Documentation

◆ accessTime()

const RealTime & cosmos::FileStatus::accessTime ( ) const

inline

Returns the time of the last (read) access of the file content.

This timestamp may not be available on all file systems or in all circumstances, for example there is mount option noatime that disables this for performance reasons.

Definition at line 228 of file FileStatus.hxx.

                                           {
                return *reinterpret_cast<const RealTime*>(&m_st.st_atim);
        }

◆ allocatedBlocks()

blkcnt_t cosmos::FileStatus::allocatedBlocks ( ) const

inline

Returns the number of blocks in 512 byte units allocated to the file.

This can be smaller than the result of size() / 512 if the file has holes in it.

Definition at line 196 of file FileStatus.hxx.

                                         {
                return m_st.st_blocks;
        }

◆ blockSize()

blksize_t cosmos::FileStatus::blockSize ( ) const

inline

Preferred block size for file system I/O.

This returns the optimal size for individual read and write operations on this file system with regards to performance. The value can theoretically be different for different files on the same file system.

Definition at line 187 of file FileStatus.hxx.

                                    {
                return m_st.st_blksize;
        }

◆ device()

DeviceID cosmos::FileStatus::device ( ) const

inline

Returns the identifier for the block device this file resides on.

Definition at line 117 of file FileStatus.hxx.

                                {
                return DeviceID{m_st.st_dev};
        }

◆ gid()

GroupID cosmos::FileStatus::gid ( ) const

inline

Returns the GID of the owner of the file.

Definition at line 142 of file FileStatus.hxx.

                            {
                return GroupID{m_st.st_gid};
        }

◆ inode()

Inode cosmos::FileStatus::inode ( ) const

inline

Returns the unique file inode for the file.

The pair of data device() and inode() allow to uniquely identifier a file on the system. For example this allows to detect hard links to the same file data.

Definition at line 127 of file FileStatus.hxx.

                            {
                return Inode{m_st.st_ino};
        }

◆ isSameFile()

bool cosmos::FileStatus::isSameFile ( const FileStatus & other ) const

inline

Returns whether the two FileStatus objects refer to the same file.

This condition is true if both the inodes and the block device IDs for both FileStatus objects match. Note that files can be identical even if the file names aren't (hard links).

Definition at line 238 of file FileStatus.hxx.

                                                       {
                return this->inode() == other.inode() &&
                        this->device() == other.device();
        }

◆ mode()

FileMode cosmos::FileStatus::mode ( ) const

inline

Returns the file mode bitmask containing the permission bits for the file.

Definition at line 107 of file FileStatus.hxx.

                              {
                return FileMode{rawMode()};
        }

◆ modTime()

const RealTime & cosmos::FileStatus::modTime ( ) const

inline

Returns the time of the last modification of the file content.

Definition at line 204 of file FileStatus.hxx.

                                        {
                // This is a bit dirty, casting the struct timespec to its
                // wrapper type. Should work as long as we don't change the
                // object size (is checked in the compilation unit for
                // TimeSpec). This saves us some copying since struct timespec
                // is 16 bytes in size.
                return *reinterpret_cast<const RealTime*>(&m_st.st_mtim);
        }

◆ numLinks()

nlink_t cosmos::FileStatus::numLinks ( ) const

inline

Returns the number of hard links for this file.

Definition at line 132 of file FileStatus.hxx.

                                 {
                return m_st.st_nlink;
        }

◆ operator!=()

bool cosmos::FileStatus::operator!= ( const FileStatus & other )

inline

Definition at line 253 of file FileStatus.hxx.

                                                 {
                return !(*this == other);
        }

◆ operator==()

bool cosmos::FileStatus::operator== ( const FileStatus & other )

inline

Compares the two objects on raw data level.

All file status fields need to be equal for this to match. To compare file objects on a logical level (i.e. if they refer to the same file system object) use isSameFile().

Definition at line 249 of file FileStatus.hxx.

                                                 {
                return std::memcmp(&m_st, &other.m_st, sizeof(m_st)) == 0;
        }

◆ rawMode()

ModeT cosmos::FileStatus::rawMode ( ) const

inline

Returns the composite ModeT for the file.

Definition at line 102 of file FileStatus.hxx.

                              {
                return ModeT{m_st.st_mode};
        }

◆ representedDevice()

DeviceID cosmos::FileStatus::representedDevice ( ) const

Returns the identifier of the device this file represents.

This is only valid if

    type() == FileType::BLOCKDEV || type() == FileType::CHARDEV

If this condition is not fulfilled then a UsageError is thrown.

Definition at line 40 of file FileStatus.cxx.

                                             {
        switch (type().raw()) {
                case FileType::BLOCKDEV:
                case FileType::CHARDEV:
                        return DeviceID{m_st.st_rdev};
                default:
                        throwBadType("attempted to get st_rdev but this is no dev!");
                        return DeviceID{0};
        }
}

◆ reset()

void cosmos::FileStatus::reset ( )

inline

Definition at line 90 of file FileStatus.hxx.

                     {
                // we identify an invalid stat structure by clearing the mode
                // field only. Due to the file type bits it should never be
                // zero for any valid struct stat.
                m_st.st_mode = 0;
        }

◆ size()

off_t cosmos::FileStatus::size ( ) const

inline

Returns the size of the file in bytes.

The size only has meaning for the following file types:

REGULAR: net size of the file in bytes
LINK: number of characters in the symlink, excluding '\0' terminator
DIRECTORY: the size the directory entries uses (depends on file system internal details, does not include sizes of contained files).

For any other type a UsageError exception is thrown.

Definition at line 158 of file FileStatus.hxx.

                           {
                switch (type().raw()) {
                        case FileType::REGULAR:
                        case FileType::LINK:
                        case FileType::DIRECTORY:
                                return m_st.st_size;
                        default:
                                throwBadType("invalid type for st_size");
                                return 0;
                }
        };

◆ statusTime()

const RealTime & cosmos::FileStatus::statusTime ( ) const

inline

Returns the time of the last status (inode) modification.

This timestamp reflects the last change to the inode data i.e. the metadata of the file (e.g. ownership, permissions etc.)

Definition at line 218 of file FileStatus.hxx.

                                           {
                return *reinterpret_cast<const RealTime*>(&m_st.st_ctim);
        }

◆ throwBadType()

void cosmos::FileStatus::throwBadType ( const std::string_view context ) const

protected

Definition at line 13 of file FileStatus.cxx.

                                                                {
        cosmos_throw (UsageError(context));
}

◆ type()

FileType cosmos::FileStatus::type ( ) const

inline

Returns the FileType representation for the file.

Definition at line 112 of file FileStatus.hxx.

                              {
                return FileType{rawMode()};
        }

◆ uid()

UserID cosmos::FileStatus::uid ( ) const

inline

Returns the UID of the owner of the file.

Definition at line 137 of file FileStatus.hxx.

                           {
                return UserID{m_st.st_uid};
        }

◆ updateFrom() [1/3]

void cosmos::FileStatus::updateFrom	(	const DirFD	fd,
		const SysString	path,
		const FollowSymlinks	follow = FollowSymlinks{false} )

Obtains stat data for the path relative to fd.

If path is an absolute path then this behaves like updateFrom(const SysString, const FollowSymlinks) and fd is ignored.

If path is relative then it will be looked up relative to the given dir fd. You can pass cosmos::AT_CWD as fd to lookup path relative to the current working directory.

If path is an empty string then this behaves similar to updateFrom(const FileDescriptor) and fd can be any type of file descriptor (but this usage is not encouraged due to libcosmos' type modeling).

Definition at line 31 of file FileStatus.cxx.

                                                                                             {
 
        auto res = ::fstatat(to_integral(fd.raw()), path.raw(), &m_st, follow ? 0 : AT_SYMLINK_NOFOLLOW);
 
        if (res != 0) {
                cosmos_throw (FileError(path, "fstatat()"));
        }
}

◆ updateFrom() [2/3]

void cosmos::FileStatus::updateFrom ( const FileDescriptor fd )

Obtains stat data for the file object represented by the given FD (fstat).

On error an ApiError exception is thrown. Typical errors are like in updateFrom(const SysString, const FollowSymlinks), with the following addition:

Errno::BAD_FD: file descriptor is invalid

Definition at line 17 of file FileStatus.cxx.

                                                   {
        if (fstat(to_integral(fd.raw()), &m_st) != 0) {
                cosmos_throw (ApiError("fstat()"));
        }
}

◆ updateFrom() [3/3]

void cosmos::FileStatus::updateFrom	(	const SysString	path,
		const FollowSymlinks	follow = FollowSymlinks{false} )

Obtains stat data for the file object at the given path (stat, lstat).

On error an ApiError exception is thrown. Typical errors are:

Errno::NO_ENTRY: file doesn't exist
Errno::ACCESS: access denied
Errno::NO_MEMORY: out of memory

Definition at line 23 of file FileStatus.cxx.

                                                                             {
        auto statfunc = follow ? ::stat : ::lstat;
 
        if (statfunc(path.raw(), &m_st) != 0) {
                cosmos_throw (FileError(path, follow ? "stat" : "lstat"));
        }
}

◆ valid()

bool cosmos::FileStatus::valid ( ) const

inline

Definition at line 97 of file FileStatus.hxx.

                           {
                return m_st.st_mode != 0;
        }

Member Data Documentation

◆ m_st

struct stat cosmos::FileStatus::m_st

protected

Definition at line 263 of file FileStatus.hxx.

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

include/fs/FileStatus.hxx
src/fs/FileStatus.cxx

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ FileStatus() [1/4]

◆ FileStatus() [2/4]

◆ FileStatus() [3/4]

◆ FileStatus() [4/4]

Member Function Documentation

◆ accessTime()

◆ allocatedBlocks()

◆ blockSize()

◆ device()

◆ gid()

◆ inode()

◆ isSameFile()

◆ mode()

◆ modTime()

◆ numLinks()

◆ operator!=()

◆ operator==()

◆ rawMode()

◆ representedDevice()

◆ reset()

◆ size()

◆ statusTime()

◆ throwBadType()

◆ type()

◆ uid()

◆ updateFrom() [1/3]

◆ updateFrom() [2/3]

◆ updateFrom() [3/3]

◆ valid()

Member Data Documentation

◆ m_st