% File system hooks

## API: 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

## API: ALLEGRO_FILE_MODE

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

# Search Path Routines

## API: al_add_search_path

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

## API: al_get_search_path

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]

## API: al_search_path_count

Returns the number of items in the search path list.

# File Manipulation

## API: al_create_entry

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

## API: al_destroy_entry

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

Does nothing if passed NULL.

## API: al_close_entry

Closes fs entry.

Does nothing if passed NULL.

## API: al_closedir

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.

## API: al_mkdir

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]

## API: al_open_entry

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]

## API: al_opendir

Creates and opens a filesystem entry object for a directory.

Returns NULL on error.

## API: al_readdir

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

Returns NULL on error.

## API: al_remove_entry

"Unlink" or delete this file on disk.

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

## API: al_remove_str

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]

## API: al_fstat

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_atime] [al_get_entry_ctime] [al_is_directory]
[al_is_file] [al_get_entry_mode]

# File Properties

## API: al_is_present

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.

## API: al_is_present_str

Check if entry 'path' exists on disk.

See Also:
[al_is_present]

## API: al_is_file

Return true iff this entry is a regular file.

## API: al_is_directory

Return true iff this entry is a directory.

## API: al_get_entry_mode

Returns the entry's mode flags.

See also: [al_get_errno]

See the [ALLEGRO_FILE_MODE] enum for valid flags.

## API: al_get_entry_mode_str

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

See Also:
[ALLEGRO_FILE_MODE]

## API: al_get_entry_atime

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.

## API: al_get_entry_ctime

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

## API: al_get_entry_mtime

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

## API: al_get_entry_name

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.

## API: al_get_entry_size

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

# Other

## API: al_getcwd

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]

## API: al_chdir

Changes the current working directory to 'path'.

Returns -1 on error.

## API: al_path_sep

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

## API: al_drive_sep

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


