A hierarchy of directories and files that appears to be one continuous file system, even though the files may originate from several different sources that may not be related to the actual OS's file system. More...

#include "virtualFileSystem.h"

Public Types
enum	MountFlags { MF_read_only = 0x0002 }

enum	OpenFlags { OF_status_only = 0x0001, OF_create_file = 0x0002, OF_make_directory = 0x0004, OF_allow_nonexist = 0x0008 }

Public Member Functions
bool	atomic_compare_and_exchange_contents (const Filename &filename, std::string &orig_contents, const std::string &old_contents, const std::string &new_contents)
	See Filename::atomic_compare_and_exchange_contents(). More...

bool	atomic_read_contents (const Filename &filename, std::string &contents) const
	See Filename::atomic_read_contents(). More...

bool	chdir (const Filename &new_directory)
	Changes the current directory. More...

bool	copy_file (const Filename &orig_filename, const Filename &new_filename)
	Attempts to copy the contents of the indicated file to the indicated file. More...

PointerTo< VirtualFile >	create_file (const Filename &filename)
	Attempts to create a file by the indicated name in the filesystem, if possible, and returns it. More...

bool	delete_file (const Filename &filename)
	Attempts to delete the indicated file or directory. More...

bool	exists (const Filename &filename) const
	Convenience function; returns true if the named file exists. More...

int	find_all_files (const Filename &filename, const DSearchPath &searchpath, DSearchPath::Results &results) const
	Searches all the directories in the search list for the indicated file, in order. More...

PointerTo< VirtualFile >	find_file (const Filename &filename, const DSearchPath &searchpath, bool status_only=false) const
	Uses the indicated search path to find the file within the file system. More...

Filename	get_cwd () const
	Returns the current directory name. More...

PointerTo< VirtualFile >	get_file (const Filename &filename, bool status_only=false) const
	Looks up the file by the indicated name in the file system. More...

PointerTo< VirtualFileMount >	get_mount (int n) const

int	get_num_mounts () const

bool	is_directory (const Filename &filename) const
	Convenience function; returns true if the named file exists and is a directory. More...

bool	is_regular_file (const Filename &filename) const
	Convenience function; returns true if the named file exists and is a regular file. More...

void	ls (const Filename &filename) const

void	ls_all (const Filename &filename) const

bool	make_directory (const Filename &filename)
	Attempts to create a directory within the file system. More...

bool	make_directory_full (const Filename &filename)
	Attempts to create a directory within the file system. More...

bool	mount (Multifile *multifile, const Filename &mount_point, int flags)
	Mounts the indicated Multifile at the given mount point. More...

bool	mount (const Filename &physical_filename, const Filename &mount_point, int flags, const std::string &password="")
	Mounts the indicated system file or directory at the given mount point. More...

bool	mount (VirtualFileMount *mount, const Filename &mount_point, int flags)
	Adds the given VirtualFileMount object to the mount list. More...

bool	mount_loop (const Filename &virtual_filename, const Filename &mount_point, int flags, const std::string &password="")
	This is similar to mount(), but it receives the name of a Multifile that already appears within the virtual file system. More...

std::ostream *	open_append_file (const Filename &filename)
	Works like open_write_file(), but the file is opened in append mode. More...

std::iostream *	open_read_append_file (const Filename &filename)
	Works like open_read_write_file(), but the file is opened in append mode. More...

std::istream *	open_read_file (const Filename &filename, bool auto_unwrap) const
	Convenience function; returns a newly allocated istream if the file exists and can be read, or NULL otherwise. More...

std::iostream *	open_read_write_file (const Filename &filename, bool truncate)
	Convenience function; returns a newly allocated iostream if the file exists and can be written, or NULL otherwise. More...

std::ostream *	open_write_file (const Filename &filename, bool auto_wrap, bool truncate)
	Convenience function; returns a newly allocated ostream if the file exists and can be written, or NULL otherwise. More...

std::string	read_file (const Filename &filename, bool auto_unwrap) const

bool	read_file (const Filename &filename, std::string &result, bool auto_unwrap) const
	Convenience function; fills the string up with the data from the indicated file, if it exists and can be read. More...

bool	read_file (const Filename &filename, vector_uchar &result, bool auto_unwrap) const
	Convenience function; fills the pvector up with the data from the indicated file, if it exists and can be read. More...

bool	rename_file (const Filename &orig_filename, const Filename &new_filename)
	Attempts to move or rename the indicated file or directory. More...

bool	resolve_filename (Filename &filename, const DSearchPath &searchpath, const std::string &default_extension=std::string()) const
	Searches the given search path for the filename. More...

PointerTo< VirtualFileList >	scan_directory (const Filename &filename) const

void	scan_mount_points (vector_string &names, const Filename &path) const
	Adds to names a list of all the mount points in use that are one directory below path, if any. More...

int	unmount (Multifile *multifile)
	Unmounts all appearances of the indicated Multifile from the file system. More...

int	unmount (const Filename &physical_filename)
	Unmounts all appearances of the indicated directory name or multifile name from the file system. More...

int	unmount (VirtualFileMount *mount)
	Unmounts the indicated VirtualFileMount object from the file system. More...

int	unmount_all ()
	Unmounts all files from the file system. More...

int	unmount_point (const Filename &mount_point)
	Unmounts all systems attached to the given mount point from the file system. More...

void	write (std::ostream &out) const
	Print debugging information. More...

bool	write_file (const Filename &filename, const std::string &data, bool auto_wrap)

bool	write_file (const Filename &filename, const unsigned char *data, size_t data_size, bool auto_wrap)
	Convenience function; writes the entire contents of the indicated file as a block of data. More...

Static Public Member Functions
static void	close_read_file (std::istream *stream)
	Closes a file opened by a previous call to open_read_file(). More...

static void	close_read_write_file (std::iostream *stream)
	Closes a file opened by a previous call to open_read_write_file(). More...

static void	close_write_file (std::ostream *stream)
	Closes a file opened by a previous call to open_write_file(). More...

static VirtualFileSystem *	get_global_ptr ()
	Returns the default global VirtualFileSystem. More...

static void	parse_option (const std::string &option, int &flags, std::string &password)
	Parses one of the option flags in the options list on the vfs-mount Config.prc line. More...

static void	parse_options (const std::string &options, int &flags, std::string &password)
	Parses all of the option flags in the options list on the vfs-mount Config.prc line. More...

Public Attributes
	get_mount
	Returns the nth mount in the system. More...

	get_num_mounts
	Returns the number of individual mounts in the system. More...

ConfigVariableBool	vfs_case_sensitive

ConfigVariableBool	vfs_implicit_mf

ConfigVariableBool	vfs_implicit_pz

Detailed Description

A hierarchy of directories and files that appears to be one continuous file system, even though the files may originate from several different sources that may not be related to the actual OS's file system.

For instance, a VirtualFileSystem can transparently mount one or more Multifiles as their own subdirectory hierarchies.

Definition at line 40 of file virtualFileSystem.h.

Member Function Documentation

◆ atomic_compare_and_exchange_contents()

bool VirtualFileSystem::atomic_compare_and_exchange_contents	(	const Filename &	filename,
		std::string &	orig_contents,
		const std::string &	old_contents,
		const std::string &	new_contents
	)

See Filename::atomic_compare_and_exchange_contents().

Definition at line 1001 of file virtualFileSystem.cxx.

◆ atomic_read_contents()

bool VirtualFileSystem::atomic_read_contents	(	const Filename &	filename,
		std::string &	contents
	)		const

See Filename::atomic_read_contents().

Definition at line 1016 of file virtualFileSystem.cxx.

◆ chdir()

bool VirtualFileSystem::chdir ( const Filename & new_directory )

Changes the current directory.

This is used to resolve relative pathnames in get_file() and/or find_file(). Returns true if successful, false otherwise.

Definition at line 432 of file virtualFileSystem.cxx.

Referenced by get_global_ptr().

◆ close_read_file()

void VirtualFileSystem::close_read_file ( std::istream * stream )

static

Closes a file opened by a previous call to open_read_file().

This really just deletes the istream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

Definition at line 867 of file virtualFileSystem.cxx.

