Data Structures
struct	filelist_s
	Simple list for file searches. More...

struct	findfile_s

struct	gamedir_s
	Cached information about the current game directory. More...

Typedefs
typedef struct filelist_s	filelist_t
	Simple list for file searches. More...

typedef struct findfile_s	findfile_t

typedef void	gamedir_callback_t (int phase)
	Function type of callback called on gamedir change. More...

typedef struct gamedir_s	gamedir_t
	Cached information about the current game directory. More...

typedef struct vpath_s	vpath_t

Functions
QFile *	_QFS_FOpenFile (const char *filename, int zip)
	Open a file for reading. More...

QFile *	_QFS_VOpenFile (const char filename, int zip, const vpath_t start, const vpath_t *end)

char *	QFS_CompressPath (const char *pth)
	Create a canonical path. More...

void	QFS_DefaultExtension (struct dstring_s path, const char extension)
	Set the file extention if not already present. More...

char *	QFS_FileBase (const char *in)
	Extract the non-extension part of the file name from the path. More...

const char *	QFS_FileExtension (const char *in)
	Return a pointer to the start of the extention part of the path. More...

void	QFS_FilelistAdd (filelist_t filelist, const char fname, const char *ext)
	Add a single file to the file list. More...

void	QFS_FilelistFill (filelist_t list, const char path, const char *ext, int strip)
	Add files from the gamedir within the specified path. More...

void	QFS_FilelistFree (filelist_t *list)
	Free a file list. More...

filelist_t *	QFS_FilelistNew (void)
	Create a new file list. More...

findfile_t *	QFS_FindFile (const char fname, const vpath_t start, const vpath_t *end)
	Search for a file in the quake file-system. More...

QFile *	QFS_FOpenFile (const char *filename)
	Open a file for reading. More...

void	QFS_Gamedir (const char *gamedir)
	Change the current game directory. More...

void	QFS_GamedirCallback (gamedir_callback_t *func)
	Register a callback function for when the gamedir changes. More...

void	QFS_Init (const char *game)
	Initialize the Quake Filesystem. More...

void	QFS_LoadCacheFile (QFile file, struct cache_user_s cu)
	Load a file into memeory. More...

byte *	QFS_LoadFile (QFile *file, int usehunk)
	Load a file into memory. More...

byte *	QFS_LoadHunkFile (QFile *file)
	Load a file into memeory. More...

int	QFS_NextFilename (struct dstring_s filename, const char prefix, const char *ext)
	Find available filename. More...

QFile *	QFS_Open (const char path, const char mode)
	Open a file from within the user directory. More...

int	QFS_Remove (const char *path)
	Delete a file. More...

int	QFS_Rename (const char old_path, const char new_path)
	Rename a file. More...

void	QFS_SetExtension (struct dstring_s path, const char extension)
	Set the file extention. More...

const char *	QFS_SkipPath (const char *pathname)
	Return a pointer to the start of the filename part of the path. More...

void	QFS_StripExtension (const char in, char out)
	Remove any extension from the path. More...

QFile *	QFS_VOpenFile (const char filename, const vpath_t start, const vpath_t *end)

QFile *	QFS_WOpen (const char *path, int zip)
	Open a file for writing. More...

void	QFS_WriteFile (const char filename, const void data, int len)
	Write a block of data to a file. More...

Variables
int	qfs_filesize
	The size of the file found via QFS_FOpenFile() or _QFS_FOpenFile(). More...

findfile_t	qfs_foundfile
	Gives information about the last file opened by the FOpenFile functions. More...

gamedir_t *	qfs_gamedir
	Cached information about the current game directory. More...

const char *	qfs_userpath
	Base of the QFS user directory tree. More...

Detailed Description

Typedef Documentation

typedef struct filelist_s filelist_t

Simple list for file searches.

typedef struct findfile_s findfile_t

typedef void gamedir_callback_t(int phase)

Function type of callback called on gamedir change.

Parameters

phase 0 = before Cache_Flush(), 1 = after Cache_Flush()

typedef struct gamedir_s gamedir_t

Cached information about the current game directory.

See also: Directory Configuration.

typedef struct vpath_s vpath_t

Function Documentation

QFile* _QFS_FOpenFile	(	const char *	filename,
		int	zip
	)

Open a file for reading.

The file will be searched for through all the subdirectories given in the Path attribute (Directory Configuration). For each directory in Path, this function will check ${fs_userpath}/${dir} then ${fs_sharepath}/${dir}. In each location, pak files are checked before external files. pak files will be searched in reverse order (pak10.pak, pak9.pak, ... pak2.pak,pak1.pak,pak0.pak). However, any file ending in .pak will be checked whether it is a pak file.

Does name mangling for files with .gz extention and .wav-.ogg substitution.

Parameters

