libcamgm
Classes | Public Types | Public Member Functions | Private Attributes | Friends | List of all members
ca_mgm::path::PathInfo Class Reference

Wrapper class for ::stat/::lstat and other file/directory related operations. More...

#include <PathInfo.hpp>

Classes

class  DevInoCache
 Simple cache remembering device/inode to detect hard links. More...
 
class  StatMode
 Wrapper class for mode_t values as derived from ::stat. More...
 

Public Types

enum  Mode { E_STAT, E_LSTAT }
 
enum  FileType {
  NOT_AVAIL = 0x00, NOT_EXIST = 0x01, T_FILE = 0x02, T_DIR = 0x04,
  T_CHARDEV = 0x08, T_BLOCKDEV = 0x10, T_FIFO = 0x20, T_LINK = 0x40,
  T_SOCKET = 0x80
}
 

Public Member Functions

 PathInfo (const PathName &path="", Mode initial=E_STAT)
 Constructor to create a PathInfo object from an existing PathName object. Initial stat-mode defaults to E_STAT. More...
 
 PathInfo (const std::string &path, Mode initial=E_STAT)
 Constructor to create a PathInfo object from a std::string. Initial stat-mode defaults to E_STAT. More...
 
 PathInfo (const char *path, Mode initial=E_STAT)
 Constructor to create a PathInfo object from a c-string. Initial stat-mode defaults to E_STAT. More...
 
virtual ~PathInfo ()
 Destructor. More...
 
const PathName path () const
 Returns the PathName object this PathInfo object holds. More...
 
std::string toString () const
 Returns a std::string formed from the PathName object this this PathInfo object holds. More...
 
Mode mode () const
 Returns the stat mode which is currently set in this PathInfo object. More...
 
int error () const
 Returns the internal error code. More...
 
void setPath (const PathName &path)
 Set the path you want to explore to path. More...
 
void setMode (Mode mode)
 Set the [l]stat mode to mode. More...
 
bool stat (const PathName &path)
 Performs stat on path. More...
 
bool lstat (const PathName &path)
 Performs lstat on path. More...
 
bool operator() (const PathName &path)
 Sets the PathInfo object to path and performs (l)stat on on it. More...
 
bool stat ()
 Performs a stat operation on the path currently held by this PathInfo object. More...
 
bool lstat ()
 Performs a lstat operation on the path currently held by this PathInfo object. More...
 
bool operator() ()
 Performs (l)stat on current path. More...
 
bool exists () const
 True if the path that this PathInfo object points to exists. More...
 
nlink_t nlink () const
 Returns the number of hard links to the file the PathName object points to. More...
 
uid_t owner () const
 Get the user ID of the file owner. More...
 
gid_t group () const
 Get the group ID of the file owner. More...
 
dev_t dev () const
 Returns the ID of the device that contains the file. More...
 
dev_t rdev () const
 Returns the device ID of a special file. More...
 
ino_t ino () const
 Returns the inode number of the file or directory this PathInfo object holds. More...
 
::off_t size () const
 Returns the size of the file. More...
 
blksize_t blksize () const
 Returns the block size of the file. More...
 
blkcnt_t blocks () const
 Returns the number of blocks used by the file. More...
 
File type functions.
FileType fileType () const
 Returns the file type. More...
 
bool isFile () const
 Check if the PathInfo object points to a regular file. More...
 
bool isDir () const
 Check if the PathInfo object points to a directory. More...
 
bool isLink () const
 Check if the PathInfo object points to a symbolic link. More...
 
bool isChr () const
 Check if the PathInfo object points to a character device. More...
 
bool isBlk () const
 Check if the PathInfo object points to a block device. More...
 
bool isFifo () const
 Check if the PathInfo object points to a FIFO (named pipe). More...
 
bool isSock () const
 Check if the PathInfo object points to a socket. More...
 
Permissions

The following functions can be used to check for file permissions. Their functionality closely resembles the POSIX flags mentioned in 'man [l]stat'.

bool isRUsr () const
 Check if owner has read permission. More...
 
bool isWUsr () const
 Check if owner has write permission. More...
 
bool isXUsr () const
 Check if owner has execute permission. More...
 
bool isR () const
 
bool isW () const
 
bool isX () const
 
bool isRGrp () const
 Check if group has read permission. More...
 