Referenced by PandaIOSystem::Close(), VirtualFileMount::close_read_file(), and FlacAudioCursor::~FlacAudioCursor().

◆ close_read_write_file()

void VirtualFileSystem::close_read_write_file ( std::iostream * stream )

static

Closes a file opened by a previous call to open_read_write_file().

This really just deletes the iostream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

Definition at line 986 of file virtualFileSystem.cxx.

Referenced by VirtualFileMount::close_read_write_file().

◆ close_write_file()

void VirtualFileSystem::close_write_file ( std::ostream * stream )

static

Closes a file opened by a previous call to open_write_file().

This really just deletes the ostream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

Definition at line 930 of file virtualFileSystem.cxx.

Referenced by VirtualFileMount::close_write_file().

◆ copy_file()

bool VirtualFileSystem::copy_file	(	const Filename &	orig_filename,
		const Filename &	new_filename
	)

Attempts to copy the contents of the indicated file to the indicated file.

Returns true on success, false on failure.

Definition at line 621 of file virtualFileSystem.cxx.

◆ create_file()

PointerTo< VirtualFile > VirtualFileSystem::create_file ( const Filename & filename )

Attempts to create a file by the indicated name in the filesystem, if possible, and returns it.

If a file by this name already exists, returns the same thing as get_file(). If the filename is located within a read- only directory, or the directory doesn't exist, returns NULL.

Definition at line 531 of file virtualFileSystem.cxx.

◆ delete_file()

bool VirtualFileSystem::delete_file ( const Filename & filename )

Attempts to delete the indicated file or directory.

This can remove a single file or an empty directory. It will not remove a nonempty directory. Returns true on success, false on failure.

Definition at line 576 of file virtualFileSystem.cxx.

◆ exists()

bool VirtualFileSystem::exists ( const Filename & filename ) const

inline

Convenience function; returns true if the named file exists.

Definition at line 18 of file virtualFileSystem.I.

References get_file().

Referenced by PandaIOSystem::Exists().

◆ find_all_files()

int VirtualFileSystem::find_all_files	(	const Filename &	filename,
		const DSearchPath &	searchpath,
		DSearchPath::Results &	results
	)		const

Searches all the directories in the search list for the indicated file, in order.

Fills up the results list with *all* of the matching filenames found, if any. Returns the number of matches found.

It is the responsibility of the the caller to clear the results list first; otherwise, the newly-found files will be appended to the list.

Definition at line 690 of file virtualFileSystem.cxx.

References DSearchPath::get_num_directories, and Filename::is_local().

◆ find_file()

PointerTo< VirtualFile > VirtualFileSystem::find_file	(	const Filename &	filename,
		const DSearchPath &	searchpath,
		bool	status_only = `false`
	)		const

Uses the indicated search path to find the file within the file system.

Returns the first occurrence of the file found, or NULL if the file cannot be found.

Definition at line 544 of file virtualFileSystem.cxx.

References get_file(), DSearchPath::get_num_directories, and Filename::is_local().

◆ get_cwd()

Filename VirtualFileSystem::get_cwd ( ) const

Returns the current directory name.

See chdir().

Definition at line 455 of file virtualFileSystem.cxx.

◆ get_file()

PointerTo< VirtualFile > VirtualFileSystem::get_file	(	const Filename &	filename,
		bool	status_only = `false`
	)		const

Looks up the file by the indicated name in the file system.

Returns a VirtualFile pointer representing the file if it is found, or NULL if it is not.

If status_only is true, the file will be checked for existence and length and so on, but the returned file's contents cannot be read. This is an optimization which is especially important for certain mount types, for instance HTTP, for which opening a file to determine its status is substantially less expensive than opening it to read its contents.

Definition at line 516 of file virtualFileSystem.cxx.

Referenced by exists(), find_file(), is_directory(), is_regular_file(), and read_file().

◆ get_global_ptr()

VirtualFileSystem * VirtualFileSystem::get_global_ptr ( )

static

Returns the default global VirtualFileSystem.

You may create your own personal VirtualFileSystem objects and use them for whatever you like, but Panda will attempt to load models and stuff from this default object.

Initially, the global VirtualFileSystem is set up to mount the OS filesystem to root; i.e. it is equivalent to the OS filesystem. This may be subsequently adjusted by the user.

