[#BloombergLP-bdls-FilesystemUtil]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdls.adoc[bdls]::FilesystemUtil
:relfileprefix: ../../
:mrdocs:

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

== Synopsis

Declared in `<bdls_filesystemutil.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
struct FilesystemUtil;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FilesystemUtil/FileDescriptor.adoc[`FileDescriptor`] 
| `FileDescriptor` is an alias for the operating system's native file descriptor / file handle type.
| xref:BloombergLP/bdls/FilesystemUtil/Offset.adoc[`Offset`] 
| `Offset` is an alias for a signed value, representing the offset of a location within a file.
|===


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FilesystemUtil/_04enum.adoc[`Unnamed enum`] 
| Default growth increment for file operations.
| xref:BloombergLP/bdls/FilesystemUtil/ErrorType.adoc[`ErrorType`] 
| Enumeration of error codes returned by certain filesystem operations.
| xref:BloombergLP/bdls/FilesystemUtil/FileIOPolicy.adoc[`FileIOPolicy`] 
| Enumeration used to distinguish between different sets of actions permitted on an open file descriptor.
| xref:BloombergLP/bdls/FilesystemUtil/FileOpenPolicy.adoc[`FileOpenPolicy`] 
| Enumeration used to determine whether 'open' should open an existing file, or create a new file.
| xref:BloombergLP/bdls/FilesystemUtil/FileTruncatePolicy.adoc[`FileTruncatePolicy`] 
| Enumeration used to distinguish between different ways to handle the contents, if any, of an existing file immediately upon opening the file.
| xref:BloombergLP/bdls/FilesystemUtil/Whence.adoc[`Whence`] 
| Enumeration used to distinguish among different starting points for a seek operation.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FilesystemUtil/close.adoc[`close`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/createDirectories-04.adoc[`createDirectories`] 
| `createDirectories` overloads
| xref:BloombergLP/bdls/FilesystemUtil/createPrivateDirectory-0e.adoc[`createPrivateDirectory`] 
| `createPrivateDirectory` overloads
| xref:BloombergLP/bdls/FilesystemUtil/createTemporaryDirectory-04.adoc[`createTemporaryDirectory`] 
| `createTemporaryDirectory` overloads
| xref:BloombergLP/bdls/FilesystemUtil/createTemporaryFile-08.adoc[`createTemporaryFile`] 
| `createTemporaryFile` overloads
| xref:BloombergLP/bdls/FilesystemUtil/createTemporarySubdirectory-00.adoc[`createTemporarySubdirectory`] 
| `createTemporarySubdirectory` overloads
| xref:BloombergLP/bdls/FilesystemUtil/exists-056.adoc[`exists`] 
| `exists` overloads
| xref:BloombergLP/bdls/FilesystemUtil/findMatchingPaths-065e.adoc[`findMatchingPaths`] 
| `findMatchingPaths` overloads
| xref:BloombergLP/bdls/FilesystemUtil/getAvailableSpace-01.adoc[`getAvailableSpace`] 
| `getAvailableSpace` overloads
| xref:BloombergLP/bdls/FilesystemUtil/getFileSize-0d.adoc[`getFileSize`] 
| `getFileSize` overloads
| xref:BloombergLP/bdls/FilesystemUtil/getFileSizeLimit.adoc[`getFileSizeLimit`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/getLastModificationTime-09.adoc[`getLastModificationTime`] 
| `getLastModificationTime` overloads
| xref:BloombergLP/bdls/FilesystemUtil/getSymbolicLinkTarget-0fb.adoc[`getSymbolicLinkTarget`] 
| `getSymbolicLinkTarget` overloads
| xref:BloombergLP/bdls/FilesystemUtil/getSystemTemporaryDirectory-077.adoc[`getSystemTemporaryDirectory`] 
| `getSystemTemporaryDirectory` overloads
| xref:BloombergLP/bdls/FilesystemUtil/getWorkingDirectory-01.adoc[`getWorkingDirectory`] 
| `getWorkingDirectory` overloads
| xref:BloombergLP/bdls/FilesystemUtil/growFile.adoc[`growFile`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/isDirectory-02.adoc[`isDirectory`] 
| `isDirectory` overloads
| xref:BloombergLP/bdls/FilesystemUtil/isRegularFile-0a.adoc[`isRegularFile`] 
| `isRegularFile` overloads
| xref:BloombergLP/bdls/FilesystemUtil/isSymbolicLink-09.adoc[`isSymbolicLink`] 
| `isSymbolicLink` overloads
| xref:BloombergLP/bdls/FilesystemUtil/lock.adoc[`lock`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/makeUnsafeTemporaryFilename-09.adoc[`makeUnsafeTemporaryFilename`] 
| `makeUnsafeTemporaryFilename` overloads
| xref:BloombergLP/bdls/FilesystemUtil/map.adoc[`map`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/mapChecked.adoc[`mapChecked`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/move-0d.adoc[`move`] 
| `move` overloads
| xref:BloombergLP/bdls/FilesystemUtil/open-0f.adoc[`open`] 
| `open` overloads
| xref:BloombergLP/bdls/FilesystemUtil/read.adoc[`read`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/remove-0e.adoc[`remove`] 
| `remove` overloads
| xref:BloombergLP/bdls/FilesystemUtil/rollFileChain.adoc[`rollFileChain`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/seek.adoc[`seek`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/setWorkingDirectory-00.adoc[`setWorkingDirectory`] 
| `setWorkingDirectory` overloads
| xref:BloombergLP/bdls/FilesystemUtil/sync.adoc[`sync`] 
| 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`.
| xref:BloombergLP/bdls/FilesystemUtil/truncateFileSize.adoc[`truncateFileSize`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/tryLock.adoc[`tryLock`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/unlock.adoc[`unlock`] 
| Release any lock this process holds on the file with the specified `descriptor`. Return 0 on success, and a non‐zero value otherwise.
| xref:BloombergLP/bdls/FilesystemUtil/unmap.adoc[`unmap`] 
| 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.
| xref:BloombergLP/bdls/FilesystemUtil/visitPaths-0f.adoc[`visitPaths`] 
| `visitPaths` overloads
| xref:BloombergLP/bdls/FilesystemUtil/visitTree.adoc[`visitTree`] 
| 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 `char`s, 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.
| xref:BloombergLP/bdls/FilesystemUtil/write.adoc[`write`] 
| 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.
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FilesystemUtil/k_INVALID_FD.adoc[`k_INVALID_FD`] 
| `FileDescriptor` value representing no file, used as the error return for `open`.
| xref:BloombergLP/bdls/FilesystemUtil/k_OFFSET_MAX.adoc[`k_OFFSET_MAX`] 
| maximum representable file offset value
| xref:BloombergLP/bdls/FilesystemUtil/k_OFFSET_MIN.adoc[`k_OFFSET_MIN`] 
| minimum representable file offset value
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#