Classes | Macros | Functions
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. More...
 
#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. More...
 
#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

status_t acquire_vnode (fs_volume *volume, ino_t vnodeID)
 Acquires another reference to a vnode. More...
 
status_t get_vnode (fs_volume *volume, ino_t vnodeID, void **_privateNode)
 Retrieves the private data handle for the node with the given ID. More...
 
status_t get_vnode_removed (fs_volume *volume, ino_t vnodeID, bool *_removed)
 Returns whether the specified vnode is marked removed. More...
 
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. More...
 
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. More...
 
status_t put_vnode (fs_volume *volume, ino_t vnodeID)
 Surrenders a reference to the specified vnode. More...
 
status_t remove_vnode (fs_volume *volume, ino_t vnodeID)
 Marks the specified vnode removed. More...
 
status_t unremove_vnode (fs_volume *volume, ino_t vnodeID)
 Clears the "removed" mark of the specified vnode. More...
 
fs_volume * volume_for_vnode (fs_vnode *vnode)
 Returns the volume object for a given vnode. More...
 
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_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_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_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_stat_changed (dev_t device, ino_t directory, ino_t node, uint32 statFields)
 Notifies listeners that certain statFields of a node were updated.
 
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_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.
 

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
volumeThe volume object.
vnodeIDThe 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
volumeThe volume object.
vnodeIDThe ID of the node.
_privateNodePointer 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
volumeThe volume object.
vnodeIDThe ID of the node.
_removedPointer 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
volumeThe volume object.
vnodeIDThe ID of the node.
privateNodeThe private data handle to be associated with the node.
opsThe 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
volumeThe volume object.
vnodeIDThe ID of the node.
privateNodeThe private data handle to be associated with the node.
opsThe operation vector for this vnode. Is not copied and must be valid through the whole life time of the vnode.
typeThe type of the node as it would appear in a stat::st_mode (with all non type-related bits set to 0).
flagsA 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
volumeThe volume object.
vnodeIDThe 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
volumeThe volume object.
vnodeIDThe 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
volumeThe volume object.
vnodeIDThe 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
vnodeThe node object.
Returns
The volume object for the given vnode.