Definition at line 742 of file virtualFileSystem.cxx.

References chdir(), init_libexpress(), and mount().

◆ is_directory()

bool VirtualFileSystem::is_directory ( const Filename & filename ) const

inline

Convenience function; returns true if the named file exists and is a directory.

Definition at line 27 of file virtualFileSystem.I.

References get_file(), and PT().

◆ is_regular_file()

bool VirtualFileSystem::is_regular_file ( const Filename & filename ) const

inline

Convenience function; returns true if the named file exists and is a regular file.

Definition at line 37 of file virtualFileSystem.I.

References get_file(), and PT().

◆ make_directory()

bool VirtualFileSystem::make_directory ( const Filename & filename )

Attempts to create a directory within the file system.

Returns true on success, false on failure (for instance, because the parent directory does not exist, or is read-only). If the directory already existed prior to this call, returns true.

Definition at line 469 of file virtualFileSystem.cxx.

◆ make_directory_full()

bool VirtualFileSystem::make_directory_full ( const Filename & filename )

Attempts to create a directory within the file system.

Will also create any intervening directories needed. Returns true on success, false on failure.

Definition at line 483 of file virtualFileSystem.cxx.

◆ mount() [1/3]

bool VirtualFileSystem::mount	(	Multifile *	multifile,
		const Filename &	mount_point,
		int	flags
	)

Mounts the indicated Multifile at the given mount point.

Definition at line 90 of file virtualFileSystem.cxx.

Referenced by get_global_ptr(), mount(), unmount(), unmount_all(), unmount_point(), and write().

◆ mount() [2/3]

bool VirtualFileSystem::mount	(	const Filename &	physical_filename,
		const Filename &	mount_point,
		int	flags,
		const std::string &	password = `""`
	)

Mounts the indicated system file or directory at the given mount point.

If the named file is a directory, mounts the directory. If the named file is a Multifile, mounts it as a Multifile. Returns true on success, false on failure.

A given system directory may be mounted to multiple different mount point, and the same mount point may share multiple system directories. In the case of ambiguities (that is, two different files with exactly the same full pathname), the most-recently mounted system wins.

The filename specified as the first parameter must refer to a real, physical filename on disk; it cannot be a virtual file already appearing within the vfs filespace. However, it is possible to mount such a file; see mount_loop() for this.

Note that a mounted VirtualFileSystem directory is fully case-sensitive, unlike the native Windows file system, so you must refer to files within the virtual file system with exactly the right case.

Definition at line 117 of file virtualFileSystem.cxx.

◆ mount() [3/3]

bool VirtualFileSystem::mount	(	VirtualFileMount *	mount,
		const Filename &	mount_point,
		int	flags
	)

Adds the given VirtualFileMount object to the mount list.

This is a lower- level function that the other flavors of mount(); it requires you to create a VirtualFileMount object specifically.

Definition at line 194 of file virtualFileSystem.cxx.

References mount().

◆ mount_loop()

bool VirtualFileSystem::mount_loop	(	const Filename &	virtual_filename,
		const Filename &	mount_point,
		int	flags,
		const std::string &	password = `""`
	)

This is similar to mount(), but it receives the name of a Multifile that already appears within the virtual file system.

It can be used to mount a Multifile that is itself hosted within a virtually-mounted Multifile.

This interface can also be used to mount physical files (that appear within the virtual filespace), but it cannot be used to mount directories. Use mount() if you need to mount a directory.

Note that there is additional overhead, in the form of additional buffer copies of the data, for recursively mounting a multifile like this.

Definition at line 158 of file virtualFileSystem.cxx.

◆ open_append_file()

ostream * VirtualFileSystem::open_append_file ( const Filename & filename )

Works like open_write_file(), but the file is opened in append mode.

Like open_write_file, the returned pointer should eventually be passed to close_write_file().

Definition at line 910 of file virtualFileSystem.cxx.

◆ open_read_append_file()

iostream * VirtualFileSystem::open_read_append_file ( const Filename & filename )

Works like open_read_write_file(), but the file is opened in append mode.

Like open_read_write_file, the returned pointer should eventually be passed to close_read_write_file().

