OS-independent file system layer that optimizes the performance of queries by caching and prefetching. More...

Classes
class	ListSettings

Public Member Functions
void	setCacheLifetime (float t)
	Set the cacheLifetime(). More...

Static Public Member Functions
static float	cacheLifetime ()
	A cache is used to optimize repeated calls. More...

static void	cleanup ()
	Destroy the common instance. More...

static void	clearCache (const String &path="")
	Clears old cache entries so that exists() and list() will reflect recent changes to the file system. More...

static void	clearUsedFiles ()
	Clears list of used files marked by markFileUsed(). More...

static void	copyDir (const String &srcPath, const String &dstPath)
	More...

static void	copyFile (const String &srcPath, const String &dstPath)
	More...

static void	createDirectory (const String &path)
	Creates the directory named, including any subdirectories that do not already exist. More...

static String	currentDirectory ()
	The current working directory (cwd). More...

static const Array< String > &	drives ()
	On Windows, the drive letters that form the file system roots. More...

static bool	exists (const String &f, bool trustCache=true, bool caseSensitive=false)
	Returns true if a node named f exists. More...

static void	fclose (FILE *f)

static FILE *	fopen (const char filename, const char mode)
	Same as the C standard library fopen, but updates the file cache to acknowledge the new file on a write operation. More...

static void	getDirectories (const String &spec, Array< String > &result, bool includeParentPath=false)
	list() directories More...

static void	getFiles (const String &spec, Array< String > &result, bool includeParentPath=false)
	list() files More...

static void	init ()
	Create the common instance. More...

static bool	inZipfile (const String &path, String &zipfile, String &pathInZipfile)
	Returns true if some sub-path of path is a zipfile. More...

static bool	inZipfile (const String &path)
	Returns true if some sub-path of path is a zipfile. More...

static bool	isDirectory (const String &path, bool expandEnvironmentVariablesInPath=true)
	Known bug: does not work inside zipfiles. More...

static bool	isFile (const String &path)
	Known bug: does not work inside zipfiles. More...

static bool	isNewer (const String &src, const String &dst)
	Returns true if dst does not exist or src is newer than dst, according to their time stamps. More...

static bool	isPasswordProtected (const String &zipFile, String &password)
	If true, returns the password in the second parameter. More...

static bool	isZipfile (const String &path)
	Returns true if path is a file that is a zipfile. More...

static void	list (const String &spec, Array< String > &result, const ListSettings &listSettings=ListSettings())
	Appends all nodes matching spec to the result array. More...

static void	markFileUsed (const String &filename)
	Adds filename to usedFiles(). More...

static String	NFDStandardizeFilename (const String &path, const String &cwd=currentDirectory())
	Attempts to fully resolve a filename, removing all instances of "." and "..", assuming that there are no Symlinks that would make "." or ".." difficult to reason about. More...

static bool	registerPasswordProtectedZip (const String &zipFile, const String &password)
	Add a zipfile and password to FileSystem registry. More...

static void	removeFile (const String &path)
	Delete this file. More...

static int	rename (const String &src, const String &dst)

static String	resolve (const String &path, const String &cwd=currentDirectory())
	Fully qualifies a filename. More...

static void	setMarkFileUsedEnabled (bool enabled)
	Sets whether markFileUsed is enabled. More...

static int64	size (const String &path)
	Returns the length of the file in bytes, or -1 if the file could not be opened. More...

static String	tempFilename (const String &basePath=".")
	Creates a unique name for a temporary file. More...

static const Set< String > &	usedFiles ()
	All files that have been marked by markFileUsed(). More...

Detailed Description

OS-independent file system layer that optimizes the performance of queries by caching and prefetching.

This class uses the following definitions:

"file" = document that can be opened for reading or writing
"directory" = folder containing files and other directories
"node" = file or directory
"path" = string identifying a (see the FSPath class)
"zipfile" = a compressed file storing an archive of files and directories in the zip format

In G3D, Zipfiles are transparently treated as if they were directories, provided:

The zipfile name contains an extension (e.g., map.pk3, files.zip)
There are no nested zipfiles

All FileSystem routines invoke FilePath::expandEnvironmentVariables if the input contains a '$'.

The extension requirement allows G3D to quickly identify whether a path could enter a zipfile without forcing it to open all parent directories for reading.

See also: FilePath

Member Function Documentation

◆ cacheLifetime()

static float G3D::FileSystem::cacheLifetime ( )

inlinestatic

