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::

os::SeekableIO os::FSNode os::StreamableIO os::TempFile 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 doxygen1.2.9.1 written by Dimitri van Heesch, © 1997-2001