FreeBSD Manual Pages
AG_FILE(3) Library Functions Manual 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, 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. Regard- less 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 el- ement of a pathname path. Agar maintains a general-purpose table mapping file extensions to Agar ob- ject 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); SEE ALSO AG_DataSource(3), AG_Intro(3), AG_Version(3) HISTORY The AG_File interface officially appeared in Agar 1.3.3. Agar 1.7 December 21, 2022 AG_FILE(3)
NAME | SYNOPSIS | DESCRIPTION | FILES | DIRECTORIES | UTILITY ROUTINES | EXAMPLES | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_File&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>