AG_FILE(3)

NAME
AG_File - agar file access routines

SYNOPSIS

    #include <agar/core.h>

DESCRIPTION
AG_File provides a consistent interface to basic filesystem operations (which may be implemented differently under different platforms).

FILES
int AG_GetFileInfo(const char *path, AG_FileInfo *fileInfo)

int AG_GetSystemTempDir(char *dst, size_t dstLen)

int AG_FileExists(const char *path)

int AG_FileDelete(const char *path)

The AG_GetFileInfo() function returns information about the specified filesystem object, into the structure:

    typedef struct ag_file_info {
    	enum ag_file_info_type type;
    	int perms;
    	int flags;
    } AG_FileInfo;

The type field can take on the values:

AG_FILE_REGULAR
    Regular file
AG_FILE_DIRECTORY
    File represents a directory
AG_FILE_DEVICE
    File is a special device
AG_FILE_FIFO
    File a POSIX fifo
AG_FILE_SYMLINK
    File is a symbolic link
AG_FILE_SOCKET
    File is a Unix-domain socket

The perms field can contain the following permission flags, assumed to be true under the effective privileges of the current process:

AG_FILE_READABLE
    File may be read from
AG_FILE_WRITEABLE
    File may be written to
AG_FILE_EXECUTABLE
    File is executable

The flags field allows the following values:

AG_FILE_SUID
    File has setuid bit set
AG_FILE_SGID
    File has setgid bit set
AG_FILE_ARCHIVE
    File is marked as being an archive
AG_FILE_HIDDEN
    File is marked as hidden
AG_FILE_TEMPORARY
    File is marked as temporary

DIRECTORIES
int AG_MkDir(const char *path)

int AG_MkPath(const char *path)

int AG_RmDir(const char *path)

int AG_ChDir(const char *path)

void AG_GetCWD(char *dst, size_t dstLen)

AG_Dir * AG_OpenDir(const char *path)

void AG_CloseDir(AG_Dir *dir)

The AG_MkDir() function creates a new directory under the specified path. The AG_MkPath() variant tries to create additional directories if elements of the path are missing. Both return 0 on success, -1 on failure.

AG_RmDir() removes the specified directory, assumed to be empty, returning 0 on success and -1 on failure.

The AG_ChDir() function changes the working directory to the specified value, returning 0 on success and -1 on failure. AG_GetCWD() returns the current working directory path into dst, assumed to be dstLen bytes in size.

AG_OpenDir() opens the specified directory. If successful, the function returns a newly allocated AG_Dir structure:

    typedef struct ag_dir {
    	char **ents;		/* Filenames */
    	int nents;
    } AG_Dir;

The ents array contains the filenames for all directory entries. Regardless of the filesystem's character encoding, ents is in UTF-8 encoding.

AG_CloseDir() closes the given directory.

UTILITY ROUTINES
const char * AG_ShortFilename(const char *path)

void AG_RegisterFileExtMappings(const AG_FileExtMapping *map, Uint count)

AG_ShortFilename() returns a pointer to the first character of the last element of a pathname path.

Agar maintains a general-purpose table mapping file extensions to Agar object classes. The AG_RegisterFileExtMappings() function registers a set of new file extension descriptions. The map argument should point to an array containing up to count items:

    typedef struct ag_file_ext_mapping {
    	const char *ext;
    	const char *descr;
    	void *cls;
    	int editDirect;
    } AG_FileExtMapping;

The ext member should be set to the file extension, including the leading dot. descr is a short description string. The cls pointer should be set to to an Agar object class (see AG_ObjectClass(3)) with a load() function capable of loading files with the given extension. Set editDirect to 1 to advise that objects of this class may be freely created, loaded from file and directly edited with the edit function of the class.

SEE ALSO
AG_DataSource(3), AG_Intro(3), AG_Version(3)

HISTORY
The AG_File interface officially appeared in Agar 1.3.3.