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, re- turning 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 func- tion 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. Re- gardless of the filesystem's character encoding, ents is in UTF-8 en- coding. 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 lead- ing 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 cre- ated, 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 tempo- rary 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 direc- tory 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+14.3.quarterly>