bdls::FdStreamBuf Class Reference

#include <bdls_fdstreambuf.h>

List of all members.

Public Member Functions
	FdStreamBuf (FilesystemUtil::FileDescriptor fileDescriptor, bool writableFlag, bool willCloseOnResetFlag=true, bool binaryModeFlag=false, bslma::Allocator *basicAllocator=0)
	~FdStreamBuf ()
int	reset (FilesystemUtil::FileDescriptor fileDescriptor, bool writableFlag, bool willCloseOnResetFlag=true, bool binaryModeFlag=false)
void	release ()
int	clear ()
FilesystemUtil::FileDescriptor	fileDescriptor () const
bool	isOpened () const
bool	willCloseOnReset () const
Protected Member Functions
virtual int_type	underflow ()
virtual int_type	pbackfail (int_type c=traits_type::eof())
virtual int_type	overflow (int_type c=traits_type::eof())
virtual FdStreamBuf *	setbuf (char_type *buffer, bsl::streamsize numBytes)
virtual pos_type	seekoff (off_type offset, bsl::ios_base::seekdir whence, bsl::ios_base::openmode mode=bsl::ios_base::in|bsl::ios_base::out)
virtual pos_type	seekpos (pos_type offset, bsl::ios_base::openmode mode=bsl::ios_base::in|bsl::ios_base::out)
virtual int	sync ()
virtual void	imbue (const bsl::locale &locale)
virtual bsl::streamsize	showmanyc ()
virtual bsl::streamsize	xsgetn (char *buffer, bsl::streamsize numBytes)
virtual bsl::streamsize	xsputn (const char *buffer, bsl::streamsize numBytes)

---

Detailed Description

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.

See Component bdls_fdstreambuf

---

Constructor & Destructor Documentation

bdls::FdStreamBuf::FdStreamBuf	(	FilesystemUtil::FileDescriptor	fileDescriptor,
		bool	writableFlag,
		bool	willCloseOnResetFlag = true,
		bool	binaryModeFlag = false,
		bslma::Allocator *	basicAllocator = 0
	)			[explicit]

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 \ns are to be translated to and from \r\n sequences on the device. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. 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).

bdls::FdStreamBuf::~FdStreamBuf

(

)

Destroy this object and, if willCloseOnReset is true, close the file descriptor associated with this object, if any.

---

Member Function Documentation

virtual int_type bdls::FdStreamBuf::underflow

(

)

[protected, 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\n sequences on the device will be translated to \ns.

virtual int_type bdls::FdStreamBuf::pbackfail

(

int_type

c = traits_type::eof()

)

[protected, 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.

virtual int_type bdls::FdStreamBuf::overflow

(

int_type

c = traits_type::eof()

)

[protected, 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 \ns to \r\ns.

virtual FdStreamBuf* bdls::FdStreamBuf::setbuf	(	char_type *	buffer,
		bsl::streamsize	numBytes
	)			[protected, 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.

virtual pos_type bdls::FdStreamBuf::seekoff	(	off_type	offset,
		bsl::ios_base::seekdir	whence,
		bsl::ios_base::openmode	mode = bsl::ios_base::in|bsl::ios_base::out
	)			[protected, virtual]

Set the file pointer associated with the file descriptor according to the specified offset and whence:

 If 'whence' is 'bsl::ios_base::beg', set the pointer to 'offset'
           bytes from the beginning of the file.
 If 'whence' is 'bsl::ios_base::cur', advance the pointer by
           'offset' bytes
 If 'whence' is 'bsl::ios_base::end', set the pointer to 'offset'
           bytes beyond the end of the file.

Optionally specify mode, which is ignored. Return the new location of the file position, in bytes from the beginning of the file, on success, and -1 otherwise. The behavior is undefined unless the file descriptor is on a device capable of seeking. Note that seeking does not change the size of the file if the pointer advances beyond the end of the file; instead, the next write at the pointer will increase the file size. Also note that seeks are always in terms of bytes on the device, meaning that in Windows text mode, seeking past a \n perceived by the caller will count as 2 bytes since it has to seek over a \r\n sequence on the device.

virtual pos_type bdls::FdStreamBuf::seekpos	(	pos_type	offset,
		bsl::ios_base::openmode	mode = bsl::ios_base::in|bsl::ios_base::out
	)			[protected, 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\n sequence on the disk will count as two bytes, though if it is read in it will be a single \n byte.

virtual int bdls::FdStreamBuf::sync

(

)

[protected, virtual]

If in output mode, flush the buffer to the associated file descriptor; otherwise do nothing. Return 0 on success, -1 otherwise.

virtual void bdls::FdStreamBuf::imbue

(

const bsl::locale &

locale

)

[protected, 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().

virtual bsl::streamsize bdls::FdStreamBuf::showmanyc

(

)

[protected, 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.

virtual bsl::streamsize bdls::FdStreamBuf::xsgetn	(	char *	buffer,
		bsl::streamsize	numBytes
	)			[protected, 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\n in the file will be read as \n (counting as a single character).

virtual bsl::streamsize bdls::FdStreamBuf::xsputn	(	const char *	buffer,
		bsl::streamsize	numBytes
	)			[protected, 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 \n will be written to the file as \r\n (counted as a single character).

int bdls::FdStreamBuf::reset	(	FilesystemUtil::FileDescriptor	fileDescriptor,
		bool	writableFlag,
		bool	willCloseOnResetFlag = true,
		bool	binaryModeFlag = false
	)

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. 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 which will set willCloseOnReset, which, if true, indicates that the specified file descriptor 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 \ns internally are to be translated to and from \r\n 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.

void bdls::FdStreamBuf::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.

int bdls::FdStreamBuf::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.

FilesystemUtil::FileDescriptor bdls::FdStreamBuf::fileDescriptor

(

)

const

Return the file descriptor associated with this object, or FilesystemUtil::k_INVALID_FD if this object is not currently associated with a file descriptor.

bool bdls::FdStreamBuf::isOpened

(

)

const

Return true if this object is currently associated with a file descriptor, and false otherwise.

bool bdls::FdStreamBuf::willCloseOnReset

(

)

const

Return true if this object will close the associated file descriptor the next time it is reset, cleared, or destroyed, and false otherwise.

---

The documentation for this class was generated from the following file:

• bdls_fdstreambuf.h