Dv::Util::File Class Reference

A File objects represents a pathname, possibly an existing file. More...

#include <file.h>

Inheritance diagram for Dv::Util::File:

Public Types
enum	Type { REGULAR, SYMLINK, DIRECTORY, SPECIALCHAR, SPECIALBLOCK, FIFO, SOCKET, OTHER, NONEXISTENT }
	Type of file, note NONEXISTENT for pathnames that do not refer to a file. More...
enum	Mode { READ_OWNER = 0400, WRITE_OWNER = 0200, EXEC_OWNER = 0100, READ_GROUP = 040, WRITE_GROUP = 020, EXEC_GROUP = 010, READ_OTHER = 04, WRITE_OTHER = 02, EXEC_OTHER = 01, SETUID = 04000, SETGID = 02000, RWX_OWNER = 0700, RWX_GROUP = 070, RWX_OTHER = 07, RW_OWNER = 0600, RW_GROUP = 060, RW_OTHER = 06 }
	File permissions, you can use the \| operator to combine them. More...
Public Member Functions
	File (const std::string &path) throw (FileError)
	Constructor, argument can be a relative or an absolute path.
	File (const File &f) throw (FileError)
	Copy constructor.
File &	operator= (const File &f) throw (FileError)
	Assignment.
virtual	~File ()
	Virtual destructor, calls unmap().
File &	expand () throw (FileError)
	Change File object to a non-symbolic link file by expanding symbolic links, if any.
bool	exists () const throw (FileError)
	Check existence of file.
	operator bool () const throw (FileError)
	Delegates to exists().
std::string	str () const
	Returns a full, clean, absolute path as given by realpath(3C).
	operator const char * () const
	Delegates to str().
const char *	path () const
	Identical to str().c_str().
std::string	fullpath () const throw (FileError)
	Retrieve full path without resolving symbolic links.
std::string	realpath () const throw (FileError)
	Only useful for symbolic links.
std::string	relpath (const std::string &from) const throw (FileError)
	Return path relative to from, which must be absolute.
std::string	relpath () const throw (FileError)
	Return path relative to Directory::pwd().
Type	type () const throw (FileError)
	Return type of file (possibly File::NONEXISTENT).
bool	isdir () const throw (FileError)
	Return true iff type() == File::DIRECTORY.
size_t	size () const throw (FileError)
	Return size in bytes of file, 0 if !exists().
time_t	last_modified () const throw (FileError)
	Return time of last modification of file, or 0 if it does not exist.
time_t	last_accessed () const throw (FileError)
	Return time of last access to file, or 0 if it does not exist.
mode_t	mode () const throw (FileError)
	Return permissions of file,.
uid_t	owner () const throw (FileError)
	Return uid of owner of file.
gid_t	group () const throw (FileError)
	Return gid of group-owner of file.
bool	chown (uid_t uid) const throw (FileError)
	Change the ownership of an existing file, return true iff successful.
bool	chgrp (const char *groupname) const throw (FileError)
	Change group-ownership of an existing file, return true iff successful.
bool	chmod (int mode=0755) throw (FileError)
	Change permissions on an existing file.
bool	rm () throw (FileError)
	Remove a file, for directories, rmdir is used.
void	rmfr () throw (FileError)
	Like rm -fr.
bool	mv (const std::string &newpath) throw (FileError)
	Rename file, return true iff succeeds, also renames *this.
bool	touch (int mode=0644) throw (FileError)
	Creates or updates modification time of file.
bool	mkdir (int mode=0755) throw (FileError)
	Create a directory str(), precondition is !exists().
bool	mklink (const std::string &path) throw (FileError)
	Create a hard link to path, precondition is !exists().
bool	mksymlink (const std::string &path) throw (FileError)
	Create a symbolic link to path.
const void *	map () throw (FileError)
	Map the contents of an existing file into memory.
void	unmap () throw (FileError)
	Release a mapping, if any, obtained by File::map().
const void *	mapped () const
std::string &	content (std::string &s) const throw (FileError)
	Append contents of file to string.
std::string	content () const throw (FileError)
	Return contents of file to string.
std::string	md5 (unsigned char *md5sum=NULL) throw (FileError)
	Return the md5 digest of the file.
std::string	sha1 (unsigned char *sha1sum=NULL) throw (FileError)
	Return the sha1 digest of the file.
