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.

Enumerations

ALLEGRO_FS_FILTER

typedef enum ALLEGRO_FS_FILTER {

File system search filters.

Type Filters:

  • ALLEGRO_FS_FILTER_DRIVES - Include Drive letters
  • ALLEGRO_FS_FILTER_DIRS - Include Directories
  • ALLEGRO_FS_FILTER_FILES - Include Files
  • ALLEGRO_FS_FILTER_NOSYMLINKS - Exclude symlinks
  • ALLEGRO_FS_FILTER_ALLENTRIES - Include all entries (including symlinks)

Permission Filters:

  • ALLEGRO_FS_FILTER_READABLE - Entry is Readable
  • ALLEGRO_FS_FILTER_WRITABLE - Entry is Writeable
  • ALLEGRO_FS_FILTER_EXECUTABLE - Entry is Executable

Access Filters:

  • ALLEGRO_FS_FILTER_HIDDEN - Entry is hidden
  • ALLEGRO_FS_FILTER_SYSTEM - Entry is marked as a system file

Other Filters:

  • ALLEGRO_FS_FILTER_ALLDIRS - Include all directories, including '.' and '..'
  • ALLEGRO_FS_FILTER_CASESENSITIVE - Search case sentitively
  • ALLEGRO_FS_FILTER_NODOTDOT - Exclude '..'
  • ALLEGRO_FS_FILTER_NOFILTER - No filtering
enum {

al_fs_mktemp unlink modes

  • ALLEGRO_FS_MKTEMP_UNLINK_NEVER - Don't auto unlink
  • ALLEGRO_FS_MKTEMP_UNLINK_NOW - Unlink on open, makes file "hidden"
  • ALLEGRO_FS_MKTEMP_UNLINK_ON_CLOSE - Unlink on close

ALLEGRO_FS_MODE

enum {

Filesystem modes/types

  • AL_FM_READ - Readable
  • AL_FM_WRITE - Writable
  • AL_FM_EXECUTE - Executable
  • AL_FM_HIDDEN - Hidden
  • AL_FM_ISFILE - Regular file
  • AL_FM_ISDIR - Directory

ALLEGRO_FS_SORT

typedef enum ALLEGRO_FS_SORT {

Filesystem search sort flags

  • ALLEGRO_FS_SORT_NAME - By name
  • ALLEGRO_FS_SORT_TIME - By time
  • ALLEGRO_FS_SORT_SIZE - By size
  • ALLEGRO_FS_SORT_UNSORTED - Don't sort

  • ALLEGRO_FS_SORT_DIRSFIRST - Directories first
  • ALLEGRO_FS_SORT_REVERSED - Reverse sort
  • ALLEGRO_FS_SORT_CASESENSITIVE - Case Sensitive
  • ALLEGRO_FS_SORT_DIRSLAST - Directories Last
  • ALLEGRO_FS_SORT_TYPE - By Type (extension?)

XXX do we need ALLEGRO_FS_SORT_TYPE? It sounds like we don't even know what it should do.

ALLEGRO_SEEK

enum {
  • ALLEGRO_SEEK_SET - Seek to pos from beginning of file
  • ALLEGRO_SEEK_CUR - Seek to pos from curent position
  • ALLEGRO_SEEK_END - Seek to pos from end of file

Search Path Routines

al_add_search_path

bool al_add_search_path(const char *path)

Adds a path to the list of directories to search for files when searching/opening files with a relative pathname.

al_get_search_path

bool al_get_search_path(uint32_t idx, size_t len, char *dest)

Fills in 'dest' up to 'len' bytes with the 'idx'th search path item.

Parameters: idx - index of search path element requested dest - memory buffer to copy path to len - length of memory buffer

Returns true on success, and false on failure.

errno is set to indicate the error.

Possible Errors: * EINVAL - invalid item selected * ERANGE - buffer not large enough

See also: al_get_errno

al_search_path_count

int32_t al_search_path_count()

Returns the number of items in the search path list.

File Manipulation

al_create_entry

ALLEGRO_FS_ENTRY *al_create_entry(AL_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.

al_close_entry

void al_close_entry(ALLEGRO_FS_ENTRY *handle)

Closes fs entry.

al_closedir

bool al_closedir(ALLEGRO_FS_ENTRY *dir)

Closes a previously opened directory entry object.

al_close_entry is also a valid way to close any entry object.

Does not free the entry object if it was opened with al_opendir. XXX This is probably a bug.

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

al_mkdir

bool al_mkdir(AL_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_mktemp

ALLEGRO_FS_ENTRY *al_mktemp(const char *template, uint32_t ulink)

Make a temporary randomly named file given a filename 'template' and 'ulink' flags.

'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 chars.

'ulink' is one of:

  • ALLEGRO_FS_MKTEMP_UNLINK_NOW - unlink now to create an anonymous temporary file
  • ALLEGRO_FS_MKTEMP_UNLINK_ON_CLOSE - unlink when entry is closed
  • ALLEGRO_FS_MKTEMP_UNLINK_NEVER - don't unlink

al_open_entry

bool al_open_entry(ALLEGRO_FS_ENTRY *handle, AL_CONST char *mode)

Opens handle with mode 'mode'. mode is a stdio type mode, ie: "r", "w", etc

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

See also: al_get_errno

al_opendir

ALLEGRO_FS_ENTRY *al_opendir(const char *path)

Creates and opens a filesystem entry object for a directory.

Returns NULL on error.

al_readdir

int32_t al_readdir(ALLEGRO_FS_ENTRY *dir, size_t size, char *name)

Reads the next dir item name into 'name' buffer, up to 'size' chars.

Warning: this may leave the filename truncated. XXX and how do users know if that's the case?

Returns non zero on error.

al_unlink_entry

bool al_unlink_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.

bool al_unlink_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_unlink_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_file_str

bool al_is_file_str(AL_CONST char *path)

Return true if 'path' is a file.

See Also: al_is_file

al_is_directory

bool al_is_directory(ALLEGRO_FS_ENTRY *e)

Return true iff this entry is a directory.

al_is_directory_str

bool al_is_directory_str(AL_CONST char *path)

Return true if 'path' is a directory.

See Also: al_is_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_FS_MODE enum for valid flags.

al_get_entry_mode_str

uint32_t al_get_entry_mode_str(const char *path)

Returns stat 'mode' for fs entry 'path'.

See Also: ALLEGRO_FS_MODE

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_atime_str

time_t al_get_entry_atime_str(const char *path)

Returns last access time for fs entry 'path'.

See Also: al_get_entry_atime

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_ctime_str

time_t al_get_entry_ctime_str(const char *path)

Returns creation time for fs entry 'path'.

See Also: al_get_entry_ctime

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_mtime_str

time_t al_get_entry_mtime_str(const char *path)

Returns last modification time for fs entry 'path'.

See Also: al_get_entry_mtime

al_get_entry_name

bool al_get_entry_name(ALLEGRO_FS_ENTRY *fp, size_t size, char *buf)

Fills in buf up to size bytes including trailing NULL char with the entry's name

Returns true on success, and false on error.

errno is set to indicate the error.

If buf isn't large enough, errno will be set to ERANGE

al_get_entry_size

off_t al_get_entry_size(ALLEGRO_FS_ENTRY *e)

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

al_get_entry_size_str

off_t al_get_entry_size_str(const char *path)

Returns file size for fs entry 'path'.

See Also: al_get_entry_size

File I/O

al_fopen

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

Creates and opens an ALLEGRO_FS_ENTRY object given path and mode.

'path' - the path to open

'mode' - mode to open the entry in ("r", "w", etc.)

al_fclose

void al_fclose(ALLEGRO_FS_ENTRY *fp)

Closes the given file entry object. Will destroy the handle if it was opened with al_fopen.

If you do not wish the entry object destroyed, use al_close_entry instead.

al_feof

bool al_feof(ALLEGRO_FS_ENTRY *fp)

Returns true if we have an end of file condition.

al_ferror

bool al_ferror(ALLEGRO_FS_ENTRY *fp)

Returns true if there was some sort of previous error.

al_fgets

char *al_fgets(ALLEGRO_FS_ENTRY *f, size_t max, char *p)

Reads a string of bytes terminated with a newline (\r,\n,\r\n).

Parameters:

  • p - buffer to fill
  • max - maximum size of buffer
  • f - entry to read from

Returns: p

al_fputs

int al_fputs(ALLEGRO_FS_ENTRY *f, AL_CONST char *p)

Writes a string to file.

Parameters:

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

Returns: 0 on success or -1 on error

Note: Function converts string to UTF8 before writing.

al_fflush

bool al_fflush(ALLEGRO_FS_ENTRY *fp)

Flush any pending writes to 'fp' to disk.

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

See also: al_get_errno

al_fgetc

int al_fgetc(ALLEGRO_FS_ENTRY *f)

Read and return next byte in entry 'f'. Returns EOF on end of file, and 0 on other errors (XXX this is probably a bug)

al_fputc

int al_fputc(ALLEGRO_FS_ENTRY *f, int c)

Write a single byte to entry.

Parameters: c - byte value to write f - entry to write to

Returns: EOF on error

al_fungetc

int al_fungetc(ALLEGRO_FS_ENTRY *fp, int c)

Ungets a single byte from a file. Does not write to file, it only places the char back into the entry's buffer.

See also al_get_errno

al_fread32le

int32_t al_fread32le(ALLEGRO_FS_ENTRY *f)

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

Returns: The read 32-bit word or EOF on error.

al_fwrite32le

int32_t al_fwrite32le(ALLEGRO_FS_ENTRY *f, int32_t l)

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

Returns: The written 32-bit word or EOF on error.

al_fread16le

int16_t al_fread16le(ALLEGRO_FS_ENTRY *f)

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

Returns: The read 16-bit word or EOF on error

al_fwrite16le

int16_t al_fwrite16le(ALLEGRO_FS_ENTRY *f, int16_t w)

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

Returns: The written 16-bit word or EOF on error.

al_fread32be

int32_t al_fread32be(ALLEGRO_FS_ENTRY *f)

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

Returns: The read 32-bit word or EOF on error

al_fwrite32be

int32_t al_fwrite32be(ALLEGRO_FS_ENTRY *f, int32_t l)

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

Returns: The written 32-bit word or EOF on error.

al_fread16be

int16_t al_fread16be(ALLEGRO_FS_ENTRY *f)

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

Returns: The read 16-bit word or EOF on error.

al_fwrite16be

int16_t al_fwrite16be(ALLEGRO_FS_ENTRY *f, int16_t w)

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

Returns: The written 16-bit word or EOF on error

al_fread

size_t al_fread(ALLEGRO_FS_ENTRY *fp, size_t size, void *ptr)

Read 'size' bytes into 'ptr' from entry 'fp'

Return number of bytes actually read.

al_fwrite

size_t al_fwrite(ALLEGRO_FS_ENTRY *fp, size_t size, const void *ptr)

Write 'size' bytes from 'ptr' into file 'fp'

Return number of bytes actually written or 0 on error.

Does not distinguish between EOF and other errors. Use al_feof and al_ferror to tell them apart.

al_fseek

bool al_fseek(ALLEGRO_FS_ENTRY *fp, int64_t offset, uint32_t whence)

Seek to 'offset' in file based on 'whence'.

'whence' can be:

  • ALLEGRO_SEEK_SET - Seek from beggining of file
  • ALLEGRO_SEEK_CUR - Seek from current position
  • ALLEGRO_SEEK_END - Seek from end of file

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

On some platforms this function may not support large files.

See also: al_get_errno

al_ftell

int64_t al_ftell(ALLEGRO_FS_ENTRY *fp)

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

On some platforms this function may not support large files.

See also: al_get_errno

Other

al_getcwd

bool al_getcwd(size_t len, char *buf)

Fill in 'buf' up to 'len' characters with the current working directory.

Returns true on success, false 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.

al_path_to_sys

int32_t al_path_to_sys(const char *orig, size_t len, char *path)

Converts path 'orig' to system dependant format. XXX return code?

al_path_to_uni

int32_t al_path_to_uni(const char *orig, size_t len, char *path)

Converts path 'orig' to 'allegro' format. XXX return code?

al_path_sep

int32_t al_path_sep(size_t len, char *sep)

Fills in 'sep' up to 'len' characters with the path separator string. XXX return code?

al_drive_sep

int32_t al_drive_sep(size_t len, char *sep)

Fills in 'sep' up to 'len' characters with the drive separator string. XXX return code?

Last updated: 2009-02-09 09:20:17Z