limal::path::PathInfo Class Reference

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

#include <PathInfo.hpp>

List of all members.

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.
 PathInfo (const BLOCXX_NAMESPACE::String &path, Mode initial=E_STAT)
 Constructor to create a PathInfo object from a blocxx::String. Initial stat-mode defaults to E_STAT.
 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.
virtual ~PathInfo ()
 Destructor.
const PathName path () const
 Returns the PathName object this PathInfo object holds.
BLOCXX_NAMESPACE::String toString () const
 Returns a blocxx::String formed from the PathName object this this PathInfo object holds.
Mode mode () const
 Returns the stat mode which is currently set in this PathInfo object.
int error () const
 Returns the internal error code.
void setPath (const PathName &path)
 Set the path you want to explore to path.
void setMode (Mode mode)
 Set the [l]stat mode to mode.
bool stat (const PathName &path)
 Performs stat on path.
bool lstat (const PathName &path)
 Performs lstat on path.
bool operator() (const PathName &path)
 Sets the PathInfo object to path and performs (l)stat on on it.
bool stat ()
 Performs a stat operation on the path currently held by this PathInfo object.
bool lstat ()
 Performs a lstat operation on the path currently held by this PathInfo object.
bool operator() ()
 Performs (l)stat on current path.
bool exists () const
 True if the path that this PathInfo object points to exists.
nlink_t nlink () const
 Returns the number of hard links to the file the PathName object points to.
uid_t owner () const
 Get the user ID of the file owner.
gid_t group () const
 Get the group ID of the file owner.
dev_t dev () const
 Returns the ID of the device that contains the file.
dev_t rdev () const
 Returns the device ID of a special file.
ino_t ino () const
 Returns the inode number of the file or directory this PathInfo object holds.
::off_t size () const
 Returns the size of the file.
blksize_t blksize () const
 Returns the block size of the file.
blkcnt_t blocks () const
 Returns the number of blocks used by the file.
File type functions.

FileType fileType () const
 Returns the file type.
bool isFile () const
 Check if the PathInfo object points to a regular file.
bool isDir () const
 Check if the PathInfo object points to a directory.
bool isLink () const
 Check if the PathInfo object points to a symbolic link.
bool isChr () const
 Check if the PathInfo object points to a character device.
bool isBlk () const
 Check if the PathInfo object points to a block device.
bool isFifo () const
 Check if the PathInfo object points to a FIFO (named pipe).
bool isSock () const
 Check if the PathInfo object points to a socket.
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.
bool isWUsr () const
 Check if owner has write permission.
bool isXUsr () const
 Check if owner has execute permission.
bool isR () const
bool isW () const
bool isX () const
bool isRGrp () const
 Check if group has read permission.
bool isWGrp () const
 Check if group has write permission.
bool isXGrp () const
 Check if group has execute permission.
bool isROth () const
 Check if others have read permission.
bool isWOth () const
 Check if others have write permission.
bool isXOth () const
 Check if others have execute permission.
bool isUid () const
 Check if 'set UID bit" is set.
bool isGid () const
 Check if 'set GID bit" is set.
bool isVtx () const
 Check if 'sticky bit" is set.
mode_t uperm () const
 Get the file owner permissions.
mode_t gperm () const
 Get the file group permissions.
mode_t operm () const
 Get the file permissions for others.
mode_t perm () const
 Get the complete file permissions.
bool isPerm (mode_t m) const
 Check if file has given permissions.
bool hasPerm (mode_t m) const
 Check if file has given permission flags set.
mode_t st_mode () const
 Returns the mode (i.e. file access permissions) of the file.
mode_t userMay () const
 Get permission according to current uid/gid.
bool userMayR () const
 Check if the current User (as returned by getuid()) may read the file.
bool userMayW () const
 Check if the current User (as returned by getuid()) may write to the file.
bool userMayX () const
 Check if the current User (as returned by getuid()) may execute the file.
bool userMayRW () const
 Check if the current User (as returned by getuid()) may read and write the file.
bool userMayRX () const
 Check if the current User (as returned by getuid()) may read and execute the file.
bool userMayWX () const
 Check if the current User (as returned by getuid()) may write and execute the file.
bool userMayRWX () const
 Check if the current User (as returned by getuid()) may read, write and execute the file.
time functions

time_t atime () const
 Get the access time of the file.
time_t mtime () const
 Get the time of the last modification of the file.