virtual void	refresh () const throw (Dv::Util::FileError)
	Updates private data members, exist_ and type_.
struct stat &	stats () const
	Provide access to stats object.
Static Public Member Functions
static const std::string &	typestr (Type) throw (FileError)
	Return string representation of File::Type.
static std::string	absolute_path (const std::string &path) throw (FileError)
	Returns a full, clean, absolute path as given by realpath(3C).
static std::string &	fullpath (std::string path, std::string &resolved_path) throw (FileError)
	Retrieve full path without resolving symbolic links.
Protected Attributes
bool	exist_
	True iff there is a file with pathname str().
Type	type_
	Type of file.
Private Attributes
struct stat	stats_
	Man 2 stat for more info on this.
std::string	path_
void *	addr_
Friends
bool	operator== (const Dv::Util::File &, const Dv::Util::File &)
	Compare File objects.
bool	operator!= (const File &f1, const File &f2)
	Compare File objects.
bool	operator< (const File &, const File &)
	Compare File objects.

Detailed Description

A File objects represents a pathname, possibly an existing file.

Example usage:

 const char*    name;
 File           f(name);
 if (f.exists()) {
   Date         d(f.last_modified());
 
   cout << f.str() << endl;
   cout << std::string(d) << endl;
 
   const char*  pc = static_cast<const char*>(f.map());
 
   if (pc) // note: pc is not necessarily a C string
     for (unsigned int i=0;(i<f.size());++i,++pc)
       cout << *pc;
 }
 else
   f.touch(); // make it exist

Definition at line 61 of file file.h.

Member Enumeration Documentation

enum Dv::Util::File::Type

Type of file, note NONEXISTENT for pathnames that do not refer to a file.

Enumerator:

REGULAR
SYMLINK
DIRECTORY
SPECIALCHAR
SPECIALBLOCK
FIFO
SOCKET
OTHER
NONEXISTENT

Definition at line 64 of file file.h.

enum Dv::Util::File::Mode

File permissions, you can use the | operator to combine them.

Enumerator:

READ_OWNER
WRITE_OWNER
EXEC_OWNER
READ_GROUP
WRITE_GROUP
EXEC_GROUP
READ_OTHER
WRITE_OTHER
EXEC_OTHER
SETUID
SETGID
RWX_OWNER
RWX_GROUP
RWX_OTHER
RW_OWNER
RW_GROUP
RW_OTHER

Definition at line 67 of file file.h.

Constructor & Destructor Documentation

Dv::Util::File::File ( const std::string & path ) throw (FileError)

Constructor, argument can be a relative or an absolute path.

Parameters:

path

absolute or relative path

Dv::Util::File::File ( const File & f ) throw (FileError)

Copy constructor.

Parameters:

f

existing File object

Warning:

 File f(g);

is equivalent with

 File f(g.str());

virtual Dv::Util::File::~File ( ) [virtual]

Virtual destructor, calls unmap().

Member Function Documentation

File& Dv::Util::File::operator= ( const File & f ) throw (FileError)

Assignment.

Parameters:

f

existing File object

Warning:

 f = g;

is, if &f!=&g , equivalent with

 File f(g.str());

File& Dv::Util::File::expand ( ) throw (FileError)

Change File object to a non-symbolic link file by expanding symbolic links, if any.

Returns:: reference to *this.

Exceptions:

FileError

e.g. if there are too many symbolic links to follow.

static const std::string& Dv::Util::File::typestr ( Type ) throw (FileError) [static]

Return string representation of File::Type.

bool Dv::Util::File::exists ( ) const throw (FileError) [inline]

Check existence of file.

Definition at line 119 of file file.h.

References exist_, and refresh().

Referenced by operator bool().

Dv::Util::File::operator bool ( ) const throw (FileError) [inline]

Delegates to exists().

Definition at line 121 of file file.h.

References exists().

std::string Dv::Util::File::str ( ) const [inline]

Returns a full, clean, absolute path as given by realpath(3C).

Warning:: For symbolic links the path used in the constructor is returned.

Definition at line 126 of file file.h.

References path_.

static std::string Dv::Util::File::absolute_path ( const std::string & path ) throw (FileError) [static]

Returns a full, clean, absolute path as given by realpath(3C).

Warning:: For symbolic links the path used in the constructor is returned.

