Wrapper for file operations. More...

#include <File.hpp>

Inheritance diagram for OksSystem::File:

Public Types
typedef std::vector< OksSystem::File >	file_list_t

Public Member Functions
	File (const std::string &name)
	File (const char *name)
	File (const File &other)
virtual	~File ()
	operator std::string () const throw ()
	operator const char * () const throw ()
	operator bool () const throw ()
bool	equals (const File &other) const throw ()
	compare two files *‍/
	operator size_t () const
const std::string &	full_name () const throw ()
	full name for file *‍/
const char *	c_full_name () const throw ()
std::string	short_name () const throw ()
	short name for file *‍/
std::string	parent_name () const throw ()
	path of directory containing file *‍/
std::string	extension () const throw ()
	extension for file *‍/
int	depth () const throw ()
	depth of the file *‍/
OksSystem::File	parent () const
	parent of the current file *‍/
OksSystem::File	child (const std::string &name) const
	named child of the current directory *‍/
OksSystem::File	temporary (const std::string &prefix) const
bool	exists () const throw ()
	does the file exist *‍/
mode_t	permissions () const
	permissions for the file *‍/
std::string	pretty_permissions () const
	pretty permissions for the file *‍/
size_t	size () const
	size of file *‍/
uid_t	owner_id () const
	owner id of file *‍/
User	owner () const
	owner of the file *‍/
gid_t	group () const
	group of file *‍/
bool	is_regular () const
	is the file a directory *‍/
bool	is_directory () const
	is the file a regular file *‍/
bool	is_fifo () const
	is the file a named pipe *‍/
std::string	file_type () const
	type of the file *‍/
file_list_t	directory () const
	list of file in directory *‍/
void	unlink () const
	deletes (unlinks) file *‍/
void	rmdir () const
	deletes directory *‍/
void	remove () const
	recursively delete files and directories *‍/
void	rename (const File &other) const
	rename or moves the file *‍/
void	permissions (mode_t permissions) const
	sets the type of the file *‍/
void	make_dir (mode_t permissions) const
	creates a directory *‍/
void	make_path (mode_t permissions) const
	creates a full path *‍/
void	make_fifo (mode_t permissions) const
	creates a FIFO (named pipe) *‍/
void	ensure_path (mode_t permissions) const
	creates the parent path *‍/
std::istream *	input () const
	returns an input stream from the file*‍/
std::ostream *	output (bool append=false) const
	returns an output stream to the file*‍/

Static Public Member Functions
static std::string	protocol (const std::string &url) throw ()
	extracts the protocol part of an url *‍/
static std::string	extension (const std::string &url) throw ()
	extracts the extension of a path or an url *‍/
static std::string	uri (const std::string &url) throw ()
	extracts the local path of an url *‍/
static std::string	short_name (const std::string &url) throw ()
	extracts the short file name of an url *‍/
static int	depth (const std::string &path) throw ()
	calculates depth of a path *‍/
static std::string	first_line (const std::string &text)
	extracts the first line of a text *‍/
static File	from_url (const std::string &url)
	build a file out of an URL *‍/
static std::string	working_directory ()
	current directory of process *‍/
static void	working_directory (const File &dir)
	set working directory of process *‍/
static std::string	expand_home (const std::string path)
	resolve home directory *‍/
static std::string	pretty_permissions (mode_t permissions)
	pretty prints permissions *‍/
static std::string	to_string (mode_t permissions) throw ()
	converts permission to string *‍/
static std::string	pretty_open_flag (int flags)
	pretty prints open flags *‍/
static std::string	pretty_size (size_t size, bool cut_small)
	pretty prints a file size *‍/

Static Public Attributes
static const char *const	FILE_FLAG_STR = "-rwxS"
	column headers for display of permissions *‍/
static const char *const	FILE_PROTOCOL = "file"
	string for the file protocol *‍/

Protected Member Functions
void	set_name (const std::string &name)
	sets the name of the file *‍/
mode_t	get_mode () const
	get mode associated with file (permission + type) *‍/

Static Protected Member Functions
static int	unit (int u)
	calculates the value of a computer unit of order n (i.e KB,GB, etc *‍/

Protected Attributes
std::string	m_full_name
	full name (path) of the file *‍/

Static Protected Attributes
static const char *const	HUMAN_SIZE_STR [] = { "B", "KB", "MB", "GB" }
	strings for pretty printing file sizes *‍/
static const char *const	HUMAN_OPEN_STR []
	strings for pretty printing open flags *‍/
static const int	KILOBYTE = 1024
	number of bytes in a kilobyte *‍/
static const char *const	FILE_COMMAND_PATH = "/usr/bin/file"

Detailed Description

Wrapper for file operations.

This class represents a file. it provides tools to manipulate files in a simple way. All methods throw ers issues in case of error. Internally, files are handled as canonical paths i.e with ./ ../ and symlinks resolved.

Author: Matthias Wiesmann

Version: 1.1

Definition at line 37 of file File.hpp.

Member Typedef Documentation

◆ file_list_t

typedef std::vector<OksSystem::File> OksSystem::File::file_list_t

Definition at line 40 of file File.hpp.

Constructor & Destructor Documentation

◆ File() [1/3]

OksSystem::File::File ( const std::string & name )

Constructor

Note: This method does not create a file, it simply builds an object describing a file

Definition at line 327 of file File.cpp.

{
  set_name(name);
} // File

◆ File() [2/3]

OksSystem::File::File ( const char * c_name )

Constructor This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 336 of file File.cpp.

{
  ERS_PRECONDITION(c_name);
  std::string name = std::string(c_name);
  set_name(name);
} // File

◆ File() [3/3]

OksSystem::File::File ( const File & other )

Constructor This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 347 of file File.cpp.

{
  set_name(other.m_full_name);
} // File

◆ ~File()

virtual OksSystem::File::~File ( )

inlinevirtual

Definition at line 78 of file File.hpp.

78{}

Member Function Documentation

◆ c_full_name()

const char * OksSystem::File::c_full_name	(		)	const
throw	(	)

Returns: the full (absolute) path of the file

Definition at line 451 of file File.cpp.

{
  return m_full_name.c_str();
} // c_full_name

◆ child()

OksSystem::File OksSystem::File::child ( const std::string & name ) const

named child of the current directory *‍/

Definition at line 501 of file File.cpp.

{
  std::string child_name = m_full_name + "/" + name;
  return OksSystem::File(child_name);
} // child

◆ depth() [1/2]

int OksSystem::File::depth	(		)	const
throw	(	)

depth of the file *‍/

Definition at line 487 of file File.cpp.

{
  return depth(m_full_name);
} // depth

◆ depth() [2/2]

int OksSystem::File::depth	(	const std::string &	path	)
throw	(	)

static

calculates depth of a path *‍/

Calculates the depth of a file. This depth is the number of parent directories. Files in the root directory have depht of 0, other files have a depth of their parent's depth + 1

Parameters

path	to analyze

Returns: depth or -1 if the format of the path is not understood.

Definition at line 130 of file File.cpp.

{
  if (path[0] == SLASH_CHAR) {
    int count = 0;
    std::string rest = path.substr(1);
    while (!rest.empty()) {
      std::string::size_type slash = rest.find(SLASH_CHAR);
      if (slash == std::string::npos)
        return count;
      count++;
      rest = rest.substr(slash + 1);
    } // while
    return count;
  } // path with slash
  if (protocol(path) == FILE_PROTOCOL) {
    return depth(uri(path));
  } //
  return -1;
} // depth

◆ directory()

OksSystem::File::file_list_t OksSystem::File::directory ( ) const

list of file in directory *‍/

Builds a vector containing all the files contained in a directory

Returns: a vector of files contained in the directory

Exceptions

OksSystem::OpenFail	if the directory could not be openend
OksSystem::CloseFail	if the directory cannot be closed

Definition at line 692 of file File.cpp.

{
  file_list_t file_vector;
  DIR* directory_ptr = opendir(m_full_name.c_str());
  if (!directory_ptr) {
    std::string message = "on directory " + m_full_name;
    throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "opendir", message.c_str());
  }
  while (true) {
    struct dirent* directory_entry = readdir(directory_ptr);
    if (directory_entry) {
      const std::string name = directory_entry->d_name;
      if ((name != ".") && (name != "..")) {
        std::string path = m_full_name + "/" + name;
        OksSystem::File file(path);
        file_vector.push_back(file);
      } // if
    } else {
      break;
    } // if / else
  } // while
  int status = closedir(directory_ptr);
  if (status < 0) {
    std::string message = "on directory " + m_full_name;
    throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "closedir", message.c_str());
  }
  return file_vector;
} // directory

◆ ensure_path()

void OksSystem::File::ensure_path ( mode_t perm ) const

creates the parent path *‍/

Makes sure that the path for a file exists This is done by calling make_path on the parent directory

Parameters

permissions permissions used to create directories

See also: OksSystem::File::make_path()

Definition at line 869 of file File.cpp.

{
  const File father = parent();
  father.make_path(perm);
} // ensure_path

◆ equals()

bool OksSystem::File::equals	(	const File &	other	)	const
throw	(	)

compare two files *‍/

Comparison operator As path are canonicalized, we simply compare the full paths.

Parameters

other file to compare this file to

Returns: true if both file are equal

Note: This comparison method does not taken hard links into account

Definition at line 383 of file File.cpp.

{
  return (m_full_name == other.m_full_name);
} // operator==

◆ exists()

bool OksSystem::File::exists	(		)	const
throw	(	)

does the file exist *‍/

Checks if the file exists in the fileOksSystem

Returns: true if the file exists, false otherwise

Exceptions

ers::IOIssue if an error occurs

Definition at line 526 of file File.cpp.

{
  struct stat file_status;
  const int result = stat(m_full_name.c_str(), &file_status);
  if (0 == result)
    return true;
  return false;
} // exists

◆ expand_home()

std::string OksSystem::File::expand_home ( const std::string path )

static

resolve home directory *‍/

Expands a file containing a home directory reference (~user).

Definition at line 208 of file File.cpp.

{
  ERS_PRECONDITION(!path.empty());
  ERS_PRECONDITION(path[0] == '~');
  std::string::size_type slash = path.find('/');
  const std::string user_name = path.substr(1, slash - 1);
  const std::string rest_path = path.substr(slash);
  OksSystem::User user;
  if (!user_name.empty()) {
    user = OksSystem::User(user_name);
  }
  return user.home() + rest_path;
} // home_directory

◆ extension() [1/2]

std::string OksSystem::File::extension	(		)	const
throw	(	)

extension for file *‍/

Returns: the extension of the file

Definition at line 481 of file File.cpp.

{
  return extension(m_full_name);
} // extension

◆ extension() [2/2]

std::string OksSystem::File::extension	(	const std::string &	url	)
throw	(	)

static

extracts the extension of a path or an url *‍/

Extracts the extension of an url or path

Parameters

url	an url or file path

Returns: the extension (without the dot) or an empty string

Definition at line 83 of file File.cpp.

{
  std::string::size_type dot = url.rfind(DOT_CHAR);
  if (dot == std::string::npos)
    return std::string();
  return url.substr(dot + 1);
} // extension

◆ file_type()

std::string OksSystem::File::file_type ( ) const

type of the file *‍/

Definition at line 676 of file File.cpp.

{
  OksSystem::Executable file_command(FILE_COMMAND_PATH);
  OksSystem::Executable::param_collection params;
  params.push_back("-b");
  params.push_back(full_name());
  return first_line(file_command.pipe_in(params));
} // file_type

◆ first_line()

std::string OksSystem::File::first_line ( const std::string & text )

static

extracts the first line of a text *‍/

Extracts the first line of a text

Parameters

text	the text to process

Returns: the first line of the text

Definition at line 156 of file File.cpp.

{
  std::string::size_type nl = text.find('\n');
  if (nl > 0)
    return text.substr(0, nl);
  return text;
} // first_line

◆ from_url()

OksSystem::File OksSystem::File::from_url ( const std::string & url )

static

build a file out of an URL *‍/

Builds a File object ou of an url

Parameters

url	the url, it must start with the file protocol

Returns: a File object

Definition at line 170 of file File.cpp.

{
  std::string prot = protocol(url);
  ERS_PRECONDITION(prot == FILE_PROTOCOL);
  const std::string path = uri(url);
  return File(path);
} // from_url

◆ full_name()

const std::string & OksSystem::File::full_name	(		)	const
throw	(	)

full name for file *‍/

Returns: the full (absolute) path of the file

Definition at line 443 of file File.cpp.

{
  return m_full_name;
} // full_name

◆ get_mode()

mode_t OksSystem::File::get_mode ( ) const

protected

get mode associated with file (permission + type) *‍/

Extracts the mode information of the file. This is used to determine both the file type and the file permissions

Returns: the mode of the file

Exceptions

OksSystem::FStatFail if fstat fails

Definition at line 542 of file File.cpp.

{
  struct stat file_status;
  const int result = stat(m_full_name.c_str(), &file_status);
  if (0 == result) {
    return file_status.st_mode;
  } // if
  std::string message = "on file/directory " + m_full_name;
  throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "stat", message.c_str());
} // mode

◆ group()

gid_t OksSystem::File::group ( ) const

group of file *‍/

Returns: the group-id of the group of the file

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 629 of file File.cpp.

{
  struct stat file_status;
  const int result = stat(m_full_name.c_str(), &file_status);
  if (0 == result)
    return file_status.st_gid;
  std::string message = "on file/directory " + m_full_name;
  throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "stat", message.c_str());
} // owner

◆ input()

std::istream * OksSystem::File::input ( ) const

returns an input stream from the file*‍/

Conversion into a input stream pointer This actually creates a new input stream that reads from the file.

Returns: a dynamically allocated input stream

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 908 of file File.cpp.

{
  try {
    std::ifstream* stream = new std::ifstream(m_full_name.c_str());
    stream->exceptions(std::ios::failbit | std::ios::badbit);
    return stream;
  } catch (std::ios_base::failure& ex) {
    throw OksSystem::OpenFileIssue(ERS_HERE, errno, m_full_name.c_str(), ex);
  } // catch
} // std::istream*

◆ is_directory()

bool OksSystem::File::is_directory ( ) const

is the file a regular file *‍/

Checks if the file a directory

Returns: true if the file is a directory

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 657 of file File.cpp.

{
  const mode_t mode = get_mode();
  return (mode & S_IFDIR);
} // is_regular

◆ is_fifo()

bool OksSystem::File::is_fifo ( ) const

is the file a named pipe *‍/

Checks if the file a named pipe (FIFO)

Returns: true if the file is named pipe (FIFO)

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 669 of file File.cpp.

{
  const mode_t mode = get_mode();
  return (mode & S_IFIFO);
} // is_pipe

◆ is_regular()

bool OksSystem::File::is_regular ( ) const

is the file a directory *‍/

Checks if the file a regular file (i.e not a directory, named pipe or anything else).

Returns: true if the file is regular

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 645 of file File.cpp.

{
  const mode_t mode = get_mode();
  return (mode & S_IFREG);
} // is_regular

◆ make_dir()

void OksSystem::File::make_dir ( mode_t perm ) const

creates a directory *‍/

Creates a directory The current object is taken as the name of the directory to create.

Parameters

perm	the permissions to associate with the directory

Note: if the directory exists, the method attempts to do a chmod to match the permissions

Definition at line 808 of file File.cpp.

{
 
  errno = 0;
  const int result = ::mkdir(m_full_name.c_str(), perm);
  int mkdir_error = errno;
 
  if (0 == result) {
    try {
      permissions(perm);
    } catch (OksSystem::OksSystemCallIssue& e) {
      std::string message = "on directory " + m_full_name;
      throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "mkdir -> chmod", message.c_str());
    }
    return;
  } else {
    if (exists()) {
      if (is_directory()) { // already exists we attempt a chmod
        try {
          permissions(perm);
        } catch (OksSystem::OksSystemCallIssue& e) {
          // ignore this case...
        }
        return;
      } // is directory
    } else { // exists
      std::string message = "on directory " + m_full_name;
      throw OksSystem::OksSystemCallIssue(ERS_HERE, mkdir_error, "mkdir", message.c_str());
    }
  }
 
} // makedir

◆ make_fifo()

void OksSystem::File::make_fifo ( mode_t perm ) const

creates a FIFO (named pipe) *‍/

Creates a named pipe (FIFO)

Parameters

perm	the permission to give the pipe

Definition at line 880 of file File.cpp.

{
  if (exists()) {
    if (is_fifo()) {
      if (perm != permissions()) {
        permissions(perm);
        return;
      } else {
        return;
      }
    } // is_fifo
  } // exists
  const int status = ::mkfifo(m_full_name.c_str(), perm);
  if (status == 0) {
    permissions(perm);
    return;
  }
  std::string message = "while creating FIFO " + m_full_name;
  throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "mkfifo", message.c_str());
} // makefifo

◆ make_path()

void OksSystem::File::make_path ( mode_t perm ) const

creates a full path *‍/

Builds a full path. The current object is taken as the name of a directory to create. This method creates all the parent directories as needed

Parameters

permissions the permissions to associate with the directory

Note: If parent directories are created, their permissions will be those defined in permissions ORed with 0700. This is needed to ensure we can actually write into the directories we create.

Definition at line 852 of file File.cpp.

{
  const File father = parent();
  if (!father.exists()) {
    mode_t father_permission = perm | S_IRWXU; // we need rights to write sons
    father.make_path(father_permission);
  } // if
  make_dir(perm);
} // makepath

◆ operator bool()

OksSystem::File::operator bool	(		)	const
throw	(	)

Cast to boolean, checks if the file exists

Returns: true if the file exists

Definition at line 370 of file File.cpp.

{
  return exists();
} // operator bool

◆ operator const char *()

OksSystem::File::operator const char *	(		)	const
throw	(	)

Definition at line 361 of file File.cpp.

{
  return m_full_name.c_str();
} // operator const char*

◆ operator size_t()

OksSystem::File::operator size_t ( ) const

Cast to size type

Returns: the size of the file

See also: size()

Definition at line 393 of file File.cpp.

{
  return size();
} // operator size_t

◆ operator std::string()

OksSystem::File::operator std::string	(		)	const
throw	(	)

Definition at line 356 of file File.cpp.

{
  return m_full_name;
} // operator std::string

◆ output()

std::ostream * OksSystem::File::output ( bool append = false ) const

returns an output stream to the file*‍/

Conversion into an output stream pointer This actually creates a new output stream that writes to the file.

Returns: a dynamically allocated output stream

Parameters

append is the file opened in append mode

Exceptions

ers::IOIssue if an error occurs

Definition at line 927 of file File.cpp.

{
  try {
    std::ios::openmode mode = std::ios::out;
    if (append) {
      mode |= std::ios::app;
    }
    std::ofstream* stream = new std::ofstream(m_full_name.c_str(), mode);
    stream->exceptions(std::ios::failbit | std::ios::badbit);
    return stream;
  } catch (std::ios_base::failure& ex) {
    throw OksSystem::OpenFileIssue(ERS_HERE, errno, m_full_name.c_str(), ex);
  } // catch
} // std::ostream*

◆ owner()

OksSystem::User OksSystem::File::owner ( ) const

owner of the file *‍/

Definition at line 619 of file File.cpp.

{
  return User(owner_id());
} // owner

◆ owner_id()

uid_t OksSystem::File::owner_id ( ) const

owner id of file *‍/

Returns: the user-id of the owner of the file

Exceptions

OksSystem::IOIssue if an error occurs or the file does not exist

Definition at line 608 of file File.cpp.

{
  struct stat file_status;
  const int result = stat(m_full_name.c_str(), &file_status);
  if (0 == result)
    return file_status.st_uid;
  std::string message = "on file/directory " + m_full_name;
  throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "stat", message.c_str());
} // owner_id

◆ parent()

OksSystem::File OksSystem::File::parent ( ) const

parent of the current file *‍/

Returns: the parent directory

Definition at line 495 of file File.cpp.

{
  return File(parent_name());
} // parent

◆ parent_name()

std::string OksSystem::File::parent_name	(		)	const
throw	(	)

path of directory containing file *‍/

Finds the name of the enclosing directory

Returns: the path of the directory containing the file

Definition at line 469 of file File.cpp.

{
  std::string::size_type size = m_full_name.size();
  std::string::size_type slash = m_full_name.rfind(SLASH_CHAR, size - 1);
  if (slash == std::string::npos || slash == 0)
    return ("/");
  return m_full_name.substr(0, slash);
} // directory

◆ permissions() [1/2]

mode_t OksSystem::File::permissions ( ) const

permissions for the file *‍/

Returns: the permissions for the file

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 558 of file File.cpp.

{
  mode_t mode = get_mode();
  return (mode & 07777);
} // permissions

◆ permissions() [2/2]

void OksSystem::File::permissions ( mode_t perm ) const

sets the type of the file *‍/

Sets the permissions of the file

Parameters

permissions the new permissions

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 788 of file File.cpp.

{
  if (perm != permissions()) {
    const int result = ::chmod(m_full_name.c_str(), perm);
    if (0 == result) {
      return;
    }
    std::string message = "on file/directory " + m_full_name;
    throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "chmod", message.c_str());
  }
} // permissions

◆ pretty_open_flag()

std::string OksSystem::File::pretty_open_flag ( int flags )

static

pretty prints open flags *‍/

Builds a prettyfied version of flags used by the open OksSystem call

Parameters

flags as passed to open

Returns: a string containing the beautified flags

Note: This method only handles flags available accross plateforms.

Definition at line 253 of file File.cpp.

{
  std::ostringstream flag_str;
  if (flags & O_WRONLY) {
    flag_str << HUMAN_OPEN_STR[1];
  } else if (flags & O_RDWR) {
    flag_str << HUMAN_OPEN_STR[0] << "-" << HUMAN_OPEN_STR[1];
  } else {
    flag_str << HUMAN_OPEN_STR[0];
  }
  if (flags & O_NONBLOCK) {
    flag_str << "/" << HUMAN_OPEN_STR[2];
  }
  if (flags & O_APPEND) {
    flag_str << "/" << HUMAN_OPEN_STR[3];
  }
  if (flags & O_CREAT) {
    flag_str << "/" << HUMAN_OPEN_STR[4];
  }
  if (flags & O_TRUNC) {
    flag_str << "/" << HUMAN_OPEN_STR[5];
  }
  if (flags & O_EXCL) {
    flag_str << "/" << HUMAN_OPEN_STR[6];
  }
  flag_str << "(" << flags << ")";
  return flag_str.str();
} // pretty_open_permission

