[AD] Clarifying and revising filesystem API

[Peter Wang <novalazy@xxxxxxxxxx>]

Here is an attempt to clarify the filesystem API, and mold it to my
liking (mostly just superficial renaming; "entry" was far too generic,
and the C/Unix-derived names seemed out of place).  I'm not finished
with it, but it's time to sleep.  Some questions are marked with (Q).
Suggestions welcome.


=========================================================================

% File system hooks

# File system types

## API: ALLEGRO_FILE_HANDLE

An opaque filesystem handle pointing to some path on the file system, either
a regular file or a directory.

Note that handles can be created whether the paths already exist or not.  You
then use [al_open_file_handle] to actually open the file or directory for
reading or writing.  Alternatively, use [al_fopen] to create a file handle
and open a regular file in one step.

See also: [al_open_file_handle], [al_fopen], [al_file_handle_is_regular],
[al_file_handle_is_directory].



# File system enumerations

## API: ALLEGRO_MAKE_TEMP_FLAGS

* ALLEGRO_MAKE_TEMP_REMOVE_NEVER
* ALLEGRO_MAKE_TEMP_REMOVE_ON_OPEN
* ALLEGRO_MAKE_TEMP_REMOVE_ON_CLOSE

See [al_make_temp].


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


## API: ALLEGRO_SEEK

* 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

*(Q) As discussed, I think these should be removed*

## 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_file_handle

Creates an [ALLEGRO_FILE_HANDLE] referring to the given path.
'path' can be a path to a file or a directory.
The file or directory is *not* opened automatically.

Returns a handle on success, NULL on failure.

See also: [al_open_file_handle], [al_fopen].


## API: al_destroy_file_handle

Destroy a filesystem handle.
Closes the file if it was open.

Does nothing if passed NULL.

See also: [al_close_file_handle].


## API: al_close_file_handle

Closes a filesystem entry.  The file handle is *not* destroyed.

Does nothing if passed NULL.

See also: [al_destroy_file_handle].


## API: al_close_dir

*(Q) Why not just use al_close_file_handle or al_destroy_file_handle?*

Closes a previously opened directory entry object.

[al_close_file_handle] is also a valid way to close any entry object.

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

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


## API: al_make_directory

Creates a new directory at the given path.

Returns true on success, or false on error.
On an error, the Allegro errno will be set.

See also: [al_get_errno]


## API: al_make_temp

Make a temporary, randomly named, file.

'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_MAKE_TEMP_REMOVE_NEVER - don't remove

* ALLEGRO_MAKE_TEMP_REMOVE_ON_OPEN - remove the file immediately after
    creation to create an anonymous temporary file.  May not work on all
    filesystems.

* ALLEGRO_MAKE_TEMP_REMOVE_ON_CLOSE - remove when entry is closed


## API: al_open_file_handle

Opens a filesystem entry with the given mode.  As with fopen(), `mode` may
begin with any of the following string sequences:

* r  - open file for reading.

* r+ - open file for reading and writing.

* w  - create file for writing, or truncate an existing file.

* w+ - open file for reading and writing.
	The file will be created or truncated as necessary.

* a  - open file for appending, creating it if necessary.
	The handle is positioned at the end of the file.

* a+ - open file for reading and appending, creating it if necessary.
	The handle is positioned at the end of the file.

The letter 'b' can also appear after the first letter, e.g. "rb+".
On some platforms this is required to open the file in "binary" mode.

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

See also: [al_get_errno]


## API: al_open_dir

*(Q) At least in the stdio version, this is no different to
al_open_file_handle followed by a check that the path was a directory, so
maybe this is not required?*

Creates and opens a filesystem entry handle for a directory.

Returns NULL on error, e.g. 


## API: al_read_dir

Reads the next directory item and returns a filesystem handle for it.

Returns NULL if the end of the directory is reached, or if there is an error.
On an error, the Allegro errno will be set.

See also: [al_get_errno]

*(Q) Peter Hull points out there is no rewind.*


## API: al_remove_file_handle

Remove the file at the path that the handle refers to.  This function is only
designed to work for regular files and empty directories.

Returns true on success, or false on failure.
On an error, the Allegro errno will be set.

See also: [al_get_errno]


## API: al_remove_file

*(Q) Do we need this?*

Like [al_remove_file_handle] but takes the path as a string rather than a
handle representing the path.


## API: al_update_file_handle_info

*(Q) Does this need to be called before al_get_file_handle_mode, etc.?*

Update the status information for the given filesystem handle,
i.e. modes, timestamps, etc.

Returns true on success, false on failure.
On an error, the Allegro errno will be set.

See also: [al_get_errno], [al_get_file_handle_atime],
[al_get_file_handle_ctime], [al_is_directory], [al_is_file],
[al_get_file_handle_mode].



# File Properties

## API: al_file_handle_exists

Check if the path represented by the given filesystem handle exists.

Returns true if it does exist.  Otherwise returns false if it doesn't exist,
or if an error occurred.  On an error, the Allegro errno will be set.

See also: [al_get_errno].


## API: al_file_exists

*(Q) I think this is unnecessary*

Like [al_file_handle_exists] but takes the path as a string rather than
a handle representing the path.


## API: al_file_handle_is_regular

Return true iff the file handle represents a regular file.


## API: al_file_is_regular

*(Q) I think this is unnecessary*

Return true if there exists a regular file at 'path'.

See also: [al_file_handle_is_regular].


## API: al_file_handle_is_directory

Return true iff the file handle represents a directory.


## API: al_file_is_directory
*(Q) I think this is unnecessary*

Return true if there exists a directory at 'path'.

See also: [al_file_handle_is_directory].


## API: al_get_file_handle_mode

Returns the file handle's mode flags.

See also: [ALLEGRO_FILE_MODE].


## API: al_get_file_mode
*(Q) I think this is unnecessary*

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

See Also: [ALLEGRO_FILE_MODE]


## API: al_get_file_handle_atime

Returns the time in seonds since the epoch since the path represented
by the file handle 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_file_atime
*(Q) I think this is unnecessary*

Returns last access time for fs entry 'path'.

See Also:
[al_get_file_handle_atime]


## API: al_get_file_handle_ctime

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


## API: al_get_file_ctime
*(Q) I think this is unnecessary*

Returns creation time for fs entry 'path'.

See Also:
[al_get_file_handle_ctime]


## API: al_get_file_handle_mtime

Returns the time in seonds since the epoch since the path represented
by the file handle was last modified.


## API: al_get_file_mtime
*(Q) I think this is unnecessary*

Returns last modification time for fs entry 'path'.

See Also:
[al_get_file_handle_mtime]


## API: al_get_file_handle_path

Returns the file handle's 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_file_handle_size

Returns the size, in bytes, of the given file represented by the file handle.

If the handle points to a directory the interpretation of the return value is
filesystem dependent.


## API: al_get_file_size
*(Q) I think this is unnecessary*

Returns file size for fs entry 'path'.

See Also:
[al_get_file_handle_size]



# File I/O

## API: al_fopen

Creates and opens a file handle to the path, using the given mode.

'path' - the path to open

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

See also: [al_create_file_handle], [al_open_file_handle].


## API: al_fclose

*(Q) Why not just make this a synonym for al_destroy_file_handle?*

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_file_handle]
instead.


## API: al_feof

Returns true if we have an end of file condition.


## API: al_ferror

Returns true if there was some sort of previous error.


## API: al_fgets

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


## API: al_fputs

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.


## API: al_fflush

Flush any pending writes to 'fp' to disk.

Returns true on success, false on failure.
On an error, the Allegro errno will be set.

See also: [al_get_errno]


## API: al_fgetc

Read and return next byte in entry 'f'.
Returns EOF on end of file or if an error occurred.

*(Q) XXX changed semantics: remember to change the implementation!*

See also: [al_feof], [al_get_errno].

*(Q) Consider naming this with 'byte' in the name, as char != byte since 
forever.*


## API: al_fputc

Write a single byte to entry.

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

Returns the written character (c) on success, or EOF on error.


## API: al_fungetc

Push back a single byte into a buffer for the given handle.  Pushed-back
bytes will be read on subsequent calls to reading functions, and will be
returned in the opposite order to that which they were pushed.
Only a single push back is guaranteed; different filesystems may support
larger buffers.

Returns c on success, EOF on error.

See also: [al_get_errno]


## API: al_fread_32le

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

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


## API: al_fwrite_32le

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

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


## API: al_fread_16le

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

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


## API: al_fwrite_16le

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

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


## API: al_fread_32be

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

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


## API: al_fwrite_32be

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

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


## API: al_fread_16be

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

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


## API: al_fwrite_16be

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

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


## API: al_fread

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

Return number of bytes actually read.


## API: al_fwrite

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.


## API: al_fseek

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

'whence' can be:

* ALLEGRO_SEEK_SET - Seek from beginning of file
* ALLEGRO_SEEK_CUR - Seek from current position
* ALLEGRO_SEEK_END - Seek from end of file

Returns true on success, false on failure.
On an error, the Allegro errno will be set.

On some platforms this function may not support large files.

See also: [al_get_errno]


## API: al_ftell

Returns the current position in file, or -1 on error.
On an error, the Allegro errno will be set.

On some platforms this function may not support large files.

See also: [al_get_errno]



# Other

## API: al_get_current_directory

Returns the path to the current directory, or NULL on failure.
On an error, the Allegro errno will be set.

Possible Errors:
* ERANGE - buffer is not large enough

See also: [al_get_errno]


## API: al_change_directory

Changes the current working directory to 'path'.

Returns true on success, false on error.

*(Q) need to figure out what to do with this if there are multiple
filesystems in effect; which filesystem's version of the "current directory"
is changed?*

*(Q) need to consider if this should _actually_ change the process'
working directory when using stdio driver, or just change it logically*

*(Q) threads*


## API: al_get_path_separator

*(Q) need to figure out what to do with this if there are multiple
filesystems in effect, each with potentially its own syntax*

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


## API: al_get_drive_separator

*(Q) I don't think this should be here.*

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