filename	The name of the file to open.
zip	If true and the file has been compressed with gzip, the file will be opened such that it decompresses on the fly. Otherwise, the file will be read as-is.

Returns: The file handle or NULL if there is an error.

QFile* _QFS_VOpenFile	(	const char *	filename,
		int	zip,
		const vpath_t *	start,
		const vpath_t *	end
	)

char* QFS_CompressPath ( const char * pth )

Create a canonical path.

Convert all \ to /, remove all . elements from the path and resolve all foo/.. pairs.

Parameters

pth	The path to make canonical

Returns: The canonical path.

Note: It is the caller's responsibility to free the canonical path.

void QFS_DefaultExtension	(	struct dstring_s *	path,
		const char *	extension
	)

Set the file extention if not already present.

If the file already has an extension, do nothing.

Parameters

path	The path to which the extension will be added.
extension	The extension to add.

char* QFS_FileBase ( const char * in )

Extract the non-extension part of the file name from the path.

Parameters

in	The path from which the name will be extracted.

Returns: The extracted name.

Note: It is the caller's responsibility to free the extracted name.

const char* QFS_FileExtension ( const char * in )

Return a pointer to the start of the extention part of the path.

Parameters

in	The path withing which to find the extention.

Returns: Pointer to the beginning of the extention. This points inside in at all times. If the path has no extension, the returned pointer will point to the terminating nul of the path.

void QFS_FilelistAdd	(	filelist_t *	filelist,
		const char *	fname,
		const char *	ext
	)

Add a single file to the file list.

If the extension of the file matches ext, it will be trimmed off the file name befor the file is added to the list.

Parameters

filelist	The list to which the file is to be added.
fname	The file which is to be added to the file list.
ext	The extention to be stripped from the file.

Todo:: Should the extension stripping be done by the caller?

void QFS_FilelistFill	(	filelist_t *	list,
		const char *	path,
		const char *	ext,
		int	strip
	)

Add files from the gamedir within the specified path.

All files from the specified path in the gamedir with the given extension will be added to the list after possibly stripping their extension.

Parameters

list	The list to which the files are to be added.
path	The path withing the gamedir from which files are to be added to the list.
ext	The extension of the files to be added.
strip	If true, the extension of the files will be stripped.

Bug:: can escape the quake file system

void QFS_FilelistFree ( filelist_t * list )

Free a file list.

Parameters

list	The list to be freed.

filelist_t* QFS_FilelistNew ( void )

Create a new file list.

Returns: Pointer to the new file list.

findfile_t* QFS_FindFile	(	const char *	fname,
		const vpath_t *	start,
		const vpath_t *	end
	)

Search for a file in the quake file-system.

The search will begin in the start vpath and end in the end vpath. If start is null, the search will begin in the vpath specified by qfs_vpaths (ie, the first directory in the Path attribute (Directory Configuration)). If end is null, the search will continue to the end of the list of vpaths. If start and end are the same (and non-null), then only the one vpath will be searched.

Note: All search paths in a vpath will be searched. This keeps QuakeForge's directory system transparent.; It is a fatal error for end to be non-null but not in the list of vpaths.

Warning: The returned pointer is to a static instance of findfile_t and thus will be overwritten on the next call to any of the search functions (QFS_FindFile, QFS_FOpenFile, _QFS_FOpenFile)

Parameters

fname	The name of the file to be searched for.
start	The first vpath (gamedir) to search.
end	The last vpath (gamedir) to search.

Returns: Pointer to the findfile_t record indicating the location of the file, or null if the file was not found.

QFile* QFS_FOpenFile ( const char * filename )

Open a file for reading.

This is a convenience wrapper for _QFS_FOpenFile(). The file will always be opened with decompression enabled. See the documentation for _QFS_FOpenFile() for more details.

Parameters

filename The name of the file to open.

Returns: The file handle pointer, or NULL if there is an error.

void QFS_Gamedir ( const char * gamedir )

Change the current game directory.

The configuration for the game directory is taken from Directory Configuration. Sets the fields in qfs_gamedir. Can be called at any time (and is, by the quakeworld clients and servers).

Parameters

gamedir The directory to which the game directory will be set.

void QFS_GamedirCallback ( gamedir_callback_t * func )

Register a callback function for when the gamedir changes.

The callbacks will be called in order of registration, in two passes. The first pass (phase is 0) is before the cache has been flushed. The second pass (phase is 1) is after the cache has been flushed.

Parameters

func	The function to call every time the gamedir changes via QFS_Gamedir().

void QFS_Init ( const char * game )

Initialize the Quake Filesystem.

This function initializes the fs_sharepath, fs_userpath and fs_dirconf Cvars. It then loads the Directory Configuration and parses the -game command line option.

Parameters

