fs_interface.h File Reference

Provides an interface for file system modules. More...

Classes
struct	file_io_vec
	Structure that describes the io vector of a file. More...
struct	file_system_module_info
	Kernel module interface for file systems. More...
struct	fs_vnode_ops
	Operations vector for a node. More...
struct	fs_volume_ops
	Operations vector for a volume. More...

Macros
#define	B_CURRENT_FS_API_VERSION   "/v1"
	Constant that defines the version of the file system API that your filesystem conforms to.
#define	B_STAT_SIZE_INSECURE   0x2000
	Flag for the fs_vnode_ops::write_stat hook indicating that the FS is allowed not to clear the additional space when enlarging a file.
#define	B_VNODE_DONT_CREATE_SPECIAL_SUB_NODE   0x02
	Flag for publish_vnode() and fs_volume_ops::get_vnode() indicating that no subnodes shall be created for the node to publish the node shall be published.
#define	B_VNODE_PUBLISH_REMOVED   0x01
	Flag for publish_vnode() and fs_vnode_ops::create_special_node() indicating that the node shall be published in removed state (i.e. no entry refers to it).
#define	FS_WRITE_FSINFO_NAME   0x0001
	Passed to fs_volume_ops::write_fs_info() to indicate that the name of the volume shall be changed.

Functions
Vnode functions
status_t	acquire_vnode (fs_volume *volume, ino_t vnodeID)
	Acquires another reference to a vnode.
status_t	get_vnode (fs_volume *volume, ino_t vnodeID, void **_privateNode)
	Retrieves the private data handle for the node with the given ID.
status_t	get_vnode_removed (fs_volume *volume, ino_t vnodeID, bool *_removed)
	Returns whether the specified vnode is marked removed.
status_t	new_vnode (fs_volume *volume, ino_t vnodeID, void *privateNode, fs_vnode_ops *ops)
	Create the vnode with ID vnodeID and associates it with the private data handle privateNode, but leaves is in an unpublished state.
status_t	publish_vnode (fs_volume *volume, ino_t vnodeID, void *privateNode, fs_vnode_ops *ops, int type, uint32 flags)
	Creates the vnode with ID vnodeID and associates it with the private data handle privateNode or just marks it published.
status_t	put_vnode (fs_volume *volume, ino_t vnodeID)
	Surrenders a reference to the specified vnode.
status_t	remove_vnode (fs_volume *volume, ino_t vnodeID)
	Marks the specified vnode removed.
status_t	unremove_vnode (fs_volume *volume, ino_t vnodeID)
	Clears the "removed" mark of the specified vnode.
fs_volume *	volume_for_vnode (fs_vnode *vnode)
	Returns the volume object for a given vnode.
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.
status_t	notify_attribute_changed (dev_t device, ino_t directory, ino_t node, const char *attribute, int32 cause)
	Notifies listeners that an attribute of a node has been changed.
status_t	notify_entry_created (dev_t device, ino_t directory, const char *name, ino_t node)
	Notifies listeners that a file system entry has been created.
status_t	notify_entry_moved (dev_t device, ino_t fromDirectory, const char *fromName, ino_t toDirectory, const char *toName, ino_t node)
	Notifies listeners that a file system entry has been renamed and/or moved to another directory.
status_t	notify_entry_removed (dev_t device, ino_t directory, const char *name, ino_t node)
	Notifies listeners that a file system entry has been removed.
status_t	notify_query_entry_created (port_id port, int32 token, dev_t device, ino_t directory, const char *name, ino_t node)
	Notifies listeners that an entry has entered the result set of a live query.
status_t	notify_query_entry_removed (port_id port, int32 token, dev_t device, ino_t directory, const char *name, ino_t node)
	Notifies listeners that an entry has left the result set of a live query.
status_t	notify_stat_changed (dev_t device, ino_t directory, ino_t node, uint32 statFields)
	Notifies listeners that certain statFields of a node were updated.

Detailed Description

Provides an interface for file system modules.

See the introduction to file system modules for a guide on how to get started with writing file system modules.

Macro Definition Documentation

B_CURRENT_FS_API_VERSION

#define B_CURRENT_FS_API_VERSION   "/v1"

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:

"file_systems/myfs" B_CURRENT_FS_API_VERSION 

B_STAT_SIZE_INSECURE

#define B_STAT_SIZE_INSECURE   0x2000

Flag for the fs_vnode_ops::write_stat hook indicating that the FS is allowed not to clear the additional space when enlarging a file.

This flag was added because BFS doesn't support sparse files. It will be phased out, when it does.

Function Documentation

acquire_vnode()

status_t acquire_vnode	(	fs_volume *	volume,
		ino_t	vnodeID
	)

Acquires another reference to a vnode.

Similar to get_vnode() in that the function acquires a vnode reference. Unlike get_vnode() this function can also be invoked between new_vnode() and publish_vnode().

Parameters

volume	The volume object.
vnodeID	The ID of the node.

Returns

B_OK if everything went fine, another error code otherwise.

get_vnode()

status_t get_vnode	(	fs_volume *	volume,
		ino_t	vnodeID,
		void **	_privateNode
	)

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().

Parameters

volume	The volume object.
vnodeID	The ID of the node.
_privateNode	Pointer to a pre-allocated variable the private data handle shall be written to.

Returns

B_OK if everything went fine, another error code otherwise.

get_vnode_removed()

status_t get_vnode_removed	(	fs_volume *	volume,
		ino_t	vnodeID,
		bool *	_removed
	)

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.

Parameters

volume	The volume object.
vnodeID	The ID of the node.
_removed	Pointer to a pre-allocated variable set to true, if the node is marked removed, to false otherwise.

Returns

B_OK if everything went fine, another error code otherwise.

new_vnode()

status_t new_vnode	(	fs_volume *	volume,
		ino_t	vnodeID,
		void *	privateNode,
		fs_vnode_ops *	ops
	)

Create the vnode with ID vnodeID and associates it with the private data handle 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 remove_vnode() 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.

Parameters

volume	The volume object.
vnodeID	The ID of the node.
privateNode	The private data handle to be associated with the node.
ops	The operation vector for this vnode. Is not copied and must be valid through the whole life time of the vnode.

Returns

B_OK if everything went fine, another error code otherwise.

publish_vnode()

status_t publish_vnode	(	fs_volume *	volume,
		ino_t	vnodeID,
		void *	privateNode,
		fs_vnode_ops *	ops,
		int	type,
		uint32	flags
	)

Creates the vnode with ID vnodeID and associates it with the private data handle 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().

If called after a new_vnode() the privateNode and ops parameters must be the same as previously passed to new_vnode().

This call is equivalent to the former BeOS R5 new_vnode() function.

Parameters

volume	The volume object.
vnodeID	The ID of the node.
privateNode	The private data handle to be associated with the node.
ops	The operation vector for this vnode. Is not copied and must be valid through the whole life time of the vnode.
type	The type of the node as it would appear in a stat::st_mode (with all non type-related bits set to 0).
flags	A bitwise combination of none or more of the following: B_VNODE_PUBLISH_REMOVED: The node is published in "removed" state, i.e. it has no entry referring to it and releasing the last reference to the vnode will remove it. B_VNODE_DONT_CREATE_SPECIAL_SUB_NODE: Normally for FIFO or socket type nodes the VFS creates sub node providing the associated functionality. This flag prevents that from happing.

Returns

B_OK if everything went fine, another error code otherwise.

put_vnode()

status_t put_vnode	(	fs_volume *	volume,
		ino_t	vnodeID
	)

Surrenders a reference to the specified vnode.

When the last reference to the vnode has been put the VFS will call fs_vnode_ops::put_vnode() (eventually), respectively, if the node has been marked removed fs_vnode_ops::remove_vnode() (immediately).

Parameters

volume	The volume object.
vnodeID	The ID of the node.

Returns

B_OK if everything went fine, another error code otherwise.

remove_vnode()

status_t remove_vnode	(	fs_volume *	volume,
		ino_t	vnodeID
	)

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 node's remove_vnode() hook.

Parameters

volume	The volume object.
vnodeID	The ID of the node.

Returns

B_OK if everything went fine, another error code otherwise.

unremove_vnode()

status_t unremove_vnode	(	fs_volume *	volume,
		ino_t	vnodeID
	)

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). Afterwards the vnode will continue to exist as if remove_vnode() had never been invoked.

Parameters

volume	The volume object.
vnodeID	The ID of the node.

Returns

B_OK if everything went fine, another error code otherwise.

volume_for_vnode()

fs_volume * volume_for_vnode

(

fs_vnode *

vnode

)

Returns the volume object for a given vnode.

Parameters

vnode

The node object.

Returns

The volume object for the given vnode.