#include <bdls_filesystemutil.h>

Public Types
enum	Whence { e_SEEK_FROM_BEGINNING = 0 , e_SEEK_FROM_CURRENT = 1 , e_SEEK_FROM_END = 2 }

enum	{ k_DEFAULT_FILE_GROWTH_INCREMENT = 0x10000 }

enum	ErrorType { k_ERROR_LOCKING_CONFLICT = 1 , k_ERROR_LOCKING_INTERRUPTED = 2 , k_ERROR_ALREADY_EXISTS = 3 , k_ERROR_PATH_NOT_FOUND = 4 , k_ERROR_PAST_EOF = 5 , k_BAD_FILE_DESCRIPTOR = -1 }

enum	FileOpenPolicy { e_OPEN , e_CREATE , e_CREATE_PRIVATE , e_OPEN_OR_CREATE }

enum	FileIOPolicy { e_READ_ONLY , e_WRITE_ONLY , e_APPEND_ONLY , e_READ_WRITE , e_READ_APPEND }

enum	FileTruncatePolicy { e_TRUNCATE , e_KEEP }

Static Public Member Functions
static FileDescriptor	open (const char *path, FileOpenPolicy openPolicy, FileIOPolicy ioPolicy, FileTruncatePolicy truncatePolicy=e_KEEP)

template<class STRING_TYPE >
static FileDescriptor	open (const STRING_TYPE &path, FileOpenPolicy openPolicy, FileIOPolicy ioPolicy, FileTruncatePolicy truncatePolicy=e_KEEP)

static int	close (FileDescriptor descriptor)

static int	getWorkingDirectory (bsl::string *path)

static int	getWorkingDirectory (std::string *path)

static int	setWorkingDirectory (const char *path)

template<class STRING_TYPE >
static int	setWorkingDirectory (const STRING_TYPE &path)

static bool	exists (const char *path)

template<class STRING_TYPE >
static bool	exists (const STRING_TYPE &path)

static bool	isRegularFile (const char *path, bool followLinksFlag=false)

template<class STRING_TYPE >
static bool	isRegularFile (const STRING_TYPE &path, bool followLinksFlag=false)

static bool	isDirectory (const char *path, bool followLinksFlag=false)

template<class STRING_TYPE >
static bool	isDirectory (const STRING_TYPE &path, bool followLinksFlag=false)

static bool	isSymbolicLink (const char *path)

template<class STRING_TYPE >
static bool	isSymbolicLink (const STRING_TYPE &path)

static int	getLastModificationTime (bdlt::Datetime time, const char path)

template<class STRING_TYPE >
static int	getLastModificationTime (bdlt::Datetime *time, const STRING_TYPE &path)

static int	getLastModificationTime (bdlt::Datetime *time, FileDescriptor descriptor)

static int	createDirectories (const char *path, bool isLeafDirectoryFlag=false)

template<class STRING_TYPE >
static int	createDirectories (const STRING_TYPE &path, bool isLeafDirectoryFlag=false)

static int	createPrivateDirectory (const char *path)

template<class STRING_TYPE >
static int	createPrivateDirectory (const STRING_TYPE &path)

static int	getSystemTemporaryDirectory (bsl::string *path)

static int	getSystemTemporaryDirectory (std::string *path)

static FileDescriptor	createTemporaryFile (bsl::string *outPath, const bsl::string_view &prefix)

static FileDescriptor	createTemporaryFile (std::string *outPath, const bsl::string_view &prefix)

static int	createTemporaryDirectory (bsl::string *outPath, const bsl::string_view &prefix)

static int	createTemporaryDirectory (std::string *outPath, const bsl::string_view &prefix)

static int	createTemporarySubdirectory (bsl::string *outPath, const bsl::string_view &rootDirectory, const bsl::string_view &prefix)

static int	createTemporarySubdirectory (std::string *outPath, const bsl::string_view &rootDirectory, const bsl::string_view &prefix)

static void	makeUnsafeTemporaryFilename (bsl::string *outPath, const bsl::string_view &prefix)

static void	makeUnsafeTemporaryFilename (std::string *outPath, const bsl::string_view &prefix)

static int	visitPaths (const char pattern, const bsl::function< void(const char path)> &visitor)

template<class STRING_TYPE >
static int	visitPaths (const STRING_TYPE &pattern, const bsl::function< void(const char *path)> &visitor)

static int	visitTree (const bsl::string_view &root, const bsl::string_view &pattern, const bsl::function< void(const char *path)> &visitor, bool sortFlag=false)

static int	findMatchingPaths (bsl::vector< bsl::string > result, const char pattern)

template<class STRING_TYPE >
static int	findMatchingPaths (bsl::vector< bsl::string > *result, const STRING_TYPE &pattern)

static int	findMatchingPaths (std::vector< std::string > result, const char pattern)

template<class STRING_TYPE >
static int	findMatchingPaths (std::vector< std::string > *result, const STRING_TYPE &pattern)

static Offset	getAvailableSpace (const char *path)

template<class STRING_TYPE >
static Offset	getAvailableSpace (const STRING_TYPE &path)

static Offset	getAvailableSpace (FileDescriptor descriptor)

static Offset	getFileSize (const char *path)

template<class STRING_TYPE >
static Offset	getFileSize (const STRING_TYPE &path)

static Offset	getFileSize (FileDescriptor descriptor)