Definition at line 966 of file virtualFileSystem.cxx.

◆ open_read_file()

istream * VirtualFileSystem::open_read_file	(	const Filename &	filename,
		bool	auto_unwrap
	)		const

Convenience function; returns a newly allocated istream if the file exists and can be read, or NULL otherwise.

Does not return an invalid istream.

If auto_unwrap is true, an explicitly-named .pz file is automatically decompressed and the decompressed contents are returned. This is different than vfs-implicit-pz, which will automatically decompress a file if the extension .pz is *not* given.

Definition at line 847 of file virtualFileSystem.cxx.

Referenced by PandaIOSystem::Open().

◆ open_read_write_file()

iostream * VirtualFileSystem::open_read_write_file	(	const Filename &	filename,
		bool	truncate
	)

Convenience function; returns a newly allocated iostream if the file exists and can be written, or NULL otherwise.

Does not return an invalid iostream.

Definition at line 947 of file virtualFileSystem.cxx.

◆ open_write_file()

ostream * VirtualFileSystem::open_write_file	(	const Filename &	filename,
		bool	auto_wrap,
		bool	truncate
	)

Convenience function; returns a newly allocated ostream if the file exists and can be written, or NULL otherwise.

Does not return an invalid ostream.

If auto_wrap is true, an explicitly-named .pz file is automatically compressed while writing. If truncate is true, the file is truncated to zero length before writing.

Definition at line 891 of file virtualFileSystem.cxx.

◆ parse_option()

void VirtualFileSystem::parse_option	(	const std::string &	option,
		int &	flags,
		std::string &	password
	)

static

Parses one of the option flags in the options list on the vfs-mount Config.prc line.

Definition at line 1092 of file virtualFileSystem.cxx.

◆ parse_options()

void VirtualFileSystem::parse_options	(	const std::string &	options,
		int &	flags,
		std::string &	password
	)

static

Parses all of the option flags in the options list on the vfs-mount Config.prc line.

Definition at line 1071 of file virtualFileSystem.cxx.

◆ read_file() [1/2]

bool VirtualFileSystem::read_file	(	const Filename &	filename,
		std::string &	result,
		bool	auto_unwrap
	)		const

inline

Convenience function; fills the string up with the data from the indicated file, if it exists and can be read.

Returns true on success, false otherwise.

If auto_unwrap is true, an explicitly-named .pz/.gz file is automatically decompressed and the decompressed contents are returned. This is different than vfs-implicit-pz, which will automatically decompress a file if the extension .pz is *not* given.

Definition at line 127 of file virtualFileSystem.I.

References get_file(), and PT().

◆ read_file() [2/2]

bool VirtualFileSystem::read_file	(	const Filename &	filename,
		vector_uchar &	result,
		bool	auto_unwrap
	)		const

inline

Convenience function; fills the pvector up with the data from the indicated file, if it exists and can be read.

Returns true on success, false otherwise.

If auto_unwrap is true, an explicitly-named .pz/.gz file is automatically decompressed and the decompressed contents are returned. This is different than vfs-implicit-pz, which will automatically decompress a file if the extension .pz is *not* given.

Definition at line 143 of file virtualFileSystem.I.

References get_file(), and PT().

◆ rename_file()

bool VirtualFileSystem::rename_file	(	const Filename &	orig_filename,
		const Filename &	new_filename
	)

Attempts to move or rename the indicated file or directory.

If the original file is an ordinary file, it will quietly replace any already- existing file in the new filename (but not a directory). If the original file is a directory, the new filename must not already exist.

If the file is a directory, the new filename must be within the same mount point. If the file is an ordinary file, the new filename may be anywhere; but if it is not within the same mount point then the rename operation is automatically performed as a two-step copy-and-delete operation.

Definition at line 597 of file virtualFileSystem.cxx.

◆ resolve_filename()

bool VirtualFileSystem::resolve_filename	(	Filename &	filename,
		const DSearchPath &	searchpath,
		const std::string &	default_extension = `std::string()`
	)		const

Searches the given search path for the filename.

If it is found, updates the filename to the full pathname found and returns true; otherwise, returns false.

