Documentation updates for Storage Kit classes
* Added \since to each method and parameter. * Whitespace cleanup. * Some other minor cleanups and updates.
This commit is contained in:
John Scipione
+128
-62
@@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright 2011 Haiku, Inc. All rights reserved.
|
||||
* Copyright 2011-2014 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
@@ -9,8 +9,8 @@
|
||||
* John Scipione, [email protected]
|
||||
*
|
||||
* Corresponds to:
|
||||
* headers/os/storage/Directory.h hrev43528
|
||||
* src/kits/storage/Directory.cpp hrev43528
|
||||
* headers/os/storage/Directory.h hrev47402
|
||||
* src/kits/storage/Directory.cpp hrev47402
|
||||
*/
|
||||
|
||||
|
||||
@@ -27,12 +27,16 @@
|
||||
\ingroup storage
|
||||
\ingroup libbe
|
||||
\brief A directory in the file system.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BDirectory::BDirectory()
|
||||
\brief Creates an uninitialized BDirectory object.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -41,52 +45,64 @@
|
||||
\brief Creates a copy of the supplied BDirectory object.
|
||||
|
||||
\param dir The BDirectory object to be copied.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BDirectory::BDirectory(const entry_ref* ref)
|
||||
\brief Creates a BDirectory and initializes it to the directory referred
|
||||
to by the supplied entry_ref.
|
||||
to by the supplied entry_ref.
|
||||
|
||||
\param ref The entry_ref that refers to the directory.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BDirectory::BDirectory(const node_ref* nref)
|
||||
\brief Creates a BDirectory and initializes it to the directory referred
|
||||
to by the supplied node_ref.
|
||||
to by the supplied node_ref.
|
||||
|
||||
\param nref The node_ref that refers to the directory.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BDirectory::BDirectory(const BEntry* entry)
|
||||
\brief Creates a BDirectory and initializes it to the directory referred
|
||||
to by the supplied BEntry.
|
||||
to by the supplied BEntry.
|
||||
|
||||
\param entry The BEntry that refers to the directory.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BDirectory::BDirectory(const char* path)
|
||||
\brief Creates a BDirectory and initializes it to the directory referred
|
||||
to by the supplied \a path name.
|
||||
to by the supplied \a path name.
|
||||
|
||||
\param path The \a path name of the directory.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BDirectory::BDirectory(const BDirectory* dir, const char* path)
|
||||
\brief Creates a BDirectory and initializes it to the directory referred
|
||||
to by the supplied path name relative to the specified BDirectory.
|
||||
to by the supplied path name relative to the specified BDirectory.
|
||||
|
||||
\param dir The base BDirectory object.
|
||||
\param path The \a path of the directory relative to \a dir
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -96,13 +112,15 @@
|
||||
|
||||
If the BDirectory is properly initialized, the directory's file descriptor
|
||||
is closed.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BDirectory::SetTo(const entry_ref* ref)
|
||||
\brief Re-initializes the BDirectory to the directory referred to by the
|
||||
supplied entry_ref.
|
||||
supplied entry_ref.
|
||||
|
||||
\param ref The entry_ref referring to the directory.
|
||||
|
||||
@@ -116,13 +134,15 @@
|
||||
\retval B_BUSY A node was busy.
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BDirectory::SetTo(const node_ref* nref)
|
||||
\brief Re-initializes the BDirectory to the directory referred to by the
|
||||
supplied node_ref.
|
||||
supplied node_ref.
|
||||
|
||||
\param nref The node_ref referring to the directory.
|
||||
|
||||
@@ -136,13 +156,15 @@
|
||||
\retval B_BUSY A node was busy.
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BDirectory::SetTo(const BEntry* entry)
|
||||
\brief Re-initializes the BDirectory to the directory referred to by the
|
||||
supplied BEntry.
|
||||
supplied BEntry.
|
||||
|
||||
\param entry The BEntry referring to the directory.
|
||||
|
||||
@@ -156,13 +178,15 @@
|
||||
\retval B_BUSY A node was busy.
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BDirectory::SetTo(const char* path)
|
||||
\brief Re-initializes the BDirectory to the directory referred to by the
|
||||
supplied path name.
|
||||
supplied path name.
|
||||
|
||||
\param path The directory's \a path name.
|
||||
|
||||
@@ -178,13 +202,15 @@
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BDirectory::SetTo(const BDirectory* dir, const char* path)
|
||||
\brief Re-initializes the BDirectory to the directory referred to by the
|
||||
supplied path name relative to the specified BDirectory.
|
||||
supplied path name relative to the specified BDirectory.
|
||||
|
||||
\param dir The base directory.
|
||||
\param path The directory path name relative to \a dir.
|
||||
@@ -201,13 +227,15 @@
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BDirectory::GetEntry(BEntry* entry) const
|
||||
\brief Gets a BEntry object referring to the directory. If the
|
||||
initialization of \a entry fails, it is Unset().
|
||||
initialization of \a entry fails, it is Unset().
|
||||
|
||||
\param entry A pointer to the \a entry that will refer to the directory.
|
||||
|
||||
@@ -221,6 +249,8 @@
|
||||
\retval B_BUSY A node was busy.
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -229,7 +259,9 @@
|
||||
\brief Returns whether the directory is the root directory of a volume.
|
||||
|
||||
\returns \c true if the BDirectory is properly initialized and represents
|
||||
a root directory of a volume, \c false otherwise.
|
||||
a root directory of a volume, \c false otherwise.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -237,18 +269,18 @@
|
||||
\fn status_t BDirectory::FindEntry(const char* path, BEntry* entry,
|
||||
bool traverse) const
|
||||
\brief Finds an entry referred to by a path relative to the directory
|
||||
represented by this BDirectory.
|
||||
represented by this BDirectory.
|
||||
|
||||
\a path may represent an absolute path. If the BDirectory is not properly
|
||||
initialized then the entry is relative to the current directory. If the
|
||||
entry couldn't be found, \a entry is Unset().
|
||||
|
||||
\note The functionality of this method differs from
|
||||
BEntry::SetTo(BDirectory *, const char *, bool) in that it doesn't
|
||||
require the entry to exist, whereas this method does.
|
||||
BEntry::SetTo(BDirectory *, const char *, bool) in that it doesn't
|
||||
require the entry to exist, whereas this method does.
|
||||
|
||||
\param path The entry's \a path name. May be relative to this directory
|
||||
or an absolute path.
|
||||
or an absolute path.
|
||||
\param entry A pointer to a BEntry to be initialized with the found entry.
|
||||
\param traverse Whether or not to follow a symbolic link.
|
||||
|
||||
@@ -266,69 +298,77 @@
|
||||
\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
|
||||
|
||||
\sa BEntry::SetTo(BDirectory *, const char *, bool)
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn bool BDirectory::Contains(const char* path, int32 nodeFlags) const
|
||||
\brief Returns whether or not this directory or any of its subdirectories
|
||||
at any level contain the entry referred to by the supplied path name.
|
||||
at any level contain the entry referred to by the supplied path
|
||||
name.
|
||||
|
||||
Only entries that match the node flavor specified by \a nodeFlags are
|
||||
considered.
|
||||
|
||||
If the BDirectory is not properly initialized, the method returns \c false.
|
||||
A non-absolute path is considered relative to the current directory.
|
||||
If the BDirectory is not properly initialized, the method returns
|
||||
\c false. A non-absolute path is considered relative to the current
|
||||
directory.
|
||||
|
||||
\note R5's implementation always returns \c true given an absolute path
|
||||
or an unitialized directory. This implementation is not compatible
|
||||
with that behavior. Instead it converts the path into a BEntry and
|
||||
passes it to the other version of Contains().
|
||||
\note BeOS R5's implementation always returns \c true given an absolute
|
||||
path or an initialized directory. This implementation is not
|
||||
compatible with that behavior. Instead it converts the path into
|
||||
a BEntry and passes it to the other version of Contains().
|
||||
|
||||
\param path The entry's \a path name. May be relative to this directory
|
||||
or may be an absolute \a path.
|
||||
or may be an absolute \a path.
|
||||
\param nodeFlags Any of the following:
|
||||
- \c B_FILE_NODE: The entry must be a file.
|
||||
- \c B_DIRECTORY_NODE: The entry must be a directory.
|
||||
- \c B_SYMLINK_NODE: The entry must be a symbolic link.
|
||||
- \c B_ANY_NODE: The entry may be of any kind.
|
||||
- \c B_FILE_NODE: The entry must be a file.
|
||||
- \c B_DIRECTORY_NODE: The entry must be a directory.
|
||||
- \c B_SYMLINK_NODE: The entry must be a symbolic link.
|
||||
- \c B_ANY_NODE: The entry may be of any kind.
|
||||
|
||||
\returns \c true if the entry exists and its kind does match \a nodeFlags
|
||||
and the BDirectory is properly initialized and does contain the entry
|
||||
at any level, \c false otherwise.
|
||||
and the BDirectory is properly initialized and does contain the
|
||||
entry at any level, \c false otherwise.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn bool BDirectory::Contains(const BEntry* entry, int32 nodeFlags) const
|
||||
\brief Returns whether or not this directory or any of its subdirectories
|
||||
at any level contain the entry referred to by the supplied BEntry.
|
||||
|
||||
at any level contain the entry referred to by the supplied BEntry.
|
||||
|
||||
Only entries that match the node flavor specified by \a nodeFlags are
|
||||
considered.
|
||||
|
||||
\note If the paths are identical, this method returns \c true to stay
|
||||
consistent with BeOS 5.
|
||||
consistent with BeOS 5.
|
||||
|
||||
\param entry a BEntry referring to the entry
|
||||
\param nodeFlags Any of the following:
|
||||
- \c B_FILE_NODE: The entry must be a file.
|
||||
- \c B_DIRECTORY_NODE: The entry must be a directory.
|
||||
- \c B_SYMLINK_NODE: The entry must be a symbolic link.
|
||||
- \c B_ANY_NODE: The entry may be of any kind.
|
||||
- \c B_FILE_NODE: The entry must be a file.
|
||||
- \c B_DIRECTORY_NODE: The entry must be a directory.
|
||||
- \c B_SYMLINK_NODE: The entry must be a symbolic link.
|
||||
- \c B_ANY_NODE: The entry may be of any kind.
|
||||
|
||||
\returns \c true if the BDirectory is properly initialized and the
|
||||
entry of the matching kind was found, \c false otherwise.
|
||||
entry of the matching kind was found, \c false otherwise.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BDirectory::GetStatFor(const char* path, struct stat* st) const
|
||||
\brief Returns the stat structure of the entry referred to by the supplied
|
||||
path name.
|
||||
path name.
|
||||
|
||||
\param path The entry's path name. May be relative to this directory or
|
||||
absolute, or \c NULL to get the directories stat info.
|
||||
absolute, or \c NULL to get the directories stat info.
|
||||
\param st A pointer to the stat structure to be filled in by this method.
|
||||
|
||||
\returns A status code.
|
||||
@@ -343,6 +383,8 @@
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -353,7 +395,7 @@
|
||||
Unlike GetNextDirents() this method ignores "." and "..".
|
||||
|
||||
\note The iterator used by this method is the same one used by
|
||||
GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
|
||||
GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
|
||||
|
||||
\param entry A pointer to a BEntry to be initialized to the found entry
|
||||
\param traverse Specifies whether or not to follow a symbolic link.
|
||||
@@ -368,6 +410,8 @@
|
||||
\retval B_BUSY A node was busy.
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -378,10 +422,10 @@
|
||||
Unlike GetNextDirents() this method ignores "." and "..".
|
||||
|
||||
\note The iterator used be this method is the same one used by
|
||||
GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
|
||||
GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
|
||||
|
||||
\param ref A pointer to an entry_ref to be filled in with the data
|
||||
from the found entry.
|
||||
from the found entry.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
@@ -393,27 +437,31 @@
|
||||
\retval B_BUSY A node was busy.
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn int32 BDirectory::GetNextDirents(dirent* buf, size_t bufSize, int32 count)
|
||||
\fn int32 BDirectory::GetNextDirents(dirent* buf, size_t bufSize,
|
||||
int32 count)
|
||||
\brief Returns the next entries of the BDirectory object as a pointer
|
||||
to dirent structures.
|
||||
to dirent structures.
|
||||
|
||||
Unlike GetNextEntry() and GetNextRef(), this method returns also
|
||||
the entries "." and "..".
|
||||
|
||||
\note The iterator used by this method is the same one used by
|
||||
GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
|
||||
GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
|
||||
|
||||
\param buf A pointer to a buffer filled with dirent structures containing
|
||||
the found entries.
|
||||
the found entries.
|
||||
\param bufSize The size of \a buf.
|
||||
\param count The maximum number of entries to be returned.
|
||||
|
||||
\returns The number of dirent structures stored in the buffer, 0 when
|
||||
there are no more entries to be returned or a status code on error.
|
||||
there are no more entries to be returned or a status code on
|
||||
error.
|
||||
\retval B_BAD_VALUE \c NULL \a buf.
|
||||
\retval B_PERMISSION_DENIED Directory permissions didn't allow operation.
|
||||
\retval B_NO_MEMORY Insufficient memory for operation.
|
||||
@@ -422,6 +470,8 @@
|
||||
\retval B_BUSY A node was busy.
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -442,6 +492,8 @@
|
||||
\sa BDirectory::GetNextRef()
|
||||
\sa BDirectory::GetNextDirents()
|
||||
\sa BDirectory::CountEntries()
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -454,7 +506,7 @@
|
||||
the entries and Rewind()s again. The entries "." and ".." are not counted.
|
||||
|
||||
\returns The number of entries in the directory (not counting "." and
|
||||
"..") or a status code on error.
|
||||
"..") or a status code on error.
|
||||
\retval B_PERMISSION_DENIED Directory permissions didn't allow operation.
|
||||
\retval B_NO_MEMORY Insufficient memory for operation.
|
||||
\retval B_LINK_LIMIT Indicates a cyclic loop within the file system.
|
||||
@@ -466,6 +518,8 @@
|
||||
\sa BDirectory::GetNextRef()
|
||||
\sa BDirectory::GetNextDirents()
|
||||
\sa BDirectory::Rewind()
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -477,9 +531,9 @@
|
||||
an error status code.
|
||||
|
||||
\param path The new path name of the directory. May be a relative
|
||||
path to this directory or an absolute path.
|
||||
path to this directory or an absolute path.
|
||||
\param dir A pointer to a BDirectory to be initialized to the newly
|
||||
created directory. May be \c NULL.
|
||||
created directory. May be \c NULL.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
@@ -492,6 +546,8 @@
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_FILE_EXISTS An entry with that name does already exist.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -506,9 +562,9 @@
|
||||
mode.
|
||||
|
||||
\param path The new file's path name. May be relative to this
|
||||
directory or an absolute path.
|
||||
directory or an absolute path.
|
||||
\param file A pointer to a BFile to be initialized to the newly
|
||||
created file. May be \c NULL.
|
||||
created file. May be \c NULL.
|
||||
\param failIfExists Whether or not to fail if the file already exists.
|
||||
|
||||
\returns A status code.
|
||||
@@ -521,10 +577,12 @@
|
||||
\retval B_BUSY A node was busy.
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_FILE_EXISTS A file with that name does already exist and
|
||||
\c true has been passed for \a failIfExists.
|
||||
\c true has been passed for \a failIfExists.
|
||||
\retval B_IS_A_DIRECTORY A directory with the supplied name already
|
||||
exists.
|
||||
exists.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -536,10 +594,10 @@
|
||||
This method fails if an entry with the supplied name already exists.
|
||||
|
||||
\param path the new symbolic link's path name. May be relative to this
|
||||
directory or absolute.
|
||||
directory or absolute.
|
||||
\param linkToPath the path the symbolic link shall point to.
|
||||
\param link a pointer to a BSymLink to be initialized to the newly
|
||||
created symbolic link. May be \c NULL.
|
||||
created symbolic link. May be \c NULL.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
@@ -552,6 +610,8 @@
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_FILE_EXISTS An entry with that name does already exist.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -566,6 +626,8 @@
|
||||
\param dir The original BDirectory object.
|
||||
|
||||
\returns A reference to this BDirectory object.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -577,6 +639,8 @@
|
||||
member directly.
|
||||
|
||||
\returns the file descriptor, or -1 if not properly initialized.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
@@ -586,7 +650,7 @@
|
||||
|
||||
\param path The directory path name.
|
||||
\param mode A permission specification, which shall be used for the
|
||||
newly created directories.
|
||||
newly created directories.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
@@ -598,6 +662,8 @@
|
||||
\retval B_BUSY A node was busy.
|
||||
\retval B_FILE_ERROR A general file error.
|
||||
\retval B_NOT_A_DIRECTORY An entry other than a directory with that name
|
||||
already exists.
|
||||
already exists.
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user