static Offset	getFileSizeLimit ()

static int	getSymbolicLinkTarget (bsl::string result, const char path)

static int	getSymbolicLinkTarget (std::string result, const char path)

template<class STRING_TYPE >
static int	getSymbolicLinkTarget (bsl::string *result, const STRING_TYPE &path)

template<class STRING_TYPE >
static int	getSymbolicLinkTarget (std::string *result, const STRING_TYPE &path)

static int	lock (FileDescriptor descriptor, bool lockWriteFlag)

static int	truncateFileSize (FileDescriptor descriptor, Offset size)

static int	tryLock (FileDescriptor descriptor, bool lockWriteFlag)

static int	unlock (FileDescriptor descriptor)

static int	map (FileDescriptor descriptor, void **address, Offset offset, bsl::size_t size, int mode)

static int	mapChecked (FileDescriptor descriptor, void **address, Offset offset, bsl::size_t size, int mode)

static int	unmap (void *address, bsl::size_t size)

static int	sync (char *address, bsl::size_t numBytes, bool syncFlag)

static Offset	seek (FileDescriptor descriptor, Offset offset, int whence)

static int	read (FileDescriptor descriptor, void *buffer, int numBytes)

static int	remove (const char *path, bool recursiveFlag=false)

template<class STRING_TYPE >
static int	remove (const STRING_TYPE &path, bool recursiveFlag=false)

static int	rollFileChain (const bsl::string_view &path, int maxSuffix)

static int	move (const char oldPath, const char newPath)

template<class OLD_STRING_TYPE , class NEW_STRING_TYPE >
static int	move (const OLD_STRING_TYPE &oldPath, const NEW_STRING_TYPE &newPath)

static int	write (FileDescriptor descriptor, const void *buffer, int numBytes)

static int	growFile (FileDescriptor descriptor, Offset size, bool reserveFlag=false, bsl::size_t increment=k_DEFAULT_FILE_GROWTH_INCREMENT)

Static Public Attributes
static const FileDescriptor	k_INVALID_FD

Detailed Description

This struct provides a namespace for utility functions dealing with platform-independent filesystem access.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
k_DEFAULT_FILE_GROWTH_INCREMENT

◆ ErrorType

enum bdls::FilesystemUtil::ErrorType

Enumerator
k_ERROR_LOCKING_CONFLICT
k_ERROR_LOCKING_INTERRUPTED
k_ERROR_ALREADY_EXISTS
k_ERROR_PATH_NOT_FOUND
k_ERROR_PAST_EOF
k_BAD_FILE_DESCRIPTOR

◆ FileIOPolicy

enum bdls::FilesystemUtil::FileIOPolicy

Enumeration used to distinguish between different sets of actions permitted on an open file descriptor.

Enumerator
e_READ_ONLY
e_WRITE_ONLY
e_APPEND_ONLY
e_READ_WRITE
e_READ_APPEND

◆ FileOpenPolicy

enum bdls::FilesystemUtil::FileOpenPolicy

Enumeration used to determine whether 'open' should open an existing file, or create a new file.

Enumerator
e_OPEN
e_CREATE
e_CREATE_PRIVATE
e_OPEN_OR_CREATE

◆ FileTruncatePolicy

enum bdls::FilesystemUtil::FileTruncatePolicy

Enumeration used to distinguish between different ways to handle the contents, if any, of an existing file immediately upon opening the file.

Enumerator
e_TRUNCATE
e_KEEP

◆ Whence

enum bdls::FilesystemUtil::Whence

Enumeration used to distinguish among different starting points for a seek operation.

Enumerator
e_SEEK_FROM_BEGINNING
e_SEEK_FROM_CURRENT
e_SEEK_FROM_END

Member Function Documentation

◆ close()

static int bdls::FilesystemUtil::close ( FileDescriptor descriptor )

static

Close the specified descriptor. Return 0 on success and a non-zero value otherwise. A return value of k_BAD_FILE_DESCRIPTOR indicates that the supplied descriptor is invalid.

◆ createDirectories() [1/2]

static int bdls::FilesystemUtil::createDirectories	(	const char *	path,
		bool	isLeafDirectoryFlag = `false`
	)

static

Create any directories in the specified path that do not exist. If the optionally specified isLeafDirectoryFlag is true, treat the final name component in path as a directory name, and create it. Otherwise, create only the directories leading up to the final name component. Return 0 on success, k_ERROR_PATH_NOT_FOUND if a component used as a directory in path exists but is not a directory, and a negative value for any other kind of error. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ createDirectories() [2/2]

template<class STRING_TYPE >

int bdls::FilesystemUtil::createDirectories	(	const STRING_TYPE &	path,
		bool	isLeafDirectoryFlag = `false`
	)

inlinestatic

◆ createPrivateDirectory() [1/2]

static int bdls::FilesystemUtil::createPrivateDirectory ( const char * path )

static

Create a private directory with the specified path. Return 0 on success, k_ERROR_PATH_NOT_FOUND if a component used as a directory in path either does not exist or is not a directory, k_ERROR_ALREADY_EXISTS if the file system entry (not necessarily a directory) with the name path already exists, and a negative value for any other kind of error. The directory is created with permissions restricting access, as closely as possible, to the caller's userid only. Note that directories created on Microsoft Windows may receive default, not restricted permissions. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ createPrivateDirectory() [2/2]

