Module file

[Main Page] [Details] [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:

readfile (version 3)
void *file::readfile(FILE *f,char *data)

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

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

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

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

Static Template Methods:

openfile

openfile (version 1)
FILE *file::openfile(const char *filename)

openfile (version 2)
FILE *file::openfile(const char *filename,const char *mode)

openfile (version 3)
FILE *file::openfile(const char *path,const char *filename,const char *mode)

readfile

readfile (version 1)
void *file::readfile(const char *filename,unsigned int *length)

readfile (version 2)
void *file::readfile(const char *filename,char *data)

writefile

writefile (version 1)
bool file::writefile(const char *filename,void *data,unsigned int length)

More output functions:

appendfile
bool file::appendfile(const char *filename,void *data,unsigned int length)

write_newfile
char *file::write_newfile(const char *filename,void *data,unsigned int length)

remove

remove
bool file::remove(const char *filename)

remove_clean
bool file::remove_clean(const char *filename)

testfile

testfile
bool file::testfile(const char *path)

testfile_open
bool file::testfile_open(const char *path)

rwfile
bool file::rwfile(const char *filename,unsigned int rep,bool dodelete)

compare
bool file::compare(const char *path_a,const char *path_b)

get_time_write
time_t file::get_time_write(const char *filename)

get_size
unsigned long int file::get_size(const char *filename)

copyfile

copyfile (version 1)
bool file::copyfile(const char *targetpath,const char *sourcepath)

copyfile (version 2)
bool file::copyfile(const char *targetpath,const char *sourcepath,const char *filename)

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

copyfile (version 6)
bool file::copyfile(const char *targetpath,const char *sourcepath,const char *filename,CondCopyControl< char > *ccc)

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

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

Interfaces

CondCopyControl

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.

About text mode: Although text-mode is intended to increase portability, it introduces system specific behaviour. Creating a text file using text mode can improve the readability of this file by other programs on the same system. But when exchanging files across different systems, text mode can cause problems. Correct interpretation of the file may require information about the system on which the file has been created.
Because text mode is system specific, you can not know what output it really generates when your program is compiled and run on an unknown system.

Static Methods

readfile (version 3)

Reads the contents of a file into the memory.

Signature:

void *file::readfile(FILE *f,char *data)

Parameters:

FILE *	f	[IN]	A pointer to the file-handle of the opend file.
char *	data	[OUT]	The buffer that receives the read bytes.

Return value:
A pointer to the Buffer.

Remarks:

Take care to provide a large enough buffer.

The application has to free the returned buffer.

writefile (version 2)

Writes the content from a buffer to a file.

Signature:

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

Parameters:

FILE *	f	[IN]	A pointer to the file-handle of the opend file.
void *	data	[IN]	The buffer that holds the content to be written to the file.
unsigned int	length		The number of bytes to be written.

writefile (version 3)

Writes the content from a buffer to a file.

Signature:

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

Parameters:

int	f		Specifies the opened file by its file descriptor.
void *	data	[IN]	The buffer that holds the content to be written to the file.
unsigned int	length		The number of bytes to be written.

Remarks:

The file descriptor can be obtained from the open() system call. (You can use for 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.

copyfile (version 3)

Copies a file.

Signature:

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

Parameters:

FILE *	targetfile	[IN]
FILE *	sourcefile	[IN]

Required code:

function pathtype from module path (version 1 - 0)
function fnopath from module path (version 1 - 0)

copyfile (version 4)

Copies a file.

Signature:

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

Parameters:

int	targetfile
int	sourcefile

Required code:

function pathtype from module path (version 1 - 0)
function fnopath from module path (version 1 - 0)

Static Template Methods

openfile (version 1)

Opens a file.

Signature:

FILE *file::openfile(const char *filename)

Parameters:

const char *

filename

[IN]

The filename (as null-terminated string). The filename may optionally include a path.

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

Remarks:

The file will be opened for input with mode rb.

Close the file-handle f of a successfully opened file with fclose(f).

openfile (version 2)

Opens a file.

Signature:

FILE *file::openfile(const char *filename,const char *mode)

Parameters:

const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.
const char *	mode	[IN]	The file access mode (as null-terminated string). See the section about file access modes.

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

Remarks:

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

Close the file-handle f of a successfully opened file with fclose(f).

Required code:

function createdir from module dir (version 1 - 0)

openfile (version 3)

Opens a file.

Signature:

FILE *file::openfile(const char *path,const char *filename,const char *mode)

Parameters:

const char *	path	[IN]	The path (as null-terminated string).
const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.
const char *	mode	[IN]	The file access mode (as null-terminated string). See the section about file access modes.

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

Remarks:

The file-path is built by concatenating path and filename. Mind the importance of the /-symbol at the end of the path. F.e. if path is set to "C:/Users/Daniel" and filename is set to "myfile.txt", the concatenation would give "C:/Users/Danielmyfile.txt". To avoid this, always have a / (or \) at the end of the path: "C:/Users/Daniel/".

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

Close the file-handle f of a successfully opened file with fclose(f).

Required code:

function createdir from module dir (version 1 - 0)

readfile (version 1)

Reads the contents of a file into the memory.

Signature:

void *file::readfile(const char *filename,unsigned int *length)

Parameters:

const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.
unsigned int *	length	[OUT]	Receives the length (size) of the file.

Return value:
A pointer to the buffer, which receives the contents of the file. The function returns 0, if the file could not be opened or read.

Remarks:

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

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

The application has to free the returned buffer.

readfile (version 2)

Reads the contents of a file into the memory.

Signature:

void *file::readfile(const char *filename,char *data)

Parameters:

const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.
char *	data	[OUT]	The buffer that receives the read bytes.

Return value:
A pointer to the Buffer.

Remarks:

Take care to provide a large enough buffer.

The application has to free the returned buffer.

writefile (version 1)

Writes the content from a buffer to a file.

Signature:

bool file::writefile(const char *filename,void *data,unsigned int length)

Parameters:

const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.
void *	data	[IN]	The buffer that holds the content to be written to the file.
unsigned int	length		The number of bytes to be written.

Return value:
Returns true if successful (otherwise false).

Remarks:

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

The function will try to create any missing directories on the path.

appendfile

Appends the content from a buffer to an existing file.

Signature:

bool file::appendfile(const char *filename,void *data,unsigned int length)

Parameters:

const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.
void *	data	[IN]	The buffer that holds the content to be written to the file.
unsigned int	length		The number of bytes to be written.

Return value:
Returns true if successful (otherwise false).

Remarks:

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

The function will try to create any missing directories on the path.

write_newfile

Writes the content from a buffer to a new file.

Signature:

char *file::write_newfile(const char *filename,void *data,unsigned int length)

Parameters:

const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.
void *	data	[IN]	The buffer that holds the content to be written to the file.
unsigned int	length		The number of bytes to be written.

Remarks:

The function will try to create any missing directories on the path.

Required code:

function dnopath from module path (version 1 - 0)
function fnopath from module path (version 1 - 0)
function sxopath from module path (version 1 - 0)

remove

Removes a file.

Signature:

bool file::remove(const char *filename)

Parameters:

const char *

filename

[IN]

The filename (as null-terminated string). The filename may optionally include a path.

Return value:
Returns true if successful (otherwise false).

remove_clean

Removes a file.

Signature:

bool file::remove_clean(const char *filename)

Parameters:

const char *

filename

[IN]

The filename (as null-terminated string). The filename may optionally include a path.

Return value:
Returns true if successful (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)

testfile

Tests, if a file exists.

Signature:

bool file::testfile(const char *path)

Parameters:

const char *

path

[IN]

The path (as null-terminated string).

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

testfile_open

Tests, if a file exists.

Signature:

bool file::testfile_open(const char *path)

Parameters:

const char *

path

[IN]

The path (as null-terminated string).

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

rwfile

Signature:

bool file::rwfile(const char *filename,unsigned int rep,bool dodelete)

Parameters:

const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.
unsigned int	rep		rep
bool	dodelete		dodelete

compare

Compares two files.

Signature:

bool file::compare(const char *path_a,const char *path_b)

Parameters:

const char *	path_a	[IN]	The path (as null-terminated string).
const char *	path_b	[IN]	The path (as null-terminated string).

get_time_write

Compares two files.

Signature:

time_t file::get_time_write(const char *filename)

Parameters:

const char *

filename

[IN]

The filename (as null-terminated string). The filename may optionally include a path.

get_size

Compares two files.

Signature:

unsigned long int file::get_size(const char *filename)

Parameters:

const char *

filename

[IN]

The filename (as null-terminated string). The filename may optionally include a path.

copyfile (version 1)

Copies a file.

Signature:

bool file::copyfile(const char *targetpath,const char *sourcepath)

Parameters:

const char *	targetpath	[IN]	The path (as null-terminated string).
const char *	sourcepath	[IN]	The path (as null-terminated string).

Required code:

function pathtype from module path (version 1 - 0)
function fnopath from module path (version 1 - 0)

copyfile (version 2)

Copies a file.

Signature:

bool file::copyfile(const char *targetpath,const char *sourcepath,const char *filename)

Parameters:

const char *	targetpath	[IN]	The path (as null-terminated string).
const char *	sourcepath	[IN]	The path (as null-terminated string).
const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.

Required code:

function pathtype from module path (version 1 - 0)
function fnopath from module path (version 1 - 0)

copyfile (version 5)

Copies a file.

Signature:

bool file::copyfile(const char *targetpath,const char *sourcepath,CondCopyControl< char > *ccc)

Parameters:

const char *	targetpath	[IN]	The path (as null-terminated string).
const char *	sourcepath	[IN]	The path (as null-terminated string).
CondCopyControl< char > *	ccc	[IN]	Pointer to an instance of an implementation of CondCopyControl. See file:CondCopyControl.

Required code:

function pathtype from module path (version 1 - 0)
function fnopath from module path (version 1 - 0)

copyfile (version 6)

Copies a file.

Signature:

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

Parameters:

const char *	targetpath	[IN]	The path (as null-terminated string).
const char *	sourcepath	[IN]	The path (as null-terminated string).
const char *	filename	[IN]	The filename (as null-terminated string). The filename may optionally include a path.
CondCopyControl< char > *	ccc	[IN]	Pointer to an instance of an implementation of CondCopyControl. See file:CondCopyControl.

Required code:

function pathtype from module path (version 1 - 0)
function fnopath from module path (version 1 - 0)

copyfile (version 7)

Copies a file.

Signature:

size_t file::copyfile(FILE *targetfile,FILE *sourcefile,CondCopyControl< char > *ccc)

Parameters:

FILE *	targetfile	[IN]
FILE *	sourcefile	[IN]
CondCopyControl< char > *	ccc	[IN]	Pointer to an instance of an implementation of CondCopyControl. See file:CondCopyControl.

Required code:

function pathtype from module path (version 1 - 0)
function fnopath from module path (version 1 - 0)

copyfile (version 8)

Copies a file.

Signature:

size_t file::copyfile(int targetfile,int sourcefile,CondCopyControl< char > *ccc)

Parameters:

int	targetfile
int	sourcefile
CondCopyControl< char > *	ccc	[IN]	Pointer to an instance of an implementation of CondCopyControl. See file:CondCopyControl.

Required code:

function pathtype from module path (version 1 - 0)
function fnopath from module path (version 1 - 0)