Lowlevel filesystem node class. More...

Inheritance diagram for os::FSNode:

Classes
class	Private

Public Member Functions
	FSNode ()
	Default contructor. More...

	FSNode (const String &cPath, int nOpenMode=O_RDONLY)
	Construct a FSNode from a file path. More...

	FSNode (const Directory &cDir, const String &cName, int nOpenMode=O_RDONLY)
	Construct a FSNode from directory and a name inside that directory. More...

	FSNode (const FileReference &cRef, int nOpenMode=O_RDONLY)
	Construct a FSNode from a file reference. More...

	FSNode (int nFD)
	Construct a FSNode from a file descriptor. More...

	FSNode (const FSNode &cNode)
	Copy contructor. More...

virtual	~FSNode ()
	Destructor. More...

virtual status_t	FDChanged (int nNewFD, const struct stat &sStat)

virtual status_t	SetTo (const String &cPath, int nOpenMode=O_RDONLY)
	Open a node using a path. More...

virtual status_t	SetTo (const Directory &cDir, const String &cPath, int nOpenMode=O_RDONLY)
	Open a node using a dir/path pair. More...

virtual status_t	SetTo (const FileReference &cRef, int nOpenMode=O_RDONLY)
	Open the node referred to by the given os::FileReference. More...

virtual status_t	SetTo (int nFD)
	Make the FSNode represent an already open file. More...

virtual status_t	SetTo (const FSNode &cNode)
	Copy another FSNode. More...

virtual void	Unset ()
	Reset the FSNode. More...

virtual bool	IsValid () const
	Check if the node has been properly initialized. More...

virtual status_t	GetStat (struct stat *psStat, bool bUpdateCache=true) const

virtual ino_t	GetInode () const

virtual dev_t	GetDev () const

virtual int	GetMode (bool bUpdateCache=false) const

virtual off_t	GetSize (bool bUpdateCache=true) const

virtual time_t	GetCTime (bool bUpdateCache=true) const

virtual time_t	GetMTime (bool bUpdateCache=true) const

virtual time_t	GetATime (bool bUpdateCache=true) const

bool	IsDir () const

bool	IsLink () const

bool	IsFile () const

bool	IsCharDev () const

bool	IsBlockDev () const

bool	IsFIFO () const

virtual status_t	GetNextAttrName (String *pcName)
	Read the node's attribute directory. More...

virtual status_t	RewindAttrdir ()
	Reset the attribute directory iterator. More...

virtual ssize_t	WriteAttr (const String &cAttrName, int nFlags, int nType, const void *pBuffer, off_t nPos, size_t nLen)
	Add/update an attribute. More...

virtual ssize_t	ReadAttr (const String &cAttrName, int nType, void *pBuffer, off_t nPos, size_t nLen)
	Read the data held by an attribute. More...

virtual status_t	RemoveAttr (const String &cName)
	Remove an attribute from an FS node. More...

virtual status_t	StatAttr (const String &cName, struct::attr_info *psBuffer)
	Get extended info about an attribute. More...

virtual int	GetFileDescriptor () const

Friends
class	Directory

Detailed Description

Description:: This class give access to the lowest level of a filesystem node. A node can be a directory, regular file, symlink or named pipe.

It give you access to stats that is common to all nodes in the filesystem like time-stamps, access-rights, inode and device numbers, and most imporant the file-attributes.

The native AtheOS filesystem (AFS) support "attributes" wich is extra data-streams associated with filesystem nodes. An attribute can have a specific type like int, float, string, etc etc, or it can be a untyped stream of data. Attributes can be used to store information associated by the file but that don't belong to file content itself (for example the file's icon-image and mime-type).

See Also: os::FileReference, os::File, os::Directory

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Constructor & Destructor Documentation

FSNode::FSNode ( )

Description:: Initiate the FSNode to a known but "invalid" state. The node must be initialize with one of the SetTo() members before any other members can be called.

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by os::SymLink::SetTo().

FSNode::FSNode	(	const String &	cPath,
		int	nOpenMode = `O_RDONLY`
	)

Description:: See: SetTo( const String& cPath, int nOpenMode )

Note:: Since constructors can't return error codes it will throw an os::errno_exception in the case of failure. The error code can be retrieved from the exception object.

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::String::begin(), os::String::c_str(), os::String::end(), os::FSNode::Private::m_hAttrDir, os::FSNode::Private::m_nFD, os::String::size(), and os::String::str().

FSNode::FSNode	(	const Directory &	cDir,
		const String &	cPath,
		int	nOpenMode = `O_RDONLY`
	)

Description:: See: SetTo( const Directory& cDir, const String& cPath, int nOpenMode )

Note:: Since constructors can't return error codes it will throw an os::errno_exception in the case of failure. The error code can be retrieved from the exception object.

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::String::c_str(), GetFileDescriptor(), IsValid(), os::FSNode::Private::m_hAttrDir, and os::FSNode::Private::m_nFD.

FSNode::FSNode	(	const FileReference &	cRef,
		int	nOpenMode = `O_RDONLY`
	)

Description:: See: SetTo( const FileReference& cRef, int nOpenMode )

Note:: Since constructors can't return error codes it will throw an os::errno_exception in the case of failure. The error code can be retrieved from the exception object.

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::String::c_str(), os::FileReference::GetDirectory(), GetFileDescriptor(), os::FileReference::GetName(), os::FileReference::IsValid(), os::FSNode::Private::m_hAttrDir, and os::FSNode::Private::m_nFD.

FSNode::FSNode ( int nFD )

Description:: See: SetTo( int nFD )

Note:: Since constructors can't return error codes it will throw an os::errno_exception in the case of failure. The error code can be retrieved from the exception object.

Since: 0.3.7

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::FSNode::Private::m_hAttrDir, and os::FSNode::Private::m_nFD.

FSNode::FSNode ( const FSNode & cNode )

Description:: Copy an existing node. If the node can't be copyed an os::errno_exception will be thrown. Each node consume a file-descriptor so running out of FD's will cause the copy to fail.

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

cNode The node to copy.

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::FSNode::Private::m_hAttrDir, and os::FSNode::Private::m_nFD.

FSNode::~FSNode ( )

virtual

Description:: Will close the file descriptor and release other resources may consumed by the FSNode.

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::FSNode::Private::m_hAttrDir, and os::FSNode::Private::m_nFD.

Member Function Documentation

status_t FSNode::FDChanged	(	int	nNewFD,
		const struct stat &	sStat
	)

virtual

Reimplemented in os::Directory, and os::File.

Referenced by SetTo(), and Unset().

time_t FSNode::GetATime ( bool bUpdateCache = true ) const

virtual

References os::FSNode::Private::m_nFD.

time_t FSNode::GetCTime ( bool bUpdateCache = true ) const

virtual

References os::FSNode::Private::m_nFD.

dev_t FSNode::GetDev ( ) const

virtual

References os::FSNode::Private::m_nFD.

int FSNode::GetFileDescriptor ( ) const

virtual

References os::FSNode::Private::m_nFD.

Referenced by os::Directory::CreateDirectory(), os::Directory::CreateFile(), os::Directory::CreateSymlink(), os::Directory::Directory(), os::File::Flush(), FSNode(), os::Directory::GetPath(), os::FileReference::GetStat(), os::SymLink::ReadLink(), os::File::ReadPos(), os::Directory::SetPath(), SetTo(), and os::File::WritePos().

ino_t FSNode::GetInode ( ) const

virtual

References os::FSNode::Private::m_nFD.

Referenced by os_priv::DirKeeper::HandleMessage().

int FSNode::GetMode ( bool bUpdateCache = false ) const

virtual

References os::FSNode::Private::m_nFD.

Referenced by os::Directory::Directory(), os::File::File(), os::Directory::SetPath(), os::SymLink::SetTo(), and os::SymLink::SymLink().

time_t FSNode::GetMTime ( bool bUpdateCache = true ) const

virtual

References os::FSNode::Private::m_nFD.

status_t FSNode::GetNextAttrName ( String * pcName )

virtual

Description:: Iterate over the node's "attribute directory". Call this member in sequence until it return "0" to iterate over all the attributes associated with the node. The attribute iterator can be reset to the first attribute with the RewindAttrdir() member.

More info about the returned attributes can be obtain with the StatAttr() member and the content of an attribute can be read with the ReadAttr() member.

Note:: Currently only the Syllable native filesystem (AFS) support attributes so if the the file is not located on an AFS volume this member will fail.

Parameters

pcName Pointer to an STL string that will receive the name.

Returns: If a new name was successfully obtained 1 will be returned. If we reach the end of the attribute directory 0 will be returned. Any other errors will cause -1 to be returned and a error code will be stored in the global "errno" variable.

See Also: StatAttr(), ReadAttr(), WriteAttr()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::FSNode::Private::m_hAttrDir, and os::FSNode::Private::m_nFD.

Referenced by InfoWin::InfoWin().

off_t FSNode::GetSize ( bool bUpdateCache = true ) const

virtual

Reimplemented in os::File.

References os::FSNode::Private::m_nFD.

Referenced by os::File::GetSize().

status_t FSNode::GetStat	(	struct stat *	psStat,
		bool	bUpdateCache = `true`
	)		const

virtual

References os::FSNode::Private::m_nFD.

Referenced by os::IconDirectoryView::HandleMessage(), and InfoWin::InfoWin().

bool os::FSNode::IsBlockDev ( ) const

inline

bool os::FSNode::IsCharDev ( ) const

inline

bool os::FSNode::IsDir ( ) const

inline

bool os::FSNode::IsFIFO ( ) const

inline

bool os::FSNode::IsFile ( ) const

inline

bool os::FSNode::IsLink ( ) const

inline

Referenced by os::IconDirectoryView::Invoked().

bool FSNode::IsValid ( void ) const

virtual

Description:: Return true if the the object actually reference a real FS node. All other access functions will fail if the object is not fully initializesed eighter through one of the non-default constructors or with one of the SetTo() members.

Returns: True if the object is fully initialized false otherwhice.

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::FSNode::Private::m_nFD.

Referenced by os::File::FDChanged(), FSNode(), os::FileReference::IsValid(), os::NodeMonitor::NodeMonitor(), SetTo(), and os::NodeMonitor::SetTo().

ssize_t FSNode::ReadAttr	(	const String &	cAttrName,
		int	nType,
		void *	pBuffer,
		off_t	nPos,
		size_t	nLen
	)

virtual

Description:: Read an arbritary chunk of an attributes data. Both the name and the type must match for the operation so succede. If you don't know the type in advance it can be retrieved with the StatAttr() member.

Note:: Currently only the Syllable native filesystem (AFS) support attributes so if the the file is not located on an AFS volume this member will fail.

Parameters

cAttrName	The name of the attribute to read.
nType	The expected attribute type. The attribute must be of this type for the function to succede. See WriteAttr() for a more detailed descritpion of attribute types.

Returns: On success the number of bytes actually read is returned. On failure -1 is returned and the error code is stored in the global variable "errno".

See Also: WriteAttr(), StatAttr()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::String::c_str(), and os::FSNode::Private::m_nFD.

Referenced by InfoWin::InfoWin().

status_t FSNode::RemoveAttr ( const String & cName )

virtual

Description:: This will remove the named attribute from the node itself and if the attribute has been indexed it will also be removed from the index.

Note:: Currently only the Syllable native filesystem (AFS) support attributes so if the the file is not located on an AFS volume this member will fail.

Parameters

cName Name of the attribute to remove.

Returns: On success 0 is returned. On failure -1 is returned and the error code is stored in the global variable "errno".

See Also: WriteAttr(), ReadAttr()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::String::c_str(), and os::FSNode::Private::m_nFD.

status_t FSNode::RewindAttrdir ( )

virtual

Description:: RewindAttrdir() will cause the next GetNextAttrName() call to return the name of the first attribute associated with this node.

Note:: Currently only the Syllable native filesystem (AFS) support attributes so if the the file is not located on an AFS volume this member will fail.

Returns: 0 on success. On failure -1 is returned and a error code is stored in the global variable "errno".

See Also: GetNextAttrName()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::FSNode::Private::m_hAttrDir, and os::FSNode::Private::m_nFD.

status_t FSNode::SetTo	(	const String &	cPath,
		int	nOpenMode = `O_RDONLY`
	)

virtual

Description:: Open a node by path. The path must be valid and the process must have access to it but it can point to any kind of FS-node (file, directory, symlink).

The path can start with "~/" to make it relative to the current users home directory or it can start with "^/" to make it relative to the directory where the executable our application was started from lives in. This path expansion is performed by the os::FSNode class itself and is not part of the low-level filesystem.

The nOpenMode should be a compination of any of the O_* flags defined in <fcntl.h>. Their meaning is the same as when opening a file with the open() POSIX function except you can not create a file by setting the O_CREAT flag.

The following flags are accepted:

O_RDONLY open the node read-only
O_WRONLY open the node write-only
O_RDWR open the node for both reading and writing
O_TRUNC trunate the size to 0 (only valid for files)
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
O_DIRECTORY fail if cPath don't point at a directory
O_NOTRAVERSE open the symlink it self rather than it's target if cPath points at a symlink

Note:: If this call fail the old state of the FSNode will remain unchanged

Parameters

cPath	Path pointing at the node to open.
nOpenMode	Flags controlling how to open the node.

Returns: On success 0 is returned. On error -1 is returned and a error code is assigned to the global variable "errno". The error code can be any of the errors returned by the open() POSIX function.

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Reimplemented in os::SymLink.

References os::String::begin(), os::String::c_str(), os::String::end(), FDChanged(), os::FSNode::Private::m_nFD, os::String::size(), and os::String::str().

Referenced by os::Directory::CreateDirectory(), os::Directory::CreateFile(), os::FileReference::FileReference(), os_priv::DirKeeper::GetNode(), os::RegistrarManager::GetTypeAndIcon(), InfoWin::InfoWin(), os::RegistrarManager::RegisterTypeIconFromRes(), os::Directory::SetPath(), os::SymLink::SetTo(), os::FileReference::SetTo(), and os::TempFile::TempFile().

status_t FSNode::SetTo	(	const Directory &	cDir,
		const String &	cPath,
		int	nOpenMode = `O_RDONLY`
	)

virtual

Description:: Open a node by using a directory and a path relative to that directory.

The path can eighter be absolute (cDir will then be ignored) or it can be relative to cDir. This have much the same semantics as setting the current working directory to cDir and then open the node by calling SetTo( const String& cPath, int nOpenMode ) with the path. The main advantage with this function is that it is thread-safe. You don't get any races while temporarily changing the current working directory.

For a more detailed description look at: SetTo( const String& cPath, int nOpenMode )

Note: If this call fail the old state of the FSNode will remain unchanged

Parameters

cDir	A valid directory from which the `cPath` is relative to.
cPath	The file path relative to `cDir`. The path can eighter be absoulute (in which case `cDir` is ignored) or it can be relative to `cDir`.
nOpenMode	Flags controlling how to open the node. See SetTo( const String& cPath, int nOpenMode ) for a full description of the various flags.

Returns: On success 0 is returned. On error -1 is returned and a error code is assigned to the global variable "errno". The error code can be any of the errors returned by the open() POSIX function.

See Also: FSNode( const String& cPath, int nOpenMode )

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Reimplemented in os::SymLink.

References os::String::c_str(), FDChanged(), GetFileDescriptor(), IsValid(), and os::FSNode::Private::m_nFD.

status_t FSNode::SetTo	(	const FileReference &	cRef,
		int	nOpenMode = `O_RDONLY`
	)

virtual

Description:: Same semantics SetTo( const String& cPath, int nOpenMode ) except that the node to open is targeted by a file reference rather than a regular path.

Note:: If this call fail the old state of the FSNode will remain unchanged

Returns: On success 0 is returned. On error -1 is returned and a error code is assigned to the global variable "errno". The error code can be any of the errors returned by the open() POSIX function.

See Also: SetTo( const String& cPath, int nOpenMode )

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Reimplemented in os::SymLink.

References os::String::c_str(), FDChanged(), os::FileReference::GetDirectory(), GetFileDescriptor(), os::FileReference::GetName(), os::FileReference::IsValid(), and os::FSNode::Private::m_nFD.

status_t FSNode::SetTo ( int nNewFD )

virtual

Description:: Make the FSNode represent an already open file.

Note:: If this call fail the old state of the FSNode will remain unchanged

Returns: On success 0 is returned. On error -1 is returned and a error code is assigned to the global variable "errno". The error code can be any of the errors returned by the open() POSIX function.

Since: 0.3.7

