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
+89
-59
@@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright 2009-2012 Haiku, Inc. All rights reserved.
|
||||
* Copyright 2009-2014 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
@@ -8,8 +8,8 @@
|
||||
* Ingo Weinhold, [email protected]
|
||||
*
|
||||
* Corresponds to:
|
||||
* headers/os/storage/File.h hrev45060
|
||||
* src/kits/storage/File.cpp hrev45060
|
||||
* headers/os/storage/File.h hrev47402
|
||||
* src/kits/storage/File.cpp hrev47402
|
||||
*/
|
||||
|
||||
|
||||
@@ -33,6 +33,8 @@
|
||||
Symbolic links are automatically transversed by opening a BFile.
|
||||
The node that the BFile ends up opening will be the file or directory
|
||||
that the link points to, not the symbolic link file itself.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -47,6 +49,8 @@
|
||||
- SetTo(const char* path, uint32 openMode)
|
||||
- SetTo(const BDirectory* dir, const char* path, uint32 openMode)
|
||||
- operator=(const BFile &file)
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -57,57 +61,67 @@
|
||||
If \a file is uninitialized, the newly constructed BFile will be too.
|
||||
|
||||
\param file The BFile object to be copied.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BFile::BFile(const entry_ref* ref, uint32 openMode)
|
||||
\brief Creates a BFile and initializes it to the file referred to by
|
||||
the supplied entry_ref and according to the specified open mode.
|
||||
the supplied entry_ref and according to the specified open mode.
|
||||
|
||||
\param ref The entry_ref referring to the file.
|
||||
\param openMode The mode in which the file should be opened.
|
||||
|
||||
\see SetTo(const entry_ref* ref, uint32 openMode)
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BFile::BFile(const BEntry* entry, uint32 openMode)
|
||||
\brief Creates a BFile and initializes it to the file referred to by
|
||||
the supplied BEntry and according to the specified open mode.
|
||||
the supplied BEntry and according to the specified open mode.
|
||||
|
||||
\param entry The BEntry referring to the file.
|
||||
\param openMode The mode in which the file should be opened.
|
||||
|
||||
\see SetTo(const BEntry* entry, uint32 openMode)
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BFile::BFile(const char* path, uint32 openMode)
|
||||
\brief Creates a BFile and initializes it to the file referred to by
|
||||
the supplied path name and according to the specified open mode.
|
||||
the supplied path name and according to the specified open mode.
|
||||
|
||||
\param path The file's path name.
|
||||
\param openMode The mode in which the file should be opened.
|
||||
|
||||
\see SetTo(const char* path, uint32 openMode)
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BFile::BFile(const BDirectory *dir, const char* path, uint32 openMode)
|
||||
\brief Creates a BFile and initializes it to the file referred to by
|
||||
the supplied path name relative to the specified BDirectory and
|
||||
according to the specified open mode.
|
||||
the supplied path name relative to the specified BDirectory and
|
||||
according to the specified open mode.
|
||||
|
||||
\param dir The BDirectory, relative to which the file's path name is
|
||||
given.
|
||||
given.
|
||||
\param path The file's path name relative to \a dir.
|
||||
\param openMode The mode in which the file should be opened.
|
||||
|
||||
\see SetTo(const BDirectory* dir, const char* path, uint32 openMode)
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -116,27 +130,30 @@
|
||||
\brief Destroys the BFile object and frees all allocated resources.
|
||||
|
||||
If the file is properly initialized, the file descriptor is closed.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BFile::SetTo(const entry_ref* ref, uint32 openMode)
|
||||
\brief Re-initializes the BFile to the file referred to by the
|
||||
supplied entry_ref and according to the specified open mode.
|
||||
supplied entry_ref and according to the specified open mode.
|
||||
|
||||
\param ref The entry_ref referring to the file.
|
||||
\param openMode The mode in which the file should be opened
|
||||
\a openMode must be a bitwise or of exactly one of the flags.
|
||||
- \c B_READ_ONLY: The file is opened read only.
|
||||
- \c B_WRITE_ONLY: The file is opened write only.
|
||||
- \c B_READ_WRITE: The file is opened for random read/write access.
|
||||
and any number of the flags
|
||||
- \c B_CREATE_FILE: A new file will be created, if it does not already
|
||||
exist.
|
||||
- \c B_FAIL_IF_EXISTS: If the file does already exist and
|
||||
\c B_CREATE_FILE is set, SetTo() fails.
|
||||
- \c B_ERASE_FILE: An already existing file is truncated to zero size.
|
||||
- \c B_OPEN_AT_END: Seek() to the end of the file after opening.
|
||||
\a openMode must be a bitwise or of exactly one of the flags.
|
||||
- \c B_READ_ONLY: The file is opened read only.
|
||||
- \c B_WRITE_ONLY: The file is opened write only.
|
||||
- \c B_READ_WRITE: The file is opened for random read/write access.
|
||||
and any number of the flags
|
||||
- \c B_CREATE_FILE: A new file will be created, if it does not
|
||||
already exist.
|
||||
- \c B_FAIL_IF_EXISTS: If the file does already exist and
|
||||
\c B_CREATE_FILE is set, SetTo() fails.
|
||||
- \c B_ERASE_FILE: An already existing file is truncated to zero
|
||||
size.
|
||||
- \c B_OPEN_AT_END: Seek() to the end of the file after opening.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
@@ -149,13 +166,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 BFile::SetTo(const BEntry* entry, uint32 openMode)
|
||||
\brief Re-initializes the BFile to the file referred to by the
|
||||
supplied BEntry and according to the specified open mode.
|
||||
supplied BEntry and according to the specified open mode.
|
||||
|
||||
\param entry the BEntry referring to the file
|
||||
\param openMode the mode in which the file should be opened
|
||||
@@ -173,14 +192,16 @@
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\todo Implemented using SetTo(entry_ref*, uint32). Check, if necessary
|
||||
to re-implement!
|
||||
to re-implement!
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BFile::SetTo(const char* path, uint32 openMode)
|
||||
\brief Re-initializes the BFile to the file referred to by the
|
||||
supplied path name and according to the specified open mode.
|
||||
supplied path name and according to the specified open mode.
|
||||
|
||||
\param path The file's path name.
|
||||
\param openMode The mode in which the file should be opened.
|
||||
@@ -196,19 +217,20 @@
|
||||
\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 BFile::SetTo(const BDirectory* dir, const char* path,
|
||||
uint32 openMode)
|
||||
uint32 openMode)
|
||||
\brief Re-initializes the BFile to the file referred to by the
|
||||
supplied path name relative to the specified BDirectory and
|
||||
according to the specified open mode.
|
||||
supplied path name relative to the specified BDirectory and
|
||||
according to the specified open mode.
|
||||
|
||||
\param dir The BDirectory, relative to which the file's path name is
|
||||
given.
|
||||
given.
|
||||
\param path The file's path name relative to \a dir.
|
||||
\param openMode The mode in which the file should be opened.
|
||||
|
||||
@@ -225,7 +247,9 @@
|
||||
\retval B_NO_MORE_FDS The application has run out of file descriptors.
|
||||
|
||||
\todo Implemented using SetTo(BEntry*, uint32). Check, if necessary
|
||||
to re-implement!
|
||||
to re-implement!
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -237,6 +261,8 @@
|
||||
- \c true, if the BFile has been initialized properly and the file has
|
||||
been been opened for reading,
|
||||
- \c false, otherwise.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -248,6 +274,8 @@
|
||||
- \c true, if the BFile has been initialized properly and the file has
|
||||
been opened for writing,
|
||||
- \c false, otherwise.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -259,20 +287,24 @@
|
||||
\param size The number of bytes that shall be read.
|
||||
|
||||
\returns The number of bytes read or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn ssize_t BFile::ReadAt(off_t location, void* buffer, size_t size)
|
||||
\brief Reads a number of bytes from a certain position within the file
|
||||
into a buffer.
|
||||
into a buffer.
|
||||
|
||||
\param location The position (in bytes) within the file from which the
|
||||
data shall be read.
|
||||
data shall be read.
|
||||
\param buffer The buffer the data from the file shall be written to.
|
||||
\param size The number of bytes that shall be read.
|
||||
|
||||
\returns The number of bytes read or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -284,20 +316,24 @@
|
||||
\param size The number of bytes that shall be written.
|
||||
|
||||
\returns The number of bytes actually written or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn ssize_t BFile::WriteAt(off_t location, const void* buffer, size_t size)
|
||||
\brief \brief Writes a number of bytes from a buffer at a certain position
|
||||
into the file.
|
||||
\brief Writes a number of bytes from a buffer at a certain position
|
||||
into the file.
|
||||
|
||||
\param location The position (in bytes) within the file at which the data
|
||||
shall be written.
|
||||
shall be written.
|
||||
\param buffer The buffer containing the data to be written to the file.
|
||||
\param size The number of bytes that shall be written.
|
||||
|
||||
\returns The number of bytes actually written or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -311,16 +347,18 @@
|
||||
or Write() invocations will be undefined.
|
||||
|
||||
\param offset New read/write position, depending on \a seekMode relative
|
||||
to the beginning or the end of the file or the current position.
|
||||
to the beginning or the end of the file or the current position.
|
||||
\param seekMode
|
||||
- \c SEEK_SET: move relative to the beginning of the file
|
||||
- \c SEEK_CUR: move relative to the current position
|
||||
- \c SEEK_END: move relative to the end of the file
|
||||
- \c SEEK_SET: move relative to the beginning of the file.
|
||||
- \c SEEK_CUR: move relative to the current position.
|
||||
- \c SEEK_END: move relative to the end of the file.
|
||||
|
||||
\returns The new read/write position relative to the beginning of the
|
||||
file or an error code.
|
||||
file or an error code.
|
||||
\retval B_ERROR Trying to seek before the beginning of the file.
|
||||
\retval B_FILE_ERROR The file is not properly initialized.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -329,9 +367,11 @@
|
||||
\brief Gets the current read/write position within the file.
|
||||
|
||||
\returns The current read/write position relative to the beginning of the
|
||||
file or an error code.
|
||||
file or an error code.
|
||||
\retval B_ERROR After a Seek() before the beginning of the file.
|
||||
\retval B_FILE_ERROR The file has not been initialized.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -344,15 +384,17 @@
|
||||
truncated.
|
||||
|
||||
\note There's no problem with setting the size of a BFile opened in
|
||||
\c B_READ_ONLY mode, unless the file resides on a read only volume.
|
||||
\c B_READ_ONLY mode, unless the file resides on a read only volume.
|
||||
|
||||
\param size The new file size.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NOT_ALLOWED Trying to set the size of a file on a read only
|
||||
volume.
|
||||
volume.
|
||||
\retval B_DEVICE_FULL There's not enough space left on the volume.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -365,6 +407,8 @@
|
||||
\returns A status code.
|
||||
|
||||
\see BStatable::GetSize()
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -378,20 +422,6 @@
|
||||
\param file The original BFile to assign from.
|
||||
|
||||
\returns A reference to the assigned BFile.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn int BFile::get_fd() const
|
||||
\brief Gets the file descriptor of the BFile.
|
||||
|
||||
To be used instead of accessing the BNode's private \c fFd member directly.
|
||||
|
||||
\returns The file descriptor, or -1 if not properly initialized.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn void BFile::close_fd()
|
||||
\brief Overrides BNode::close_fd() for binary compatibility with BeOS R5.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user