fileUtils.h File Reference

#include "pxr/pxr.h"
#include "pxr/base/tf/api.h"
#include <string>
#include <vector>
#include <functional>

Include dependency graph for fileUtils.h:

Go to the source code of this file.

Typedefs
typedef std::function< bool(std::string const &, std::vector < std::string > *, std::vector < std::string > const &)>	TfWalkFunction
typedef std::function< void(std::string const &, std::string const &)>	TfWalkErrorHandler

Functions
PXR_NAMESPACE_OPEN_SCOPE TF_API bool	TfPathExists (std::string const &path, bool resolveSymlinks=false)
TF_API bool	TfIsDir (std::string const &path, bool resolveSymlinks=false)
TF_API bool	TfIsFile (std::string const &path, bool resolveSymlinks=false)
TF_API bool	TfIsLink (std::string const &path)
	Returns true if the path exists and is a symbolic link. More...
TF_API bool	TfIsWritable (std::string const &path)
TF_API bool	TfIsDirEmpty (std::string const &path)
	Returns true if the path is an empty directory. More...
TF_API bool	TfSymlink (std::string const &src, std::string const &dst)
	Creates a symbolic link from src to dst. More...
TF_API bool	TfDeleteFile (std::string const &path)
	Deletes a file at path. More...
TF_API bool	TfMakeDir (std::string const &path, int mode=-1)
TF_API bool	TfMakeDirs (std::string const &path, int mode=-1, bool existOk=false)
TF_API void	TfWalkIgnoreErrorHandler (std::string const &path, std::string const &msg)
TF_API void	TfWalkDirs (std::string const &top, TfWalkFunction fn, bool topDown=true, TfWalkErrorHandler onError=0, bool followLinks=false)
TF_API void	TfRmTree (std::string const &path, TfWalkErrorHandler onError=0)
TF_API std::vector< std::string >	TfListDir (std::string const &path, bool recursive=false)
TF_API bool	TfReadDir (std::string const &dirPath, std::vector< std::string > *dirnames, std::vector< std::string > *filenames, std::vector< std::string > *symlinknames, std::string *errMsg=NULL)
TF_API bool	TfTouchFile (std::string const &fileName, bool create=true)

Detailed Description

Definitions of basic file utilities in tf.

Definition in file fileUtils.h.

Typedef Documentation

typedef std::function<void (std::string const&, std::string const&)> TfWalkErrorHandler

TfRmTree error handler function.

The first parameter is the path which caused the error (file or directory), and the second parameter is an error message indicating why the error occurred.

Definition at line 131 of file fileUtils.h.

typedef std::function<bool (std::string const&, std::vector<std::string> *, std::vector<std::string> const&)> TfWalkFunction

Function type for TfWalkDirs.

This function is called once for each directory visited by TfWalkDirs. The first parameter is the directory path; if the topmost directory passed to TfWalkDirs is relative, this path will also be relative. The second parameter is a vector of subdirectory names, relative to the directory path. This parameter is a pointer, allowing the subdirectory list to be modified, thus controlling which directories are visited. Note that modifying the subdirectory vector has no effect when TfWalkDirs is called with topDown set to false. The final parameter is a vector of file names found in the directory path. The returned value determines whether the walk should be terminated (false), or continue (true).

Definition at line 123 of file fileUtils.h.

Function Documentation

TF_API bool TfDeleteFile

(

std::string const &

path

)

Deletes a file at path.

TF_API bool TfIsDir	(	std::string const &	path,
		bool	resolveSymlinks = false
	)

Returns true if the path exists and is a directory.

If resolveSymlinks is false (default), the path is checked using lstat(). if resolveSymlinks is true, the path is checked using stat(), which resolves all symbolic links in the path.

TF_API bool TfIsDirEmpty

(

std::string const &

path

)

Returns true if the path is an empty directory.

TF_API bool TfIsFile	(	std::string const &	path,
		bool	resolveSymlinks = false
	)

Returns true if the path exists and is a file.

If resolveSymlinks is false (default), the path is checked using lstat(). if resolveSymlinks is true, the path is checked using stat(), which resolves all symbolic links in the path.

TF_API bool TfIsLink

(

std::string const &

path

)

Returns true if the path exists and is a symbolic link.

TF_API bool TfIsWritable

(

std::string const &

path

)

Returns true if the file or directory at path is writable.

For this function to return true, the file must exist and be writable by the effective user, effective group, or all users. This function dereferences symbolic links, returning whether or not the resolved file or directory path is writable. If the file or directory does not exist, this function returns false.

TF_API std::vector<std::string> TfListDir	(	std::string const &	path,
		bool	recursive = false
	)