time_t ctime () const
 Get the last-change time of inode status of the file.

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.
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( blocxx::String( "/foo/bar/some_file" ); // new object from blocxx::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" << blocxx::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

limal::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:
path The PathName object used to create the new PathInfo object.
initial The stat-mode used when performing stat operations.
limal::path::PathInfo::PathInfo ( const BLOCXX_NAMESPACE::String &  path,
Mode  initial = E_STAT 
)

Constructor to create a PathInfo object from a blocxx::String. Initial stat-mode defaults to E_STAT.

Parameters:
path The blocxx::String representing a path which is used to create the new PathInfo object.
initial The stat-mode used when performing stat operations.
limal::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:
path The c-string representing a path which is used to create the new PathInfo object.
virtual limal::path::PathInfo::~PathInfo (  )  [virtual]

Destructor.


Member Function Documentation

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

Get the access time of the file.

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

Returns the block size of the file.

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

Returns the number of blocks used by the file.

Returns:
The number of blocks used by the file.
time_t limal::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 limal::path::PathInfo::dev (  )  const

Returns the ID of the device that contains the file.

Returns:
The device id that contains the file.
int limal::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 limal::path::PathInfo::exists (  )  const [inline]

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

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

Returns the file type.

Returns:
The file type.
See also:
FileType
mode_t limal::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 limal::path::PathInfo::group (  )  const

Get the group ID of the file owner.

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

Check if file has given permission flags set.

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

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

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

Check if the PathInfo object points to a block device.

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

Check if the PathInfo object points to a character device.

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

Check if the PathInfo object points to a directory.

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

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

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

Check if the PathInfo object points to a regular file.

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

Check if 'set GID bit" is set.

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

Check if the PathInfo object points to a symbolic link.

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

Check if file has given permissions.

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

Check if group has read permission.

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

Check if others have read permission.

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

Check if owner has read permission.

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

Check if the PathInfo object points to a socket.

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

Check if 'set UID bit" is set.

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

Check if 'sticky bit" is set.

bool limal::path::PathInfo::isW (  )  const
See also:
isWUsr()
bool limal::path::PathInfo::isWGrp (  )  const

Check if group has write permission.

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

Check if others have write permission.

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

Check if owner has write permission.

bool limal::path::PathInfo::isX (  )  const
See also:
isXUsr()
bool limal::path::PathInfo::isXGrp (  )  const

Check if group has execute permission.

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

Check if others have execute permission.

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

Check if owner has execute permission.

bool limal::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.
bool limal::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:
path A PathName object pointing to the path you want to investigate.
Returns:
True on success, false if lstat fails.
Mode limal::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 limal::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 limal::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 limal::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.
bool limal::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:
path A PathName object point to the path you want to investigate.
Returns:
True on success, false if (l)stat fails.
mode_t limal::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 limal::path::PathInfo::owner (  )  const

Get the user ID of the file owner.

Returns:
Uid of file owner.
const PathName limal::path::PathInfo::path (  )  const [inline]

Returns the PathName object this PathInfo object holds.

Returns:
The PathName object this PathInfo object holds.
mode_t limal::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 limal::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 limal::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:
mode The mode you want to set. Can be PathInfo::E_STAT, or PathInfo::E_LSTAT
See also:
Mode
void limal::path::PathInfo::setPath ( const PathName path  ) 

Set the path you want to explore to path.

Parameters:
path The PathName object you want to investigate.
::off_t limal::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 blocxx::String(p.size()), that provides proper conversion constructors for 64bit integers.
mode_t limal::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 limal::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.
bool limal::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:
path The PathName object pointing to the path you want to investigate.
Returns:
True on success, false if stat fails.
BLOCXX_NAMESPACE ::String limal::path::PathInfo::toString (  )  const [inline]

Returns a blocxx::String formed from the PathName object this this PathInfo object holds.

Returns:
A blocxx::String created from the PathName object this PathInfo object holds.
mode_t limal::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 limal::path::PathInfo::userMay (  )  const

Get permission according to current uid/gid.

Returns:
The current users' permissions on the file [0-7].
bool limal::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 limal::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 limal::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 limal::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 limal::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 limal::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 limal::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,
const PathInfo obj 
) [friend]
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:
str The std::ostream we want to write to.
obj The FileType object we want to be written to the ostream.
Returns:
A reference to the resulting std::ostream.

Member Data Documentation

struct stat limal::path::PathInfo::m_statbuf_C [private]

The documentation for this class was generated from the following file:
Generated on Mon Jul 5 22:00:06 2010 for limal by  doxygen 1.6.3