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.
Declared in <bdls_fdstreambuf.h>
class FdStreamBuf
: public std::streambuf| Name | Description |
|---|---|
std::streambuf |
| Name | Description |
|---|---|
FdStreamBuf [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). |
~FdStreamBuf [destructor] [virtual] | Destroy this object and, if willCloseOnReset is true, close the file descriptor associated with this object, if any. |
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. |
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. |
isOpened | Return true if this object is currently associated with a file descriptor, and false otherwise. |
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. |
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. |
willCloseOnReset | Return true if this object will close the associated file descriptor the next time it is reset, cleared, or destroyed, and false otherwise. |
| Name | Description |
|---|---|
imbue [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(). |
overflow [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. |
pbackfail [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. |
seekoff [virtual] | Set the file pointer associated with the file descriptor according to the specified offset and whence: |
seekpos [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. |
setbuf [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. |
showmanyc [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. |
sync [virtual] | If in output mode, flush the buffer to the associated file descriptor; otherwise do nothing. Return 0 on success, -1 otherwise. |
underflow [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. |
xsgetn [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). |
xsputn [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). |