Main Page Modules Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages

os::File Class Reference

#include <file.h>

Inheritance diagram for os::File::

List of all members.

Public Types
enum	{ DEFAULT_BUFFER_SIZE = 32768 }
Public Methods
	File ()
	Default constructor. More...
	File (const std::string &cPath, int nOpenMode=O_RDONLY)
	Construct a file from a regular path. More...
	File (const Directory &cDir, const std::string &cName, int nOpenMode=O_RDONLY)
	Open a file addressed as a name inside a specified directory. More...
	File (const FileReference &cRef, int nOpenMode=O_RDONLY)
	Open a file referred to by a os::FileReference. More...
	File (const FSNode &cNode)
	Construct a file from a FSNode. More...
	File (const File &cFile)
	Copy constructos. More...
virtual	~File ()
virtual status_t	FDChanged (int nNewFD, const struct::stat &sStat)
virtual off_t	GetSize (bool bUpdateCache=true) const
virtual ssize_t	Read (void *pBuffer, ssize_t nSize)
virtual ssize_t	Write (const void *pBuffer, ssize_t nSize)
virtual ssize_t	ReadPos (off_t nPos, void *pBuffer, ssize_t nSize)
virtual ssize_t	WritePos (off_t nPos, const void *pBuffer, ssize_t nSize)
virtual off_t	Seek (off_t nPos, int nMode)
	Move the file pointer. More...
status_t	SetBufferSize (int nSize)
	Set the size of the files caching buffer. More...
int	GetBufferSize () const
	Obtain the files buffer size. More...
status_t	Flush ()
	Write unwritten data to the underlying file. More...

Detailed Description

Description:

See also:

Author:: Kurt Skauen ([email protected])

Member Enumeration Documentation

anonymous enum

Enumeration values:

DEFAULT_BUFFER_SIZE

Constructor & Destructor Documentation

File::File ( )

Description:
Initialize the instance to a known but invalid state. The instance must be successfully initialized with one of the SetTo() members before it can be used.
Author:
Kurt Skauen ([email protected])

File::File ( const std::string & cPath,

int nOpenMode = O_RDONLY

)

Description:
Open the file pointed to by cPath. The node must be a regular file or a symlink pointing at a regular file. Anything else will cause and errno_exception(EINVAL) exception to be thrown.
Parameters:

cPath The file to open. The path can eigther be absolute (starting with "/") or relative to the current working directory.

nOpenMode Flags controling how the file should be opened. The value should be one of the O_RDONLY, O_WRONLY, or O_RDWR. In addition the following flags can be bitwise or'd in to further control the operation:

O_TRUNC trunate the size to 0.
O_APPEND automatically move the file-pointer to the end of the file before each write (only valid for files)
O_NONBLOCK open the file in non-blocking mode. This is only relevant for named pipes and PTY's.
O_NOCTTY Don't make the file controlling TTY even if cPath points to a PTY.

Author:
Kurt Skauen ([email protected])

File::File ( const Directory & cDir,

const std::string & cPath,

int nOpenMode = O_RDONLY

)

Description:
Look at File( const std::string& cPath, int nOpenMode ) for a more detailed description.
Parameters:

cDir The directory to use as a base for cPath

cPath Path relative to cPath.

nOpenMode Flags controlling how to open the file. See File( const std::string& cPath, int nOpenMode ) for a full description.

See also:
File( const std::string& cPath, int nOpenMode )
Author:
Kurt Skauen ([email protected])

File::File ( const FileReference & cRef,

int nOpenMode = O_RDONLY

)

Description:
Look at File( const std::string& cPath, int nOpenMode ) for a more detailed description.
Parameters:

cRef Reference to the file to open.

nOpenMode Flags controlling how to open the file. See File( const std::string& cPath, int nOpenMode ) for a full description.

See also:
File( const std::string& cPath, int nOpenMode )
Author:
Kurt Skauen ([email protected])

File::File ( const FSNode & cNode )

Description:
This constructor can be used to "downcast" an os::FSNode to a os::File. The FSNode must represent a regular file, pipe, or PTY. Attempts to convert symlinks and directories will cause an errno_exception(EINVAL) exception to be thrown.
Parameters:

cNode The FSNode to downcast.

Author:
Kurt Skauen ([email protected])

File::File ( const File & cFile )

Description:
This constructor will make an independent copy of cFile. The copy and original will have their own file pointers and they will have their own attribute directory iterators (see note).
Note:
The attribute directory iterator will not be cloned so when FSNode::GetNextAttrName() is called for the first time it will return the first attribute name even if the iterator was not located at the beginning of the originals attribute directory.
Parameters:

cFile The file object to copy.

Author:
Kurt Skauen ([email protected])

File::~File ( ) [virtual]

Member Function Documentation

status_t File::FDChanged ( int nNewFD,

const struct::stat & sStat

) [virtual]

Reimplemented from os::FSNode.

status_t File::Flush ( void )

Note:
Flush() will be called automatically by the destructor if there is unwritten data in the buffer.
Returns:
On success 0 will be returned. On failure -1 will be returned and a error code will be stored in the global variable "errno".

Author:
Kurt Skauen ([email protected])

int File::GetBufferSize ( ) const

Returns:
The files buffer size in bytes. A value of 0 means the file is unbuffered.
See also:
SetBufferSize()
Author:
Kurt Skauen ([email protected])

off_t File::GetSize ( bool bUpdateCache = true ) const [virtual]

Reimplemented from os::FSNode.

ssize_t File::Read ( void * pBuffer,

ssize_t nSize

) [virtual]

Reimplemented from os::StreamableIO.

ssize_t File::ReadPos ( off_t nPos,

void * pBuffer,

ssize_t nSize

) [virtual]

Reimplemented from os::SeekableIO.

off_t File::Seek ( off_t nPos,

int nMode

) [virtual]

Description:

Note:

Warning:

Parameters:

return

Error codes:

See also:

Author:
Kurt Skauen ([email protected])

Reimplemented from os::SeekableIO.

status_t File::SetBufferSize ( int nBufferSize )

Description:
By default the os::File class use a 32KB internal memory buffer to cache resently read/written data. Normally you the buffer can greatly increase the performance since it reduce the number of kernel-calls when doing multiple small reads or writes on the file. There is cases however where it is beneficial to increase the buffer size or even to disabling buffering entirely.

If you read/write large chunks of data at the time the buffer might impose more overhead than gain and it could be a good idea to disable the buffering entirely by setting the buffer size to 0. When for example streaming video the amount of data read are probably going to be much larger than the buffer anyway and each byte is only read once by the application and if the application read the file in reasonably sized chunks the extra copy imposed by reading the data into the internal buffer and then copy it to the callers buffer will only decrease the performance.
Parameters:

nBufferSize The buffer size in bytes. If the size is set to 0 the file will be unbuffered and each call to Read()/Write() and ReadPos()/WritePos() will translate directly to kernel calls.

Returns:
On success 0 is returned. If there was not enough memory for the new buffer -1 will be returned and the global variable "errno" will be set to ENOMEM.
See also:
GetBufferSize()
Author:
Kurt Skauen ([email protected])

ssize_t File::Write ( const void * pBuffer,

ssize_t nSize

) [virtual]

Reimplemented from os::StreamableIO.

ssize_t File::WritePos ( off_t nPos,

const void * pBuffer,

ssize_t nSize

) [virtual]

Reimplemented from os::SeekableIO.

Generated at Tue Sep 11 15:27:47 2001 for AtheOS higlevel API by

os::File Class Reference

Public Types

Public Methods

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation