bdls::FdStreamBuf_FileHandler Class Reference

#include <bdls_fdstreambuf.h>

Public Member Functions
	FdStreamBuf_FileHandler ()
	~FdStreamBuf_FileHandler ()
int	reset (FilesystemUtil::FileDescriptor fileDescriptor, bool writableFlag, bool willCloseOnResetFlag=true, bool binaryModeFlag=false)
void	release ()
int	clear ()
int	read (char *buffer, int numBytes)
int	write (const char *buffer, int numBytes)
bsl::streampos	seek (bsl::streamoff offset, FilesystemUtil::Whence dir)
void *	mmap (bsl::streamoff offset, bsl::streamoff length)
void	unmap (void *mappedMemory, bsl::streamoff length)
void	setWillCloseOnReset (bool booleanValue)
FilesystemUtil::FileDescriptor	fileDescriptor () const
bsl::streamoff	fileSize () const
bsl::streamoff	getOffset (char *first, char *last) const
bool	isInBinaryMode () const
bool	isOpened () const
bool	isRegularFile () const
int	openMode () const
bool	willCloseOnReset () const

Static Public Member Functions
static bsl::size_t	pageSize ()
	Return the operating system's page size.

Detailed Description

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 \n and its corresponding on-file \r\n 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.

See bdls_fdstreambuf

Constructor & Destructor Documentation

FdStreamBuf_FileHandler()

bdls::FdStreamBuf_FileHandler::FdStreamBuf_FileHandler

(

)

Create a file handler that is not associated with any file descriptor. Note that isOpened will be false on the newly created object.

~FdStreamBuf_FileHandler()

bdls::FdStreamBuf_FileHandler::~FdStreamBuf_FileHandler

(

)

Destroy this file handler. If willCloseOnReset is true, close any file descriptor associated with this object.

Member Function Documentation

clear()

int bdls::FdStreamBuf_FileHandler::clear ( )

inline

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.

fileDescriptor()

FilesystemUtil::FileDescriptor bdls::FdStreamBuf_FileHandler::fileDescriptor ( ) const

inline

Return the file descriptor associated with this object, if isOpened is true, and -1 otherwise.

fileSize()

bsl::streamoff bdls::FdStreamBuf_FileHandler::fileSize

(

)

const

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).

getOffset()

bsl::streamoff bdls::FdStreamBuf_FileHandler::getOffset ( char *  first, char *  last  ) const

inline

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 \n would be written to the file descriptor as \r\n.

isInBinaryMode()

bool bdls::FdStreamBuf_FileHandler::isInBinaryMode ( ) const

inline

Return false if on Windows and the file is opened in text mode, and true otherwise.

isOpened()

bool bdls::FdStreamBuf_FileHandler::isOpened ( ) const

inline

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

isRegularFile()

bool bdls::FdStreamBuf_FileHandler::isRegularFile ( ) const

inline

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.

mmap()

void * bdls::FdStreamBuf_FileHandler::mmap	(	bsl::streamoff	offset,
		bsl::streamoff	length
	)

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.

openMode()

int bdls::FdStreamBuf_FileHandler::openMode ( ) const

inline

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.

pageSize()

size_t bdls::FdStreamBuf_FileHandler::pageSize ( )

inlinestatic

read()

int bdls::FdStreamBuf_FileHandler::read	(	char *	buffer,
		int	numBytes
	)

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\n is read as a single character and stored in the buffer as \n.

release()

void bdls::FdStreamBuf_FileHandler::release ( )

inline

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.

reset()

int bdls::FdStreamBuf_FileHandler::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 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 \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 fileDescriptor is unchanged by this call, there is no implicit seek.

seek()

bsl::streampos bdls::FdStreamBuf_FileHandler::seek	(	bsl::streamoff	offset,
		FilesystemUtil::Whence	dir
	)

Set the file position associated with this object according to the specified offset and dir behavior.

• If 'dir' is 'FilesystemUtil::e_SEEK_FROM_BEGINNING', set the position to 'offset' bytes from the beginning of the file.
• If 'dir' is 'FilesystemUtil::e_SEEK_FROM_CURRENT', advance the position by 'offset' bytes
• If 'dir' is 'FilesystemUtil::e_SEEK_FROM_END', set the position to 'offset' bytes beyond the end of the file.

Return the new location of the file position, in bytes from the beginning of the file on success; and FilesystemUtil::k_INVALID_FD otherwise. The effect on the file position is undefined unless the file descriptor represents a device capable of seeking. Note that seek does not change the size of the file if the position advances beyond the end of the file; instead, the next write at the pointer will increase the file size. Also note that on Windows in text mode, offset will be the number of bytes on disk passed over, including \rs in \r\n sequences.

setWillCloseOnReset()

void bdls::FdStreamBuf_FileHandler::setWillCloseOnReset ( bool  booleanValue )

inline

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.

unmap()

void bdls::FdStreamBuf_FileHandler::unmap	(	void *	mappedMemory,
		bsl::streamoff	length
	)

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.

willCloseOnReset()

bool bdls::FdStreamBuf_FileHandler::willCloseOnReset ( ) const

inline

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.

write()

int bdls::FdStreamBuf_FileHandler::write	(	const char *	buffer,
		int	numBytes
	)

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 \n is written as \r\n and counts as one character.

---

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

• bdls_fdstreambuf.h