diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index a1a1e41373..7eb5b6d040 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -494,6 +494,7 @@ INPUT = . \ ../../headers/os/midi2 \ ../../headers/os/storage/AppFileInfo.h \ ../../headers/os/storage/FindDirectory.h \ + ../../headers/os/storage/Node.h \ ../../headers/os/support \ ../../headers/posix/syslog.h diff --git a/docs/user/book.dox b/docs/user/book.dox index d5d392e3ad..1b87f6d721 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -7,10 +7,10 @@ - \ref drivers - \ref interface | \link interface_intro \em Introduction \endlink - \ref locale | \link locale_intro \em Introduction \endlink - - \ref media | \link media_intro \em Introduction \endlink + - \ref media | \em Introduction - \ref midi1 - \ref midi2 | \link midi2_intro \em Introduction \endlink - - \ref storage | \link storage_intro \em Introduction \endlink + - \ref storage | \em Introduction - \ref support | \link support_intro \em Introduction \endlink \section notes General Notes and Information @@ -26,9 +26,11 @@ \defgroup drivers Drivers \defgroup interface Interface Kit \brief API for displaying a graphical user interface. + \defgroup media \defgroup midi2 MIDI 2 Kit \brief API for producing and consuming MIDI events. \defgroup libmidi2 (libmidi2.so) + \defgroup storage \defgroup support Support Kit \brief Collection of utility classes that are used throughout the API. \defgroup libbe (libbe.so) diff --git a/docs/user/storage/Node.dox b/docs/user/storage/Node.dox new file mode 100644 index 0000000000..861ac2dc94 --- /dev/null +++ b/docs/user/storage/Node.dox @@ -0,0 +1,634 @@ +/* + * Copyright 2002-2011, Haiku Inc. + * Distributed under the terms of the MIT License. + * + * Authors: + * Tyler Dauwalder, tylerdauwalder@users.sf.net + * John Scipione, jscipione@gmail.com + * Ingo Weinhold, bonefish@users.sf.net + * Corresponds to: + * /trunk/headers/os/app/Node.h rev 42803 + * /trunk/src/kits/app/Node.cpp rev 42803 + */ + + +/*! + \file Node.h + \brief Provides the BNode class and node_ref structure. +*/ + + +/*! + \struct node_ref + \brief Reference structure to a particular vnode on a device. +*/ + + +/*! + \fn node_ref::node_ref() + \brief Creates an uninitialized node_ref object. +*/ + + +/*! + \fn node_ref::node_ref(const node_ref &ref) + \brief Creates a copy of the given node_ref object. + + \param ref the node_ref to be copied. +*/ + + +/*! + \fn bool node_ref::operator==(const node_ref &ref) const + \brief Tests whether this node_ref and the supplied one are equal. + + \param ref the node_ref to be compared with. + + \return \c true, if the objects are equal, \c false otherwise. +*/ + + +/*! + \fn bool node_ref::operator!=(const node_ref &ref) const + \brief Tests whether this node_ref and the supplied one are not equal. + + \param ref the node_ref to be compared with. + + \return \c true, if the objects are \b not equal, \c false otherwise. +*/ + + +/*! + \fn node_ref& node_ref::operator=(const node_ref &ref) + \brief Makes this node ref a copy of the supplied one. + + \param ref the node_ref to be copied. + + \return a reference to this object. +*/ + + +/*! + \class BNode + \ingroup storage + \brief A BNode represents a chunk of data in the filesystem. + + The BNode class provides an interface for manipulating the data and + attributes belonging to filesystem entries. The BNode is unaware of the + name that refers to it in the filesystem (i.e. its entry), instead, a + BNode is concerned solely with the entry's data and attributes. +*/ + + +/*! + \var BNode::fFd + File descriptor for the given node. +*/ + + +/*! + \var BNode::fAttrFd + File descriptor for the attribute directory of the node. Initialized lazily. +*/ + + +/*! + \var BNode::fCStatus + The object's initialization status. +*/ + + +/*! + \fn BNode::BNode() + \brief Creates an uninitialized BNode object. +*/ + + +/*! + \fn BNode::BNode(const entry_ref *ref) + \brief Creates a BNode object and initializes it to the specified + entry_ref. + + \param ref the entry_ref referring to the entry. +*/ + + +/*! + \fn BNode::BNode(const BEntry *entry) + \brief Creates a BNode object and initializes it to the specified + filesystem entry. + + \param entry the BEntry representing the entry. +*/ + + +/*! + \fn BNode::BNode(const char *path) + \brief Creates a BNode object and initializes it to the entry referred + to by the specified path. + + \param path the path referring to the entry. +*/ + + +/*! + \fn BNode::BNode(const BDirectory *dir, const char *path) + \brief Creates a BNode object and initializes it to the entry referred + to by the specified path rooted in the specified directory. + + \param dir the BDirectory, relative to which the entry's path name is + given. + \param path the entry's path name relative to \a dir. +*/ + + +/*! + \fn BNode::BNode(const BNode &node) + \brief Creates a copy of the given BNode. + + \param node the BNode to be copied. +*/ + + +/*! + \fn BNode::~BNode() + \brief Frees all resources associated with the BNode. +*/ + + +/*! + \fn status_t BNode::InitCheck() const + \brief Checks whether the object has been properly initialized or not. + + \returns B_OK if the object has been properly initialized, or an error + code otherwise. +*/ + + +/*! + \fn status_t BNode::GetStat(struct stat *st) const + \brief Fills in the given stat structure with the stat() + information for this object. + + \param st a pointer to a stat structure to be filled in. + + \retval B_OK Everything went fine. + \retval B_BAD_VALUE: \c NULL \a st. +*/ + + +/*! + \fn int BNode::Dup() + \brief Gets the POSIX file descriptor referred to by this node. + + Remember to call close() on the file descriptor when you're through + with it. + + \returns a valid file descriptor, or -1 if something went wrong. +*/ + + +/*! + \name Assignment Methods +*/ + + +//! @{ + + +/*! + \fn BNode& BNode::operator=(const BNode &node) + \brief Initializes the object as a copy of the \a node. + + \param node the BNode to be copied. + + \returns a reference to this BNode object. +*/ + + +/*! + \fn status_t BNode::SetTo(const entry_ref *ref) + \brief Initializes the object to the specified entry_ref. + + \param ref the entry_ref referring to the entry. + + \retval B_OK: Everything went fine. + \retval B_BAD_VALUE: \c NULL \a ref. + \retval B_ENTRY_NOT_FOUND: The entry could not be found. + \retval B_BUSY: The entry is locked. +*/ + + +/*! + \fn status_t BNode::SetTo(const BEntry *entry) + \brief Initializes the object to the specified filesystem \a entry. + + \param entry the BEntry representing the entry. + + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \c NULL \a entry. + \retval B_ENTRY_NOT_FOUND The entry could not be found. + \retval B_BUSY The entry is locked. +*/ + + +/*! + \fn status_t BNode::SetTo(const BDirectory *dir, const char *path) + \brief Initializes the object to the entry referred by the + specified \a path relative to the the specified directory. + + \param dir the base BDirectory. + \param path the entry's path name relative to \a dir + + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \c NULL \a entry. + \retval B_ENTRY_NOT_FOUND The entry could not be found. + \retval B_BUSY The entry is locked. +*/ + + +/*! + \fn void BNode::Unset() + \brief Returns the object to an uninitialized state. +*/ + + +//! @} + + +/*! + \name Locking Methods +*/ + + +//! @{ + + +/*! + \fn status_t BNode::Lock() + \brief Attains an exclusive lock on the data referred to by this node + so that it may not be modified by any other objects or methods. + + \retval B_OK Everything went fine. + \retval B_FILE_ERROR The object is not initialized. + \retval B_BUSY The node is already locked. +*/ + + +/*! + \fn status_t BNode::Unlock() + \brief Unlocks the date referred to by this node. + + \retval B_OK Everything went fine. + \retval B_FILE_ERROR The object is not initialized. + \retval B_BAD_VALUE The node is not locked. +*/ + + +/*! + \fn status_t BNode::Sync() + \brief Immediately performs any pending disk actions on the node. + + \retval B_OK Everything went fine. + \retval B_FILE_ERROR Something went wrong. +*/ + + +//! @} + + +/*! + \name Attribute Methods +*/ + + +//! @{ + + +/*! + \fn ssize_t BNode::WriteAttr(const char *attr, type_code type, + off_t offset, const void *buffer, size_t len) + \brief Writes data from a buffer to an attribute. + + Write \a len bytes of data from \a buffer to the attribute specified + by \a name after erasing any data that existed previously. The type + specified by \a type \em is remembered, and may be queried with + GetAttrInfo(). The value of \a offset is currently ignored. + + \param attr the name of the attribute. + \param type the type of the attribute. + \param offset the index at which to write the data (currently ignored). + \param buffer the buffer containing the data to be written. + \param len the number of bytes to be written. + + \returns the number of bytes actually written. + \retval B_BAD_VALUE \a attr or \a buffer is \c NULL. + \retval B_FILE_ERROR The object is not initialized or the node it refers to + is read only. + \retval B_NOT_ALLOWED The node resides on a read only volume. + \retval B_DEVICE_FULL Insufficient disk space. + \retval B_NO_MEMORY Insufficient memory to complete the operation. +*/ + + +/*! + \fn ssize_t BNode::ReadAttr(const char *attr, type_code type, + off_t offset, void *buffer, size_t len) const + \brief Reads data from an attribute into \a buffer. + + Reads \a len bytes of data from the attribute given by \a name into + \a buffer. \a type and \a offset are currently ignored. + + \param attr the name of the attribute. + \param type the type of the attribute (currently ignored). + \param offset the index from which to read the data (currently ignored). + \param buffer the buffer for the data to be read. + \param len the number of bytes to be read. + + \returns the number of bytes actually read + \retval B_BAD_VALUE \a attr or \a buffer is \c NULL. + \retval B_FILE_ERROR The object is not initialized. + \retval B_ENTRY_NOT_FOUND The node has no attribute \a attr. +*/ + + +/*! + \fn status_t BNode::RemoveAttr(const char *name) + \brief Deletes the attribute given by \a name. + + \param name the name of the attribute to remove. + + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \a name is \c NULL. + \retval B_FILE_ERROR The object is not initialized or the node it + refers to read only. + \retval B_ENTRY_NOT_FOUND The node has no attribute \a name. + \retval B_NOT_ALLOWED The node resides on a read only volume. +*/ + + +/*! + \fn status_t BNode::RenameAttr(const char *oldname, const char *newname) + \brief Moves the attribute given by \a oldname to \a newname. + + If \a newname already exists, the data is clobbered. + + \param oldname the name of the attribute to be renamed. + \param newname the new name for the attribute. + + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \a oldname or \a newname is \c NULL. + \retval B_FILE_ERROR The object is not initialized or the node it + refers to is read only. + \retval B_ENTRY_NOT_FOUND The node has no attribute \a oldname. + \retval B_NOT_ALLOWED The node resides on a read only volume. +*/ + + +/*! + \fn status_t BNode::GetAttrInfo(const char *name, + struct attr_info *info) const + \brief Fills in the pre-allocated attr_info struct pointed to by \a info + with information about the attribute specified by \a name. + + \param name the name of the attribute + \param info the attr_info structure to be filled in + + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \a name is \c NULL. + \retval B_FILE_ERROR The object is not initialized. + \retval B_ENTRY_NOT_FOUND The node has no attribute \a name. +*/ + + +/*! + \fn status_t BNode::GetNextAttrName(char *buffer) + \brief Copies the name of the attribute into \c buffer and then advances + the pointer to the next attribute. + + The name of the node is first copied into \a buffer, which should be at + least \c B_ATTR_NAME_LENGTH characters long. The copied node name is + \c NUL terminated. Once the name is copied the attribute list pointer + is advanced to the next attribute in the list. When GetNextAttrName() + reaches the end of the list it returns \c B_ENTRY_NOT_FOUND. + + \param buffer A buffer to copy the name of the attribute into. + + \retval B_OK The Attribute name was copied and there are more attribute + names to copy. + \retval B_BAD_VALUE passed in \a buffer is \c NULL. + \retval B_FILE_ERROR The object is not initialized. + \retval B_ENTRY_NOT_FOUND There are no more attributes, the last attribute + name has already been copied. +*/ + + +/*! + \fn status_t BNode::RewindAttrs() + \brief Resets the object's attribute pointer to the first attribute in the + list. + + \retval B_OK Everything went fine. + \retval B_FILE_ERROR Some other error occurred. +*/ + + +/*! + \fn status_t BNode::WriteAttrString(const char *name, const BString *data) + \brief Writes the specified string to the specified attribute, clobbering + any previous data. + + \param name the name of the attribute. + \param data the BString to be written to the attribute. + + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \c NULL \a name or \a data + \retval B_FILE_ERROR The object is not initialized or the node it refers to + is read only. + \retval B_NOT_ALLOWED The node resides on a read only volume. + \retval B_DEVICE_FULL Insufficient disk space. + \retval B_NO_MEMORY Insufficient memory to complete the operation. +*/ + + +/*! + \fn status_t BNode::ReadAttrString(const char *name, BString *result) const + \brief Reads the data of the specified attribute into the pre-allocated + \a result. + + \param name the name of the attribute. + \param result the BString to be set to the value of the attribute. + + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \a name or \a result is \c NULL. + \retval B_FILE_ERROR The object is not initialized. + \retval B_ENTRY_NOT_FOUND The node has no attribute \a attr. +*/ + + +//! @} + + +/*! + \name Comparison Methods +*/ + + +//! @{ + + +/*! + \fn bool BNode::operator==(const BNode &node) const + \brief Tests whether this and the supplied BNode object are equal. + + Two BNode objects are said to be equal if they're set to the same node, + or if they're both \c B_NO_INIT. + + \param node the BNode to be compared with. + + \return \c true, if the BNode objects are equal, \c false otherwise. +*/ + + +/*! + \fn bool BNode::operator!=(const BNode &node) const + \brief Tests whether this and the supplied BNode object are not equal. + + Two BNode objects are said to be equal if they're set to the same node, + or if they're both \c B_NO_INIT. + + \param node the BNode to be compared with + + \return \c false, if the BNode objects are equal, \c true otherwise. +*/ + + +//! @} + + +/*! + \name Private Methods +*/ + + +//! @{ + + +/*! + \fn status_t BNode::set_fd(int fd) + \brief Sets the node's file descriptor. + + Used by each implementation (i.e. BNode, BFile, BDirectory, etc.) to set + the node's file descriptor. This allows each subclass to use the various + file-type specific system calls for opening file descriptors. + + \note This method calls close_fd() to close previously opened FDs. Thus + derived classes should take care to first call set_fd() and set + class specific resources freed in their close_fd() version + thereafter. + + \param fd the file descriptor this BNode should be set to (may be -1). + + \returns \c B_OK if everything went fine, or an error code if something + went wrong. +*/ + + +/*! + \fn void BNode::close_fd() + \brief Closes the node's file descriptor(s). + + To be implemented by subclasses to close the file descriptor using the + proper system call for the given file-type. This implementation calls + _kern_close(fFd) and also _kern_close(fAttrDir) if necessary. +*/ + + +/*! + \fn void BNode::set_status(status_t newStatus) + \brief Sets the BNode's status. + + To be used by derived classes instead of accessing the BNode's private + \c fCStatus member directly. + + \param newStatus the new value for the status variable. +*/ + + +/*! + \fn status_t BNode::_SetTo(int fd, const char *path, bool traverse) + \brief Initializes the BNode's file descriptor to the node referred to + by the given FD and path combo. + + \a path must either be \c NULL, an absolute or a relative path. + In the first case, \a fd must not be \c NULL; the node it refers to will + be opened. If absolute, \a fd is ignored. If relative and \a fd is >= 0, + it will be reckoned off the directory identified by \a fd, otherwise off + the current working directory. + + The method will first try to open the node with read and write permission. + If that fails due to a read-only FS or because the user has no write + permission for the node, it will re-try opening the node read-only. + + The \a fCStatus member will be set to the return value of this method. + + \param fd Either a directory FD or a value < 0. In the latter case \a path + must be specified. + \param path Either \a NULL in which case \a fd must be given, absolute, or + relative to the directory specified by \a fd (if given) or to the + current working directory. + \param traverse If the node identified by \a fd and \a path is a symlink + and \a traverse is \c true, the symlink will be resolved recursively. + + \returns \c B_OK if everything went fine, or an error code if something + went wrong. +*/ + + +/*! + \fn status_t BNode::_SetTo(const entry_ref *ref, bool traverse) + \brief Initializes the BNode's file descriptor to the node referred to + by the given entry_ref. + + The method will first try to open the node with read and write permission. + If that fails due to a read-only FS or because the user has no write + permission for the node, it will re-try opening the node read-only. + + The \a fCStatus member will be set to the return value of this method. + + \param ref An entry_ref identifying the node to be opened. + \param traverse If the node identified by \a ref is a symlink and + \a traverse is \c true, the symlink will be resolved recursively. + + \returns \c B_OK if everything went fine, or an error code if something + went wrong. +*/ + + +/*! + \fn status_t BNode::set_stat(struct stat &st, uint32 what) + \brief Modifies a certain setting for this node based on \a what and the + corresponding value in \a st. + + Inherited from and called by BStatable. + + \param st a stat structure containing the value to be set. + \param what specifies what setting to be modified. + + \returns \c B_OK if everything went fine, or an error code if something + went wrong. +*/ + + +/*! + \fn status_t BNode::InitAttrDir() + \brief Verifies that the BNode has been properly initialized, and then + (if necessary) opens the attribute directory on the node's file + descriptor, storing it in fAttrDir. + + \returns \c B_OK if everything went fine, or an error code if something + went wrong. +*/ + + +//! @} diff --git a/headers/os/storage/Node.h b/headers/os/storage/Node.h index 06f8ed4520..bb22e74fac 100644 --- a/headers/os/storage/Node.h +++ b/headers/os/storage/Node.h @@ -14,13 +14,6 @@ class BString; struct entry_ref; -//! Reference structure to a particular vnode on a particular device -/*! node_ref - A node reference. - - @author Tyler Dauwalder - @author Be Inc. - @version 0.0.0 -*/ struct node_ref { node_ref(); node_ref(const node_ref &ref); @@ -34,17 +27,6 @@ struct node_ref { }; -//! A BNode represents a chunk of data in the filesystem. -/*! The BNode class provides an interface for manipulating the data and attributes - belonging to filesystem entries. The BNode is unaware of the name that refers - to it in the filesystem (i.e. its entry); a BNode is solely concerned with - the entry's data and attributes. - - - @author Tyler Dauwalder - @version 0.0.0 - -*/ class BNode : public BStatable { public: BNode(); diff --git a/src/kits/storage/Node.cpp b/src/kits/storage/Node.cpp index 0def72e11b..1fc1fa730b 100644 --- a/src/kits/storage/Node.cpp +++ b/src/kits/storage/Node.cpp @@ -8,11 +8,6 @@ */ -/*! - \file Node.cpp - BNode implementation. -*/ - #include #include @@ -37,8 +32,6 @@ // #pragma mark - node_ref -/*! \brief Creates an uninitialized node_ref object. -*/ node_ref::node_ref() : device((dev_t)-1), node((ino_t)-1) @@ -46,9 +39,6 @@ node_ref::node_ref() } // copy constructor -/*! \brief Creates a copy of the given node_ref object. - \param ref the node_ref to be copied -*/ node_ref::node_ref(const node_ref &ref) : device((dev_t)-1), node((ino_t)-1) @@ -57,10 +47,6 @@ node_ref::node_ref(const node_ref &ref) } // == -/*! \brief Tests whether this node_ref and the supplied one are equal. - \param ref the node_ref to be compared with - \return \c true, if the objects are equal, \c false otherwise -*/ bool node_ref::operator==(const node_ref &ref) const { @@ -68,10 +54,6 @@ node_ref::operator==(const node_ref &ref) const } // != -/*! \brief Tests whether this node_ref and the supplied one are not equal. - \param ref the node_ref to be compared with - \return \c false, if the objects are equal, \c true otherwise -*/ bool node_ref::operator!=(const node_ref &ref) const { @@ -79,10 +61,6 @@ node_ref::operator!=(const node_ref &ref) const } // = -/*! \brief Makes this node ref a copy of the supplied one. - \param ref the node_ref to be copied - \return a reference to this object -*/ node_ref& node_ref::operator=(const node_ref &ref) { @@ -95,8 +73,6 @@ node_ref::operator=(const node_ref &ref) // #pragma mark - BNode -/*! \brief Creates an uninitialized BNode object -*/ BNode::BNode() : fFd(-1), fAttrFd(-1), @@ -105,10 +81,6 @@ BNode::BNode() } -/*! \brief Creates a BNode object and initializes it to the specified - entry_ref. - \param ref the entry_ref referring to the entry -*/ BNode::BNode(const entry_ref *ref) : fFd(-1), fAttrFd(-1), @@ -118,10 +90,6 @@ BNode::BNode(const entry_ref *ref) } -/*! \brief Creates a BNode object and initializes it to the specified - filesystem entry. - \param entry the BEntry representing the entry -*/ BNode::BNode(const BEntry *entry) : fFd(-1), fAttrFd(-1), @@ -131,10 +99,6 @@ BNode::BNode(const BEntry *entry) } -/*! \brief Creates a BNode object and initializes it to the entry referred - to by the specified path. - \param path the path referring to the entry -*/ BNode::BNode(const char *path) : fFd(-1), fAttrFd(-1), @@ -144,12 +108,6 @@ BNode::BNode(const char *path) } -/*! \brief Creates a BNode object and initializes it to the entry referred - to by the specified path rooted in the specified directory. - \param dir the BDirectory, relative to which the entry's path name is - given - \param path the entry's path name relative to \a dir -*/ BNode::BNode(const BDirectory *dir, const char *path) : fFd(-1), fAttrFd(-1), @@ -159,9 +117,6 @@ BNode::BNode(const BDirectory *dir, const char *path) } -/*! \brief Creates a copy of the given BNode. - \param node the BNode to be copied -*/ BNode::BNode(const BNode &node) : fFd(-1), fAttrFd(-1), @@ -171,19 +126,12 @@ BNode::BNode(const BNode &node) } -/*! \brief Frees all resources associated with the BNode. -*/ BNode::~BNode() { Unset(); } -/*! \brief Checks whether the object has been properly initialized or not. - \return - - \c B_OK, if the object has been properly initialized, - - an error code, otherwise. -*/ status_t BNode::InitCheck() const { @@ -191,25 +139,6 @@ BNode::InitCheck() const } -/*! \fn status_t BNode::GetStat(struct stat *st) const - \brief Fills in the given stat structure with \code stat() \endcode - information for this object. - \param st a pointer to a stat structure to be filled in - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a st. - - another error code, e.g., if the object wasn't properly initialized -*/ - - -/*! \brief Reinitializes the object to the specified entry_ref. - \param ref the entry_ref referring to the entry - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a ref. - - \c B_ENTRY_NOT_FOUND: The entry could not be found. - - \c B_BUSY: The entry is locked. -*/ status_t BNode::SetTo(const entry_ref *ref) { @@ -217,14 +146,6 @@ BNode::SetTo(const entry_ref *ref) } -/*! \brief Reinitializes the object to the specified filesystem entry. - \param entry the BEntry representing the entry - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a entry. - - \c B_ENTRY_NOT_FOUND: The entry could not be found. - - \c B_BUSY: The entry is locked. -*/ status_t BNode::SetTo(const BEntry *entry) { @@ -236,15 +157,6 @@ BNode::SetTo(const BEntry *entry) } -/*! \brief Reinitializes the object to the entry referred to by the specified - path. - \param path the path referring to the entry - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a path. - - \c B_ENTRY_NOT_FOUND: The entry could not be found. - - \c B_BUSY: The entry is locked. -*/ status_t BNode::SetTo(const char *path) { @@ -252,17 +164,6 @@ BNode::SetTo(const char *path) } -/*! \brief Reinitializes the object to the entry referred to by the specified - path rooted in the specified directory. - \param dir the BDirectory, relative to which the entry's path name is - given - \param path the entry's path name relative to \a dir - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a dir or \a path. - - \c B_ENTRY_NOT_FOUND: The entry could not be found. - - \c B_BUSY: The entry is locked. -*/ status_t BNode::SetTo(const BDirectory *dir, const char *path) { @@ -274,8 +175,6 @@ BNode::SetTo(const BDirectory *dir, const char *path) } -/*! \brief Returns the object to an uninitialized state. -*/ void BNode::Unset() { @@ -284,13 +183,6 @@ BNode::Unset() } -/*! \brief Attains an exclusive lock on the data referred to by this node, so - that it may not be modified by any other objects or methods. - \return - - \c B_OK: Everything went fine. - - \c B_FILE_ERROR: The object is not initialized. - - \c B_BUSY: The node is already locked. -*/ status_t BNode::Lock() { @@ -300,12 +192,6 @@ BNode::Lock() } -/*! \brief Unlocks the node. - \return - - \c B_OK: Everything went fine. - - \c B_FILE_ERROR: The object is not initialized. - - \c B_BAD_VALUE: The node is not locked. -*/ status_t BNode::Unlock() { @@ -315,11 +201,6 @@ BNode::Unlock() } -/*! \brief Immediately performs any pending disk actions on the node. - \return - - \c B_OK: Everything went fine. - - an error code, if something went wrong. -*/ status_t BNode::Sync() { @@ -327,26 +208,6 @@ BNode::Sync() } -/*! \brief Writes data from a buffer to an attribute. - Write the \a len bytes of data from \a buffer to - the attribute specified by \a name after erasing any data - that existed previously. The type specified by \a type \em is - remembered, and may be queried with GetAttrInfo(). The value of - \a offset is currently ignored. - \param attr the name of the attribute - \param type the type of the attribute - \param offset the index at which to write the data (currently ignored) - \param buffer the buffer containing the data to be written - \param len the number of bytes to be written - \return - - the number of bytes actually written - - \c B_BAD_VALUE: \c NULL \a attr or \a buffer - - \c B_FILE_ERROR: The object is not initialized or the node it refers to - is read only. - - \c B_NOT_ALLOWED: The node resides on a read only volume. - - \c B_DEVICE_FULL: Insufficient disk space. - - \c B_NO_MEMORY: Insufficient memory to complete the operation. -*/ ssize_t BNode::WriteAttr(const char *attr, type_code type, off_t offset, const void *buffer, size_t len) @@ -361,21 +222,6 @@ BNode::WriteAttr(const char *attr, type_code type, off_t offset, } -/*! \brief Reads data from an attribute into a buffer. - Reads the data of the attribute given by \a name into - the buffer specified by \a buffer with length specified - by \a len. \a type and \a offset are currently ignored. - \param attr the name of the attribute - \param type the type of the attribute (currently ignored) - \param offset the index from which to read the data (currently ignored) - \param buffer the buffer for the data to be read - \param len the number of bytes to be read - \return - - the number of bytes actually read - - \c B_BAD_VALUE: \c NULL \a attr or \a buffer - - \c B_FILE_ERROR: The object is not initialized. - - \c B_ENTRY_NOT_FOUND: The node has no attribute \a attr. -*/ ssize_t BNode::ReadAttr(const char *attr, type_code type, off_t offset, void *buffer, size_t len) const @@ -390,15 +236,6 @@ BNode::ReadAttr(const char *attr, type_code type, off_t offset, } -/*! \brief Deletes the attribute given by \a name. - \param name the name of the attribute - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a name - - \c B_FILE_ERROR: The object is not initialized or the node it refers to - is read only. - - \c B_ENTRY_NOT_FOUND: The node has no attribute \a name. - - \c B_NOT_ALLOWED: The node resides on a read only volume. -*/ status_t BNode::RemoveAttr(const char *name) { @@ -406,18 +243,6 @@ BNode::RemoveAttr(const char *name) } -/*! \brief Moves the attribute given by \a oldname to \a newname. - If \a newname already exists, the current data is clobbered. - \param oldname the name of the attribute to be renamed - \param newname the new name for the attribute - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a oldname or \a newname - - \c B_FILE_ERROR: The object is not initialized or the node it refers to - is read only. - - \c B_ENTRY_NOT_FOUND: The node has no attribute \a oldname. - - \c B_NOT_ALLOWED: The node resides on a read only volume. -*/ status_t BNode::RenameAttr(const char *oldname, const char *newname) { @@ -428,16 +253,6 @@ BNode::RenameAttr(const char *oldname, const char *newname) } -/*! \brief Fills in the pre-allocated attr_info struct pointed to by \a info - with useful information about the attribute specified by \a name. - \param name the name of the attribute - \param info the attr_info structure to be filled in - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a name - - \c B_FILE_ERROR: The object is not initialized. - - \c B_ENTRY_NOT_FOUND: The node has no attribute \a name. -*/ status_t BNode::GetAttrInfo(const char *name, struct attr_info *info) const { @@ -450,23 +265,6 @@ BNode::GetAttrInfo(const char *name, struct attr_info *info) const } -/*! \brief Returns the next attribute in the node's list of attributes. - Every BNode maintains a pointer to its list of attributes. - GetNextAttrName() retrieves the name of the attribute that the pointer is - currently pointing to, and then bumps the pointer to the next attribute. - The name is copied into the buffer, which should be at least - B_ATTR_NAME_LENGTH characters long. The copied name is NULL-terminated. - When you've asked for every name in the list, GetNextAttrName() - returns \c B_ENTRY_NOT_FOUND. - \param buffer the buffer the name of the next attribute shall be stored in - (must be at least \c B_ATTR_NAME_LENGTH bytes long) - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a buffer. - - \c B_FILE_ERROR: The object is not initialized. - - \c B_ENTRY_NOT_FOUND: There are no more attributes, the last attribute - name has already been returned. -*/ status_t BNode::GetNextAttrName(char *buffer) { @@ -489,12 +287,6 @@ BNode::GetNextAttrName(char *buffer) } -/*! \brief Resets the object's attribute pointer to the first attribute in the - list. - \return - - \c B_OK: Everything went fine. - - \c B_FILE_ERROR: Some error occured. -*/ status_t BNode::RewindAttrs() { @@ -505,18 +297,6 @@ BNode::RewindAttrs() } -/*! Writes the specified string to the specified attribute, clobbering any - previous data. - \param name the name of the attribute - \param data the BString to be written to the attribute - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a name or \a data - - \c B_FILE_ERROR: The object is not initialized or the node it refers to - is read only. - - \c B_NOT_ALLOWED: The node resides on a read only volume. - - \c B_DEVICE_FULL: Insufficient disk space. - - \c B_NO_MEMORY: Insufficient memory to complete the operation. -*/ status_t BNode::WriteAttrString(const char *name, const BString *data) { @@ -532,16 +312,6 @@ BNode::WriteAttrString(const char *name, const BString *data) } -/*! \brief Reads the data of the specified attribute into the pre-allocated - \a result. - \param name the name of the attribute - \param result the BString to be set to the value of the attribute - \return - - \c B_OK: Everything went fine. - - \c B_BAD_VALUE: \c NULL \a name or \a result - - \c B_FILE_ERROR: The object is not initialized. - - \c B_ENTRY_NOT_FOUND: The node has no attribute \a attr. -*/ status_t BNode::ReadAttrString(const char *name, BString *result) const { @@ -577,10 +347,6 @@ BNode::ReadAttrString(const char *name, BString *result) const } -/*! \brief Reinitializes the object as a copy of the \a node. - \param node the BNode to be copied - \return a reference to this BNode object. -*/ BNode& BNode::operator=(const BNode &node) { @@ -598,12 +364,6 @@ BNode::operator=(const BNode &node) } -/*! Tests whether this and the supplied BNode object are equal. - Two BNode objects are said to be equal if they're set to the same node, - or if they're both \c B_NO_INIT. - \param node the BNode to be compared with - \return \c true, if the BNode objects are equal, \c false otherwise -*/ bool BNode::operator==(const BNode &node) const { @@ -622,12 +382,6 @@ BNode::operator==(const BNode &node) const } -/*! Tests whether this and the supplied BNode object are not equal. - Two BNode objects are said to be equal if they're set to the same node, - or if they're both \c B_NO_INIT. - \param node the BNode to be compared with - \return \c false, if the BNode objects are equal, \c true otherwise -*/ bool BNode::operator!=(const BNode &node) const { @@ -635,11 +389,6 @@ BNode::operator!=(const BNode &node) const } -/*! \brief Returns a POSIX file descriptor to the node this object refers to. - Remember to call close() on the file descriptor when you're through with - it. - \return a valid file descriptor, or -1, if something went wrong. -*/ int BNode::Dup() { @@ -657,17 +406,6 @@ void BNode::_RudeNode5() { } void BNode::_RudeNode6() { } -/*! \brief Sets the node's file descriptor. - Used by each implementation (i.e. BNode, BFile, BDirectory, etc.) to set - the node's file descriptor. This allows each subclass to use the various - file-type specific system calls for opening file descriptors. - \param fd the file descriptor this BNode should be set to (may be -1) - \return \c B_OK, if everything went fine, an error code otherwise. - \note This method calls close_fd() to close previously opened FDs. Thus - derived classes should take care to first call set_fd() and set - class specific resources freed in their close_fd() version - thereafter. -*/ status_t BNode::set_fd(int fd) { @@ -678,11 +416,6 @@ BNode::set_fd(int fd) } -/*! \brief Closes the node's file descriptor(s). - To be implemented by subclasses to close the file descriptor using the - proper system call for the given file-type. This implementation calls - _kern_close(fFd) and also _kern_close(fAttrDir) if necessary. -*/ void BNode::close_fd() { @@ -697,11 +430,6 @@ BNode::close_fd() } -/*! \brief Sets the BNode's status. - To be used by derived classes instead of accessing the BNode's private - \c fCStatus member directly. - \param newStatus the new value for the status variable. -*/ void BNode::set_status(status_t newStatus) { @@ -709,30 +437,6 @@ BNode::set_status(status_t newStatus) } -/*! \brief Initializes the BNode's file descriptor to the node referred to - by the given FD and path combo. - - \a path must either be \c NULL, an absolute or a relative path. - In the first case, \a fd must not be \c NULL; the node it refers to will - be opened. If absolute, \a fd is ignored. If relative and \a fd is >= 0, - it will be reckoned off the directory identified by \a fd, otherwise off - the current working directory. - - The method will first try to open the node with read and write permission. - If that fails due to a read-only FS or because the user has no write - permission for the node, it will re-try opening the node read-only. - - The \a fCStatus member will be set to the return value of this method. - - \param fd Either a directory FD or a value < 0. In the latter case \a path - must be specified. - \param path Either \a NULL in which case \a fd must be given, absolute, or - relative to the directory specified by \a fd (if given) or to the - current working directory. - \param traverse If the node identified by \a fd and \a path is a symlink - and \a traverse is \c true, the symlink will be resolved recursively. - \return \c B_OK, if everything went fine, another error code otherwise. -*/ status_t BNode::_SetTo(int fd, const char *path, bool traverse) { @@ -752,20 +456,6 @@ BNode::_SetTo(int fd, const char *path, bool traverse) } -/*! \brief Initializes the BNode's file descriptor to the node referred to - by the given entry_ref. - - The method will first try to open the node with read and write permission. - If that fails due to a read-only FS or because the user has no write - permission for the node, it will re-try opening the node read-only. - - The \a fCStatus member will be set to the return value of this method. - - \param ref An entry_ref identifying the node to be opened. - \param traverse If the node identified by \a ref is a symlink - and \a traverse is \c true, the symlink will be resolved recursively. - \return \c B_OK, if everything went fine, another error code otherwise. -*/ status_t BNode::_SetTo(const entry_ref *ref, bool traverse) { @@ -787,13 +477,6 @@ BNode::_SetTo(const entry_ref *ref, bool traverse) } -/*! \brief Modifies a certain setting for this node based on \a what and the - corresponding value in \a st. - Inherited from and called by BStatable. - \param st a stat structure containing the value to be set - \param what specifies what setting to be modified - \return \c B_OK if everything went fine, an error code otherwise. -*/ status_t BNode::set_stat(struct stat &st, uint32 what) { @@ -805,11 +488,6 @@ BNode::set_stat(struct stat &st, uint32 what) } -/*! \brief Verifies that the BNode has been properly initialized, and then - (if necessary) opens the attribute directory on the node's file - descriptor, storing it in fAttrDir. - \return \c B_OK if everything went fine, an error code otherwise. -*/ status_t BNode::InitAttrDir() { @@ -847,19 +525,6 @@ BNode::_GetStat(struct stat_beos *st) const } -/*! \var BNode::fFd - File descriptor for the given node. -*/ - -/*! \var BNode::fAttrFd - File descriptor for the attribute directory of the node. Initialized lazily. -*/ - -/*! \var BNode::fCStatus - The object's initialization status. -*/ - - // #pragma mark - symbol versions