Operations vector for a volume. More...

Public Attributes
General Operations
status_t(*	unmount )(fs_volume *volume)
	Unmounts the given volume.

status_t(*	read_fs_info )(fs_volume volume, struct fs_info info)
	Retrieves general information about the volume.

status_t(*	write_fs_info )(fs_volume volume, const struct fs_info info, uint32 mask)
	Update filesystem information on the volume.

status_t(*	sync )(fs_volume *volume)
	Synchronize the cached data with the contents of the disk.

status_t(*	get_vnode )(fs_volume volume, ino_t id, fs_vnode vnode, int _type, uint32 _flags, bool reenter)
	Creates the private data handle to be associated with the node referred to by id.

Index Directory and Operation
status_t(*	open_index_dir )(fs_volume volume, void *_cookie)
	Open the list of an indices as a directory.

status_t(*	close_index_dir )(fs_volume volume, void cookie)
	Close a 'directory' of indices.

status_t(*	free_index_dir_cookie )(fs_volume volume, void cookie)
	Free the cookie to the index 'directory'.

status_t(*	read_index_dir )(fs_volume volume, void cookie, struct dirent buffer, size_t bufferSize, uint32 _num)
	Read the next one or more index entries.

status_t(*	rewind_index_dir )(fs_volume volume, void cookie)
	Reset the index directory cookie to the first entry of the directory.

status_t(*	create_index )(fs_volume volume, const char name, uint32 type, uint32 flags)
	Create a new index.

status_t(*	remove_index )(fs_volume volume, const char name)
	Remove the index with name.

status_t(*	read_index_stat )(fs_volume volume, const char name, struct stat *stat)
	Read the stat of the index with a name.

Query Operations
status_t(*	open_query )(fs_volume volume, const char query, uint32 flags, port_id port, uint32 token, void **_cookie)
	Open a query as a 'directory'.

status_t(*	close_query )(fs_volume volume, void cookie)
	Close a 'directory' of a query.

status_t(*	free_query_cookie )(fs_volume volume, void cookie)
	Free a cookie of a query.

status_t(*	read_query )(fs_volume volume, void cookie, struct dirent buffer, size_t bufferSize, uint32 _num)
	Read the next one or more entries matching the query.

status_t(*	rewind_query )(fs_volume volume, void cookie)
	Reset the query cookie to the first entry of the results.

FS Layer Operations
status_t(*	all_layers_mounted )(fs_volume *volume)
	TODO: Document!

status_t(*	create_sub_vnode )(fs_volume volume, ino_t id, fs_vnode vnode)
	TODO: Document!

status_t(*	delete_sub_vnode )(fs_volume volume, fs_vnode vnode)
	TODO: Document!

Detailed Description

Operations vector for a volume.

See the introduction to file system modules for an introduction to writing file systems.

Member Data Documentation

◆ close_index_dir

status_t(* fs_volume_ops::close_index_dir)(fs_volume *volume, void *cookie)

Close a 'directory' of indices.

Note that you should free the cookie in the free_index_dir_cookie() call.

Parameters

volume	The volume object.
cookie	The cookie associated with this 'directory'.

Returns: B_OK if everything went fine, another error code otherwise.

◆ close_query

status_t(* fs_volume_ops::close_query)(fs_volume *volume, void *cookie)

Close a 'directory' of a query.

Note that you should free the cookie in the free_query_cookie() call.

Parameters

volume	The volume object.
cookie	The cookie that refers to this query.

Returns: You should return B_OK if the creation succeeded, or return an error otherwise.

◆ create_index

status_t(* fs_volume_ops::create_index)(fs_volume *volume, const char *name, uint32 type, uint32 flags)

Create a new index.

Parameters

volume	The volume object.
name	The name of the new index.
type	The type of index. BFS implements the following types: `B_INT32_TYPE` `B_UINT32_TYPE` `B_INT64_TYPE` `B_UINT64_TYPE` `B_FLOAT_TYPE` `B_DOUBLE_TYPE` `B_STRING_TYPE` `B_MIME_STRING_TYPE`
flags	There are currently no extra flags specified. This parameter can be ignored.

Returns: You should return B_OK if the creation succeeded, or return an error otherwise.

◆ free_index_dir_cookie

status_t(* fs_volume_ops::free_index_dir_cookie)(fs_volume *volume, void *cookie)

Free the cookie to the index 'directory'.

Parameters

volume	The volume object.
cookie	The cookie that should be freed.

Returns: B_OK if everything went fine, another error code otherwise.

◆ free_query_cookie

status_t(* fs_volume_ops::free_query_cookie)(fs_volume *volume, void *cookie)

Free a cookie of a query.

Parameters

volume	The volume object.
cookie	The cookie that should be freed.

Returns: You should return B_OK if the creation succeeded, or return an error otherwise.

◆ get_vnode

status_t(* fs_volume_ops::get_vnode)(fs_volume *volume, ino_t id, fs_vnode *vnode, int *_type, uint32 *_flags, bool reenter)

Creates the private data handle to be associated with the node referred to by 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.

The hook has to initialize vnode->private_node with its handle created for the node and vnode->ops with the operation vector for the node. It also has to set *_type to the type of the node – as in stat::st_mode (the non-type bits can, but do not need to be cleared) – and *_flags to a bitwise OR of vnode flags to apply (cf. publish_vnode() for what flags bits are possible).

Parameters

volume	The volume object.
id	The ID of the node.
vnode	Pointer to a node object to be initialized.
_type	Pointer to a variable to be set to the node's type.
_flags	Pointer to a variable to be set to flags to apply to the vnode.
reenter	`true` if the hook invocation has been caused by the FS itself, e.g. by invoking get_vnode().

Returns: B_OK if everything went fine, another error code otherwise.

◆ open_index_dir

status_t(* fs_volume_ops::open_index_dir)(fs_volume *volume, void **_cookie)

Open the list of an indices as a directory.

See Generic Concepts on directories and iterators. Basically, the VFS uses the same way of traversing through indeces as it traverses through a directory.

Parameters

	volume	The volume object.
[out]	_cookie	Pointer where the file system can store a directory cookie if the index directory is succesfully opened.

Returns: B_OK if everything went fine, another error code otherwise.

◆ open_query

status_t(* fs_volume_ops::open_query)(fs_volume *volume, const char *query, uint32 flags, port_id port, uint32 token, void **_cookie)

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 Generic Concepts on directories and iterators. Basically, the VFS uses the same way of traversing through indices as it traverses through a directory.

Parameters

	volume	The volume object.
	query	The string that represents a query.
	flags	Any combination of none or more of these flags: `B_LIVE_QUERY` The query is live. When a query is live, it is constantly updated using the port. The FS must invoke the functions notify_query_entry_created() and notify_query_entry_removed() whenever an entry starts respectively stops to match the query predicate. `B_QUERY_NON_INDEXED` Normally at least one of the attributes used in the query string should be indexed. If none is, this hook is allowed to fail, unless this flag is specified. Usually an implementation will simply add a wildcard match for any complete index ("name", "last_modified", or "size") to the query expression.
	port	The id of the port where updates need to be sent to in case the query is live.
	token	A token that should be attached to the messages sent over the port.
[out]	_cookie	The cookie that will be used as 'directory' to traverse through the results of the query.

Returns: You should return B_OK if the creation succeeded, or return an error otherwise.

◆ read_fs_info

status_t(* fs_volume_ops::read_fs_info)(fs_volume *volume, struct fs_info *info)

Retrieves general information about the volume.

The following fields of the fs_info structure need to be filled in:

flags: Flags applying to the volume, e.g. B_FS_IS_READONLY, B_FS_HAS_ATTR, etc.
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 total_blocks and free_blocks.
io_size: Preferred size of the buffers passed to read() and write().
total_blocks: Total number of blocks the volume contains.
free_blocks: Number of free blocks on the volume.
total_nodes: Maximal number of nodes the volume can contain. If there is no such limitation use LONGLONG_MAX.
free_nodes: Number of additional nodes the volume could contain. If there is no such limitation use LONGLONG_MAX.
volume_name: The name of the volume.

The other values are filled in by the VFS.

Parameters

volume	The volume object.
info	Pointer to a pre-allocated variable the FS info shall be written to.

Returns: B_OK if everything went fine, another error code otherwise. The error code will be ignored, though.

◆ read_index_dir

status_t(* fs_volume_ops::read_index_dir)(fs_volume *volume, void *cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num)

Read the next one or more index entries.

This method should perform the same task as fs_vnode_ops::read_dir(), except that the '.' and the '..' entries don't have to be present.

◆ read_index_stat

status_t(* fs_volume_ops::read_index_stat)(fs_volume *volume, const char *name, struct stat *stat)

Read the stat of the index with a name.

Parameters

volume	The volume object.
name	The name of the index to be queried.
stat	A pointer to a structure where you should store the values.

Returns: You should return B_OK if the creation succeeded, or return an error otherwise.

◆ read_query

status_t(* fs_volume_ops::read_query)(fs_volume *volume, void *cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num)

Read the next one or more entries matching the query.

This hook function works pretty much the same way as fs_vnode_ops::read_dir(), with the difference that it doesn't read the entries of a directory, but the entries matching the given query. Unlike the fs_vnode_ops::read_dir() hook, this hook also has to fill in the dirent::d_pino field.

Parameters

volume	The volume object.
cookie	The query cookie as returned by open_query().
buffer	Pointer to a pre-allocated buffer the directory entries shall be written to.
bufferSize	The size of buffer in bytes.
_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.

Returns: B_OK if everything went fine, another error code otherwise.

◆ remove_index

status_t(* fs_volume_ops::remove_index)(fs_volume *volume, const char *name)

Remove the index with name.

Parameters

volume	The volume object.
name	The name of the index to be removed.

Returns: You should return B_OK if the creation succeeded, or return an error otherwise.

◆ rewind_index_dir

status_t(* fs_volume_ops::rewind_index_dir)(fs_volume *volume, void *cookie)

Reset the index directory cookie to the first entry of the directory.

Parameters

volume	The volume object.
cookie	The directory cookie as returned by open_index_dir().

Returns: B_OK if everything went fine, another error code otherwise.

◆ rewind_query

status_t(* fs_volume_ops::rewind_query)(fs_volume *volume, void *cookie)

Reset the query cookie to the first entry of the results.

Parameters

volume	The volume object.
cookie	The query cookie as returned by open_query().

Returns: B_OK if everything went fine, another error code otherwise.

◆ sync

status_t(* fs_volume_ops::sync)(fs_volume *volume)

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.

Parameters

volume The volume object.

◆ unmount

status_t(* fs_volume_ops::unmount)(fs_volume *volume)

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. Before unmount() is called, the VFS calls file_system_module_info::put_vnode() respectively file_system_module_info::remove_vnode() for each of the volume's nodes. That is although the mount() hook called publish_vnode() for the volume's root node, unmount() must not invoke put_vnode().

Parameters

volume The volume object.

Returns: B_OK if everything went fine, another error code otherwise. The error code will be ignored, though.

◆ write_fs_info

status_t(* fs_volume_ops::write_fs_info)(fs_volume *volume, const struct fs_info *info, uint32 mask)

Update filesystem information on the volume.

You are requested to update certain information on the given volume. The supplied info contains the new values filled in for the mask. Currently, the only possible mask is solely the FS_WRITE_FSINFO_NAME, which asks you to update the volume name represented by the value volume_name in the fs_info struct.

Parameters

volume	The volume object.
info	The structure that contains the new data.
mask	The values of the info that need to be updated.

Returns: B_OK if everything went fine, if not, one of the error codes.

Public Attributes

Detailed Description

Member Data Documentation

◆ close_index_dir

◆ close_query

◆ create_index

◆ free_index_dir_cookie

◆ free_query_cookie

◆ get_vnode

◆ open_index_dir

◆ open_query

◆ read_fs_info

◆ read_index_dir

◆ read_index_stat

◆ read_query

◆ remove_index

◆ rewind_index_dir

◆ rewind_query

◆ sync

◆ unmount

◆ write_fs_info