[Haiku-commits] r29787 - haiku/trunk/docs/user/drivers
bonefish at BerliOS
bonefish at mail.berlios.de
Sun Mar 29 19:17:56 CEST 2009
Author: bonefish
Date: 2009-03-29 19:17:55 +0200 (Sun, 29 Mar 2009)
New Revision: 29787
ViewCVS: http://svn.berlios.de/viewcvs/haiku?rev=29787&view=rev
Modified:
haiku/trunk/docs/user/drivers/fs_interface.dox
Log:
* Updated to current FS interface.
* Fixed and completed several function documentations. There's still quite
a bit missing.
Modified: haiku/trunk/docs/user/drivers/fs_interface.dox
===================================================================
--- haiku/trunk/docs/user/drivers/fs_interface.dox 2009-03-29 17:14:52 UTC (rev 29786)
+++ haiku/trunk/docs/user/drivers/fs_interface.dox 2009-03-29 17:17:55 UTC (rev 29787)
@@ -8,7 +8,7 @@
* Axel Dörfler <axeld at pinc-software.de>
*
* Corresponds to:
- * /trunk/headers/os/drivers/fs_interface.h rev 21568
+ * /trunk/headers/os/drivers/fs_interface.h rev 29781
*/
/*!
@@ -21,6 +21,8 @@
*/
///// write_stat_mask //////
+// TODO: These have been superseded by the B_STAT_* flags in <NodeMonitor.h>.
+// Move the documentation there!
/*!
\enum write_stat_mask
@@ -65,11 +67,22 @@
\brief The 'creation time' should be updated.
*/
+/*!
+ \def B_STAT_SIZE_INSECURE
+ \brief Flag for the fs_vnode_ops::write_stat hook indicating that the FS
+ is allowed not to clear the additional space when enlarging a file.
+
+ This flag was added because BFS doesn't support sparse files. It will be
+ phased out, when it does.
+/*
+
+
///// FS_WRITE_FSINFO_NAME /////
/*!
\def FS_WRITE_FSINFO_NAME
- \brief Passed to file_system_module_info::write_fs_info().
+ \brief Passed to fs_volume_ops::write_fs_info() to indicate that the name
+ of the volume shall be changed.
*/
///// file_io_vec /////
@@ -101,6 +114,26 @@
\code "file_systems/myfs" B_CURRENT_FS_API_VERSION \endcode
*/
+
+///// B_VNODE_PUBLISH_REMOVED /////
+
+/*!
+ \def B_VNODE_PUBLISH_REMOVED
+ \brief Flag for publish_vnode() and fs_vnode_ops::create_special_node()
+ indicating that the node shall be published in removed state (i.e. no
+ entry refers to it).
+*/
+
+///// B_VNODE_DONT_CREATE_SPECIAL_SUB_NODE /////
+
+/*!
+ \def B_VNODE_DONT_CREATE_SPECIAL_SUB_NODE
+ \brief Flag for publish_vnode() and fs_volume_ops::get_vnode()
+ indicating that no subnodes shall be created for the node to publish
+ the node shall be published.
+*/
+
+
///// file_system_module_info /////
@@ -127,8 +160,8 @@
\var const char *file_system_module_info::pretty_name
\brief A NULL-terminated string with a 'pretty' name for you file system.
- Note, if a system wide disk device type constant exists for your file system,
- it should equal this identifier.
+ Note, if a system wide disk device type constant exists for your file
+ system, it should equal this identifier.
*/
//! @}
@@ -172,42 +205,204 @@
//! @{
/*!
- \fn status_t (*file_system_module_info::mount)(ino_t id, const char *device,
- uint32 flags, const char *args, fs_volume *_fs, ino_t *_rootVnodeID)
+ \fn status_t (*file_system_module_info::mount)(fs_volume *volume,
+ const char *device, uint32 flags, const char *args,
+ ino_t *_rootVnodeID)
+
\brief Mount a volume according to the specified parameters.
Invoked by the VFS when it has been requested to mount the volume. The FS is
supposed to perform whatever one-time initialization is necessary for the
volume. It is required to create a volume handle for the volume and pass it
- back in \a _fs. Moreover it must invoke publish_vnode() for the root node
- of the volume and pass the ID of the volume back in \a _rootVnodeID.
+ back in \a volume->private_volume and set \a volume->ops to the operation
+ vector for the volume. Moreover it must invoke publish_vnode() for the root
+ node of the volume and pass the ID of the volume back in \a _rootVnodeID.
A disk-based FS will need to check whether \a device is not \c NULL, open
- it, and analyze whether the device or image file actually represents a volume
- of that FS type.
+ it, and analyze whether the device or image file actually represents a
+ volume of that FS type.
If mounting the volume fails for whatever reason, the hook must return an
error code other than \c B_OK. In this case all resources allocated by the
hook must be freed before returning. If and only if \c B_OK is returned, the
unmount() hook will be invoked at a later point when unmounting the volume.
- \param id The ID of the volume to be mounted. It should be saved in the FS's
- volume private data (volume handle).
+ \param volume Object created by the VFS to represent the volume. Its
+ \c private_volume and \c ops members must be set by the hooks. All other
+ members are read-only for the FS.
\param device The path to the device (or image file) representing the volume
to be mounted. Can be \c NULL.
\param flags Flags:
- \c B_MOUNT_READ_ONLY: Mount the volume read-only.
\param args Null-terminated string in driver settings format, containing FS
specific parameters.
- \param _fs Pointer to a pre-allocated variable the volume handle shall be
- written to.
\param _rootVnodeID Pointer to a pre-allocated variable the ID of the
volume's root directory shall be written to.
\return \c B_OK if everything went fine, another error code otherwise.
*/
+//! @}
+
/*!
- \fn status_t (*file_system_module_info::unmount)(fs_volume fs)
+ \name Capability Querying
+*/
+
+//! @{
+
+/*!
+ \fn bool (*file_system_module_info::supports_defragmenting)(partition_data
+ *partition, bool *whileMounted)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::supports_repairing)(partition_data *partition,
+ bool checkOnly, bool *whileMounted)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::supports_resizing)(partition_data *partition,
+ bool *whileMounted)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::supports_moving)(partition_data *partition, bool *isNoOp)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::supports_setting_content_name)(partition_data *partition,
+ bool *whileMounted)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::supports_setting_content_parameters)(partition_data *partition,
+ bool *whileMounted)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::supports_initializing)(partition_data *partition)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::validate_resize)(partition_data *partition, off_t *size)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::validate_move)(partition_data *partition, off_t *start)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::validate_set_content_name)(partition_data *partition,
+ char *name)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::validate_set_content_parameters)(partition_data *partition,
+ const char *parameters)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn bool (*file_system_module_info::validate_initialize)(partition_data *partition, char *name,
+ const char *parameters)
+ \brief Undocumented. TODO.
+*/
+
+//! @}
+
+/*!
+ \name Shadow Partition Modification
+*/
+
+//! @{
+
+/*!
+ \fn status_t (*file_system_module_info::shadow_changed)(partition_data *partition,
+ uint32 operation)
+ \brief Undocumented. TODO.
+*/
+
+//! @}
+
+/*!
+ \name Special Operations
+*/
+
+//! @{
+
+/*!
+ \fn status_t (*file_system_module_info::defragment)(int fd, partition_id partition,
+ disk_job_id job)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn status_t (*file_system_module_info::repair)(int fd, partition_id partition, bool checkOnly,
+ disk_job_id job)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn status_t (*file_system_module_info::resize)(int fd, partition_id partition, off_t size,
+ disk_job_id job)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn status_t (*file_system_module_info::move)(int fd, partition_id partition, off_t offset,
+ disk_job_id job)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn status_t (*file_system_module_info::set_content_name)(int fd, partition_id partition,
+ const char *name, disk_job_id job)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn status_t (*file_system_module_info::set_content_parameters)(int fd, partition_id partition,
+ const char *parameters, disk_job_id job)
+ \brief Undocumented. TODO.
+*/
+
+/*!
+ \fn status_t (*file_system_module_info::initialize)(const char *partition, const char *name,
+ const char *parameters, disk_job_id job)
+ \brief Undocumented. TODO.
+*/
+
+//! @}
+
+
+///// fs_volume_ops /////
+
+
+/*!
+ \struct fs_volume_ops
+ \brief Operations vector for a volume.
+
+ See the \ref fs_modules "introduction to file system modules" for an
+ introduction to writing file systems.
+*/
+
+/*!
+ \name General Operations
+*/
+
+//! @{
+
+/*!
+ \fn status_t (*fs_volume_ops::unmount)(fs_volume *volume)
\brief Unmounts the given volume.
Invoked by the VFS when it is asked to unmount the volume. The function must
@@ -215,13 +410,13 @@
handle. Although the mount() hook called publish_vnode() for the root node
of the volume, unmount() must not invoke put_vnode().
- \param fs The volume handle.
+ \param volume The volume object.
\return \c B_OK if everything went fine, another error code otherwise. The
error code will be ignored, though.
*/
/*!
- \fn status_t (*file_system_module_info::read_fs_info)(fs_volume fs,
+ \fn status_t (*fs_volume_ops::read_fs_info)(fs_volume *volume,
struct fs_info *info)
\brief Retrieves general information about the volume.
@@ -234,17 +429,15 @@
- \c io_size: Preferred size of the buffers passed to read() and write().
- \c total_blocks: Total number of blocks the volume contains.
- \c free_blocks: Number of free blocks on the volume.
- - \c total_nodes: Maximal number of nodes the volume can contain. If there is
- no such limitation use \c LONGLONG_MAX.
+ - \c total_nodes: Maximal number of nodes the volume can contain. If there
+ is no such limitation use \c LONGLONG_MAX.
- \c free_nodes: Number of additional nodes the volume could contain. If
there is no such limitation use \c LONGLONG_MAX.
- - \c device_name: The name of the device or image file containing the volume.
- Non-disk-based FSs shall fill in an empty string.
- \c volume_name: The name of the volume.
The other values are filled in by the VFS.
- \param fs The volume handle.
+ \param volume The volume object.
\param info Pointer to a pre-allocated variable the FS info shall be written
to.
\return \c B_OK if everything went fine, another error code otherwise. The
@@ -252,25 +445,24 @@
*/
/*!
- \fn status_t (*file_system_module_info::write_fs_info)(fs_volume fs,
+ \fn status_t (*fs_volume_ops::write_fs_info)(fs_volume *volume,
const struct fs_info *info, uint32 mask)
\brief Update filesystem information on the volume.
- You are requested to update certain information on the volume \a fs. The
+ You are requested to update certain information on the given volume. The
supplied \a info contains the new values filled in for the \a mask.
Currently, the only possible mask is solely the \c FS_WRITE_FSINFO_NAME,
which asks you to update the volume name represented by the value
\c volume_name in the \c fs_info struct.
- \param fs The cookie your filesystem supplied to the volume that should be
- updated.
+ \param volume The volume object.
\param info The structure that contains the new data.
\param mask The values of the \a info that need to be updated.
\return \c B_OK if everything went fine, if not, one of the error codes.
*/
/*!
- \fn status_t (*file_system_module_info::sync)(fs_volume fs)
+ \fn status_t (*fs_volume_ops::sync)(fs_volume *volume)
\brief Synchronize the cached data with the contents of the disk.
The VFS layer sometimes wants you to synchronize any cached values with the
@@ -279,63 +471,333 @@
This currently only happens when the POSIX sync() function is invoked, for
example via the "sync" command line tool.
- \param fs The cookie your filesystem supplied to the volume that should be
- updated.
+ \param volume The volume object.
*/
+/*!
+ \fn status_t (*fs_volume_ops::get_vnode)(fs_volume *volume, ino_t id,
+ fs_vnode *vnode, int *_type, uint32 *_flags, bool reenter)
+ \brief Creates the private data handle to be associated with the node
+ referred to by \a id.
+
+ Invoked by the VFS when it creates the vnode for the respective node.
+ When the VFS no longer needs the vnode in memory (for example when
+ memory is becoming tight), it will your file_system_module_info::put_vnode(),
+ or file_system_module_info::remove_vnode() in case the vnode has been
+ marked removed.
+
+ The hook has to initialize \a vnode->private_node with its handle created
+ for the node and \a vnode->ops with the operation vector for the node.
+
+ \param volume The volume object.
+ \param id The ID of the node.
+ \param vnode Pointer to a node object to be initialized.
+ \param reenter \c true if the hook invocation has been caused by the FS
+ itself, e.g. by invoking ::get_vnode().
+ \return \c B_OK if everything went fine, another error code otherwise.
+*/
+
//! @}
/*!
+ \name Index Directory and Operation
+*/
+
+//! @{
+
+/*!
+ \fn status_t (*fs_volume_ops::open_index_dir)(fs_volume *volume,
+ void **_cookie)
+ \brief Open the list of an indices as a directory.
+
+ See \ref concepts "Generic Concepts" on directories and iterators.
+ Basically, the VFS uses the same way of traversing through indeces as it
+ traverses through a directory.
+
+ \param volume The volume object.
+ \param[out] _cookie Pointer where the file system can store a directory
+ cookie if the index directory is succesfully opened.
+ \return \c B_OK if everything went fine, another error code otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::close_index_dir)(fs_volume *volume,
+ void *cookie)
+ \brief Close a 'directory' of indices.
+
+ Note that you should free the cookie in the free_index_dir_cookie() call.
+
+ \param volume The volume object.
+ \param cookie The cookie associated with this 'directory'.
+ \return B_OK if everything went fine, another error code otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::free_index_dir_cookie)(fs_volume *volume,
+ void *cookie)
+ \brief Free the \a cookie to the index 'directory'.
+
+ \param volume The volume object.
+ \param cookie The cookie that should be freed.
+ \return B_OK if everything went fine, another error code otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::read_index_dir)(fs_volume *volume,
+ void *cookie, struct dirent *buffer, size_t bufferSize,
+ uint32 *_num)
+ \brief Read the next one or more index entries.
+
+ This method should perform the same task as fs_vnode_ops::read_dir(),
+ except that the '.' and the '..' entries don't have to be present.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::rewind_index_dir)(fs_volume *volume,
+ void *cookie)
+ \brief Reset the index directory cookie to the first entry of the directory.
+
+ \param volume The volume object.
+ \param cookie The directory cookie as returned by open_index_dir().
+ \return \c B_OK if everything went fine, another error code otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::create_index)(fs_volume *volume,
+ const char *name, uint32 type, uint32 flags)
+ \brief Create a new index.
+
+ \param volume The volume object.
+ \param name The name of the new index.
+ \param type The type of index. BFS implements the following types:
+ - \c B_INT32_TYPE
+ - \c B_UINT32_TYPE
+ - \c B_INT64_TYPE
+ - \c B_UINT64_TYPE
+ - \c B_FLOAT_TYPE
+ - \c B_DOUBLE_TYPE
+ - \c B_STRING_TYPE
+ - \c B_MIME_STRING_TYPE
+ \param flags There are currently no extra flags specified. This parameter
+ can be ignored.
+ \return You should return \c B_OK if the creation succeeded, or return an
+ error otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::remove_index)(fs_volume *volume,
+ const char *name)
+ \brief Remove the index with \a name.
+
+ \param volume The volume object.
+ \param name The name of the index to be removed.
+ \return You should return \c B_OK if the creation succeeded, or return an
+ error otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::read_index_stat)(fs_volume *volume,
+ const char *name, struct stat *stat)
+ \brief Read the \a stat of the index with a name.
+
+ \param volume The volume object.
+ \param name The name of the index to be queried.
+ \param stat A pointer to a structure where you should store the values.
+ \return You should return \c B_OK if the creation succeeded, or return an
+ error otherwise.
+*/
+
+//! @}
+
+/*!
+ \name Query Operations
+*/
+
+//! @{
+
+/*!
+ \fn status_t (*fs_volume_ops::open_query)(fs_volume *volume,
+ const char *query, uint32 flags, port_id port, uint32 token,
+ void **_cookie)
+ \brief Open a query as a 'directory'.
+
+ TODO: query expressions should be documented and also the format for sending
+ query updates over the port should be updated.
+
+ See \ref concepts "Generic Concepts" on directories and iterators.
+ Basically, the VFS uses the same way of traversing through indices as it
+ traverses through a directory.
+
+ \param volume The volume object.
+ \param query The string that represents a query.
+ \param flags Any combination of none or more of these flags:
+ - \c #B_LIVE_QUERY The query is live. When a query is live, it is
+ constantly updated using the \a port. The FS must invoke the functions
+ notify_query_entry_created() and notify_query_entry_removed() whenever
+ an entry starts respectively stops to match the query predicate.
+ - \c #B_QUERY_NON_INDEXED Normally at least one of the attributes used
+ in the query string should be indexed. If none is, this hook is
+ allowed to fail, unless this flag is specified. Usually an
+ implementation will simply add a wildcard match for any complete
+ index ("name", "last_modified", or "size") to the query expression.
+ \param port The id of the port where updates need to be sent to in case the
+ query is live.
+ \param token A token that should be attached to the messages sent over the
+ \a port.
+ \param[out] _cookie The cookie that will be used as 'directory' to traverse
+ through the results of the query.
+ \return You should return \c B_OK if the creation succeeded, or return an
+ error otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::close_query)(fs_volume *volume, void *cookie)
+ \brief Close a 'directory' of a query.
+
+ Note that you should free the cookie in the free_query_cookie() call.
+
+ \param volume The volume object.
+ \param cookie The cookie that refers to this query.
+ \return You should return \c B_OK if the creation succeeded, or return an
+ error otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::free_query_cookie)(fs_volume *volume,
+ void *cookie)
+ \brief Free a cookie of a query.
+
+ \param volume The volume object.
+ \param cookie The cookie that should be freed.
+ \return You should return \c B_OK if the creation succeeded, or return an
+ error otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::read_query)(fs_volume *volume, void *cookie,
+ struct dirent *buffer, size_t bufferSize, uint32 *_num)
+ \brief Read the next one or more entries matching the query.
+
+ This hook function works pretty much the same way as
+ fs_vnode_ops::read_dir(), with the difference that it doesn't read the
+ entries of a directory, but the entries matching the given query. Unlike the
+ fs_vnode_ops::read_dir() hook, this hook also has to fill in the
+ dirent::d_pino field.
+
+ \param volume The volume object.
+ \param cookie The query cookie as returned by open_query().
+ \param buffer Pointer to a pre-allocated buffer the directory entries shall
+ be written to.
+ \param bufferSize The size of \a buffer in bytes.
+ \param _num Pointer to a pre-allocated variable, when invoked, containing
+ the number of entries to be read, and into which the number of entries
+ actually read shall be written.
+ \return \c B_OK if everything went fine, another error code otherwise.
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::rewind_query)(fs_volume *volume, void *cookie)
+ \brief Reset the query cookie to the first entry of the results.
+
+ \param volume The volume object.
+ \param cookie The query cookie as returned by open_query().
+ \return \c B_OK if everything went fine, another error code otherwise.
+*/
+
+//! @}
+
+/*!
+ \name FS Layer Operations
+*/
+
+//! @{
+
+/*!
+ \fn status_t (*fs_volume_ops::all_layers_mounted)(fs_volume *volume)
+ \brief TODO: Document!
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::create_sub_vnode)(fs_volume *volume, ino_t id,
+ fs_vnode *vnode)
+ \brief TODO: Document!
+*/
+
+/*!
+ \fn status_t (*fs_volume_ops::delete_sub_vnode)(fs_volume *volume,
+ fs_vnode *vnode)
+ \brief TODO: Document!
+*/
+
+//! @}
+
+
+///// fs_vnode_ops /////
+
+
+/*!
+ \struct fs_vnode_ops
+ \brief Operations vector for a node.
+
+ See the \ref fs_modules "introduction to file system modules" for an
+ introduction to writing file systems.
+*/
+
+/*!
\name VNode Operations
*/
//! @{
/*!
- \fn status_t (*file_system_module_info::lookup)(fs_volume fs, fs_vnode dir,
- const char *name, ino_t *_id, int *_type)
+ \fn status_t (*fs_vnode_ops::lookup)(fs_volume *volume, fs_vnode *dir,
+ const char *name, ino_t *_id)
\brief Looks up the node a directory entry refers to.
The VFS uses this hook to resolve path names to vnodes. It is used quite
often and should be implemented efficiently.
If the parameter \a dir does not specify a directory, the function shall
- fail. It shall also fail, if it is a directory, but does not contain an entry
- with the given name \a name. Otherwise the function shall invoke get_vnode()
- for the node the entry refers to and pass back the ID and the type of the
- node in \a _id and \a _type respectively.
+ fail. It shall also fail, if it is a directory, but does not contain an
+ entry with the given name \a name. Otherwise the function shall invoke
+ get_vnode() for the node the entry refers to and pass back the ID of the
+ node in \a _id.
Note that a directory must contain the special entries \c "." and \c "..",
referring to the same directory and the parent directory respectively.
lookup() must resolve the nodes accordingly. \c ".." for the root directory
of the volume shall be resolved to the root directory itself.
- \param fs The volume handle.
- \param dir The node handle of the directory.
+ \param volume The volume object.
+ \param dir The node object for the directory.
\param name The name of the directory entry.
\param _id Pointer to a pre-allocated variable the ID of the found node
shall be written to.
- \param _type Pointer to a pre-allocated variable the type of the found node
- shall be written to. The type is encoded as in the \c st_mode field of a
- <tt>struct stat</tt> (bitwise anded with \c S_IFMT).
\retval B_OK Everything went fine.
+ \retval B_NOT_A_DIRECTORY The given node is not a directory.
\retval B_ENTRY_NOT_FOUND The given directory does not contain an entry with
the given name.
*/
/*!
- \fn status_t (*file_system_module_info::get_vnode_name)(fs_volume fs,
- fs_vnode vnode, char *buffer, size_t bufferSize)
- \brief Return the file name of a vnode.
+ \fn status_t (*fs_vnode_ops::get_vnode_name)(fs_volume *volume,
+ fs_vnode *vnode, char *buffer, size_t bufferSize)
+ \brief Return the file name of a directory vnode.
+ Normally file systems don't support hard links for directories, which means
+ that a directory can be addressed by a unique path. This hook returns the
+ name of the directory's entry in its parent directory.
+
Note that you don't have to implement this call if it can't be easily done;
it's completely optional.
If you don't implement it, you'll have to export a NULL pointer for this
function in the module definition. In this case, the VFS will find the name
by iterating over its parent directory.
- \param fs The file system provided cookie associated with this volume.
- \param vnode The file system provided cookie associated with this vnode.
+ If invoked for a non-directory node the hook is allowed to fail.
+
+ \param volume The volume object.
+ \param vnode The node object.
\param buffer The buffer that the name can be copied into.
\param bufferSize The size of the buffer.
\retval B_OK You successfully copied the file name into the \a buffer.
@@ -343,51 +805,30 @@
*/
/*!
- \fn status_t (*file_system_module_info::get_vnode)(fs_volume fs, ino_t id,
- fs_vnode *_vnode, bool reenter)
- \brief Creates the private data handle to be associated with the node
- referred to by \a id.
-
- Invoked by the VFS when it creates the vnode for the respective node.
- When the VFS no longer needs the vnode in memory (for example when
- memory is becoming tight), it will your file_system_module_info::put_vnode(),
- or file_system_module_info::remove_vnode() in case the vnode has been
- marked removed.
-
- \param fs The volume handle.
- \param id The ID of the node.
- \param _vnode Pointer to a pre-allocated variable the node handle shall be
- written to.
- \param reenter \c true if the hook invocation has been caused by the FS
- itself, e.g. by invoking ::get_vnode().
- \return \c B_OK if everything went fine, another error code otherwise.
-*/
-
-/*!
- \fn \fn status_t (*file_system_module_info::put_vnode)(fs_volume fs,
- fs_vnode vnode, bool reenter)
+ \fn \fn status_t (*fs_vnode_ops::put_vnode)(fs_volume *volume,
+ fs_vnode *vnode, bool reenter)
\brief Deletes the private data handle associated with the specified node.
Invoked by the VFS when it deletes the vnode for the respective node and the
node is not marked removed.
- \param fs The volume handle.
- \param vnode The node handle.
+ \param volume The volume object.
+ \param vnode The node object.
\param reenter \c true if the hook invocation has been caused by the FS
itself, e.g. by invoking ::put_vnode().
\return \c B_OK if everything went fine, another error code otherwise.
*/
/*!
- \fn status_t (*file_system_module_info::remove_vnode)(fs_volume fs,
- fs_vnode vnode, bool reenter)
+ \fn status_t (*fs_vnode_ops::remove_vnode)(fs_volume *volume,
+ fs_vnode *vnode, bool reenter)
\brief Deletes the private data handle associated with the specified node.
Invoked by the VFS when it deletes the vnode for the respective node and the
node has been marked removed by a call to remove_vnode().
- \param fs The volume handle.
- \param vnode The node handle.
+ \param volume The volume object.
+ \param vnode The node object.
\param reenter \c true if the hook invocation has been caused by the FS
itself, e.g. by invoking ::put_vnode().
\return \c B_OK if everything went fine, another error code otherwise.
@@ -402,29 +843,48 @@
//! @{
/*!
- \fn bool (*file_system_module_info::can_page)(fs_volume fs, fs_vnode vnode,
- fs_cookie cookie)
- \brief Undocumented. TODO.
+ \fn bool (*fs_vnode_ops::can_page)(fs_volume *volume, fs_vnode *vnode,
+ void *cookie)
+ \brief Deprecated.
+ \deprecated This is an obsolete hook that is never invoked.
+*/
- TODO: In both the dos and the bfs implementations this thing simply returns
- false... Is there anything more to it?
- This call might be removed in the future - it's currently unused.
+/*!
+ \fn status_t (*fs_vnode_ops::read_pages)(fs_volume *volume, fs_vnode *vnode,
+ void *cookie, off_t pos, const iovec *vecs, size_t count,
+ size_t *_numBytes)
+ \brief Deprecated.
+ \deprecated This is an obsolete hook that is never invoked.
*/
/*!
- \fn status_t (*file_system_module_info::read_pages)(fs_volume fs, fs_vnode vnode,
- fs_cookie cookie, off_t pos, const iovec *vecs, size_t count,
- size_t *_numBytes, bool reenter)
- \brief Undocumented. TODO.
+ \fn status_t (*fs_vnode_ops::write_pages)(fs_volume *volume,
+ fs_vnode *vnode, void *cookie, off_t pos, const iovec *vecs,
+ size_t count, size_t *_numBytes)
+ \brief Deprecated.
+ \deprecated This is an obsolete hook that is never invoked.
*/
+//! @}
+
/*!
- \fn status_t (*file_system_module_info::write_pages)(fs_volume fs, fs_vnode vnode,
- fs_cookie cookie, off_t pos, const iovec *vecs, size_t count,
- size_t *_numBytes, bool reenter)
- \brief Undocumented. TODO.
+ \name Asynchronous I/O
*/
+//! @{
+
+/*!
+ \fn status_t (*fs_vnode_ops::io)(fs_volume *volume, fs_vnode *vnode,
+ void *cookie, io_request *request)
+ \brief TODO: Document!
+*/
+
+/*!
+ \fn status_t (*fs_vnode_ops::cancel_io)(fs_volume *volume, fs_vnode *vnode,
+ void *cookie, io_request *request)
+ \brief TODO: Document!
+*/
+
//! @}
/*!
@@ -434,9 +894,9 @@
//! @{
/*!
- \fn status_t (*file_system_module_info::get_file_map)(fs_volume fs,
- fs_vnode vnode, off_t offset, size_t size, struct file_io_vec *vecs,
- size_t *_count)
+ \fn status_t (*fs_vnode_ops::get_file_map)(fs_volume *volume,
+ fs_vnode *vnode, off_t offset, size_t size,
+ struct file_io_vec *vecs, size_t *_count)
\brief Fills the \a vecs with the extents of the file data stream.
This function is called only when you are using the file cache, but if you
@@ -454,8 +914,8 @@
//! @{
/*!
- \fn status_t (*file_system_module_info::ioctl)(fs_volume fs, fs_vnode vnode,
- fs_cookie cookie, ulong op, void *buffer, size_t length)
+ \fn status_t (*fs_vnode_ops::ioctl)(fs_volume *volume, fs_vnode *vnode,
+ void *cookie, ulong op, void *buffer, size_t length)
\brief Perform file system specific operations.
You can implement a customized API using this call. This can be extremely
@@ -464,9 +924,8 @@
If you don't want to use this feature, you don't have to implement it.
- \param fs The file system provided cookie associated with this volume.
- \param vnode The file system provided cookie associated with the vnode (if
- applicable).
+ \param volume The volume object.
+ \param vnode The node object.
\param cookie The file system provided cookie associated with, for example,
an open file (if applicable).
\param op The operation code. You will have to define them yourself.
@@ -476,14 +935,14 @@
*/
/*!
- \fn status_t (*file_system_module_info::set_flags)(fs_volume fs,
- fs_vnode vnode, fs_cookie cookie, int flags)
+ \fn status_t (*fs_vnode_ops::set_flags)(fs_volume *volume, fs_vnode *vnode,
+ void *cookie, int flags)
\brief Set the open mode flags for an opened file.
This function should change the open flags for an opened file.
- \param fs The file system provided cookie associated with this volume.
- \param vnode The file system provided cookie associated with the vnode.
+ \param volume The volume object.
+ \param vnode The node object.
\param cookie The file system provided cookie associated with the opened
file.
\param flags The new flags.
@@ -491,8 +950,8 @@
*/
/*!
- \fn status_t (*file_system_module_info::select)(fs_volume fs, fs_vnode vnode,
- fs_cookie cookie, uint8 event, uint32 ref, selectsync *sync)
+ \fn status_t (*fs_vnode_ops::select)(fs_volume *volume, fs_vnode *vnode,
+ void *cookie, uint8 event, selectsync *sync)
\brief Selects the specified \a vnode with the specified \a events.
This function is called by the VFS whenever select() or poll() is called on
@@ -507,9 +966,9 @@
notify_select_event() whenever the condition becomes true until the
vnode is deselected again via file_system_module_info::deselect().
- This function is optional. If you don't export it, the default implementation
- in the VFS will call notify_select_event() directly which will be sufficient
- for most file systems.
+ This function is optional. If you don't export it, the default
+ implementation in the VFS will call notify_select_event() directly which
+ will be sufficient for most file systems.
Note that while select() and the corresponding deselect() are invoked by the
same thread, notifications are usually generated by other threads. It is
@@ -519,30 +978,54 @@
and when removing the selectsync object from the cookie in deselect().
Such a lock can be any lock, usually one that is associated with the node or
the volume.
+
+ \param volume The volume object.
+ \param vnode The node object.
+ \param cookie The file system provided cookie associated with the opened
+ file.
+ \param event The event to be selected. One of:
+ - \c B_SELECT_READ: File ready for reading.
+ - \c B_SELECT_WRITE: File ready for writing.
+ - \c B_SELECT_ERROR: I/O error condition.
+ - \c B_SELECT_PRI_READ: File ready for priority read.
+ - \c B_SELECT_PRI_WRITE: File ready for priority write.
+ - \c B_SELECT_HIGH_PRI_READ: File ready for high priority read.
+ - \c B_SELECT_HIGH_PRI_WRITE: File ready for high priority write.
+ - \c B_SELECT_DISCONNECTED: Socket/FIFO/... has been disconnected.
+ \param sync Opaque pointer to be passed to notify_select_event().
+ \return \c B_OK if the operation succeeded, or else an error code.
*/
/*!
- \fn status_t (*file_system_module_info::deselect)(fs_volume fs, fs_vnode vnode,
- fs_cookie cookie, uint8 event, selectsync *sync)
+ \fn status_t (*fs_vnode_ops::deselect)(fs_volume *volume, fs_vnode *vnode,
+ void *cookie, uint8 event, selectsync *sync)
\brief Deselects the specified \a vnode from a previous select() call.
This function is called by the VFS whenever a select() or poll() function
exits that previously called file_system_module_info::select() on that
\a vnode.
+
+ \param volume The volume object.
+ \param vnode The node object.
+ \param cookie The file system provided cookie associated with the opened
+ file.
+ \param event The event to be deselected.
+ \param sync Opaque pointer to be passed to notify_select_event().
+ \return \c B_OK if the operation succeeded, or else an error code.
*/
/*!
- \fn status_t (*file_system_module_info::fsync)(fs_volume fs, fs_vnode vnode)
+ \fn status_t (*fs_vnode_ops::fsync)(fs_volume *volume, fs_vnode *vnode)
\brief Synchronize the buffers with the on disk data.
- \param fs The file system provided cookie associated with this volume.
- \param vnode The file system provided cookie associated with the vnode.
+ \param volume The volume object.
+ \param vnode The node object.
\return \c B_OK if the operation succeeded, or else an error code.
*/
/*!
- \fn status_t (*file_system_module_info::read_symlink)(fs_volume fs,
- fs_vnode link, char *buffer, size_t *_bufferSize)
+ \fn status_t (*fs_vnode_ops::read_symlink)(fs_volume *volume,
+ fs_vnode *link, char *buffer, size_t *_bufferSize)
\brief Read the value of a symbolic link.
If the function is successful, the symlink string shall be written to the
@@ -553,8 +1036,8 @@
points to shall be set to the length of the string written to the buffer,
not including any terminating null character (if written).
- \param fs The volume handle.
- \param link The node handle.
+ \param volume The volume object.
+ \param link The node object.
\param buffer Pointer to a pre-allocated buffer the link value shall be
written to.
\param _bufferSize Pointer to a pre-allocated variable containing the size
@@ -566,39 +1049,34 @@
*/
/*!
- \fn status_t (*file_system_module_info::create_symlink)(fs_volume fs,
- fs_vnode dir, const char *name, const char *path, int mode)
[... truncated: 1487 lines follow ...]
More information about the Haiku-commits
mailing list