◆ pretty_permissions() [1/2]

std::string OksSystem::File::pretty_permissions ( ) const

pretty permissions for the file *‍/

Returns: the prettfied permissions for the file

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 569 of file File.cpp.

{
  return pretty_permissions(permissions());
} // pretty_permissions

◆ pretty_permissions() [2/2]

std::string OksSystem::File::pretty_permissions ( mode_t permissions )

static

pretty prints permissions *‍/

Builds a prettyfied version of permissions. This should look similar to what ls returns with the -l flag

Parameters

permissions the permission to beautify

Returns: a string containing the beautified permissions

Definition at line 229 of file File.cpp.

{
  char buffer[11];
  buffer[0] = (permissions & S_ISUID) ? SETUID_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[1] = (permissions & S_IRUSR) ? READ_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[2] = (permissions & S_IWUSR) ? WRITE_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[3] = (permissions & S_IXUSR) ? EXECUTE_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[4] = (permissions & S_IRGRP) ? READ_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[5] = (permissions & S_IWGRP) ? WRITE_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[6] = (permissions & S_IXGRP) ? EXECUTE_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[7] = (permissions & S_IROTH) ? READ_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[8] = (permissions & S_IWOTH) ? WRITE_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[9] = (permissions & S_IXOTH) ? EXECUTE_CHAR_CODE : NOTHING_CHAR_CODE;
  buffer[10] = '\0';
  return std::string(buffer);
} // pretty_permissions

◆ pretty_size()

std::string OksSystem::File::pretty_size	(	size_t	size,
		bool	cut_small )

static

pretty prints a file size *‍/

Builds a human readable textual description of a file size. The file size is expressed in Gigabytes (GB), Megabytes (MB) and Kilobytes (KB) and Bytes (B).

Parameters

size	the size of the file
cut_small	should the display only contain the highest quantity? For example if a file is 1 gigabyte and 20 bytes, if `cut_small` is `true`, then the 20 bytes are ignored.

Returns: a string containing the textual description

Definition at line 301 of file File.cpp.

{
  if (0 == size)
    return "0";
  std::ostringstream size_str;
  bool writen_something = false;
  for (int i = 3; i >= 0; i--) {
    const unsigned int size_unit = unit(i);
    if (size > size_unit && !(cut_small && writen_something)) {
      const int amount = size / size_unit;
      size = size % size_unit;
      size_str << amount << SPACE_CHAR << HUMAN_SIZE_STR[i];
      writen_something = true;
    } // if unit is present
  } // loop
  return size_str.str();
} // pretty_size

◆ protocol()

std::string OksSystem::File::protocol	(	const std::string &	url	)
throw	(	)

static

extracts the protocol part of an url *‍/

Extracts the protocol part of an url. The protocol part is everything until the colon (:)

Parameters

url an url

Returns: the protocol part of an empty string

Definition at line 69 of file File.cpp.

{
  std::string::size_type colon = url.find(COLON_CHAR);
  if (colon == std::string::npos)
    return std::string();
  return url.substr(0, colon);
} // protocol

◆ remove()

void OksSystem::File::remove ( ) const

recursively delete files and directories *‍/

Recursively delete files and directories. If the file is a directory, all its child are deleted recursively.

Exceptions

OksSystem::UnlinkFail if unlink fails

Definition at line 750 of file File.cpp.

{
  if (is_directory()) {
    file_list_t childs = directory();
    for (file_list_t::const_iterator p = childs.begin(); p != childs.end(); p++) {
      const File f = *p;
      if (f.exists()) {
        f.remove();
      }
    } // for
    rmdir();
  } else {
    unlink();
  }
} // remove

◆ rename()

void OksSystem::File::rename ( const File & other ) const

rename or moves the file *‍/

Renames or moves a file.

Parameters

new_name the new name of the file

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 772 of file File.cpp.

{
  const char* source = c_full_name();
  const char* dest = other.c_full_name();
  const int result = ::rename(source, dest);
  if (0 == result)
    return;
  throw OksSystem::RenameFileIssue(ERS_HERE, errno, source, dest);
} // rename

◆ rmdir()

void OksSystem::File::rmdir ( ) const

deletes directory *‍/

Definition at line 735 of file File.cpp.

{
  const int result = ::rmdir(m_full_name.c_str());
  if (0 == result)
    return;
  std::string message = "on directory " + m_full_name;
  throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "rmdir", message.c_str());
} // rmdir

◆ set_name()

void OksSystem::File::set_name ( const std::string & name )

protected

sets the name of the file *‍/

Sets the name for a file. The path name is first expanded and the canonlicalized. Expension means the following

If the path starts with / nothing is done
If the path starts with ~ the username is resolved and the path starts from there
If the path starts with any other character, the working directory is prepended.

The path is then made canonical, this implies removing all ./ and ../ sequences, and resolving all symbolic links.

Parameters

name	the name of the file

Definition at line 415 of file File.cpp.

{
  ERS_PRECONDITION(!name.empty());
  const char c = name[0];
  std::string long_path;
  switch (c) {
    case '/':
      long_path = name;
      break;
    case '~':
      long_path = expand_home(name);
      break;
    default:
      long_path = working_directory() + "/" + name;
      break;
  } // switch
  char buffer[PATH_MAX];
  const char* result = realpath(long_path.c_str(), buffer);
  if (result == 0) { // could not resolve path
    m_full_name = long_path;
  } else { // we could canonicalize the path
    m_full_name = buffer;
  } //
} // set_name

◆ short_name() [1/2]

std::string OksSystem::File::short_name	(		)	const
throw	(	)

short name for file *‍/

Returns: the short name of the file - that is the name of the file in its directory

Definition at line 459 of file File.cpp.

{
  return short_name(m_full_name);
} // short_name

◆ short_name() [2/2]

std::string OksSystem::File::short_name	(	const std::string &	url	)
throw	(	)

static

extracts the short file name of an url *‍/

Extracts the short file name of an url or path

Parameters

url	an url or file path

Returns: the short name or the full url if it cannot be found

Definition at line 97 of file File.cpp.

{
  std::string::size_type slash = url.rfind(SLASH_CHAR);
  if (slash == std::string::npos)
    return url;
  return url.substr(slash + 1);
} // extension

◆ size()

size_t OksSystem::File::size ( ) const

size of file *‍/

Returns: the size (in bytes) of the file

Exceptions

OksSystem::IOIssue if an error occurs or the file does not exist

Definition at line 593 of file File.cpp.

{
  struct stat file_status;
  const int result = stat(m_full_name.c_str(), &file_status);
  if (0 == result)
    return file_status.st_size;
  std::string message = "on file/directory " + m_full_name;
  throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "stat", message.c_str());
} // size

◆ temporary()

OksSystem::File OksSystem::File::temporary ( const std::string & prefix ) const

Definition at line 508 of file File.cpp.

{
  char* tmp_name = tempnam(m_full_name.c_str(), prefix.c_str());
  if (!tmp_name) {
    std::string message = "while creating a valid filename in directory " + m_full_name;
    throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "tempnam", message.c_str());
  }
  OksSystem::File tmp_file(tmp_name);
  free(tmp_name);
  return tmp_file;
} // temporary

◆ to_string()

std::string OksSystem::File::to_string	(	mode_t	permissions	)
throw	(	)

static

converts permission to string *‍/

Converts permissions into a string

Parameters

permissions the permissions

Returns: a string contaning the permissions in octal form

Definition at line 580 of file File.cpp.

{
  std::ostringstream stream;
  stream.setf(std::ios::oct, std::ios::basefield);
  stream << permissions;
  return stream.str();
} // to_string

◆ unit()

int OksSystem::File::unit ( int u )

staticprotected

calculates the value of a computer unit of order n (i.e KB,GB, etc *‍/

Definition at line 283 of file File.cpp.

{
  ERS_PRECONDITION(u >= 0);
  if (u == 0)
    return 1;
  return KILOBYTE * unit(u - 1);
} // unit

◆ unlink()

void OksSystem::File::unlink ( ) const

deletes (unlinks) file *‍/

Unlinks (i.e deletes) a file.

Exceptions

ers::IOIssue if an error occurs or the file does not exist

Definition at line 726 of file File.cpp.

{
  const int result = ::unlink(m_full_name.c_str());
  if (0 == result)
    return;
  throw OksSystem::RemoveFileIssue(ERS_HERE, errno, m_full_name.c_str());
} // unlink

◆ uri()

std::string OksSystem::File::uri	(	const std::string &	url	)
throw	(	)

static

extracts the local path of an url *‍/

Extacts the uri part of an url. The uri of an url is everything except the protocol part In the case of file or http urls, the uri is the local path

Parameters

url an url

Returns: the uri or the full url if no colon in the string

Definition at line 113 of file File.cpp.

{
  std::string::size_type colon = url.find(COLON_CHAR);
  if (colon == std::string::npos)
    return url;
  return url.substr(colon + 1);
} // uri

◆ working_directory() [1/2]

std::string OksSystem::File::working_directory ( )

static

current directory of process *‍/

Returns: a string containing the working directory for the process

Definition at line 181 of file File.cpp.

{
  char* wd_buffer = getcwd(0, MAXPATHLEN);
  if (wd_buffer) {
    std::string directory = std::string(wd_buffer);
    free(wd_buffer);
    return directory;
  }
  std::string message("getting the current working directory");
  throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "getcwd", message.c_str());
} // working_directory

