haiku/docs/user/storage/Statable.dox

/*
 * Copyright 2002-2013 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Tyler Dauwalder
 *		John Scipione, jscipione@gmail.com
 *		Ingo Weinhold, bonefish@users.sf.net
 *
 * Corresponds to:
 *		headers/os/storage/Statable.h	hrev47402
 *		src/kits/storage/Statable.cpp	hrev47402
 */


/*!
	\file Statable.h
	\ingroup storage
	\ingroup libbe
	\brief Provides the BStatable abstract class.
*/


/*!
	\class BStatable
	\ingroup storage
	\ingroup libbe
	\brief Pure abstract class that provides a wrapper interface to the POSIX®
	       stat() function.

	BStatable provides common functionality for the BEntry and BNode classes.
	You can use this class to:
	- Get the stat struct of a node with the GetStat() method.
	- Identify a node as a file, directory, or symbolic link with the
	  IsFile(), IsDirectory(), and IsSymLink() methods.
	- Get and set the UID (GetOwner() and SetOwner()), GID (GetGroup() and
	  SetGroup()), and permissions (GetPermissions() and SetPermissions()) of
	  a node.
	- Get the size of a node's data (not counting attributes) with the
	  GetSize() method.
	- Get and set a node's modification time (GetModificationTime() and
	  SetModificationTime()), creation time (GetCreationTime() and
	  SetCreationTime()), and access time (GetAccessTime() and
	  SetAccessTime()).
	- Get a pointer to the BVolume object that a node lives on via the
	  GetVolume() method.
	- Get a node_ref of a node to pass into watch_node() via the GetNodeRef()
	  method.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::GetStat(struct stat* stat) const
	\brief Fills out the stat structure for the node.

	This method may be used to access the stat structure of a node directly.

	\param stat The stat structure to be filled in.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_NO_MEMORY Could not allocate enough memory.
	\retval B_BAD_VALUE The node does not exist.
	\retval B_NOT_ALLOWED Node or volume was read only.

	\since BeOS R3
*/


/*!
	\fn bool BStatable::IsFile() const
	\brief Returns whether or not the node is a file.

	\return \c true, if the node is properly initialized and is a file,
	        \c false otherwise.

	\since BeOS R5
*/


/*!
	\fn bool BStatable::IsDirectory() const
	\brief Returns whether or not the node is a directory.

	\return \c true, if the node is properly initialized and is a directory,
	        \c false otherwise.

	\since BeOS R5
*/


/*!
	\fn bool BStatable::IsSymLink() const
	\brief Returns whether or not the node is a symbolic link.

	\return \c true, if the node is properly initialized and is a symlink,
	        \c false otherwise.

	\since BeOS R5
*/


/*!
	\fn status_t BStatable::GetNodeRef(node_ref* ref) const
	\brief Fills out \a ref with the \c node_ref of the node.

	\param ref the node_ref to be set.

	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::GetOwner(uid_t* owner) const
	\brief Fills out the node's UID into \a owner.

	\param owner A pointer to a \c uid_t to be set.

	\see SetOwner()
	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::SetOwner(uid_t owner)
	\brief Sets the node's UID to \a owner.

	\param owner The UID to set the node to.

	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::GetGroup(gid_t* group) const
	\brief Fills out the node's GID into \a group.

	\param group a pointer to a \c gid_t variable to be set.

	\see SetGroup()
	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::SetGroup(gid_t group)
	\brief Sets the node's GID to \a group.

	\param group The GID to set the node to.

	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::GetPermissions(mode_t* permissions) const
	\brief Fills out \a perms with the permissions of the node.

	\param permissions The permissions to get from the node.

	\see SetPermissions()
	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::SetPermissions(mode_t permissions)
	\brief Sets the node's permissions to \a perms.

	\param permissions The permissions to set the node to.

	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::GetSize(off_t* size) const
	\brief Fills out the size of the node's data (not counting attributes)
	       into \a size.

	\param size A pointer to a \c off_t variable to be set.

	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::GetModificationTime(time_t* mtime) const
	\brief Fills out \a mtime with the last modification time of the node.

	\param mtime A pointer to a \c time_t variable to be set.

	\see SetModificationTime()
	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::SetModificationTime(time_t mtime)
	\brief Sets the node's last modification time to \a mtime.

	\param mtime The modification time to set the node to.

	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::GetCreationTime(time_t* ctime) const
	\brief Fills out \a ctime with the creation time of the node.

	\param ctime A pointer to a \c time_t variable to be set.

	\see SetCreationTime()
	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::SetCreationTime(time_t ctime)
	\brief Sets the node's creation time to \a ctime.

	\param ctime The creation time to set the node to.

	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::GetAccessTime(time_t* atime) const
	\brief Fills out \a atime with the access time of the node.

	\see GetModificationTime()
	\see SetAccessTime()
	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::SetAccessTime(time_t atime)
	\brief Sets the node's access time to \a atime.

	\see GetModificationTime()
	\see GetStat() for return codes.

	\since BeOS R3
*/


/*!
	\fn status_t BStatable::GetVolume(BVolume* volume) const
	\brief Fills out \a vol with the the volume that the node lives on.

	\param volume A pointer to a BVolume object to be set.

	\see BVolume
	\see GetStat() for return codes.

	\since Haiku R1
*/