File

Interface for basic file and directory operations.

File information

Filecommon/interface/file.h

Classes FileSystem
IFileWrite
IFileRead
IDirectory
IDirectoryEntry
IElfBinary
enum elf_architecture_t

Examples class FileSystem
   FileSystem::OpenWriteFile
   FileSystem::OpenReadFile
   FileSystem::OpenDirectory
   FileSystem::OpenElfBinary
   FileSystem::WriteWholeFile
   FileSystem::WriteBinaryFile
   FileSystem::ScanFile
   FileSystem::Rename
   FileSystem::CreateDirectory
   FileSystem::ChangeMode
   FileSystem::GetFileSystemTotalSize
class IFileWrite
class IDirectory

Classes

FileSystem

class FileSystem {
public:
    static class IFileWrite * OpenWriteFile(const char * fileName, bool append, class IInstanceLog * log);
    static class IFileRead * OpenReadFile(const char * fileName, class IInstanceLog * log);
    static class IDirectory * OpenDirectory(const char * directoryName, class IInstanceLog * log);
    static class IElfBinary * OpenElfBinary(const char * bin, class IInstanceLog * log);
    static bool ReadWholeFile(const char * filename, char * readBuffer, size_t size, class IInstanceLog * log);
    static bool WriteWholeFile(const char * filename, const char * writeBuffer, size_t size, class IInstanceLog * log);
    static bool WriteBinaryFile(const char * filename, const byte * writeBuffer, size_t size, class IInstanceLog * log);
    static bool ScanFile(class IInstanceLog * log, const char * filename, const char * format, ...);
    static bool FileExists(const char * filename, class IInstanceLog * log);
    static time_t GetLastWriteTime(const char * filename, class IInstanceLog * log);
    static bool SetLastWriteTime(const char * filename, long64 writeTimeMs, class IInstanceLog * log);
    static off_t GetFileSize(const char * filename, class IInstanceLog * log);
    static off_t GetFileBlockSize(const char * filename, class IInstanceLog * log);
    static bool Rename(const char * oldName, const char * newName, class IInstanceLog * log);
    static bool RemoveFile(const char * filename, class IInstanceLog * log);
    static bool CreateDirectory(const char * absolutePath, int mode, class IInstanceLog * log);
    static bool RemoveDirectory(const char * directoryPath, class IInstanceLog * log);
    static bool ChangeOwner(const char * path, const char * newOwner, const char * newGroup, class IInstanceLog * log);
    static bool ChangeMode(const char * path, int mode, class IInstanceLog * log);
    static ulong64 GetFileSystemTotalSize(const char * path, class IInstanceLog * log);
    static ulong64 GetFileSystemUsedSpace(const char * path, class IInstanceLog * log);
    static bool CheckSystemUser(const char * user, const char * group, class IInstanceLog * log);
    static char * GetFileSystemUser(const char * filepath, class IInstanceLog * log);
};

Overview

The basic class to perform read/write and create/rename/remove operations on linux files and directories. It also offers some functions to obtain information about file/block sizes, last write time of files and system users, and some other functions to maniplulate file owners or modes.

Logging

To enable logging for File interface, the flag LOG_FILE must be set in the Manager App diagnostic settings.

Public functions

OpenWriteFile (static function)
The main function to use to open a file for write operation. An empty file is created and opened for writinf if append is false; otherwise the file is opened for the writing at the end of the file. If the file is opened successfully, an object of class IFileWrite is returned. In case of error, a null pointer is returned.

Parameters

const char * fileNameThe absolute full path of the file
bool appendSpecifies whether a file is to be opened for append oor write operation
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

The IFileWrite instance created. It must be freed by the C++ operator delete, if no longer needed.

Code Example

class IFileWrite * file = FileSystem::OpenWriteFile("/path/file.txt", false, log_instance);
if(file) {
....
  write operation
...
delete file;
}
                
OpenReadFile (static function)
The main function to open an exisitng file for a read operation. On success, an object of the class IFileRead is returned which can be used to read the content of the file; otherwise a null pointer is returned.

Parameters

const char * fileNameThe absolute full path of the file
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

The IFileRead instance created. It must be freed by the C++ operator delete, if no longer be used.

Code Example

class IFileRead * file = FileSystem::OpenReadFile("/path/file.txt", log_instance);
if(file) {
....
  read operation
...
delete file;
}
                
OpenDirectory (static function)
The main function to use to open a directory corresponding to directoryName. An object of class IDirectory is returned on success and a null pointer on failure.

Parameters

const char * directoryNameThe absolute full name of the directory
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

The created IDirectory instance. It must be freed by the C++ operator delete, if no longer be used.

Code Example

class IDirectory * dir = FileSystem::OpenDirectory("/dir/", log_instance);
if(dir) {
....
  perform action
...
delete dir;
}
                
OpenElfBinary (static function)
The function is used to open a binary file bin. An object of class IElfBinary is returned on success and a null pointer on failure. This object can be used to get some information about an ELF (Executable and Linkable Format) binary.

Parameters

const char * binThe absolute full name of the binary
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

The created IElfBinary instance. It must be freed by the C++ operator delete, if no longer be used.

Code Example

class IElfBinary * bin = FileSystem::OpenElfBinary(binary, log_instance);
if(bin) {
....
  perform action
...
delete bin;
}
                
ReadWholeFile (static function)
Opens and reads the whole file into a buffer with a defined size. The file is closed afterwards.

Parameters

const char * filenameThe absolute path of the file
char * readBufferThe buffer in which the file is read to
size_t sizeThe size of the read buffer which must be big enough
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

If the read is successfull true is returned; otherwise false.
WriteWholeFile (static function)
Opens a file with an absolute path and writes the whole content of the write buffer into the file. The file is closed afterwards.

Note

This function just writes a NULL terminated string and the size is ignored! Thus this function is deprecated and you should use WriteBinaryFile instead!

Parameters

const char * filenameThe absolute path of the file
const char * writeBufferThe buffer to be written to the file. Must be a NULL terminated string.
size_t sizeThe size of the write buffer.
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

If the write is successfull true is returned; otherwise false.

Code Example

char * buffer = malloc(BIG_ENOUGH_SIZE);
FileSystem::WriteWholeFile("/path/important_file.txt", buffer, strlen(buffer), log_instance);
free(buffer);
                
WriteBinaryFile (static function)
Opens a file with an absolute path and writes the whole content of the write buffer into the file. The file is closed afterwards.

Parameters

const char * filenameThe absolute path of the file
cosnt byte * writeBufferThe buffer to be written to the file
size_t sizeThe size of the write buffer.
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

If the write is successfull true is returned; otherwise false.

Code Example

byte buffer[BIG_ENOUGH_SIZE];
FileSystem::WriteBinaryFile("/path/important_file.txt", buffer, sizeof(buffer), log_instance);
                
ScanFile (static function)
Scans a file given as an absolute path, based on a set of characters specified in a format string.

Parameters

class IInstanceLog * logThe IInstanceLog instance used for loging purposes.
const char * filenameThe absolute path of the file
const char * formatA string containing a set of characters that specifies how characters are extracted from the file (C string following the same specifications as in the C function scanf.)

Return value

If scanning the file is successfull, the file is closed and true is returned; otherwise false.

Code Example

long long unsigned time;
int id;
char s_string[128];
FileSystem::ScanFile(log_instance, "/path/file_to_scan", "%*32[^:]:%llu %*s %d %s", &time, &id, s_string);
FileExists (static function)
Checks if a file exists.

Parameters

const char * filenameThe absolute path of the file
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

If a file exists true is returned; otherwise false.
GetLastWriteTime (static function)
Returns the time of the last write operation performed on a file specified by an absolute path.

Parameters

const char * filenameThe absolute path of the file
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success the time in seconds is retured; otherwise -1.
SetLastWriteTime (static function)
Sets the modified and last access time of a file specified by an absolute path.

Parameters

