.TH "FBB::Stat" "3bobcat" "2005\-2024" "libbobcat\-dev_6\&.06\&.02" "Characteristics of object in the filesystem" .PP .SH "NAME" FBB::Stat \- Determines File Characteristics .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" \fBStat\fP is a wrapper around the \fBstat\fP(2) and \fBlstat\fP(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 \fIStat bool\fP conversion operator\&. If this operator returns \fIfalse\fP then no other member except for \fIerror\fP should be used\&. .PP .SH "NAMESPACE" \fBFBB\fP .br All constructors, members, operators and manipulators, mentioned in this man\-page, are defined in the namespace \fBFBB\fP\&. .PP .SH "INHERITS FROM" \- .PP .SH "ENUMERATIONS" .PP \fBStat::Combine\fP: .br This enumeration defines the following values: .IP o \fBALL\fP: require all of the specified \fBMode\fP or \fBSpecialMode\fP values to match; .IP o \fBANY\fP: require any match of the specified \fBMode\fP or \fBSpecialMode\fP values (one match suffices); .PP \fBStat::Mode\fP: .br This enumeration defines the following values: .IP o \fBUR\fP: the owner of the object has read permissions .IP o \fBUW\fP: the owner of the object has write permissions .IP o \fBUX\fP: the owner of the object has execute permissions .IP o \fBGR\fP: the group to which the object belongs has read permissions .IP o \fBGW\fP: the group to which the object belongs has write permissions .IP o \fBGX\fP: the group to which the object belongs has execute permissions .IP o \fBOR\fP: others have read permissions .IP o \fBOW\fP: others have write permissions .IP o \fBOX\fP: others have execute permissions .IP o \fBREAD\fP: equal to \fIUR | GR | OR\fP .IP o \fBWRITE\fP: equal to \fIUW | GW | OW\fP .IP o \fBEXEC\fP: equal to \fIUX | GX | OX\fP .IP o \fBRWX\fP: all of the above\&. .PP \fBStat::SpecialMode\fP: .br This enumeration defines the following values: .IP o \fBSUID\fP: set UID bit is up .IP o \fBSGID\fP: set GID bit is up .IP o \fBSB\fP: sticky bit is up .PP \fBStat::Type\fP: .br This enumeration, which is identical to the \fBglob\fP(3bobcat) \fIType\fP enumeration, defines the following values: .IP o \fBBLOCK_DEVICE\fP (0060000): the object is a block device; .IP o \fBCHARACTER_DEVICE\fP (0020000): the object is a character device; .IP o \fBDIRECTORY\fP (0040000): the object is a directory; .IP o \fBFIFO\fP (0010000): the object is a named pipe (a queue); .IP o \fBREGULAR_FILE\fP (0100000): the object is a regular file; .IP o \fBSOCKET\fP (0140000): the object is a socket; .IP o \fBSYMBOLIC_LINK\fP (0120000): the object is a symbolic link; .IP o \fBANY\fP: any of the above types\&. .PP \fBStat::Lstat\fP: .br This enumeration has one value: \fILStat\fP, which can be specified by construtors and some members when the \fIStat\fP object should distinguish regular files and symbolic links (calling \fBlstat\fP(2)) instead of considering symbolic links as regular files (using \fBstat\fP(2))\&. .PP Constructors and members that define \fIStat::Lstat\fP parameters call \fBlstat\fP(2), thus distinguishing symbolic links from regular files, while constructors and members that do not define \fIStat::Lstat\fP parameters use \fBstat\fP(2)\&. .PP The return values of the members \fIstatStruct\fP and \fItype\fP and \fItypeStr\fP (see below) only distinguish symbolic links from regular files when the \fIStat::LStat\fP argument has been used\&. .PP The constructors and member functions listed below for which \fI[Stat::Lstat,]\fP is specified as first parameter may optionally specify the \fIStat::LStat\fP argument\&. .PP .SH "CONSTRUCTORS" .IP o \fBStat()\fP: .br The default constructor, creating an empty \fBStat\fP object\&. It\(cq\&s mainly used as default object when defining, e\&.g\&., vectors of \fIStat\fP objects\&. As it doesn\(cq\&t refer to an existing file system entry its \fIoperator bool\fP returns false; .IP o \fBStat([Stat::Lstat,] std::string const &fname)\fP: .br Initializes a \fBStat\fP with a given object name; .IP o \fBStat([Stat::Lstat,] std::string const &fname, std::string const &searchPath)\fP: .br Initializes a \fBStat\fP with a given object name, where the object is searched in the \fIsearchPath\fP directories, which is a colon\-separated string of directory names\&. The filenames are constructed by appending \fIfname\fP to each of the elements of \fIsearchPath\fP until an existing object is found\&. This object is then used\&. If \fIfname\fP is an absolute path, \fIsearchPath\fP is ignored\&. .PP Copy and move constructors (and assignment operators) are available\&. .PP .SH "OVERLOADED OPERATORS" .IP o \fBoperator bool() const\fP: .br This operator returns \fItrue\fP if the \fIStat\fP object holds information about an existing object\&. Otherwise \fIfalse\fP is returned\&. When \fIfalse\fP is returned other members, except for the assignment operators, the \fIerror\fP member, and the \fIset\fP members should not be used\&. .PP .SH "MEMBER FUNCTIONS" .IP o \fBbool access(FBB::User const &user, size_t spec, bool useEffective = true) const\fP: .br Returns \fItrue\fP if \fIuser\fP has the permissions as specified at \fIspec\fP (of which only the defined \fIMode\fP 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 \fIfalse\fP\&. E\&.g, when specifying \fIaccess(user, UW | UR | GR)\fP then the user \fImust\fP have write permissions, but either the user or the user\(cq\&s group must have read permissions\&. If multiple read, multiple write or multiple execute permissions are specified (like \fIUR | GR\fP) then this member returns \fItrue\fP if at least one of the requested read, write, or execute permissions are granted for \fIuser\fP\&. .IP o \fBsize_t blockSize() const\fP: .br Returns the blocksize (\fIst_blksize\fP) for filesystem I/O .IP o \fBsize_t device() const\fP: .br Returns the device id (\fIst_dev\fP)\&. .IP o \fBsize_t deviceType() const\fP: .br Returns the device type number, but only if the object type is \fBDEVICE\fP (\fIst_rdev\fP)\&. .IP o \fBsize_t error() const\fP: .br Returns the error number associated with an error, in cases where \fBoperator bool()\fP returns \fBfalse\fP\&. A returned value of 0 indicates `no errors\(cq\&\&. To obtain a verbal transcription of returned error numbers the \fIException::errnodescr\fP manipulator (cf\&. \fBexception\fP(3bobcat)) can be used\&. .IP o \fBbool isType(Stat::Type probe)\fP: .br Returns \fItrue\fP if the object has the probed type otherwise \fIfalse\fP is returned\&. .IP o \fBsize_t inode() const\fP: .br Returns the inode number (\fIst_ino\fP)\&. .IP o \fBsize_t gid() const\fP: .br Returns the group ID of the object\(cq\&s owner (\fIst_gid\fP)\&. .IP o \fBFBB::DateTime lastAccess() const\fP: .br Returns an \fBFBB::DateTime\fP object holding information about the object\(cq\&s time of last access (\fIst_atime\fP) (using UTC)\&. .IP o \fBFBB::DateTime lastChange() const\fP: .br Returns an \fBFBB::DateTime\fP object holding information about the object\(cq\&s time of last status change (\fIst_ctime\fP) (using UTC)\&. .IP o \fBFBB::DateTime lastModification() const\fP: .br Returns an \fBFBB::DateTime\fP object holding information about the object\(cq\&s last modification time (\fIst_mtime\fP) (using UTC)\&. .IP o \fBsize_t mode() const\fP: .br Returns the object\(cq\&s raw, uninterpreted mode (\fIst_mode & RWX\fP)\&. Note that this value is usually displayed (and is processed most easily) as an octal value\&. .IP o \fBbool mode(size_t mode, Combine combine = ALL)\fP: .br Returns true if the object has the indicated mode\&. Multiple modes may be set, which can be combined by the logical \fBbitor\fP operator\&. By default, if multiple modes are specified, the resulting pattern must exactly represent the object\(cq\&s mode for the member function to return \fBtrue\fP\&. An optional argument \fIANY\fP may be specified if the function should return true if at least one specified mode matches the object\(cq\&s actual mode\&. An \fIException\fP exception is thrown if the specified \fImode\fP contains other values than the defined \fBMode\fP or \fBSpecialMode\fP values\&. .IP o \fBstd::string modeStr() const\fP: .br Returns the standard string\-representation of the object\(cq\&s mode (e\&.g\&., \fIrw\-r\-\-r\-\-\fP)\&. Special modes (e\&.g\&., suid) are indicated by \fIs\fP instead of \fIx\fP when the object is user and/or group executable and by \fIS\fP if the object has the special mode bit(s) set, but is not executable\&. For the `other\(cq\& executable mode flag \fIt\fP is used (`sticky\(cq\& bit) and \fIT\fP if the object is not `other\(cq\& executable\&. .IP o \fBstd::string const &name() const\fP: .br Returns the object\(cq\&s name as specified in the constructor or \fBset()\fP member function\&. .IP o \fBsize_t nBlocks() const\fP: .br Returns the object\(cq\&s number of allocated blocks (\fIst_blocks\fP)\&. .IP o \fBsize_t nLinks() const\fP: .br Returns the object\(cq\&s number of hard links (\fIst_nlink\fP)\&. .IP o \fBstd::string path() const\fP: .br Returns the object\(cq\&s full pathname\&. If the full pathname could not be determined, an empty string is returned\&. .IP o \fBbool set([Stat::Lstat,] std::string const &name)\fP: .br Redefine the \fBStat\fP object to represent the information about the indicated object name\&. .IP o \fBbool set([Stat::Lstat,] std::string const &name, std::string const &pathlist)\fP: .br Redefine the \fBStat\fP object to represent the information about the indicated object name, where the object is searched in the \fIpathlist\fP directories, which is a colon\-separated string of directory names\&. The object names are constructed by appending \fIfname\fP to each of the elements of \fIsearchPath\fP until an existing object is found\&. This object is then used\&. If \fIfname\fP is an absolute path, \fIsearchPath\fP is ignored\&. .IP o \fBoff_t size() const\fP: .br Returns the object\(cq\&s size in number of bytes (\fIst_size\fP)\&. .IP o \fBbool specialMode(size_t special, Combine combine = ALL)\fP: .br Returns true if the object has the indicated special modes\&. Multiple special modes may be specified, which can be combined by the logical \fBbitor\fP operator\&. By default, if multiple modes are specified, the resulting pattern must exactly represent the object\(cq\&s mode for the member function to return \fBtrue\fP\&. An optional argument \fIANY\fP may be specified if the function should return true if at least one specified mode matches the object\(cq\&s actual mode\&. The non\-special modes are ignored but a \fIException\fP exception is thrown if \fIspecial\fP contains other values than those defined by the \fBSpecialMode\fP enum\&. .IP o \fBStat::stat const &statStruct() const\fP: .br Returns a reference to the object\(cq\&s \fBstat struct\fP\&. .IP o \fBStat::Type type() const\fP: .br Returns the \fIStat::Type\fP value of the object\&. .IP o \fBstd::string typeStr() const\fP: .br Returns a textual representation of the object\(cq\&s type as returned by the \fIStat::type()\fP member function\&. .IP o \fBsize_t uid() const\fP: .br Returns the user ID of the object\(cq\&s owner (\fIst_uid\fP)\&. .PP .SH "EXAMPLE" .nf /* driver\&.cc */ #include #include #include \(dq\&\&.\&./stat\(dq\& #include using namespace std; using namespace FBB; int main(int argc, char **argv) { if (argc == 1) { cout << \(dq\&Usage: driver [\-l] object [colon\-separated searchpath]\en\(dq\&; return 1; } bool lstat = \(dq\&\-l\(dq\&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 << \(dq\&Can\(cq\&t stat \(dq\& << argv[1] << \(dq\&, errno = \(dq\& << st\&.error() << endl; return 1; } cout << st\&.name() << \(dq\&: access: \(dq\& << st\&.lastAccess() << \(dq\&\en\(dq\& << st\&.name() << \(dq\&: change: \(dq\& << st\&.lastChange() << \(dq\&\en\(dq\& << st\&.name() << \(dq\&: modif: \(dq\& << st\&.lastModification() << \(dq\&\en\(dq\& \(dq\&Mode: \(dq\& << oct << st\&.mode() << \(dq\& (\(dq\& << st\&.modeStr() << \(dq\&)\en\(dq\& \(dq\&Type: \(dq\& << st\&.type() << \(dq\& (\(dq\& << st\&.typeStr() << \(dq\&)\en\(dq\& \(dq\&Full path: \(dq\& << st\&.path() << endl; } .fi .PP .SH "FILES" \fIbobcat/stat\fP \- defines the class interface .PP .SH "SEE ALSO" \fBbobcat\fP(7), \fBglob\fP(3bobcat), \fBstat\fP(2), \fBlstat\fP(2) .PP .SH "BUGS" None Reported\&. .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_6\&.06\&.02\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_6\&.06\&.02\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_6\&.06\&.02\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_6\&.06\&.02\-x_*\&.deb\fP: debian package containing the libraries, headers and manual pages; .PP .SH "BOBCAT" Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&. .PP .SH "COPYRIGHT" This is free software, distributed under the terms of the GNU General Public License (GPL)\&. .PP .SH "AUTHOR" Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&. .PP