[#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&hyphen;independent filesystem access&period;

== Synopsis

Declared in `&lt;bdls&lowbar;filesystemutil&period;h&gt;`

[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&apos;s native file descriptor &sol; file handle type&period;
| xref:BloombergLP/bdls/FilesystemUtil/Offset.adoc[`Offset`] 
| `Offset` is an alias for a signed value, representing the offset of a location within a file&period;
|===


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FilesystemUtil/_04enum.adoc[`Unnamed enum`] 
| Default growth increment for file operations&period;
| xref:BloombergLP/bdls/FilesystemUtil/ErrorType.adoc[`ErrorType`] 
| Enumeration of error codes returned by certain filesystem operations&period;
| xref:BloombergLP/bdls/FilesystemUtil/FileIOPolicy.adoc[`FileIOPolicy`] 
| Enumeration used to distinguish between different sets of actions permitted on an open file descriptor&period;
| xref:BloombergLP/bdls/FilesystemUtil/FileOpenPolicy.adoc[`FileOpenPolicy`] 
| Enumeration used to determine whether &apos;open&apos; should open an existing file, or create a new file&period;
| 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&period;
| xref:BloombergLP/bdls/FilesystemUtil/Whence.adoc[`Whence`] 
| Enumeration used to distinguish among different starting points for a seek operation&period;
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FilesystemUtil/close.adoc[`close`] 
| Close the specified `descriptor`&period; Return 0 on success and a non&hyphen;zero value otherwise&period; A return value of `k&lowbar;BAD&lowbar;FILE&lowbar;DESCRIPTOR` indicates that the supplied `descriptor` is invalid&period;
| 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&lowbar;OFFSET&lowbar;MAX` if no limit is set, or a negative value if an error occurs&period; Note that if you are doing any calculations involving the returned value, it is recommended to check for `k&lowbar;OFFSET&lowbar;MAX` specifically to avoid integer overflow in your calculations&period;
| 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&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; If the optionally specified `reserveFlag` is true, make sure the space on disk is preallocated and not allocated on demand, preventing a possible out&hyphen;of&hyphen;disk&hyphen;space error when accessing the data on file systems with sparse file support&period; 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&period; Note that if the size of the file is greater than or equal to `size`, this function has no effect&period; Also note that the contents of the newly grown portion of the file is undefined&period;
| 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`&period; If `lockWriteFlag` is true, acquire an exclusive write lock&semi; otherwise acquire a (possibly) shared read lock&period; The calling thread will block until the lock is acquired&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; Note that this operation locks the indicated file for use by the current _process_, but the behavior is unspecified (and platform&hyphen;dependent) when either attempting to lock `descriptor` multiple times, or attempting to lock another descriptor referring to the same file, within a single process&period;
| 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&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; The access permissions for mapping memory are defined by the specified `mode`, which may be a combination of `MemoryUtil&colon;&colon;k&lowbar;ACCESS&lowbar;READ`, `MemoryUtil&colon;&colon;k&lowbar;ACCESS&lowbar;WRITE` and `MemoryUtil&colon;&colon;k&lowbar;ACCESS&lowbar;EXECUTE`&period; Note that on failure, the value of `address` is undefined&period; Also note that mapping will succeed even if there are fewer than `offset &plus; 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&period;e&period;, this function does not grow the file to guarantee it can accommodate the mapped region)&period; Also note that mapping past the end of file may return 0, but any access of the resulting mapped memory may segfault&period;
| 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&period; Return 0 on success, `k&lowbar;ERROR&lowbar;PAST&lowbar;EOF` if an attempt is made to map past the end of file, and a non&hyphen;zero value otherwise&period; The access permissions for mapping memory are defined by the specified `mode`, which may be a combination of `MemoryUtil&colon;&colon;k&lowbar;ACCESS&lowbar;READ`, `MemoryUtil&colon;&colon;k&lowbar;ACCESS&lowbar;WRITE` and `MemoryUtil&colon;&colon;k&lowbar;ACCESS&lowbar;EXECUTE`, though on some platforms they must be a subset of the file permissions&period; The behavior is undefined unless bits in `mode` other than `MemoryUtil&colon;&colon;k&lowbar;ACCESS&lowbar;READ&lowbar;WRITE&lowbar;EXECUTE` are all clear, unless `0 &lt;&equals; offset`, and unless `0 &lt; size`, and unless the `offset` is a multiple of `MemoryUtil&colon;&colon;pageSize()`&period; Note that on failure, the value of `address` is undefined&period; Also note that the check against mapping past the end of file and all assertions are done before the call to map the file&period;
| 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`&period; Return `numBytes` on success&semi; the number of bytes read if there were not enough available&semi; or a negative number on some other error&period;
| 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 `&period;` as a separator&period; Then move the files with the suffixes `&period;1` to `&period;maxSuffix&hyphen;1` so they have new suffixes from `&period;2` to `&period;maxSuffix`&period; Finally, move `path` to `path` with a `&period;1` suffix&period; Return 0 on success, and non&hyphen;zero otherwise&period;
| 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&colon; &grave; &ast; If &apos;whence&apos; is e&lowbar;SEEK&lowbar;FROM&lowbar;BEGINNING, set the pointer to &apos;offset&apos; bytes from the beginning of the file&period; &ast; If &apos;whence&apos; is e&lowbar;SEEK&lowbar;FROM&lowbar;CURRENT, advance the pointer by &apos;offset&apos; bytes &ast; If &apos;whence&apos; is e&lowbar;SEEK&lowbar;FROM&lowbar;END, set the pointer to &apos;offset&apos; bytes beyond the end of the file&period; &grave; Return the new location of the file pointer, in bytes from the beginning of the file, on success&semi; and &hyphen;1 otherwise&period; The effect on the file pointer is undefined unless the file is on a device capable of seeking&period; Note that `seek` does not change the size of the file if the pointer advances beyond the end of the file&semi; instead, the next write at the pointer will increase the file size&period;
| 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&period; If the specified `syncFlag` is true, block until all writes to nonvolatile media have actually completed, otherwise, return once they have been scheduled&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; The behavior is undefined unless `address` is aligned on a page boundary, `numBytes` is a multiple of `pageSize()`, and `0 &lt;&equals; numBytes`&period;
| xref:BloombergLP/bdls/FilesystemUtil/truncateFileSize.adoc[`truncateFileSize`] 
| Set the size of the file referred to by the specified `descriptor` to the specified `size`&period; `descriptor` must be open for writing&period; After the function call, the position is set to the end of the file&period; Return 0 on success and a non&hyphen;zero value otherwise&period; The behavior is undefined if the file is currently mapped, or if `size` is greater than the existing size of the file&period;
| xref:BloombergLP/bdls/FilesystemUtil/tryLock.adoc[`tryLock`] 
| Acquire a lock for the file with the specified `descriptor` if it is currently available&period; If the specified `lockWriteFlag` is true, acquire an exclusive write lock unless another process has any type of lock on the file&period; If `lockWriteFlag` is false, acquire a shared read lock unless a process has a write lock&period; This method will not block&period; Return 0 on success, `k&lowbar;ERROR&lowbar;LOCKING&lowbar;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&period; Note that this operation locks the indicated file for the current _process_, but the behavior is unspecified (and platform&hyphen;dependent) when either attempting to lock `descriptor` multiple times, or attempting to lock another descriptor referring to the same file, within a single process&period;
| xref:BloombergLP/bdls/FilesystemUtil/unlock.adoc[`unlock`] 
| Release any lock this process holds on the file with the specified `descriptor`&period; Return 0 on success, and a non&hyphen;zero value otherwise&period;
| xref:BloombergLP/bdls/FilesystemUtil/unmap.adoc[`unmap`] 
| Unmap the memory mapping with the specified base `address` and specified `size`&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; The behavior is undefined unless this area with `address` and `size` was previously mapped with a `map` call&period;
| 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&period; See `findMatchingPaths` for a discussion of how `pattern` is interpreted&period; 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&period; UTF&hyphen;8 paths will be sorted by `strcmp`, which sorts by `char`s, not unicode code points&period; Found `&period;` and `&period;&period;` directories are ignored, except that `root` may be `&period;` or `&period;&period;`&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; This function will fail if `root` does not specify a directory, of if `pattern` contains `&sol;` on Unix or &apos;&apos; on Windows&period; 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&period; No file or directory that is not matched will be visited&period; All directories are traversed, regardless of whether they are matched&period; If a directory is matched and `sortFlag` is `true`, it is visited immediately before it is traversed&period; Also note that `root` is never visited, even if it matches `pattern`&period; Also note that no pattern matching is done on `root` &hyphen;&hyphen; if it contains wildcards, they are not interpreted as such and must exactly match the characters in the name of the directory&period;
| xref:BloombergLP/bdls/FilesystemUtil/write.adoc[`write`] 
| Write the specified `numBytes` from the specified `buffer` address to the file with the specified `descriptor`&period; Return `numBytes` on success&semi; the number of bytes written if space was exhausted&semi; or a negative value on some other error&period;
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FilesystemUtil/k_INVALID_FD.adoc[`k&lowbar;INVALID&lowbar;FD`] 
| `FileDescriptor` value representing no file, used as the error return for `open`&period;
| xref:BloombergLP/bdls/FilesystemUtil/k_OFFSET_MAX.adoc[`k&lowbar;OFFSET&lowbar;MAX`] 
| maximum representable file offset value
| xref:BloombergLP/bdls/FilesystemUtil/k_OFFSET_MIN.adoc[`k&lowbar;OFFSET&lowbar;MIN`] 
| minimum representable file offset value
|===



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