stat

FBB::Stat(3bobcat)Characteristics of object in the filesysteFBB::Stat(3bobcat)



NAME
       FBB::Stat - Determines File Characteristics

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

DESCRIPTION
       Stat is a wrapper around the stat(2) system function. In particular, it
       offers features to test directly for object characteristics offered by
       stat(2). To determine whether an object exists the Stat bool conversion
       operator can 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: the object represents a block device

       o      CHARACTER_DEVICE: the object represents a character device

       o      DIRECTORY: the object represents a directory

       o      FIFO: the object represents a named pipe (a queue)

       o      REGULAR_FILE: the object represents a regular file

       o      SOCKET: the object represents a socket

       o      SYMBOLIC_LINK: the object represents a symbolic link

       o      ANY: any of the above types


CONSTRUCTORS
       o      Stat():
              The default constructor, creating an empty Stat object.

       o      Stat(std::string const &fname):
              Initializes a Stat with a given object name.

       o      Stat(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.


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

       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 a FBB::DateTime object holding information about the
              object’s time of last access (st_atime) (using UTC).

       o      FBB::DateTime lastChange() const:
              Returns a FBB::DateTime object holding information about the
              object’s time of last status change (st_ctime) (using UTC).

       o      FBB::DateTime lastModification() const:
              Returns a 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(std::string const &name):
              Redefine the Stat object to represent the information about the
              indicated object name.

       o      bool set(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 <bobcat/stat>
       #include <bobcat/datetime>

       using namespace std;
       using namespace FBB;

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

           Stat st;
           if (argc == 2)
               st.set(argv[1]);
           else if (argc == 3)
               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)

BUGS
       None Reported.

DISTRIBUTION FILES
       o      bobcat_5.00.02-x.dsc: detached signature;

       o      bobcat_5.00.02-x.tar.gz: source archive;

       o      bobcat_5.00.02-x_i386.changes: change log;

       o      libbobcat1_5.00.02-x_*.deb: debian package holding the
              libraries;

       o      libbobcat1-dev_5.00.02-x_*.deb: debian package holding the
              libraries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;


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

libbobcat-dev_5.00.02-x.tar.gz     2005-2019                FBB::Stat(3bobcat)