* Removed deprecated functions.

* The documented the notify_*() functions - only notify_listener() was deprecated
  among them.
* Replaced spaces with tabs - there is no reason to deviate from the standard we're
  using everywhere else.
* Completed the docs here and there.


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21615 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Axel Dörfler
2007-07-15 13:31:02 +00:00
parent bd1877933f
commit 84f03dd594
+177 -183
View File
@@ -1,179 +1,168 @@
/* /*
* Copyright 2007 Haiku Inc. All rights reserved. * Copyright 2007 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Authors: * Authors:
* Ingo Weinhold * Ingo Weinhold
* Niels Sascha Reedijk <[email protected]> * Niels Sascha Reedijk <[email protected]>
* Axel Dörfler, [email protected]
*
* Corresponds to: * Corresponds to:
* /trunk/headers/os/drivers/fs_interface.h rev 21568 * /trunk/headers/os/drivers/fs_interface.h rev 21568
*/ */
/*! /*!
\file fs_interface.h \file fs_interface.h
\ingroup drivers \ingroup drivers
\brief Provides an interface for file system modules. \brief Provides an interface for file system modules.
See the \ref fs_modules "introduction to file system modules" for a guide on See the \ref fs_modules "introduction to file system modules" for a guide on
how to get started with writing file system modules. how to get started with writing file system modules.
*/
///// Typedefs /////
/*!
\typedef typedef void *fs_volume
\brief Private data structure for the filesystem to store data associated
with volumes.
*/
/*!
\typedef typedef void *fs_cookie
\brief Private data structure that is passed to the filesystem when it is
called.
*/
/*!
\typedef typedef void *fs_vnode
\brief Private data structure that is passed to the filesystem when it is
operating on vnodes.
*/ */
///// write_stat_mask ////// ///// write_stat_mask //////
/*! /*!
\enum write_stat_mask \enum write_stat_mask
\brief This mask is used in file_system_module_info::write_stat() to \brief This mask is used in file_system_module_info::write_stat() to
determine which values need to be written. determine which values need to be written.
*/ */
/*! /*!
\var write_stat_mask::FS_WRITE_STAT_MODE \var write_stat_mask::FS_WRITE_STAT_MODE
\brief The mode parameter should be updated. \brief The mode parameter should be updated.
*/ */
/*! /*!
\var write_stat_mask::FS_WRITE_STAT_UID \var write_stat_mask::FS_WRITE_STAT_UID
\brief The UID field should be updated. \brief The UID field should be updated.
*/ */
/*! /*!
\var write_stat_mask::FS_WRITE_STAT_GID \var write_stat_mask::FS_WRITE_STAT_GID
\brief The GID field should be updated. \brief The GID field should be updated.
*/ */
/*! /*!
\var write_stat_mask::FS_WRITE_STAT_SIZE \var write_stat_mask::FS_WRITE_STAT_SIZE
\brief The size field should be updated. If the actual size is less than the \brief The size field should be updated. If the actual size is less than the
new provided file size, the file should be set to the new size and the new provided file size, the file should be set to the new size and the
extra space should be filled with zeros. extra space should be filled with zeros.
*/ */
/*! /*!
\var write_stat_mask::FS_WRITE_STAT_ATIME \var write_stat_mask::FS_WRITE_STAT_ATIME
\brief The access time should be updated. \brief The access time should be updated.
*/ */
/*! /*!
\var write_stat_mask::FS_WRITE_STAT_MTIME \var write_stat_mask::FS_WRITE_STAT_MTIME
\brief The 'last modified' field should be updated. \brief The 'last modified' field should be updated.
*/ */
/*! /*!
\var write_stat_mask::FS_WRITE_STAT_CRTIME \var write_stat_mask::FS_WRITE_STAT_CRTIME
\brief The 'creation time' should be updated. \brief The 'creation time' should be updated.
*/ */
///// FS_WRITE_FSINFO_NAME ///// ///// FS_WRITE_FSINFO_NAME /////
/*! /*!
\def FS_WRITE_FSINFO_NAME \def FS_WRITE_FSINFO_NAME
\brief Passed to file_system_module_info::write_fs_info(). \brief Passed to file_system_module_info::write_fs_info().
*/ */
///// file_io_vec ///// ///// file_io_vec /////
/*! /*!
\struct file_io_vec \struct file_io_vec
\brief Structure that describes the io vector of a file. \brief Structure that describes the io vector of a file.
*/ */
/*! /*!
\var off_t file_io_vec::offset \var off_t file_io_vec::offset
\brief The offset within the file. \brief The offset within the file.
*/ */
/*! /*!
\var off_t file_io_vec::length \var off_t file_io_vec::length
\brief The length of the vector. \brief The length of the vector.
*/ */
///// B_CURRENT_FS_API_VERSION ///// ///// B_CURRENT_FS_API_VERSION /////
/*! /*!
\def B_CURRENT_FS_API_VERSION \def B_CURRENT_FS_API_VERSION
\brief Constant that defines the version of the filesystem API that your \brief Constant that defines the version of the file system API that your
filesystem conforms to. filesystem conforms to.
The module name that exports the interface to your file system has to
end with this constant as in:
\code "file_systems/myfs" B_CURRENT_FS_API_VERSION
*/ */
///// file_system_module_info ///// ///// file_system_module_info /////
/*! /*!
\struct file_system_module_info \struct file_system_module_info
\brief Kernel module interface for file systems. \brief Kernel module interface for file systems.
See the \ref fs_modules "introduction to file system modules" for an See the \ref fs_modules "introduction to file system modules" for an
introduction to writing file systems. introduction to writing file systems.
*/ */
/*! /*!
\name Data members \name Data members
*/ */
//! @{ //! @{
/*! /*!
\var module_info file_system_module_info::info \var module_info file_system_module_info::info
\brief Your module_info object which is required for all modules. \brief Your module_info object which is required for all modules.
*/ */
/*! /*!
\var const char *file_system_module_info::pretty_name \var const char *file_system_module_info::pretty_name
\brief A NULL-terminated string with a 'pretty' name for you file system. \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.
*/ */
//! @} //! @}
/*! /*!
\name Scanning \name Scanning
*/ */
//! @{ //! @{
/*! /*!
\fn float (*file_system_module_info::identify_partition)(int fd, partition_data *partition, void **cookie) \fn float (*file_system_module_info::identify_partition)(int fd, partition_data *partition, void **cookie)
\brief Undocumented. TODO. \brief Undocumented. TODO.
*/ */
/*! /*!
\fn status_t (*file_system_module_info::scan_partition)(int fd, partition_data *partition, void *cookie) \fn status_t (*file_system_module_info::scan_partition)(int fd, partition_data *partition, void *cookie)
\brief Undocumented. TODO. \brief Undocumented. TODO.
*/ */
/*! /*!
\fn void (*file_system_module_info::free_identify_partition_cookie)(partition_data *partition, void *cookie) \fn void (*file_system_module_info::free_identify_partition_cookie)(partition_data *partition, void *cookie)
\brief Undocumented. TODO. \brief Undocumented. TODO.
*/ */
/*! /*!
\fn void (*file_system_module_info::free_partition_content_cookie)(partition_data *partition) \fn void (*file_system_module_info::free_partition_content_cookie)(partition_data *partition)
\brief Undocumented. TODO. \brief Undocumented. TODO.
*/ */
//! @} //! @}
/*! /*!
\name General Operations \name General Operations
*/ */
//! @{ //! @{
@@ -1554,185 +1543,190 @@
//! @} //! @}
///// Global Functions ///// ///// Vnode functions /////
/*! /*!
\fn status_t new_vnode(dev_t mountID, ino_t vnodeID, \fn status_t new_vnode(dev_t mountID, ino_t vnodeID,
fs_vnode privateNode) fs_vnode privateNode)
\brief Create the vnode with ID \a vnodeID and associates it with the \brief Create the vnode with ID \a vnodeID and associates it with the
private data handle \a privateNode, but leaves is in an unpublished state. private data handle \a privateNode, but leaves is in an unpublished state.
The effect of the function is similar to publish_vnode(), but the vnode The effect of the function is similar to publish_vnode(), but the vnode
remains in an unpublished state, with the effect that a subsequent remains in an unpublished state, with the effect that a subsequent
remove_vnode() will just delete the vnode and not invoke the file system's remove_vnode() will just delete the vnode and not invoke the file system's
\link file_system_module_info::remove_vnode remove_vnode() \endlink is not \link file_system_module_info::remove_vnode remove_vnode() \endlink when
invoked. the final reference is put down.
If the vnode shall be kept, publish_vnode() has to be invoked afterwards to If the vnode shall be kept, publish_vnode() has to be invoked afterwards to
mark the vnode published. The combined effect is the same as only invoking mark the vnode published. The combined effect is the same as only invoking
publish_vnode(). publish_vnode().
The function fails, if the vnode does already exist. You'll usually use this function to secure a vnode ID from being reused
while you are in the process of creating the entry. Note that this function
will panic in case you call it for an existing vnode ID.
\param mountID The ID of the volume. The function fails, if the vnode does already exist.
\param vnodeID The ID of the node.
\param privateNode The private data handle to be associated with the node. \param mountID The ID of the volume.
\return \c B_OK if everything went fine, another error code otherwise. \param vnodeID The ID of the node.
\param privateNode The private data handle to be associated with the node.
\return \c B_OK if everything went fine, another error code otherwise.
*/ */
/*! /*!
\fn status_t publish_vnode(dev_t mountID, ino_t vnodeID, \fn status_t publish_vnode(dev_t mountID, ino_t vnodeID,
fs_vnode privateNode) fs_vnode privateNode)
\brief Creates the vnode with ID \a vnodeID and associates it with the \brief Creates the vnode with ID \a vnodeID and associates it with the
private data handle \a privateNode or just marks it published. private data handle \a privateNode or just marks it published.
If the vnode does already exist and has been published, the function fails. If the vnode does already exist and has been published, the function fails.
If it has not been published yet (i.e. after a successful new_vnode()), the If it has not been published yet (i.e. after a successful new_vnode()), the
function just marks the vnode published. If the vnode did not exist at all function just marks the vnode published. If the vnode did not exist at all
before, it is created and published. before, it is created and published.
If the function is successful, the caller owns a reference to the vnode. A If the function is successful, the caller owns a reference to the vnode. A
sequence of new_vnode() and publish_vnode() results in just one reference as sequence of new_vnode() and publish_vnode() results in just one reference as
well. The reference can be surrendered by calling put_vnode(). well. The reference can be surrendered by calling put_vnode().
\param mountID The ID of the volume. This call is equivalent to the former R5 new_vnode() function.
\param vnodeID The ID of the node.
\param privateNode The private data handle to be associated with the node. \param mountID The ID of the volume.
\return \c B_OK if everything went fine, another error code otherwise. \param vnodeID The ID of the node.
\param privateNode The private data handle to be associated with the node.
\return \c B_OK if everything went fine, another error code otherwise.
*/ */
/*! /*!
\fn status_t get_vnode(dev_t mountID, ino_t vnodeID, \fn status_t get_vnode(dev_t mountID, ino_t vnodeID,
fs_vnode *_privateNode) fs_vnode *_privateNode)
\brief Retrieves the private data handle for the node with the given ID. \brief Retrieves the private data handle for the node with the given ID.
If the function is successful, the caller owns a reference to the vnode. The If the function is successful, the caller owns a reference to the vnode. The
reference can be surrendered by calling put_vnode(). reference can be surrendered by calling put_vnode().
\param mountID The ID of the volume. \param mountID The ID of the volume.
\param vnodeID The ID of the node. \param vnodeID The ID of the node.
\param _privateNode Pointer to a pre-allocated variable the private data \param _privateNode Pointer to a pre-allocated variable the private data
handle shall be written to. handle shall be written to.
\return \c B_OK if everything went fine, another error code otherwise. \return \c B_OK if everything went fine, another error code otherwise.
*/ */
/*! /*!
\fn status_t put_vnode(dev_t mountID, ino_t vnodeID) \fn status_t put_vnode(dev_t mountID, ino_t vnodeID)
\brief Surrenders a reference to the specified vnode. \brief Surrenders a reference to the specified vnode.
\param mountID The ID of the volume. \param mountID The ID of the volume.
\param vnodeID The ID of the node. \param vnodeID The ID of the node.
\return \c B_OK if everything went fine, another error code otherwise. \return \c B_OK if everything went fine, another error code otherwise.
*/ */
/*! /*!
\fn status_t remove_vnode(dev_t mountID, ino_t vnodeID) \fn status_t remove_vnode(dev_t mountID, ino_t vnodeID)
\brief Marks the specified vnode removed. \brief Marks the specified vnode removed.
The caller must own a reference to the vnode or at least ensure that a The caller must own a reference to the vnode or at least ensure that a
reference to the vnode exists. The function does not surrender a reference, reference to the vnode exists. The function does not surrender a reference,
though. though.
As soon as the last reference to the vnode has been surrendered, the VFS As soon as the last reference to the vnode has been surrendered, the VFS
invokes the file system's invokes the file system's
\link file_system_module_info::remove_vnode remove_vnode() \endlink \link file_system_module_info::remove_vnode remove_vnode() \endlink
hook. hook.
\param mountID The ID of the volume. \param mountID The ID of the volume.
\param vnodeID The ID of the node. \param vnodeID The ID of the node.
\return \c B_OK if everything went fine, another error code otherwise. \return \c B_OK if everything went fine, another error code otherwise.
*/ */
/*! /*!
\fn status_t unremove_vnode(dev_t mountID, ino_t vnodeID); \fn status_t unremove_vnode(dev_t mountID, ino_t vnodeID);
\brief Clears the "removed" mark of the specified vnode. \brief Clears the "removed" mark of the specified vnode.
The caller must own a reference to the vnode or at least ensure that a The caller must own a reference to the vnode or at least ensure that a
reference to the vnode exists. reference to the vnode exists.
The function is usually called when the caller, who has invoked The function is usually called when the caller, who has invoked
remove_vnode() before realizes that it is not possible to remove the node remove_vnode() before realizes that it is not possible to remove the node
(e.g. due to an error). (e.g. due to an error).
\param mountID The ID of the volume. \param mountID The ID of the volume.
\param vnodeID The ID of the node. \param vnodeID The ID of the node.
\return \c B_OK if everything went fine, another error code otherwise. \return \c B_OK if everything went fine, another error code otherwise.
*/ */
/*! /*!
\fn status_t get_vnode_removed(dev_t mountID, ino_t vnodeID, \fn status_t get_vnode_removed(dev_t mountID, ino_t vnodeID,
bool* removed); bool* removed);
\brief Returns whether the specified vnode is marked removed. \brief Returns whether the specified vnode is marked removed.
The caller must own a reference to the vnode or at least ensure that a The caller must own a reference to the vnode or at least ensure that a
reference to the vnode exists. reference to the vnode exists.
\param mountID The ID of the volume. \param mountID The ID of the volume.
\param vnodeID The ID of the node. \param vnodeID The ID of the node.
\param removed Pointer to a pre-allocated variable set to \c true, if the \param removed Pointer to a pre-allocated variable set to \c true, if the
node is marked removed, to \c false otherwise. node is marked removed, to \c false otherwise.
\return \c B_OK if everything went fine, another error code otherwise. \return \c B_OK if everything went fine, another error code otherwise.
*/ */
///// Deprecated Global Functions ///// Notification Functions
/*! /*!
\name Deprecated functions \name Notification Functions
The following list of functions should not be used, and could be removed even The following functions are used to implement the node monitor functionality
before the release of Haiku R1. in your file system. Whenever one of the below mentioned events occur, you
*/ have to call them.
//! @{ The node monitor will then notify all registered listeners for the nodes
that changed.
/*!
\fn status_t notify_listener(int op, dev_t device, ino_t parentNode,
ino_t toParentNode, ino_t node, const char *name)
\brief Deprecated. This feature will be removed in future versions.
*/ */
/*! /*!
\fn status_t notify_entry_created(dev_t device, ino_t directory, \fn status_t notify_entry_created(dev_t device, ino_t directory,
const char *name, ino_t node) const char *name, ino_t node)
\brief Deprecated. This feature will be removed in future versions. \brief Notifies listeners that a file system entry has been created.
*/ */
/*! /*!
\fn status_t notify_entry_removed(dev_t device, ino_t directory, \fn status_t notify_entry_removed(dev_t device, ino_t directory,
const char *name, ino_t node) const char *name, ino_t node)
\brief Deprecated. This feature will be removed in future versions. \brief Notifies listeners that a file system entry has been removed.
*/ */
/*! /*!
\fn status_t notify_entry_moved(dev_t device, ino_t fromDirectory, \fn status_t notify_entry_moved(dev_t device, ino_t fromDirectory,
const char *fromName, ino_t toDirectory, const char *fromName, ino_t toDirectory,
const char *toName, ino_t node) const char *toName, ino_t node)
\brief Deprecated. This feature will be removed in future versions. \brief Notifies listeners that a file system entry has been moved to
another directory.
*/ */
/*! /*!
\fn status_t notify_stat_changed(dev_t device, ino_t node, \fn status_t notify_stat_changed(dev_t device, ino_t node,
uint32 statFields) uint32 statFields)
\brief Deprecated. This feature will be removed in future versions. \brief Notifies listeners that certain \a statFields of a file system entry
were updated.
*/ */
/*! /*!
\fn status_t notify_attribute_changed(dev_t device, ino_t node, \fn status_t notify_attribute_changed(dev_t device, ino_t node,
const char *attribute, int32 cause) const char *attribute, int32 cause)
\brief Deprecated. This feature will be removed in future versions. \brief Notifies listeners that an attribute of a file system entry has been
changed.
*/ */
/*! /*!
\fn status_t notify_query_entry_created(port_id port, int32 token, \fn status_t notify_query_entry_created(port_id port, int32 token,
dev_t device, ino_t directory, const char *name, dev_t device, ino_t directory, const char *name,
ino_t node) ino_t node)
\brief Deprecated. This feature will be removed in future versions. \brief Notifies listeners that an entry has entered the result set of a live query.
*/ */
/*! /*!
\fn status_t notify_query_entry_removed(port_id port, int32 token, \fn status_t notify_query_entry_removed(port_id port, int32 token,
dev_t device, ino_t directory, const char *name, dev_t device, ino_t directory, const char *name,
ino_t node) ino_t node)
\brief Deprecated. This feature will be removed in future versions. \brief Notifies listeners that an entry has left the result set of a live query.
*/ */
//! @} //! @}