Dv::Util::File::operator const char * ( ) const [inline]

Delegates to str().

Definition at line 133 of file file.h.

References path_.

const char* Dv::Util::File::path ( ) const [inline]

Identical to str().c_str().

Returns:: str().c_str()

Warning:: For symbolic links the path used in the constructor is returned.

Definition at line 140 of file file.h.

References path_.

static std::string& Dv::Util::File::fullpath	(	std::string	path,
		std::string &	resolved_path
	)			throw (FileError) `[static]`

Retrieve full path without resolving symbolic links.

The result is absolute and does not contain '..' or '.' components and no superfluous '/' chars.

Parameters:

	path	relative or absolute path
	resolved_path	(output)

Returns:: reference to second parameter

Exceptions:

if

the full path would climb up from '/', e.g. '/..' would throw an exception. An empty path will also throw an exception.

std::string Dv::Util::File::fullpath ( ) const throw (FileError)

Retrieve full path without resolving symbolic links.

The result is absolute and does not contain '..' or '.' components and no superfluous '/' chars.

Returns:: resolved path.

Exceptions:

if

the full path would climb up from '/', e.g. '/..' would throw an exception. An empty path will also throw an exception.

std::string Dv::Util::File::realpath ( ) const throw (FileError)

Only useful for symbolic links.

std::string Dv::Util::File::relpath ( const std::string & from ) const throw (FileError)

Return path relative to from, which must be absolute.

Parameters:

from

path such that from/relpath(from) refers to this file

Returns:: relative path x such that from/x refers to this file

std::string Dv::Util::File::relpath ( ) const throw (FileError)

Return path relative to Directory::pwd().

Returns:: relpath(pwd())

Type Dv::Util::File::type ( ) const throw (FileError)

Return type of file (possibly File::NONEXISTENT).

Referenced by isdir().

bool Dv::Util::File::isdir ( ) const throw (FileError) [inline]

Return true iff type() == File::DIRECTORY.

Definition at line 184 of file file.h.

References DIRECTORY, and type().

size_t Dv::Util::File::size ( ) const throw (FileError)

Return size in bytes of file, 0 if !exists().

time_t Dv::Util::File::last_modified ( ) const throw (FileError)

Return time of last modification of file, or 0 if it does not exist.

time_t Dv::Util::File::last_accessed ( ) const throw (FileError)

Return time of last access to file, or 0 if it does not exist.

mode_t Dv::Util::File::mode ( ) const throw (FileError)

Return permissions of file,.

See also:: File::Mode.

uid_t Dv::Util::File::owner ( ) const throw (FileError)

Return uid of owner of file.

See also:: Dv::Util::User.

gid_t Dv::Util::File::group ( ) const throw (FileError)

Return gid of group-owner of file.

See also:: Dv::Util::User.

bool Dv::Util::File::chown ( uid_t uid ) const throw (FileError)

Change the ownership of an existing file, return true iff successful.

Parameters:

uid

id of new owner.

Returns:: true iff new owner is uid.

bool Dv::Util::File::chgrp ( const char * groupname ) const throw (FileError)

Change group-ownership of an existing file, return true iff successful.

Parameters:

groupname

of new group owner.

Returns:: true iff new group owner is groupname.

bool Dv::Util::File::chmod ( int mode = 0755 ) throw (FileError)

Change permissions on an existing file.

Parameters:

mode

representing permissions.

Returns:: true iff permissions where succesfully set.

See also:: File::Mode

bool Dv::Util::File::rm ( ) throw (FileError)

Remove a file, for directories, rmdir is used.

Returns:: true if exists(); false afterwards or if !exists()

void Dv::Util::File::rmfr ( ) throw (FileError)

Like rm -fr.

Throws FileError if exists() afterwards.

bool Dv::Util::File::mv ( const std::string & newpath ) throw (FileError)

Rename file, return true iff succeeds, also renames *this.

Parameters:

newpath

new name of file.

Returns:: true iff rename succeeded.

bool Dv::Util::File::touch ( int mode = 0644 ) throw (FileError)

Creates or updates modification time of file.

bool Dv::Util::File::mkdir ( int mode = 0755 ) throw (FileError)

Create a directory str(), precondition is !exists().

bool Dv::Util::File::mklink ( const std::string & path ) throw (FileError)

