API documentation, and differences of the two C libraries

[Alejandro Exojo]

Hi.

I'm a bit confused as to what API documentation there is (if any) provided by OSXFUSE. From what I've read in the wiki pages and previous questions to the group, and what I've found in the code, I've drawn this conclusions. Please, correct me if something is wrong:

- The kernel specific parts are completely independent from the Linux version. That's irrelevant to application developers, unless they want to contribute to the driver itself.

- The Objective C layer wraps the C code, so if you were to use another language, better target the C library.

- The C library was based on the Linux one, and it should be compatible because the FUSE filesystems work.

- libfuse is for MacFUSE compatibility, and libosxfuse is the newer one.

Now my doubts:

- What are exactly the differences of the two libraries? The FAQ page says they use the same headers, which look a lot like the Linux's versions. One message to the group mentions libosxfuse as a superset of libfuse. But what adds? The obvious would be the fuse_darwin.h, but that seems to be from MacFUSE if the copyright is up to date.

- Is there any reference documentation, or should one go the one published in the "original" FUSE website? I could do just by looking at the headers, but I would like to know the differences between Linux and Mac if possible.

Thank you very much.

[Sam Moffatt]

Not sure if I can give you a reasonable answer but I'll take a stab. I've only ever used the C library so can't comment on Obj-C. 

Fundamentally most of it is compatible with the base FUSE however the devil is in the detail of the Mac VFS layer. Once you've set up the callbacks, the documentation I've always used is the standard man pages for the system calls. Most of the system calls are the same across the platforms (Darwin vs Linux) though there are places where they deviate. Not sure if this is particularly helpful but realistically for the C stuff all I've relied upon is the man pages for the system calls.

Cheers,

Sam

--

Sam Moffatt

http://pasamio.id.au

Note: I'm not at my desk, responses may be delayed. Apologies for the typos, smartphones aren't all that smart. 

--
You received this message because you are subscribed to the Google Groups "OSXFUSE" group.
To unsubscribe from this group and stop receiving emails from it, send an email to osxfuse-grou...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Alejandro Exojo]

On 3 June 2015 at 07:05, Sam Moffatt <pas...@gmail.com> wrote:
> Not sure if I can give you a reasonable answer but I'll take a stab. I've only ever used the C library so can't comment on Obj-C.
>
> Fundamentally most of it is compatible with the base FUSE however the devil is in the detail of the Mac VFS layer. Once you've set up the callbacks, the documentation I've always used is the standard man pages for the system calls. Most of the system calls are the same across the platforms (Darwin vs Linux) though there are places where they deviate. Not sure if this is particularly helpful but realistically for the C stuff all I've relied upon is the man pages for the system calls.
>

Thank you very much for sharing your experience. This is more or less
what I'll need for starting with filling the operations struct, and I
think it will be sufficiently good documentation. What worries me a
bit is reading that there might be differences, and not knowing for
sure if those will be in the fuse_* functions. I'll try diffing the
headers from time to time, then, since the documentation is there in
the Doxygen comments.

Thank you.

[Benjamin Fleischer]

- The kernel specific parts are completely independent from the Linux version. That's irrelevant to application developers, unless they want to contribute to the driver itself.

Correct.

- The Objective C layer wraps the C code, so if you were to use another language, better target the C library.

It’s basically a layer model. The Objective-C framework is located above libosxfuse. It implements the high-level C API of libosxfuse and does not communicate with the kernel directly. Most importantly there are some features of libosxfuse that are not exposed by the Objective-C framework.

The Objective C framework includes Bridge support. I’ve never used it myself but in theory it should get you bindings for Ruby an Python for free. See https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/BridgeSupport.5.html for details.

- The C library was based on the Linux one, and it should be compatible because the FUSE filesystems work.

Yes, libosxfuse is a modified version of Linux libfuse.

- libfuse is for MacFUSE compatibility, and libosxfuse is the newer one.

Correct. You should never link against libfuse (MacFUSE compatibility layer), always use libosxfuse.

- What are exactly the differences of the two libraries? The FAQ page says they use the same headers, which look a lot like the Linux's versions. One message to the group mentions libosxfuse as a superset of libfuse.

osxfuse 2.x does not ship with headers for libfuse (MacFUSE compatibility layer). It only includes headers for libosxfuse that are located at /usr/local/include/osxfuse.

In osxfuse 2.x libfuse and libosxfuse are almost identical. In fact libfuse re-exports libosxfuse’s symbols and adds a couple MacFUSE specific functions. It exists mainly for enabling the MacFUSE compatibility mode in kernel and for future-proofing.

In osxfuse 3.x libfuse and libosxfuse are two completely independent libraries. libfuse (MacFUSE compatibility layer) is based on Linux libfuse 2.7.3 while libosxfuse is based on Linux libfuse 2.9.3.

But what adds? The obvious would be the fuse_darwin.h, but that seems to be from MacFUSE if the copyright is up to date.

The copyright is not always up to date. libosxfuse adds several osxfuse specific file systems callbacks like exchange, getxtimes, and setattr_x. For a complete list see fuse.h and fuse_lowlevel.h.

There are more additions but it would take too much time to list them all. Please see https://github.com/osxfuse/fuse/commits/fuse-2.7 for details. 4a541a9617e2f6cf6762d78dd8554d7b92e09485 is the last Linux FUSE commit. Everything after that are OS X specific changes. 

- Is there any reference documentation, or should one go the one published in the "original" FUSE website? I could do just by looking at the headers, but I would like to know the differences between Linux and Mac if possible.

You can go to the Linux FUSE website or take a look at example file systems. Many FUSE file systems should work on OS X out of the box. Some require minor tweaks. There is no specific documentation outlining the differences between Linux FUSE and osxfuse.

Regards,

Benjamin

[Alejandro Exojo]

On 3 June 2015 at 20:33, Benjamin Fleischer <fle...@gmail.com> wrote:

You can go to the Linux FUSE website or take a look at example file systems. Many FUSE file systems should work on OS X out of the box. Some require minor tweaks. There is no specific documentation outlining the differences between Linux FUSE and osxfuse.

Thank you very much for this detailed answer! It's very much appreciated. When doing the Windows version of the project I've been able to send some minor fixes and documentation. I hope I can help osxfuse as well, now with a better overview of the situation. :-)

Regards.