Path

al_find_resource

char *al_find_resource(const char *base, const char *resource, uint32_t fm,
   char *buffer, size_t len)

Returns the full path of a 'resource' given mode 'fm'.

Parameters:

• base - sub directory name resource may be found in
• resource - name of resource
• fm - file mode/type of resource to match. See ALLEGRO_FS_MODE
• buffer - buffer to write full path to
• len - length of buffer

Notes: If asking for a read-only resource function scans the user data path, the program path, the current working directory followed by the system data path, if it doesn't find anything, it will return a bogus path in the users data path. XXX This is probably a bug.

If asking for a writable resource, it will scan the same places as the read only scan, and will pick the first wirteable existing resource it finds. If it doesn't find any pre-existing resource, it finds the first writable directory path made up of the path components of the path returned from al_get_path, the 'base', and 'resource' arguments. If none are writable, it will return a path made up of the USER_DATA_PATH, and the 'base' and 'resource' arguments.

al_path_append

void al_path_append(ALLEGRO_PATH *path, const char *s)

Append a directory component.

al_path_clone

ALLEGRO_PATH *al_path_clone(ALLEGRO_PATH *path)

Clones an ALLEGRO_PATH structure. Returns NULL on failure.

al_path_concat

void al_path_concat(ALLEGRO_PATH *path, const ALLEGRO_PATH *tail)

Concatenate two path structures. The first path structure is modified.

If tail is an absolute path, this function does nothing. tail's file/basename will overwrite path's if it exists, if tail does not have a basename, 'path's is kept (probably shouldn't).

Returns NULL on failure.

al_path_create

ALLEGRO_PATH *al_path_create(const char *str)

Create a path structure from a string. The string may be NULL for an empty path.

al_path_drop_tail

void al_path_drop_tail(ALLEGRO_PATH *path)

Drop the last directory component.

al_path_emode

bool al_path_emode(ALLEGRO_PATH *path, uint32_t mode)

Return true iff the path represents a file on the system that exists with the given mode bits.

al_path_exists

int32_t al_path_exists(ALLEGRO_PATH *path)

Return 1 if path represents an existing file on the system, or 0 if it doesn't exist. Returns -1 on error.

al_path_free

void al_path_free(ALLEGRO_PATH *path)

Free a path structure. Does nothing if passed NULL.

al_path_get_basename

/* XXX rename; 'basename' doesn't imply no extension */
/* TF
const char *al_path_get_basename(ALLEGRO_PATH *path, char *buf, size_t len)

Fill buf with filename part of the path, with the extension removed. If there is no filename part then buf is filled with the empty string. Returns buf.

al_path_get_drive

const char *al_path_get_drive(ALLEGRO_PATH *path)

Return the drive letter on a path, or NULL if there is none.

al_path_get_extension

const char *al_path_get_extension(ALLEGRO_PATH *path, char *buf, size_t len)

Fill buf with extension of the filename part of the path. If there is no filename part then buf is filled with the empty string. Returns buf.

al_path_get_filename

/* XXX rename; 'filename' doesn't mean 'basename' */
const char *al_path_get_filename(ALLEGRO_PATH *path)

Return the filename (i.e. basename) part of the path, or NULL if there is none.

al_path_index

const char *al_path_index(ALLEGRO_PATH *path, int i)

Return the i'th directory component of a path, counting from zero. If the index is negative then count from the right, i.e. -1 refers to the last path component. It is an error to pass an index which is out of bounds.

al_path_insert

void al_path_insert(ALLEGRO_PATH *path, int i, const char *s)

Insert a directory component at index i. If the index is negative then count from the right, i.e. -1 refers to the last path component. It is an error to pass an index which is out of bounds.

al_path_make_absolute

bool al_path_make_absolute(ALLEGRO_PATH *path)

Prepends the current working directory to 'path' if it is a relative path. Does nothing otherwise.

al_path_make_canonical

bool al_path_make_canonical(ALLEGRO_PATH *path)

Removes any leading '..' entries in absolute paths. Removes all '.' entries.

Note that this does not collapse x/../y sections into y. This is by design. If /foo on your system is a symlink to /bar/baz, then /foo/../quux is actually /bar/quux, not /quux as a naive ../-removal would give you.

al_path_num_components

int al_path_num_components(ALLEGRO_PATH *path)

Return the number of directory components in a path.

The directory components do not include the final part of a path (the basename).

al_path_remove

void al_path_remove(ALLEGRO_PATH *path, int i)

Delete the i'th directory component. If the index is negative then count from the right, i.e. -1 refers to the last path component. It is an error to pass an index which is out of bounds.

al_path_replace

void al_path_replace(ALLEGRO_PATH *path, int i, const char *s)

Replace the i'th directory component by another string. If the index is negative then count from the right, i.e. -1 refers to the last path component. It is an error to pass an index which is out of bounds.

al_path_set_drive

int32_t al_path_set_drive(ALLEGRO_PATH *path, const char *drive)

Set the drive letter on a path. The drive may be NULL to remove the drive letter.

al_path_set_filename

/* XXX rename; 'filename' doesn't mean 'basename' */
/* XXX what happens if filename includes directory separators? */
/* TF
int32_t al_path_set_filename(ALLEGRO_PATH *path, const char *filename)

Set the optional filename (i.e. basename) part of the path. The filename may be NULL.

al_path_set_extension

bool al_path_set_extension(ALLEGRO_PATH *path, char const *extension)

Replaces the extension of the path with the given one. If the filename of the path has no extension, the given one is appended.

Returns false if the path contains no filename part.

al_path_tail

const char *al_path_tail(ALLEGRO_PATH *path)

Returns the last directory component, or NULL if there are none.

al_path_to_string

/* FIXME
/* FIXME
            but it will at least return NULL if the buffer was too small. */
char *al_path_to_string(ALLEGRO_PATH *path, char *buffer, size_t len, char delim)

Get the string representation of a path.

Will fill buffer upto len bytes with a string representation of path, using delim as the path separator. To use the current native path separator use ALLEGRO_NATIVE_PATH_SEP