---
name: "stat"
section: "3bobcat"
platform: "linux"
package: "libbobcat-dev"
version: "6.07.01-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/stat/3bobcat"
---

# stat(3bobcat)

Determines File Characteristics

## NAME

FBB::Stat - Determines File Characteristics

## SYNOPSIS

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

## DESCRIPTION

**Stat** is a wrapper around the [**stat**(2)](/stat/2.md) and [**lstat**(2)](/lstat/2.md) system functions. In particular, it offers features to test directly for object characteristics offered by these two functions. To determine whether an object could properly be constructed use the *Stat bool* conversion operator. If this operator returns *false* then no other member except for *error* should be used.

## NAMESPACE

**FBB**\
 All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace **FBB**.

## INHERITS FROM

\-

## ENUMERATIONS

**Stat::Combine**: \
 This enumeration defines the following values:

- o

  **ALL**: require all of the specified **Mode** or **SpecialMode** values to match;

- o

  **ANY**: require any match of the specified **Mode** or **SpecialMode** values (one match suffices);

**Stat::Mode**: \
 This enumeration defines the following values:

- o

  **UR**: the owner of the object has read permissions

- o

  **UW**: the owner of the object has write permissions

- o

  **UX**: the owner of the object has execute permissions

- o

  **GR**: the group to which the object belongs has read permissions

- o

  **GW**: the group to which the object belongs has write permissions

- o

  **GX**: the group to which the object belongs has execute permissions

- o

  **OR**: others have read permissions

- o

  **OW**: others have write permissions

- o

  **OX**: others have execute permissions

- o

  **READ**: equal to *UR \| GR \| OR*

- o

  **WRITE**: equal to *UW \| GW \| OW*

- o

  **EXEC**: equal to *UX \| GX \| OX*

- o

  **RWX**: all of the above.

**Stat::SpecialMode**: \
 This enumeration defines the following values:

- o

  **SUID**: set UID bit is up

- o

  **SGID**: set GID bit is up

- o

  **SB**: sticky bit is up

**Stat::Type**: \
 This enumeration, which is identical to the [**glob**(3bobcat)](/glob/3bobcat.md) *Type* enumeration,  defines the following values:

- o

  **BLOCK\_DEVICE** (0060000): the object is a block device;

- o

  **CHARACTER\_DEVICE** (0020000): the object is a character device;

- o

  **DIRECTORY** (0040000): the object is a directory;

- o

  **FIFO** (0010000): the object is a named pipe (a queue);

- o

  **REGULAR\_FILE** (0100000): the object is a regular file;

- o

  **SOCKET** (0140000): the object is a socket;

- o

  **SYMBOLIC\_LINK** (0120000): the object is a symbolic link;

- o

  **ANY**: any of the above types.

**Stat::Lstat**: \
 This enumeration has one value: *LStat*, which can be specified by construtors and some members when the *Stat* object should distinguish regular files and symbolic links (calling [**lstat**(2)](/lstat/2.md)) instead of considering symbolic links as regular files (using [**stat**(2)](/stat/2.md)).

Constructors and members that define *Stat::Lstat* parameters call [**lstat**(2)](/lstat/2.md), thus distinguishing symbolic links from regular files, while constructors and members that do not define *Stat::Lstat* parameters use [**stat**(2)](/stat/2.md).

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.

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

## CONSTRUCTORS

- o

  **Stat()**:\
   The default constructor, creating an empty **Stat** object. It’s mainly used as default object when defining, e.g., vectors of *Stat* objects. As it doesn’t refer to an existing file system entry its *operator bool* returns false;

- o

  **Stat(\[Stat::Lstat,\] std::string const &fname)**:\
   Initializes a **Stat** with a given object name;

- o

  **Stat(\[Stat::Lstat,\] std::string const &fname, std::string const** **&searchPath)**:\
   Initializes a **Stat** with a given object name, where the object is 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. This object is then used. If *fname* is an absolute path, *searchPath* is ignored.

Copy and move constructors (and assignment operators) are available.

## OVERLOADED OPERATORS

- o

  **operator bool() const**:\
   This operator returns *true* if the *Stat* object holds information about an existing object. Otherwise *false* is returned. When *false* is returned other members, except for the assignment operators, the *error* member, and the *set* members should not be used.

## MEMBER FUNCTIONS

- o

  **bool access(FBB::User const &user, size\_t spec, bool useEffective =** **true) const**:\
   Returns *true* if *user* has the permissions as specified at *spec* (of which only the defined *Mode* bits are interpreted). If a combination of read, write and/or execute permissions are specified, then at least one of the read permissions, one of the write permissions and one of the execute permissions must be granted or the function returns *false*. E.g, when specifying *access(user, UW \|* *UR \| GR)* then the user *must* have write permissions, but either the user or the user’s group must have read permissions. If multiple read, multiple write or multiple execute permissions are specified (like *UR \| GR*) then this member returns *true* if at least one of the requested read, write, or execute permissions are granted for *user*.

- o

  **size\_t blockSize() const**:\
   Returns the blocksize (*st\_blksize*) for filesystem I/O

- o

  **size\_t device() const**:\
   Returns the device id (*st\_dev*).

- o

  **size\_t deviceType() const**:\
   Returns the device type number, but only if the object type is **DEVICE** (*st\_rdev*).

- o

  **size\_t error() const**:\
   Returns the error number associated with an error, in cases where **operator bool()** returns **false**. A returned value of 0 indicates \`no errors’. To obtain a verbal transcription of returned error numbers the *Exception::errnodescr* manipulator (cf. [**exception**(3bobcat)](/exception/3bobcat.md)) can be used.

- o

  **bool isType(Stat::Type probe)**:\
   Returns *true* if the object has the probed type otherwise *false* is returned.

- o

  **size\_t inode() const**:\
   Returns the inode number (*st\_ino*).

- o

  **size\_t gid() const**:\
   Returns the group ID of the object’s owner (*st\_gid*).

- o

  **FBB::DateTime lastAccess() const**:\
   Returns an **FBB::DateTime** object holding information about the object’s time of last access (*st\_atime*) (using UTC).

- o

  **FBB::DateTime lastChange() const**:\
   Returns an **FBB::DateTime** object holding information about the object’s time of last status change (*st\_ctime*) (using UTC).

- o

  **FBB::DateTime lastModification() const**:\
   Returns an **FBB::DateTime** object holding information about the object’s last modification time (*st\_mtime*) (using UTC).

- o

  **size\_t mode() const**:\
   Returns the object’s raw, uninterpreted mode (*st\_mode & RWX*). Note that this value is usually displayed (and is processed most easily) as an octal value.

- o

  **bool mode(size\_t mode, Combine combine = ALL)**:\
   Returns true if the object has the indicated mode. Multiple modes may be set, which can be combined by the logical **bitor** operator. By default, if multiple modes are specified, the resulting pattern must exactly represent the object’s mode for the member function to return **true**. An optional argument *ANY* may be specified if the function should return true if at least one specified mode matches the object’s actual mode. An *Exception* exception is thrown if the specified *mode* contains other values than the defined **Mode** or **SpecialMode** values.

- o

  **std::string modeStr() const**:\
   Returns the standard string-representation of the object’s mode (e.g., *rw-r--r--*). Special modes (e.g., suid) are indicated by *s* instead of *x* when the object is user and/or group executable and by *S* if the object has the special mode bit(s) set, but is not executable. For the \`other’ executable mode flag *t* is used (\`sticky’ bit) and *T* if the object is not \`other’ executable.

- o

  **std::string const &name() const**:\
   Returns the object’s name as specified in the constructor or **set()** member function.

- o

  **size\_t nBlocks() const**:\
   Returns the object’s number of allocated blocks (*st\_blocks*).

- o

  **size\_t nLinks() const**:\
   Returns the object’s number of hard links (*st\_nlink*).

- o

  **std::string path() const**:\
   Returns the object’s full pathname. If the full pathname could not be determined, an empty string is returned.

- o

  **bool set(\[Stat::Lstat,\] std::string const &name)**:\
   Redefine the **Stat** object to represent the information about the indicated object name.

- o

  **bool set(\[Stat::Lstat,\] std::string const &name, std::string const** **&pathlist)**:\
   Redefine the **Stat** object to represent the information about the indicated object name, where the object is searched in the *pathlist* directories, which is a colon-separated string of directory names. The object names are constructed by appending *fname* to each of the elements of *searchPath* until an existing object is found. This object is then used. If *fname* is an absolute path, *searchPath* is ignored.

- o

  **off\_t size() const**:\
   Returns the object’s size in number of bytes (*st\_size*).

- o

  **bool specialMode(size\_t special, Combine combine = ALL)**:\
   Returns true if the object has the indicated special modes.  Multiple special modes may be specified, which can be combined by the logical **bitor** operator. By default, if multiple modes are specified, the resulting pattern must exactly represent the object’s mode for the member function to return **true**. An optional argument *ANY* may be specified if the function should return true if at least one specified mode matches the object’s actual mode. The non-special modes are ignored but a *Exception* exception is thrown if *special* contains other values than those defined by the **SpecialMode** enum.

- o

  **Stat::stat const &statStruct() const**:\
   Returns a reference to the object’s **stat struct**.

- o

  **Stat::Type type() const**:\
   Returns the *Stat::Type* value of the object.

- o

  **std::string typeStr() const**:\
   Returns a textual representation of the object’s type as returned by the *Stat::type()* member function.

- o

  **size\_t uid() const**:\
   Returns the user ID of the object’s owner (*st\_uid*).

## EXAMPLE

```
#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)](/bobcat/7.md), [**glob**(3bobcat)](/glob/3bobcat.md), [**stat**(2)](/stat/2.md), [**lstat**(2)](/lstat/2.md)

## BUGS

None Reported.

## BOBCAT PROJECT FILES

- o

  *https://fbb-git.gitlab.io/bobcat/*: gitlab project page;

Debian Bobcat project files:

- o

  *libbobcat6*: debian package containing the shared library, changelog and copyright note;

- o

  *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’.

## COPYRIGHT

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

## AUTHOR

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