Create a hard link to path, precondition is !exists().

bool Dv::Util::File::mksymlink ( const std::string & path ) throw (FileError)

Create a symbolic link to path.

Returns:: false if the file already exists, true if the link was succesfully created.

Precondition:: exists() returns false

Warning:: There is no check on the path parameter.

const void* Dv::Util::File::map ( ) throw (FileError)

Map the contents of an existing file into memory.

Return 0 upon failure. Map() returns a pointer to the contents of the file, mapped into virtual memory

Warning:: the returned pointer is not a C string, use Dv::Util::File::size() to obtain the size of the map.

void Dv::Util::File::unmap ( ) throw (FileError)

Release a mapping, if any, obtained by File::map().

Unmapping a file that is not mapped is a noop. File::unmap() is automatically called by the destructor.

Exceptions:

throws

a FileError iff munmap(2) failed.

const void* Dv::Util::File::mapped ( ) const [inline]

Returns:: address of map for mapped file, or 0 otherwise.

Definition at line 294 of file file.h.

References addr_.

std::string& Dv::Util::File::content ( std::string & s ) const throw (FileError)

Append contents of file to string.

Parameters:

s

string to append to

Returns:: reference to s

std::string Dv::Util::File::content ( ) const throw (FileError)

Return contents of file to string.

Returns:: contents of file

std::string Dv::Util::File::md5 ( unsigned char * md5sum = NULL ) throw (FileError)

Return the md5 digest of the file.

Author:: Davy Van Nieuwenborgh <rasto@rasto.be>

Parameters:

md5sum

NULL or pointer to an array of 16 unsigned char bytes which will contain the binary md5 digest sum.

Returns:: hexadecimal string representation of the md5 digest sum.

std::string Dv::Util::File::sha1 ( unsigned char * sha1sum = NULL ) throw (FileError)

Return the sha1 digest of the file.

Author:: Davy Van Nieuwenborgh <rasto@rasto.be>

Parameters:

sha1sum

NULL or pointer to an array of 20 unsigned char bytes which will contain the binary sha1 digest sum.

Returns:: hexadecimal string representation of the sha1 digest sum.

virtual void Dv::Util::File::refresh ( ) const throw (Dv::Util::FileError) [virtual]

Updates private data members, exist_ and type_.

Reimplemented in Dv::Util::Directory.

Referenced by exists().

struct stat& Dv::Util::File::stats ( ) const [inline, read]

Provide access to stats object.

Returns:: const reference to stats object (man 2 stat)

See also:: Dv::Util::File::stats_

Definition at line 326 of file file.h.

References stats_.

Friends And Related Function Documentation

bool operator==	(	const Dv::Util::File &	,
		const Dv::Util::File &
	)			`[friend]`

Compare File objects.

File comparison is independent of the name, the operator compares i-nodes and devices. Nonexistent File objects are never equal.

Warning:: This function does not expand symbolic links. Thus, if s is a symbolic link to f, s and f will be different.

bool operator!=	(	const File &	f1,
		const File &	f2
	)			`[friend]`

Compare File objects.

File comparison is independent of the name, the operator compares i-nodes and devices. Nonexistent File objects are never equal.

Warning:: This function does not expand symbolic links. Thus, if s is a symbolic link to f, s and f will be different.

Definition at line 266 of file file.h.

bool operator<	(	const File &	,
		const File &
	)			`[friend]`

Compare File objects.

File comparison is independent of the name, the operator compares i-nodes and devices. Nonexistent File objects are never equal.

Warning:: This function does not expand symbolic links. Thus, if s is a symbolic link to f, s and f will be different.

Member Data Documentation

bool Dv::Util::File::exist_ [protected]

True iff there is a file with pathname str().

Definition at line 329 of file file.h.

Referenced by exists().

Type Dv::Util::File::type_ [protected]

Type of file.

Definition at line 331 of file file.h.

struct stat Dv::Util::File::stats_ [read, private]

Man 2 stat for more info on this.

Definition at line 334 of file file.h.

Referenced by stats().

std::string Dv::Util::File::path_ [private]

Definition at line 335 of file file.h.

Referenced by operator const char *(), path(), and str().

void* Dv::Util::File::addr_ [private]

Definition at line 336 of file file.h.

Referenced by mapped().

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

file.h

Dv::Util::File Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation