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

This private helper class isolates direct operations on files from the `FdStreamBuf` class; it is a thin wrapper around `FilesystemUtil`. One service this class provides is converting between an in‐process ` ` and its corresponding on‐file `\r ` when writing to or reading from a Windows text file. 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`.

== Synopsis

Declared in `<bdls_fdstreambuf.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class FdStreamBuf_FileHandler;
----

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/2constructor.adoc[`FdStreamBuf_FileHandler`]         [.small]#[constructor]#
| Create a file handler that is not associated with any file descriptor. Note that `isOpened` will be `false` on the newly created object.
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/2destructor.adoc[`~FdStreamBuf_FileHandler`] [.small]#[destructor]#
| Destroy this file handler. If `willCloseOnReset` is `true`, close any file descriptor associated with this object.
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/clear.adoc[`clear`] 
| Release any file descriptor that may be associated with this file handler. If `isOpened` and `willCloseOnReset` are both `true`, the file descriptor will be closed, otherwise it will be left unchanged. Return 0 on success and a non‐zero value if the close fails. This method succeeds with no effect if `isOpened` was `false`. Note that `fileDescriptor` is always `FilesystemUtil::k_INVALID_FD` after this call.
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/fileDescriptor.adoc[`fileDescriptor`] 
| Return the file descriptor associated with this object, if `isOpened` is `true`, and ‐1 otherwise.
| 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.g., a device or directory).
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/getOffset.adoc[`getOffset`] 
| Return the number of bytes that the data in the range specified by `[first, last)]` will fill when written to the file descriptor. Note that on Unix, or for a binary file on Windows, this value will be `last ‐ first`, but for on Windows in text mode, extra bytes are added when `
` would be written to the file descriptor as `r
`.
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/isInBinaryMode.adoc[`isInBinaryMode`] 
| Return `false` if on Windows and the file is opened in text mode, and `true` otherwise.
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/isOpened.adoc[`isOpened`] 
| Return `true` if this file handler is currently associated with a file descriptor, and `false` otherwise.
| 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. Note that directories and pipes are not regular files.
| 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. The section mapped is to be of the specified `length`. The behavior is undefined unless `offset` is a multiple of `pageSize`. Note that the memory is mapped for readonly access.
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/openMode.adoc[`openMode`] 
| Return the `bsl::ios_base` mode bits corresponding to this file handler. Note that this will be a union (bitwise‐OR) of a subset of the `bsl::ios_base` constants `in`, `out`, and `binary`.
| 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`. Return the number of characters successfully read. The behavior is undefined unless `0 <= numBytes` and `buffer` is at least `numBytes` long. Note that on Windows in text mode, `\r ` is read as a single character and stored in the buffer as ` `.
| 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. This method succeeds with no effect if `isOpened` was `false`. Note that `fileDescriptor` is `FilesystemUtil::k_INVALID_FD` after this call.
| 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. 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. 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. Optionally specify a `binaryModeFlag`, which is ignored on Unix; if `false` on Windows, it indicates that `
`s internally are to be translated to and from `\r
` sequences on the device; on Unix or if `binaryModeFlag` is `true` no such translation is to occur. Return 0 on success, and a non‐zero value otherwise. Note that if `FilesystemUtil::k_INVALID_FD` is passed as `fileDescriptor`, no file descriptor is to be associated with this object. Also note that the state of `fileDescriptor` is unchanged by this call, there is no implicit seek.
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/seek.adoc[`seek`] 
| Set the file position associated with this object according to the specified `offset` and `dir` behavior.
| 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`. If `willCloseOnReset` is `true`, the next reset, clear, or destruction will result in the file descriptor being closed, otherwise, it will remain open.
| xref:BloombergLP/bdls/FdStreamBuf_FileHandler/unmap.adoc[`unmap`] 
| Unmap the section of memory beginning at the specified `mappedMemory`, having the specified `length`. 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.
| 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. Note that this value is determined by the value of `willCloseOnResetFlag` that was passed to the most recent call to `reset` or `setWillCloseOnReset`.
| 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. Return 0 on success, and a non‐zero value otherwise. The behavior is undefined unless `0 <= numBytes`. Note that on Windows in text mode, a ` ` is written as `\r ` and counts as one character.
|===


== Static Member Functions

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



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