diff --git a/docs/user/drivers/fs_interface.dox b/docs/user/drivers/fs_interface.dox
index b4fe2d402b..3bf94e703e 100644
--- a/docs/user/drivers/fs_interface.dox
+++ b/docs/user/drivers/fs_interface.dox
@@ -168,114 +168,115 @@
//! @{
/*!
- \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.
+ \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.
+ 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.
+ 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.
+ 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.
+ \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.
+ \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().
+ 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.
+ \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.
+ \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 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.
+ 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.
+ \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.
+ \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.
- \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.
+ 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
- updated.
+ \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.
*/
//! @}
@@ -287,381 +288,417 @@
//! @{
/*!
- \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.
+ \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.
+ 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.
+ 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.
+ 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.
+ \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.
-
- \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_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.
+ \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.
+ 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.
+ \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.
+ \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.
+ 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.
+ \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.
+ \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 is marked removed.
+ 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.
+ \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
+ \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?
+ \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::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)
+ \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
+ \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 Undocumented. TODO.
+ \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
+ \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::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::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 Undocumented. TODO.
-
- TODO: What should this do?
+ \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.
*/
/*!
- \fn status_t (*file_system_module_info::deselect)(fs_volume fs, fs_vnode vnode, fs_cookie cookie,
- uint8 event, selectsync *sync)
- \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 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::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.
+ \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 string written to the buffer shall be
- null-terminated and the variable \a _bufferSize points to shall be set to
- the length of that string, including the terminating null character.
+ If the function is successful, the string written to the buffer shall be
+ null-terminated and the variable \a _bufferSize points to shall be set to
+ the length of that string, including the terminating null character.
- \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 buffer 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.
- \retval B_BUFFER_OVERFLOW The supplied buffer is not big enough to contain
- the complete link value.
+ \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 buffer 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.
+ \retval B_BUFFER_OVERFLOW The supplied buffer is not big enough to contain
+ the complete link value.
*/
/*!
- \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::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().
-
- \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::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::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::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.
+ \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.
+ \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.
+ 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.
+ 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.
+ \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.
+ \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.
+ 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.
+ \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.
+ \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.
*/
//! @}
@@ -673,304 +710,304 @@
//! @{
/*!
- \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::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.
+ \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 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.
+ 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.
+ \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.
+ \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.
+ 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.
+ 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.
+ \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.
+ \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.
+ 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.
+ \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.
+ \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.
+ 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.
+ 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.
+ \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.
+ \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.
- 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.
+ 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
+ \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::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::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.
+ \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.
+ 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.
+ \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.
+ \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.
+ 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.
+ \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.
+ \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.
+ 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.
+ \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.
+ \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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ \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.
+ \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
+ \name Attribute Directory Operations
*/
//! @{