xref: /haiku/docs/user/drivers/fs_interface.dox (revision 40ba6c7004fe3c4a23e30b18273160a3cea9d005)
1/*
2 * Copyright 2007 Haiku Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Ingo Weinhold
7 *		Niels Sascha Reedijk <niels.reedijk@gmail.com>
8 *		Axel Dörfler <axeld@pinc-software.de>
9 *
10 * Corresponds to:
11 *		/trunk/headers/os/drivers/fs_interface.h rev 21568
12 */
13
14/*!
15	\file fs_interface.h
16	\ingroup drivers
17	\brief Provides an interface for file system modules.
18
19	See the \ref fs_modules "introduction to file system modules" for a guide on
20	how to get started with writing file system modules.
21*/
22
23///// write_stat_mask //////
24
25/*!
26	\enum write_stat_mask
27	\brief This mask is used in file_system_module_info::write_stat() to
28		determine which values need to be written.
29*/
30
31/*!
32	\var write_stat_mask::FS_WRITE_STAT_MODE
33	\brief The mode parameter should be updated.
34*/
35
36/*!
37	\var write_stat_mask::FS_WRITE_STAT_UID
38	\brief The UID field should be updated.
39*/
40
41/*!
42	\var write_stat_mask::FS_WRITE_STAT_GID
43	\brief The GID field should be updated.
44*/
45
46/*!
47	\var write_stat_mask::FS_WRITE_STAT_SIZE
48	\brief The size field should be updated. If the actual size is less than the
49		new provided file size, the file should be set to the new size and the
50		extra space should be filled with zeros.
51*/
52
53/*!
54	\var write_stat_mask::FS_WRITE_STAT_ATIME
55	\brief The access time should be updated.
56*/
57
58/*!
59	\var write_stat_mask::FS_WRITE_STAT_MTIME
60	\brief The 'last modified' field should be updated.
61*/
62
63/*!
64	\var write_stat_mask::FS_WRITE_STAT_CRTIME
65	\brief The 'creation time' should be updated.
66*/
67
68///// FS_WRITE_FSINFO_NAME /////
69
70/*!
71	\def FS_WRITE_FSINFO_NAME
72	\brief Passed to file_system_module_info::write_fs_info().
73*/
74
75///// file_io_vec /////
76
77/*!
78	\struct file_io_vec
79	\brief Structure that describes the io vector of a file.
80*/
81
82/*!
83	\var off_t file_io_vec::offset
84	\brief The offset within the file.
85*/
86
87/*!
88	\var off_t file_io_vec::length
89	\brief The length of the vector.
90*/
91
92///// B_CURRENT_FS_API_VERSION /////
93
94/*!
95	\def B_CURRENT_FS_API_VERSION
96	\brief Constant that defines the version of the file system API that your
97		filesystem conforms to.
98
99	The module name that exports the interface to your file system has to
100	end with this constant as in:
101	\code "file_systems/myfs" B_CURRENT_FS_API_VERSION \endcode
102*/
103
104///// file_system_module_info /////
105
106
107/*!
108	\struct file_system_module_info
109	\brief Kernel module interface for file systems.
110
111	See the \ref fs_modules "introduction to file system modules" for an
112	introduction to writing file systems.
113*/
114
115/*!
116	\name Data members
117*/
118
119//! @{
120
121/*!
122	\var module_info file_system_module_info::info
123	\brief Your module_info object which is required for all modules.
124*/
125
126/*!
127	\var const char *file_system_module_info::pretty_name
128	\brief A NULL-terminated string with a 'pretty' name for you file system.
129
130	Note, if a system wide disk device type constant exists for your file system,
131	it should equal this identifier.
132*/
133
134//! @}
135
136/*!
137	\name Scanning
138*/
139
140//! @{
141
142/*!
143	\fn float (*file_system_module_info::identify_partition)(int fd,
144			partition_data *partition, void **cookie)
145	\brief Undocumented. TODO.
146*/
147
148/*!
149	\fn status_t (*file_system_module_info::scan_partition)(int fd,
150			partition_data *partition, void *cookie)
151	\brief Undocumented. TODO.
152*/
153
154/*!
155	\fn void (*file_system_module_info::free_identify_partition_cookie)(
156			partition_data *partition, void *cookie)
157	\brief Undocumented. TODO.
158*/
159
160/*!
161	\fn void (*file_system_module_info::free_partition_content_cookie)(
162			partition_data *partition)
163	\brief Undocumented. TODO.
164*/
165
166//! @}
167
168/*!
169	\name General Operations
170*/
171
172//! @{
173
174/*!
175	\fn status_t (*file_system_module_info::mount)(ino_t id, const char *device,
176			uint32 flags, const char *args, fs_volume *_fs, ino_t *_rootVnodeID)
177	\brief Mount a volume according to the specified parameters.
178
179	Invoked by the VFS when it has been requested to mount the volume. The FS is
180	supposed to perform whatever one-time initialization is necessary for the
181	volume. It is required to create a volume handle for the volume and pass it
182	back in \a _fs. Moreover it must invoke publish_vnode() for the root node
183	of the volume and pass the ID of the volume back in \a _rootVnodeID.
184
185	A disk-based FS will need to check whether \a device is not \c NULL, open
186	it, and analyze whether the device or image file actually represents a volume
187	of that FS type.
188
189	If mounting the volume fails for whatever reason, the hook must return an
190	error code other than \c B_OK. In this case all resources allocated by the
191	hook must be freed before returning. If and only if \c B_OK is returned, the
192	unmount() hook will be invoked at a later point when unmounting the volume.
193
194	\param id The ID of the volume to be mounted. It should be saved in the FS's
195		volume private data (volume handle).
196	\param device The path to the device (or image file) representing the volume
197		to be mounted. Can be \c NULL.
198	\param flags Flags:
199		- \c B_MOUNT_READ_ONLY: Mount the volume read-only.
200	\param args Null-terminated string in driver settings format, containing FS
201		specific parameters.
202	\param _fs Pointer to a pre-allocated variable the volume handle shall be
203		written to.
204	\param _rootVnodeID Pointer to a pre-allocated variable the ID of the
205		volume's root directory shall be written to.
206	\return \c B_OK if everything went fine, another error code otherwise.
207*/
208
209/*!
210	\fn status_t (*file_system_module_info::unmount)(fs_volume fs)
211	\brief Unmounts the given volume.
212
213	Invoked by the VFS when it is asked to unmount the volume. The function must
214	free all resources associated with the mounted volume, including the volume
215	handle. Although the mount() hook called publish_vnode() for the root node
216	of the volume, unmount() must not invoke put_vnode().
217
218	\param fs The volume handle.
219	\return \c B_OK if everything went fine, another error code otherwise. The
220		error code will be ignored, though.
221*/
222
223/*!
224	\fn status_t (*file_system_module_info::read_fs_info)(fs_volume fs,
225			struct fs_info *info)
226	\brief Retrieves general information about the volume.
227
228	The following fields of the \c fs_info structure need to be filled in:
229	- \c flags: Flags applying to the volume, e.g. \c B_FS_IS_READONLY,
230	  \c B_FS_HAS_ATTR, etc.
231	- \c block_size: The size of blocks the volume data are organized in.
232	  Meaningful mainly for disk-based FSs, other FSs should use some reasonable
233	  value for computing \c total_blocks and \c free_blocks.
234	- \c io_size: Preferred size of the buffers passed to read() and write().
235	- \c total_blocks: Total number of blocks the volume contains.
236	- \c free_blocks: Number of free blocks on the volume.
237	- \c total_nodes: Maximal number of nodes the volume can contain. If there is
238	  no such limitation use \c LONGLONG_MAX.
239	- \c free_nodes: Number of additional nodes the volume could contain. If
240	  there is no such limitation use \c LONGLONG_MAX.
241	- \c device_name: The name of the device or image file containing the volume.
242	  Non-disk-based FSs shall fill in an empty string.
243	- \c volume_name: The name of the volume.
244
245	The other values are filled in by the VFS.
246
247	\param fs The volume handle.
248	\param info Pointer to a pre-allocated variable the FS info shall be written
249		to.
250	\return \c B_OK if everything went fine, another error code otherwise. The
251		error code will be ignored, though.
252*/
253
254/*!
255	\fn status_t (*file_system_module_info::write_fs_info)(fs_volume fs,
256			const struct fs_info *info, uint32 mask)
257	\brief Update filesystem information on the volume.
258
259	You are requested to update certain information on the volume \a fs. The
260	supplied \a info contains the new values filled in for the \a mask.
261	Currently, the only possible mask is solely the \c FS_WRITE_FSINFO_NAME,
262	which asks you to update the volume name represented by the value
263	\c volume_name in the \c fs_info struct.
264
265	\param fs The cookie your filesystem supplied to the volume that should be
266		updated.
267	\param info The structure that contains the new data.
268	\param mask The values of the \a info that need to be updated.
269	\return \c B_OK if everything went fine, if not, one of the error codes.
270*/
271
272/*!
273	\fn status_t (*file_system_module_info::sync)(fs_volume fs)
274	\brief Synchronize the cached data with the contents of the disk.
275
276	The VFS layer sometimes wants you to synchronize any cached values with the
277	data on the device.
278
279	This currently only happens when the POSIX sync() function is invoked, for
280	example via the "sync" command line tool.
281
282	\param fs The cookie your filesystem supplied to the volume that should be
283		updated.
284*/
285
286//! @}
287
288/*!
289	\name VNode Operations
290*/
291
292//! @{
293
294/*!
295	\fn status_t (*file_system_module_info::lookup)(fs_volume fs, fs_vnode dir,
296			const char *name, ino_t *_id, int *_type)
297	\brief Looks up the node a directory entry refers to.
298
299	The VFS uses this hook to resolve path names to vnodes. It is used quite
300	often and should be implemented efficiently.
301
302	If the parameter \a dir does not specify a directory, the function shall
303	fail. It shall also fail, if it is a directory, but does not contain an entry
304	with the given name \a name. Otherwise the function shall invoke get_vnode()
305	for the node the entry refers to and pass back the ID and the type of the
306	node in \a _id and \a _type respectively.
307
308	Note that a directory must contain the special entries \c "." and \c "..",
309	referring to the same directory and the parent directory respectively.
310	lookup() must resolve the nodes accordingly. \c ".." for the root directory
311	of the volume shall be resolved to the root directory itself.
312
313	\param fs The volume handle.
314	\param dir The node handle of the directory.
315	\param name The name of the directory entry.
316	\param _id Pointer to a pre-allocated variable the ID of the found node
317		shall be written to.
318	\param _type Pointer to a pre-allocated variable the type of the found node
319		shall be written to. The type is encoded as in the \c st_mode field of a
320		<tt>struct stat</tt> (bitwise anded with \c S_IFMT).
321	\retval B_OK Everything went fine.
322	\retval B_ENTRY_NOT_FOUND The given directory does not contain an entry with
323		the given name.
324*/
325
326/*!
327	\fn status_t (*file_system_module_info::get_vnode_name)(fs_volume fs,
328			fs_vnode vnode, char *buffer, size_t bufferSize)
329	\brief Return the file name of a vnode.
330
331	Note that you don't have to implement this call if it can't be easily done;
332	it's completely optional.
333	If you don't implement it, you'll have to export a NULL pointer for this
334	function in the module definition. In this case, the VFS will find the name
335	by iterating over its parent directory.
336
337	\param fs The file system provided cookie associated with this volume.
338	\param vnode The file system provided cookie associated with this vnode.
339	\param buffer The buffer that the name can be copied into.
340	\param bufferSize The size of the buffer.
341	\retval B_OK You successfully copied the file name into the \a buffer.
342	\retval "other errors" There was some error looking up or copying the name.
343*/
344
345/*!
346	\fn status_t (*file_system_module_info::get_vnode)(fs_volume fs, ino_t id,
347			fs_vnode *_vnode, bool reenter)
348	\brief Creates the private data handle to be associated with the node
349		referred to by \a id.
350
351	Invoked by the VFS when it creates the vnode for the respective node.
352	When the VFS no longer needs the vnode in memory (for example when
353	memory is becoming tight), it will your file_system_module_info::put_vnode(),
354	or file_system_module_info::remove_vnode() in case the vnode has been
355	marked removed.
356
357	\param fs The volume handle.
358	\param id The ID of the node.
359	\param _vnode Pointer to a pre-allocated variable the node handle shall be
360		written to.
361	\param reenter \c true if the hook invocation has been caused by the FS
362		itself, e.g. by invoking ::get_vnode().
363	\return \c B_OK if everything went fine, another error code otherwise.
364*/
365
366/*!
367	\fn \fn status_t (*file_system_module_info::put_vnode)(fs_volume fs,
368			fs_vnode vnode, bool reenter)
369	\brief Deletes the private data handle associated with the specified node.
370
371	Invoked by the VFS when it deletes the vnode for the respective node and the
372	node is not marked removed.
373
374	\param fs The volume handle.
375	\param vnode The node handle.
376	\param reenter \c true if the hook invocation has been caused by the FS
377		itself, e.g. by invoking ::put_vnode().
378	\return \c B_OK if everything went fine, another error code otherwise.
379*/
380
381/*!
382	\fn status_t (*file_system_module_info::remove_vnode)(fs_volume fs,
383			fs_vnode vnode, bool reenter)
384	\brief Deletes the private data handle associated with the specified node.
385
386	Invoked by the VFS when it deletes the vnode for the respective node and the
387	node has been marked removed by a call to remove_vnode().
388
389	\param fs The volume handle.
390	\param vnode The node handle.
391	\param reenter \c true if the hook invocation has been caused by the FS
392		itself, e.g. by invoking ::put_vnode().
393	\return \c B_OK if everything went fine, another error code otherwise.
394*/
395
396//! @}
397
398/*!
399	\name VM file access
400*/
401
402//! @{
403
404/*!
405	\fn bool (*file_system_module_info::can_page)(fs_volume fs, fs_vnode vnode,
406			fs_cookie cookie)
407	\brief Undocumented. TODO.
408
409	TODO: In both the dos and the bfs implementations this thing simply returns
410	false... Is there anything more to it?
411	This call might be removed in the future - it's currently unused.
412*/
413
414/*!
415	\fn status_t (*file_system_module_info::read_pages)(fs_volume fs, fs_vnode vnode,
416			fs_cookie cookie, off_t pos, const iovec *vecs, size_t count,
417			size_t *_numBytes, bool reenter)
418	\brief Undocumented. TODO.
419*/
420
421/*!
422	\fn status_t (*file_system_module_info::write_pages)(fs_volume fs, fs_vnode vnode,
423			fs_cookie cookie, off_t pos, const iovec *vecs, size_t count,
424			size_t *_numBytes, bool reenter)
425	\brief Undocumented. TODO.
426*/
427
428//! @}
429
430/*!
431	\name Cache File Access
432*/
433
434//! @{
435
436/*!
437	\fn status_t (*file_system_module_info::get_file_map)(fs_volume fs,
438			fs_vnode vnode, off_t offset, size_t size, struct file_io_vec *vecs,
439			size_t *_count)
440	\brief Fills the \a vecs with the extents of the file data stream.
441
442	This function is called only when you are using the file cache, but if you
443	use it, its implementation is mandatory.
444
445	TODO: complete me
446*/
447
448//! @}
449
450/*!
451	\name Standard Operations
452*/
453
454//! @{
455
456/*!
457	\fn status_t (*file_system_module_info::ioctl)(fs_volume fs, fs_vnode vnode,
458			fs_cookie cookie, ulong op, void *buffer, size_t length)
459	\brief Perform file system specific operations.
460
461	You can implement a customized API using this call. This can be extremely
462	handy for debugging purposes. There are no obligatory operations for you to
463	implement.
464
465	If you don't want to use this feature, you don't have to implement it.
466
467	\param fs The file system provided cookie associated with this volume.
468	\param vnode The file system provided cookie associated with the vnode (if
469		applicable).
470	\param cookie The file system provided cookie associated with, for example,
471		an open file (if applicable).
472	\param op The operation code. You will have to define them yourself.
473	\param buffer A buffer (if applicable).
474	\param length The size of the buffer.
475	\return You should return any of your status codes.
476*/
477
478/*!
479	\fn status_t (*file_system_module_info::set_flags)(fs_volume fs,
480			fs_vnode vnode, fs_cookie cookie, int flags)
481	\brief Set the open mode flags for an opened file.
482
483	This function should change the open flags for an opened file.
484
485	\param fs The file system provided cookie associated with this volume.
486	\param vnode The file system provided cookie associated with the vnode.
487	\param cookie The file system provided cookie associated with the opened
488		file.
489	\param flags The new flags.
490	\return \c B_OK if the operation succeeded, or else an error code.
491*/
492
493/*!
494	\fn status_t (*file_system_module_info::select)(fs_volume fs, fs_vnode vnode,
495			fs_cookie cookie, uint8 event, uint32 ref, selectsync *sync)
496	\brief Selects the specified \a vnode with the specified \a events.
497
498	This function is called by the VFS whenever select() or poll() is called on
499	a file descriptor that points to your file system.
500
501	You have to check if the condition of the select() (ie. if there is data
502	available if event is B_SELECT_READ) is already satisfied, and call
503	notify_select_event() with the \a sync and \a ref arguments you retrieve
504	here.
505
506	Additionally, when a vnode is selected this way, you have to call
507	notify_select_event() whenever the condition becomes true until the
508	vnode is deselected again via file_system_module_info::deselect().
509
510	This function is optional. If you don't export it, the default implementation
511	in the VFS will call notify_select_event() directly which will be sufficient
512	for most file systems.
513*/
514
515/*!
516	\fn status_t (*file_system_module_info::deselect)(fs_volume fs, fs_vnode vnode,
517			fs_cookie cookie, uint8 event, selectsync *sync)
518	\brief Deselects the specified \a vnode from a previous select() call.
519
520	This function is called by the VFS whenever a select() or poll() function
521	exits that previously called file_system_module_info::select() on that
522	\a vnode.
523*/
524
525/*!
526	\fn status_t (*file_system_module_info::fsync)(fs_volume fs, fs_vnode vnode)
527	\brief Synchronize the buffers with the on disk data.
528
529	\param fs The file system provided cookie associated with this volume.
530	\param vnode The file system provided cookie associated with the vnode.
531	\return \c B_OK if the operation succeeded, or else an error code.
532*/
533
534/*!
535	\fn status_t (*file_system_module_info::read_symlink)(fs_volume fs,
536			fs_vnode link, char *buffer, size_t *_bufferSize)
537	\brief Read the value of a symbolic link.
538
539	If the function is successful, the string written to the buffer shall be
540	null-terminated and the variable \a _bufferSize points to shall be set to
541	the length of that string, including the terminating null character.
542
543	\param fs The volume handle.
544	\param link The node handle.
545	\param buffer Pointer to a pre-allocated buffer the link value shall be
546		written to.
547	\param buffer Pointer to a pre-allocated variable containing the size of the
548		buffer supplied to the function. Upon successful completion the hook shall
549		store the number of bytes actually written into the buffer in the variable.
550	\retval B_OK Everything went fine.
551	\retval B_BAD_VALUE \a link does not identify a symbolic link.
552	\retval B_BUFFER_OVERFLOW The supplied buffer is not big enough to contain
553		the complete link value.
554*/
555
556/*!
557	\fn status_t (*file_system_module_info::create_symlink)(fs_volume fs,
558			fs_vnode dir, const char *name, const char *path, int mode)
559	\brief Create a new symbolic link.
560
561	Your implementation should check if the user has permission to perform this
562	operation.
563
564	\param fs The file system provided cookie associated with this volume.
565	\param dir The file system provided cookie associated with the directory
566		the symbolic link should be created in.
567	\param name The name of the new symbolic link.
568	\param path The path of the original inode the symbolic link should refer to.
569	\param mode The mode that this symbolic link should be created in. (TODO
570		what exactly?)
571	\return \c B_OK if you succeeded, or an error code if you failed.
572*/
573
574/*!
575	\fn status_t (*file_system_module_info::link)(fs_volume fs, fs_vnode dir,
576			const char *name, fs_vnode vnode)
577	\brief Create a new hard link.
578
579	You should make sure the user has the proper permissions.
580
581	The virtual file system will request the creation of symbolic links with
582	create_symlink().
583
584	If you don't implement this function, the VFS will return \c EROFS
585	when a hard link is requested.
586
587	\param fs The file system provided cookie associated with this volume.
588	\param dir The cookie associated to the directory where the link should be
589		saved.
590	\param name The name the link should have.
591	\param vnode The vnode the new link should resolve to.
592	\retval B_OK The hard link is properly created.
593	\retval B_NOT_ALLOWED The user does not have the proper permissions.
594	\retval "other errors" Another error occured.
595*/
596
597/*!
598	\fn status_t (*file_system_module_info::unlink)(fs_volume fs, fs_vnode dir,
599			const char *name)
600	\brief Remove a node or directory.
601
602	You should make sure the user has the proper permissions.
603
604	\param fs The file system provided cookie associated with this volume.
605	\param dir The parent directory of the node that should be removed.
606	\param name The name of the node that should be deleted.
607	\retval B_OK Removal succeeded.
608	\retval B_ENTRY_NOT_FOUND The entry does not exist.
609	\retval B_NOT_ALLOWED The user does not have the proper permissions.
610	\retval B_DIRECTORY_NOT_EMPTY The \a name refers to a directory. The virtual
611		file system expects directories to be emptied before they can be unlinked.
612	\retval "other errors" Another error occured.
613*/
614
615/*!
616	\fn status_t (*file_system_module_info::rename)(fs_volume fs,
617			fs_vnode fromDir, const char *fromName, fs_vnode toDir,
618			const char *toName)
619	\brief Rename and/or relocate a vnode.
620
621	The virtual file system merely relays the request, so make sure the user is
622	not changing the file name to something like '.', '..' or anything starting
623	with '/'.
624
625	This also means that it if the node is a directory, that it should not be
626	moved into one of its own children.
627
628	You should also make sure the user has the proper permissions.
629
630	\param fs The file system provided cookie associated with this volume.
631	\param fromDir The cookie of the parent directory the vnode should be moved
632		from.
633	\param fromName The old name of the node.
634	\param toDir The cookie of the parent directory the vnode should be moved to.
635	\param toName The new name of the node.
636	\retval B_OK The renaming and relocating succeeded.
637	\retval B_BAD_VALUE One of the supplied parameters were invalid.
638	\retval B_NOT_ALLOWED The user does not have the proper permissions.
639	\retval "other errors" Another error condition was encountered.
640*/
641
642/*!
643	\fn status_t (*file_system_module_info::access)(fs_volume fs, fs_vnode vnode,
644			int mode)
645	\brief Checks whether the current user is allowed to access the node in the
646		specified way.
647
648	\a mode is a bitwise combination of:
649	- \c R_OK: Read access.
650	- \c W_OK: Write access.
651	- \c X_OK: Execution.
652
653	If the current user does not have any of the access permissions represented
654	by the set bits, the function shall return \c B_NOT_ALLOWED. As a special
655	case, if the volume is read-only and write access is requested,
656	\c B_READ_ONLY_DEVICE shall be returned. If the requested access mode
657	complies with the user's access permissions, the function shall return
658	\c B_OK.
659
660	For most FSs the permissions a user has are defined by the \c st_mode,
661	\c st_uid, and \c st_gid fields of the node's stat data. As a special
662	exception, the root user (<tt>geteuid() == 0</tt>) does always have
663	read and write permissions, execution permission only when at least one of
664	the execution permission bits are set.
665
666	\param fs The volume handle.
667	\param vnode The node handle.
668	\param mode The access mode mask.
669	\retval B_OK The user has the permissions to access the node in the requested
670		way.
671	\retval B_READ_ONLY_DEVICE The volume is read-only, but the write access has
672		been requested.
673	\retval B_NOT_ALLOWED The user does not have all permissions to access the
674		node in the requested way.
675*/
676
677/*!
678	\fn status_t (*file_system_module_info::read_stat)(fs_volume fs,
679			fs_vnode vnode, struct stat *stat)
680	\brief Retrieves the stat data for a given node.
681
682	All values of the <tt>struct stat</tt> save \c st_dev, \c st_ino, \c st_rdev,
683	and \c st_type need to be filled in.
684
685	\param fs The volume handle.
686	\param vnode The node handle.
687	\param stat Pointer to a pre-allocated variable the stat data shall be
688		written to.
689	\return \c B_OK if everything went fine, another error code otherwise.
690*/
691
692/*!
693	\fn status_t (*file_system_module_info::write_stat)(fs_volume fs,
694			fs_vnode vnode, const struct stat *stat, uint32 statMask)
695	\brief Update the stats for a vnode.
696
697	You should make sure that the new values are valid and that the user has the
698	proper permissions to update the stats.
699
700	\param fs The file system provided cookie to the volume.
701	\param vnode The cookie to the vnode.
702	\param stat The structure with the updated values.
703	\param statMask One of the #write_stat_mask enumeration, which forms a mask
704		of which of the values in \a stat should actually be updated.
705	\retval B_OK The update succeeded.
706	\retval B_NOT_ALLOWED The user does not have the proper permissions.
707	\retval "other errors" Another error condition occured.
708*/
709
710//! @}
711
712/*!
713 \name File Operations
714*/
715
716//! @{
717
718/*!
719	\fn status_t (*file_system_module_info::create)(fs_volume fs, fs_vnode dir,
720			const char *name, int openMode, int perms, fs_cookie *_cookie,
721			ino_t *_newVnodeID)
722	\brief Create a new file.
723
724	Your implementation shall check whether it is possible to create the node.
725	You will need to take the user's permissions into account. When you create
726	a new file, you will also have to open it. This means also checking the
727	permissions the user requires to open the file according to the \a mode.
728	See \link file_system_module_info::open() open() \endlink for the possible
729	values of \a mode.
730
731	\param fs The file system provided cookie associated with this volume.
732	\param dir The file system provided cookie associated with the directory
733		where the file should appear.
734	\param name The name of the new file.
735	\param openMode The mode associated to the file.
736	\param perms The permissions the new file should have.
737	\param[out] _cookie In case of success, the you can store your file system
738		data for this node in this variable.
739	\param[out] _newVnodeID In case of success, you can store the new vnode id
740		in this variable.
741	\return You should return \c B_OK if creating the new node succeeded, and if
742		you put data in both \a _cookie and \a _newVnodeID. Else you should return
743		an error code.
744*/
745
746/*!
747	\fn status_t (*file_system_module_info::open)(fs_volume fs, fs_vnode vnode,
748			int openMode, fs_cookie *_cookie)
749	\brief Opens the given node.
750
751	The function shall check whether it is possible to open the node according to
752	the mode specified by \c openMode (also considering the user's access
753	permissions), create a node cookie, and store it in the variable
754	\a _cookie points to.
755
756	The open mode \a openMode is encoded in the same way as the parameter of the
757	POSIX function \c open(), i.e. it is either \c O_RDONLY, \c O_WRONLY, or
758	\c O_RDWR, bitwise or'ed with flags. The only relevant flags for this hook
759	are \c O_TRUNC and \c O_NONBLOCK.
760
761	\param fs The volume handle.
762	\param vnode The node handle.
763	\param openMode The open mode.
764	\param _cookie Pointer to a pre-allocated variable the node cookie shall be
765		written to.
766	\return \c B_OK if everything went fine, another error code otherwise.
767*/
768
769/*!
770	\fn status_t (*file_system_module_info::close)(fs_volume fs, fs_vnode vnode,
771			fs_cookie cookie)
772	\brief Closes the given node cookie.
773
774	The hook is invoked, when closing the node has been requested. At this point
775	other threads might still use the cookie, i.e. still execute hooks to which
776	the cookie has been passed. If the FS supports blocking I/O operations, this
777	hook should make sure to unblock all currently blocking threads performing
778	an operation using the cookie, and mark the cookie such that no further
779	threads will block using it.
780
781	For many FSs this hook is a no-op - it's mandatory to be exported, though.
782
783	\param fs The volume handle.
784	\param vnode The node handle.
785	\param cookie The node cookie as returned by open().
786	\return \c B_OK if everything went fine, another error code otherwise.
787*/
788
789/*!
790	\fn status_t (*file_system_module_info::free_cookie)(fs_volume fs,
791			fs_vnode vnode, fs_cookie cookie)
792	\brief Frees the given node cookie.
793
794	The hook is invoked after close(), when no other thread uses or is going to
795	use the cookie. All resources associated with the cookie must be freed.
796
797	\param fs The volume handle.
798	\param vnode The node handle.
799	\param cookie The node cookie as returned by open().
800	\return \c B_OK if everything went fine, another error code otherwise.
801*/
802
803/*!
804	\fn status_t (*file_system_module_info::read)(fs_volume fs, fs_vnode vnode,
805			fs_cookie cookie, off_t pos, void *buffer, size_t *length)
806	\brief Reads data from a file.
807
808	This function should fail if
809	- the node is not a file,
810	- the cookie has not been opened for reading,
811	- \a pos is negative, or
812	- some other error occurs while trying to read the data, and no data have
813	been read at all.
814
815	The number of bytes to be read is stored in the variable pointed to by
816	\a length. If less data is  available at file position \a pos, or if \a pos
817	if greater than the size of the file, only as many data as available shall
818	be read, the function shall store the number of bytes actually read into the
819	variable pointed to by \a length, and return \c B_OK.
820
821	\param fs The volume handle.
822	\param vnode The node handle.
823	\param cookie The node cookie as returned by open().
824	\param pos The file position where to start reading data.
825	\param buffer Pointer to a pre-allocated buffer the read data shall be
826		written to.
827	\param length Pointer to a pre-allocated variable containing the size of the
828		buffer when invoked, and into which the size of the data actually read
829		shall be written.
830	\return \c B_OK if everything went fine, another error code otherwise.
831*/
832
833/*!
834	\fn status_t (*file_system_module_info::write)(fs_volume fs, fs_vnode vnode,
835			fs_cookie cookie, off_t pos, const void *buffer, size_t *length)
836	\brief Write data to a file.
837
838	This function should fail if
839	- the node is not a file,
840	- the cookie has not been opened for writing,
841	- \a pos is negative, or
842	- some other error occurs while trying to read the data, and no data have
843	been read at all.
844
845	The number of bytes to be written is stored in the variable pointed to by
846	\a length. If not all bytes could be written, that variable must be updated
847	to reflect the amount of actually written bytes. If an error prevented
848	you from writing the full amount, an appropriate error code should be
849	returned.
850
851	\param fs The file system provided cookie associated with this volume.
852	\param vnode The file system provided cookie associated with the vnode.
853	\param cookie The file system provided cookie associated with the file.
854	\param pos The position to start writing.
855	\param buffer The buffer that contains the data that will need to be written.
856	\param length The length of the data that needs to be written.
857	\return \c B_OK if everything went fine, another error code otherwise.
858*/
859
860//! @}
861
862/*!
863	\name Directory Operations
864*/
865
866/*!
867	\fn status_t (*file_system_module_info::create_dir)(fs_volume fs, fs_vnode
868			parent, const char *name, int perms, ino_t *_newVnodeID)
869	\brief Create a new directory.
870
871	Your implementation should make sure that the directory actually can be
872	created in the \a parent directory. You will have to check if the user has
873	permissions to actually write to the \a parent. If not, this function should
874	fail (probably with \c B_NOT_ALLOWED, or in case of a read-only filesystem,
875	with \c B_READ_ONLY_DEVICE). If the operation succeeds, you should put the
876	new vnode id in \a _newVnodeID.
877
878	\param fs The file system provided cookie associated with this volume.
879	\param parent The file system provided cookie associated with the parent
880		node.
881	\param name The name the new directory should have.
882	\param perms The permissions the new directory should have.
883	\param[out] _newVnodeID If creating the directory succeeds, than you should
884		put the new vnode id in this variable.
885	\return If the operation succeeds and the \a _newVnodeID is populated with
886		the new vnode, then you should return \c B_OK. Else you should return with
887		an error code.
888*/
889
890/*!
891	\fn status_t (*file_system_module_info::remove_dir)(fs_volume fs, fs_vnode
892			parent, const char *name)
893	\brief Remove a directory.
894
895	You should make sure the user has the proper permissions. You should also
896	check that the directory is empty.
897
898	\param fs The file system provided cookie associated with this volume.
899	\param parent The file system provided cookie associated with the parent
900		node.
901	\param name The \a name of the directory that needs to be removed.
902	\retval B_OK Operation succeeded.
903	\retval B_DIRECTORY_NOT_EMPTY The directory is not empty.
904	\retval B_ENTRY_NOT_FOUND There is no directory with this \a name.
905	\retval B_NOT_A_DIRECTORY The entry is not a directory.
906	\retval "other errors" Other errors occured.
907*/
908
909/*!
910	\fn status_t (*file_system_module_info::open_dir)(fs_volume fs, fs_vnode vnode,
911			fs_cookie *_cookie)
912	\brief Opens the given directory node.
913
914	If the specified node is not a directory, or if the current user does not
915	have the permissions to read the directory, the function shall fail.
916	Otherwise it shall allocate a directory cookie and store it in the variable
917	\a _cookie points to. A subsequent read_dir() using the cookie shall start
918	reading the first entry of the directory.
919
920	\param fs The volume handle.
921	\param vnode The node handle.
922	\param _cookie Pointer to a pre-allocated variable the directory cookie shall
923		be written to.
924	\return \c B_OK if everything went fine, another error code otherwise.
925*/
926
927/*!
928	\fn status_t (*file_system_module_info::close_dir)(fs_volume fs,
929			fs_vnode vnode, fs_cookie cookie)
930	\brief Closes the given directory cookie.
931
932	Generally the situation is similar to the one described for close(). In
933	practice it is a bit, though, since directory cookies are exclusively used
934	for directory iteration, and it normally doesn't make sense to have multiple
935	threads read the same directory concurrently. Furthermore reading a directory
936	should not block. Therefore for most FSs this hook is a no-op.
937
938	\param fs The volume handle.
939	\param vnode The node handle.
940	\param cookie The directory cookie as returned by open_dir().
941	\return \c B_OK if everything went fine, another error code otherwise.
942*/
943
944/*!
945	\fn status_t (*file_system_module_info::free_dir_cookie)(fs_volume fs,
946			fs_vnode vnode, fs_cookie cookie)
947	\brief Frees the given directory cookie.
948
949	The hook is invoked after close_dir(), when no other thread uses or is going
950	to use the cookie. All resources associated with the cookie must be freed.
951
952	\param fs The volume handle.
953	\param vnode The node handle.
954	\param cookie The directory cookie as returned by open_dir().
955	\return \c B_OK if everything went fine, another error code otherwise.
956*/
957
958/*!
959	\fn status_t (*file_system_module_info::read_dir)(fs_volume fs, fs_vnode vnode,
960			fs_cookie cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num)
961	\brief Reads the next one or more directory entries.
962
963	The number of entries to be read at maximum is stored in the variable \a _num
964	points to.
965
966	Per read \c dirent the following fields have to be filled in:
967	- \c d_dev: The volume ID.
968	- \c d_ino: The ID of the node the entry refers to.
969	- \c d_name: The null-terminated name of the entry.
970	- \c d_reclen: The size of the \c dirent structure in bytes, starting from
971	  the beginning of the structure, counting all bytes up to and including
972	  the null-termination char of the name stored in \c d_name.
973
974	If more than one entry is read, the corresponding \c dirent structures are
975	tightly packed, i.e. the second entry begins directly after the end of the
976	first one (i.e. \c d_reclen bytes after the beginning of the first one).
977	Most FSs read only one entry at a time though, even if more are requested.
978
979	When the function is invoked after the end of the directory has been reached,
980	it shall set the variable \a _num points to to \c 0 and return \c B_OK. If
981	the provided buffer is too small to contain even the single next entry,
982	\c B_BUFFER_OVERFLOW shall be returned. It shall not fail, if at least one
983	entry has been read, and the buffer is just too small to hold as many entries
984	as requested.
985
986	Note that a directory is expected to contain the special entries \c "." and
987	\c "..", referring to the same directory and the parent directory
988	respectively. The \c dirent structure returned for the \c ".." entry of the
989	volume's root directory shall refer to the root node itself.
990
991	\param fs The volume handle.
992	\param vnode The node handle.
993	\param cookie The directory cookie as returned by open_dir().
994	\param buffer Pointer to a pre-allocated buffer the directory entries shall
995		be written to.
996	\param bufferSize The size of \a buffer in bytes.
997	\param _num Pointer to a pre-allocated variable, when invoked, containing the
998		number of directory entries to be read, and into which the number of
999		entries actually read shall be written.
1000	\return \c B_OK if everything went fine, another error code otherwise.
1001*/
1002
1003/*!
1004	\fn status_t (*file_system_module_info::rewind_dir)(fs_volume fs,
1005			fs_vnode vnode, fs_cookie cookie)
1006	\brief Resets the directory cookie to the first entry of the directory.
1007	\param fs The volume handle.
1008	\param vnode The node handle.
1009	\param cookie The directory cookie as returned by open_dir().
1010	\return \c B_OK if everything went fine, another error code otherwise.
1011*/
1012
1013//! @}
1014
1015/*!
1016	\name Attribute Directory Operations
1017*/
1018
1019//! @{
1020
1021/*!
1022	\fn status_t (*file_system_module_info::open_attr_dir)(fs_volume fs, fs_vnode
1023			vnode, fs_cookie *_cookie)
1024	\brief Open a 'directory' of attributes for a \a vnode.
1025
1026	See \ref concepts "Generic Concepts" on directories and iterators. Basically,
1027	the VFS uses the same way of traversing through attributes as it traverses
1028	through a directory.
1029
1030	\param fs The file system provided cookie to the volume.
1031	\param vnode The vnode on which the file system wants to read the attributes.
1032	\param[out] _cookie Pointer where the file system can store a directory
1033		cookie if the attribute directory is succesfully opened.
1034	\return \c B_OK if everything went fine, another error code otherwise.
1035*/
1036
1037/*!
1038	\fn status_t (*file_system_module_info::close_attr_dir)(fs_volume fs,
1039			fs_vnode vnode, fs_cookie cookie)
1040	\brief Close a 'directory' of attributes for a \a vnode.
1041
1042	Note that you should free the cookie in the free_attr_dir_cookie() call.
1043
1044	\param fs The file system provided cookie to the volume.
1045	\param vnode The vnode on which the 'directory' was opened.
1046	\param cookie The cookie associated with this 'directory'.
1047	\return \c B_OK if everything went fine, another error code otherwise.
1048*/
1049
1050/*!
1051	\fn status_t (*file_system_module_info::free_attr_dir_cookie)(fs_volume fs,
1052			fs_vnode vnode, fs_cookie cookie)
1053	\brief Free the \a cookie to an attribute 'directory'.
1054
1055	\param fs The file system provided cookie to the volume.
1056	\param vnode The vnode on which the 'directory' was opened.
1057	\param cookie The cookie associated that should be freed.
1058	\return \c B_OK if everything went fine, another error code otherwise.
1059*/
1060
1061/*!
1062	\fn status_t (*file_system_module_info::read_attr_dir)(fs_volume fs, fs_vnode
1063			vnode, fs_cookie cookie, struct dirent *buffer, size_t bufferSize,
1064			uint32 *_num)
1065	\brief Read the next one or more attribute directory entries.
1066
1067	This method should perform the same tasks as read_dir(), except that the '.'
1068	and '..' entries do not have to be present.
1069*/
1070
1071/*!
1072	\fn status_t (*file_system_module_info::rewind_attr_dir)(fs_volume fs,
1073			fs_vnode vnode, fs_cookie cookie)
1074	\brief Rewind the attribute directory iterator to the first entry.
1075
1076	\param fs The file system provided cookie to the volume.
1077	\param vnode The vnode on which the 'directory' was opened.
1078	\param cookie The cookie associated with this 'directory'.
1079	\return \c B_OK if everything went fine, another error code otherwise.
1080*/
1081
1082//! @}
1083
1084/*!
1085	\name Attribute Operations
1086*/
1087
1088//! @{
1089
1090/*!
1091	\fn status_t (*file_system_module_info::create_attr)(fs_volume fs, fs_vnode
1092			vnode, const char *name, uint32 type, int openMode, fs_cookie *_cookie)
1093	\brief Create a new attribute.
1094
1095	If the attribute already exists, you should open it in truncated mode.
1096
1097	\param fs The file system provided cookie to the volume.
1098	\param vnode The file system provided cookie to the vnode.
1099	\param name The name of the attribute.
1100	\param type The \c type_code of the attribute.
1101	\param openMode The openMode of the associated attribute.
1102	\param[out] _cookie A pointer where you can store an associated file system
1103		cookie.
1104	\return \c B_OK if everything went fine, another error code otherwise.
1105*/
1106
1107/*!
1108	\fn status_t (*file_system_module_info::open_attr)(fs_volume fs, fs_vnode
1109			vnode, const char *name, int openMode, fs_cookie *_cookie)
1110	\brief Open an existing attribute.
1111
1112	\param fs The file system provided cookie to the volume.
1113	\param vnode The file system provided cookie to the vnode.
1114	\param name The name of the attribute.
1115	\param openMode The mode in which you want to open the attribute data.
1116	\param[out] _cookie A pointer where you can store an associated file system
1117		cookie.
1118	\return \c B_OK if everything went fine, another error code otherwise.
1119*/
1120
1121/*!
1122	\fn status_t (*file_system_module_info::close_attr)(fs_volume fs, fs_vnode
1123			vnode, fs_cookie cookie)
1124	\brief Close access to an attribute.
1125
1126	Note that you should not delete the cookie yet, you should do that when the
1127	VFS calls free_attr_cookie().
1128
1129	\param fs The file system provided cookie to the volume.
1130	\param vnode The file system provided cookie to the vnode.
1131	\param cookie The cookie you associated to this attribute.
1132	\return \c B_OK if everything went fine, another error code otherwise.
1133*/
1134
1135/*!
1136	\fn status_t (*file_system_module_info::free_attr_cookie)(fs_volume fs,
1137			fs_vnode vnode, fs_cookie cookie)
1138	\brief Free the cookie of an attribute.
1139
1140	The VFS calls this hook when all operations on the attribute have ceased.
1141
1142	\param fs The file system provided cookie to the volume.
1143	\param vnode The file system provided cookie to the vnode.
1144	\param cookie The cookie to the attribute that should be freed.
1145	\return \c B_OK if everything went fine, another error code otherwise.
1146*/
1147
1148/*!
1149	\fn status_t (*file_system_module_info::read_attr)(fs_volume fs, fs_vnode
1150			vnode, fs_cookie cookie, off_t pos, void *buffer, size_t *length)
1151	\brief Read attribute data associated with \a cookie.
1152
1153	Read until the \a buffer with size \a length is full, or until you are out of
1154	data, in which case you should update \a length.
1155
1156	\param fs The file system provided cookie to the volume.
1157	\param vnode The file system provided cookie to the vnode.
1158	\param cookie The cookie you associated to this attribute.
1159	\param pos The position to start reading from.
1160	\param buffer The buffer the data should be copied in.
1161	\param length The length of the buffer. Update this variable to the actual
1162		amount of bytes read.
1163	\return \c B_OK if everything went fine, another error code otherwise.
1164*/
1165
1166/*!
1167	\fn status_t (*file_system_module_info::write_attr)(fs_volume fs, fs_vnode
1168			vnode, fs_cookie cookie, off_t pos, const void *buffer, size_t *length)
1169	\brief Write attribute data associated with \a cookie.
1170
1171	\param fs The file system provided cookie to the volume.
1172	\param vnode The file system provided cookie to the vnode.
1173	\param cookie The cookie you associated with this attribute.
1174	\param pos The position to start writing to.
1175	\param buffer The buffer the data should be copied from.
1176	\param length The size of the buffer. Update this variable to the actual
1177		amount of bytes written.
1178	\return \c B_OK if everything went fine, another error code otherwise.
1179*/
1180
1181/*!
1182	\fn status_t (*file_system_module_info::read_attr_stat)(fs_volume fs,
1183			fs_vnode vnode, fs_cookie cookie, struct stat *stat)
1184	\brief Get the stats for an attribute.
1185
1186	\param fs The file system provided cookie to the volume.
1187	\param vnode The file system provided cookie to the vnode.
1188	\param cookie The cookie you associated with this attribute.
1189	\param stat A pointer to a stat structure you should fill.
1190	\return \c B_OK if everything went fine, another error code otherwise.
1191*/
1192
1193/*!
1194	\fn status_t (*file_system_module_info::write_attr_stat)(fs_volume fs,
1195			fs_vnode vnode, fs_cookie cookie, const struct stat *stat, int statMask)
1196	\brief Update the stats of an attribute.
1197
1198	\param fs The file system provided cookie to the volume.
1199	\param vnode The file system provided cookie to the vnode.
1200	\param cookie The cookie you associated with this attribute.
1201	\param stat A pointer to the new stats you should write.
1202	\param statMask One or more of the values of #write_stat_mask that tell you
1203		which fields of \a stat are to be updated.
1204	\return \c B_OK if everything went fine, another error code otherwise.
1205*/
1206
1207/*!
1208	\fn status_t (*file_system_module_info::rename_attr)(fs_volume fs,
1209			fs_vnode fromVnode, const char *fromName, fs_vnode toVnode,
1210			const char *toName)
1211	\brief Rename and/or relocate an attribute.
1212
1213	You should make sure the user has the proper permissions.
1214
1215	\param fs The file system provided cookie associated with this volume.
1216	\param fromVnode The cookie associated with the vnode the attribute currently
1217		is related to.
1218	\param fromName The old name of the attribute.
1219	\param toVnode The cookie associated with the vnode the attribute should be
1220		moved to. This can be the same as \a fromVnode, in which case it only means
1221		the attribute should be renamed.
1222	\param toName The new name of the attribute.This can be the same as
1223		\a fromName, in which case it only means the attribute should be relocated.
1224	\retval B_OK The renaming and/or relocating succeeded.
1225	\retval B_BAD_VALUE One of the supplied parameters were invalid.
1226	\retval B_NOT_ALLOWED The user does not have the proper permissions.
1227	\retval "other errors" Another error condition was encountered.
1228*/
1229
1230/*!
1231	\fn status_t (*file_system_module_info::remove_attr)(fs_volume fs,
1232			fs_vnode vnode, const char *name)
1233	\brief Remove an attribute.
1234
1235	\param fs The file system provided cookie to the volume.
1236	\param vnode The file system provided cookie to the vnode.
1237	\param name The name of the attribute.
1238	\return \c B_OK if everything went fine, another error code otherwise.
1239*/
1240
1241//! @}
1242
1243/*!
1244	\name Index Directory and Operation
1245*/
1246
1247//! @{
1248
1249/*!
1250	\fn status_t (*file_system_module_info::open_index_dir)(fs_volume fs,
1251			fs_cookie *_cookie)
1252	\brief Open the list of an indeces as a directory.
1253
1254	See \ref concepts "Generic Concepts" on directories and iterators. Basically,
1255	the VFS uses the same way of traversing through indeces as it traverses
1256	through a directory.
1257
1258	\param fs The file system provided cookie to the volume.
1259	\param[out] _cookie Pointer where the file system can store a directory
1260		cookie if the index directory is succesfully opened.
1261	\return \c B_OK if everything went fine, another error code otherwise.
1262*/
1263
1264/*!
1265	\fn status_t (*file_system_module_info::close_index_dir)(fs_volume fs,
1266			fs_cookie cookie)
1267	\brief Close a 'directory' of indeces.
1268
1269	Note that you should free the cookie in the free_index_dir_cookie() call.:
1270
1271	\param fs The file system provided cookie to the volume.
1272 	\param cookie The cookie associated with this 'directory'.
1273	\return B_OK if everything went fine, another error code otherwise.
1274*/
1275
1276/*!
1277	\fn status_t (*file_system_module_info::free_index_dir_cookie)(fs_volume fs,
1278			fs_cookie cookie)
1279	\brief Free the \a cookie to the index 'directory'.
1280
1281	\param fs The file system provided cookie for the volume.
1282	\param cookie The cookie that should be freed.
1283	\return B_OK if everything went fine, another error code otherwise.
1284*/
1285
1286/*!
1287	\fn status_t (*file_system_module_info::read_index_dir)(fs_volume fs,
1288			fs_cookie cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num)
1289	\brief Read the next one or more index entries.
1290
1291	This method should perform the same task as read_dir(), except that the '.'
1292	and the '..' entries don't have to be present.
1293*/
1294
1295/*!
1296	\fn status_t (*file_system_module_info::rewind_index_dir)(fs_volume fs,
1297			fs_cookie cookie)
1298	\brief Reset the index directory cookie to the first entry of the directory.
1299
1300	\param fs The file system provided handle to the volume.
1301	\param cookie The directory cookie as returned by open_index_dir().
1302	\return \c B_OK if everything went fine, another error code otherwise.
1303*/
1304
1305/*!
1306	\fn status_t (*file_system_module_info::create_index)(fs_volume fs,
1307			const char *name, uint32 type, uint32 flags)
1308	\brief Create a new index.
1309
1310	\param fs The file system provided handle to the volume.
1311	\param name The name of the new index.
1312	\param type The type of index. BFS implements the following types:
1313		- \c B_INT32_TYPE
1314		- \c B_UINT32_TYPE
1315		- \c B_INT64_TYPE
1316		- \c B_UINT64_TYPE
1317		- \c B_FLOAT_TYPE
1318		- \c B_DOUBLE_TYPE
1319		- \c B_STRING_TYPE
1320		- \c B_MIME_STRING_TYPE
1321	\param flags There are currently no extra flags specified. This parameter can
1322		be ignored.
1323	\return You should return \c B_OK if the creation succeeded, or return an
1324		error otherwise.
1325*/
1326
1327/*!
1328	\fn status_t (*file_system_module_info::remove_index)(fs_volume fs,
1329			const char *name)
1330	\brief Remove the index with \a name.
1331
1332	\param fs The file system provided handle to the volume.
1333	\param name The name of the index to be removed.
1334	\return You should return \c B_OK if the creation succeeded, or return an
1335		error otherwise.
1336*/
1337
1338/*!
1339	\fn status_t (*file_system_module_info::read_index_stat)(fs_volume fs,
1340			const char *name, struct stat *stat)
1341	\brief Read the \a stat of the index with a name.
1342
1343	\param fs The file system provided handle to the volume.
1344	\param name The name of the index to be queried.
1345	\param stat A pointer to a structure where you should store the values.
1346	\return You should return \c B_OK if the creation succeeded, or return an
1347		error otherwise.
1348*/
1349
1350//! @}
1351
1352/*!
1353	\name Query Operations
1354*/
1355
1356//! @{
1357
1358/*!
1359	\fn status_t (*file_system_module_info::open_query)(fs_volume fs,
1360			const char *query, uint32 flags, port_id port, uint32 token,
1361			fs_cookie *_cookie)
1362	\brief Open a query as a 'directory'.
1363
1364	TODO: query expressions should be documented and also the format for sending
1365	query updates over the port should be updated.
1366
1367	See \ref concepts "Generic Concepts" on directories and iterators. Basically,
1368	the VFS uses the same way of traversing through indeces as it traverses
1369	through a directory.
1370
1371	\param fs The file system provided cookie to the volume.
1372	\param query The string that represents a query.
1373	\param flags Either one of these flags:
1374		- \c #B_LIVE_QUERY The query is live. When a query is live, it is
1375		  constantly updated using the \a port. In this case the file system should
1376		  be pro-active.
1377		- \c #B_QUERY_NON_INDEXED When this parameter is provided, the query
1378		  should be carried out over the whole file system. This parameter is
1379		  provided with the idea that sometimes the indeces can be out of date. If
1380		  the requestor for this query requires absolutely everything to be
1381		  queried, it will pass this parameter. Of course, if your indeces are
1382		  always up to date, you can ignore this parameter.
1383	\param port The id of the port where updates need to be sent to in case the
1384		query is live.
1385	\param token A token that should be attached to the messages sent over the
1386		\a port.
1387	\param[out] _cookie The cookie that will be used as 'directory' to traverse
1388		through the results of the query.
1389	\return You should return \c B_OK if the creation succeeded, or return an
1390		error otherwise.
1391*/
1392
1393/*!
1394	\fn status_t (*file_system_module_info::close_query)(fs_volume fs,
1395			fs_cookie cookie)
1396	\brief Close a 'directory' of a query.
1397
1398	Note that you should free the cookie in the free_query_cookie() call.
1399
1400	\param fs The file system provided cookie to the volume.
1401	\param cookie The cookie that refers to this query.
1402	\return You should return \c B_OK if the creation succeeded, or return an
1403		error otherwise.
1404*/
1405
1406/*!
1407	\fn status_t (*file_system_module_info::free_query_cookie)(fs_volume fs,
1408			fs_cookie cookie)
1409	\brief Free a cookie of a query.
1410
1411	\param fs The file system provided cookie to the volume.
1412	\param cookie The cookie that should be freed.
1413	\return You should return \c B_OK if the creation succeeded, or return an
1414		error otherwise.
1415*/
1416
1417/*!
1418	\fn status_t (*file_system_module_info::read_query)(fs_volume fs,
1419			fs_cookie cookie, struct dirent *buffer, size_t bufferSize, uint32 *_num)
1420	\brief Read the next one or more entries matching the query.
1421
1422	This hook function works pretty much the same way as read_dir(), with the
1423	difference that it doesn't read the entries of a directory, but the entries
1424	matching the given query.
1425
1426	\param fs The volume handle.
1427	\param cookie The query cookie as returned by open_query().
1428	\param buffer Pointer to a pre-allocated buffer the directory entries shall
1429		be written to.
1430	\param bufferSize The size of \a buffer in bytes.
1431	\param _num Pointer to a pre-allocated variable, when invoked, containing the
1432		number of entries to be read, and into which the number of entries
1433		actually read shall be written.
1434	\return \c B_OK if everything went fine, another error code otherwise.
1435*/
1436
1437/*!
1438	\fn status_t (*file_system_module_info::rewind_query)(fs_volume fs,
1439			fs_cookie cookie)
1440	\brief Reset the query cookie to the first entry of the results.
1441
1442	\param fs The file system provided handle to the volume.
1443	\param cookie The query cookie as returned by open_query().
1444	\return \c B_OK if everything went fine, another error code otherwise.
1445*/
1446
1447//! @}
1448
1449/*!
1450	\name Capability Querying
1451*/
1452
1453//! @{
1454
1455/*!
1456	\fn bool (*file_system_module_info::supports_defragmenting)(partition_data
1457		*partition, bool *whileMounted)
1458	\brief Undocumented. TODO.
1459*/
1460
1461/*!
1462	\fn bool (*file_system_module_info::supports_repairing)(partition_data *partition,
1463			bool checkOnly, bool *whileMounted)
1464	\brief Undocumented. TODO.
1465*/
1466
1467/*!
1468	\fn bool (*file_system_module_info::supports_resizing)(partition_data *partition,
1469			bool *whileMounted)
1470	\brief Undocumented. TODO.
1471*/
1472
1473/*!
1474	\fn bool (*file_system_module_info::supports_moving)(partition_data *partition, bool *isNoOp)
1475	\brief Undocumented. TODO.
1476*/
1477
1478/*!
1479	\fn bool (*file_system_module_info::supports_setting_content_name)(partition_data *partition,
1480			bool *whileMounted)
1481	\brief Undocumented. TODO.
1482*/
1483
1484/*!
1485	\fn bool (*file_system_module_info::supports_setting_content_parameters)(partition_data *partition,
1486			bool *whileMounted)
1487	\brief Undocumented. TODO.
1488*/
1489
1490/*!
1491	\fn bool (*file_system_module_info::supports_initializing)(partition_data *partition)
1492	\brief Undocumented. TODO.
1493*/
1494
1495/*!
1496	\fn bool (*file_system_module_info::validate_resize)(partition_data *partition, off_t *size)
1497	\brief Undocumented. TODO.
1498*/
1499
1500/*!
1501	\fn bool (*file_system_module_info::validate_move)(partition_data *partition, off_t *start)
1502	\brief Undocumented. TODO.
1503*/
1504
1505/*!
1506	\fn bool (*file_system_module_info::validate_set_content_name)(partition_data *partition,
1507			char *name)
1508	\brief Undocumented. TODO.
1509*/
1510
1511/*!
1512	\fn bool (*file_system_module_info::validate_set_content_parameters)(partition_data *partition,
1513			const char *parameters)
1514	\brief Undocumented. TODO.
1515*/
1516
1517/*!
1518	\fn bool (*file_system_module_info::validate_initialize)(partition_data *partition, char *name,
1519			const char *parameters)
1520	\brief Undocumented. TODO.
1521*/
1522
1523//! @}
1524
1525/*!
1526	\name Shadow Partition Modification
1527*/
1528
1529//! @{
1530
1531/*!
1532	\fn status_t (*file_system_module_info::shadow_changed)(partition_data *partition,
1533			uint32 operation)
1534	\brief Undocumented. TODO.
1535*/
1536
1537//! @}
1538
1539/*!
1540	\name Special Operations
1541*/
1542
1543//! @{
1544
1545/*!
1546	\fn status_t (*file_system_module_info::defragment)(int fd, partition_id partition,
1547			disk_job_id job)
1548	\brief Undocumented. TODO.
1549*/
1550
1551/*!
1552	\fn status_t (*file_system_module_info::repair)(int fd, partition_id partition, bool checkOnly,
1553			disk_job_id job)
1554	\brief Undocumented. TODO.
1555*/
1556
1557/*!
1558	\fn status_t (*file_system_module_info::resize)(int fd, partition_id partition, off_t size,
1559			disk_job_id job)
1560	\brief Undocumented. TODO.
1561*/
1562
1563/*!
1564	\fn status_t (*file_system_module_info::move)(int fd, partition_id partition, off_t offset,
1565			disk_job_id job)
1566	\brief Undocumented. TODO.
1567*/
1568
1569/*!
1570	\fn status_t (*file_system_module_info::set_content_name)(int fd, partition_id partition,
1571			const char *name, disk_job_id job)
1572	\brief Undocumented. TODO.
1573*/
1574
1575/*!
1576	\fn status_t (*file_system_module_info::set_content_parameters)(int fd, partition_id partition,
1577			const char *parameters, disk_job_id job)
1578	\brief Undocumented. TODO.
1579*/
1580
1581/*!
1582	\fn status_t (*file_system_module_info::initialize)(const char *partition, const char *name,
1583			const char *parameters, disk_job_id job)
1584	\brief Undocumented. TODO.
1585*/
1586
1587//! @}
1588
1589///// Vnode functions /////
1590
1591/*!
1592	\fn status_t new_vnode(dev_t mountID, ino_t vnodeID,
1593			fs_vnode privateNode)
1594	\brief Create the vnode with ID \a vnodeID and associates it with the
1595		private data handle \a privateNode, but leaves is in an unpublished state.
1596
1597	The effect of the function is similar to publish_vnode(), but the vnode
1598	remains in an unpublished state, with the effect that a subsequent
1599	remove_vnode() will just delete the vnode and not invoke the file system's
1600	\link file_system_module_info::remove_vnode remove_vnode() \endlink when
1601	the final reference is put down.
1602
1603	If the vnode shall be kept, publish_vnode() has to be invoked afterwards to
1604	mark the vnode published. The combined effect is the same as only invoking
1605	publish_vnode().
1606
1607	You'll usually use this function to secure a vnode ID from being reused
1608	while you are in the process of creating the entry. Note that this function
1609	will panic in case you call it for an existing vnode ID.
1610
1611	The function fails, if the vnode does already exist.
1612
1613	\param mountID The ID of the volume.
1614	\param vnodeID The ID of the node.
1615	\param privateNode The private data handle to be associated with the node.
1616	\return \c B_OK if everything went fine, another error code otherwise.
1617*/
1618
1619/*!
1620	\fn status_t publish_vnode(dev_t mountID, ino_t vnodeID,
1621			fs_vnode privateNode)
1622	\brief Creates the vnode with ID \a vnodeID and associates it with the
1623		private data handle \a privateNode or just marks it published.
1624
1625	If the vnode does already exist and has been published, the function fails.
1626	If it has not been published yet (i.e. after a successful new_vnode()), the
1627	function just marks the vnode published. If the vnode did not exist at all
1628	before, it is created and published.
1629
1630	If the function is successful, the caller owns a reference to the vnode. A
1631	sequence of new_vnode() and publish_vnode() results in just one reference as
1632	well. The reference can be surrendered by calling put_vnode().
1633
1634	This call is equivalent to the former R5 new_vnode() function.
1635
1636	\param mountID The ID of the volume.
1637	\param vnodeID The ID of the node.
1638	\param privateNode The private data handle to be associated with the node.
1639	\return \c B_OK if everything went fine, another error code otherwise.
1640*/
1641
1642/*!
1643	\fn status_t get_vnode(dev_t mountID, ino_t vnodeID,
1644			fs_vnode *_privateNode)
1645	\brief Retrieves the private data handle for the node with the given ID.
1646
1647	If the function is successful, the caller owns a reference to the vnode. The
1648	reference can be surrendered by calling put_vnode().
1649
1650	\param mountID The ID of the volume.
1651	\param vnodeID The ID of the node.
1652	\param _privateNode Pointer to a pre-allocated variable the private data
1653		handle shall be written to.
1654	\return \c B_OK if everything went fine, another error code otherwise.
1655*/
1656
1657/*!
1658	\fn status_t put_vnode(dev_t mountID, ino_t vnodeID)
1659	\brief Surrenders a reference to the specified vnode.
1660	\param mountID The ID of the volume.
1661	\param vnodeID The ID of the node.
1662	\return \c B_OK if everything went fine, another error code otherwise.
1663*/
1664
1665/*!
1666	\fn status_t remove_vnode(dev_t mountID, ino_t vnodeID)
1667	\brief Marks the specified vnode removed.
1668
1669	The caller must own a reference to the vnode or at least ensure that a
1670	reference to the vnode exists. The function does not surrender a reference,
1671	though.
1672
1673	As soon as the last reference to the vnode has been surrendered, the VFS
1674	invokes the file system's
1675	\link file_system_module_info::remove_vnode remove_vnode() \endlink
1676	hook.
1677
1678	\param mountID The ID of the volume.
1679	\param vnodeID The ID of the node.
1680	\return \c B_OK if everything went fine, another error code otherwise.
1681*/
1682
1683/*!
1684	\fn status_t unremove_vnode(dev_t mountID, ino_t vnodeID);
1685	\brief Clears the "removed" mark of the specified vnode.
1686
1687	The caller must own a reference to the vnode or at least ensure that a
1688	reference to the vnode exists.
1689
1690	The function is usually called when the caller, who has invoked
1691	remove_vnode() before realizes that it is not possible to remove the node
1692	(e.g. due to an error).
1693
1694	\param mountID The ID of the volume.
1695	\param vnodeID The ID of the node.
1696	\return \c B_OK if everything went fine, another error code otherwise.
1697*/
1698
1699/*!
1700	\fn status_t get_vnode_removed(dev_t mountID, ino_t vnodeID,
1701			bool* removed);
1702	\brief Returns whether the specified vnode is marked removed.
1703
1704	The caller must own a reference to the vnode or at least ensure that a
1705	reference to the vnode exists.
1706
1707	\param mountID The ID of the volume.
1708	\param vnodeID The ID of the node.
1709	\param removed Pointer to a pre-allocated variable set to \c true, if the
1710		node is marked removed, to \c false otherwise.
1711	\return \c B_OK if everything went fine, another error code otherwise.
1712*/
1713
1714///// Notification Functions
1715
1716/*!
1717	\name Notification Functions
1718
1719	The following functions are used to implement the node monitor functionality
1720	in your file system. Whenever one of the below mentioned events occur, you
1721	have to call them.
1722
1723	The node monitor will then notify all registered listeners for the nodes
1724	that changed.
1725*/
1726
1727/*!
1728	\fn status_t notify_entry_created(dev_t device, ino_t directory,
1729			const char *name, ino_t node)
1730	\brief Notifies listeners that a file system entry has been created.
1731*/
1732
1733/*!
1734	\fn status_t notify_entry_removed(dev_t device, ino_t directory,
1735			const char *name, ino_t node)
1736	\brief Notifies listeners that a file system entry has been removed.
1737*/
1738
1739/*!
1740	\fn status_t notify_entry_moved(dev_t device, ino_t fromDirectory,
1741			const char *fromName, ino_t toDirectory,
1742			const char *toName, ino_t node)
1743	\brief Notifies listeners that a file system entry has been moved to
1744		another directory.
1745*/
1746
1747/*!
1748	\fn status_t notify_stat_changed(dev_t device, ino_t node,
1749			uint32 statFields)
1750	\brief Notifies listeners that certain \a statFields of a file system entry
1751		were updated.
1752*/
1753
1754/*!
1755	\fn status_t notify_attribute_changed(dev_t device, ino_t node,
1756			const char *attribute, int32 cause)
1757	\brief Notifies listeners that an attribute of a file system entry has been
1758		changed.
1759*/
1760
1761/*!
1762	\fn status_t notify_query_entry_created(port_id port, int32 token,
1763			dev_t device, ino_t directory, const char *name,
1764			ino_t node)
1765	\brief Notifies listeners that an entry has entered the result set of a live query.
1766*/
1767
1768/*!
1769	\fn status_t notify_query_entry_removed(port_id port, int32 token,
1770			dev_t device, ino_t directory, const char *name,
1771			ino_t node)
1772	\brief Notifies listeners that an entry has left the result set of a live query.
1773*/
1774
1775//! @}
1776