Module file [Version: v01]

[Documentation]

[Details]

[Wiki]

[Tests]

[CondCopyControl]

This documentation describes the Prokee module interface.

Templates

Show templates with parameter T set to: (T) -- (char) -- (wchar_t)

Use the char - versions for ANSI and UTF-8 encoded Strings.
The wchar_t - versions are only available on Windows operating systems.

Static Methods:

copyfile (version 3)
bool file::copyfile(FILE *targetfile,FILE *sourcefile)

copyfile (version 4)
bool file::copyfile(int targetfile,int sourcefile)

readfile (version 3)
void *file::readfile(FILE *f,void *data,unsigned int *length)

writefilef (version 2)
int file::writefilef(FILE *f,void *data,unsigned int length)

writefilef (version 3)
int file::writefilef(int f,void *data,unsigned int length)

getblocksize
int file::getblocksize(FILE *f)

Static Template Methods:

openfile (version 3)
template< class T > FILE *file::openfile(const T *path,const T *filename,const T *mode)

openfile (version 2)
template< class T > FILE *file::openfile(const T *filename,const T *mode)

openfile

openfile (version 1)
template< class T > FILE *file::openfile(const T *filename)

readfile

readfile (version 1)
template< class T > void *file::readfile(const T *filename,unsigned int *length)

readfile_as_string
template< class T > char *file::readfile_as_string(const T *filename,unsigned int *length)

readfile (version 2)
template< class T > void *file::readfile(const T *filename,void *data,unsigned int *length)

writefile

writefile (version 1)
template< class T > bool file::writefile(const T *filename,void *data,unsigned int length)

More output functions:

appendfile
template< class T > bool file::appendfile(const T *filename,void *data,unsigned int length)

write_newfile
template< class T > T *file::write_newfile(const T *filename,void *data,unsigned int length)

rwfile
template< class T > bool file::rwfile(const T *filename,unsigned int r,bool d)

testfile_open
template< class T > bool file::testfile_open(const T *path)

testfile

testfile
template< class T > bool file::testfile(const T *path)

copyfile

copyfile (version 1)
template< class T > bool file::copyfile(const T *targetpath,const T *sourcepath)

copyfile (version 2)
template< class T > bool file::copyfile(const T *targetpath,const T *sourcepath,const T *filename)

copyfile (version 5)
template< class T > bool file::copyfile(const T *targetpath,const T *sourcepath,CondCopyControl< T > *ccc)

copyfile (version 6)

template< class T > bool file::copyfile(const T *targetpath,const T *sourcepath,const T *filename,CondCopyControl< T > *ccc)

copyfile (version 7)
template< class T > size_t file::copyfile(FILE *targetfile,FILE *sourcefile,CondCopyControl< T > *ccc)

copyfile (version 8)
template< class T > size_t file::copyfile(int targetfile,int sourcefile,CondCopyControl< T > *ccc)

compare
template< class T > bool file::compare(const T *path_to_file_a,const T *path_to_file_b)

get_time_write
template< class T > time_t file::get_time_write(const T *filename)

get_size
template< class T > unsigned long int file::get_size(const T *filename)

remove

remove
template< class T > bool file::remove(const T *filename)

remove_clean
template< class T > bool file::remove_clean(const T *filename)

Motivation

File access modes

You can use the following access modes, when opening a file:

Mode	Direction	Info
r	input	The file must exist.
r+	input and output	The file must exist.
w	output	The file will be created. The contents of an existing file will be discarded.
w+	input and output	The file will be created. The contents of an existing file will be discarded.
a	output	The file will be created if it does not jet exist. The output will be appended on the end of the file.
a+	input and output	The file will be created if it does not jet exist. The output will be appended on the end of the file.
rt, r+t, rt+, wt, w+t, wt+, at, a+t, at+	--	Specifying the 'text' mode, by adding a 't' has no effect, because this is the default mode according to the C standard.
rb, r+b, rb+, wb, w+b, wb+, ab, a+b, ab+	--	When adding a 'b', the file will be opened in 'binary' mode, meaning that every byte is read (or written) as it is indeed stored in the file. There is no conversion of special characters.

Static Methods

copyfile (version 3)

Copies a file.

Signature:

bool file::copyfile(FILE *targetfile,FILE *sourcefile)

Parameters:

Type	Name	Direction	Description
FILE *	targetfile	[IN]	File handle of the target file.
FILE *	sourcefile	[IN]	File handle of the source file.

Required code:

function pathtype from module path (version 1 - 0 -- default: v01)