Return a list containing files and directories in path.

A trailing path separator character is appended to directories returned in the listing. If recursive is true, the directory listing will include all subdirectory structure of path.

TF_API bool TfMakeDir	(	std::string const &	path,
		int	mode = -1
	)

Creates a directory.

If the directory cannot be created, this function returns false. If no mode is specified, the default mode is 0777. If the specified path already exists, or an error occurs while creating the directory, this method returns false.

TF_API bool TfMakeDirs	(	std::string const &	path,
		int	mode = -1,
		bool	existOk = false
	)

Creates a directory hierarchy.

If any element of the path cannot be created, this function will return false. The specified mode will be used to create all new directories. If no mode is specified, the default mode of TfMakeDir is used. If the target directory exists, this function returns false if existOk is false.

PXR_NAMESPACE_OPEN_SCOPE TF_API bool TfPathExists	(	std::string const &	path,
		bool	resolveSymlinks = false
	)

Returns true if the path exists.

If resolveSymlinks is false (default), the path is checked using lstat(). if resolveSymlinks is true, the path is checked using stat(), which resolves all symbolic links in the path.

TF_API bool TfReadDir	(	std::string const &	dirPath,
		std::vector< std::string > *	dirnames,
		std::vector< std::string > *	filenames,
		std::vector< std::string > *	symlinknames,
		std::string *	errMsg = NULL
	)

Read the contents of dirPath and append the names of the contained directories, files, and symlinks to dirnames, filenames, and symlinknames, respectively.

Return true if dirPath 's contents were read successfully. Otherwise return false and set errMsg with a description of the error if errMsg is not NULL.

It is safe to pass NULL for any of dirnames, filenames, and symlinknames. In that case those elements are not reported

TF_API void TfRmTree	(	std::string const &	path,
		TfWalkErrorHandler	onError = 0
	)

Recursively delete a directory tree rooted at path.

Tf runtime errors are raised if any errors are encountered while deleting the specified path. Pass in TfWalkIgnoreErrorHandler() to ignore errors. Alternately, sending in a custom TfWalkErrorHandler will call this handler when errors occur. This handler receives the path which caused the error, and a message indicating why the error occurred.

TF_API bool TfSymlink	(	std::string const &	src,
		std::string const &	dst
	)

Creates a symbolic link from src to dst.

TF_API bool TfTouchFile	(	std::string const &	fileName,
		bool	create = true
	)

Touch fileName, updating access and modification time to 'now'.

A simple touch-like functionality. Simple in a sense that it does not offer as many options as the same-name unix touch command, but otherwise is identical to the default touch behavior. If create is true and the file does not already exist, an empty file gets created, otherwise the touch call fails if the file does not already exist.

TF_API void TfWalkDirs	(	std::string const &	top,
		TfWalkFunction	fn,
		bool	topDown = true,
		TfWalkErrorHandler	onError = 0,
		bool	followLinks = false
	)

Directory tree walker.

This function attempts to be as compatible as possible with Python's os.walk() function.

For each directory in the tree rooted at top (including top itself, but excluding '.' and '..'), the std::function fn is called with three arguments: dirpath, dirnames, and filenames.

dirpath is a string, the path to the directory. dirnames is a list of the names of the subdirectories in dirpath (excluding '.' and '..'). filenames is a list of the names of the non-directory files in dirpath. Note that the names in the sets are just names, with no path components. To get a full path (which begins with top) to a file or directory in dirpath, use TfStringCatPaths(dirpath, name).

If optional argument topDown is true, or not specified, fn is called for a directory before any subdirectories. If topdown is false, fn is called for a directory after all subdirectories. Additionally, when topDown is true, the walk function can modify the dirnames set in place. This can be used to prune the search, or to impose a specific visitation order. Modifying dirnames when topDown is false has no effect, since the directories in dirnames have already been visited by the time they are passed to fn.

The value returned by the error handler function onError determines what further action will be taken if an error is encountered. If true is returned, the walk will continue; if false, the walk will not continue.

If followLinks is false, symbolic links to directories encountered during the walk are passed to the walk function in the filenames vector. If followLinks is true, symbolic links to directories are passed to the walk function in the dirnames vector, and the walk will recurse into these directories.

If top is a symbolic link to a directory, it is followed regardless of the value of followLinks. Calling TfWalkDirs with a file argument returns immediately without calling fn.

TF_API void TfWalkIgnoreErrorHandler	(	std::string const &	path,
		std::string const &	msg
	)

error handler to use when you want to ignore errors

When calling TfWalkDirs/ChmodTree/RmTree and you want to ignore errors, you can pass in this public error handler which will ignore all the errors.