diff --git a/docs/user/drivers/fs_interface.dox b/docs/user/drivers/fs_interface.dox deleted file mode 100644 index eaa3f5ad8b..0000000000 --- a/docs/user/drivers/fs_interface.dox +++ /dev/null @@ -1,1787 +0,0 @@ -/* - * Copyright 2007-2008 Haiku Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Ingo Weinhold - * Niels Sascha Reedijk - * Axel Dörfler - * - * Corresponds to: - * /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. -*/ - -///// 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. -*/ - -/*! - \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_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_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_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(). -*/ - -///// file_io_vec ///// - -/*! - \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::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 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 \endcode -*/ - -///// 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. -*/ - -/*! - \name Data members -*/ - -//! @{ - -/*! - \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. - - Note, if a system wide disk device type constant exists for your file system, - it should equal this identifier. -*/ - -//! @} - -/*! - \name Scanning -*/ - -//! @{ - -/*! - \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 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. -*/ - -//! @} - -/*! - \name General Operations -*/ - -//! @{ - -/*! - \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) - \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. - - 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. - - 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 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) - \brief Unmounts the given volume. - - Invoked by the VFS when it is asked to unmount the volume. The function must - free all resources associated with the mounted volume, including the volume - 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. - \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, - struct fs_info *info) - \brief Retrieves general information about the volume. - - The following fields of the \c fs_info structure need to be filled in: - - \c flags: Flags applying to the volume, e.g. \c B_FS_IS_READONLY, - \c B_FS_HAS_ATTR, etc. - - \c block_size: The size of blocks the volume data are organized in. - Meaningful mainly for disk-based FSs, other FSs should use some reasonable - value for computing \c total_blocks and \c free_blocks. - - \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 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 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 - error code will be ignored, though. -*/ - -/*! - \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. - \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. - - 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. -*/ - -//! @} - -/*! - \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) - \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. - - 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 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 - struct stat (bitwise anded with \c S_IFMT). - \retval B_OK Everything went fine. - \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. - - 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. - \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. -*/ - -/*! - \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) - \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 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) - \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 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. -*/ - -//! @} - -/*! - \name VM file access -*/ - -//! @{ - -/*! - \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 - false... Is there anything more to it? - This call might be removed in the future - it's currently unused. -*/ - -/*! - \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 (*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 Cache File Access -*/ - -//! @{ - -/*! - \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) - \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 - use it, its implementation is mandatory. - - TODO: complete me -*/ - -//! @} - -/*! - \name Standard Operations -*/ - -//! @{ - -/*! - \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. - \return You should return any of your status codes. -*/ - -/*! - \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. - \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 Selects the specified \a vnode with the specified \a events. - - This function is called by the VFS whenever select() or poll() is called on - a file descriptor that points to your file system. - - You have to check if the condition of the select() (ie. if there is data - available if event is B_SELECT_READ) is already satisfied, and call - notify_select_event() with the \a sync and \a ref arguments you retrieve - here. - - Additionally, when a vnode is selected this way, you have to call - 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. - - Note that while select() and the corresponding deselect() are invoked by the - same thread, notifications are usually generated by other threads. It is - your responsibility to make sure that notify_select_event() is never called - for a selectsync object for which deselect() has already returned. This is - commonly done by holding the same lock when invoking notify_select_event() - 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. -*/ - -/*! - \fn status_t (*file_system_module_info::deselect)(fs_volume fs, fs_vnode vnode, - fs_cookie 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. -*/ - -/*! - \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. - \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) - \brief Read the value of a symbolic link. - - If the function is successful, the symlink string shall be written to the - buffer. It does not need to be null-terminated. If the buffer is too small - to hold the complete string, only the first \c *_bufferSize bytes of the - string shall be written to the buffer; the buffer shall not be - null-terminated in this case. Furthermore the variable \a _bufferSize - 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 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 - of the buffer supplied to the function. Upon successful completion the - hook shall store the number of bytes actually written into the buffer - in the variable. - \retval B_OK Everything went fine. - \retval B_BAD_VALUE \a link does not identify a symbolic link. -*/ - -/*! - \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?) - \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, - 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(). - - If you don't implement this function, the VFS will return \c EROFS - when a hard link is requested. - - \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. - \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. - \retval "other errors" Another error condition was encountered. -*/ - -/*! - \fn status_t (*file_system_module_info::access)(fs_volume fs, fs_vnode vnode, - int mode) - \brief Checks whether the current user is allowed to access the node in the - specified way. - - \a mode is a bitwise combination of: - - \c R_OK: Read access. - - \c W_OK: Write access. - - \c X_OK: Execution. - - If the current user does not have any of the access permissions represented - by the set bits, the function shall return \c B_NOT_ALLOWED. As a special - case, if the volume is read-only and write access is requested, - \c B_READ_ONLY_DEVICE shall be returned. If the requested access mode - complies with the user's access permissions, the function shall return - \c B_OK. - - For most FSs the permissions a user has are defined by the \c st_mode, - \c st_uid, and \c st_gid fields of the node's stat data. As a special - exception, the root user (geteuid() == 0) does always have - read and write permissions, execution permission only when at least one of - the execution permission bits are set. - - \param fs The volume handle. - \param vnode The node handle. - \param mode The access mode mask. - \retval B_OK The user has the permissions to access the node in the requested - way. - \retval B_READ_ONLY_DEVICE The volume is read-only, but the write access has - been requested. - \retval B_NOT_ALLOWED The user does not have all permissions to access the - node in the requested way. -*/ - -/*! - \fn status_t (*file_system_module_info::read_stat)(fs_volume fs, - fs_vnode vnode, struct stat *stat) - \brief Retrieves the stat data for a given node. - - All values of the struct stat save \c st_dev, \c st_ino, \c st_rdev, - and \c st_type need to be filled in. - - \param fs The volume handle. - \param vnode The node handle. - \param stat Pointer to a pre-allocated variable the stat data shall be - written to. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \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. - \retval "other errors" Another error condition occured. -*/ - -//! @} - -/*! - \name File Operations -*/ - -//! @{ - -/*! - \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 - an error code. -*/ - -/*! - \fn status_t (*file_system_module_info::open)(fs_volume fs, fs_vnode vnode, - int openMode, fs_cookie *_cookie) - \brief Opens the given node. - - The function shall check whether it is possible to open the node according to - the mode specified by \c openMode (also considering the user's access - permissions), create a node cookie, and store it in the variable - \a _cookie points to. - - The open mode \a openMode is encoded in the same way as the parameter of the - POSIX function \c open(), i.e. it is either \c O_RDONLY, \c O_WRONLY, or - \c O_RDWR, bitwise or'ed with flags. The only relevant flags for this hook - are \c O_TRUNC and \c O_NONBLOCK. - - \param fs The volume handle. - \param vnode The node handle. - \param openMode The open mode. - \param _cookie Pointer to a pre-allocated variable the node cookie shall be - written to. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t (*file_system_module_info::close)(fs_volume fs, fs_vnode vnode, - fs_cookie cookie) - \brief Closes the given node cookie. - - The hook is invoked, when closing the node has been requested. At this point - other threads might still use the cookie, i.e. still execute hooks to which - the cookie has been passed. If the FS supports blocking I/O operations, this - hook should make sure to unblock all currently blocking threads performing - an operation using the cookie, and mark the cookie such that no further - threads will block using it. - - For many FSs this hook is a no-op - it's mandatory to be exported, though. - - \param fs The volume handle. - \param vnode The node handle. - \param cookie The node cookie as returned by open(). - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t (*file_system_module_info::free_cookie)(fs_volume fs, - fs_vnode vnode, fs_cookie cookie) - \brief Frees the given node cookie. - - The hook is invoked after close(), when no other thread uses or is going to - use the cookie. All resources associated with the cookie must be freed. - - \param fs The volume handle. - \param vnode The node handle. - \param cookie The node cookie as returned by open(). - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t (*file_system_module_info::read)(fs_volume fs, fs_vnode vnode, - fs_cookie cookie, off_t pos, void *buffer, size_t *length) - \brief Reads data from a file. - - This function should fail if - - the node is not a file, - - the cookie has not been opened for reading, - - \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 read is stored in the variable pointed to by - \a length. If less data is available at file position \a pos, or if \a pos - if greater than the size of the file, only as many data as available shall - be read, the function shall store the number of bytes actually read into the - variable pointed to by \a length, and return \c B_OK. - - \param fs The volume handle. - \param vnode The node handle. - \param cookie The node cookie as returned by open(). - \param pos The file position where to start reading data. - \param buffer Pointer to a pre-allocated buffer the read data shall be - written to. - \param length Pointer to a pre-allocated variable containing the size of the - buffer when invoked, and into which the size of the data actually read - shall be written. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \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. If not all bytes could be written, that variable must be updated - to reflect the amount of actually written bytes. If an error prevented - you from writing the full amount, an appropriate error code should be - returned. - - \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. -*/ - -//! @} - -/*! - \name Directory Operations -*/ - -/*! - \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 - an error code. -*/ - -/*! - \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. - \retval "other errors" Other errors occured. -*/ - -/*! - \fn status_t (*file_system_module_info::open_dir)(fs_volume fs, fs_vnode vnode, - fs_cookie *_cookie) - \brief Opens the given directory node. - - If the specified node is not a directory, or if the current user does not - have the permissions to read the directory, the function shall fail. - Otherwise it shall allocate a directory cookie and store it in the variable - \a _cookie points to. A subsequent read_dir() using the cookie shall start - reading the first entry of the directory. - - \param fs The volume handle. - \param vnode The node handle. - \param _cookie Pointer to a pre-allocated variable the directory cookie shall - be written to. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t (*file_system_module_info::close_dir)(fs_volume fs, - fs_vnode vnode, fs_cookie cookie) - \brief Closes the given directory cookie. - - Generally the situation is similar to the one described for close(). In - practice it is a bit, though, since directory cookies are exclusively used - for directory iteration, and it normally doesn't make sense to have multiple - threads read the same directory concurrently. Furthermore reading a directory - should not block. Therefore for most FSs this hook is a no-op. - - \param fs The volume handle. - \param vnode The node handle. - \param cookie The directory cookie as returned by open_dir(). - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t (*file_system_module_info::free_dir_cookie)(fs_volume fs, - fs_vnode vnode, fs_cookie cookie) - \brief Frees the given directory cookie. - - The hook is invoked after close_dir(), when no other thread uses or is going - to use the cookie. All resources associated with the cookie must be freed. - - \param fs The volume handle. - \param vnode The node handle. - \param cookie The directory cookie as returned by open_dir(). - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \fn status_t (*file_system_module_info::read_dir)(fs_volume fs, fs_vnode vnode, - fs_cookie cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num) - \brief Reads the next one or more directory entries. - - The number of entries to be read at maximum is stored in the variable \a _num - points to. - - Per read \c dirent the following fields have to be filled in: - - \c d_dev: The volume ID. - - \c d_ino: The ID of the node the entry refers to. - - \c d_name: The null-terminated name of the entry. - - \c d_reclen: The size of the \c dirent structure in bytes, starting from - the beginning of the structure, counting all bytes up to and including - the null-termination char of the name stored in \c d_name. - - If more than one entry is read, the corresponding \c dirent structures are - tightly packed, i.e. the second entry begins directly after the end of the - first one (i.e. \c d_reclen bytes after the beginning of the first one). - Most FSs read only one entry at a time though, even if more are requested. - - When the function is invoked after the end of the directory has been reached, - it shall set the variable \a _num points to to \c 0 and return \c B_OK. If - the provided buffer is too small to contain even the single next entry, - \c B_BUFFER_OVERFLOW shall be returned. It shall not fail, if at least one - entry has been read, and the buffer is just too small to hold as many entries - as requested. - - Note that a directory is expected to contain the special entries \c "." and - \c "..", referring to the same directory and the parent directory - respectively. The \c dirent structure returned for the \c ".." entry of the - volume's root directory shall refer to the root node itself. - - \param fs The volume handle. - \param vnode The node handle. - \param cookie The directory cookie as returned by open_dir(). - \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 directory 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 (*file_system_module_info::rewind_dir)(fs_volume fs, - fs_vnode vnode, fs_cookie cookie) - \brief Resets the directory cookie to the first entry of the directory. - \param fs The volume handle. - \param vnode The node handle. - \param cookie The directory cookie as returned by open_dir(). - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -//! @} - -/*! - \name Attribute Directory Operations -*/ - -//! @{ - -/*! - \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. - \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, - 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'. - \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, - 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. - \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, - 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 '.' - and '..' entries do not have to be present. -*/ - -/*! - \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'. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -//! @} - -/*! - \name Attribute Operations -*/ - -//! @{ - -/*! - \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. - \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 - 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. - \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 - 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. - \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, - 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. - \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 - 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. - \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 - 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. - \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, - 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. - \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, - 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 - which fields of \a stat are to be updated. - \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, - 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. - \retval "other errors" Another error condition was encountered. -*/ - -/*! - \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. - \param name The name of the attribute. - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -//! @} - -/*! - \name Index Directory and Operation -*/ - -//! @{ - -/*! - \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. - \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, - 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. -*/ - -/*! - \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 '.' - and the '..' entries don't have to be present. -*/ - -/*! - \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(). - \return \c B_OK if everything went fine, another error code otherwise. -*/ - -/*! - \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 - error otherwise. -*/ - -/*! - \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 - error otherwise. -*/ - -/*! - \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 - error otherwise. -*/ - -//! @} - -/*! - \name Query Operations -*/ - -//! @{ - -/*! - \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 - error otherwise. -*/ - -/*! - \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 - error otherwise. -*/ - -/*! - \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 - error otherwise. -*/ - -/*! - \fn status_t (*file_system_module_info::read_query)(fs_volume fs, - fs_cookie 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 read_dir(), with the - difference that it doesn't read the entries of a directory, but the entries - matching the given query. - - \param fs The volume handle. - \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 (*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. -*/ - -//! @} - -/*! - \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. -*/ - -//! @} - -///// 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. -*/ - -//! @} diff --git a/docs/user/drivers/fs_modules.dox b/docs/user/drivers/fs_modules.dox deleted file mode 100644 index d825b7f0b3..0000000000 --- a/docs/user/drivers/fs_modules.dox +++ /dev/null @@ -1,212 +0,0 @@ -/* - * Copyright 2007 Haiku Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Ingo Weinhold - */ - - /*! - \page fs_modules File System Modules - - To support a particular file system (FS), a kernel module implementing a - special interface (\c file_system_module_info defined in \c ) - has to be provided. As for any other module the \c std_ops() hook is invoked - with \c B_MODULE_INIT directly after the FS module has been loaded by the - kernel, and with \c B_MODULE_UNINIT before it is unloaded, thus providing - a simple mechanism for one-time module initializations. The same module is - used for accessing any volume of that FS type. - - - \section objects File System Objects - - There are several types of objects a FS module has to deal with directly or - indirectly: - - - A \em volume is an instance of a file system. For a disk-based file - system it corresponds to a disk, partition, or disk image file. When - mounting a volume the virtual file system layer (VFS) assigns a unique - number (ID, of type \c mount_id aka \c dev_t) to it and a handle (type - \c fs_volume, in fact \c void*) provided by - the file system. Whenever the FS requests a volume-related service from the - kernel, it has to pass the volume ID, and whenever the VFS asks the FS to - perform an operation, it supplies the handle. Normally the handle is a - pointer to a data structure the FS allocates to associate data with the - volume. - - - A \em node is contained by a volume. It can be of type file, directory, or - symbolic link (symlink). Just as volumes nodes are associated with an ID - (type \c vnode_id aka ino_t) and, if in use, also with a handle - (type \c fs_vnode, in fact \c void*). - Unlike the volume ID the node ID is defined by the FS. It often - has a meaning to the FS, e.g. file systems using inodes might choose the - inode number corresponding to the node. As long as the volume is mounted - and the node is known to the VFS, its node ID must not change. The node - handle is again a pointer to a data structure allocated by the FS. - - - A \em vnode (VFS node) is the VFS representation of a node. A volume may - contain a great number of nodes, but at a time only a few are represented - by vnodes, usually only those that are currently in use (sometimes a few - more). - - - An \em entry (directory entry) belongs to a directory, has a name, and - refers to a node. It is important to understand the difference between - entries and nodes: A node doesn't have a name, only the entries that refer - to it have. If a FS supports to have more than one entry refer to a single - node, it is also said to support "hard links". It is possible that no entry - refers to a node. This happens when a node (e.g. a file) is still open, but - the last entry referring to it has been removed (the node will be deleted - when the it is closed). While entries are to be understood as independent - entities, the FS interface does not use IDs or handles to refer to them; - it always uses directory and entry name pairs to do that. - - - An \em attribute is a named and typed data container belonging to a node. A - node may have any number of attributes; they are organized in a (virtual or - actually existing) attribute directory, through which one can iterate. - - - An \em index is supposed to provide fast searching capabilities for - attributes with a certain name. A volume's index directory allows for - iterating through the indices. - - - A \em query is a fully virtual object for searching for entries via an - expression matching entry name, node size, node modification date, and/or - node attributes. The mechanism of retrieving the entries found by a query - is similar to that for reading a directory contents. A query can be live - in which case the creator of the query is notified by the FS whenever an - entry no longer matches the query expression or starts matching. - - - \section concepts Generic Concepts - - A FS module has to (or can) provide quite a lot of hook functions. There are - a few concepts that apply to several groups of them: - - - Opening, Closing, and Cookies: Many FS objects can be opened and - closed, namely nodes in general, directories, attribute directories, - attributes, the index directory, and queries. In each case there are three - hook functions: open*(), close*(), and - free*_cookie(). The open*() hook is passed all that is - needed to identify the object to be opened and, in some cases, additional - parameters e.g. specifying a particular opening mode. The implementation - is required to return a cookie (type \c fs_cookie, in fact \c void*), - usually a pointer to a data structure the FS allocates. In some cases (e.g. - when an iteration state is associated with the cookie) a new cookie must - be allocated for each instance of opening the object. The cookie is passed - to all hooks that operate on a thusly opened object. The close*() - hook is invoked to signal that the cookie is to be closed. At this point - the cookie might still be in use. Blocking FS hooks (e.g. blocking - read/write operations) using the same cookie have to be unblocked. When - the cookie stops being in use the free*_cookie() hook is called; - it has to free the cookie. - - - Entry Iteration: For the FS objects serving as containers for - other objects, i.e. directories, attribute directories, the index - directory, and queries, the cookie mechanism is used for a stateful - iteration through the contained objects. The read_*() hook reads - the next one or more entries into a struct dirent buffer. The - rewind_*() hook resets the iteration state to the first entry. - - - Stat Information: In case of nodes, attributes, and indices - detailed information about an object are requested via a - read*_stat() hook and must be written into a struct stat - buffer. - - - \section vnodes VNodes - - A vnode is the VFS representation of a node. As soon as an access to a node - is requested, the VFS creates a corresponding vnode. The requesting entity - gets a reference to the vnode for the time it works with the vnode and - releases the reference when done. When the last reference to a vnode has been - surrendered, the vnode is unused and the VFS can decide to destroy it - (usually it is cached for a while longer). - - When the VFS creates a vnode, it invokes the FS's - \link file_system_module_info::get_vnode get_vnode() \endlink - hook to let it create the respective node handle (unless the FS requests the - creation of the vnode explicitely by calling publish_vnode()). That's the - only hook that specifies a node by ID; to all other node-related hooks the - node handle is passed. When the VFS deletes the vnode, it invokes the FS's - \link file_system_module_info::put_vnode put_vnode() \endlink - hook or, if the node was marked removed, - \link file_system_module_info::remove_vnode remove_vnode() \endlink. - - There are only four FS hooks through which the VFS gains knowledge of the - existence of a node. The first one is the - \link file_system_module_info::mount mount() \endlink - hook. It is supposed to call \c publish_vnode() for the root node of the - volume and return its ID. The second one is the - \link file_system_module_info::lookup lookup() \endlink - hook. Given a node handle of a directory and an entry name, it is supposed to - call \c get_vnode() for the node the entry refers to and return the node ID. - The remaining two hooks, - \link file_system_module_info::read_dir read_dir() \endlink and - \link file_system_module_info::read_query read_query() \endlink, - both return entries in a struct dirent structure, which also - contains the ID of the node the entry refers to. - - - \section mandatory_hooks Mandatory Hooks - - Which hooks a FS module should provide mainly depends on what functionality - it features. E.g. a FS without support for attribute, indices, and/or queries - can omit the respective hooks (i.e. set them to \c NULL in the module - structure). Some hooks are mandatory, though. A minimal read-only FS module - must implement: - - - \link file_system_module_info::mount mount() \endlink and - \link file_system_module_info::unmount unmount() \endlink: - Mounting and unmounting a volume is required for pretty obvious reasons. - - - \link file_system_module_info::lookup lookup() \endlink: - The VFS uses this hook to resolve path names. It is probably one of the - most frequently invoked hooks. - - - \link file_system_module_info::get_vnode get_vnode() \endlink and - \link file_system_module_info::put_vnode put_vnode() \endlink: - Create respectively destroy the FS's private node handle when - the VFS creates/deletes the vnode for a particular node. - - - \link file_system_module_info::read_stat read_stat() \endlink: - Return a struct stat info for the given node, consisting of the - type and size of the node, its owner and access permissions, as well as - certain access times. - - - \link file_system_module_info::open open() \endlink, - \link file_system_module_info::close close() \endlink, and - \link file_system_module_info::free_cookie free_cookie() \endlink: - Open and close a node as explained in \ref concepts. - - - \link file_system_module_info::read read() \endlink: - Read data from an opened node (file). Even if the FS does not feature - files, the hook has to be present anyway; it should return an error in this - case. - - - \link file_system_module_info::open_dir open_dir() \endlink, - \link file_system_module_info::close_dir close_dir() \endlink, and - \link file_system_module_info::free_dir_cookie free_dir_cookie() \endlink: - Open and close a directory for entry iteration as explained in - \ref concepts. - - - \link file_system_module_info::read_dir read_dir() \endlink and - \link file_system_module_info::rewind_dir rewind_dir() \endlink: - Read the next entry/entries from a directory, respectively reset the - iterator to the first entry, as explained in \ref concepts. - - Although not strictly mandatory, a FS should additionally implement the - following hooks: - - - \link file_system_module_info::read_fs_info read_fs_info() \endlink: - Return general information about the volume, e.g. total and free size, and - what special features (attributes, MIME types, queries) the volume/FS - supports. - - - \link file_system_module_info::read_symlink read_symlink() \endlink: - Read the value of a symbolic link. Needed only, if the FS and volume - support symbolic links at all. If absent symbolic links stored on the - volume won't be interpreted. - - - \link file_system_module_info::access access() \endlink: - Return whether the current user has the given access permissions for a - node. If the hook is absent the user is considerd to have all permissions. -*/