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, AG_Size 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, AG_Size 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.

EXAMPLES

The following code lists the contents of a directory:

AG_Dir *dir;
int i;

dir = AG_OpenDir("example-directory");
if (dir == NULL) {
	AG_FatalError(NULL);
}
for (i = 0; i < dir->nents; i++) {
	AG_Verbose("%s\n", dir->ents[i]);
}
AG_CloseDir(dir);

The following code displays information about a file:

AG_FileInfo info;

if (AG_GetFileInfo("file.txt", &info) != 0) {
	AG_FatalError(NULL);
}
AG_Verbose("File type: %d\n", info.type);
AG_Verbose("Permissions: %x\n", info.perms);
AG_Verbose("Flags: %x\n", info.flags);

The following code checks if a given file exists in the system temporary directory and if so, deletes it:

char path[AG_PATHNAME_MAX];

if (AG_GetSystemTempDir(path, sizeof(path)) != 0) {
	AG_FatalError(NULL);
}
AG_Strlcat(path, "file-to-delete.txt", sizeof(path));

if (AG_FileExists(path) == 1) {
	if (AG_FileDelete(path) == -1)
		AG_Verbose("Delete failed (%s)\n",
		    AG_GetError());
}

The following code creates a new directory, changes the working directory to it, prints out its complete path name and finally deletes it:

if (AG_MkDir("tempdir") != 0) {
	AG_FatalError(NULL);
}
if (AG_ChDir("tempdir") == 0) {
	char dir[AG_PATHNAME_MAX];

	if (AG_GetCWD(dir, sizeof(dir)) == 0) {
		AG_Verbose("Created %s (%s)\n",
		    AG_ShortFilename(dir), dir);
	}
	AG_ChDir("..");
}
if (AG_RmDir("tempdir") != 0) {
	AG_Verbose("Delete failed (%s)\n",
	    AG_GetError());
}

The following code maps the ".foo", ".bar" and ".baz" extensions to the AG_ObjectClass(3) at fooClass, barClass and bazClass, respectively.

const AG_FileExtMapping myExts[] = {
	{ ".foo", N_("Foo file"), &fooClass, 1 },
	{ ".bar", N_("Bar file"), &barClass, 1 },
	{ ".baz", N_("Baz file"), &bazClass, 1 }
};
const Uint myExtsCount = sizeof(myExts) /
                         sizeof(myExts[0]);

AG_RegisterFileExtMappings(myExts, myExtsCount);

HISTORY

The AG_File interface officially appeared in Agar 1.3.3.