[haiku-development] Re: Filesystem API documentation
- From: Ingo Weinhold <bonefish@xxxxxxxxxxxxxxx>
- To: haiku-development@xxxxxxxxxxxxx
- Date: Sun, 15 Jul 2007 14:46:09 +0200
On 2007-07-15 at 13:05:36 [+0200], Niels Reedijk <niels.reedijk@xxxxxxxxx>
wrote:
> 2007/7/14, Axel Dörfler <axeld@xxxxxxxxxxxxxxxx>:
> > "Niels Reedijk" <niels.reedijk@xxxxxxxxx> wrote:
>
> > > - Also, there are a few notify functions that are documented as
> > > deprecated, but what will come in place?
> >
> > The replacements are already in place - the notify_listener() function
> > was formerly used for all kinds of notifications; now, it has been
> > divided into several ones.
>
> Okay, I'll update the documentation to reflect that soon. It looked as
> if all notify* functions were deprecated.
No, only notify_listener(). There was also a send_notification(), but that
one is already gone.
> Is there any reason not to
> remove notify_listener() right now? (perhaps a good small task for a
> willing new young developer?)
The only reason is, that there are file systems still using it. It shouldn't
be that much of a problem to change that, though. Some of our new notify_*()
functions require a bit more info, but that should usally be available
anyway.
> > > - In which hooks should file system developers use the vnode
> > > functions
> > > in fs_interface.h?
> >
> > I don't understand this question.
>
> http://factory.haiku-os.org/documentation/Haiku_Book_doxygen/html/fs__interface_8h.html
>
> There are several *_vnode functions. I've had another look at them,
> and I might be able to manage finding the correct meaning. I'll try
> that later.
In some of the cases where a node ID is returned (mount(), lookup(), and
create(), but not create_dir()) the FS is supposed to acquire a vnode
reference for the caller, i.e. it has to invoke a publish_vnode() or
get_vnode() (not balanced by a put_vnode()). In cases where the last entry
referring to a node has been removed (potentially unlink() and
remove_dir()), remove_vnode() shall be called. Unless I missed something,
other than that the FS is not required to call anything, and free to call
whatever it needs, which will usually be balanced get_vnode()/put_vnode()
pairs.
BTW, calling the VFS functions is not restricted to happen from within the
hooks only. E.g. in a network FS you're like running a thread communicating
with other hosts (respectively a server) and which propagates changes done
by other clients. It will have to use the VFS functions, too.
> > I currently haven't got the time to look into your documentation
> > itself, but there is no code that depends on specific error code -
> > expecting specific error codes is often a sign of bad code; it should
> > only be used where it makes sense (like when dealing with semaphores),
> > or when you always have control over all the code (ie. it would be a
> > particularly bad thing to check for error codes coming from arbitrary
> > file system implementations).
>
> I see what you mean, but I think that it's good and consistent to use
> B_NOT_ALLOWED when the user does not have the proper permissions to do
> things, is a good convention. In other words, is there a list of
> commonly used error codes when it comes to dealing with filesystems?
There's no list, but there're rules dictated by the POSIX standard. A good
deal of FS hooks directly correspond to POSIX functions. The VFS passes the
error codes returned by the hooks directly back to the userland. Therefore
the hook should behave in way that complies with the POSIX function
semantics, including error codes.
CU, Ingo
Other related posts:
