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.