template<class STRING_TYPE >

int bdls::FilesystemUtil::createPrivateDirectory ( const STRING_TYPE & path )

inlinestatic

◆ createTemporaryDirectory() [1/2]

static int bdls::FilesystemUtil::createTemporaryDirectory	(	bsl::string *	outPath,
		const bsl::string_view &	prefix
	)

static

◆ createTemporaryDirectory() [2/2]

static int bdls::FilesystemUtil::createTemporaryDirectory	(	std::string *	outPath,
		const bsl::string_view &	prefix
	)

static

Create a new directory with a name constructed by appending an automatically-generated suffix to the specified prefix. A non-zero return value indicates that no such directory could be created; otherwise the name of the directory created is assigned to the specified outPath. The directory is created with permissions restricted, as closely as possible, to the caller only. If the prefix is a relative path, the directory is created relative to the process current directory. Responsibility for deleting the directory (and any files subsequently created in it) is left to the caller.

◆ createTemporaryFile() [1/2]

static FileDescriptor bdls::FilesystemUtil::createTemporaryFile	(	bsl::string *	outPath,
		const bsl::string_view &	prefix
	)

static

◆ createTemporaryFile() [2/2]

static FileDescriptor bdls::FilesystemUtil::createTemporaryFile	(	std::string *	outPath,
		const bsl::string_view &	prefix
	)

static

