user/drivers/fs_interface.dox

/*
 * Copyright 2007-2008 Haiku Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Ingo Weinhold <ingo_weinhold@gmx.de>
 *		Niels Sascha Reedijk <niels.reedijk@gmail.com>
 *		Axel Dörfler <axeld@pinc-software.de>
 *
 * 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
		<tt>struct stat</tt> (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 (<tt>geteuid() == 0</tt>) 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 <tt>struct stat</tt> 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.
*/

//! @}