A cache is used to optimize repeated calls.

A cache entry is considered valid for this many seconds after it has been checked.

◆ cleanup()

static void G3D::FileSystem::cleanup ( )

static

Destroy the common instance.

◆ clearCache()

static void G3D::FileSystem::clearCache ( const String & path = "" )

inlinestatic

Clears old cache entries so that exists() and list() will reflect recent changes to the file system.

Parameters

path	Clear only path and its subdirectories ("" means clear the entire cache)

◆ clearUsedFiles()

static void G3D::FileSystem::clearUsedFiles ( )

static

Clears list of used files marked by markFileUsed().

◆ copyDir()

static void G3D::FileSystem::copyDir	(	const String &	srcPath,
		const String &	dstPath
	)

inlinestatic

Parameters

srcPath	Must name a directory or zipfile.
dstPath	Must name a directory

Flushes the cache.

◆ copyFile()

static void G3D::FileSystem::copyFile	(	const String &	srcPath,
		const String &	dstPath
	)

inlinestatic

Parameters

srcPath	Must name a file.
dstPath	Must not contain a zipfile.

Flushes the cache.

◆ createDirectory()

static void G3D::FileSystem::createDirectory ( const String & path )

inlinestatic

Creates the directory named, including any subdirectories that do not already exist.

The directory must not be inside a zipfile.

Flushes the cache.

◆ currentDirectory()

static String G3D::FileSystem::currentDirectory ( )

inlinestatic

The current working directory (cwd).

Only ends in a slash if this is the root of the file system.

◆ drives()

static const Array<String>& G3D::FileSystem::drives ( )

inlinestatic

On Windows, the drive letters that form the file system roots.

◆ exists()

static bool G3D::FileSystem::exists	(	const String &	f,
		bool	trustCache = `true`,
		bool	caseSensitive = `false`
	)

inlinestatic

Returns true if a node named f exists.

Parameters

f	If f contains wildcards, the function returns true if any file matches those wildcards. Wildcards may only appear in the base or ext, not the path. Environment variables beginning with dollar signs (e.g., in "$G3DDATA/cubemap"), with optional parens ("$(G3DDATA)") are automatically expanded in f. Default share names on Windows (e.g., "\\mycomputer\c$") are correctly distinguished from empty environment variables.
trustCache	If true, uses the cache for optimizing repeated calls in the same parent directory.
caseSensitive	If true, the match must have exactly the same case for the base and extension. If false, case is ignored. The default on Windows is false and the default on other operating systems is true.

◆ fclose()

static void G3D::FileSystem::fclose ( FILE * f )

inlinestatic

◆ fopen()

static FILE* G3D::FileSystem::fopen	(	const char *	filename,
		const char *	mode
	)

inlinestatic

Same as the C standard library fopen, but updates the file cache to acknowledge the new file on a write operation.

◆ getDirectories()

static void G3D::FileSystem::getDirectories	(	const String &	spec,
		Array< String > &	result,
		bool	includeParentPath = `false`
	)

inlinestatic

list() directories

◆ getFiles()

static void G3D::FileSystem::getFiles	(	const String &	spec,
		Array< String > &	result,
		bool	includeParentPath = `false`
	)

inlinestatic

list() files

◆ init()

static void G3D::FileSystem::init ( )

static

Create the common instance.

◆ inZipfile() [1/2]

static bool G3D::FileSystem::inZipfile	(	const String &	path,
		String &	zipfile,
		String &	pathInZipfile
	)

inlinestatic

Returns true if some sub-path of path is a zipfile.

If the path itself is a zipfile, returns false.

Parameters

zipfile	The part of path that was the zipfile, if the function returned true
pathInZipfile	The path within the zipfile to the named file, if the function returned true

◆ inZipfile() [2/2]

static bool G3D::FileSystem::inZipfile ( const String & path )

inlinestatic

Returns true if some sub-path of path is a zipfile.

If the path itself is a zipfile, returns false.

◆ isDirectory()

static bool G3D::FileSystem::isDirectory	(	const String &	path,
		bool	expandEnvironmentVariablesInPath = `true`
	)

inlinestatic

Known bug: does not work inside zipfiles.

◆ isFile()

static bool G3D::FileSystem::isFile ( const String & path )

inlinestatic

Known bug: does not work inside zipfiles.

◆ isNewer()

static bool G3D::FileSystem::isNewer	(	const String &	src,
		const String &	dst
	)

inlinestatic