◆ working_directory() [2/2]

void OksSystem::File::working_directory ( const File & dir )

static

set working directory of process *‍/

Definition at line 194 of file File.cpp.

{
  const char* path = dir.c_full_name();
  const int status = ::chdir(path);
  if (status < 0) {
    std::string message = "on directory " + dir.full_name();
    throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "chdir", message.c_str());
  }
} // working_directory

Member Data Documentation

◆ FILE_COMMAND_PATH

const char *const OksSystem::File::FILE_COMMAND_PATH = "/usr/bin/file"

staticprotected

Definition at line 50 of file File.hpp.

◆ FILE_FLAG_STR

const char *const OksSystem::File::FILE_FLAG_STR = "-rwxS"

static

column headers for display of permissions *‍/

Definition at line 53 of file File.hpp.

◆ FILE_PROTOCOL

const char *const OksSystem::File::FILE_PROTOCOL = "file"

static

string for the file protocol *‍/

Definition at line 54 of file File.hpp.

◆ HUMAN_OPEN_STR

const char *const OksSystem::File::HUMAN_OPEN_STR

staticprotected

Initial value:

= { "READ", "WRITE", "NOBLOCK", "APPEND",

"CREATE", "TRUNCATE", "EXCLUSIVE" }

strings for pretty printing open flags *‍/

Definition at line 40 of file File.hpp.

◆ HUMAN_SIZE_STR

const char *const OksSystem::File::HUMAN_SIZE_STR = { "B", "KB", "MB", "GB" }

staticprotected

strings for pretty printing file sizes *‍/

Definition at line 39 of file File.hpp.

◆ KILOBYTE

const int OksSystem::File::KILOBYTE = 1024

staticprotected

number of bytes in a kilobyte *‍/

Definition at line 47 of file File.hpp.

◆ m_full_name

std::string OksSystem::File::m_full_name

protected

full name (path) of the file *‍/

Definition at line 43 of file File.hpp.

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

/github/workspace/dunedaq/sourcecode/okssystem/include/okssystem/File.hpp
/github/workspace/dunedaq/sourcecode/okssystem/src/File.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Typedef Documentation

◆ file_list_t

Constructor & Destructor Documentation

◆ File() [1/3]

◆ File() [2/3]

◆ File() [3/3]

◆ ~File()

Member Function Documentation

◆ c_full_name()

◆ child()

◆ depth() [1/2]

◆ depth() [2/2]

◆ directory()

◆ ensure_path()

◆ equals()

◆ exists()

◆ expand_home()

◆ extension() [1/2]

◆ extension() [2/2]

◆ file_type()

◆ first_line()

◆ from_url()

◆ full_name()

◆ get_mode()

◆ group()

◆ input()

◆ is_directory()

◆ is_fifo()

◆ is_regular()

◆ make_dir()

◆ make_fifo()

◆ make_path()

◆ operator bool()

◆ operator const char *()

◆ operator size_t()

◆ operator std::string()

◆ output()

◆ owner()

◆ owner_id()

◆ parent()

◆ parent_name()

◆ permissions() [1/2]

◆ permissions() [2/2]

◆ pretty_open_flag()

◆ pretty_permissions() [1/2]

◆ pretty_permissions() [2/2]

◆ pretty_size()

◆ protocol()

◆ remove()

◆ rename()

◆ rmdir()

◆ set_name()

◆ short_name() [1/2]

◆ short_name() [2/2]

◆ size()

◆ temporary()

◆ to_string()

◆ unit()

◆ unlink()

◆ uri()

◆ working_directory() [1/2]

◆ working_directory() [2/2]

Member Data Documentation

◆ FILE_COMMAND_PATH

◆ FILE_FLAG_STR

◆ FILE_PROTOCOL

◆ HUMAN_OPEN_STR

◆ HUMAN_SIZE_STR

◆ KILOBYTE

◆ m_full_name