docs/user/storage/Node.dox

   1 /*
   2  * Copyright 2002-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              John Scipione, jscipione@gmail.com
   7  *              Ingo Weinhold, bonefish@users.sf.net
   8  *
   9  * Corresponds to:
  10  *              headers/os/storage/Node.h       hrev47402
  11  *              src/kits/storage/Node.cpp       hrev47402
  12  */
  13
  14
  15 /*!
  16         \file Node.h
  17         \ingroup storage
  18         \ingroup libbe
  19         \brief Provides the BNode class and node_ref struct.
  20 */
  21
  22
  23 /*!
  24         \struct node_ref
  25         \ingroup storage
  26         \ingroup libbe
  27         \brief Reference structure to a particular vnode on a device.
  28
  29         \since BeOS R3
  30 */
  31
  32
  33 /*!
  34         \fn node_ref::node_ref()
  35         \brief Creates an uninitialized node_ref object.
  36
  37         \since BeOS R3
  38 */
  39
  40
  41 /*!
  42         \fn node_ref::node_ref(const node_ref& other)
  43         \brief Creates a copy of the given node_ref object.
  44
  45         \param other the node_ref to be copied.
  46
  47         \since BeOS R3
  48 */
  49
  50
  51 /*!
  52         \name Operators
  53 */
  54
  55
  56 //! @{
  57
  58
  59 /*!
  60         \fn bool node_ref::operator==(const node_ref& other) const
  61         \brief Tests whether this node_ref and the supplied one are equal.
  62
  63         \param other The node_ref to be compared against.
  64
  65         \return \c true, if the objects are equal, \c false otherwise.
  66
  67         \since BeOS R3
  68 */
  69
  70
  71 /*!
  72         \fn bool node_ref::operator!=(const node_ref& other) const
  73         \brief Tests whether this node_ref and the supplied one are NOT equal.
  74
  75         \param other The node_ref to be compared against.
  76
  77         \return \c true, if the objects are \b NOT equal, \c false otherwise.
  78
  79         \since BeOS R3
  80 */
  81
  82
  83 /*!
  84         \fn bool node_ref::operator<(const node_ref& other) const
  85         \brief Tests whether this node_ref is less than the supplied one.
  86
  87         \param other The node_ref to be compared against.
  88
  89         \return \c true, if this node_ref is less than \a other,
  90                 \c false otherwise.
  91
  92         \since Haiku R1
  93 */
  94
  95
  96 /*!
  97         \fn node_ref& node_ref::operator=(const node_ref& other)
  98         \brief Makes this node ref a copy of the supplied one.
  99
 100         \param other The node_ref to be copied.
 101
 102         \return A reference to this object.
 103
 104         \since BeOS R3
 105 */
 106
 107
 108 //! @}
 109
 110
 111 /*!
 112         \var node_ref::device
 113         \brief The device number on which the node is located.
 114
 115         \since BeOS R3
 116 */
 117
 118
 119 /*!
 120         \var node_ref::node
 121         \brief The node's inode number.
 122
 123         \since BeOS R3
 124 */
 125
 126
 127 /*!
 128         \class BNode
 129         \ingroup storage
 130         \ingroup libbe
 131         \brief A BNode represents a chunk of data in the filesystem.
 132
 133         The BNode class provides an interface for manipulating the data and
 134         attributes belonging to filesystem entries. The BNode is unaware of the
 135         name that refers to it in the filesystem (i.e. its entry), instead, a
 136         BNode is concerned solely with the entry's data and attributes.
 137
 138         \since BeOS R3
 139 */
 140
 141
 142 /*!
 143         \fn BNode::BNode()
 144         \brief Creates an uninitialized BNode object.
 145
 146         \see SetTo()
 147
 148         \since BeOS R3
 149 */
 150
 151
 152 /*!
 153         \fn BNode::BNode(const entry_ref* ref)
 154         \brief Creates a BNode object and initializes it to the specified
 155                entry_ref.
 156
 157         \param ref The entry_ref referring to the node.
 158
 159         \since BeOS R3
 160 */
 161
 162
 163 /*!
 164         \fn BNode::BNode(const BEntry* entry)
 165         \brief Creates a BNode object and initializes it to the specified
 166                filesystem entry.
 167
 168         \param entry The BEntry referring to the node.
 169
 170         \since BeOS R3
 171 */
 172
 173
 174 /*!
 175         \fn BNode::BNode(const char* path)
 176         \brief Creates a BNode object and initializes it to the entry referred
 177                to by the specified path.
 178
 179         \param path The \a path referring to the node.
 180
 181         \since BeOS R3
 182 */
 183
 184
 185 /*!
 186         \fn BNode::BNode(const BDirectory* dir, const char* path)
 187         \brief Creates a BNode object and initializes it to the entry referred
 188                to by the specified path rooted in the specified directory.
 189
 190         \param dir The base BDirectory.
 191         \param path The \a path name relative to \a dir.
 192
 193         \since BeOS R3
 194 */
 195
 196
 197 /*!
 198         \fn BNode::BNode(const BNode& other)
 199         \brief Creates a copy of the given BNode.
 200
 201         \param other The BNode to be copied.
 202
 203         \since BeOS R3
 204 */
 205
 206
 207 /*!
 208         \fn BNode::~BNode()
 209         \brief Frees all resources associated with the BNode.
 210
 211         \since BeOS R3
 212 */
 213
 214
 215 /*!
 216         \fn status_t BNode::GetStat(struct stat* stat) const
 217         \brief Fills in the given stat structure with the <tt>stat()</tt>
 218                information for this object.
 219
 220         \param stat A pointer to a stat structure to be filled in.
 221
 222         \return \c B_OK on success or an error code otherwise.
 223         \retval B_OK Everything went fine.
 224         \retval B_BAD_VALUE: \c NULL \a stat.
 225
 226         \since Haiku R1
 227 */
 228
 229
 230 /*!
 231         \fn int BNode::Dup()
 232         \brief Gets the POSIX file descriptor referred to by this node.
 233
 234         Remember to call close() on the file descriptor when you're through
 235         with it.
 236
 237         \returns A valid file descriptor, or -1 if something went wrong.
 238
 239         \since Haiku R1
 240 */
 241
 242
 243 /*!
 244         \name Constructor Helpers
 245 */
 246
 247
 248 //! @{
 249
 250
 251 /*!
 252         \fn status_t BNode::InitCheck() const
 253         \brief Checks whether the object has been properly initialized or not.
 254
 255         \returns \c B_OK if the object has been properly initialized, or
 256                  \c B_NO_INIT otherwise.
 257
 258         \since BeOS R3
 259 */
 260
 261
 262 /*!
 263         \fn status_t BNode::SetTo(const entry_ref* ref)
 264         \brief Initializes the object to the specified entry_ref.
 265
 266         \param ref The entry_ref referring to the entry.
 267
 268         \return \c B_OK on success or an error code otherwise.
 269         \retval B_OK: Everything went fine.
 270         \retval B_BAD_VALUE: \a ref was \c NULL.
 271         \retval B_ENTRY_NOT_FOUND: The entry could not be found.
 272         \retval B_BUSY: The entry was locked.
 273
 274         \since BeOS R3
 275 */
 276
 277
 278 /*!
 279         \fn status_t BNode::SetTo(const BEntry* entry)
 280         \brief Initializes the object to the specified filesystem \a entry.
 281
 282         \param entry The BEntry representing the entry.
 283
 284         \return \c B_OK on success or an error code otherwise.
 285         \retval B_OK Everything went fine.
 286         \retval B_BAD_VALUE \a entry was \c NULL.
 287         \retval B_ENTRY_NOT_FOUND The \a entry could not be found.
 288         \retval B_BUSY The \a entry was locked.
 289
 290         \since BeOS R3
 291 */
 292
 293
 294 /*!
 295         \fn status_t BNode::SetTo(const char* path)
 296         \brief Initializes the object to the specified \a path.
 297
 298         \param path The entry's path name; \a path can be relative or absolute,
 299                and can contain "." and ".." elements. If path is relative, it uses
 300                the current working directory as the base directory.
 301
 302         \return \c B_OK on success or an error code otherwise.
 303         \retval B_OK Everything went fine.
 304         \retval B_BAD_VALUE \a path was \c NULL.
 305         \retval B_ENTRY_NOT_FOUND The entry could not be found.
 306         \retval B_BUSY The entry of was locked.
 307
 308         \since BeOS R3
 309 */
 310
 311
 312 /*!
 313         \fn status_t BNode::SetTo(const BDirectory* dir, const char* path)
 314         \brief Initializes the object to the entry referred by the
 315                specified \a path relative to the the specified directory.
 316
 317         \param dir The base BDirectory.
 318         \param path The path name relative to \a dir.
 319
 320         \return \c B_OK on success or an error code otherwise.
 321         \retval B_OK Everything went fine.
 322         \retval B_BAD_VALUE \a dir was \c NULL.
 323         \retval B_ENTRY_NOT_FOUND The entry could not be found.
 324         \retval B_BUSY The entry was locked.
 325
 326         \since BeOS R3
 327 */
 328
 329
 330 /*!
 331         \fn void BNode::Unset()
 332         \brief Returns the object to an uninitialized state.
 333
 334         \since BeOS R3
 335 */
 336
 337
 338 //! @}
 339
 340
 341 /*!
 342         \name Locking Methods
 343 */
 344
 345
 346 //! @{
 347
 348
 349 /*!
 350         \fn status_t BNode::Lock()
 351         \brief Attains an exclusive lock on the data referred to by this node
 352                so that it may not be modified by any other objects or methods.
 353
 354         \return \c B_OK on success or an error code otherwise.
 355         \retval B_OK Everything went fine.
 356         \retval B_FILE_ERROR The object is not initialized.
 357         \retval B_BUSY The node is already locked.
 358
 359         \since BeOS R3
 360 */
 361
 362
 363 /*!
 364         \fn status_t BNode::Unlock()
 365         \brief Unlocks the date referred to by this node.
 366
 367         \return \c B_OK on success or an error code otherwise.
 368         \retval B_OK Everything went fine.
 369         \retval B_FILE_ERROR The object is not initialized.
 370         \retval B_BAD_VALUE The node is not locked.
 371
 372         \since BeOS R3
 373 */
 374
 375
 376 /*!
 377         \fn status_t BNode::Sync()
 378         \brief Immediately performs any pending disk actions on the node.
 379
 380         \return \c B_OK on success or an error code otherwise.
 381         \retval B_OK Everything went fine.
 382         \retval B_FILE_ERROR Something went wrong.
 383
 384         \since BeOS R3
 385 */
 386
 387
 388 //! @}
 389
 390
 391 /*!
 392         \name Attribute Methods
 393 */
 394
 395
 396 //! @{
 397
 398
 399 /*!
 400         \fn ssize_t BNode::WriteAttr(const char* attr, type_code type,
 401                 off_t offset, const void* buffer, size_t length)
 402         \brief Writes data from a buffer to an attribute.
 403
 404         Write \a length bytes of data from \a buffer to the attribute specified
 405         by \a name after erasing any data that existed previously. The type
 406         specified by \a type \em is remembered, and may be queried with
 407         GetAttrInfo(). The value of \a offset is currently ignored.
 408
 409         \param attr The name of the attribute.
 410         \param type The type of the attribute.
 411         \param offset The index at which to write the data (currently ignored).
 412         \param buffer The buffer containing the data to be written.
 413         \param length The number of bytes to be written.
 414
 415         \return The number of bytes actually written.
 416         \retval B_BAD_VALUE \a attr or \a buffer was \c NULL.
 417         \retval B_FILE_ERROR The object was not initialized or the node it refers
 418                 to was read only.
 419         \retval B_NOT_ALLOWED The node resides on a read only volume.
 420         \retval B_DEVICE_FULL There was insufficient disk space to complete the
 421                 operation.
 422         \retval B_NO_MEMORY There was insufficient memory to complete the
 423                 operation.
 424
 425         \since BeOS R3
 426 */
 427
 428
 429 /*!
 430         \fn ssize_t BNode::ReadAttr(const char* attr, type_code type,
 431                 off_t offset, void* buffer, size_t length) const
 432         \brief Reads data from an attribute into \a buffer.
 433
 434         Reads \a length bytes of data from the attribute given by \a name into
 435         \a buffer. \a type and \a offset are currently ignored.
 436
 437         \param attr The name of the attribute.
 438         \param type The type of the attribute (currently ignored).
 439         \param offset The index from which to read the data (currently ignored).
 440         \param buffer The buffer for the data to be read.
 441         \param length The number of bytes to be read.
 442
 443         \return The number of bytes actually read.
 444         \retval B_BAD_VALUE \a attr or \a buffer was \c NULL.
 445         \retval B_FILE_ERROR The object was not initialized.
 446         \retval B_ENTRY_NOT_FOUND The node had no attribute \a attr.
 447
 448         \since BeOS R3
 449 */
 450
 451
 452 /*!
 453         \fn status_t BNode::RemoveAttr(const char* name)
 454         \brief Deletes the attribute given by \a name.
 455
 456         \param name The name of the attribute to remove.
 457
 458         \return \c B_OK on success or an error code otherwise.
 459         \retval B_OK Everything went fine.
 460         \retval B_BAD_VALUE \a name was \c NULL.
 461         \retval B_FILE_ERROR The object was not initialized or the node it
 462                 referred to was read-only.
 463         \retval B_ENTRY_NOT_FOUND The node had no attribute \a name.
 464         \retval B_NOT_ALLOWED The node resided on a read-only volume.
 465
 466         \since BeOS R3
 467 */
 468
 469
 470 /*!
 471         \fn status_t BNode::RenameAttr(const char* oldName, const char* newName)
 472         \brief Moves the attribute given by \a oldName to \a newName.
 473
 474         If \a newName already exists, the data is clobbered.
 475
 476         \param oldName The name of the attribute to be renamed.
 477         \param newName The new name for the attribute.
 478
 479         \return \c B_OK on success or an error code otherwise.
 480         \retval B_OK Everything went fine.
 481         \retval B_BAD_VALUE \a oldName or \a newName was \c NULL.
 482         \retval B_FILE_ERROR The object was not initialized or the node it
 483                 referred to was read only.
 484         \retval B_ENTRY_NOT_FOUND The node had no attribute \a oldName.
 485         \retval B_NOT_ALLOWED The node resided on a read-only volume.
 486
 487         \since BeOS R3
 488 */
 489
 490
 491 /*!
 492         \fn status_t BNode::GetAttrInfo(const char* name,
 493                 struct attr_info* info) const
 494         \brief Fills in the pre-allocated attr_info struct pointed to by \a info
 495                with information about the attribute specified by \a name.
 496
 497         \param name The name of the attribute.
 498         \param info The attr_info structure to be filled in.
 499
 500         \return \c B_OK on success or an error code otherwise.
 501         \retval B_OK Everything went fine.
 502         \retval B_BAD_VALUE \a name was \c NULL.
 503         \retval B_FILE_ERROR The object was not initialized.
 504         \retval B_ENTRY_NOT_FOUND The node had no attribute \a name.
 505
 506         \since BeOS R3
 507 */
 508
 509
 510 /*!
 511         \fn status_t BNode::GetNextAttrName(char* buffer)
 512         \brief Copies the name of the attribute into \c buffer and then advances
 513                the pointer to the next attribute.
 514
 515         The name of the node is first copied into \a buffer, which should be at
 516         least \c B_ATTR_NAME_LENGTH characters long. The copied node name is
 517         \0 terminated. Once the name is copied the attribute list pointer
 518         is advanced to the next attribute in the list. When GetNextAttrName()
 519         reaches the end of the list it returns \c B_ENTRY_NOT_FOUND.
 520
 521         \param buffer A buffer to copy the name of the attribute into.
 522
 523         \return \c B_OK on success or an error code otherwise.
 524         \retval B_OK The Attribute name was copied and there are more attribute
 525                 names to copy.
 526         \retval B_BAD_VALUE passed in \a buffer was \c NULL.
 527         \retval B_FILE_ERROR The object was not initialized.
 528         \retval B_ENTRY_NOT_FOUND There were no more attributes, the last attribute
 529                 name had already been copied.
 530
 531         \since BeOS R3
 532 */
 533
 534
 535 /*!
 536         \fn status_t BNode::RewindAttrs()
 537         \brief Resets the object's attribute pointer to the first attribute in the
 538                list.
 539
 540         \return \c B_OK on success or an error code otherwise.
 541         \retval B_OK Everything went fine.
 542         \retval B_FILE_ERROR Some other error occurred.
 543
 544         \since BeOS R3
 545 */
 546
 547
 548 /*!
 549         \fn status_t BNode::WriteAttrString(const char* name, const BString* data)
 550         \brief Writes the specified string to the specified attribute, clobbering
 551                any previous data.
 552
 553         \param name the name of the attribute.
 554         \param data the BString to be written to the attribute.
 555
 556         \return \c B_OK on success or an error code otherwise.
 557         \retval B_OK Everything went fine.
 558         \retval B_BAD_VALUE \a name or \a data was \c NULL.
 559         \retval B_FILE_ERROR The object was not initialized or the node it
 560                 referred to was read-only.
 561         \retval B_NOT_ALLOWED The node resided on a read-only volume.
 562         \retval B_DEVICE_FULL There was insufficient disk space to complete the
 563                 operation.
 564         \retval B_NO_MEMORY There was insufficient memory to complete the
 565                 operation.
 566
 567         \since Haiku R1
 568 */
 569
 570
 571 /*!
 572         \fn status_t BNode::ReadAttrString(const char* name, BString* result) const
 573         \brief Reads the data of the specified attribute into the pre-allocated
 574                \a result.
 575
 576         \param name the name of the attribute.
 577         \param result the BString to be set to the value of the attribute.
 578
 579         \return \c B_OK on success or an error code otherwise.
 580         \retval B_OK Everything went fine.
 581         \retval B_BAD_VALUE \a name or \a result was \c NULL.
 582         \retval B_FILE_ERROR The object was not initialized.
 583         \retval B_ENTRY_NOT_FOUND The node had no attribute \a attr.
 584
 585         \since Haiku R1
 586 */
 587
 588
 589 //! @}
 590
 591
 592 /*!
 593         \name Operators
 594 */
 595
 596
 597 //! @{
 598
 599
 600 /*!
 601         \fn BNode& BNode::operator=(const BNode& other)
 602         \brief Initializes the object as a copy of \a other.
 603
 604         \param other the BNode to be copied.
 605
 606         \returns A reference to this BNode object.
 607
 608         \since BeOS R3
 609 */
 610
 611
 612 /*!
 613         \fn bool BNode::operator==(const BNode &node) const
 614         \brief Tests whether this and the supplied BNode object are equal.
 615
 616         Two BNode objects are said to be equal if they're set to the same node,
 617         or if they're both unintialized
 618
 619         \param node The BNode to be compared against.
 620
 621         \return \c true, if the BNode objects are equal, \c false otherwise.
 622
 623         \since BeOS R3
 624 */
 625
 626
 627 /*!
 628         \fn bool BNode::operator!=(const BNode &node) const
 629         \brief Tests whether this and the supplied BNode object are not equal.
 630
 631         Two BNode objects are said to be equal if they're set to the same node,
 632         or if they're both unintialized.
 633
 634         \param node The BNode to be compared with
 635
 636         \return \c false, if the BNode objects are equal, \c true otherwise.
 637
 638         \since BeOS R3
 639 */
 640
 641
 642 //! @}