function fnopath from module path (version 1 - 0 -- default: v01)

copyfile (version 4)

Copies a file.

Signature:

bool file::copyfile(int targetfile,int sourcefile)

Parameters:

Type	Name	Direction	Description
int	targetfile		File descriptor of the target file.
int	sourcefile		File descriptor of the source file.

Required code:

function pathtype from module path (version 1 - 0 -- default: v01)

function fnopath from module path (version 1 - 0 -- default: v01)

readfile (version 3)

Copies the contents of a file into memory.

Reads the contents of file f from the current reading position until EOF (end of file) is reached.

Signature:

void *file::readfile(FILE *f,void *data,unsigned int *length)

Parameters:

Type	Name	Direction	Description
FILE *	f	[IN]	The file handle of a opend file as returned by `openfile()`.
void *	data	[OUT]	The memory block that receives the read bytes.
unsigned int *	length	[OUT]	Receives the number of bytes read.

Return value:
Returns data. (The pointer to the memory block, which received the contents of the file)

Remarks:

Take care to provide a large enough memory block.

writefilef (version 2)

Writes the contents of a memory block to a file.

Signature:

int file::writefilef(FILE *f,void *data,unsigned int length)

Parameters:

Type	Name	Direction	Description
FILE *	f	[IN]	The file handle of a opend file as returned by `openfile()`.
void *	data	[IN]	A Pointer to the memory block, that holds the contents to be written.
unsigned int	length		The number of bytes to be written.

Return value:
The number of bytes successfully written.

writefilef (version 3)

Writes the contents of a memory block to a file.

Signature:

int file::writefilef(int f,void *data,unsigned int length)

Parameters:

Type	Name	Direction	Description
int	f		A valid file descriptor of a opened file.
void *	data	[IN]	A Pointer to the memory block, that holds the contents to be written.
unsigned int	length		The number of bytes to be written.

Return value:
The number of bytes successfully written.

Remarks:

The file descriptor can be obtained from the system call open(). (You can use 0 for stdin, 1 for stdout and 2 for stderr.)

You should not use this version of the function unless you have reason to. This version uses write(int f,...) instead of fwrite(FILE *f,...). The system call write() is unbuffered and may significantly slow down your application. Also mind that write() is not part of the ISO C standard and may be missing or implemented differently on non POSIX operating systems.

getblocksize

getblocksize

This is not jet implemented!

Signature:

int file::getblocksize(FILE *f)

Parameters:

Type	Name	Direction	Description
FILE *	f	[IN]	The file handle of a opend file as returned by `openfile()`.

Return value:
The block size of the file/device.

Static Template Methods

openfile (version 3)

Opens a file.