game	The game type used for searching the directory configuration. Currently, this is "qw" for quakeworld clients and servers, and one of "nq", "hexen", "rogue" or "abyss" for the netquake clients and servers.

void QFS_LoadCacheFile	(	QFile *	file,
		struct cache_user_s *	cu
	)

Load a file into memeory.

This is a wrapper for QFS_LoadFile().

Deprecated:: This should go away soon.

byte* QFS_LoadFile	(	QFile *	file,
		int	usehunk
	)

Load a file into memory.

The file will be loaded into memory allocated from the location indicated by usehunk.

Parameters

file	The handle of the file to load.
usehunk	The location from which to allocate memory for the file's data. Use 0.

Returns: Pointer to the file's data, or NULL on error.

Todo:: remove usehunk

byte* QFS_LoadHunkFile ( QFile * file )

Load a file into memeory.

The file is loaded into memory allocated from the hunk.

int QFS_NextFilename	(	struct dstring_s *	filename,
		const char *	prefix,
		const char *	ext
	)

Find available filename.

The filename will be of the form prefixXXXX.ext where XXXX is a zero padded number from 0 to 9999.

Parameters

filename	This will be set to the available filename.
prefix	The part of the filename preceeding the numers.
ext	The extension to add to the filename.

Returns: 1 for success, 0 for failure.

Note: prefix is relative to qfc_userpath.

QFile* QFS_Open	(	const char *	path,
		const char *	mode
	)

Open a file from within the user directory.

If path attempts to leave the user directory, this function sets errno to EACCESS and returns NULL. If mode indicates a write operation, then this function will make sure that any directories leading to the file exist.

Parameters

path	Path name of file to open, relative to qfs_userpath.
mode	Mode in which to open the file. Passed through as-is to Qopen ().

Returns: The file handle as returned by Qopen or NULL on error.

Note: This function cannot be used to access files within a pak file. For pak file support, use QFS_FOpenFile().

int QFS_Remove ( const char * path )

Delete a file.

Parameters

path	The file to delete.

Returns: 0 for success, -1 for failure.

Note: The file must be within qfs_userpath.

int QFS_Rename	(	const char *	old_path,
		const char *	new_path
	)

Rename a file.

Parameters

old_path	The file to rename.
new_path	The new name for the file.

Returns: 0 for success, -1 for failure.

Note: The file and destination must both be within qfs_userpath.

void QFS_SetExtension	(	struct dstring_s *	path,
		const char *	extension
	)

Set the file extention.

If the file already has an extension, it will be replaced.

Parameters

path	The path to which the extension will be set.
extension	The extension to set.

const char* QFS_SkipPath ( const char * pathname )

Return a pointer to the start of the filename part of the path.

Parameters

pathname The path withing which to find the filename.

Returns: Pointer to the beginning of the filename. This points inside pathname.

void QFS_StripExtension	(	const char *	in,
		char *	out
	)

Remove any extension from the path.

Parameters

in	The path from which to strip the extension.
out	The destination of the stripped path. May be the same as in.

Note: No size checking is done on out. It use the caller's responsibility to ensure out is large enough to hold the stripped path. However, the stripped path will never be longer than the original path.

QFile* QFS_VOpenFile	(	const char *	filename,
		const vpath_t *	start,
		const vpath_t *	end
	)

QFile* QFS_WOpen	(	const char *	path,
		int	zip
	)

Open a file for writing.

This is a convenience wrapper for QFS_Open(). If zip is true, then the file will be written uzing gzip compression if QuakeForge was built with zlib support, otherwise the file will be written uncompressed.

Parameters

path	Path name of file to open, relative to qfs_userpath.
zip	Compression control.

Returns: The file handle as returned by Qopen or NULL on error.

void QFS_WriteFile	(	const char *	filename,
		const void *	data,
		int	len
	)

Write a block of data to a file.

This is a convenience wrapper for QFS_Open().

Parameters

filename	Path name of file to open, relative to qfs_userpath.
data	Pointer to the block of data to be written.
len	The size of the block of data, in bytes.

Note: If an error occurs, this function will call Sys_Error(), aborting the program.

Variable Documentation

int qfs_filesize

The size of the file found via QFS_FOpenFile() or _QFS_FOpenFile().

Set by QFS_FOpenFile() and _QFS_FOpenFile().

findfile_t qfs_foundfile

Gives information about the last file opened by the FOpenFile functions.

Set by QFS_FOpenFile() and _QFS_FOpenFile().

gamedir_t* qfs_gamedir

Cached information about the current game directory.

See also: Directory Configuration.

const char* qfs_userpath

Base of the QFS user directory tree.

The QFS functions, except for QFS_FOpenFile() and _QFS_FOpenFile(), will never access a file outside of this tree. Set via the fs_userpath directory.

Data Structures

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

Function Documentation

Variable Documentation