FB...tat(3bobcat)

📦
version 6.15.01 · 7 versions
, in ubuntu stonking

💖 FB...tat(3bobcat) 💖

okay bestie, so this is the tea on FBB::Stat — it's all about Characteristics of object in the filesystem, and it lives in the (3bobcat) manual section. grab a snack, this one's a whole saga (part 1 of 2, so don't go anywhere) 🍓

✨ NAME ✨

FBB::Stat — Determines File Characteristics 👑

🌸 SYNOPSIS 🌸

#include <bobcat/stat>
Linking option: -lbobcat

that's it. that's the whole vibe. 💅

🦋 DESCRIPTION 🦋

so Stat is basically a glow-up wrapper around the stat(2) and lstat(2) system functions. like, it wraps them, but it also serves ✨looks✨ — specifically, it gives you straight-up ways to test for the object characteristics those two functions hand you.

here's the important part tho, no cap: to find out whether an object even got constructed properly, use the Stat bool conversion operator. if that operator comes back false, then do not touch any other member except error. none. nada. put it down. 🙈

🌈 NAMESPACE 🌈

FBB

every single constructor, member, operator and manipulator mentioned in this man-page is defined in the namespace FBB. periodt.

💀 INHERITS FROM 💀

-

(nothing. it inherits from nothing. it's self-made, main character energy fr fr ✨)

🎀 ENUMERATIONS 🎀

💜 Stat::Combine

this enum defines the following values:

  • ALL — require all of the specified Mode or SpecialMode values to match;
  • ANY — require any match of the specified Mode or SpecialMode values (one single match suffices, we're not picky 💅)

💜 Stat::Mode

this enum defines the following values:

  • UR — the owner of the object has read permissions
  • UW — the owner of the object has write permissions
  • UX — the owner of the object has execute permissions
  • GR — the group to which the object belongs has read permissions
  • GW — the group to which the object belongs has write permissions
  • GX — the group to which the object belongs has execute permissions
  • OR — others have read permissions
  • OW — others have write permissions
  • OX — others have execute permissions
  • READ — equal to UR | GR | OR
  • WRITE — equal to UW | GW | OW
  • EXEC — equal to UX | GX | OX
  • RWX — all of the above. every single one. the full set 🫶

💜 Stat::SpecialMode

this enum defines the following values:

  • SUID — set UID bit is up
  • SGID — set GID bit is up
  • SB — sticky bit is up

💜 Stat::Type

this enumeration — which is identical to the glob(3bobcat) Type enumeration, cute little sibling situation — defines the following values:

  • BLOCK_DEVICE (0060000) — the object is a block device;
  • CHARACTER_DEVICE (0020000) — the object is a character device;
  • DIRECTORY (0040000) — the object is a directory;
  • FIFO (0010000) — the object is a named pipe (a queue);
  • REGULAR_FILE (0100000) — the object is a regular file;
  • SOCKET (0140000) — the object is a socket;
  • SYMBOLIC_LINK (0120000) — the object is a symbolic link;
  • ANY — any of the above types. basically "surprise me" 🎁

💜 Stat::Lstat

this enumeration has exactly one value: LStat.

you can pass it to constructors and to some members when you want the Stat object to distinguish regular files from symbolic links — which it does by calling lstat(2) — instead of just treating symbolic links as regular files (which is the stat(2) behaviour).

so here's the rule, bestie:

  • constructors and members that define Stat::Lstat parameters call lstat(2), which means they distinguish symbolic links from regular files;
  • constructors and members that do not define Stat::Lstat parameters use stat(2).

also important: the return values of the members statStruct and type and typeStr (see below) only distinguish symbolic links from regular files when the Stat::LStat argument has been used. iykyk 🔥

and lastly: the constructors and member functions listed below for which [Stat::Lstat,] is specified as first parameter may optionally specify the Stat::LStat argument.

🧚 CONSTRUCTORS 🧚

  • Stat() — the default constructor, creating an empty Stat object. it's mainly used as a default object when you're defining, like, vectors of Stat objects. since it doesn't refer to an existing file system entry, its operator bool returns false. (it's the empty husk era 💀)
  • Stat([Stat::Lstat,] std::string const &fname) — initializes a Stat with a given object name.
  • Stat([Stat::Lstat,] std::string const &fname, std::string const &searchPath) — initializes a Stat with a given object name, where the object gets searched in the searchPath directories, which is a colon-separated string of directory names. the filenames are constructed by appending fname to each of the elements of searchPath until an existing object is found — and that object is the one that gets used. oh and if fname is an absolute path, searchPath is ignored entirely. 🚫

Copy and move constructors (and assignment operators) are available. slay, very movable, very copyable 💅

👑 OVERLOADED OPERATORS 👑

  • operator bool() const — this operator returns true if the Stat object holds information about an existing object. otherwise false is returned. and when false comes back, other members should not be used — with the exceptions of the assignment operators, the error member, and the set members.
⚠️ real talk bestie: a false here means don't touch anything else. the only things you're allowed to go near are the assignment operators, error, and the set members. everything else is off-limits fr fr.

💅 MEMBER FUNCTIONS 💅

okay so bestie, this is the whole entire buffet 🌈 every single one of these lives on your Stat object and honestly, you're gonna want them all. no skips, no shortcuts, we're going through the whole list together 💖

  • bool access(FBB::User const &user, size_t spec, bool useEffective = true) const — gives you true if user has the perms you asked for in spec (only the defined Mode bits get interpreted, the rest are just vibing in the background). here's the tea: if you specify a combo of read, write and/or execute perms, then at least one read perm, one write perm and one execute perm all have to be granted, otherwise it hands you back false. like, access(user, UW | UR | GR) means the user must have write perms, but either the user or the user's group has to have read perms. and if you ask for multiple read, multiple write or multiple execute perms (think UR | GR), then it returns true if at least one of the requested read, write or execute perms is granted for user. lowkey iconic ✨
  • size_t blockSize() const — the blocksize for filesystem I/O, aka st_blksize 🎀
  • size_t device() const — the device id, aka st_dev 🦋
  • size_t deviceType() const — the device type number, but only if the object's type is DEVICE (it's st_rdev, bestie, just so you know) 💅
  • size_t error() const — the error number tied to an error, only relevant in those sad moments where operator bool() returns false. a return value of 0 means no errors 😌 if you want a verbal transcription of the returned error numbers, that's what the errnodescr manipulator is for (cf. manipulators(3bobcat))
  • bool isType(Stat::Type probe) — true if the object has the type you probed for, otherwise you get false back 🙈
  • size_t inode() const — the inode number, st_ino ⭐
  • size_t gid() const — the group ID of the object's owner, st_gid 👑
  • FBB::DateTime lastAccess() const — an FBB::DateTime object holding info about the object's time of last access (st_atime) — and yes, it's in UTC 🌸
  • FBB::DateTime lastChange() const — an FBB::DateTime object holding info about the object's time of last status change (st_ctime), also UTC 🦋
  • FBB::DateTime lastModification() const — an FBB::DateTime object holding info about the object's last modification time (st_mtime), UTC again, consistent queen 💜
  • size_t mode() const — the object's raw, uninterpreted mode, i.e. st_mode & RWX. heads up, this value is usually displayed (and processed most easily) as an octal value 👀
  • bool mode(size_t mode, Combine combine = ALL) — true if the object has the mode you indicated. multiple modes are allowed and you can smash them together with the logical bitor operator. by default, if you specify multiple modes, the resulting pattern has to exactly represent the object's mode for this to return true. there's an optional ANY argument you can pass if you'd rather it return true whenever at least one of your specified modes matches the object's actual mode. and if your specified mode contains anything other than the defined Mode or SpecialMode values, an Exception gets thrown 😭
  • std::string modeStr() const — the standard string representation of the object's mode (like rw-r--r--, cute). special modes (suid, etc.) show up as s instead of x when the object is user and/or group executable, and as S if the object has the special mode bit(s) set but isn't executable. for the other executable mode flag, t is used (the sticky bit 🍓), and T if the object isn't other executable 💅
  • std::string const &name() const — the object's name, exactly as you gave it in the constructor or in the set() member function 🎀
  • size_t nBlocks() const — the object's number of allocated blocks, st_blocks ✨
  • size_t nLinks() const — the object's number of hard links, st_nlink 🔥
  • std::string path() const — the object's full pathname. and if the full pathname couldn't be figured out, you get an empty string back, sorry bestie 😭
  • bool set([Stat::Lstat,] std::string const &name) — redefines the Stat object so it represents the info about the object name you handed it 🫶
  • bool set([Stat::Lstat,] std::string const &name, std::string const &pathlist) — same deal, redefines the Stat object to represent the info about the indicated object name, but now the object gets searched for inside the pathlist directories — which is a colon-separated string of directory names. the object names get constructed by appending fname to each of the elements of searchPath until an existing object turns up, and then that object is the one that gets used. tiny caveat: if fname is an absolute path, searchPath is ignored, periodt 💅
  • off_t size() const — the object's size in number of bytes, st_size 🌈
  • bool specialMode(size_t special, Combine combine = ALL) — true if the object has the special modes you indicated. multiple special modes allowed, bitor them together. by default, if you specify multiple modes, the resulting pattern must exactly represent the object's mode for this to return true. optional ANY argument if you want it to return true when at least one specified mode matches the object's actual mode. the non-special modes are just ignored here, but an Exception gets thrown if special contains any values other than those defined by the SpecialMode enum ⚠️
  • Stat::stat const &statStruct() const — a reference to the object's stat struct 👑
  • Stat::Type type() const — the Stat::Type value of the object 🦋
  • std::string typeStr() const — a textual representation of the object's type, exactly as returned by the Stat::type() member function ✨
  • size_t uid() const — the user ID of the object's owner, st_uid 💖

🌸 EXAMPLE 🌸

bestie this is the whole vibe in one file, go off:

#include <iostream>
#include <string>

#include <bobcat/datetime>
#include <bobcat/stat>

using namespace std;
using namespace FBB;

int main(int argc, char **argv)
{
    if (argc == 1)
    {
        cout << "Usage: driver [-l] object [colon-separated searchpath]\n";
        return 1;
    }

    bool lstat = "-l"s == argv[1];
    if (lstat)
    {
        ++argv;
        --argc;
    }

    Stat st;
    if (argc == 2)
    {
        if (lstat)
            st.set(Stat::LStat, argv[1]);
        else
            st.set(argv[1]);
    }
    else if (argc == 3)
    {
        if (lstat)
            st.set(Stat::LStat, argv[1], argv[2]);
        else
            st.set(argv[1], argv[2]);
    }

    if (!st)
    {
        cout << "Can’t stat " << argv[1] << ", errno = " << st.error() << endl;
        return 1;
    }

    cout << st.name() << ": access: " << st.lastAccess() << "\n" <<
            st.name() << ": change: " << st.lastChange() << "\n" <<
            st.name() << ": modif:  " << st.lastModification() << "\n"
            "Mode: " << oct << st.mode() <<  " (" << st.modeStr() << ")\n"
            "Type: " << st.type() << " (" << st.typeStr() << ")\n"
            "Full path:  " << st.path()  << endl;
}

📁 FILES 📁

  • bobcat/stat — defines the class interface 🎀

👀 SEE ALSO 👀

bobcat(7), glob(3bobcat), stat(2), lstat(2)

🐛 BUGS 🐛

None Reported. (we love a clean record, not a single red flag 💅)

🎀 BOBCAT PROJECT FILES 🎀

Debian Bobcat project files:

  • libbobcat6: debian package containing the shared library, changelog and copyright note 💖
  • libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info 🦋

🦋 BOBCAT 🦋

Bobcat is an acronym of Brokken’s Own Base Classes And Templates. it's giving extremely clever naming, honestly ✨

This is free software, distributed under the terms of the GNU General Public License (GPL). fr fr, free 💜

👑 AUTHOR 👑

Frank B. Brokken (f.b.brokken@rug.nl).

aaaand that's a wrap bestie 🫶 this whole page is from libbobcat-dev_6.15.01, dated 2005-2026, and it's the FB...tat(3bobcat) manual page — iconic run, no notes 💅✨

📦 where this page comes from