Create and open a new file with a name constructed by appending an automatically-generated suffix to the specified prefix, and return its file descriptor open for reading and writing. A return value of k_INVALID_FD indicates that no such file could be created; otherwise, the name of the file created is assigned to the specified outPath. The file is created with permissions restricted, as closely as possible, to the callers userid only. If the prefix is a relative path, the file is created relative to the process current directory. Responsibility for deleting the file is left to the caller. Note that on Posix systems, ifoutPath` is unlinked immediately, the file will remain usable until its descriptor is closed. Note that files created on Microsoft Windows may receive default, not restricted permissions.

◆ createTemporarySubdirectory() [1/2]

static int bdls::FilesystemUtil::createTemporarySubdirectory	(	bsl::string *	outPath,
		const bsl::string_view &	rootDirectory,
		const bsl::string_view &	prefix
	)

static

◆ createTemporarySubdirectory() [2/2]

static int bdls::FilesystemUtil::createTemporarySubdirectory	(	std::string *	outPath,
		const bsl::string_view &	rootDirectory,
		const bsl::string_view &	prefix
	)

static

Create a new directory with a name constructed by appending an automatically-generated suffix to the specified prefix within the specified rootDirectory. A non-zero return value indicates that no such directory could be created; otherwise the name of the directory created is assigned to the specified outPath. The directory is created with permissions restricted, as closely as possible, to the caller only. If the rootDirectory is a relative path, the directory is created relative to the process current directory. Responsibility for deleting the directory (and any files subsequently created in it) is left to the caller.

◆ exists() [1/2]

static bool bdls::FilesystemUtil::exists ( const char * path )

static

Return true if there currently exists a file or directory at the specified path, and false otherwise. If path is a symlink, the result of this function is platform dependent. On POSIX/Unix platforms this method dereferences symlinks, while on Windows it does not. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ exists() [2/2]

template<class STRING_TYPE >

bool bdls::FilesystemUtil::exists ( const STRING_TYPE & path )

inlinestatic

◆ findMatchingPaths() [1/4]

static int bdls::FilesystemUtil::findMatchingPaths	(	bsl::vector< bsl::string > *	result,
		const char *	pattern
	)

static

Load into the specified result vector all paths in the filesystem matching the specified pattern. The '*' character will match any number of characters in a filename; however, this matching will not span a directory separator (e.g., "logs/m*.txt" will not match "logs/march/001.txt"). '?' will match any one character. '*' and '?' may be used any number of times in the pattern. The special directories "." and ".." will not be matched against any pattern. Note that any initial contents of result will be erased, and that the paths in result will not be in any particular guaranteed order. Return the number of paths matched on success, and a negative value otherwise; if a negative value is returned, the contents of *result are undefined. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

WINDOWS-SPECIFIC NOTE: To support DOS idioms, the OS-provided search function has behavior that we have chosen not to work around: an extension consisting of wild-card characters ('?', '*') can match an extension or no extension. E.g., "file.?" matches "file.z", but not "file.txt"; however, it also matches "file" (without any extension). Likewise, "*.*" matches any filename, including filenames having no extension. Also, on Windows (but not on Unix) attempting to match a pattern that is invalid UTF-8 will result in an error.

IBM-SPECIFIC WARNING: This function is not thread-safe. The AIX implementation of the system glob function can temporarily change the working directory of the entire program, casuing attempts in other threads to open files with relative path names to fail.

◆ findMatchingPaths() [2/4]

template<class STRING_TYPE >

int bdls::FilesystemUtil::findMatchingPaths	(	bsl::vector< bsl::string > *	result,
		const STRING_TYPE &	pattern
	)

inlinestatic

◆ findMatchingPaths() [3/4]

static int bdls::FilesystemUtil::findMatchingPaths	(	std::vector< std::string > *	result,
		const char *	pattern
	)

static

◆ findMatchingPaths() [4/4]

template<class STRING_TYPE >

int bdls::FilesystemUtil::findMatchingPaths	(	std::vector< std::string > *	result,
		const STRING_TYPE &	pattern
	)

inlinestatic

◆ getAvailableSpace() [1/3]

static Offset bdls::FilesystemUtil::getAvailableSpace ( const char * path )

static

Return the number of bytes available for allocation in the file system where the file or directory with the specified path resides, or a negative value if an error occurs. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ getAvailableSpace() [2/3]

template<class STRING_TYPE >

FilesystemUtil::Offset bdls::FilesystemUtil::getAvailableSpace ( const STRING_TYPE & path )

inlinestatic

◆ getAvailableSpace() [3/3]

static Offset bdls::FilesystemUtil::getAvailableSpace ( FileDescriptor descriptor )

static

Return the number of bytes available for allocation in the file system where the file with the specified descriptor resides, or a negative value if an error occurs.

◆ getFileSize() [1/3]

static Offset bdls::FilesystemUtil::getFileSize ( const char * path )

static

Return the size, in bytes, of the file or directory at the specified path, or a negative value if an error occurs. Note that the size of a symbolic link is the size of the file or directory to which it points. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ getFileSize() [2/3]

template<class STRING_TYPE >

FilesystemUtil::Offset bdls::FilesystemUtil::getFileSize ( const STRING_TYPE & path )

inlinestatic

◆ getFileSize() [3/3]

static Offset bdls::FilesystemUtil::getFileSize ( FileDescriptor descriptor )

static

Return the size, in bytes, of the file or directory specified by the specified open descriptor, or a negative value if an error occurs. Note that the size of a symbolic link is the size of the file or directory to which it points.

◆ getFileSizeLimit()

static Offset bdls::FilesystemUtil::getFileSizeLimit ( )

static

Return the file size limit for this process, k_OFFSET_MAX if no limit is set, or a negative value if an error occurs. Note that if you are doing any calculations involving the returned value, it is recommended to check for k_OFFSET_MAX specifically to avoid integer overflow in your calculations.

◆ getLastModificationTime() [1/3]

static int bdls::FilesystemUtil::getLastModificationTime	(	bdlt::Datetime *	time,
		const char *	path
	)

static

Load into the specified time the last modification time of the file at the specified path, as reported by the filesystem. Return 0 on success, and a non-zero value otherwise. The time is reported in UTC. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ getLastModificationTime() [2/3]

template<class STRING_TYPE >

int bdls::FilesystemUtil::getLastModificationTime	(	bdlt::Datetime *	time,
		const STRING_TYPE &	path
	)

inlinestatic

◆ getLastModificationTime() [3/3]

static int bdls::FilesystemUtil::getLastModificationTime	(	bdlt::Datetime *	time,
		FileDescriptor	descriptor
	)

static

Load into the specified time the last modification time of the file with the specified descriptor, as reported by the filesystem. Return 0 on success, and a non-zero value otherwise. The time is reported in UTC.

◆ getSymbolicLinkTarget() [1/4]

static int bdls::FilesystemUtil::getSymbolicLinkTarget	(	bsl::string *	result,
		const char *	path
	)

static

◆ getSymbolicLinkTarget() [2/4]

template<class STRING_TYPE >

int bdls::FilesystemUtil::getSymbolicLinkTarget	(	bsl::string *	result,
		const STRING_TYPE &	path
	)

inlinestatic

◆ getSymbolicLinkTarget() [3/4]

static int bdls::FilesystemUtil::getSymbolicLinkTarget	(	std::string *	result,
		const char *	path
	)

static

Load, into the specified result, the target of the symbolic link at the specified path. Return 0 on success, and a non-zero value otherwise. For example, this function will return an error if path does not refer to a symbolic link. Windows directory junctions are treated as directory symbolic links. If path is a relative path, it is evaluated against the current working directory. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ getSymbolicLinkTarget() [4/4]

template<class STRING_TYPE >

int bdls::FilesystemUtil::getSymbolicLinkTarget	(	std::string *	result,
		const STRING_TYPE &	path
	)

inlinestatic

◆ getSystemTemporaryDirectory() [1/2]

static int bdls::FilesystemUtil::getSystemTemporaryDirectory ( bsl::string * path )

static

◆ getSystemTemporaryDirectory() [2/2]

static int bdls::FilesystemUtil::getSystemTemporaryDirectory ( std::string * path )

static

Load a valid path to the system temporary directory to the specified path. Return 0 on success, and a non-zero value otherwise. A temporary directory is one in which the operating system has permission to delete its contents, but not necessarily the directory itself, the next time the computer reboots.

◆ getWorkingDirectory() [1/2]

static int bdls::FilesystemUtil::getWorkingDirectory ( bsl::string * path )

static

◆ getWorkingDirectory() [2/2]

static int bdls::FilesystemUtil::getWorkingDirectory ( std::string * path )

static

Load into the specified 'path' the absolute pathname of the current working directory. Return 0 on success and a non-zero value otherwise.

◆ growFile()

static int bdls::FilesystemUtil::growFile	(	FileDescriptor	descriptor,
		Offset	size,
		bool	reserveFlag = `false`,
		bsl::size_t	increment = `k_DEFAULT_FILE_GROWTH_INCREMENT`
	)

static

Grow the file with the specified descriptor to the size of at least the specified size bytes. Return 0 on success, and a non-zero value otherwise. If the optionally specified reserveFlag is true, make sure the space on disk is preallocated and not allocated on demand, preventing a possible out-of-disk-space error when accessing the data on file systems with sparse file support. Preallocation is done by writing unspecified data to file in blocks of the optionally specified increment or a default value if increment is zero or unspecified. Note that if the size of the file is greater than or equal to size, this function has no effect. Also note that the contents of the newly grown portion of the file is undefined.

◆ isDirectory() [1/2]

static bool bdls::FilesystemUtil::isDirectory	(	const char *	path,
		bool	followLinksFlag = `false`
	)

static

Return true if there currently exists a directory at the specified path, and false otherwise. If there is a symbolic link at path, follow it only if the optionally specified followLinksFlag is true (otherwise return false). Platform-specific note: On Windows, a "shortcut" is not a symbolic link. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ isDirectory() [2/2]

template<class STRING_TYPE >

bool bdls::FilesystemUtil::isDirectory	(	const STRING_TYPE &	path,
		bool	followLinksFlag = `false`
	)

inlinestatic

◆ isRegularFile() [1/2]

static bool bdls::FilesystemUtil::isRegularFile	(	const char *	path,
		bool	followLinksFlag = `false`
	)

static

Return true if there currently exists a regular file at the specified path, and false otherwise. If there is a symbolic link at path, follow it only if the optionally specified followLinksFlag is true (otherwise, return false as the symbolic link itself is not a regular file irrespective of the file to which it points). Platform-specific note: On POSIX, this is a positive test on the "regular file" mode; on Windows, this is a negative test on the "directory" attribute, i.e., on Windows, everything that exists and is not a directory is a regular file. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ isRegularFile() [2/2]

template<class STRING_TYPE >

bool bdls::FilesystemUtil::isRegularFile	(	const STRING_TYPE &	path,
		bool	followLinksFlag = `false`
	)

inlinestatic

◆ isSymbolicLink() [1/2]

static bool bdls::FilesystemUtil::isSymbolicLink ( const char * path )

static

Return true if there currently exists a symbolic link at the specified path, and false otherwise. Windows directory junctions are treated as directory symbolic links. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ isSymbolicLink() [2/2]

template<class STRING_TYPE >

bool bdls::FilesystemUtil::isSymbolicLink ( const STRING_TYPE & path )

inlinestatic

◆ lock()

static int bdls::FilesystemUtil::lock	(	FileDescriptor	descriptor,
		bool	lockWriteFlag
	)

static

Acquire a lock for the file with the specified descriptor. If lockWriteFlag is true, acquire an exclusive write lock; otherwise acquire a (possibly) shared read lock. The calling thread will block until the lock is acquired. Return 0 on success, and a non-zero value otherwise. Note that this operation locks the indicated file for use by the current process, but the behavior is unspecified (and platform-dependent) when either attempting to lock descriptor multiple times, or attempting to lock another descriptor referring to the same file, within a single process.

◆ makeUnsafeTemporaryFilename() [1/2]

static void bdls::FilesystemUtil::makeUnsafeTemporaryFilename	(	bsl::string *	outPath,
		const bsl::string_view &	prefix
	)

static

◆ makeUnsafeTemporaryFilename() [2/2]

static void bdls::FilesystemUtil::makeUnsafeTemporaryFilename	(	std::string *	outPath,
		const bsl::string_view &	prefix
	)

static

Construct a file name by appending an automatically-generated suffix to the specified prefix. The file name constructed is assigned to the specified outPath. Note that this function is called "unsafe" because a file with the resulting name may be created by another program before the caller has opportunity to use the name, which could be a security vulnerability, and a file with the given name may already exist where you mean to put it. Note that the suffix is hashed from environmental details, including any pre-existing value of outPath so that if a resulting name is unsuitable (e.g. the file exists) this function may simply be called again, pointing to its previous result, to get a new, probably different name.

◆ map()

static int bdls::FilesystemUtil::map	(	FileDescriptor	descriptor,
		void **	address,
		Offset	offset,
		bsl::size_t	size,
		int	mode
	)

static

Map the region of the specified size bytes, starting at the specified offset bytes into the file with the specified descriptor to memory, and load into the specified address of the mapped area. Return 0 on success, and a non-zero value otherwise. The access permissions for mapping memory are defined by the specified mode, which may be a combination of MemoryUtil::k_ACCESS_READ, MemoryUtil::k_ACCESS_WRITE and MemoryUtil::k_ACCESS_EXECUTE. Note that on failure, the value of address is undefined. Also note that mapping will succeed even if there are fewer than offset + size bytes in the specified file, and an attempt to access the mapped memory beyond the end of the file will result in undefined behavior (i.e., this function does not grow the file to guarantee it can accommodate the mapped region). Also note that mapping past the end of file may return 0, but any access of the resulting mapped memory may segfault.

◆ mapChecked()

static int bdls::FilesystemUtil::mapChecked	(	FileDescriptor	descriptor,
		void **	address,
		Offset	offset,
		bsl::size_t	size,
		int	mode
	)

static

Map the region of the specified size bytes, starting at the specified offset bytes into the file with the specified descriptor to memory, and load into the specified address of the mapped area. Return 0 on success, k_ERROR_PAST_EOF if an attempt is made to map past the end of file, and a non-zero value otherwise. The access permissions for mapping memory are defined by the specified mode, which may be a combination of MemoryUtil::k_ACCESS_READ, MemoryUtil::k_ACCESS_WRITE and MemoryUtil::k_ACCESS_EXECUTE, though on some platforms they must be a subset of the file permissions. The behavior is undefined unless bits in mode other than MemoryUtil::k_ACCESS_READ_WRITE_EXECUTE are all clear, unless 0 <= offset, and unless 0 < size, and unless the offset is a multiple of MemoryUtil::pageSize(). Note that on failure, the value of address is undefined. Also note that the check against mapping past the end of file and all assertions are done before the call to map the file.

◆ move() [1/2]

static int bdls::FilesystemUtil::move	(	const char *	oldPath,
		const char *	newPath
	)

static

Move the file or directory at the specified oldPath to the specified newPath. If there is a file or directory at newPath, it will be removed and replaced. In that case, newPath must refer to the same type of filesystem item as oldPath - that is, they must both be directories or both be files. Return 0 on success, and a non-zero value otherwise. If oldPath is a symbolic link, the link will be renamed. If a symbolic link already exists at newPath, the resulting behavior is platform dependent. Note that this operation is carried out via library/system facilities (rename in UNIX and MoveFile in Windows) that usually cannot move files between file systems or volumes, and that the behavior of the underlying library/system facilities differs when oldPath and newPath refer to the same file (in that case, UNIX succeeds, Windows fails). Note that a symbolic link already exists at newPath POSIX/Unix systems will overwrite that existing symbolic link, while Windows will return an error status (GetLastError will report ERROR_ALREADY_EXISTS). The parameterized OLD_STRING_TYPE and NEW_STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ move() [2/2]

template<class OLD_STRING_TYPE , class NEW_STRING_TYPE >

int bdls::FilesystemUtil::move	(	const OLD_STRING_TYPE &	oldPath,
		const NEW_STRING_TYPE &	newPath
	)

inlinestatic

◆ open() [1/2]

static FileDescriptor bdls::FilesystemUtil::open	(	const char *	path,
		FileOpenPolicy	openPolicy,
		FileIOPolicy	ioPolicy,
		FileTruncatePolicy	truncatePolicy = `e_KEEP`
	)

static

Open the file at the specified path, using the specified openPolicy to determine whether to open an existing file or create a new file, and using the specified ioPolicy to determine whether the file will be opened for reading, writing, or both. Optionally specify a truncatePolicy to determine whether any contents of the file will be deleted before open returns. If truncatePolicy is not supplied, the value e_KEEP will be used. Return a valid FileDescriptor for the file on success, or k_INVALID_FD otherwise. If openPolicy is e_OPEN, the file will be opened if it exists, and open will fail otherwise. If openPolicy is e_CREATE or e_CREATE_PRIVATE, and no file exists at path, a new file will be created, and open will fail otherwise. If openPolicy is e_CREATE_PRIVATE, the file will be created with access restricted to the same userid as the caller in environments where that is supported (which does not necessarily include Windows) otherwise the system default access policy is used (e.g. '0777 & ~umask'). If openPolicy is e_OPEN_OR_CREATE, the file will be opened if it exists, and a new file will be created otherwise. If ioPolicy is e_READ_ONLY, the returned FileDescriptor will allow only read operations on the file. If ioPolicy is e_WRITE_ONLY or e_APPEND_ONLY, the returned FileDescriptor will allow only write operations on the file. If ioPolicy is e_READ_WRITE or e_READ_APPEND, the returned FileDescriptor will allow both read and write operations on the file. Additionally, if ioPolicy is e_APPEND_ONLY or e_READ_APPEND all writes will be made to the end of the file ("append mode"). If truncatePolicy is e_TRUNCATE, the file will have zero length when open returns. If truncatePolicy is e_KEEP, the file will be opened with its existing contents, if any. Note that when a file is opened in append mode, all writes will go to the end of the file, even if there has been seeking on the file descriptor or another process has changed the length of the file. Append-mode writes are not atomic except in limited cases; another thread, or even another process, operating on the file may cause output not to be written, unbroken, to the end of the file. (Unix environments writing to local file systems may promise more.) Note that open will fail to open a file with a truncatePolicy of e_TRUNCATE unless at least one of the following policies is specified for openPolicy or ioPolicy:

e_CREATE
e_CREATE_PRIVATE
e_OPEN_OR_CREATE
'e_WRITE_ONLY
e_READ_WRITE The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ open() [2/2]

template<class STRING_TYPE >

FilesystemUtil::FileDescriptor bdls::FilesystemUtil::open	(	const STRING_TYPE &	path,
		FileOpenPolicy	openPolicy,
		FileIOPolicy	ioPolicy,
		FileTruncatePolicy	truncatePolicy = `e_KEEP`
	)

inlinestatic

◆ read()

static int bdls::FilesystemUtil::read	(	FileDescriptor	descriptor,
		void *	buffer,
		int	numBytes
	)

static

Read the specified numBytes bytes beginning at the file pointer of the file with the specified descriptor into the specified buffer. Return numBytes on success; the number of bytes read if there were not enough available; or a negative number on some other error.

◆ remove() [1/2]

static int bdls::FilesystemUtil::remove	(	const char *	path,
		bool	recursiveFlag = `false`
	)

static

Remove the file or directory at the specified path. If the path refers to a directory and the optionally specified recursiveFlag is true, recursively remove all files and directories within the specified directory before removing the directory itself. Return 0 on success and a non-zero value otherwise. If path refers to a symbolic link, the symbolic link will be removed, not the target of the link. Note that if path is a directory, and the directory is not empty, and recursive is false, this method will fail. Also note that if the function fails when recursive is true, it may or may not have removed some files or directories before failing. Also note that if remove is called on "." or "..", it will fail with no effect. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

IBM-SPECIFIC WARNING: This function is not thread-safe. The AIX implementation of the system glob function can temporarily change the working directory of the entire program, causing attempts in other threads to open files with relative path names to fail.

◆ remove() [2/2]

template<class STRING_TYPE >

int bdls::FilesystemUtil::remove	(	const STRING_TYPE &	path,
		bool	recursiveFlag = `false`
	)

inlinestatic

◆ rollFileChain()

static int bdls::FilesystemUtil::rollFileChain	(	const bsl::string_view &	path,
		int	maxSuffix
	)

static

Remove the file at the specified path appended with the specified maxSuffix using a . as a separator. Then move the files with the suffixes .1 to .maxSuffix-1 so they have new suffixes from .2 to .maxSuffix. Finally, move path to path with a .1 suffix. Return 0 on success, and non-zero otherwise.

◆ seek()

static Offset bdls::FilesystemUtil::seek	(	FileDescriptor	descriptor,
		Offset	offset,
		int	whence
	)

static

Set the file pointer associated with the specified descriptor (used by calls to the read and write system calls) according to the specified whence behavior:

 * If 'whence' is e_SEEK_FROM_BEGINNING, set the pointer to
   'offset' bytes from the beginning of the file.
 * If 'whence' is e_SEEK_FROM_CURRENT, advance the pointer by
   'offset' bytes
 * If 'whence' is e_SEEK_FROM_END, set the pointer to 'offset'
   bytes beyond the end of the file.

Return the new location of the file pointer, in bytes from the beginning of the file, on success; and -1 otherwise. The effect on the file pointer is undefined unless the file is on a device capable of seeking. Note that seek does not change the size of the file if the pointer advances beyond the end of the file; instead, the next write at the pointer will increase the file size.

◆ setWorkingDirectory() [1/2]

static int bdls::FilesystemUtil::setWorkingDirectory ( const char * path )

static

Set the working directory of the current process to the specified path. Return 0 on success and a non-zero value otherwise. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

◆ setWorkingDirectory() [2/2]

template<class STRING_TYPE >

int bdls::FilesystemUtil::setWorkingDirectory ( const STRING_TYPE & path )

inlinestatic

◆ sync()

static int bdls::FilesystemUtil::sync	(	char *	address,
		bsl::size_t	numBytes,
		bool	syncFlag
	)

static

Synchronize the contents of the specified numBytes of mapped memory beginning at the specified address with the underlying file on disk. If the specified syncFlag is true, block until all writes to nonvolatile media have actually completed, otherwise, return once they have been scheduled. Return 0 on success, and a non-zero value otherwise. The behavior is undefined unless address is aligned on a page boundary, numBytes is a multiple of pageSize(), and 0 <= numBytes.

◆ truncateFileSize()

static int bdls::FilesystemUtil::truncateFileSize	(	FileDescriptor	descriptor,
		Offset	size
	)

static

Set the size of the file referred to by the specified descriptor to the specified size. descriptor must be open for writing. After the function call, the position is set to the end of the file. Return 0 on success and a non-zero value otherwise. The behavior is undefined if the file is currently mapped, or if size is greater than the existing size of the file.

◆ tryLock()

static int bdls::FilesystemUtil::tryLock	(	FileDescriptor	descriptor,
		bool	lockWriteFlag
	)

static

Acquire a lock for the file with the specified descriptor if it is currently available. If the specified lockWriteFlag is true, acquire an exclusive write lock unless another process has any type of lock on the file. If lockWriteFlag is false, acquire a shared read lock unless a process has a write lock. This method will not block. Return 0 on success, k_ERROR_LOCKING_CONFLICT if the platform reports the lock could not be acquired because another process holds a conflicting lock, and a negative value for any other kind of error. Note that this operation locks the indicated file for the current process, but the behavior is unspecified (and platform-dependent) when either attempting to lock descriptor multiple times, or attempting to lock another descriptor referring to the same file, within a single process.

◆ unlock()

static int bdls::FilesystemUtil::unlock ( FileDescriptor descriptor )

static

Release any lock this process holds on the file with the specified descriptor. Return 0 on success, and a non-zero value otherwise.

◆ unmap()

static int bdls::FilesystemUtil::unmap	(	void *	address,
		bsl::size_t	size
	)

static

Unmap the memory mapping with the specified base address and specified size. Return 0 on success, and a non-zero value otherwise. The behavior is undefined unless this area with address and size was previously mapped with a map call.

◆ visitPaths() [1/2]

static int bdls::FilesystemUtil::visitPaths	(	const char *	pattern,
		const bsl::function< void(const char *path)> &	visitor
	)

static

Call the specified visitor function object for each path in the filesystem matching the specified pattern. Return the number of paths visited on success, and a negative value otherwise. Note that if visitor deletes files or directories during the search, visitor may subsequently be called with paths which have already been deleted, so must be prepared for this event. Also note that there is no guarantee as to the order in which paths will be visited. See findMatchingPaths for a discussion of how pattern is interpreted. Also note that . and .. are never matched by wild cards. The parameterized STRING_TYPE must be one of bsl::string, std::string, std::pmr::string (if supported), or bslstl::StringRef.

IBM-SPECIFIC WARNING: This function is not thread-safe. The AIX implementation of the system glob function can temporarily change the working directory of the entire program, causing attempts in other threads to open files with relative path names to fail.

◆ visitPaths() [2/2]

template<class STRING_TYPE >

int bdls::FilesystemUtil::visitPaths	(	const STRING_TYPE &	pattern,
		const bsl::function< void(const char *path)> &	visitor
	)

inlinestatic

◆ visitTree()

static int bdls::FilesystemUtil::visitTree	(	const bsl::string_view &	root,
		const bsl::string_view &	pattern,
		const bsl::function< void(const char *path)> &	visitor,
		bool	sortFlag = `false`
	)

static

Recursively traverse the directory tree starting at the specified root for files whose leaf names match the specified pattern, and run the specified function visitor, passing it the full path starting with root to each pattern matching file. See findMatchingPaths for a discussion of how pattern is interpreted. If the specified sortFlag is true, traverse the files in the tree in sorted order, sorted by the full path name, otherwise the order in which the files will be visited is unspecified. UTF-8 paths will be sorted by strcmp, which sorts by chars, not unicode code points. Found . and .. directories are ignored, except that root may be . or ... Return 0 on success, and a non-zero value otherwise. This function will fail if root does not specify a directory, of if pattern contains / on Unix or '\' on Windows. Note that both directories and plain files whose names match pattern will be visited, while other files such as symlinks will not be visited or followed. No file or directory that is not matched will be visited. All directories are traversed, regardless of whether they are matched. If a directory is matched and sortFlag is true, it is visited immediately before it is traversed. Also note that root is never visited, even if it matches pattern. Also note that no pattern matching is done on root – if it contains wildcards, they are not interpreted as such and must exactly match the characters in the name of the directory.

IBM-SPECIFIC WARNING: This function is not thread-safe. The AIX implementation of the system glob function can temporarily change the working directory of the entire program, casuing attempts in other threads to open files with relative path names to fail.

◆ write()

static int bdls::FilesystemUtil::write	(	FileDescriptor	descriptor,
		const void *	buffer,
		int	numBytes
	)

static

Write the specified numBytes from the specified buffer address to the file with the specified descriptor. Return numBytes on success; the number of bytes written if space was exhausted; or a negative value on some other error.

Member Data Documentation

◆ k_INVALID_FD

const FileDescriptor bdls::FilesystemUtil::k_INVALID_FD

static

The documentation for this struct was generated from the following file:

bdls_filesystemutil.h

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ ErrorType

◆ FileIOPolicy

◆ FileOpenPolicy

◆ FileTruncatePolicy

◆ Whence

Member Function Documentation

◆ close()

◆ createDirectories() [1/2]

◆ createDirectories() [2/2]

◆ createPrivateDirectory() [1/2]

◆ createPrivateDirectory() [2/2]

◆ createTemporaryDirectory() [1/2]

◆ createTemporaryDirectory() [2/2]

◆ createTemporaryFile() [1/2]

◆ createTemporaryFile() [2/2]

◆ createTemporarySubdirectory() [1/2]

◆ createTemporarySubdirectory() [2/2]

◆ exists() [1/2]

◆ exists() [2/2]

◆ findMatchingPaths() [1/4]

◆ findMatchingPaths() [2/4]

◆ findMatchingPaths() [3/4]

◆ findMatchingPaths() [4/4]

◆ getAvailableSpace() [1/3]

◆ getAvailableSpace() [2/3]

◆ getAvailableSpace() [3/3]

◆ getFileSize() [1/3]

◆ getFileSize() [2/3]

◆ getFileSize() [3/3]

◆ getFileSizeLimit()

◆ getLastModificationTime() [1/3]

◆ getLastModificationTime() [2/3]

◆ getLastModificationTime() [3/3]

◆ getSymbolicLinkTarget() [1/4]

◆ getSymbolicLinkTarget() [2/4]

◆ getSymbolicLinkTarget() [3/4]

◆ getSymbolicLinkTarget() [4/4]

◆ getSystemTemporaryDirectory() [1/2]

◆ getSystemTemporaryDirectory() [2/2]

◆ getWorkingDirectory() [1/2]

◆ getWorkingDirectory() [2/2]

◆ growFile()

◆ isDirectory() [1/2]

◆ isDirectory() [2/2]

◆ isRegularFile() [1/2]

◆ isRegularFile() [2/2]

◆ isSymbolicLink() [1/2]

◆ isSymbolicLink() [2/2]

◆ lock()

◆ makeUnsafeTemporaryFilename() [1/2]

◆ makeUnsafeTemporaryFilename() [2/2]

◆ map()

◆ mapChecked()

◆ move() [1/2]

◆ move() [2/2]

◆ open() [1/2]

◆ open() [2/2]

◆ read()

◆ remove() [1/2]

◆ remove() [2/2]

◆ rollFileChain()

◆ seek()

◆ setWorkingDirectory() [1/2]

◆ setWorkingDirectory() [2/2]

◆ sync()

◆ truncateFileSize()

◆ tryLock()

◆ unlock()

◆ unmap()

◆ visitPaths() [1/2]

◆ visitPaths() [2/2]

◆ visitTree()

◆ write()

Member Data Documentation