bool isWGrp () const
 Check if group has write permission. More...
 
bool isXGrp () const
 Check if group has execute permission. More...
 
bool isROth () const
 Check if others have read permission. More...
 
bool isWOth () const
 Check if others have write permission. More...
 
bool isXOth () const
 Check if others have execute permission. More...
 
bool isUid () const
 Check if 'set UID bit" is set. More...
 
bool isGid () const
 Check if 'set GID bit" is set. More...
 
bool isVtx () const
 Check if 'sticky bit" is set. More...
 
mode_t uperm () const
 Get the file owner permissions. More...
 
mode_t gperm () const
 Get the file group permissions. More...
 
mode_t operm () const
 Get the file permissions for others. More...
 
mode_t perm () const
 Get the complete file permissions. More...
 
bool isPerm (mode_t m) const
 Check if file has given permissions. More...
 
bool hasPerm (mode_t m) const
 Check if file has given permission flags set. More...
 
mode_t st_mode () const
 Returns the mode (i.e. file access permissions) of the file. More...
 
mode_t userMay () const
 Get permission according to current uid/gid. More...
 
bool userMayR () const
 Check if the current User (as returned by getuid()) may read the file. More...
 
bool userMayW () const
 Check if the current User (as returned by getuid()) may write to the file. More...
 
bool userMayX () const
 Check if the current User (as returned by getuid()) may execute the file. More...
 
bool userMayRW () const
 Check if the current User (as returned by getuid()) may read and write the file. More...
 
bool userMayRX () const
 Check if the current User (as returned by getuid()) may read and execute the file. More...
 
bool userMayWX () const
 Check if the current User (as returned by getuid()) may write and execute the file. More...
 
bool userMayRWX () const
 Check if the current User (as returned by getuid()) may read, write and execute the file. More...
 
time functions
time_t atime () const
 Get the access time of the file. More...
 
time_t mtime () const
 Get the time of the last modification of the file. More...
 
time_t ctime () const
 Get the last-change time of inode status of the file. More...
 

Private Attributes

PathName m_path
 
struct stat m_statbuf_C
 
Mode m_mode
 
int m_error
 

Friends

std::ostream & operator<< (std::ostream &str, FileType obj)
 Overloaded << operator. More...
 
std::ostream & operator<< (std::ostream &str, const PathInfo &obj)
 

Detailed Description

Wrapper class for ::stat/::lstat and other file/directory related operations.

This wrapper class for ::stat/::lstat can be used like in the following code fragment:

PathInfo pi1( "/foo/bar/some_file"); // new object from c-string
PathInfo pi2( PathName( "/foo/bar/some_file"); // new object from PathName object
PathInfo pi3( std::string( "/foo/bar/some_file" ); // new object from std::string
std::cout << "File: \t\t" << pi1 << std::endl;
std::cout << "Type: \t\t" << pi1.fileType() << std::endl;
std::cout << "UID: \t\t" << pi1.owner() << std::endl;
std::cout << "GID: \t\t" << pi1.group() << std::endl;
std::cout << "#links: \t" << pi1.nlink() << std::endl;
// Note the comment further down on the return value of size()!
std::cout << "size: \t\t" << std::string( pi1.size() ) << std::endl;
std::cout << "blksize: \t" << pi1.blksize() << std::endl;
std::cout << "blocks: \t" << pi1.blocks() << std::endl;
std::cout << "dev: \t\t" << pi1.dev() << std::endl;
std::cout << "ino: \t\t" << pi1.ino() << std::endl;
// Using PathInfo::[a,c,m]time()
time_t tmpTime = pi1.atime();
struct tm *timeStruct = localtime( &tmpTime );
char *timeFormat = "%d.%m.%Y - %X";
char timeBuf[256];
strftime( timeBuf, sizeof( timeBuf ), timeFormat, timeStruct );
std::cout << "atime: \t\t" << timeBuf << std::endll;

Member Enumeration Documentation

Enumerator
NOT_AVAIL 

no type info available

NOT_EXIST 

file does not exist

T_FILE 

regular file

T_DIR 

directory

T_CHARDEV 

character device

T_BLOCKDEV 

block device

T_FIFO 

FIFO (named pipe)

T_LINK 

symbolic link

T_SOCKET 

socket

Enumerator
E_STAT 
E_LSTAT 

Constructor & Destructor Documentation

ca_mgm::path::PathInfo::PathInfo ( const PathName path = "",
Mode  initial = E_STAT 
)

Constructor to create a PathInfo object from an existing PathName object. Initial stat-mode defaults to E_STAT.

Parameters
pathThe PathName object used to create the new PathInfo object.
initialThe stat-mode used when performing stat operations.
ca_mgm::path::PathInfo::PathInfo ( const std::string &  path,
Mode  initial = E_STAT 
)

Constructor to create a PathInfo object from a std::string. Initial stat-mode defaults to E_STAT.

Parameters
pathThe std::string representing a path which is used to create the new PathInfo object.
initialThe stat-mode used when performing stat operations.
ca_mgm::path::PathInfo::PathInfo ( const char *  path,
Mode  initial = E_STAT 
)

Constructor to create a PathInfo object from a c-string. Initial stat-mode defaults to E_STAT.

Parameters
pathThe c-string representing a path which is used to create the new PathInfo object.
virtual ca_mgm::path::PathInfo::~PathInfo ( )
virtual

Destructor.

Member Function Documentation

time_t ca_mgm::path::PathInfo::atime ( ) const

Get the access time of the file.

Returns
The access time as a UNIX time stamp.
blksize_t ca_mgm::path::PathInfo::blksize ( ) const

Returns the block size of the file.

Returns
The block size of the file.
blkcnt_t ca_mgm::path::PathInfo::blocks ( ) const

Returns the number of blocks used by the file.

Returns
The number of blocks used by the file.
time_t ca_mgm::path::PathInfo::ctime ( ) const

Get the last-change time of inode status of the file.

Returns
The last-change time as a UNIX time stamp.
dev_t ca_mgm::path::PathInfo::dev ( ) const

Returns the ID of the device that contains the file.

Returns
The device id that contains the file.
int ca_mgm::path::PathInfo::error ( ) const
inline

Returns the internal error code.

Returns '-1' if no (l)stat operations has been performed so far. This can be the case if:

  • no path has been set so far
  • path has been changed but no (l)stat operation has been triggered.
Returns
The error code.
bool ca_mgm::path::PathInfo::exists ( ) const
inline

True if the path that this PathInfo object points to exists.

Returns
True if path exists.
FileType ca_mgm::path::PathInfo::fileType ( ) const

Returns the file type.

Returns
The file type.
See Also
FileType
mode_t ca_mgm::path::PathInfo::gperm ( ) const

Get the file group permissions.

All other flags are masked out (masked to 0).

Returns
The masked mode_t.
gid_t ca_mgm::path::PathInfo::group ( ) const

Get the group ID of the file owner.

Returns
Gid of file owner.
bool ca_mgm::path::PathInfo::hasPerm ( mode_t  m) const

Check if file has given permission flags set.

Parameters
mThe mode_t flags you want the file to be checked for.
Returns
True if given mode_t flags matches the files' flags.
ino_t ca_mgm::path::PathInfo::ino ( ) const

Returns the inode number of the file or directory this PathInfo object holds.

Returns
The inode number.
bool ca_mgm::path::PathInfo::isBlk ( ) const

Check if the PathInfo object points to a block device.

bool ca_mgm::path::PathInfo::isChr ( ) const

Check if the PathInfo object points to a character device.

bool ca_mgm::path::PathInfo::isDir ( ) const

Check if the PathInfo object points to a directory.

bool ca_mgm::path::PathInfo::isFifo ( ) const

Check if the PathInfo object points to a FIFO (named pipe).

bool ca_mgm::path::PathInfo::isFile ( ) const

Check if the PathInfo object points to a regular file.

bool ca_mgm::path::PathInfo::isGid ( ) const

Check if 'set GID bit" is set.

bool ca_mgm::path::PathInfo::isLink ( ) const

Check if the PathInfo object points to a symbolic link.

bool ca_mgm::path::PathInfo::isPerm ( mode_t  m) const

Check if file has given permissions.

Parameters
mThe mode_t you want the file to be checked for.
Returns
True if given mode_t matches the files' mode_t.
bool ca_mgm::path::PathInfo::isR ( ) const
See Also
isRUsr()
bool ca_mgm::path::PathInfo::isRGrp ( ) const

Check if group has read permission.

bool ca_mgm::path::PathInfo::isROth ( ) const

Check if others have read permission.

bool ca_mgm::path::PathInfo::isRUsr ( ) const

Check if owner has read permission.

bool ca_mgm::path::PathInfo::isSock ( ) const

Check if the PathInfo object points to a socket.

bool ca_mgm::path::PathInfo::isUid ( ) const

Check if 'set UID bit" is set.

bool ca_mgm::path::PathInfo::isVtx ( ) const

Check if 'sticky bit" is set.

bool ca_mgm::path::PathInfo::isW ( ) const
See Also
isWUsr()
bool ca_mgm::path::PathInfo::isWGrp ( ) const

Check if group has write permission.

bool ca_mgm::path::PathInfo::isWOth ( ) const

Check if others have write permission.

bool ca_mgm::path::PathInfo::isWUsr ( ) const

Check if owner has write permission.

bool ca_mgm::path::PathInfo::isX ( ) const
See Also
isXUsr()
bool ca_mgm::path::PathInfo::isXGrp ( ) const

Check if group has execute permission.

bool ca_mgm::path::PathInfo::isXOth ( ) const

Check if others have execute permission.

bool ca_mgm::path::PathInfo::isXUsr ( ) const

Check if owner has execute permission.

bool ca_mgm::path::PathInfo::lstat ( const PathName path)

Performs lstat on path.

In case lstat fails errno is saved and can be acquired with PathInfo::error(). The stat mode remains set to 'E_LSTAT'.

Parameters
pathA PathName object pointing to the path you want to investigate.
Returns
True on success, false if lstat fails.
bool ca_mgm::path::PathInfo::lstat ( )

Performs a lstat operation on the path currently held by this PathInfo object.

On error errno is saved an can be acquired via PathInfo::error(). The stat mode remains set to 'E_LSTAT'

Returns
True on success, false if lstat fails.
Mode ca_mgm::path::PathInfo::mode ( ) const
inline

Returns the stat mode which is currently set in this PathInfo object.

Returns
The [l]stat mode currently set in this object. Can be either PathInfo::E_STAT or PathInfo::E_LSTAT.
time_t ca_mgm::path::PathInfo::mtime ( ) const

Get the time of the last modification of the file.

Returns
The modification time as a UNIX time stamp.
nlink_t ca_mgm::path::PathInfo::nlink ( ) const

Returns the number of hard links to the file the PathName object points to.

Returns
Number of hard links to the file.
bool ca_mgm::path::PathInfo::operator() ( const PathName path)

Sets the PathInfo object to path and performs (l)stat on on it.

Which function is called depends on the current stat mode (default: E_STAT). On error errno is saved and can be acquired via PathInfo::error().

Parameters
pathA PathName object point to the path you want to investigate.
Returns
True on success, false if (l)stat fails.
bool ca_mgm::path::PathInfo::operator() ( )

Performs (l)stat on current path.

Depending on the current stat mode this operator performs either stat, or lstat. On error errno is saved and can be acquired via PathInfo::error().

Returns
True on success, false of (l)stat fails.
mode_t ca_mgm::path::PathInfo::operm ( ) const

Get the file permissions for others.

All other flags are masked out (masked to 0).

Returns
The masked mode_t.
uid_t ca_mgm::path::PathInfo::owner ( ) const

Get the user ID of the file owner.

Returns
Uid of file owner.
const PathName ca_mgm::path::PathInfo::path ( ) const
inline

Returns the PathName object this PathInfo object holds.

Returns
The PathName object this PathInfo object holds.
mode_t ca_mgm::path::PathInfo::perm ( ) const

Get the complete file permissions.

Returns
The ( mode_t & S_IRWXU|S_IRWXG|S_IRWXO|S_ISUID|S_ISGID|S_ISVTX ).
dev_t ca_mgm::path::PathInfo::rdev ( ) const

Returns the device ID of a special file.

Returns
The device ID of the file (in case of a special file).
void ca_mgm::path::PathInfo::setMode ( Mode  mode)

Set the [l]stat mode to mode.

When examining a link you get:

  • information about the link itself, when you are in lstat mode
  • information about the file the link points to, when you are in stat mode
Parameters
modeThe mode you want to set. Can be PathInfo::E_STAT, or PathInfo::E_LSTAT
See Also
Mode
void ca_mgm::path::PathInfo::setPath ( const PathName path)

Set the path you want to explore to path.

Parameters
pathThe PathName object you want to investigate.
::off_t ca_mgm::path::PathInfo::size ( ) const

Returns the size of the file.

Returns
The size of the file.
Note
The off_t type may be of type "long long" (64bit) and the stream operator "<<" may convert off_t to int, causing unexpected wrong outputs. You can workaround it using std::string(p.size()), that provides proper conversion constructors for 64bit integers.
mode_t ca_mgm::path::PathInfo::st_mode ( ) const

Returns the mode (i.e. file access permissions) of the file.

From the lstat man page: The following POSIX macros are defined to check the file type:

  • S_ISREG(mode_t) is it a regular file?
  • S_ISDIR(mode_t) directory?
  • S_ISCHR(mode_t) character device?
  • S_ISBLK(mode_t) block device?
  • S_ISFIFO(mode_t) FIFO (named pipe)?
  • S_ISLNK(mode_t) symbolic link? (Not in POSIX.1-1996.)
  • S_ISSOCK(mode_t) socket? (Not in POSIX.1-1996.)
Returns
The access permissions of the file.
bool ca_mgm::path::PathInfo::stat ( const PathName path)

Performs stat on path.

In case stat fails errno is saved and can be acquired with PathInfo::error(). The stat mode remains set to 'E_STAT'.

Parameters
pathThe PathName object pointing to the path you want to investigate.
Returns
True on success, false if stat fails.
bool ca_mgm::path::PathInfo::stat ( )

Performs a stat operation on the path currently held by this PathInfo object.

On error errno is saved an can be acquired via PathInfo::error(). The stat mode remains set to 'E_STAT'

Returns
True on success, false if stat fails.
std::string ca_mgm::path::PathInfo::toString ( ) const
inline

Returns a std::string formed from the PathName object this this PathInfo object holds.

Returns
A std::string created from the PathName object this PathInfo object holds.
mode_t ca_mgm::path::PathInfo::uperm ( ) const

Get the file owner permissions.

All other flags are masked out (masked to 0).

Returns
The masked mode_t.
mode_t ca_mgm::path::PathInfo::userMay ( ) const

Get permission according to current uid/gid.

Returns
The current users' permissions on the file [0-7].
bool ca_mgm::path::PathInfo::userMayR ( ) const

Check if the current User (as returned by getuid()) may read the file.

Returns
True if current user has read permissions.
bool ca_mgm::path::PathInfo::userMayRW ( ) const

Check if the current User (as returned by getuid()) may read and write the file.

Returns
True if current user has read and write permissions.
bool ca_mgm::path::PathInfo::userMayRWX ( ) const

Check if the current User (as returned by getuid()) may read, write and execute the file.

Returns
True if current user has read, write and execute permissions.
bool ca_mgm::path::PathInfo::userMayRX ( ) const

Check if the current User (as returned by getuid()) may read and execute the file.

Returns
True if current user has read and execute permissions.
bool ca_mgm::path::PathInfo::userMayW ( ) const

Check if the current User (as returned by getuid()) may write to the file.

Returns
True if current user has write permissions.
bool ca_mgm::path::PathInfo::userMayWX ( ) const

Check if the current User (as returned by getuid()) may write and execute the file.

Returns
True if current user has write and execute permissions.
bool ca_mgm::path::PathInfo::userMayX ( ) const

Check if the current User (as returned by getuid()) may execute the file.

Returns
True if current user has execute permissions.

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  str,
FileType  obj 
)
friend

Overloaded << operator.

The << operator is overloaded for FileType objects to produce the following output:

PathInfo pi("./foo/bar/some_file");
std::cout << pi.fileType(); // =="./foo/bar/some_file{<st_mode> <uid>/<gid> [size <size>]"
Parameters
strThe std::ostream we want to write to.
objThe FileType object we want to be written to the ostream.
Returns
A reference to the resulting std::ostream.
std::ostream& operator<< ( std::ostream &  str,
const PathInfo obj 
)
friend

Member Data Documentation

int ca_mgm::path::PathInfo::m_error
private
Mode ca_mgm::path::PathInfo::m_mode
private
PathName ca_mgm::path::PathInfo::m_path
private
struct stat ca_mgm::path::PathInfo::m_statbuf_C
private

The documentation for this class was generated from the following file: