File system hooks

ALLEGRO_FS_ENTRY

typedef struct ALLEGRO_FS_ENTRY ALLEGRO_FS_ENTRY;

Opaque filesystem entry object. Represents a file or a directory (check with al_is_directory or al_is_file). There are no user accessible member variables.

ALLEGRO_FS_INTERFACE

typedef struct ALLEGRO_FS_INTERFACE ALLEGRO_FS_INTERFACE;

A structure containing some basic "filesystem" functions. You can use [al_set_new_fs_interface] to make Allegro use a different set of functions instead of stdio.

Enumerations

ALLEGRO_FILE_MODE

enum {

Filesystem modes/types

• ALLEGRO_FILEMODE_READ - Readable
• ALLEGRO_FILEMODE_WRITE - Writable
• ALLEGRO_FILEMODE_EXECUTE - Executable
• ALLEGRO_FILEMODE_HIDDEN - Hidden
• ALLEGRO_FILEMODE_ISFILE - Regular file
• ALLEGRO_FILEMODE_ISDIR - Directory

File Manipulation

al_create_entry

ALLEGRO_FS_ENTRY *al_create_entry(const char *path)

Creates an ALLEGRO_FS_ENTRY object pointing to path. 'path' can be a file or a directory and must not be NULL.

al_destroy_entry

void al_destroy_entry(ALLEGRO_FS_ENTRY *handle)

Destroys a fs entry handle. Closes file if it was open.

Does nothing if passed NULL.

al_closedir

bool al_closedir(ALLEGRO_FS_ENTRY *dir)

Closes a previously opened directory entry object.

Returns true on success, false on failure and fills in errno to indicate the error.

al_mkdir

bool al_mkdir(const char *path)

Creates a new directory on disk given the path 'path'.

Returns false on error and fills in errno to indicate the error.

See also: al_get_errno

al_opendir

bool al_opendir(ALLEGRO_FS_ENTRY *dir)

Opens a directory entry object. You must call this before using al_readdir on an entry and you must call al_closedir when you no longer need it.

Returns true on success.

al_readdir

ALLEGRO_FS_ENTRY *al_readdir(ALLEGRO_FS_ENTRY *dir)

Reads the next dir item and returns a filesystem entry for it.

Returns NULL if there are no more entries or if an error occurs. Call al_closedir on the directory handle when you are done.

al_remove_entry

bool al_remove_entry(ALLEGRO_FS_ENTRY *e)

"Unlink" or delete this file on disk.

Returns true on success, and false on failure, error is indicated in errno.

al_remove_str

bool al_remove_str(const char *path)

Unlink 'path' entry from disk.

Returns true on success, and false on failure.

errno is filled in to indicate the error.

See Also: al_remove_entry

al_fstat

bool al_fstat(ALLEGRO_FS_ENTRY *fp)

Updates stat info for entry 'fp'.

Returns true on success, false on failure. Fills in errno to indicate the error.

See also al_get_errno al_get_entry_ctime al_is_file

File Properties

al_is_present

bool al_is_present(ALLEGRO_FS_ENTRY *e)

Check if the given entry exists on disk. Returns true if it does exist or false if it doesn't exist, or an error occured. Error is indicated in errno.

al_is_present_str

bool al_is_present_str(const char *path)

Check if entry 'path' exists on disk.

See Also: al_is_present

al_is_file

bool al_is_file(ALLEGRO_FS_ENTRY *e)

Return true iff this entry is a regular file.

al_is_directory

bool al_is_directory(ALLEGRO_FS_ENTRY *e)

Return true iff this entry is a directory.

al_get_entry_mode

uint32_t al_get_entry_mode(ALLEGRO_FS_ENTRY *e)

Returns the entry's mode flags.

See also: al_get_errno

See the ALLEGRO_FILE_MODE enum for valid flags.

al_get_entry_atime

time_t al_get_entry_atime(ALLEGRO_FS_ENTRY *e)

Returns the time in seonds since the epoch since the entry was last accessed.

Warning: some filesystem either don't support this flag, or people turn it off to increase performance. It may not be valid in all circumstances.

al_get_entry_ctime

time_t al_get_entry_ctime(ALLEGRO_FS_ENTRY *e)

Returns the time in seconds since the epoch this entry was created on the filsystem.

al_get_entry_mtime

time_t al_get_entry_mtime(ALLEGRO_FS_ENTRY *e)

Returns the time in seconds since the epoch since the entry was last modified.

al_get_entry_name

ALLEGRO_PATH *al_get_entry_name(ALLEGRO_FS_ENTRY *fp)

Returns the entry's filename path. Note that the path will not be an absolute path if the entry wasn't created from an absolute path.

Returns NULL on error.

errno is set to indicate the error.

al_get_entry_size

off_t al_get_entry_size(ALLEGRO_FS_ENTRY *e)

Returns the size, in bytes, of the given entry.

Other

al_getcwd

ALLEGRO_PATH *al_getcwd(void)

Returns the path to the current working directory.

Returns NULL on failure.

errno is filled in to indicate the error.

Possible Errors: * ERANGE - buffer is not large enough

See also: al_get_errno

al_chdir

bool al_chdir(const char *path)

Changes the current working directory to 'path'.

Returns -1 on error.

Alternative filesystem functions

By default, Allegro uses platform specific filesystem functions for things like directory access. However if for example the files of your game are not in the local filesystem but inside some file archive, you can provide your own set of functions (or use an addon which does this for you, for example our physfs addon allows access to the most common archive formats).

al_set_fs_interface

void al_set_fs_interface(const ALLEGRO_FS_INTERFACE *fs_interface)

Set the ALLEGRO_FS_INTERFACE table for the calling thread.

See also: al_store_state, al_restore_state.

al_get_fs_interface

const ALLEGRO_FS_INTERFACE *al_get_fs_interface(void)

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

See also: al_store_state, al_restore_state.