.\" Copyright (c) 2008-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 21, 2022
.Dt AG_FILE 3
.Os Agar 1.7
.Sh NAME
.Nm AG_File
.Nd agar file access routines
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
.Ed
.Sh DESCRIPTION
.Nm
provides a consistent interface to basic filesystem operations (which may be
implemented differently under different platforms).
.\" MANLINK(AG_FileInfo)
.Sh FILES
.nr nS 1
.Ft "int"
.Fn AG_GetFileInfo "const char *path" "AG_FileInfo *fileInfo"
.Pp
.Ft "int"
.Fn AG_GetSystemTempDir "char *dst" "AG_Size dstLen"
.Pp
.Ft "int"
.Fn AG_FileExists "const char *path"
.Pp
.Ft "int"
.Fn AG_FileDelete "const char *path"
.Pp
.nr nS 0
The
.Fn AG_GetFileInfo
function returns information about the specified filesystem object, into
the structure:
.Bd -literal
.\" SYNTAX(c)
typedef struct ag_file_info {
	enum ag_file_info_type type;
	int perms;
	int flags;
} AG_FileInfo;
.Ed
.Pp
The
.Fa type
field can take on the values:
.Pp
.Bl -tag -compact -width "AG_FILE_DIRECTORY "
.It AG_FILE_REGULAR
Regular file
.It AG_FILE_DIRECTORY
File represents a directory
.It AG_FILE_DEVICE
File is a special device
.It AG_FILE_FIFO
File a POSIX fifo
.It AG_FILE_SYMLINK
File is a symbolic link
.It AG_FILE_SOCKET
File is a Unix-domain socket
.El
.Pp
The
.Fa perms
field can contain the following permission flags, assumed to be true under
the effective privileges of the current process:
.Pp
.Bl -tag -compact -width AG_FILE_EXECUTABLE
.It AG_FILE_READABLE
File may be read from
.It AG_FILE_WRITEABLE
File may be written to
.It AG_FILE_EXECUTABLE
File is executable
.El
.Pp
The
.Fa flags
field allows the following values:
.Pp
.Bl -tag -compact -width "AG_FILE_TEMPORARY "
.It AG_FILE_SUID
File has setuid bit set
.It AG_FILE_SGID
File has setgid bit set
.It AG_FILE_ARCHIVE
File is marked as being an archive
.It AG_FILE_HIDDEN
File is marked as hidden
.It AG_FILE_TEMPORARY
File is marked as temporary
.El
.\" MANLINK(AG_Dir)
.Sh DIRECTORIES
.nr nS 1
.Ft "int"
.Fn AG_MkDir "const char *path"
.Pp
.Ft "int"
.Fn AG_MkPath "const char *path"
.Pp
.Ft "int"
.Fn AG_RmDir "const char *path"
.Pp
.Ft "int"
.Fn AG_ChDir "const char *path"
.Pp
.Ft "void"
.Fn AG_GetCWD "char *dst" "AG_Size dstLen"
.Pp
.Ft "AG_Dir *"
.Fn AG_OpenDir "const char *path"
.Pp
.Ft "void"
.Fn AG_CloseDir "AG_Dir *dir"
.Pp
.nr nS 0
The
.Fn AG_MkDir
function creates a new directory under the specified path.
The
.Fn AG_MkPath
variant tries to create additional directories if elements of the path are
missing.
Both return 0 on success, -1 on failure.
.Pp
.Fn AG_RmDir
removes the specified directory, assumed to be empty, returning 0 on success
and -1 on failure.
.Pp
The
.Fn AG_ChDir
function changes the working directory to the specified value, returning 0
on success and -1 on failure.
.Fn AG_GetCWD
returns the current working directory path into
.Fa dst ,
assumed to be
.Fa dstLen
bytes in size.
.Pp
.Fn AG_OpenDir
opens the specified directory.
If successful, the function returns a newly allocated
.Ft AG_Dir
structure:
.Bd -literal
.\" SYNTAX(c)
typedef struct ag_dir {
	char **ents;		/* Filenames */
	int nents;
} AG_Dir;
.Ed
.Pp
The
.Va ents
array contains the filenames for all directory entries.
Regardless of the filesystem's character encoding,
.Va ents
is in UTF-8 encoding.
.Pp
.Fn AG_CloseDir
closes the given directory.
.\" MANLINK(AG_FileExtMapping)
.Sh UTILITY ROUTINES
.nr nS 1
.Ft "const char *"
.Fn AG_ShortFilename "const char *path"
.Pp
.Ft void
.Fn AG_RegisterFileExtMappings "const AG_FileExtMapping *map" "Uint count"
.Pp
.nr nS 0
.Fn AG_ShortFilename
returns a pointer to the first character of the last element of a pathname
.Fa path .
.Pp
Agar maintains a general-purpose table mapping file extensions to Agar
object classes.
The
.Fn AG_RegisterFileExtMappings
function registers a set of new file extension descriptions.
The
.Fa map
argument should point to an array containing up to
.Fa count
items:
.Bd -literal
.\" SYNTAX(c)
typedef struct ag_file_ext_mapping {
	const char *ext;
	const char *descr;
	void *cls;
	int editDirect;
} AG_FileExtMapping;
.Ed
.Pp
The
.Va ext
member should be set to the file extension, including the leading dot.
.Va descr
is a short description string.
The
.Va cls
pointer should be set to to an Agar object class (see
.Xr AG_ObjectClass 3 )
with a
.Fn load
function capable of loading files with the given extension.
Set
.Va editDirect
to 1 to advise that objects of this class may be freely created, loaded
from file and directly edited with the
.Fa edit
function of the class.
.Sh EXAMPLES
The following code lists the contents of a directory:
.Bd -literal -offset indent
.\" SYNTAX(c)
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);
.Ed
.Pp
The following code displays information about a file:
.Bd -literal -offset indent
.\" SYNTAX(c)
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);
.Ed
.Pp
The following code checks if a given file exists in the system temporary
directory and if so, deletes it:
.Bd -literal -offset indent
.\" SYNTAX(c)
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());
}
.Ed
.Pp
The following code creates a new directory, changes the working directory to
it, prints out its complete path name and finally deletes it:
.Bd -literal -offset indent
.\" SYNTAX(c)
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());
}
.Ed
.Pp
The following code maps the ".foo", ".bar" and ".baz" extensions to the
.Xr AG_ObjectClass 3
at
.Va fooClass ,
.Va barClass
and
.Va bazClass ,
respectively.
.Bd -literal -offset indent
.\" SYNTAX(c)
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);
.Ed
.Sh SEE ALSO
.Xr AG_DataSource 3 ,
.Xr AG_Intro 3 ,
.Xr AG_Version 3
.Sh HISTORY
The
.Nm
interface officially appeared in Agar 1.3.3.