[haiku-commits] haiku: hrev45307 - docs/user/storage src/kits/storage
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Wed, 20 Feb 2013 01:07:49 +0100 (CET)
hrev45307 adds 1 changeset to branch 'master'
old head: 789e7d856e1e59af76566b9f806c2087258be0d7
new head: 5bff846db2dfe4bb2a575c8a25cb18e2afd5eb2b
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=5bff846+%5E789e7d8
----------------------------------------------------------------------------
5bff846: Move BStatable docs to Haiku Book.
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev45307
Commit: 5bff846db2dfe4bb2a575c8a25cb18e2afd5eb2b
URL: http://cgit.haiku-os.org/haiku/commit/?id=5bff846
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Wed Feb 20 00:07:15 2013 UTC
----------------------------------------------------------------------------
2 files changed, 278 insertions(+), 90 deletions(-)
docs/user/storage/Statable.dox | 243 +++++++++++++++++++++++++++++++++++++
src/kits/storage/Statable.cpp | 125 ++++++-------------
----------------------------------------------------------------------------
diff --git a/docs/user/storage/Statable.dox b/docs/user/storage/Statable.dox
new file mode 100644
index 0000000..0daa1ed
--- /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@xxxxxxxxx
+ * Ingo Weinhold, bonefish@xxxxxxxxxxxx
+ *
+ * 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 5acc4d0..6c7f44b 100644
--- a/src/kits/storage/Statable.cpp
+++ b/src/kits/storage/Statable.cpp
@@ -7,10 +7,6 @@
* Ingo Weinhold, bonefish@xxxxxxxxxxxx
*/
-/*!
- \file Statable.cpp
- BStatable implementation.
-*/
#include <Statable.h>
@@ -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
{
Other related posts:
- » [haiku-commits] haiku: hrev45307 - docs/user/storage src/kits/storage - jscipione