const char * filenameThe absolute path of the file
long64 writeTimeMsUTC timestamp in milliseconds
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success true, otherwise false.
GetFileSize (static function)
Returns the current size of the file.

Parameters

const char * filenameThe absolute path of the file
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success the size of the file is retured; otherwise -1.
GetFileBlockSize (static function)
Returns the current block size of the file.

Parameters

const char * filenameThe absolute path of the file
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success the block size of the file is retured; otherwise -1.
Rename (static function)
Renames a file.

Parameters

const char * oldNameThe current name of the file (absolute path)
const char * newNameThe new name of the file (absolute path)
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success true is retured; otherwise false.

Code Example

if (FileSystem::FileExists("/path/myPbx.txt", log_instance)) {
    FileSystem::Rename("/path/myPbx.txt", "/path/myApps.txt", log_instance);
}
RemoveFile (static function)
Removes a file.

Parameters

const char * filenameThe absolute path of the file to be removed
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success true is retured; otherwise false.
CreateDirectory (static function)
Creates a directory.

Parameters

const char * absolutePathThe absolute path of the directory to be created
int modeThe mode to set the file permission bits
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success true is retured; otherwise false.

Code Example

//mode 0755 defined as rwxr-xr-x 
FileSystem::CreateDirectory("/home/new", 0755, log)
RemoveDirectory (static function)
Removes a directory. If the directory is not empty, all included directories and files are deleted as well.

Parameters

const char * directoryPathThe absolute path of the directory to be removed
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success true is retured; otherwise false.
ChangeOwner (static function)
Changes the owner and group of the directory specified by an absolute path.

Parameters

const char * pathThe absolute path of the directory
const char * newOwnerThe new owner of the directory
const char * newGroupThe new group of the directory
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success true is retured; otherwise false.
ChangeMode (static function)
Changes the mode of a file.

Parameters

const char * pathThe absolute path of the directory to be removed
int modeThe new mode of the file
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success true is retured; otherwise false.

Code Example

FileSystem::ChangeMode("/directory", 0744, log);
GetFileSystemTotalSize (static function)
Returns the total size of the file system in bytes.

Parameters

const char * pathThe absolute path of the directory to be removed
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success the size is returned in bytes; otherwise -1.

Code Example

ulong64 totalSize = FileSystem::GetFileSystemTotalSize("/mnt/sda1", log);
GetFileSystemUsedSpace (static function)
Returns the total used space of the file system in bytes.

Parameters

const char * pathThe absolute path of the directory to be removed
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success the size is returned in bytes; otherwise -1.
CheckSystemUser (static function)
Checks if a system user and group exist.

Parameters

const char * userThe system user
const char * groupThe system group
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

If the user and group are available to use, true is returned; otherwise false.
GetFileSystemUser (static function)
Returns the system user of a file.

Parameters

const char * filepathThe absolute path of the file
class IInstanceLog * logThe IInstanceLog instance used for loging purposes.

Return value

On success, returns the system user; otherwise 0.

IFileWrite

class IFileWrite {
public:
    ~IFileWrite() {};
    bool IsOpen();
    bool Write(const void * buffer, size_t len);
    void Flush();
    bool Close();
};

Overview

An instance of this class is created after a call to FileSystem::OpenWriteFile

Logging

To enable logging for File interface, the flag LOG_FILE must be set in the managers diagnostic settings.

Public functions

IsOpen
Checks if the file is opened.

Return value

Returns true if the file is opened successfully; otherwise false.
Write
Writes the buffer with a size len into the file.

Parameters

const void * bufferThe buffer to be written
size_t lenThe length of the buffer

Return value

Returns true if the write operation was successful; otherwise false.
Flush (static function)
Flushes the stream opened for writing any unwritten data
Close
Close the file after writing is finished. After the write operation is completed, a call to Close() should be performed explicitly.

Return value

Returns true if the the file was closed successfully; otherwise false.

Code Example

bool append = false;
class IFileWrite * file = FileSystem::OpenWriteFile("file.txt", append, log);
file->Write(buffer, strlen(buffer));
file->Close();
delete file;

IFileRead

class IFileRead {
public:
    virtual ~IFileRead() {};
    bool IsOpen();
    size_t Read(void * buffer, size_t len);
    bool Close();
};

Overview

An instance of this class is created after a call to FileSystem::OpenReadFile

Logging

To enable logging for File interface, the flag LOG_FILE must be set in the managers diagnostic settings.

Public functions

IsOpen
Checks if the file is opened.

Return value

Returns true if the file is opened successfully; otherwise false.
Read
Reads the file into the buffer.

Parameters

void * bufferThe buffer to read the file into
size_t lenThe length of the buffer

Return value

Returns the count of the written bytes in the buffer.
Close
Close the file after writing is finished. After the last read operation is completed, a call to Close() should be performed explicitly.

Return value

Returns true if the the file was closed successfully; otherwise false.

IDirectory

class IDirectory {
public:
    ~IDirectory() {};
    bool IsOpen() const;
    class IDirectoryEntry * ReadNext();
    bool Close();
};

Overview

An instance of this class is created after a call to FileSystem::OpenDirectory. The directory is opened and the first entry is ready to be read.

Logging

To enable logging for File interface, the flag LOG_FILE must be set in the managers diagnostic settings.

Public functions

IsOpen
Checks if the directory is opened.

Return value

Returns true if the directory is opened successfully; otherwise false.
ReadNext
Starts reading the first entry of the directory. This function iterates through the whole directory till end of the directory is reached or if an error occurs.

Return value

An instance of class DirectoryEntry is returned specifying whether the entry is a regular file or a directory. NULL is returned on error or if the end of directory is reached.
Close
Closes the associated directory. A call to Close() should be done explicitly after reading is done.

Return value

Returns true if the the directory was closed successfully; otherwise false.

Code Example

class IDirectory * dir = FileSystem::OpenDirectory("/directory", log);
class IDirectoryEntry * entry;
while ((entry = dir->ReadNext())) {
    ......
    ......
    delete entry;
}
dir->Close();
delete dir;

IDirectoryEntry

class IDirectoryEntry {
public:
    ~IDirectoryEntry() {};
    const char * GetName() const ;
    bool IsFile() const ;
};

Overview

An instance of this class is created after every ReadNext() function call. After this object is no longer needed, it should be deleted.

Logging

To enable logging for File interface, the flag LOG_FILE must be set in the managers diagnostic settings.

Public functions

GetName
Reads the name of the directory entry.

Return value

Returns the name read.
IsFile
Checks if the directory entry is a regular file.

Return value

Returns true if the read directory entry is a regular file or false if the entry is a directory.

IElfBinary

class IElfBinary {
public:
    ~IElfBinary() {};
    bool IsOpen() ;
    bool IsElfBinary() ;
    bool IsExecutable() ;
    elf_architecture_t GetArchitecture() ;
    bool Close() ;
};

Overview

An instance of this class is created after a call to FileSystem::OpenElfBinary(). After this object is no longer needed, it should be deleted.

Logging

To enable logging for File interface, the flag LOG_FILE must be set in the managers diagnostic settings.

Public functions

IsOpen
Check if the binary file is opened.

Return value

Returns true if the file is successfully opened.
IsElfBinary
Checks whether the file is a valid ELF binary. The header of the binary is read the magic number is checked.

Return value

Returns true if the binary is a valid ELF binary.
IsExecutable
Checks whether the file is an executible ELF binary.

Return value

Returns true if the binary is executable; otherwise false.
GetArchitecture
Returns the architecture of the ELF binary. The types checked are ARM, ARM64 and X86_64 only.

Return value

Returns the architecture in the enum elf_architecture_t.
Close
Closes the binary file.

Return value

Returns true if the the directory was closed successfully; otherwise false.

enum elf_architecture_t

typedef enum {
    ELF_UNKOWN,
    ELF_ARM,
    ELF_X86_64,
    ELF_ARM64
} elf_architecture_t;