Returns true if dst does not exist or src is newer than dst, according to their time stamps.

Known bug: does not work inside zipfiles.

◆ isPasswordProtected()

static bool G3D::FileSystem::isPasswordProtected	(	const String &	zipFile,
		String &	password
	)

static

If true, returns the password in the second parameter.

◆ isZipfile()

static bool G3D::FileSystem::isZipfile ( const String & path )

inlinestatic

Returns true if path is a file that is a zipfile.

Note that G3D requires zipfiles to have some extension, although it is not required to be "zip"

◆ list()

static void G3D::FileSystem::list	(	const String &	spec,
		Array< String > &	result,
		const ListSettings &	listSettings = `ListSettings()`
	)

inlinestatic

Appends all nodes matching spec to the result array.

Wildcards can only appear to the right of the last slash in spec.

The names will not contain parent paths unless includePath == true. These may be relative to the current directory unless spec is fully qualified (can be done with resolveFilename).

◆ markFileUsed()

static void G3D::FileSystem::markFileUsed ( const String & filename )

static

Adds filename to usedFiles().

This is called automatically by open() and all G3D routines that open files. Is thread-safe to call.

◆ NFDStandardizeFilename()

static String G3D::FileSystem::NFDStandardizeFilename	(	const String &	path,
		const String &	cwd = `currentDirectory()`
	)

inlinestatic

Attempts to fully resolve a filename, removing all instances of "." and "..", assuming that there are no Symlinks that would make "." or ".." difficult to reason about.

Also ensures that the slashes are consistent. NFD will crash when given a path that does not meet this qualifications

◆ registerPasswordProtectedZip()

static bool G3D::FileSystem::registerPasswordProtectedZip	(	const String &	zipFile,
		const String &	password
	)

static

Add a zipfile and password to FileSystem registry.

◆ removeFile()

static void G3D::FileSystem::removeFile ( const String & path )

inlinestatic

Delete this file.

No effect if path does not exist.

Parameters

path	May contain wildcards. May not be inside a zipfile.

◆ rename()

static int G3D::FileSystem::rename	(	const String &	src,
		const String &	dst
	)

inlinestatic

◆ resolve()

static String G3D::FileSystem::resolve	(	const String &	path,
		const String &	cwd = `currentDirectory()`
	)

inlinestatic

Fully qualifies a filename.

The filename may contain wildcards, in which case the wildcards will be preserved in the returned value.

Parameters

cwd	The directory to treat as the "current" directory when resolving a relative path. The default value is the actual current directory. (G3D::Any::sourceDirectory is a common alternative)

◆ setCacheLifetime()

void G3D::FileSystem::setCacheLifetime ( float t )

inline

Set the cacheLifetime().

Parameters

t	in seconds

◆ setMarkFileUsedEnabled()

static void G3D::FileSystem::setMarkFileUsedEnabled ( bool enabled )

static

Sets whether markFileUsed is enabled.

Files are not marked when disabled

◆ size()

static int64 G3D::FileSystem::size ( const String & path )

inlinestatic

Returns the length of the file in bytes, or -1 if the file could not be opened.

◆ tempFilename()

static String G3D::FileSystem::tempFilename ( const String & basePath = "." )

static

Creates a unique name for a temporary file.

This is on FileSystem instead of FilePath because it must check the actual filesystem for name conflicts.

◆ usedFiles()

static const Set<String>& G3D::FileSystem::usedFiles ( )

static

All files that have been marked by markFileUsed().

GApp automatically prints this list to log.txt. It is useful for finding the dependencies of your program automatically. Not thread-safe to use.

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ cacheLifetime()

◆ cleanup()

◆ clearCache()

◆ clearUsedFiles()

◆ copyDir()

◆ copyFile()

◆ createDirectory()

◆ currentDirectory()

◆ drives()

◆ exists()

◆ fclose()

◆ fopen()

◆ getDirectories()

◆ getFiles()

◆ init()

◆ inZipfile() [1/2]

◆ inZipfile() [2/2]

◆ isDirectory()

◆ isFile()

◆ isNewer()

◆ isPasswordProtected()

◆ isZipfile()

◆ list()

◆ markFileUsed()

◆ NFDStandardizeFilename()

◆ registerPasswordProtectedZip()

◆ removeFile()

◆ rename()

◆ resolve()

◆ setCacheLifetime()

◆ setMarkFileUsedEnabled()

◆ size()

◆ tempFilename()

◆ usedFiles()