API

cole Library Reference Manual
Prev		Next

Details

COLE_MAJOR_VERSION

#define COLE_MAJOR_VERSION 2

COLE_MINOR_VERSION

#define COLE_MINOR_VERSION 0

COLE_MICRO_VERSION

#define COLE_MICRO_VERSION 1

cole_major_version

extern int cole_major_version;

cole_minor_version

extern int cole_minor_version;

cole_micro_version

extern int cole_micro_version;

cole_version

extern char *cole_version;

cole_host_info

extern char *cole_host_info;

enum COLERRNO

enum COLERRNO {
/* & = means that you can use perror(3) call to print an error message */
/* you can always use cole_perror to print an error message */
	COLE_EFIRST,		/* Leave this at first place */
/*&*/	COLE_EMEMORY,		/* Failed malloc(3) or realloc(3) */
/*&*/	COLE_EOPENFILE,		/* Failed fopen(3) */
/*&*/	COLE_ECLOSEFILE,	/* Failed fclose(3) */
/*&*/	COLE_EREAD,		/* Failed fread(3) */
/*&*/	COLE_EWRITE,		/* Failed fwrite(3) */
/*&*/	COLE_EREMOVE,		/* Failed remove(3) */
/*&*/	COLE_ETMPNAM,		/* Failed tmpnam(3) */
/*&*/	COLE_ESEEK,		/* Failed fseek(3) */
/*&*/	COLE_EERRNO,		/* Some system call failed */
	COLE_ENOFILESYSTEM,	/* File is not a filesystem */
	COLE_EINVALIDFILESYSTEM,/* Filesystem is broken, it's invalid */
	COLE_EISNOTDIR,		/* Directory entry is not a directory */
	COLE_EISNOTFILE,	/* Directory entry is not a file */
	COLE_EFILENOTFOUND,	/* Doesn't exist a file with the given name */
	COLE_EOF,		/* End of file has been reached */
	COLE_EMEMBERISNOTDIR,	/* A member of the filename is not
				   a directory */
	COLE_EBROKENFILENAME,	/* The filename is not right written */
	COLE_EFILENAMEISNOTFILE,/* Filename is not a file */
	COLE_EFSEEKDELTA,	/* Delta argument is not valid */
	COLE_EFSEEKFLAG,	/* Flag argument is not valid */
	COLE_EUNKNOWN,		/* An unknown error ocurred, can be a bug */
	COLE_ELAST		/* Leave this at last place */
};

cole_perror ()

void        cole_perror                     (const char *s,
                                             COLERRNO colerrno);

Prints a message on the standard error output, describing the error colerrno, preceding it with the string s, a semicolon and a space. It handles COLE_EERRNO value too, calling perror(3).

`s` :	string to print before the error message. It can be NULL.
`colerrno` :	error value of which a message will be printed.

struct COLEFS

struct COLEFS {
	/* This structure is for internal use only, not for the public API */
	pps_entry *tree;
	U32 root;			/* entry root, root pps_entry */
	U8 *BDepot;
	U8 *SDepot;
	FILE *sbfile;
	char *sbfilename;
	FILE *file;			/* actual file (the filesystem) */
};

struct COLEDIR

struct COLEDIR {
	/* This structure is for internal use only, not for the public API */
	U32 entry;
	struct _COLEDIRENT visited_entry;
	struct _COLEFS *fs;		/* father */
};

struct COLEDIRENT

struct COLEDIRENT {
	/* This structure is for internal use only, not for the public API */
	U32 entry;
	struct _COLEDIR *dir;		/* father */
};

struct COLEFILE

struct COLEFILE {
	/* This structure is for internal use only, not for the public API */
	U32 entry;
	FILE *file;			/* actual extracted file */
	char *filename;			/* actual extracted file's name */
	U32 filesize;			/* actual extracted file size */
	struct _COLEFS *fs;		/* father */
	U32 pos;			/* file pointer position */
};

cole_mount ()

COLEFS*     cole_mount                      (char *filename,
                                             COLERRNO *colerrno);

Mounts the filesystem which is in filename.

`filename` :	name of the file with the filesystem.
`colerrno` :	error value (COLE_EMEMORY, COLE_EOPENFILE, COLE_ENOFILESYSTEM, COLE_EINVALIDFILESYSTEM, COLE_EUNKNOWN).
Returns :	a filesystem in success, or NULL in other case.

cole_umount ()

int         cole_umount                     (COLEFS *colefilesystem,
                                             COLERRNO *colerrno);

Umounts the filesystem colefilesystem.

`colefilesystem` :	filesystem to umount.
`colerrno` :	error value (COLE_ECLOSEFILE, COLE_EREMOVE).
Returns :	zero in success, no zero in other case.

cole_print_tree ()

int         cole_print_tree                 (COLEFS *colefilesystem,
                                             COLERRNO *colerrno);

Prints on the standard output the tree of files and directories contained in colefilesystem. Currently this call always success.

`colefilesystem` :	filesystem of which the tree will be printed.
`colerrno` :	error value (errors from call cole_recurse_tree()).
Returns :	zero in success, no zero in other case.

cole_locate_filename ()

int         cole_locate_filename            (COLEFS *colefilesystem,
                                             char *filename,
                                             void *info,
                                             COLE_LOCATE_ACTION_FUNC *action,
                                             COLERRNO *colerrno);

Locate the filename in the filesystem colefilesystem, calling action when it's found. info is arbitrary pointer passed to action. Currently, filename must begin with a '/' character, it means filename is the absolute filename.

`colefilesystem` :	filesystem where to locate `filename`.
`filename` :	name of the file or directory to be located.
`info` :	arbitrary pointer passed to `action`.
`action` :	pointer to the function that is called when founding `filename`.
`colerrno` :	error value (COLE_EUNKNOWN, COLE_EMEMBERISNOTDIR, COLE_EFILENOTFOUND, COLE_EBROKENFILENAME, errors from call cole_recurse_tree()).
Returns :	zero in success, 1 in other case.

cole_recurse_tree ()

int         cole_recurse_tree               (COLEFS *colefilesystem,
                                             void *info,
                                             COLE_RECURSE_DIR_FUNC *inroot,
                                             COLE_RECURSE_DIRENT_FUNC *indirentry,
                                             COLE_RECURSE_DIR_FUNC *indir,
                                             COLE_RECURSE_DIR_FUNC *outdir,
                                             COLE_RECURSE_VISIT_DIR_FUNC *visitdir,
                                             COLERRNO *colerrno);

Recurse the filesystem colefilesystem, calling the functions pointed by inroot, indirentry, indir and outdirectory when start visiting root directory, start visiting any directory entry (file or directory), start visiting a directory or end visiting a directory, respectively. If visitdir returns no zero or it's NULL, the directory is visited, otherwise is not visited. info is a arbitrary pointer which is passed to the functions pointed by inroot, indirentry, indir and outdirectory: it may be used to share arbitrary information between them.

`colefilesystem` :	filesystem to recurse.
`info` :	arbitrary pointer passed to the functions.
`inroot` :	pointer to the function that is called when start visiting root directory. It can be NULL.
`indirentry` :	pointer to the function that is called when start visiting any directory entry (file or directory). It can be NULL.
`indir` :	pointer to the function that is called when start visiting a directory. It can be NULL.
`outdir` :	pointer to the function that is called when end visiting a directory. It can be NULL.
`visitdir` :	pointer to the function that is called to know if visit a directory. It can be NULL.
`colerrno` :	error value (errors from calls cole_opendir_rootdir(), cole_opendir_direntry(), cole_closedir() and inroot, indirentry, indir, and outdir functions).
Returns :	zero if recursed all the tree, no zero in other case.

cole_fopen ()

COLEFILE*   cole_fopen                      (COLEFS *colefilesystem,
                                             char *filename,
                                             COLERRNO *colerrno);

Opens the file with the name filename in the filesystem colefilesystem. Currently, filename must begin with a '/' character, it means filename is the absolute filename.

`colefilesystem` :	filesystem in which `filename` is in.
`filename` :	name of the file to open.
`colerrno` :	error value (COLE_EFILENOTFOUND, errors from calls cole_opendir_rootdir(), cole_fopen_direntry() and cole_locate_filename()).
Returns :	a file in success, or NULL in other case.

cole_fopen_direntry ()

COLEFILE*   cole_fopen_direntry             (COLEDIRENT *coledirentry,
                                             COLERRNO *colerrno);

Opens a directory entry as file.

`coledirentry` :	directory entry to be opened as file.
`colerrno` :	error value (COLE_EISNOTFILE, COLE_EMEMORY, COLE_ETMPNAM, COLE_EOPENFILE, COLE_EINVALIDFILESYSTEM, COLE_EREAD, COLE_EWRITE, COLE_EUNKNOWN).
Returns :	a file in success, or NULL in other case.

cole_fclose ()

int         cole_fclose                     (COLEFILE *colefile,
                                             COLERRNO *colerrno);

Closes the file colefile.

`colefile` :	file to be closed.
`colerrno` :	error value (COLE_ECLOSEFILE, CLOSE_EREMOVE).
Returns :	zero in sucess, no zero in other case.

cole_fread ()

size_t      cole_fread                      (COLEFILE *colefile,
                                             void *ptr,
                                             size_t size,
                                             COLERRNO *colerrno);

Reads size bytes from colefile and store them in the location given by ptr. If not success, the file position indicator is not changed.

`colefile` :	file to be read.
`ptr` :	memory location where the bytes will be stored.
`size` :	how many bytes will be read.
`colerrno` :	error value (COLE_EOF, COLE_EREAD, COLE_ESEEK).
Returns :	in sucess the number of bytes actually readed (maximum `size`) or zero in other case.

cole_feof ()

int         cole_feof                       (COLEFILE *colefile);

Tests if the end of file has been reached in colefile.

`colefile` :	file to be tested.
Returns :	no zero if the end of file has been reached, zero in other case.

cole_fsize ()

size_t      cole_fsize                      (COLEFILE *colefile);

`colefile` :	file of which its size will be returned.
Returns :	the size in bytes of the file `colefile`.

cole_ftell ()

size_t      cole_ftell                      (COLEFILE *colefile);

Get the current value of the file position indicator for the file colefile.

`colefile` :	file of which the file position indicator will be get.
Returns :	The file position.

cole_fseek ()

int         cole_fseek                      (COLEFILE *colefile,
                                             size_t delta,
                                             COLE_SEEK_FLAG direction,
                                             COLERRNO *colerrno);

Sets the value of the file position indicator for the file colefile delta bytes from the beginning of the file, forward from the current position, backward from the current position, or from the end of the file, if direction is COLE_SEEK_SET, COLE_SEEK_BACKWARD, COLE_SEEK_FORWARD or COLE_SEEK_END, respectively. The file position indicator will always be <= colefile->filesize. If you delta is such that the previous line would not true, cole_fseek fails.

`colefile` :	file of which its file position indicator will be set.
`delta` :	number of bytes that the file position indicator will be moved.
`direction` :	from where start to count the `delta` bytes.
`colerrno` :	error value (COLE_EFSEEKDELTA).
Returns :	zero in success, no zero in other case.

cole_frewind ()

int         cole_frewind                    (COLEFILE *colefile,
                                             COLERRNO *colerrno);

Sets the value of the file position indicator for the file colefile in the beginning of the file.

`colefile` :	file of which its file position indicator will be rewind.
`colerrno` :	error value (error from call cole_fseek()).
Returns :	zero in success, no zero in other case.

cole_opendir_rootdir ()

COLEDIR*    cole_opendir_rootdir            (COLEFS *colefilesystem,
                                             COLERRNO *colerrno);

Opens the root directory of the filesystem colefilesystem as directory.

`colefilesystem` :	filesystem of which the root directory will be opened.
`colerrno` :	error value (COLE_EMEMORY).
Returns :	a directory in success, or NULL in other case.

cole_opendir_direntry ()

COLEDIR*    cole_opendir_direntry           (COLEDIRENT *coledirentry,
                                             COLERRNO *colerrno);

Opens a directory entry as directory.

`coledirentry` :	directory entry to be opened as directory.
`colerrno` :	error value (COLE_EISNOTDIR, COLE_EMEMORY).
Returns :	a directory in success, or NULL in other case.

cole_closedir ()

int         cole_closedir                   (COLEDIR *coledir,
                                             COLERRNO *colerrno);

Closes the directory coledir. Currently this call always success.

`coledir` :	directory to be closed.
`colerrno` :	error value().
Returns :	zero in success, no zero in other case.

cole_visiteddirentry ()

COLEDIRENT* cole_visiteddirentry            (COLEDIR *coledir);

`coledir` :
Returns :

cole_nextdirentry ()

COLEDIRENT* cole_nextdirentry               (COLEDIR *coledir);

`coledir` :
Returns :

cole_direntry_isdir ()

int         cole_direntry_isdir             (COLEDIRENT *coledirentry);

Tests if the directory entry coledirentry is a directory.

`coledirentry` :	directory entry to be tested.
Returns :	no zero if it is a directory, zero in other case.

cole_direntry_isfile ()

int         cole_direntry_isfile            (COLEDIRENT *coledirentry);

Tests if the directory entry coledirentry is a file.

`coledirentry` :	directory entry to be tested.
Returns :	no zero if it is a directory, zero in other case.

cole_dir_getname ()

char*       cole_dir_getname                (COLEDIR *coledir);

`coledir` :
Returns :

cole_dir_getsize ()

size_t      cole_dir_getsize                (COLEDIR *coledir);

`coledir` :
Returns :

cole_dir_getsec1 ()

long        cole_dir_getsec1                (COLEDIR *coledir);

`coledir` :
Returns :

cole_dir_getsec2 ()

long        cole_dir_getsec2                (COLEDIR *coledir);

`coledir` :
Returns :

cole_dir_getdays1 ()

long        cole_dir_getdays1               (COLEDIR *coledir);

`coledir` :
Returns :

cole_dir_getdays2 ()

long        cole_dir_getdays2               (COLEDIR *coledir);

`coledir` :
Returns :

cole_direntry_getname ()

char*       cole_direntry_getname           (COLEDIRENT *coledirentry);

`coledirentry` :
Returns :

cole_direntry_getsize ()

size_t      cole_direntry_getsize           (COLEDIRENT *coledirentry);

`coledirentry` :
Returns :

cole_direntry_getdays1 ()

long        cole_direntry_getdays1          (COLEDIRENT *coledirentry);

`coledirentry` :
Returns :

cole_direntry_getsec1 ()

long        cole_direntry_getsec1           (COLEDIRENT *coledirentry);

`coledirentry` :
Returns :

cole_direntry_getdays2 ()

long        cole_direntry_getdays2          (COLEDIRENT *coledirentry);

`coledirentry` :
Returns :

cole_direntry_getsec2 ()

long        cole_direntry_getsec2           (COLEDIRENT *coledirentry);

`coledirentry` :
Returns :

API

Name

Synopsis

Description