os::File Class Reference
[The Syllable high level filesystem API]

Description:

More...

Inheritance diagram for os::File:

List of all members.

Public Types
enum	{ DEFAULT_BUFFER_SIZE = 32768 }
Public Member Functions
	File ()
	Default constructor.
	File (const String &cPath, int nOpenMode=O_RDONLY)
	Construct a file from a regular path.
	File (const Directory &cDir, const String &cName, int nOpenMode=O_RDONLY)
	Open a file addressed as a name inside a specified directory.
	File (const FileReference &cRef, int nOpenMode=O_RDONLY)
	Open a file referred to by a os::FileReference.
	File (const FSNode &cNode)
	Construct a file from a FSNode.
	File (int nFD)
	Construct a file object from a open filedescriptor.
	File (const File &cFile)
	Copy constructor.
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.
status_t	SetBufferSize (int nSize)
	Set the size of the files caching buffer.
int	GetBufferSize () const
	Obtain the files buffer size.
status_t	Flush ()
	Write unwritten data to the underlying file.
Classes
class	Private

---

Detailed Description

See also:

Author:

Kurt Skauen ([email protected])

---

Member Enumeration Documentation

anonymous enum

Enumerator:

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

(

int

nFD

)

Description:

Construct a file object from a open filedescriptor.

Note:

The file descriptor will be close when the object is deleted.

Warning:

Parameters:

\return

Error codes:

Since:

0.3.7

See also:

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.

off_t File::GetSize

(

bool

bUpdateCache = true

)

const [virtual]

Reimplemented from os::FSNode.

ssize_t File::Read	(	void *	pBuffer,
		ssize_t	nSize
	)			[virtual]

Implements os::StreamableIO.

ssize_t File::Write	(	const void *	pBuffer,
		ssize_t	nSize
	)			[virtual]

Implements os::StreamableIO.

ssize_t File::ReadPos	(	off_t	nPos,
		void *	pBuffer,
		ssize_t	nSize
	)			[virtual]

Implements os::SeekableIO.

ssize_t File::WritePos	(	off_t	nPos,
		const void *	pBuffer,
		ssize_t	nSize
	)			[virtual]

Implements 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])

Implements 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])

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

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

---