From 5bff846db2dfe4bb2a575c8a25cb18e2afd5eb2b Mon Sep 17 00:00:00 2001 From: John Scipione Date: Tue, 19 Feb 2013 19:07:15 -0500 Subject: [PATCH] Move BStatable docs to Haiku Book. --- docs/user/storage/Statable.dox | 243 +++++++++++++++++++++++++++++++++ src/kits/storage/Statable.cpp | 125 +++++------------ 2 files changed, 278 insertions(+), 90 deletions(-) create mode 100644 docs/user/storage/Statable.dox diff --git a/docs/user/storage/Statable.dox b/docs/user/storage/Statable.dox new file mode 100644 index 0000000000..0daa1ed9e5 --- /dev/null +++ b/docs/user/storage/Statable.dox @@ -0,0 +1,243 @@ +/* + * 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 hrev45306 + * src/kits/storage/Statable.cpp hrev45306 + */ + + +/*! + \file Statable.h + \ingroup storage + \ingroup libbe + + 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. +*/ + + +/*! + \fn status_t BStatable::GetStat(struct stat *st) 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 st 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. +*/ + + +/*! + \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. +*/ + + +/*! + \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. +*/ + + +/*! + \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. +*/ + + +/*! + \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. +*/ + + +/*! + \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 GetStat() for return codes. +*/ + + +/*! + \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. +*/ + + +/*! + \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 GetStat() for return codes. +*/ + + +/*! + \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. +*/ + + +/*! + \fn status_t BStatable::GetPermissions(mode_t *perms) const + \brief Fills out \a perms with the permissions of the node. + + \param perms A pointer to a \c mode_t variable to be set. + + \see GetStat() for return codes. +*/ + + +/*! + \fn status_t BStatable::SetPermissions(mode_t perms) + \brief Sets the node's permissions to \a perms. + + \param perms The permissions to set the node to. + + \see GetStat() for return codes. +*/ + + +/*! + \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. +*/ + + +/*! + \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 GetStat() for return codes. +*/ + + +/*! + \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. +*/ + + +/*! + \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 GetStat() for return codes. +*/ + + +/*! + \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. +*/ + + +/*! + \fn status_t BStatable::GetAccessTime(time_t *atime) const + \brief Fills out \a atime with the access time of the node. + + \see GetModificationTime() + \see GetStat() for return codes. +*/ + + +/*! + \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. +*/ + + +/*! + \fn status_t BStatable::GetVolume(BVolume *vol) const + \brief Fills out \a vol with the the volume that the node lives on. + + \param vol A pointer to a BVolume object to be set. + + \see BVolume + \see GetStat() for return codes. +*/ diff --git a/src/kits/storage/Statable.cpp b/src/kits/storage/Statable.cpp index 5acc4d0a01..6c7f44b4da 100644 --- a/src/kits/storage/Statable.cpp +++ b/src/kits/storage/Statable.cpp @@ -7,10 +7,6 @@ * Ingo Weinhold, bonefish@users.sf.net */ -/*! - \file Statable.cpp - BStatable implementation. -*/ #include @@ -48,21 +44,7 @@ BStatable::~BStatable() #endif -/*! \fn status_t GetStat(struct stat *st) const - \brief Returns the stat stucture for the node. - \param st the stat structure to be filled in. - \return - - \c B_OK: Worked fine - - \c B_NO_MEMORY: Could not allocate the memory for the call. - - \c B_BAD_VALUE: The current node does not exist. - - \c B_NOT_ALLOWED: Read only node or volume. -*/ - - -/*! \brief Returns if the current node is a file. - \return \c true, if the BNode is properly initialized and is a file, - \c false otherwise. -*/ +// Returns whether or not the current node is a file. bool BStatable::IsFile() const { @@ -73,10 +55,8 @@ BStatable::IsFile() const return false; } -/*! \brief Returns if the current node is a directory. - \return \c true, if the BNode is properly initialized and is a file, - \c false otherwise. -*/ + +// Returns whether or not the current node is a directory. bool BStatable::IsDirectory() const { @@ -87,10 +67,8 @@ BStatable::IsDirectory() const return false; } -/*! \brief Returns if the current node is a symbolic link. - \return \c true, if the BNode is properly initialized and is a symlink, - \c false otherwise. -*/ + +// Returns whether or not the current node is a symbolic link. bool BStatable::IsSymLink() const { @@ -101,10 +79,8 @@ BStatable::IsSymLink() const return false; } -/*! \brief Returns a node_ref for the current node. - \param ref the node_ref structure to be filled in - \see GetStat() for return codes -*/ + +// Fills out ref with the node_ref of the node. status_t BStatable::GetNodeRef(node_ref *ref) const { @@ -119,10 +95,8 @@ BStatable::GetNodeRef(node_ref *ref) const return error; } -/*! \brief Returns the owner of the node. - \param owner a pointer to a uid_t variable to be set to the result - \see GetStat() for return codes -*/ + +// Fills out the node's UID into owner. status_t BStatable::GetOwner(uid_t *owner) const { @@ -135,10 +109,8 @@ BStatable::GetOwner(uid_t *owner) const return error; } -/*! \brief Sets the owner of the node. - \param owner the new owner - \see GetStat() for return codes -*/ + +// Sets the node's UID to owner. status_t BStatable::SetOwner(uid_t owner) { @@ -147,10 +119,8 @@ BStatable::SetOwner(uid_t owner) return set_stat(statData, B_STAT_UID); } -/*! \brief Returns the group owner of the node. - \param group a pointer to a gid_t variable to be set to the result - \see GetStat() for return codes -*/ + +// Fills out the node's GID into group. status_t BStatable::GetGroup(gid_t *group) const { @@ -163,10 +133,8 @@ BStatable::GetGroup(gid_t *group) const return error; } -/*! \brief Sets the group owner of the node. - \param group the new group - \see GetStat() for return codes -*/ + +// Sets the node's GID to group. status_t BStatable::SetGroup(gid_t group) { @@ -175,10 +143,8 @@ BStatable::SetGroup(gid_t group) return set_stat(statData, B_STAT_GID); } -/*! \brief Returns the permissions of the node. - \param perms a pointer to a mode_t variable to be set to the result - \see GetStat() for return codes -*/ + +// Fills out perms with the node's permissions. status_t BStatable::GetPermissions(mode_t *perms) const { @@ -191,10 +157,8 @@ BStatable::GetPermissions(mode_t *perms) const return error; } -/*! \brief Sets the permissions of the node. - \param perms the new permissions - \see GetStat() for return codes -*/ + +// Sets the node's permissions to perms. status_t BStatable::SetPermissions(mode_t perms) { @@ -205,10 +169,8 @@ BStatable::SetPermissions(mode_t perms) return set_stat(statData, B_STAT_MODE); } -/*! \brief Get the size of the node's data (not counting attributes). - \param size a pointer to a variable to be set to the result - \see GetStat() for return codes -*/ + +// Fills out the size of the node's data (not counting attributes) into size. status_t BStatable::GetSize(off_t *size) const { @@ -221,10 +183,8 @@ BStatable::GetSize(off_t *size) const return error; } -/*! \brief Returns the last time the node was modified. - \param mtime a pointer to a variable to be set to the result - \see GetStat() for return codes -*/ + +// Fills out mtime with the last modification time of the node. status_t BStatable::GetModificationTime(time_t *mtime) const { @@ -237,10 +197,8 @@ BStatable::GetModificationTime(time_t *mtime) const return error; } -/*! \brief Sets the last time the node was modified. - \param mtime the new modification time - \see GetStat() for return codes -*/ + +// Sets the node's last modification time to mtime. status_t BStatable::SetModificationTime(time_t mtime) { @@ -249,10 +207,8 @@ BStatable::SetModificationTime(time_t mtime) return set_stat(statData, B_STAT_MODIFICATION_TIME); } -/*! \brief Returns the time the node was created. - \param ctime a pointer to a variable to be set to the result - \see GetStat() for return codes -*/ + +// Fills out ctime with the creation time of the node status_t BStatable::GetCreationTime(time_t *ctime) const { @@ -265,10 +221,8 @@ BStatable::GetCreationTime(time_t *ctime) const return error; } -/*! \brief Sets the time the node was created. - \param ctime the new creation time - \see GetStat() for return codes -*/ + +// Sets the node's creation time to ctime. status_t BStatable::SetCreationTime(time_t ctime) { @@ -277,11 +231,8 @@ BStatable::SetCreationTime(time_t ctime) return set_stat(statData, B_STAT_CREATION_TIME); } -/*! \brief Returns the time the node was accessed. - Not used. - \see GetModificationTime() - \see GetStat() for return codes -*/ + +// Fills out atime with the access time of the node. status_t BStatable::GetAccessTime(time_t *atime) const { @@ -294,11 +245,8 @@ BStatable::GetAccessTime(time_t *atime) const return error; } -/*! \brief Sets the time the node was accessed. - Not used. - \see GetModificationTime() - \see GetStat() for return codes -*/ + +// Sets the node's access time to atime. status_t BStatable::SetAccessTime(time_t atime) { @@ -307,11 +255,8 @@ BStatable::SetAccessTime(time_t atime) return set_stat(statData, B_STAT_ACCESS_TIME); } -/*! \brief Returns the volume the node lives on. - \param vol a pointer to a variable to be set to the result - \see BVolume - \see GetStat() for return codes -*/ + +// Fills out vol with the the volume that the node lives on. status_t BStatable::GetVolume(BVolume *vol) const {