/*
 * Copyright 2002-2026 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	hrev59636
 *		src/kits/storage/Statable.cpp	hrev59636
 */


/*!
	\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 \c B_OK on success, or an error code on failure.

	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE The node does not exist, possibly renamed or deleted.
	\retval B_FILE_ERROR File descriptor not found.
	\retval B_ENTRY_NOT_FOUND The node inside a directory could not be found.
	\retval B_NOT_A_DIRECTORY The node is not a directory, but it should be.

	\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
*/