The path to the file is constracted by concatenating path with filename. (The last character of path should always be '/' (or '\' on Windows).

Signature:

template< class T > FILE *file::openfile(const T *path,const T *filename,const T *mode)

Parameters:

Type	Name	Direction	Description
const T *	path	[IN]	A null-terminated string containing the path to the directory of the file.
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
const T *	mode	[IN]	The file access mode (has to be a null-terminated string). See the section about file access modes.

Return value:
A pointer to the file-handle of the opened file or NULL if the file could not be opened.

Remarks:

When opening a file for output (with mode set to w... or a...) the function will try to create any missing directories.

If a file is successfully opened, it should be closed by calling fclose(f), where f is the file handle returned by openfile().

Required code:

function createdir from module dir (version 1 - 0 -- default: v01)

openfile (version 2)

Opens a file.

Signature:

template< class T > FILE *file::openfile(const T *filename,const T *mode)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
const T *	mode	[IN]	The file access mode (has to be a null-terminated string). See the section about file access modes.

Return value:
A pointer to the file-handle of the opened file or NULL if the file could not be opened.

Remarks:

When opening a file for output (with mode set to w... or a...) the function will try to create any missing directories.

If a file is successfully opened, it should be closed by calling fclose(f), where f is the file handle returned by openfile().

Required code:

function createdir from module dir (version 1 - 0 -- default: v01)

openfile (version 1)

Opens a file.

Signature:

template< class T > FILE *file::openfile(const T *filename)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)

Return value:
A pointer to the file-handle of the opened file or NULL if the file could not be opened.

Remarks:

The file will be opened for input with mode rb.

If a file is successfully opened, it should be closed by calling fclose(f), where f is the file handle returned by openfile().

readfile (version 1)

Copies the contents of a file into memory.

Signature:

template< class T > void *file::readfile(const T *filename,unsigned int *length)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
unsigned int *	length	[OUT]	Receives the length (size in bytes) of the file.

Return value:
A pointer to the memory block, which received the contents of the file. The function returns NULL, if the file could not be opened.

Remarks:

If the file could not be opened or read (and length is not set to NULL), the function will set *length to 0. Otherwise *length will be set to the length (size in bytes) of the file.

If you do not require information about the size of the file, length can be set to NULL.

The application has to free the returned memory.

readfile_as_string

Copies the contents of a file into memory.

This function returns the contents of the file as a null-terminated string. This can be useful, when reading a text file. A 0-byte is added at the end of the data by this function.

Signature:

template< class T > char *file::readfile_as_string(const T *filename,unsigned int *length)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
unsigned int *	length	[OUT]	Receives the length (size in bytes) of the file.

Return value:
A pointer to the memory block, which received the null-terminated contents of the file. The function returns NULL, if the file could not be opened.

Remarks:

If the file could not be opened or read (and length is not set to NULL), the function will set *length to 0. Otherwise *length will be set to the length (size in bytes) of the file.

If you do not require information about the size of the file, length can be set to NULL.

The application has to free the returned memory.

readfile (version 2)

Copies the contents of a file into memory.

Signature:

template< class T > void *file::readfile(const T *filename,void *data,unsigned int *length)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
void *	data	[OUT]	The memory block that receives the read bytes.
unsigned int *	length	[OUT]	Receives the length (size in bytes) of the file.

Return value:
A pointer to the memory block, which received the contents of the file. The function returns NULL, if the file could not be opened.

Remarks:

Take care to provide a large enough memory block.

writefile (version 1)

Writes the contents of a memory block to a file.

Signature:

template< class T > bool file::writefile(const T *filename,void *data,unsigned int length)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
void *	data	[IN]	A Pointer to the memory block, that holds the contents to be written.
unsigned int	length		The number of bytes to be written.

Return value:
Returns true on successful execution (or otherwise false).

Remarks:

If the file does not exist jet, it will be created. An already existing file will be overwritten.

The function will try to create any missing directories.

appendfile

Appends the content from a memory block to an existing file.

Signature:

template< class T > bool file::appendfile(const T *filename,void *data,unsigned int length)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
void *	data	[IN]	A Pointer to the memory block, that holds the contents to be written.
unsigned int	length		The number of bytes to be written.

Return value:
Returns true on successful execution (or otherwise false).

Remarks:

If the file does not jet exist, it will be created.

The function will try to create any missing directories.

write_newfile

Writes the content from a memory block to a new file.

If the file, specified by filename already exists, the function will create a new file, by appending a number to the filename. F.e. if the file myfile.txt already exists, then the function will create the file myfile_(0000).txt. In the case, that this file also already exists, the function would create a file with the name myfile_(0001).txt and so on.

Signature:

template< class T > T *file::write_newfile(const T *filename,void *data,unsigned int length)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
void *	data	[IN]	A Pointer to the memory block, that holds the contents to be written.
unsigned int	length		The number of bytes to be written.

Remarks:

The function will try to create any missing directories.

Required code:

function dnopath from module path (version 1 - 0 -- default: v01)

function fnopath from module path (version 1 - 0 -- default: v01)

function sxopath from module path (version 1 - 0 -- default: v01)

rwfile

Writes pseudo random bytes to a file

Signature:

template< class T > bool file::rwfile(const T *filename,unsigned int r,bool d)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
unsigned int	r
bool	d

Return value:
Returns true on successful execution (or otherwise false).

testfile_open

Tests, if a file exists.

The function tries to open the file and returnes true, if this is successful. The function immediatly closes the file after opening it.

Signature:

template< class T > bool file::testfile_open(const T *path)

Parameters:

Type	Name	Direction	Description
const T *	path	[IN]	A null-terminated string containing the path to the directory of the file.

Return value:
Returns true if the file exists and can be opened (or otherwise false).

testfile

Tests, if a file exists.

Signature:

template< class T > bool file::testfile(const T *path)

Parameters:

Type	Name	Direction	Description
const T *	path	[IN]	A null-terminated string containing the path to the file.

Return value:
Returns true if the file exists (or otherwise false).

copyfile (version 1)

Copies a file.

Signature:

template< class T > bool file::copyfile(const T *targetpath,const T *sourcepath)

Parameters:

Type	Name	Direction	Description
const T *	targetpath	[IN]	The null-terminated path to the target file.
const T *	sourcepath	[IN]	The null-terminated path to the source file.

Required code:

function pathtype from module path (version 1 - 0 -- default: v01)

function fnopath from module path (version 1 - 0 -- default: v01)

copyfile (version 2)

Copies a file.

Signature:

template< class T > bool file::copyfile(const T *targetpath,const T *sourcepath,const T *filename)

Parameters:

Type	Name	Direction	Description
const T *	targetpath	[IN]	The null-terminated path to the target file.
const T *	sourcepath	[IN]	The null-terminated path to the source file.
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)

Required code:

function pathtype from module path (version 1 - 0 -- default: v01)

function fnopath from module path (version 1 - 0 -- default: v01)

copyfile (version 5)

Copies a file.

Signature:

template< class T > bool file::copyfile(const T *targetpath,const T *sourcepath,CondCopyControl< T > *ccc)

Parameters:

Type	Name	Direction	Description
const T *	targetpath	[IN]	The null-terminated path to the target file.
const T *	sourcepath	[IN]	The null-terminated path to the source file.
CondCopyControl< T > *	ccc	[IN]	Pointer to an instance of an implementation of CondCopyControl. See file:CondCopyControl.

Required code:

function pathtype from module path (version 1 - 0 -- default: v01)

function fnopath from module path (version 1 - 0 -- default: v01)

copyfile (version 6)

Copies a file.

Signature:

template< class T > bool file::copyfile(const T *targetpath,const T *sourcepath,const T *filename,CondCopyControl< T > *ccc)

Parameters:

Type	Name	Direction	Description
const T *	targetpath	[IN]	The null-terminated path to the target file.
const T *	sourcepath	[IN]	The null-terminated path to the source file.
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)
CondCopyControl< T > *	ccc	[IN]	Pointer to an instance of an implementation of CondCopyControl. See file:CondCopyControl.

Required code:

function pathtype from module path (version 1 - 0 -- default: v01)

function fnopath from module path (version 1 - 0 -- default: v01)

copyfile (version 7)

Copies a file.

Signature:

template< class T > size_t file::copyfile(FILE *targetfile,FILE *sourcefile,CondCopyControl< T > *ccc)

Parameters:

Type	Name	Direction	Description
FILE *	targetfile	[IN]	File handle of the target file.
FILE *	sourcefile	[IN]	File handle of the source file.
CondCopyControl< T > *	ccc	[IN]	Pointer to an instance of an implementation of CondCopyControl. See file:CondCopyControl.

Required code:

function pathtype from module path (version 1 - 0 -- default: v01)

function fnopath from module path (version 1 - 0 -- default: v01)

copyfile (version 8)

Copies a file.

Signature:

template< class T > size_t file::copyfile(int targetfile,int sourcefile,CondCopyControl< T > *ccc)

Parameters:

Type	Name	Direction	Description
int	targetfile		File descriptor of the target file.
int	sourcefile		File descriptor of the source file.
CondCopyControl< T > *	ccc	[IN]	Pointer to an instance of an implementation of CondCopyControl. See file:CondCopyControl.

Required code:

function pathtype from module path (version 1 - 0 -- default: v01)

function fnopath from module path (version 1 - 0 -- default: v01)

compare

Compares two files.

Signature:

template< class T > bool file::compare(const T *path_to_file_a,const T *path_to_file_b)

Parameters:

Type	Name	Direction	Description
const T *	path_to_file_a	[IN]	A null-terminated path to a file.
const T *	path_to_file_b	[IN]	A null-terminated path to a file.

Return value:
If both files are equal, the function returns true. Otherwise the funtion returnes false. In case of any errors, i.e if a file could not be opend, the function also returnes false.

get_time_write

Returnes the time when a file has been last modified.

Signature:

template< class T > time_t file::get_time_write(const T *filename)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)

Return value:
The time value.

get_size

Returnes the size in bytes of a file.

Signature:

template< class T > unsigned long int file::get_size(const T *filename)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)

Return value:
The size of the file in bytes.

remove

Removes a file.

Signature:

template< class T > bool file::remove(const T *filename)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)

Return value:
Returns true on successful execution (or otherwise false).

remove_clean

Removes a file.

Signature:

template< class T > bool file::remove_clean(const T *filename)

Parameters:

Type	Name	Direction	Description
const T *	filename	[IN]	The null-terminated filename. (The filename may optionally include a path.)

Return value:
Returns true on successful execution (or otherwise false).

Remarks:

When the deletion of a file results in an empty directory, the function attempts to delete this directory and any empty parent directory.

Required code:

function pnopath from module path (version 1 - 0 -- default: v01)