[#BloombergLP-bdls-FdStreamBuf_FileHandler]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdls.adoc[bdls]::FdStreamBuf&lowbar;FileHandler
:relfileprefix: ../../
:mrdocs:

This private helper class isolates direct operations on files from the `FdStreamBuf` class&semi; it is a thin wrapper around `FilesystemUtil`&period; One service this class provides is converting between an in&hyphen;process &grave; &grave; and its corresponding on&hyphen;file &grave;&bsol;r &grave; when writing to or reading from a Windows text file&period; On `reset` an object of this type is associated with a supplied file descriptor, after which it can do simple operations on that file descriptor in the service of a `FdStreamBuf`&period;

== Synopsis

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class FdStreamBuf&lowbar;FileHandler;
----

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/2constructor.adoc[`FdStreamBuf&lowbar;FileHandler`]         [.small]#[constructor]#
| Create a file handler that is not associated with any file descriptor&period; Note that `isOpened` will be `false` on the newly created object&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/2destructor.adoc[`&#126;FdStreamBuf&lowbar;FileHandler`] [.small]#[destructor]#
| Destroy this file handler&period; If `willCloseOnReset` is `true`, close any file descriptor associated with this object&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/clear.adoc[`clear`] 
| Release any file descriptor that may be associated with this file handler&period; If `isOpened` and `willCloseOnReset` are both `true`, the file descriptor will be closed, otherwise it will be left unchanged&period; Return 0 on success and a non&hyphen;zero value if the close fails&period; This method succeeds with no effect if `isOpened` was `false`&period; Note that `fileDescriptor` is always `FilesystemUtil&colon;&colon;k&lowbar;INVALID&lowbar;FD` after this call&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/fileDescriptor.adoc[`fileDescriptor`] 
| Return the file descriptor associated with this object, if `isOpened` is `true`, and &hyphen;1 otherwise&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/fileSize.adoc[`fileSize`] 
| Return the size of the file associated with this file handler, or 0 if it is associated with a device other than a regular file (e&period;g&period;, a device or directory)&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/getOffset.adoc[`getOffset`] 
| Return the number of bytes that the data in the range specified by `&lsqb;first, last)&rsqb;` will fill when written to the file descriptor&period; Note that on Unix, or for a binary file on Windows, this value will be `last &hyphen; first`, but for on Windows in text mode, extra bytes are added when &grave;
` would be written to the file descriptor as `r
&grave;&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/isInBinaryMode.adoc[`isInBinaryMode`] 
| Return `false` if on Windows and the file is opened in text mode, and `true` otherwise&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/isOpened.adoc[`isOpened`] 
| Return `true` if this file handler is currently associated with a file descriptor, and `false` otherwise&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/isRegularFile.adoc[`isRegularFile`] 
| Return `true` if the file descriptor associated with this file handler is associated with a regular file and `false` otherwise&period; Note that directories and pipes are not regular files&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/mmap.adoc[`mmap`] 
| Map to memory a section of the file starting at the specified `offset` from the start of the file and return a pointer to that memory&period; The section mapped is to be of the specified `length`&period; The behavior is undefined unless `offset` is a multiple of `pageSize`&period; Note that the memory is mapped for readonly access&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/openMode.adoc[`openMode`] 
| Return the `bsl&colon;&colon;ios&lowbar;base` mode bits corresponding to this file handler&period; Note that this will be a union (bitwise&hyphen;OR) of a subset of the `bsl&colon;&colon;ios&lowbar;base` constants `in`, `out`, and `binary`&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/read.adoc[`read`] 
| Read the specified `numBytes` bytes from the current position of the file descriptor into the specified `buffer`&period; Return the number of characters successfully read&period; The behavior is undefined unless `0 &lt;&equals; numBytes` and `buffer` is at least `numBytes` long&period; Note that on Windows in text mode, &grave;&bsol;r &grave; is read as a single character and stored in the buffer as &grave; &grave;&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/release.adoc[`release`] 
| Disassociate this file handler from any file descriptor with which it may be associated without closing that file descriptor&period; This method succeeds with no effect if `isOpened` was `false`&period; Note that `fileDescriptor` is `FilesystemUtil&colon;&colon;k&lowbar;INVALID&lowbar;FD` after this call&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/reset.adoc[`reset`] 
| Associate this object with the specified `fileDescriptor`, and record the state of the specified `writableFlag` which, if `true`, indicates that the `fileDescriptor` is writable, otherwise it is not&period; Before making this association, if, prior to this call, `willCloseOnReset` is true, close any file descriptor previously associated with this object, otherwise leave it open but disassociate this object from it&period; The optionally specified `willCloseOnResetFlag` will set `willCloseOnReset`, which, if `true`, indicates that `fileDescriptor` is to be closed when this object is cleared, reset, or destroyed, otherwise no action will be taken on `fileDescriptor` at that time&period; Optionally specify a `binaryModeFlag`, which is ignored on Unix&semi; if `false` on Windows, it indicates that &grave;
&grave;s internally are to be translated to and from &grave;&bsol;r
&grave; sequences on the device&semi; on Unix or if `binaryModeFlag` is `true` no such translation is to occur&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; Note that if `FilesystemUtil&colon;&colon;k&lowbar;INVALID&lowbar;FD` is passed as `fileDescriptor`, no file descriptor is to be associated with this object&period; Also note that the state of `fileDescriptor` is unchanged by this call, there is no implicit seek&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/seek.adoc[`seek`] 
| Set the file position associated with this object according to the specified `offset` and `dir` behavior&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/setWillCloseOnReset.adoc[`setWillCloseOnReset`] 
| Set `willCloseOnReset` (the flag determining whether this file handler will close the file descriptor on the next reset, clear, or destruction) to the specified `booleanValue`&period; If `willCloseOnReset` is `true`, the next reset, clear, or destruction will result in the file descriptor being closed, otherwise, it will remain open&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/unmap.adoc[`unmap`] 
| Unmap the section of memory beginning at the specified `mappedMemory`, having the specified `length`&period; The behavior is undefined unless `mappedMemory` is an address returned by a previous call to the `mmap` method and `length` was the `length` specified in that call&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/willCloseOnReset.adoc[`willCloseOnReset`] 
| Return `true` if the associated file descriptor will be closed the next time this file handler is reset, cleared, or destroyed, and `false` otherwise&period; Note that this value is determined by the value of `willCloseOnResetFlag` that was passed to the most recent call to `reset` or `setWillCloseOnReset`&period;
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/write.adoc[`write`] 
| Write the specified `buffer`, containing the specified `numBytes`, to the file descriptor starting at the current position&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; The behavior is undefined unless `0 &lt;&equals; numBytes`&period; Note that on Windows in text mode, a &grave; &grave; is written as &grave;&bsol;r &grave; and counts as one character&period;
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/pageSize.adoc[`pageSize`] 
| Return the operating system&apos;s page size&period;
|===



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