* Completed some more missing parts.

* Replaced some more spaces with tabs, though still not complete.
* And I forgot: the last commit also removed some garbage at the beginning of the file.


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21617 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/user/drivers/fs_interface.dox

@@ -272,7 +272,8 @@
 	The VFS layer sometimes wants you to synchronize any cached values with the
 	data on the device.
 
-  TODO: WHEN IS THIS CALLED AND FOR WHAT PURPOSE?
+	This currently only happens when the POSIX sync() function is invoked, for
+	example via the "sync" command line tool.
 
 	\param fs The cookie your filesystem supplied to the volume that should be
 		updated.
@@ -323,6 +324,12 @@
 		fs_vnode vnode, char *buffer, size_t bufferSize)
 	\brief Return the file name of a vnode.
 
+	Note that you don't have to implement this call if it can't be easily done;
+	it's completely optional.
+	If you don't implement it, you'll have to export a NULL pointer for this
+	function in the module definition. In this case, the VFS will find the name
+	by iterating over its parent directory.
+
 	\param fs The file system provided cookie associated with this volume.
 	\param vnode The file system provided cookie associated with this vnode.
 	\param buffer The buffer that the name can be copied into.
@@ -338,6 +345,10 @@
 		referred to by \a id.
 
 	Invoked by the VFS when it creates the vnode for the respective node.
+	When the VFS no longer needs the vnode in memory (for example when
+	memory is becoming tight), it will your file_system_module_info::put_vnode(),
+	or file_system_module_info::remove_vnode() in case the vnode has been
+	marked removed.
 
 	\param fs The volume handle.
 	\param id The ID of the node.
@@ -369,7 +380,7 @@
 	\brief Deletes the private data handle associated with the specified node.
 
 	Invoked by the VFS when it deletes the vnode for the respective node and the
-  node is marked removed.
+	node has been marked removed by a call to remove_vnode().
 
 	\param fs The volume handle.
 	\param vnode The node handle.
@@ -392,19 +403,20 @@
 
 	TODO: In both the dos and the bfs implementations this thing simply returns
 	false... Is there anything more to it?
+	This call might be removed in the future - it's currently unused.
 */
 
 /*!
-  \fn status_t (*file_system_module_info::read_pages)(fs_volume fs, fs_vnode vnode, fs_cookie cookie,
+	\fn status_t (*file_system_module_info::read_pages)(fs_volume fs, fs_vnode vnode,
-				off_t pos, const iovec *vecs, size_t count, size_t *_numBytes,
+			fs_cookie cookie, off_t pos, const iovec *vecs, size_t count,
-				bool reenter)
+			size_t *_numBytes, bool reenter)
 	\brief Undocumented. TODO.
 */
 
 /*!
-  \fn status_t (*file_system_module_info::write_pages)(fs_volume fs, fs_vnode vnode, fs_cookie cookie,
+	\fn status_t (*file_system_module_info::write_pages)(fs_volume fs, fs_vnode vnode,
-				off_t pos, const iovec *vecs, size_t count, size_t *_numBytes,
+			fs_cookie cookie, off_t pos, const iovec *vecs, size_t count,
-				bool reenter)
+			size_t *_numBytes, bool reenter)
   \brief Undocumented. TODO.
 */
 
@@ -417,9 +429,15 @@
 //! @{
 
 /*!
-  \fn status_t (*file_system_module_info::get_file_map)(fs_volume fs, fs_vnode vnode, off_t offset,
+	\fn status_t (*file_system_module_info::get_file_map)(fs_volume fs,
-				size_t size, struct file_io_vec *vecs, size_t *_count)
+			fs_vnode vnode, off_t offset, size_t size, struct file_io_vec *vecs,
-  \brief Undocumented. TODO.
+			size_t *_count)
+	\brief Fills the \a vecs with the extents of the file data stream.
+
+	This function is called only when you are using the file cache, but if you
+	use it, its implementation is mandatory.
+
+	TODO: complete me
 */
 
 //! @}
@@ -468,19 +486,35 @@
 */
 
 /*!
-  \fn status_t (*file_system_module_info::select)(fs_volume fs, fs_vnode vnode, fs_cookie cookie,
+	\fn status_t (*file_system_module_info::select)(fs_volume fs, fs_vnode vnode,
-				uint8 event, uint32 ref, selectsync *sync)
+			fs_cookie cookie, uint8 event, uint32 ref, selectsync *sync)
-  \brief Undocumented. TODO.
+	\brief Selects the specified \a vnode with the specified \a events.
 
-  TODO: What should this do?
+	This function is called by the VFS whenever select() or poll() is called on
+	a file descriptor that points to your file system.
+
+	You have to check if the condition of the select() (ie. if there is data
+	available if event is B_SELECT_READ) is already satisfied, and call
+	notify_select_event() with the \a sync and \a ref arguments you retrieve
+	here.
+
+	Additionally, when a vnode is selected this way, you have to call
+	notify_select_event() whenever the condition becomes true until the
+	vnode is deselected again via file_system_module_info::deselect().
+
+	This function is optional. If you don't export it, the default implementation
+	in the VFS will call notify_select_event() directly which will be sufficient
+	for most file systems.
 */
 
 /*!
 	\fn status_t (*file_system_module_info::deselect)(fs_volume fs, fs_vnode vnode, fs_cookie cookie,
 			uint8 event, selectsync *sync)
-  \brief Undocumented. TODO.
+	\brief Deselects the specified \a vnode from a previous select() call.
 
-  TODO: What should this do?
+	This function is called by the VFS whenever a select() or poll() function
+	exits that previously called file_system_module_info::select() on that
+	\a vnode.
 */
 
 /*!
@@ -542,6 +576,9 @@
 	The virtual file system will request the creation of symbolic links with
 	create_symlink().
 
+	If you don't implement this function, the VFS will return \c EROFS
+	when a hard link is requested.
+
 	\param fs The file system provided cookie associated with this volume.
 	\param dir The cookie associated to the directory where the link should be
 		saved.
@@ -735,7 +772,7 @@
 	an operation using the cookie, and mark the cookie such that no further
 	threads will block using it.
 
-  For many FSs this hook is a no-op.
+	For many FSs this hook is a no-op - it's mandatory to be exported, though.
 
 	\param fs The volume handle.
 	\param vnode The node handle.
@@ -800,10 +837,10 @@
 	been read at all.
 
 	The number of bytes to be written is stored in the variable pointed to by
-  \a length.
+	\a length. If not all bytes could be written, that variable must be updated
-  
+	to reflect the amount of actually written bytes. If an error prevented
-  TODO: What to do if we were to write less than the \a length? Should this
+	you from writing the full amount, an appropriate error code should be
-  function fail? 
+	returned.
 
 	\param fs The file system provided cookie associated with this volume.
 	\param vnode The file system provided cookie associated with the vnode.