1 files changed, 90 insertions, 2 deletions

diff --git a/include/fuse.h b/include/fuse.h
index 4edb0c7..4cddaaf 100644
--- a/include/fuse.h
+++ b/include/fuse.h
@@ -12,16 +12,56 @@
 #include <sys/stat.h>
 #include <utime.h>
 
+/** Handle for a FUSE filesystem */
 struct fuse;
+
+/** Handle for a getdir() operation */
 typedef struct fuse_dirhandle *fuse_dirh_t;
 
+/** Function to add an entry in a getdir() operation */
 typedef int (*fuse_dirfil_t) (fuse_dirh_t, const char *, int type);
 
+/** Credentials for an operation, these are determined by the fsuid
+    and fsgid of the calling process */
 struct fuse_cred {
     uid_t uid;
     gid_t gid;
+    /* FIXME: supplementary groups should also be included */
 };
 
+/**
+ * The file system operations:
+ *
+ * Most of these should work very similarly to the well known UNIX
+ * file system operations.  Exceptions are:
+ * 
+ *  - All operations get a fuse_cred structure by which the filesystem
+ *  implementation can check, whether the operation is permitted or
+ *  not.
+ * 
+ *  - All operations should return the negated error value (-errno) on
+ *  error.
+ * 
+ *  - readlink() should fill the buffer with a null terminated string.
+ *  The buffer size argument includes the space for the terminating
+ *  null character.  If the linkname is too long to fit in the buffer,
+ *  it should be truncated.  The return value should be 0 for success.
+ *
+ *  - getdir() is the opendir(), readdir(), ..., closedir() sequence
+ *  in one call. For each directory entry the filldir parameter should
+ *  be called. 
+ *
+ *  - There is no create() operation, mknod() will be called for
+ *  creation of all non directory, non symlink nodes.
+ *
+ *  - open() should not return a filehandle, but 0 on success.  No
+ *  creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be
+ *  passed to open().  Open should only check if the operation is
+ *  permitted for the given flags.
+ * 
+ *  - read(), write() are not passed a filehandle, but rather a
+ *  pathname.  The offset of the read and write is passed as the last
+ *  argument, like the pread() and pwrite() system calls.  */
 struct fuse_operations {
     int (*getattr)  (struct fuse_cred *, const char *, struct stat *);
     int (*readlink) (struct fuse_cred *, const char *, char *, size_t);
@@ -42,16 +82,64 @@ struct fuse_operations {
     int (*write)    (struct fuse_cred *, const char *, const char *, size_t, off_t);
 };
 
+/* FUSE flags: */
 #define FUSE_MULTITHREAD (1 << 0)
 
-struct fuse *fuse_new(int flags);
+/**
+ * Create a new FUSE filesystem. The filesystem is not yet mounted
+ *
+ * @param flags any combination of the FUSE flags defined above, or 0
+ * @param root the file type of the root node. 0 is the default (directory).
+ * @return the created FUSE handle
+ */
+struct fuse *fuse_new(int flags, mode_t root);
 
-int fuse_mount(struct fuse *f, const char *dir);
+/**
+ * Connect to the kernel and mount the filesystem.
+ * 
+ * @param f the FUSE handle
+ * @param mnt the mount point
+ * @return 0 on success -1 on failure
+ */
+int fuse_mount(struct fuse *f, const char *mnt);
 
+/**
+ * Set the filesystem operations. 
+ * 
+ * Operations which are initialised to NULL will return ENOSYS to the
+ * calling process.  This function can be called anytime after
+ * fuse_new() and before fuse_loop().
+ * 
+ * @param f the FUSE handle
+ * @param op the operations
+ */
 void fuse_set_operations(struct fuse *f, const struct fuse_operations *op);
 
+/**
+ * FUSE event loop.
+ *
+ * Requests from the kernel are processed, and the apropriate
+ * operations are called. 
+ *
+ * @param f the FUSE handle
+ */
 void fuse_loop(struct fuse *f);
 
+/**
+ * Disconnect from the kernel and unmount the filesystem
+ *
+ * @param f the FUSE handle
+ */
 int fuse_unmount(struct fuse *f);
 
+/**
+ * Destroy the filesystem. 
+ *
+ * The filesystem is not unmounted (call fuse_unmount() for that).
+ * After a fork() system call it is possible to call fuse_destroy() in
+ * one process, and leave the other process to service the filesystem
+ * requests.
+ *
+ * @param f the FUSE handle
+ */
 void fuse_destroy(struct fuse *f);