docs/user/storage/Statable.dox

   1 /*
   2  * Copyright 2002-2013 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Tyler Dauwalder
   7  *              John Scipione, jscipione@gmail.com
   8  *              Ingo Weinhold, bonefish@users.sf.net
   9  *
  10  * Corresponds to:
  11  *              headers/os/storage/Statable.h   hrev47402
  12  *              src/kits/storage/Statable.cpp   hrev47402
  13  */
  14
  15
  16 /*!
  17         \file Statable.h
  18         \ingroup storage
  19         \ingroup libbe
  20         \brief Provides the BStatable abstract class.
  21 */
  22
  23
  24 /*!
  25         \class BStatable
  26         \ingroup storage
  27         \ingroup libbe
  28         \brief Pure abstract class that provides a wrapper interface to the POSIX®
  29                stat() function.
  30
  31         BStatable provides common functionality for the BEntry and BNode classes.
  32         You can use this class to:
  33         - Get the stat struct of a node with the GetStat() method.
  34         - Identify a node as a file, directory, or symbolic link with the
  35           IsFile(), IsDirectory(), and IsSymLink() methods.
  36         - Get and set the UID (GetOwner() and SetOwner()), GID (GetGroup() and
  37           SetGroup()), and permissions (GetPermissions() and SetPermissions()) of
  38           a node.
  39         - Get the size of a node's data (not counting attributes) with the
  40           GetSize() method.
  41         - Get and set a node's modification time (GetModificationTime() and
  42           SetModificationTime()), creation time (GetCreationTime() and
  43           SetCreationTime()), and access time (GetAccessTime() and
  44           SetAccessTime()).
  45         - Get a pointer to the BVolume object that a node lives on via the
  46           GetVolume() method.
  47         - Get a node_ref of a node to pass into watch_node() via the GetNodeRef()
  48           method.
  49
  50         \since BeOS R3
  51 */
  52
  53
  54 /*!
  55         \fn status_t BStatable::GetStat(struct stat* stat) const
  56         \brief Fills out the stat structure for the node.
  57
  58         This method may be used to access the stat structure of a node directly.
  59
  60         \param stat The stat structure to be filled in.
  61
  62         \returns A status code.
  63         \retval B_OK Everything went fine.
  64         \retval B_NO_MEMORY Could not allocate enough memory.
  65         \retval B_BAD_VALUE The node does not exist.
  66         \retval B_NOT_ALLOWED Node or volume was read only.
  67
  68         \since BeOS R3
  69 */
  70
  71
  72 /*!
  73         \fn bool BStatable::IsFile() const
  74         \brief Returns whether or not the node is a file.
  75
  76         \return \c true, if the node is properly initialized and is a file,
  77                 \c false otherwise.
  78
  79         \since BeOS R5
  80 */
  81
  82
  83 /*!
  84         \fn bool BStatable::IsDirectory() const
  85         \brief Returns whether or not the node is a directory.
  86
  87         \return \c true, if the node is properly initialized and is a directory,
  88                 \c false otherwise.
  89
  90         \since BeOS R5
  91 */
  92
  93
  94 /*!
  95         \fn bool BStatable::IsSymLink() const
  96         \brief Returns whether or not the node is a symbolic link.
  97
  98         \return \c true, if the node is properly initialized and is a symlink,
  99                 \c false otherwise.
 100
 101         \since BeOS R5
 102 */
 103
 104
 105 /*!
 106         \fn status_t BStatable::GetNodeRef(node_ref* ref) const
 107         \brief Fills out \a ref with the \c node_ref of the node.
 108
 109         \param ref the node_ref to be set.
 110
 111         \see GetStat() for return codes.
 112
 113         \since BeOS R3
 114 */
 115
 116
 117 /*!
 118         \fn status_t BStatable::GetOwner(uid_t* owner) const
 119         \brief Fills out the node's UID into \a owner.
 120
 121         \param owner A pointer to a \c uid_t to be set.
 122
 123         \see SetOwner()
 124         \see GetStat() for return codes.
 125
 126         \since BeOS R3
 127 */
 128
 129
 130 /*!
 131         \fn status_t BStatable::SetOwner(uid_t owner)
 132         \brief Sets the node's UID to \a owner.
 133
 134         \param owner The UID to set the node to.
 135
 136         \see GetStat() for return codes.
 137
 138         \since BeOS R3
 139 */
 140
 141
 142 /*!
 143         \fn status_t BStatable::GetGroup(gid_t* group) const
 144         \brief Fills out the node's GID into \a group.
 145
 146         \param group a pointer to a \c gid_t variable to be set.
 147
 148         \see SetGroup()
 149         \see GetStat() for return codes.
 150
 151         \since BeOS R3
 152 */
 153
 154
 155 /*!
 156         \fn status_t BStatable::SetGroup(gid_t group)
 157         \brief Sets the node's GID to \a group.
 158
 159         \param group The GID to set the node to.
 160
 161         \see GetStat() for return codes.
 162
 163         \since BeOS R3
 164 */
 165
 166
 167 /*!
 168         \fn status_t BStatable::GetPermissions(mode_t* permissions) const
 169         \brief Fills out \a perms with the permissions of the node.
 170
 171         \param permissions The permissions to get from the node.
 172
 173         \see SetPermissions()
 174         \see GetStat() for return codes.
 175
 176         \since BeOS R3
 177 */
 178
 179
 180 /*!
 181         \fn status_t BStatable::SetPermissions(mode_t permissions)
 182         \brief Sets the node's permissions to \a perms.
 183
 184         \param permissions The permissions to set the node to.
 185
 186         \see GetStat() for return codes.
 187
 188         \since BeOS R3
 189 */
 190
 191
 192 /*!
 193         \fn status_t BStatable::GetSize(off_t* size) const
 194         \brief Fills out the size of the node's data (not counting attributes)
 195                into \a size.
 196
 197         \param size A pointer to a \c off_t variable to be set.
 198
 199         \see GetStat() for return codes.
 200
 201         \since BeOS R3
 202 */
 203
 204
 205 /*!
 206         \fn status_t BStatable::GetModificationTime(time_t* mtime) const
 207         \brief Fills out \a mtime with the last modification time of the node.
 208
 209         \param mtime A pointer to a \c time_t variable to be set.
 210
 211         \see SetModificationTime()
 212         \see GetStat() for return codes.
 213
 214         \since BeOS R3
 215 */
 216
 217
 218 /*!
 219         \fn status_t BStatable::SetModificationTime(time_t mtime)
 220         \brief Sets the node's last modification time to \a mtime.
 221
 222         \param mtime The modification time to set the node to.
 223
 224         \see GetStat() for return codes.
 225
 226         \since BeOS R3
 227 */
 228
 229
 230 /*!
 231         \fn status_t BStatable::GetCreationTime(time_t* ctime) const
 232         \brief Fills out \a ctime with the creation time of the node.
 233
 234         \param ctime A pointer to a \c time_t variable to be set.
 235
 236         \see SetCreationTime()
 237         \see GetStat() for return codes.
 238
 239         \since BeOS R3
 240 */
 241
 242
 243 /*!
 244         \fn status_t BStatable::SetCreationTime(time_t ctime)
 245         \brief Sets the node's creation time to \a ctime.
 246
 247         \param ctime The creation time to set the node to.
 248
 249         \see GetStat() for return codes.
 250
 251         \since BeOS R3
 252 */
 253
 254
 255 /*!
 256         \fn status_t BStatable::GetAccessTime(time_t* atime) const
 257         \brief Fills out \a atime with the access time of the node.
 258
 259         \see GetModificationTime()
 260         \see SetAccessTime()
 261         \see GetStat() for return codes.
 262
 263         \since BeOS R3
 264 */
 265
 266
 267 /*!
 268         \fn status_t BStatable::SetAccessTime(time_t atime)
 269         \brief Sets the node's access time to \a atime.
 270
 271         \see GetModificationTime()
 272         \see GetStat() for return codes.
 273
 274         \since BeOS R3
 275 */
 276
 277
 278 /*!
 279         \fn status_t BStatable::GetVolume(BVolume* volume) const
 280         \brief Fills out \a vol with the the volume that the node lives on.
 281
 282         \param volume A pointer to a BVolume object to be set.
 283
 284         \see BVolume
 285         \see GetStat() for return codes.
 286
 287         \since Haiku R1
 288 */