See Also: SetTo( const String& cPath, int nOpenMode )

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References FDChanged(), and os::FSNode::Private::m_nFD.

status_t FSNode::SetTo ( const FSNode & cNode )

virtual

Description:: Make this node a clone of cNode.

Note:: If this call fail the old state of the FSNode will remain unchanged

Parameters

cNode The FSNode to copy.

Returns: On success 0 is returned. On error -1 is returned and a error code is assigned to the global variable "errno". The error code can be any of the errors returned by the open() POSIX function.

See Also

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Reimplemented in os::SymLink.

References FDChanged(), and os::FSNode::Private::m_nFD.

status_t FSNode::StatAttr	(	const String &	cName,
		struct::attr_info *	psBuffer
	)

virtual

Description:: Call this function to retrieve the size and type of an attribute. For a detailed description of the attribute type take a look at WriteAttr().

Note:: Currently only the Syllable native filesystem (AFS) support attributes so if the the file is not located on an AFS volume this member will fail.

Parameters

cName The name of the attribute to examine.

Returns: On success 0 is returned. On failure -1 is returned and the error code is stored in the global variable "errno".

See Also: WriteAttr(), ReadAttr()

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::String::c_str(), and os::FSNode::Private::m_nFD.

Referenced by InfoWin::InfoWin().

void FSNode::Unset ( )

virtual

Description:: Will close the file descriptor and other resources may consumed by the FSNode. The IsValid() member will return false until the node is reinitialized with one of the SetTo() members.

Author: Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References FDChanged(), os::FSNode::Private::m_hAttrDir, and os::FSNode::Private::m_nFD.

Referenced by os::RegistrarManager::RegisterTypeIconFromRes(), and os::FileReference::Unset().

ssize_t FSNode::WriteAttr	(	const String &	cAttrName,
		int	nFlags,
		int	nType,
		const void *	pBuffer,
		off_t	nPos,
		size_t	nLen
	)

virtual

Description:: WriteAttr() is used to create new attributes and update existing attributes. A attribute is simply a chunc of data that is associated with the file but that is not part of the files regular data-stream. Attributes can be added to all kind's of FS nodes like regular files, directories, and symlinks.

A attribute can contain a untyped stream of data of an arbritary length or it can contain typed data like integers, floats, strings, etc etc. The reason for having typed data is to be able to make a search index that can be used to for efficient search for files based on their attributes. The indexing system is not fully implemented yet but will be part of Syllable in the future.

Note:: Currently only the Syllable native filesystem (AFS) support attributes so if the the file is not located on an AFS volume this member will fail.

Parameters

cAttrName	The name of the attribute. The name must be unique inside the scope of the node it belongs to. If an attribute already exists with that name it will be overwritten.
nFlags	Currently only O_TRUNC is accepted. If you pass in O_TRUNC and a attribute with the same name already exists it will be truncated to a size of 0 before the new attribute data is written. By passing in 0 you can update parts of or extend an existing attribute.
nType	The data-type of the attribute. This should be one of the ATTR_TYPE_* types defined in <pyro/filesystem.h>.

ATTR_TYPE_NONE, Untyped "raw" data of any size.
ATTR_TYPE_INT32, 32-bit integer value (the size must be exactly 4 bytes).
ATTR_TYPE_INT64, 64-bit integer value often used for time-values (the size must be exactly 8 bytes).
ATTR_TYPE_FLOAT, 32-bit floating point value (the size must be exactly 4 bytes).
ATTR_TYPE_DOUBLE, 64-bit floating point value (the size must be exactly 8 bytes).
ATTR_TYPE_STRING, UTF8 string. The string should not be NUL terminated.
Parameters

pBuffer Pointer to the data to be written.

nPos The offset into the attribute where the data will be written.

nLen Number of bytes to be written.

Returns
On success the number of bytes actually written is returned. On failure -1 is returned and the error code is stored in the global variable "errno"

See Also
ReadAttr(), StatAttr()

Author
Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::String::c_str(), and os::FSNode::Private::m_nFD.

Friends And Related Function Documentation

friend class Directory

friend

pBuffer	Pointer to the data to be written.
nPos	The offset into the attribute where the data will be written.
nLen	Number of bytes to be written.

Classes

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation