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

This class, derived from the C++ standard library class `bsl::streambuf`, is a mechanism that can be associated with an opened file descriptor, and, except for changing the locale, enables the caller to invoke all the standard `bsl::streambuf` operations on that file descriptor. Note that objects of this class are always in exactly one of the 5 modes outlined in the enum `FdStreamBuf::FdStreamBufMode`.

== Synopsis

Declared in `<bdls_fdstreambuf.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class FdStreamBuf
    : public std::streambuf
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `std::streambuf`
| 
|===

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FdStreamBuf/2constructor.adoc[`FdStreamBuf`]         [.small]#[constructor]#
| Create a `FdStreamBuf` associated with the specified `fileDescriptor` that refers to an already opened file or device, and specify `writableFlag` which, if `true`, indicates that `fileDescriptor` is writable, otherwise it is not. The optionally specified `willCloseOnResetFlag`, if `true`, indicates that `fileDescriptor` is to be closed the next time this object is reset, cleared or destroyed, or if `false` the file descriptor is to be left open. Optionally specify a `binaryModeFlag` which is ignored on Unix; if `false` on Windows, it indicates that `
`s are to be translated to and from `\r
` sequences on the device. Optionally specify a `basicAllocator` used to supply memory. If `basicAllocator` is 0, the currently installed default allocator is used. The supplied file descriptor, if valid, should remain open until the next call to either `reset` or the destructor. Note that if `FilesystemUtil::k_INVALID_FD` is passed to `fileDescriptor`, no file descriptor is to be associated with this object. Also note that the state of the `fileDescriptor` is unchanged by this call (i.e., there is no implicit seek).
| xref:BloombergLP/bdls/FdStreamBuf/2destructor.adoc[`~FdStreamBuf`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this object and, if `willCloseOnReset` is `true`, close the file descriptor associated with this object, if any.
| xref:BloombergLP/bdls/FdStreamBuf/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 not. 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 `FilesystemUtil::k_INVALID_FD` after this call.
| xref:BloombergLP/bdls/FdStreamBuf/fileDescriptor.adoc[`fileDescriptor`] 
| Return the file descriptor associated with this object, or `FilesystemUtil::k_INVALID_FD` if this object is not currently associated with a file descriptor.
| xref:BloombergLP/bdls/FdStreamBuf/isOpened.adoc[`isOpened`] 
| Return `true` if this object is currently associated with a file descriptor, and `false` otherwise.
| xref:BloombergLP/bdls/FdStreamBuf/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 is `isOpened` was false. Note that `fileDescriptor` is `FilesystemUtil::k_INVALID_FD` after this call.
| xref:BloombergLP/bdls/FdStreamBuf/reset.adoc[`reset`] 
| Associate this object with the specified `fileDescriptor`, and record the state of the specified `writableFlag` which, if `true`, indicates that `fileDescriptor` is writable, otherwise it is not. If, in the call to the constructor or `reset` prior to this call, `willCloseOnReset` was true, close any file descriptor previously associated with this object, otherwise leave it open but disassociate this object from it. The Optionally specified `willCloseOnResetFlag` which will set `willCloseOnReset`, which, if `true`, indicates that the specified file descriptor is to be closed when this object is later cleared, reset, or destroyed, otherwise no action will be taken on `fileDescriptor` at that time. The supplied file descriptor, if valid, should remain open until the next call to either `reset` or the destructor, regardless of the value of `willCloseOnResetFlag`. 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 the `fileDescriptor` is unchanged by this call, there is no implicit seek.
| xref:BloombergLP/bdls/FdStreamBuf/willCloseOnReset.adoc[`willCloseOnReset`] 
| Return `true` if this object will close the associated file descriptor the next time it is reset, cleared, or destroyed, and `false` otherwise.
|===


== Protected Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdls/FdStreamBuf/imbue.adoc[`imbue`]  [.small]#[virtual]#
| Set the locale for this object. This method has no effect. The behavior is undefined unless the specified `locale` is the same as `bsl::locale()`.
| xref:BloombergLP/bdls/FdStreamBuf/overflow.adoc[`overflow`]  [.small]#[virtual]#
| If in output mode, write the contents of the buffer to output. Return `traits_type::eof()` on failure, and any other value on success. Optionally specify a character `c` to be appended to the buffer prior to the flush. If no character is specified, no character is appended to the buffer. If not in output mode, switch to output mode. Note that the write will translate ` `s to `r
`s.
| xref:BloombergLP/bdls/FdStreamBuf/pbackfail.adoc[`pbackfail`]  [.small]#[virtual]#
| If the optionally specified `c` is not given, move the current input position back one character and return the character at that position. Otherwise specify a value for `c` other than `traits_type::eof`. If `c` is equal to the previous character in the read buffer, the behavior is the same as if `eof()` was passed. If `c` is not eof and is not equal to the previous character in the putback buffer push the character `c` is back into the input buffer, if possible. Return the backed up character on success and `traits_type::eof()` otherwise. If the input buffer is readonly, or `gptr()` is already at the beginning of the input buffer, this object enters `INPUT_PUTBACK_MODE` and `c` is stuffed back into the putback buffer. Note that only `PBACK_BUF_SIZE` characters can be backed up into the putback buffer, if this limit is exceeded, `traits_type::eof()` will be returned. Also note that this method is called by public methods `sputbackc` or `sungetc` in the base class, and only when simply decrementing the current position in the input buffer won't satisfy the request, either because `c` doesn't match the previously input character, or because the input position is already at the beginning of the input buffer.
| xref:BloombergLP/bdls/FdStreamBuf/seekoff.adoc[`seekoff`]  [.small]#[virtual]#
| Set the file pointer associated with the file descriptor according to the specified `offset` and `whence`:
| xref:BloombergLP/bdls/FdStreamBuf/seekpos.adoc[`seekpos`]  [.small]#[virtual]#
| Seek to the specified `offset` relative to the beginning of the file. Return the resulting absolute position in the file relative to the beginning. Optionally specify `mode` which is ignored. Also note that seeks are always in terms of bytes on the device, meaning that on a Windows text file, seeking past a `\r ` sequence on the disk will count as two bytes, though if it is read in it will be a single ` ` byte.
| xref:BloombergLP/bdls/FdStreamBuf/setbuf.adoc[`setbuf`]  [.small]#[virtual]#
| Use the specified `buffer` of the specified `numBytes` capacity as the input/output buffer for this `streambuf`. If `buffer == 0`, the buffer is dynamically allocated with a default size. If both `buffer` and `numBytes` are zero a 1‐byte buffer is dynamically allocated. The behavior is undefined if any I/O has preceded this call, and unless the buffer is uninitialized before this call.
| xref:BloombergLP/bdls/FdStreamBuf/showmanyc.adoc[`showmanyc`]  [.small]#[virtual]#
| If this object is in putback mode, return the number of characters remaining to be read in the putback buffer, and otherwise the number of characters remaining in the file to be read. Return a non‐negative number of characters on success and a negative value otherwise. The behavior is undefined unless this object is in input mode and the file descriptor is associated with a regular file.
| xref:BloombergLP/bdls/FdStreamBuf/sync.adoc[`sync`]  [.small]#[virtual]#
| If in output mode, flush the buffer to the associated file descriptor; otherwise do nothing. Return 0 on success, ‐1 otherwise.
| xref:BloombergLP/bdls/FdStreamBuf/underflow.adoc[`underflow`]  [.small]#[virtual]#
| Replenish the input buffer with data obtained from the file descriptor, and return the next character of input (or eof if no input is available). Note that in windows text mode, `\r ` sequences on the device will be translated to ` `s.
| xref:BloombergLP/bdls/FdStreamBuf/xsgetn.adoc[`xsgetn`]  [.small]#[virtual]#
| Read up to the specified `numBytes` characters from the file descriptor into the specified `buffer` and return the number of characters successfully read. The behavior is undefined unless `buffer` is at least `numBytes` bytes long. Note that on a Windows text file, a `\r ` in the file will be read as `
` (counting as a single character).
| xref:BloombergLP/bdls/FdStreamBuf/xsputn.adoc[`xsputn`]  [.small]#[virtual]#
| Write up to the specified `numBytes` characters from the specified `buffer` and return the number of characters successfully written. Note that this method does not necessarily modify the file: this method may simply write the characters to a buffer to be flushed to the file at a later time. Also note that on a Windows text file, a ` ` will be written to the file as `\r ` (counted as a single character).
|===



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