Definition at line 641 of file virtualFileSystem.cxx.

◆ scan_mount_points()

void VirtualFileSystem::scan_mount_points	(	vector_string &	names,
		const Filename &	path
	)		const

Adds to names a list of all the mount points in use that are one directory below path, if any.

That is, these are the external files or directories mounted directly to the indicated path.

The names vector is filled with a set of basenames, the basename part of the mount point.

Definition at line 1034 of file virtualFileSystem.cxx.

Referenced by VirtualFile::scan_directory().

◆ unmount() [1/3]

int VirtualFileSystem::unmount ( Multifile * multifile )

Unmounts all appearances of the indicated Multifile from the file system.

Returns the number of appearances unmounted.

Definition at line 211 of file virtualFileSystem.cxx.

References mount().

◆ unmount() [2/3]

int VirtualFileSystem::unmount ( const Filename & physical_filename )

Unmounts all appearances of the indicated directory name or multifile name from the file system.

Returns the number of appearances unmounted.

Definition at line 253 of file virtualFileSystem.cxx.

References mount().

◆ unmount() [3/3]

int VirtualFileSystem::unmount ( VirtualFileMount * mount )

Unmounts the indicated VirtualFileMount object from the file system.

Returns the number of appearances unmounted.

Definition at line 312 of file virtualFileSystem.cxx.

References mount().

◆ unmount_all()

int VirtualFileSystem::unmount_all ( )

Unmounts all files from the file system.

Returns the number of systems unmounted.

Definition at line 381 of file virtualFileSystem.cxx.

References mount().

◆ unmount_point()

int VirtualFileSystem::unmount_point ( const Filename & mount_point )

Unmounts all systems attached to the given mount point from the file system.

Returns the number of appearances unmounted.

Definition at line 345 of file virtualFileSystem.cxx.

References mount().

◆ write()

void VirtualFileSystem::write ( std::ostream & out ) const

Print debugging information.

(e.g. from Python or gdb prompt).

Definition at line 721 of file virtualFileSystem.cxx.

References mount().

◆ write_file()

bool VirtualFileSystem::write_file	(	const Filename &	filename,
		const unsigned char *	data,
		size_t	data_size,
		bool	auto_wrap
	)

inline

Convenience function; writes the entire contents of the indicated file as a block of data.

If auto_wrap is true, an explicitly-named .pz file is automatically compressed while writing.

Definition at line 156 of file virtualFileSystem.I.

Member Data Documentation

◆ get_mount

PointerTo< VirtualFileMount > VirtualFileSystem::get_mount

Returns the nth mount in the system.

Definition at line 63 of file virtualFileSystem.h.

◆ get_num_mounts

int VirtualFileSystem::get_num_mounts

Returns the number of individual mounts in the system.

Definition at line 63 of file virtualFileSystem.h.

The documentation for this class was generated from the following files:

panda/src/express/virtualFileSystem.h
panda/src/express/virtualFileSystem.cxx
panda/src/express/virtualFileSystem.I

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ atomic_compare_and_exchange_contents()

◆ atomic_read_contents()

◆ chdir()

◆ close_read_file()

◆ close_read_write_file()

◆ close_write_file()

◆ copy_file()

◆ create_file()

◆ delete_file()

◆ exists()

◆ find_all_files()

◆ find_file()

◆ get_cwd()

◆ get_file()

◆ get_global_ptr()

◆ is_directory()

◆ is_regular_file()

◆ make_directory()

◆ make_directory_full()

◆ mount() [1/3]

◆ mount() [2/3]

◆ mount() [3/3]

◆ mount_loop()

◆ open_append_file()

◆ open_read_append_file()

◆ open_read_file()

◆ open_read_write_file()

◆ open_write_file()

◆ parse_option()

◆ parse_options()

◆ read_file() [1/2]

◆ read_file() [2/2]

◆ rename_file()

◆ resolve_filename()

◆ scan_mount_points()

◆ unmount() [1/3]

◆ unmount() [2/3]

◆ unmount() [3/3]

◆ unmount_all()

◆ unmount_point()

◆ write()

◆ write_file()

Member Data Documentation

◆ get_mount

◆ get_num_mounts