From 84f03dd5948a8b50c4434701e622b82da98e3e5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Axel=20D=C3=B6rfler?= Date: Sun, 15 Jul 2007 13:31:02 +0000 Subject: [PATCH] * 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 --- docs/user/drivers/fs_interface.dox | 1470 ++++++++++++++-------------- 1 file changed, 732 insertions(+), 738 deletions(-) diff --git a/docs/user/drivers/fs_interface.dox b/docs/user/drivers/fs_interface.dox index 60e13adc24..b4fe2d402b 100644 --- a/docs/user/drivers/fs_interface.dox +++ b/docs/user/drivers/fs_interface.dox @@ -1,179 +1,168 @@ -/* +/* * Copyright 2007 Haiku Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: - * Ingo Weinhold - * Niels Sascha Reedijk + * Ingo Weinhold + * Niels Sascha Reedijk + * Axel Dörfler, axeld@pinc-software.de + * * Corresponds to: - * /trunk/headers/os/drivers/fs_interface.h rev 21568 + * /trunk/headers/os/drivers/fs_interface.h rev 21568 */ -/*! - \file fs_interface.h - \ingroup drivers - \brief Provides an interface for file system modules. - - See the \ref fs_modules "introduction to file system modules" for a guide on - 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. -*/ + \file fs_interface.h + \ingroup drivers + \brief Provides an interface for file system modules. -/*! - \typedef typedef void *fs_vnode - \brief Private data structure that is passed to the filesystem when it is - operating on vnodes. + See the \ref fs_modules "introduction to file system modules" for a guide on + how to get started with writing file system modules. */ ///// write_stat_mask ////// /*! - \enum write_stat_mask - \brief This mask is used in file_system_module_info::write_stat() to - determine which values need to be written. + \enum write_stat_mask + \brief This mask is used in file_system_module_info::write_stat() to + determine which values need to be written. */ /*! - \var write_stat_mask::FS_WRITE_STAT_MODE - \brief The mode parameter should be updated. + \var write_stat_mask::FS_WRITE_STAT_MODE + \brief The mode parameter should be updated. */ /*! - \var write_stat_mask::FS_WRITE_STAT_UID - \brief The UID field should be updated. + \var write_stat_mask::FS_WRITE_STAT_UID + \brief The UID field should be updated. */ /*! - \var write_stat_mask::FS_WRITE_STAT_GID - \brief The GID field should be updated. + \var write_stat_mask::FS_WRITE_STAT_GID + \brief The GID field should be updated. */ /*! - \var write_stat_mask::FS_WRITE_STAT_SIZE - \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 - extra space should be filled with zeros. + \var write_stat_mask::FS_WRITE_STAT_SIZE + \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 + extra space should be filled with zeros. */ /*! - \var write_stat_mask::FS_WRITE_STAT_ATIME - \brief The access time should be updated. + \var write_stat_mask::FS_WRITE_STAT_ATIME + \brief The access time should be updated. */ /*! - \var write_stat_mask::FS_WRITE_STAT_MTIME - \brief The 'last modified' field should be updated. + \var write_stat_mask::FS_WRITE_STAT_MTIME + \brief The 'last modified' field should be updated. */ /*! - \var write_stat_mask::FS_WRITE_STAT_CRTIME - \brief The 'creation time' should be updated. + \var write_stat_mask::FS_WRITE_STAT_CRTIME + \brief The 'creation time' should be updated. */ ///// FS_WRITE_FSINFO_NAME ///// /*! - \def FS_WRITE_FSINFO_NAME - \brief Passed to file_system_module_info::write_fs_info(). + \def FS_WRITE_FSINFO_NAME + \brief Passed to file_system_module_info::write_fs_info(). */ ///// file_io_vec ///// /*! - \struct file_io_vec - \brief Structure that describes the io vector of a file. + \struct file_io_vec + \brief Structure that describes the io vector of a file. */ /*! - \var off_t file_io_vec::offset - \brief The offset within the file. + \var off_t file_io_vec::offset + \brief The offset within the file. */ /*! - \var off_t file_io_vec::length - \brief The length of the vector. + \var off_t file_io_vec::length + \brief The length of the vector. */ ///// B_CURRENT_FS_API_VERSION ///// /*! - \def B_CURRENT_FS_API_VERSION - \brief Constant that defines the version of the filesystem API that your - filesystem conforms to. + \def B_CURRENT_FS_API_VERSION + \brief Constant that defines the version of the file system API that your + 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 ///// /*! - \struct file_system_module_info - \brief Kernel module interface for file systems. - - See the \ref fs_modules "introduction to file system modules" for an - introduction to writing file systems. + \struct file_system_module_info + \brief Kernel module interface for file systems. + + See the \ref fs_modules "introduction to file system modules" for an + introduction to writing file systems. */ /*! - \name Data members + \name Data members */ //! @{ /*! - \var module_info file_system_module_info::info - \brief Your module_info object which is required for all modules. + \var module_info file_system_module_info::info + \brief Your module_info object which is required for all modules. */ /*! - \var const char *file_system_module_info::pretty_name - \brief A NULL-terminated string with a 'pretty' name for you file system. + \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. */ //! @} /*! - \name Scanning + \name Scanning */ //! @{ /*! - \fn float (*file_system_module_info::identify_partition)(int fd, partition_data *partition, void **cookie) - \brief Undocumented. TODO. + \fn float (*file_system_module_info::identify_partition)(int fd, partition_data *partition, void **cookie) + \brief Undocumented. TODO. */ /*! - \fn status_t (*file_system_module_info::scan_partition)(int fd, partition_data *partition, void *cookie) - \brief Undocumented. TODO. + \fn status_t (*file_system_module_info::scan_partition)(int fd, partition_data *partition, void *cookie) + \brief Undocumented. TODO. */ /*! - \fn void (*file_system_module_info::free_identify_partition_cookie)(partition_data *partition, void *cookie) - \brief Undocumented. TODO. + \fn void (*file_system_module_info::free_identify_partition_cookie)(partition_data *partition, void *cookie) + \brief Undocumented. TODO. */ /*! - \fn void (*file_system_module_info::free_partition_content_cookie)(partition_data *partition) - \brief Undocumented. TODO. + \fn void (*file_system_module_info::free_partition_content_cookie)(partition_data *partition) + \brief Undocumented. TODO. */ //! @} /*! - \name General Operations + \name General Operations */ //! @{ @@ -259,33 +248,33 @@ */ /*! - \fn status_t (*file_system_module_info::write_fs_info)(fs_volume fs, const + \fn status_t (*file_system_module_info::write_fs_info)(fs_volume fs, 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 - 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 info The structure that contains the new data. - \param mask The values of the \a info that need to be updated. + \brief Update filesystem information on the volume. + + You are requested to update certain information on the volume \a fs. 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 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) - \brief Synchronize the cached data with the contents of the disk. - - The VFS layer sometimes wants you to synchronize any cached values with the - data on the device. - - TODO: WHEN IS THIS CALLED AND FOR WHAT PURPOSE? - - \param fs The cookie your filesystem supplied to the volume that should be + \brief Synchronize the cached data with the contents of the disk. + + The VFS layer sometimes wants you to synchronize any cached values with the + data on the device. + + TODO: WHEN IS THIS CALLED AND FOR WHAT PURPOSE? + + \param fs The cookie your filesystem supplied to the volume that should be updated. */ @@ -330,15 +319,15 @@ */ /*! - \fn status_t (*file_system_module_info::get_vnode_name)(fs_volume fs, + \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. - - \param fs The file system provided cookie associated with this volume. - \param vnode The file system provided cookie associated with this vnode. - \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. + \brief Return the file name of a vnode. + + \param fs The file system provided cookie associated with this volume. + \param vnode The file system provided cookie associated with this vnode. + \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. \retval "other errors" There was some error looking up or copying the name. */ @@ -399,9 +388,9 @@ /*! \fn bool (*file_system_module_info::can_page)(fs_volume fs, fs_vnode vnode, fs_cookie cookie) - \brief Undocumented. TODO. - - TODO: In both the dos and the bfs implementations this thing simply returns + \brief Undocumented. TODO. + + TODO: In both the dos and the bfs implementations this thing simply returns false... Is there anything more to it? */ @@ -442,64 +431,64 @@ //! @{ /*! - \fn status_t (*file_system_module_info::ioctl)(fs_volume fs, fs_vnode vnode, + \fn status_t (*file_system_module_info::ioctl)(fs_volume fs, fs_vnode vnode, fs_cookie 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 - handy for debugging purposes. There are no obligatory operations for you to - implement. - - 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 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. - \param buffer A buffer (if applicable). - \param length The size of the buffer. + \brief Perform file system specific operations. + + You can implement a customized API using this call. This can be extremely + handy for debugging purposes. There are no obligatory operations for you to + implement. + + 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 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. + \param buffer A buffer (if applicable). + \param length The size of the buffer. \return You should return any of your status codes. */ /*! - \fn status_t (*file_system_module_info::set_flags)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::set_flags)(fs_volume fs, fs_vnode vnode, fs_cookie 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 cookie The file system provided cookie associated with the opened - file. - \param flags The new 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 cookie The file system provided cookie associated with the opened + file. + \param flags The new flags. \return \c B_OK if the operation succeeded, or else an error code. */ /*! \fn status_t (*file_system_module_info::select)(fs_volume fs, fs_vnode vnode, fs_cookie cookie, uint8 event, uint32 ref, selectsync *sync) - \brief Undocumented. TODO. - + \brief Undocumented. TODO. + TODO: What should this do? */ /*! \fn status_t (*file_system_module_info::deselect)(fs_volume fs, fs_vnode vnode, fs_cookie cookie, uint8 event, selectsync *sync) - \brief Undocumented. TODO. - + \brief Undocumented. TODO. + TODO: What should this do? */ /*! \fn status_t (*file_system_module_info::fsync)(fs_volume fs, 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. + \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. \return \c B_OK if the operation succeeded, or else an error code. */ @@ -526,84 +515,84 @@ */ /*! - \fn status_t (*file_system_module_info::create_symlink)(fs_volume fs, + \fn status_t (*file_system_module_info::create_symlink)(fs_volume fs, fs_vnode dir, const char *name, const char *path, int mode) - \brief Create a new symbolic link. - - Your implementation should check if the user has permission to perform this - operation. - - \param fs The file system provided cookie associated with this volume. - \param dir The file system provided cookie associated with the directory - the symbolic link should be created in. - \param name The name of the new symbolic link. - \param path The path of the original inode the symbolic link should refer to. - \param mode The mode that this symbolic link should be created in. (TODO - what exactly?) + \brief Create a new symbolic link. + + Your implementation should check if the user has permission to perform this + operation. + + \param fs The file system provided cookie associated with this volume. + \param dir The file system provided cookie associated with the directory + the symbolic link should be created in. + \param name The name of the new symbolic link. + \param path The path of the original inode the symbolic link should refer to. + \param mode The mode that this symbolic link should be created in. (TODO + what exactly?) \return \c B_OK if you succeeded, or an error code if you failed. */ /*! - \fn status_t (*file_system_module_info::link)(fs_volume fs, fs_vnode dir, + \fn status_t (*file_system_module_info::link)(fs_volume fs, fs_vnode dir, const char *name, fs_vnode vnode) - \brief Create a new hard link. - - You should make sure the user has the proper permissions. - - The virtual file system will request the creation of symbolic links with - create_symlink(). - - \param fs The file system provided cookie associated with this volume. - \param dir The cookie associated to the directory where the link should be - saved. - \param name The name the link should have. - \param vnode The vnode the new link should resolve to. - \retval B_OK The hard link is properly created. - \retval B_NOT_ALLOWED The user does not have the proper permissions. - \retval "other errors" Another error occured. -*/ - -/*! - \fn status_t (*file_system_module_info::unlink)(fs_volume fs, fs_vnode dir, - const char *name) - \brief Remove a node or directory. - - You should make sure the user has the proper permissions. - - \param fs The file system provided cookie associated with this volume. - \param dir The parent directory of the node that should be removed. - \param name The name of the node that should be deleted. - \retval B_OK Removal succeeded. - \retval B_ENTRY_NOT_FOUND The entry does not exist. - \retval B_NOT_ALLOWED The user does not have the proper permissions. - \retval B_DIRECTORY_NOT_EMPTY The \a name refers to a directory. The virtual - file system expects directories to be emptied before they can be unlinked. + \brief Create a new hard link. + + You should make sure the user has the proper permissions. + + The virtual file system will request the creation of symbolic links with + create_symlink(). + + \param fs The file system provided cookie associated with this volume. + \param dir The cookie associated to the directory where the link should be + saved. + \param name The name the link should have. + \param vnode The vnode the new link should resolve to. + \retval B_OK The hard link is properly created. + \retval B_NOT_ALLOWED The user does not have the proper permissions. \retval "other errors" Another error occured. */ /*! - \fn status_t (*file_system_module_info::rename)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::unlink)(fs_volume fs, fs_vnode dir, + const char *name) + \brief Remove a node or directory. + + You should make sure the user has the proper permissions. + + \param fs The file system provided cookie associated with this volume. + \param dir The parent directory of the node that should be removed. + \param name The name of the node that should be deleted. + \retval B_OK Removal succeeded. + \retval B_ENTRY_NOT_FOUND The entry does not exist. + \retval B_NOT_ALLOWED The user does not have the proper permissions. + \retval B_DIRECTORY_NOT_EMPTY The \a name refers to a directory. The virtual + file system expects directories to be emptied before they can be unlinked. + \retval "other errors" Another error occured. +*/ + +/*! + \fn status_t (*file_system_module_info::rename)(fs_volume fs, fs_vnode fromDir, const char *fromName, fs_vnode toDir, const char *toName) - \brief Rename and/or relocate a vnode. - - The virtual file system merely relays the request, so make sure the user is - not changing the file name to something like '.', '..' or anything starting - with '/'. - - This also means that it if the node is a directory, that it should not be - moved into one of its own children. - - You should also make sure the user has the proper permissions. - - \param fs The file system provided cookie associated with this volume. - \param fromDir The cookie of the parent directory the vnode should be moved - from. - \param fromName The old name of the node. - \param toDir The cookie of the parent directory the vnode should be moved to. - \param toName The new name of the node. - \retval B_OK The renaming and relocating succeeded. - \retval B_BAD_VALUE One of the supplied parameters were invalid. - \retval B_NOT_ALLOWED The user does not have the proper permissions. + \brief Rename and/or relocate a vnode. + + The virtual file system merely relays the request, so make sure the user is + not changing the file name to something like '.', '..' or anything starting + with '/'. + + This also means that it if the node is a directory, that it should not be + moved into one of its own children. + + You should also make sure the user has the proper permissions. + + \param fs The file system provided cookie associated with this volume. + \param fromDir The cookie of the parent directory the vnode should be moved + from. + \param fromName The old name of the node. + \param toDir The cookie of the parent directory the vnode should be moved to. + \param toName The new name of the node. + \retval B_OK The renaming and relocating succeeded. + \retval B_BAD_VALUE One of the supplied parameters were invalid. + \retval B_NOT_ALLOWED The user does not have the proper permissions. \retval "other errors" Another error condition was encountered. */ @@ -658,20 +647,20 @@ */ /*! - \fn status_t (*file_system_module_info::write_stat)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::write_stat)(fs_volume fs, fs_vnode vnode, const struct stat *stat, uint32 statMask) - \brief Update the stats for a vnode. - - You should make sure that the new values are valid and that the user has the - proper permissions to update the stats. - - \param fs The file system provided cookie to the volume. - \param vnode The cookie to the vnode. - \param stat The structure with the updated values. - \param statMask One of the #write_stat_mask enumeration, which forms a mask - of which of the values in \a stat should actually be updated. - \retval B_OK The update succeeded. - \retval B_NOT_ALLOWED The user does not have the proper permissions. + \brief Update the stats for a vnode. + + You should make sure that the new values are valid and that the user has the + proper permissions to update the stats. + + \param fs The file system provided cookie to the volume. + \param vnode The cookie to the vnode. + \param stat The structure with the updated values. + \param statMask One of the #write_stat_mask enumeration, which forms a mask + of which of the values in \a stat should actually be updated. + \retval B_OK The update succeeded. + \retval B_NOT_ALLOWED The user does not have the proper permissions. \retval "other errors" Another error condition occured. */ @@ -684,30 +673,30 @@ //! @{ /*! - \fn status_t (*file_system_module_info::create)(fs_volume fs, fs_vnode dir, + \fn status_t (*file_system_module_info::create)(fs_volume fs, fs_vnode dir, const char *name, int openMode, int perms, fs_cookie *_cookie, ino_t *_newVnodeID) - \brief Create a new file. - - Your implementation shall check whether it is possible to create the node. - You will need to take the user's permissions into account. When you create - a new file, you will also have to open it. This means also checking the - permissions the user requires to open the file according to the \a mode. - See \link file_system_module_info::open() open() \endlink for the possible - values of \a mode. - - \param fs The file system provided cookie associated with this volume. - \param dir The file system provided cookie associated with the directory - where the file should appear. - \param name The name of the new file. - \param openMode The mode associated to the file. - \param perms The permissions the new file should have. - \param[out] _cookie In case of success, the you can store your file system - data for this node in this variable. - \param[out] _newVnodeID In case of success, you can store the new vnode id - in this variable. - \return You should return \c B_OK if creating the new node succeeded, and if - you put data in both \a _cookie and \a _newVnodeID. Else you should return + \brief Create a new file. + + Your implementation shall check whether it is possible to create the node. + You will need to take the user's permissions into account. When you create + a new file, you will also have to open it. This means also checking the + permissions the user requires to open the file according to the \a mode. + See \link file_system_module_info::open() open() \endlink for the possible + values of \a mode. + + \param fs The file system provided cookie associated with this volume. + \param dir The file system provided cookie associated with the directory + where the file should appear. + \param name The name of the new file. + \param openMode The mode associated to the file. + \param perms The permissions the new file should have. + \param[out] _cookie In case of success, the you can store your file system + data for this node in this variable. + \param[out] _newVnodeID In case of success, you can store the new vnode id + in this variable. + \return You should return \c B_OK if creating the new node succeeded, and if + you put data in both \a _cookie and \a _newVnodeID. Else you should return an error code. */ @@ -799,29 +788,29 @@ */ /*! - \fn status_t (*file_system_module_info::write)(fs_volume fs, fs_vnode vnode, + \fn status_t (*file_system_module_info::write)(fs_volume fs, fs_vnode vnode, fs_cookie cookie, off_t pos, const void *buffer, size_t *length) - \brief Write data to a file. - - This function should fail if - - the node is not a file, - - the cookie has not been opened for writing, - - \a pos is negative, or - - some other error occurs while trying to read the data, and no data have - been read at all. - - The number of bytes to be written is stored in the variable pointed to by - \a length. - - TODO: What to do if we were to write less than the \a length? Should this - function fail? - - \param fs The file system provided cookie associated with this volume. - \param vnode The file system provided cookie associated with the vnode. - \param cookie The file system provided cookie associated with the file. - \param pos The position to start writing. - \param buffer The buffer that contains the data that will need to be written. - \param length The length of the data that needs to be written. + \brief Write data to a file. + + This function should fail if + - the node is not a file, + - the cookie has not been opened for writing, + - \a pos is negative, or + - some other error occurs while trying to read the data, and no data have + been read at all. + + The number of bytes to be written is stored in the variable pointed to by + \a length. + + TODO: What to do if we were to write less than the \a length? Should this + function fail? + + \param fs The file system provided cookie associated with this volume. + \param vnode The file system provided cookie associated with the vnode. + \param cookie The file system provided cookie associated with the file. + \param pos The position to start writing. + \param buffer The buffer that contains the data that will need to be written. + \param length The length of the data that needs to be written. \return \c B_OK if everything went fine, another error code otherwise. */ @@ -832,45 +821,45 @@ */ /*! - \fn status_t (*file_system_module_info::create_dir)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::create_dir)(fs_volume fs, fs_vnode parent, const char *name, int perms, ino_t *_newVnodeID) - \brief Create a new directory. - - Your implementation should make sure that the directory actually can be - created in the \a parent directory. You will have to check if the user has - permissions to actually write to the \a parent. If not, this function should - fail (probably with \c B_NOT_ALLOWED, or in case of a read-only filesystem, - with \c B_READ_ONLY_DEVICE). If the operation succeeds, you should put the - new vnode id in \a _newVnodeID. - - \param fs The file system provided cookie associated with this volume. - \param parent The file system provided cookie associated with the parent - node. - \param name The name the new directory should have. - \param perms The permissions the new directory should have. - \param[out] _newVnodeID If creating the directory succeeds, than you should - put the new vnode id in this variable. - \return If the operation succeeds and the \a _newVnodeID is populated with - the new vnode, then you should return \c B_OK. Else you should return with + \brief Create a new directory. + + Your implementation should make sure that the directory actually can be + created in the \a parent directory. You will have to check if the user has + permissions to actually write to the \a parent. If not, this function should + fail (probably with \c B_NOT_ALLOWED, or in case of a read-only filesystem, + with \c B_READ_ONLY_DEVICE). If the operation succeeds, you should put the + new vnode id in \a _newVnodeID. + + \param fs The file system provided cookie associated with this volume. + \param parent The file system provided cookie associated with the parent + node. + \param name The name the new directory should have. + \param perms The permissions the new directory should have. + \param[out] _newVnodeID If creating the directory succeeds, than you should + put the new vnode id in this variable. + \return If the operation succeeds and the \a _newVnodeID is populated with + the new vnode, then you should return \c B_OK. Else you should return with an error code. */ /*! - \fn status_t (*file_system_module_info::remove_dir)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::remove_dir)(fs_volume fs, fs_vnode parent, const char *name) - \brief Remove a directory. - - You should make sure the user has the proper permissions. You should also - check that the directory is empty. - - \param fs The file system provided cookie associated with this volume. - \param parent The file system provided cookie associated with the parent - node. - \param name The \a name of the directory that needs to be removed. - \retval B_OK Operation succeeded. - \retval B_DIRECTORY_NOT_EMPTY The directory is not empty. - \retval B_ENTRY_NOT_FOUND There is no directory with this \a name. - \retval B_NOT_A_DIRECTORY The entry is not a directory. + \brief Remove a directory. + + You should make sure the user has the proper permissions. You should also + check that the directory is empty. + + \param fs The file system provided cookie associated with this volume. + \param parent The file system provided cookie associated with the parent + node. + \param name The \a name of the directory that needs to be removed. + \retval B_OK Operation succeeded. + \retval B_DIRECTORY_NOT_EMPTY The directory is not empty. + \retval B_ENTRY_NOT_FOUND There is no directory with this \a name. + \retval B_NOT_A_DIRECTORY The entry is not a directory. \retval "other errors" Other errors occured. */ @@ -987,63 +976,63 @@ //! @{ /*! - \fn status_t (*file_system_module_info::open_attr_dir)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::open_attr_dir)(fs_volume fs, fs_vnode vnode, fs_cookie *_cookie) - \brief Open a 'directory' of attributes for a \a vnode. - - See \ref concepts "Generic Concepts" on directories and iterators. Basically, - the VFS uses the same way of traversing through attributes as it traverses - through a directory. - - \param fs The file system provided cookie to the volume. - \param vnode The vnode on which the file system wants to read the attributes. - \param[out] _cookie Pointer where the file system can store a directory - cookie if the attribute directory is succesfully opened. + \brief Open a 'directory' of attributes for a \a vnode. + + See \ref concepts "Generic Concepts" on directories and iterators. Basically, + the VFS uses the same way of traversing through attributes as it traverses + through a directory. + + \param fs The file system provided cookie to the volume. + \param vnode The vnode on which the file system wants to read the attributes. + \param[out] _cookie Pointer where the file system can store a directory + cookie if the attribute directory is succesfully opened. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::close_attr_dir)(fs_volume fs, + \fn status_t (*file_system_module_info::close_attr_dir)(fs_volume fs, fs_vnode vnode, fs_cookie cookie) - \brief Close a 'directory' of attributes for a \a vnode. - - Note that you should free the cookie in the free_attr_dir_cookie() call. - - \param fs The file system provided cookie to the volume. - \param vnode The vnode on which the 'directory' was opened. - \param cookie The cookie associated with this 'directory'. + \brief Close a 'directory' of attributes for a \a vnode. + + Note that you should free the cookie in the free_attr_dir_cookie() call. + + \param fs The file system provided cookie to the volume. + \param vnode The vnode on which the 'directory' was opened. + \param cookie The cookie associated with this 'directory'. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::free_attr_dir_cookie)(fs_volume fs, + \fn status_t (*file_system_module_info::free_attr_dir_cookie)(fs_volume fs, fs_vnode vnode, fs_cookie cookie) - \brief Free the \a cookie to an attribute 'directory'. - - \param fs The file system provided cookie to the volume. - \param vnode The vnode on which the 'directory' was opened. - \param cookie The cookie associated that should be freed. + \brief Free the \a cookie to an attribute 'directory'. + + \param fs The file system provided cookie to the volume. + \param vnode The vnode on which the 'directory' was opened. + \param cookie The cookie associated that should be freed. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::read_attr_dir)(fs_volume fs, fs_vnode - vnode, fs_cookie cookie, struct dirent *buffer, size_t bufferSize, + \fn status_t (*file_system_module_info::read_attr_dir)(fs_volume fs, fs_vnode + vnode, fs_cookie cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num) - \brief Read the next one or more attribute directory entries. - - This method should perform the same tasks as read_dir(), except that the '.' + \brief Read the next one or more attribute directory entries. + + This method should perform the same tasks as read_dir(), except that the '.' and '..' entries do not have to be present. */ /*! - \fn status_t (*file_system_module_info::rewind_attr_dir)(fs_volume fs, + \fn status_t (*file_system_module_info::rewind_attr_dir)(fs_volume fs, fs_vnode vnode, fs_cookie cookie) - \brief Rewind the attribute directory iterator to the first entry. - - \param fs The file system provided cookie to the volume. - \param vnode The vnode on which the 'directory' was opened. - \param cookie The cookie associated with this 'directory'. + \brief Rewind the attribute directory iterator to the first entry. + + \param fs The file system provided cookie to the volume. + \param vnode The vnode on which the 'directory' was opened. + \param cookie The cookie associated with this 'directory'. \return \c B_OK if everything went fine, another error code otherwise. */ @@ -1056,154 +1045,154 @@ //! @{ /*! - \fn status_t (*file_system_module_info::create_attr)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::create_attr)(fs_volume fs, fs_vnode vnode, const char *name, uint32 type, int openMode, fs_cookie *_cookie) - \brief Create a new attribute. - - If the attribute already exists, you should open it in truncated mode. - - \param fs The file system provided cookie to the volume. - \param vnode The file system provided cookie to the vnode. - \param name The name of the attribute. - \param type The \c type_code of the attribute. - \param openMode The openMode of the associated attribute. - \param[out] _cookie A pointer where you can store an associated file system - cookie. + \brief Create a new attribute. + + If the attribute already exists, you should open it in truncated mode. + + \param fs The file system provided cookie to the volume. + \param vnode The file system provided cookie to the vnode. + \param name The name of the attribute. + \param type The \c type_code of the attribute. + \param openMode The openMode of the associated attribute. + \param[out] _cookie A pointer where you can store an associated file system + cookie. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::open_attr)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::open_attr)(fs_volume fs, fs_vnode vnode, const char *name, int openMode, fs_cookie *_cookie) - \brief Open an existing attribute. - - \param fs The file system provided cookie to the volume. - \param vnode The file system provided cookie to the vnode. - \param name The name of the attribute. - \param openMode The mode in which you want to open the attribute data. - \param[out] _cookie A pointer where you can store an associated file system - cookie. + \brief Open an existing attribute. + + \param fs The file system provided cookie to the volume. + \param vnode The file system provided cookie to the vnode. + \param name The name of the attribute. + \param openMode The mode in which you want to open the attribute data. + \param[out] _cookie A pointer where you can store an associated file system + cookie. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::close_attr)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::close_attr)(fs_volume fs, fs_vnode vnode, fs_cookie cookie) - \brief Close access to an attribute. - - Note that you should not delete the cookie yet, you should do that when the - VFS calls free_attr_cookie(). - - \param fs The file system provided cookie to the volume. - \param vnode The file system provided cookie to the vnode. - \param cookie The cookie you associated to this attribute. + \brief Close access to an attribute. + + Note that you should not delete the cookie yet, you should do that when the + VFS calls free_attr_cookie(). + + \param fs The file system provided cookie to the volume. + \param vnode The file system provided cookie to the vnode. + \param cookie The cookie you associated to this attribute. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::free_attr_cookie)(fs_volume fs, + \fn status_t (*file_system_module_info::free_attr_cookie)(fs_volume fs, fs_vnode vnode, fs_cookie cookie) - \brief Free the cookie of an attribute. - - The VFS calls this hook when all operations on the attribute have ceased. - - \param fs The file system provided cookie to the volume. - \param vnode The file system provided cookie to the vnode. - \param cookie The cookie to the attribute that should be freed. + \brief Free the cookie of an attribute. + + The VFS calls this hook when all operations on the attribute have ceased. + + \param fs The file system provided cookie to the volume. + \param vnode The file system provided cookie to the vnode. + \param cookie The cookie to the attribute that should be freed. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::read_attr)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::read_attr)(fs_volume fs, fs_vnode vnode, fs_cookie cookie, off_t pos, void *buffer, size_t *length) - \brief Read attribute data associated with \a cookie. - - Read until the \a buffer with size \a length is full, or until you are out of - data, in which case you should update \a length. - - \param fs The file system provided cookie to the volume. - \param vnode The file system provided cookie to the vnode. - \param cookie The cookie you associated to this attribute. - \param pos The position to start reading from. - \param buffer The buffer the data should be copied in. - \param length The length of the buffer. Update this variable to the actual - amount of bytes read. + \brief Read attribute data associated with \a cookie. + + Read until the \a buffer with size \a length is full, or until you are out of + data, in which case you should update \a length. + + \param fs The file system provided cookie to the volume. + \param vnode The file system provided cookie to the vnode. + \param cookie The cookie you associated to this attribute. + \param pos The position to start reading from. + \param buffer The buffer the data should be copied in. + \param length The length of the buffer. Update this variable to the actual + amount of bytes read. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::write_attr)(fs_volume fs, fs_vnode + \fn status_t (*file_system_module_info::write_attr)(fs_volume fs, fs_vnode vnode, fs_cookie cookie, off_t pos, const void *buffer, size_t *length) - \brief Write attribute data associated with \a cookie. - - \param fs The file system provided cookie to the volume. - \param vnode The file system provided cookie to the vnode. - \param cookie The cookie you associated with this attribute. - \param pos The position to start writing to. - \param buffer The buffer the data should be copied from. - \param length The size of the buffer. Update this variable to the actual - amount of bytes written. + \brief Write attribute data associated with \a cookie. + + \param fs The file system provided cookie to the volume. + \param vnode The file system provided cookie to the vnode. + \param cookie The cookie you associated with this attribute. + \param pos The position to start writing to. + \param buffer The buffer the data should be copied from. + \param length The size of the buffer. Update this variable to the actual + amount of bytes written. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::read_attr_stat)(fs_volume fs, + \fn status_t (*file_system_module_info::read_attr_stat)(fs_volume fs, fs_vnode vnode, fs_cookie cookie, struct stat *stat) - \brief Get the stats for an attribute. - - \param fs The file system provided cookie to the volume. - \param vnode The file system provided cookie to the vnode. - \param cookie The cookie you associated with this attribute. - \param stat A pointer to a stat structure you should fill. + \brief Get the stats for an attribute. + + \param fs The file system provided cookie to the volume. + \param vnode The file system provided cookie to the vnode. + \param cookie The cookie you associated with this attribute. + \param stat A pointer to a stat structure you should fill. \return \c B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::write_attr_stat)(fs_volume fs, + \fn status_t (*file_system_module_info::write_attr_stat)(fs_volume fs, fs_vnode vnode, fs_cookie cookie, const struct stat *stat, int statMask) - \brief Update the stats of an attribute. - - \param fs The file system provided cookie to the volume. - \param vnode The file system provided cookie to the vnode. - \param cookie The cookie you associated with this attribute. - \param stat A pointer to the new stats you should write. - \param statMask One or more of the values of #write_stat_mask that tell you + \brief Update the stats of an attribute. + + \param fs The file system provided cookie to the volume. + \param vnode The file system provided cookie to the vnode. + \param cookie The cookie you associated with this attribute. + \param stat A pointer to the new stats you should write. + \param statMask One or more of the values of #write_stat_mask that tell you which fields of \a stat are to be updated. - \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 (*file_system_module_info::rename_attr)(fs_volume fs, - fs_vnode fromVnode, const char *fromName, fs_vnode toVnode, + \fn status_t (*file_system_module_info::rename_attr)(fs_volume fs, + fs_vnode fromVnode, const char *fromName, fs_vnode toVnode, const char *toName) - \brief Rename and/or relocate an attribute. - - You should make sure the user has the proper permissions. - - \param fs The file system provided cookie associated with this volume. - \param fromVnode The cookie associated with the vnode the attribute currently - is related to. - \param fromName The old name of the attribute. - \param toVnode The cookie associated with the vnode the attribute should be - moved to. This can be the same as \a fromVnode, in which case it only means - the attribute should be renamed. - \param toName The new name of the attribute.This can be the same as - \a fromName, in which case it only means the attribute should be relocated. - \retval B_OK The renaming and/or relocating succeeded. - \retval B_BAD_VALUE One of the supplied parameters were invalid. - \retval B_NOT_ALLOWED The user does not have the proper permissions. + \brief Rename and/or relocate an attribute. + + You should make sure the user has the proper permissions. + + \param fs The file system provided cookie associated with this volume. + \param fromVnode The cookie associated with the vnode the attribute currently + is related to. + \param fromName The old name of the attribute. + \param toVnode The cookie associated with the vnode the attribute should be + moved to. This can be the same as \a fromVnode, in which case it only means + the attribute should be renamed. + \param toName The new name of the attribute.This can be the same as + \a fromName, in which case it only means the attribute should be relocated. + \retval B_OK The renaming and/or relocating succeeded. + \retval B_BAD_VALUE One of the supplied parameters were invalid. + \retval B_NOT_ALLOWED The user does not have the proper permissions. \retval "other errors" Another error condition was encountered. */ /*! - \fn status_t (*file_system_module_info::remove_attr)(fs_volume fs, + \fn status_t (*file_system_module_info::remove_attr)(fs_volume fs, fs_vnode vnode, const char *name) - \brief Remove an attribute. - - \param fs The file system provided cookie to the volume. - \param vnode The file system provided cookie to the vnode. + \brief Remove an attribute. + + \param fs The file system provided cookie to the volume. + \param vnode The file system provided cookie to the vnode. \param name The name of the attribute. - \return \c B_OK if everything went fine, another error code otherwise. + \return \c B_OK if everything went fine, another error code otherwise. */ //! @} @@ -1215,103 +1204,103 @@ //! @{ /*! - \fn status_t (*file_system_module_info::open_index_dir)(fs_volume fs, + \fn status_t (*file_system_module_info::open_index_dir)(fs_volume fs, fs_cookie *_cookie) - \brief Open the list of an indeces 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 fs The file system provided cookie to the volume. - \param[out] _cookie Pointer where the file system can store a directory - cookie if the index directory is succesfully opened. + \brief Open the list of an indeces 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 fs The file system provided cookie to the volume. + \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 (*file_system_module_info::close_index_dir)(fs_volume fs, + \fn status_t (*file_system_module_info::close_index_dir)(fs_volume fs, fs_cookie cookie) - \brief Close a 'directory' of indeces. - - Note that you should free the cookie in the free_index_dir_cookie() call.: - - \param fs The file system provided cookie to the volume. - \param cookie The cookie associated with this 'directory'. - \return B_OK if everything went fine, another error code otherwise. -*/ + \brief Close a 'directory' of indeces. -/*! - \fn status_t (*file_system_module_info::free_index_dir_cookie)(fs_volume fs, - fs_cookie cookie) - \brief Free the \a cookie to the index 'directory'. - - \param fs The file system provided cookie for the volume. - \param cookie The cookie that should be freed. + Note that you should free the cookie in the free_index_dir_cookie() call.: + + \param fs The file system provided cookie to the volume. + \param cookie The cookie associated with this 'directory'. \return B_OK if everything went fine, another error code otherwise. */ /*! - \fn status_t (*file_system_module_info::read_index_dir)(fs_volume fs, + \fn status_t (*file_system_module_info::free_index_dir_cookie)(fs_volume fs, + fs_cookie cookie) + \brief Free the \a cookie to the index 'directory'. + + \param fs The file system provided cookie for the volume. + \param cookie The cookie that should be freed. + \return B_OK if everything went fine, another error code otherwise. +*/ + +/*! + \fn status_t (*file_system_module_info::read_index_dir)(fs_volume fs, fs_cookie 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 read_dir(), except that the '.' + \brief Read the next one or more index entries. + + This method should perform the same task as read_dir(), except that the '.' and the '..' entries don't have to be present. */ /*! - \fn status_t (*file_system_module_info::rewind_index_dir)(fs_volume fs, + \fn status_t (*file_system_module_info::rewind_index_dir)(fs_volume fs, fs_cookie cookie) - \brief Reset the index directory cookie to the first entry of the directory. - - \param fs The file system provided handle to the volume. - \param cookie The directory cookie as returned by open_index_dir(). + \brief Reset the index directory cookie to the first entry of the directory. + + \param fs The file system provided handle to the volume. + \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 (*file_system_module_info::create_index)(fs_volume fs, + \fn status_t (*file_system_module_info::create_index)(fs_volume fs, const char *name, uint32 type, uint32 flags) - \brief Create a new index. - - \param fs The file system provided handle to the volume. - \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 + \brief Create a new index. + + \param fs The file system provided handle to the volume. + \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 (*file_system_module_info::remove_index)(fs_volume fs, + \fn status_t (*file_system_module_info::remove_index)(fs_volume fs, const char *name) - \brief Remove the index with \a name. - - \param fs The file system provided handle to the volume. - \param name The name of the index to be removed. - \return You should return \c B_OK if the creation succeeded, or return an + \brief Remove the index with \a name. + + \param fs The file system provided handle to the volume. + \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 (*file_system_module_info::read_index_stat)(fs_volume fs, + \fn status_t (*file_system_module_info::read_index_stat)(fs_volume fs, const char *name, struct stat *stat) - \brief Read the \a stat of the index with a name. - - \param fs The file system provided handle to the volume. - \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 + \brief Read the \a stat of the index with a name. + + \param fs The file system provided handle to the volume. + \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. */ @@ -1324,61 +1313,61 @@ //! @{ /*! - \fn status_t (*file_system_module_info::open_query)(fs_volume fs, - const char *query, uint32 flags, port_id port, uint32 token, + \fn status_t (*file_system_module_info::open_query)(fs_volume fs, + const char *query, uint32 flags, port_id port, uint32 token, fs_cookie *_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 indeces as it traverses - through a directory. - - \param fs The file system provided cookie to the volume. - \param query The string that represents a query. - \param flags Either one of these flags: - - \c #B_LIVE_QUERY The query is live. When a query is live, it is - constantly updated using the \a port. In this case the file system should - be pro-active. - - \c #B_QUERY_NON_INDEXED When this parameter is provided, the query - should be carried out over the whole file system. This parameter is - provided with the idea that sometimes the indeces can be out of date. If - the requestor for this query requires absolutely everything to be - queried, it will pass this parameter. Of course, if your indeces are - always up to date, you can ignore this parameter. - \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 + \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 indeces as it traverses + through a directory. + + \param fs The file system provided cookie to the volume. + \param query The string that represents a query. + \param flags Either one of these flags: + - \c #B_LIVE_QUERY The query is live. When a query is live, it is + constantly updated using the \a port. In this case the file system should + be pro-active. + - \c #B_QUERY_NON_INDEXED When this parameter is provided, the query + should be carried out over the whole file system. This parameter is + provided with the idea that sometimes the indeces can be out of date. If + the requestor for this query requires absolutely everything to be + queried, it will pass this parameter. Of course, if your indeces are + always up to date, you can ignore this parameter. + \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 (*file_system_module_info::close_query)(fs_volume fs, + \fn status_t (*file_system_module_info::close_query)(fs_volume fs, fs_cookie cookie) - \brief Close a 'directory' of a query. - - Note that you should free the cookie in the free_query_cookie() call. - - \param fs The file system provided cookie to the volume. - \param cookie The cookie that refers to this query. - \return You should return \c B_OK if the creation succeeded, or return an + \brief Close a 'directory' of a query. + + Note that you should free the cookie in the free_query_cookie() call. + + \param fs The file system provided cookie to the volume. + \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 (*file_system_module_info::free_query_cookie)(fs_volume fs, + \fn status_t (*file_system_module_info::free_query_cookie)(fs_volume fs, fs_cookie cookie) - \brief Free a cookie of a query. - - \param fs The file system provided cookie to the volume. - \param cookie The cookie that should be freed. - \return You should return \c B_OK if the creation succeeded, or return an + \brief Free a cookie of a query. + + \param fs The file system provided cookie to the volume. + \param cookie The cookie that should be freed. + \return You should return \c B_OK if the creation succeeded, or return an error otherwise. */ @@ -1403,13 +1392,13 @@ */ /*! - \fn status_t (*file_system_module_info::rewind_query)(fs_volume fs, + \fn status_t (*file_system_module_info::rewind_query)(fs_volume fs, fs_cookie cookie) - \brief Reset the query cookie to the first entry of the results. - - \param fs The file system provided handle to the volume. - \param cookie The query cookie as returned by open_query(). - \return \c B_OK if everything went fine, another error code otherwise. + \brief Reset the query cookie to the first entry of the results. + + \param fs The file system provided handle to the volume. + \param cookie The query cookie as returned by open_query(). + \return \c B_OK if everything went fine, another error code otherwise. */ //! @} @@ -1421,7 +1410,7 @@ //! @{ /*! - \fn bool (*file_system_module_info::supports_defragmenting)(partition_data + \fn bool (*file_system_module_info::supports_defragmenting)(partition_data *partition, bool *whileMounted) \brief Undocumented. TODO. */ @@ -1554,185 +1543,190 @@ //! @} -///// Global Functions ///// - -/*! - \fn status_t new_vnode(dev_t mountID, ino_t vnodeID, - fs_vnode privateNode) - \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. - - The effect of the function is similar to publish_vnode(), but the vnode - 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 - \link file_system_module_info::remove_vnode remove_vnode() \endlink is not - invoked. - - 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 - publish_vnode(). - - The function fails, if the vnode does already exist. - - \param mountID The ID of the volume. - \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, - fs_vnode privateNode) - \brief Creates the vnode with ID \a vnodeID and associates it with the - private data handle \a privateNode or just marks it published. - - 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 - function just marks the vnode published. If the vnode did not exist at all - before, it is created and published. - - 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 - well. The reference can be surrendered by calling put_vnode(). - - \param mountID The ID of the volume. - \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, - fs_vnode *_privateNode) - \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 - reference can be surrendered by calling put_vnode(). - - \param mountID The ID of the volume. - \param vnodeID The ID of the node. - \param _privateNode Pointer to a pre-allocated variable the private data - handle shall be written to. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t put_vnode(dev_t mountID, ino_t vnodeID) - \brief Surrenders a reference to the specified vnode. - \param mountID The ID of the volume. - \param vnodeID The ID of the node. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t remove_vnode(dev_t mountID, ino_t vnodeID) - \brief Marks the specified vnode removed. - - 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, - though. - - As soon as the last reference to the vnode has been surrendered, the VFS - invokes the file system's - \link file_system_module_info::remove_vnode remove_vnode() \endlink - hook. - - \param mountID The ID of the volume. - \param vnodeID The ID of the node. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t unremove_vnode(dev_t mountID, ino_t vnodeID); - \brief Clears the "removed" mark of the specified vnode. - - The caller must own a reference to the vnode or at least ensure that a - reference to the vnode exists. - - The function is usually called when the caller, who has invoked - remove_vnode() before realizes that it is not possible to remove the node - (e.g. due to an error). - - \param mountID The ID of the volume. - \param vnodeID The ID of the node. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t get_vnode_removed(dev_t mountID, ino_t vnodeID, - bool* 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 - reference to the vnode exists. - - \param mountID The ID of the volume. - \param vnodeID The ID of the node. - \param removed Pointer to a pre-allocated variable set to \c true, if the - node is marked removed, to \c false otherwise. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -///// Deprecated Global Functions - -/*! - \name Deprecated functions - - The following list of functions should not be used, and could be removed even - before the release of Haiku R1. -*/ - -//! @{ - -/*! - \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, - const char *name, ino_t node) - \brief Deprecated. This feature will be removed in future versions. -*/ - -/*! - \fn status_t notify_entry_removed(dev_t device, ino_t directory, - const char *name, ino_t node) - \brief Deprecated. This feature will be removed in future versions. -*/ - -/*! - \fn status_t notify_entry_moved(dev_t device, ino_t fromDirectory, - const char *fromName, ino_t toDirectory, - const char *toName, ino_t node) - \brief Deprecated. This feature will be removed in future versions. -*/ - -/*! - \fn status_t notify_stat_changed(dev_t device, ino_t node, - uint32 statFields) - \brief Deprecated. This feature will be removed in future versions. -*/ - -/*! - \fn status_t notify_attribute_changed(dev_t device, ino_t node, - const char *attribute, int32 cause) - \brief Deprecated. This feature will be removed in future versions. -*/ - -/*! - \fn status_t notify_query_entry_created(port_id port, int32 token, - dev_t device, ino_t directory, const char *name, - ino_t node) - \brief Deprecated. This feature will be removed in future versions. -*/ - -/*! - \fn status_t notify_query_entry_removed(port_id port, int32 token, - dev_t device, ino_t directory, const char *name, - ino_t node) - \brief Deprecated. This feature will be removed in future versions. -*/ - -//! @} +///// Vnode functions ///// + +/*! + \fn status_t new_vnode(dev_t mountID, ino_t vnodeID, + fs_vnode privateNode) + \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. + + The effect of the function is similar to publish_vnode(), but the vnode + 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 + \link file_system_module_info::remove_vnode remove_vnode() \endlink when + the final reference is put down. + + 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 + publish_vnode(). + + 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. + + The function fails, if the vnode does already exist. + + \param mountID The ID of the volume. + \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, + fs_vnode privateNode) + \brief Creates the vnode with ID \a vnodeID and associates it with the + private data handle \a privateNode or just marks it published. + + 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 + function just marks the vnode published. If the vnode did not exist at all + before, it is created and published. + + 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 + well. The reference can be surrendered by calling put_vnode(). + + This call is equivalent to the former R5 new_vnode() function. + + \param mountID The ID of the volume. + \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, + fs_vnode *_privateNode) + \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 + reference can be surrendered by calling put_vnode(). + + \param mountID The ID of the volume. + \param vnodeID The ID of the node. + \param _privateNode Pointer to a pre-allocated variable the private data + handle shall be written to. + \return \c B_OK if everything went fine, another error code otherwise. +*/ + +/*! + \fn status_t put_vnode(dev_t mountID, ino_t vnodeID) + \brief Surrenders a reference to the specified vnode. + \param mountID The ID of the volume. + \param vnodeID The ID of the node. + \return \c B_OK if everything went fine, another error code otherwise. +*/ + +/*! + \fn status_t remove_vnode(dev_t mountID, ino_t vnodeID) + \brief Marks the specified vnode removed. + + 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, + though. + + As soon as the last reference to the vnode has been surrendered, the VFS + invokes the file system's + \link file_system_module_info::remove_vnode remove_vnode() \endlink + hook. + + \param mountID The ID of the volume. + \param vnodeID The ID of the node. + \return \c B_OK if everything went fine, another error code otherwise. +*/ + +/*! + \fn status_t unremove_vnode(dev_t mountID, ino_t vnodeID); + \brief Clears the "removed" mark of the specified vnode. + + The caller must own a reference to the vnode or at least ensure that a + reference to the vnode exists. + + The function is usually called when the caller, who has invoked + remove_vnode() before realizes that it is not possible to remove the node + (e.g. due to an error). + + \param mountID The ID of the volume. + \param vnodeID The ID of the node. + \return \c B_OK if everything went fine, another error code otherwise. +*/ + +/*! + \fn status_t get_vnode_removed(dev_t mountID, ino_t vnodeID, + bool* 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 + reference to the vnode exists. + + \param mountID The ID of the volume. + \param vnodeID The ID of the node. + \param removed Pointer to a pre-allocated variable set to \c true, if the + node is marked removed, to \c false otherwise. + \return \c B_OK if everything went fine, another error code otherwise. +*/ + +///// Notification Functions + +/*! + \name Notification Functions + + The following functions are used to implement the node monitor functionality + 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_entry_created(dev_t device, ino_t directory, + const char *name, ino_t node) + \brief Notifies listeners that a file system entry has been created. +*/ + +/*! + \fn status_t notify_entry_removed(dev_t device, ino_t directory, + const char *name, ino_t node) + \brief Notifies listeners that a file system entry has been removed. +*/ + +/*! + \fn status_t notify_entry_moved(dev_t device, ino_t fromDirectory, + const char *fromName, ino_t toDirectory, + const char *toName, ino_t node) + \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, + uint32 statFields) + \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, + const char *attribute, int32 cause) + \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, + dev_t device, ino_t directory, const char *name, + ino_t node) + \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, + dev_t device, ino_t directory, const char *name, + ino_t node) + \brief Notifies listeners that an entry has left the result set of a live query. +*/ + +//! @}