File I/O

These functions are declared in the main Allegro header file:

#include <allegro5/allegro.h>

ALLEGRO_FILE

typedef struct ALLEGRO_FILE ALLEGRO_FILE;

An opaque object representing an open file. This could be a real file on disk or a virtual file.

ALLEGRO_FILE_INTERFACE

typedef struct ALLEGRO_FILE_INTERFACE

A structure containing function pointers to handle a type of "file", real or virtual. See the full discussion in al_set_new_file_interface.

The fields are:

void*         (*fi_fopen)(const char *path, const char *mode);
void          (*fi_fclose)(ALLEGRO_FILE *f);
size_t        (*fi_fread)(ALLEGRO_FILE *f, void *ptr, size_t size);
size_t        (*fi_fwrite)(ALLEGRO_FILE *f, const void *ptr, size_t size);
bool          (*fi_fflush)(ALLEGRO_FILE *f);
int64_t       (*fi_ftell)(ALLEGRO_FILE *f);
bool          (*fi_fseek)(ALLEGRO_FILE *f, int64_t offset, int whence);
bool          (*fi_feof)(ALLEGRO_FILE *f);
bool          (*fi_ferror)(ALLEGRO_FILE *f);
void          (*fi_fclearerr)(ALLEGRO_FILE *f);
int           (*fi_fungetc)(ALLEGRO_FILE *f, int c);
off_t         (*fi_fsize)(ALLEGRO_FILE *f);

The fi_open function must allocate memory for whatever userdata structure it needs. The pointer to that memory must be returned; it will then be associated with the file. The other functions can access that data by calling al_get_file_userdata on the file handle. If fi_open returns NULL then al_fopen will also return NULL.

The fi_fclose function must clean up and free the userdata, but Allegro will free the ALLEGRO_FILE handle.

If fi_fungetc is NULL, then Allegro's default implementation of a 16 char long buffer will be used.

ALLEGRO_SEEK

typedef enum ALLEGRO_SEEK

ALLEGRO_SEEK_SET - seek relative to beginning of file
ALLEGRO_SEEK_CUR - seek relative to current file position
ALLEGRO_SEEK_END - seek relative to end of file

al_fopen

ALLEGRO_FILE *al_fopen(const char *path, const char *mode)

Creates and opens a file (real or virtual) given the path and mode. The current file interface is used to open the file.

Parameters:

path - path to the file to open
mode - access mode to open the file in ("r", "w", etc.)

Depending on the stream type and the mode string, files may be opened in "text" mode. The handling of newlines is particularly important. For example, using the default stdio-based streams on DOS and Windows platforms, where the native end-of-line terminators are CR+LF sequences, a call to al_fgetc may return just one character ('\n') where there were two bytes (CR+LF) in the file. When writing out '\n', two bytes would be written instead. (As an aside, '\n' is not defined to be equal to LF either.)

Newline translations can be useful for text files but is disastrous for binary files. To avoid this behaviour you need to open file streams in binary mode by using a mode argument containing a "b", e.g. "rb", "wb".

Returns a file handle on success, or NULL on error.

al_fopen_interface

ALLEGRO_FILE *al_fopen_interface(const ALLEGRO_FILE_INTERFACE *drv,
   const char *path, const char *mode)

Opens a file using the specified interface, instead of the interface set with al_set_new_file_interface.

al_fclose

void al_fclose(ALLEGRO_FILE *f)

Close the given file, writing any buffered output data (if any).

al_fread

size_t al_fread(ALLEGRO_FILE *f, void *ptr, size_t size)

Read 'size' bytes into the buffer pointed to by 'ptr', from the given file.

Returns the number of bytes actually read. If an error occurs, or the end-of-file is reached, the return value is a short byte count (or zero).

al_fread() does not distinguish between EOF and other errors. Use al_feof and al_ferror to determine which occurred.

al_fwrite

size_t al_fwrite(ALLEGRO_FILE *f, const void *ptr, size_t size)

Write 'size' bytes from the buffer pointed to by 'ptr' into the given file.

Returns the number of bytes actually written. If an error occurs, the return value is a short byte count (or zero).

al_fflush

bool al_fflush(ALLEGRO_FILE *f)

Flush any pending writes to the given file.

Returns true on success, false otherwise. errno is set to indicate the error.

al_ftell

int64_t al_ftell(ALLEGRO_FILE *f)

Returns the current position in the given file, or -1 on error. errno is set to indicate the error.

On some platforms this function may not support large files.

al_fseek

bool al_fseek(ALLEGRO_FILE *f, int64_t offset, int whence)

Set the current position of the given file to a position relative to that specified by 'whence', plus 'offset' number of bytes.

'whence' can be:

ALLEGRO_SEEK_SET - seek relative to beginning of file
ALLEGRO_SEEK_CUR - seek relative to current file position
ALLEGRO_SEEK_END - seek relative to end of file

Returns true on success, false on failure. errno is set to indicate the error.

After a successful seek, the end-of-file indicator is cleared and all pushback bytes are forgotten.

On some platforms this function may not support large files.

al_feof

bool al_feof(ALLEGRO_FILE *f)

Returns true if the end-of-file indicator has been set on the file, i.e. we have attempted to read past the end of the file.

This does not return true if we simply are at the end of the file. The following code correctly reads two bytes, even when the file contains exactly two bytes:

int b1 = al_fgetc(f);
int b2 = al_fgetc(f);
if (al_feof(f)) {
   /* At least one byte was unsuccessfully read. */
   report_error();
}

al_ferror

bool al_ferror(ALLEGRO_FILE *f)

Returns true if the error indicator is set on the given file, i.e. there was some sort of previous error.

al_fclearerr

void al_fclearerr(ALLEGRO_FILE *f)

Clear the error indicator for the given file.

The standard I/O backend also clears the end-of-file indicator, and other backends should try to do this. However, they may not if it would require too much effort (e.g. PhysicsFS backend), so your code should not rely on it if you need your code to be portable to other backends.

al_fungetc

int al_fungetc(ALLEGRO_FILE *f, int c)

Ungets a single byte from a file. Pushed-back bytes are not written to the file, only made available for subsequent reads, in reverse order.

The number of pushbacks depends on the backend. The standard I/O backend only guarantees a single pushback; this depends on the libc implementation.

For backends that follow the standard behavior, the pushback buffer will be cleared after any seeking or writing; also calls to al_fseek and al_ftell are relative to the number of pushbacks. If a pushback causes the position to become negative, the behavior of al_fseek and al_ftell are undefined.

al_fsize

int64_t al_fsize(ALLEGRO_FILE *f)

Return the size of the file, if it can be determined, or -1 otherwise.

al_fgetc

int al_fgetc(ALLEGRO_FILE *f)

Read and return next byte in the given file. Returns EOF on end of file or if an error occurred.

al_fputc

int al_fputc(ALLEGRO_FILE *f, int c)

Write a single byte to the given file.

Parameters:

c - byte value to write
f - file to write to

Returns c on success, or EOF on error.

al_fread16le

int16_t al_fread16le(ALLEGRO_FILE *f)

Reads a 16-bit word in little-endian format (LSB first).

On success, returns the 16-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

al_fread16be

int16_t al_fread16be(ALLEGRO_FILE *f)

Reads a 16-bit word in big-endian format (MSB first).

al_fwrite16le

size_t al_fwrite16le(ALLEGRO_FILE *f, int16_t w)

Writes a 16-bit word in little-endian format (LSB first).

Returns the number of bytes written: 2 on success, less than 2 on an error.

al_fwrite16be

size_t al_fwrite16be(ALLEGRO_FILE *f, int16_t w)

Writes a 16-bit word in big-endian format (MSB first).

Returns the number of bytes written: 2 on success, less than 2 on an error.

al_fread32le

int32_t al_fread32le(ALLEGRO_FILE *f)

Reads a 32-bit word in little-endian format (LSB first).

On success, returns the 32-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

al_fread32be

int32_t al_fread32be(ALLEGRO_FILE *f)

Read a 32-bit word in big-endian format (MSB first).

al_fwrite32le

size_t al_fwrite32le(ALLEGRO_FILE *f, int32_t l)

Writes a 32-bit word in little-endian format (LSB first).

Returns the number of bytes written: 4 on success, less than 4 on an error.

al_fwrite32be

size_t al_fwrite32be(ALLEGRO_FILE *f, int32_t l)

Writes a 32-bit word in big-endian format (MSB first).

Returns the number of bytes written: 4 on success, less than 4 on an error.

al_fgets

char *al_fgets(ALLEGRO_FILE *f, char * const buf, size_t max)

Read a string of bytes terminated with a newline or end-of-file into the buffer given. The line terminator(s), if any, are included in the returned string. A maximum of max-1 bytes are read, with one byte being reserved for a NUL terminator.

Parameters:

f - file to read from
buf - buffer to fill
max - maximum size of buffer

Returns the pointer to buf on success. Returns NULL if an error occurred or if the end of file was reached without reading any bytes.

See al_fopen about translations of end-of-line characters.

al_fget_ustr

ALLEGRO_USTR *al_fget_ustr(ALLEGRO_FILE *f)

Read a string of bytes terminated with a newline or end-of-file. The line terminator(s), if any, are included in the returned string.

On success returns a pointer to a new ALLEGRO_USTR structure. This must be freed eventually with al_ustr_free. Returns NULL if an error occurred or if the end of file was reached without reading any bytes.

See al_fopen about translations of end-of-line characters.

al_fputs

int al_fputs(ALLEGRO_FILE *f, char const *p)

Writes a string to file. Apart from the return value, this is equivalent to:

al_fwrite(f, p, strlen(p));

Parameters:

f - file handle to write to
p - string to write

Returns a non-negative integer on success, EOF on error.

Note: depending on the stream type and the mode passed to al_fopen, newline characters in the string may or may not be automatically translated to native end-of-line sequences, e.g. CR/LF instead of LF.

Standard I/O specific routines

al_fopen_fd

ALLEGRO_FILE *al_fopen_fd(int fd, const char *mode)

Create an ALLEGRO_FILE object that operates on an open file descriptor using stdio routines. See the documentation of fdopen() for a description of the 'mode' argument.

Returns an ALLEGRO_FILE object on success or NULL on an error. On an error, the Allegro errno will be set and the file descriptor will not be closed.

The file descriptor will be closed by al_fclose so you should not call close() on it.

al_make_temp_file

ALLEGRO_FILE *al_make_temp_file(const char *template, ALLEGRO_PATH **ret_path)

Make a temporary randomly named file given a filename 'template'.

'template' is a string giving the format of the generated filename and should include one or more capital Xs. The Xs are replaced with random alphanumeric characters. There should be no path separators.

If 'ret_path' is not NULL, the address it points to will be set to point to a new path structure with the name of the temporary file.

Returns the opened ALLEGRO_FILE on success, NULL on failure.

Alternative file streams

By default, the Allegro file I/O routines use the C library I/O routines, hence work with files on the local filesystem, but can be overridden so that you can read and write to other streams. For example, you can work with block of memory or sub-files inside .zip files.

There are two ways to get an ALLEGRO_FILE that doesn't use stdio. An addon library may provide a function that returns a new ALLEGRO_FILE directly, after which, all al_f* calls on that object will use overridden functions for that type of stream. Alternatively, al_set_new_file_interface changes which function will handle the following al_fopen calls for the current thread.

al_set_new_file_interface

void al_set_new_file_interface(const ALLEGRO_FILE_INTERFACE *file_interface)

Set the ALLEGRO_FILE_INTERFACE table for the calling thread. This will change the handler for later calls to al_fopen.

al_set_standard_file_interface

void al_set_standard_file_interface(void)

Set the ALLEGRO_FILE_INTERFACE table to the default, for the calling thread. This will change the handler for later calls to al_fopen.

al_get_new_file_interface

const ALLEGRO_FILE_INTERFACE *al_get_new_file_interface(void)

Return a pointer to the ALLEGRO_FILE_INTERFACE table in effect for the calling thread.

See also: al_store_state, al_restore_state.

al_create_file_handle

ALLEGRO_FILE *al_create_file_handle(const ALLEGRO_FILE_INTERFACE *drv,
   void *userdata)

Creates an empty, opened file handle with some abstract user data. This allows custom interfaces to extend the ALLEGRO_FILE struct with their own data. You should close the handle with the standard al_fclose function when you are finished with it.

al_get_file_userdata

void *al_get_file_userdata(ALLEGRO_FILE *f)

Returns a pointer to the custom userdata that is attached to the file handle. This is intended to be used by functions that extend ALLEGRO_FILE_INTERFACE.

Allegro version 5.0.2 - Last updated: 2011-04-03 06:05:08 UTC