Provided by: libbobcat-dev_6.03.02-2_amd64 bug

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:

       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) 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)) 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

       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)) 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

       /*
                                     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

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

       o      bobcat_6.03.02-x.dsc: detached signature;

       o      bobcat_6.03.02-x.tar.gz: source archive;

       o      bobcat_6.03.02-x_i386.changes: change log;

       o      libbobcat1_6.03.02-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.03.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).