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 hrev45306 12 * src/kits/storage/Statable.cpp hrev45306 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 51 52/*! 53 \fn status_t BStatable::GetStat(struct stat *st) const 54 \brief Fills out the stat structure for the node. 55 56 This method may be used to access the stat structure of a node directly. 57 58 \param st The stat structure to be filled in. 59 60 \returns A status code. 61 \retval B_OK Everything went fine. 62 \retval B_NO_MEMORY Could not allocate enough memory. 63 \retval B_BAD_VALUE The node does not exist. 64 \retval B_NOT_ALLOWED Node or volume was read only. 65*/ 66 67 68/*! 69 \fn bool BStatable::IsFile() const 70 \brief Returns whether or not the node is a file. 71 72 \return \c true, if the node is properly initialized and is a file, 73 \c false otherwise. 74*/ 75 76 77/*! 78 \fn bool BStatable::IsDirectory() const 79 \brief Returns whether or not the node is a directory. 80 81 \return \c true, if the node is properly initialized and is a directory, 82 \c false otherwise. 83*/ 84 85 86/*! 87 \fn bool BStatable::IsSymLink() const 88 \brief Returns whether or not the node is a symbolic link. 89 90 \return \c true, if the node is properly initialized and is a symlink, 91 \c false otherwise. 92*/ 93 94 95/*! 96 \fn status_t BStatable::GetNodeRef(node_ref *ref) const 97 \brief Fills out \a ref with the \c node_ref of the node. 98 99 \param ref the node_ref to be set. 100 101 \see GetStat() for return codes. 102*/ 103 104 105/*! 106 \fn status_t BStatable::GetOwner(uid_t *owner) const 107 \brief Fills out the node's UID into \a owner. 108 109 \param owner A pointer to a \c uid_t to be set. 110 111 \see GetStat() for return codes. 112*/ 113 114 115/*! 116 \fn status_t BStatable::SetOwner(uid_t owner) 117 \brief Sets the node's UID to \a owner. 118 119 \param owner The UID to set the node to. 120 121 \see GetStat() for return codes. 122*/ 123 124 125/*! 126 \fn status_t BStatable::GetGroup(gid_t *group) const 127 \brief Fills out the node's GID into \a group. 128 129 \param group a pointer to a \c gid_t variable to be set. 130 131 \see GetStat() for return codes. 132*/ 133 134 135/*! 136 \fn status_t BStatable::SetGroup(gid_t group) 137 \brief Sets the node's GID to \a group. 138 139 \param group The GID to set the node to. 140 141 \see GetStat() for return codes. 142*/ 143 144 145/*! 146 \fn status_t BStatable::GetPermissions(mode_t *perms) const 147 \brief Fills out \a perms with the permissions of the node. 148 149 \param perms A pointer to a \c mode_t variable to be set. 150 151 \see GetStat() for return codes. 152*/ 153 154 155/*! 156 \fn status_t BStatable::SetPermissions(mode_t perms) 157 \brief Sets the node's permissions to \a perms. 158 159 \param perms The permissions to set the node to. 160 161 \see GetStat() for return codes. 162*/ 163 164 165/*! 166 \fn status_t BStatable::GetSize(off_t *size) const 167 \brief Fills out the size of the node's data (not counting attributes) 168 into \a size. 169 170 \param size A pointer to a \c off_t variable to be set. 171 172 \see GetStat() for return codes. 173*/ 174 175 176/*! 177 \fn status_t BStatable::GetModificationTime(time_t *mtime) const 178 \brief Fills out \a mtime with the last modification time of the node. 179 180 \param mtime A pointer to a \c time_t variable to be set. 181 182 \see GetStat() for return codes. 183*/ 184 185 186/*! 187 \fn status_t BStatable::SetModificationTime(time_t mtime) 188 \brief Sets the node's last modification time to \a mtime. 189 190 \param mtime The modification time to set the node to. 191 192 \see GetStat() for return codes. 193*/ 194 195 196/*! 197 \fn status_t BStatable::GetCreationTime(time_t *ctime) const 198 \brief Fills out \a ctime with the creation time of the node. 199 200 \param ctime A pointer to a \c time_t variable to be set. 201 202 \see GetStat() for return codes. 203*/ 204 205 206/*! 207 \fn status_t BStatable::SetCreationTime(time_t ctime) 208 \brief Sets the node's creation time to \a ctime. 209 210 \param ctime The creation time to set the node to. 211 212 \see GetStat() for return codes. 213*/ 214 215 216/*! 217 \fn status_t BStatable::GetAccessTime(time_t *atime) const 218 \brief Fills out \a atime with the access time of the node. 219 220 \see GetModificationTime() 221 \see GetStat() for return codes. 222*/ 223 224 225/*! 226 \fn status_t BStatable::SetAccessTime(time_t atime) 227 \brief Sets the node's access time to \a atime. 228 229 \see GetModificationTime() 230 \see GetStat() for return codes. 231*/ 232 233 234/*! 235 \fn status_t BStatable::GetVolume(BVolume *vol) const 236 \brief Fills out \a vol with the the volume that the node lives on. 237 238 \param vol A pointer to a BVolume object to be set. 239 240 \see BVolume 241 \see GetStat() for return codes. 242*/ 243