FBB::Stat(3bobcat)
Characteristics of object in the filesystem
(libbobcat-dev_6.06.02)
2005-2024
NAME
FBB::Stat - Determines File Characteristics
SYNOPSIS
    #include <bobcat/stat>
    Linking option: -lbobcat
DESCRIPTION
    Stat is a wrapper around the stat(2) and lstat(2) 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:
        
        -  ALL: require all of the specified Mode or
                SpecialMode values to match;
        
-  ANY: require any match of the specified Mode or
                SpecialMode values (one match suffices);
        
Stat::Mode: 
        This enumeration 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.
        
Stat::SpecialMode: 
        This enumeration 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,  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.
        
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))
        instead of considering symbolic links as regular files (using
        stat(2)).
Constructors and members that define Stat::Lstat parameters call
        lstat(2), thus distinguishing symbolic links from regular files,
        while constructors and members that do not define Stat::Lstat
        parameters use stat(2).
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
    
    -  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;
-  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 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
    
    -  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
    
    -  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.
-  size_t blockSize() const:
 Returns the blocksize (st_blksize) for filesystem I/O
-  size_t device() const:
 Returns the device id (st_dev).
-  size_t deviceType() const:
 Returns the device type number, but only if the object type is
        DEVICE (st_rdev).
-  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)) can be used.
-  bool isType(Stat::Type probe):
 Returns true if the object has the probed type otherwise false
        is returned.
-  size_t inode() const:
 Returns the inode number (st_ino).
-  size_t gid() const:
 Returns the group ID of the object's owner (st_gid).
-  FBB::DateTime lastAccess() const:
 Returns an FBB::DateTime object holding information about the
        object's time of last access (st_atime) (using UTC).
-  FBB::DateTime lastChange() const:
 Returns an FBB::DateTime object holding information about the
        object's time of last status change (st_ctime) (using UTC).
-  FBB::DateTime lastModification() const:
 Returns an FBB::DateTime object holding information about the
        object's last modification time (st_mtime) (using UTC).
-  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.
-  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.
-  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.
-  std::string const &name() const:
 Returns the object's name as specified in the constructor or set()
        member function.
-  size_t nBlocks() const:
 Returns the object's number of allocated blocks (st_blocks).
-  size_t nLinks() const:
 Returns the object's number of hard links (st_nlink).
-  std::string path() const:
 Returns the object's full pathname. If the full pathname could not be
        determined, an empty string is returned.
-  bool set([Stat::Lstat,] std::string const &name):
 Redefine the Stat object to represent the information about
        the indicated object name.
-  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.
-  off_t size() const:
 Returns the object's size in number of bytes (st_size).
-  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.
-  Stat::stat const &statStruct() const:
 Returns a reference to the object's stat struct.
-  Stat::Type type() const:
 Returns the Stat::Type value of the object.
-  std::string typeStr() const:
 Returns a textual representation of the object's type as returned by
        the Stat::type() member function.
-  size_t uid() const:
 Returns the user ID of the object's owner (st_uid).
EXAMPLE
    
/*
                              driver.cc
*/
#include <iostream>
#include <string>
#include "../stat"
#include <bobcat/datetime>
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.
BOBCAT PROJECT FILES
    -  https://fbb-git.gitlab.io/bobcat/: gitlab project page;
    
-  bobcat_6.06.02-x.dsc: detached signature;
    
-  bobcat_6.06.02-x.tar.gz: source archive;
    
-  bobcat_6.06.02-x_i386.changes: change log;
    
-  libbobcat1_6.06.02-x_*.deb: debian package containing the
            libraries;
    
-  libbobcat1-dev_6.06.02-x_*.deb: debian package containing the
            libraries, headers and manual pages;
    
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).