libcaca file IO

Modules
	libcaca importers/exporters from/to various

Functions
__extern caca_file_t *	caca_file_open (char const *, const char *)
	Open a file for reading or writing. More...
__extern int	caca_file_close (caca_file_t *)
	Close a file handle. More...
__extern uint64_t	caca_file_tell (caca_file_t *)
	Return the position in a file handle. More...
__extern size_t	caca_file_read (caca_file_t *, void *, size_t)
	Read data from a file handle. More...
__extern size_t	caca_file_write (caca_file_t *, const void *, size_t)
	Write data to a file handle. More...
__extern char *	caca_file_gets (caca_file_t *, char *, int)
	Read a line from a file handle. More...
__extern int	caca_file_eof (caca_file_t *)
	Tell whether a file handle reached end of file. More...

Detailed Description

These functions allow to read and write files in a platform-independent way.

Function Documentation

caca_file_open()

__extern caca_file_t* caca_file_open	(	char const *	path,
		const char *	mode
	)

Create a caca file handle for a file. If the file is zipped, it is decompressed on the fly.

If an error occurs, NULL is returned and errno is set accordingly:

• ENOSTS Function not implemented.
• EINVAL File not found or permission denied.

Parameters

path	The file path
mode	The file open mode

Returns

A file handle to path.

Referenced by caca_import_canvas_from_file().

caca_file_close()

__extern int caca_file_close

(

caca_file_t *

fp

)

Close and destroy the resources associated with a caca file handle.

This function is a wrapper for fclose() or, if available, gzclose().

Parameters

fp	The file handle

Returns

The return value of fclose() or gzclose().

Referenced by caca_import_canvas_from_file().

caca_file_tell()

__extern uint64_t caca_file_tell

(

caca_file_t *

fp

)

Return the file handle position, in bytes.

Parameters

fp	The file handle

Returns

The current offset in the file handle.

caca_file_read()

__extern size_t caca_file_read	(	caca_file_t *	fp,
		void *	ptr,
		size_t	size
	)

Read data from a file handle and copy them into the given buffer.

Parameters

fp	The file handle
ptr	The destination buffer
size	The number of bytes to read

Returns

The number of bytes read

Referenced by caca_import_canvas_from_file().

caca_file_write()

__extern size_t caca_file_write	(	caca_file_t *	fp,
		const void *	ptr,
		size_t	size
	)

Write the contents of the given buffer to the file handle.

Parameters

fp	The file handle
ptr	The source buffer
size	The number of bytes to write

Returns

The number of bytes written

caca_file_gets()

__extern char* caca_file_gets	(	caca_file_t *	fp,
		char *	s,
		int	size
	)

Read one line of data from a file handle, up to one less than the given number of bytes. A trailing zero is appended to the data.

Parameters

fp	The file handle
s	The destination buffer
size	The maximum number of bytes to read

Returns

The number of bytes read, including the trailing zero

caca_file_eof()

__extern int caca_file_eof

(

caca_file_t *

fp

)

Return the end-of-file status of the file handle.

This function is a wrapper for feof() or, if available, gzeof().

Parameters

fp	The file handle

Returns

1 if EOF was reached, 0 otherwise

Referenced by caca_import_canvas_from_file().