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