trunk/include/fuse.h

/*
    FUSE: Filesystem in Userspace
    Copyright (C) 2001-2004  Miklos Szeredi <miklos@szeredi.hu>

    This program can be distributed under the terms of the GNU LGPL.
    See the file COPYING.LIB.
*/

#ifndef _FUSE_H_
#define _FUSE_H_

/* This file defines the library interface of FUSE */

/** Major version of FUSE library interface */
#define FUSE_MAJOR_VERSION 2

/** Minor version of FUSE library interface */
#define FUSE_MINOR_VERSION 0

/* This interface uses 64 bit off_t */
#if _FILE_OFFSET_BITS != 64
#error Please add -D_FILE_OFFSET_BITS=64 to your compile flags!
#endif

#include <sys/types.h>
#include <sys/stat.h>
#include <sys/statfs.h>
#include <utime.h>

/* ----------------------------------------------------------- *
 * Basic FUSE API                                              *
 * ----------------------------------------------------------- */

/** 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
 * 
 * @param h the handle passed to the getdir() operation
 * @param name the file name of the directory entry
 * @param type the file type (0 if unknown)  see <dirent.h>
 * @return 0 on success, -errno on error
 */
typedef int (*fuse_dirfil_t) (fuse_dirh_t h, const char *name, int type);

/**
 * The file system operations:
 *
 * Most of these should work very similarly to the well known UNIX
 * file system operations.  Exceptions are:
 * 
 *  - All operations should return the negated error value (-errno) on
 *  error.
 * 
 *  - Getattr() doesn't need to fill in the following fields:
 *      st_ino
 *      st_dev
 *      st_blksize
 * 
 *  - 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.  (NOTE:
 *  read() should always return the number of bytes requested, except
 *  at end of file)
 * 
 *  - release() is called when an open file has:
 *       1) all file descriptors closed
 *       2) all memory mappings unmapped
 *  For every open() call there will be exactly one release() call
 *  with the same flags.  It is possible to have a file opened more
 *  than once, in which case only the last release will mean, that no
 *  more reads/writes will happen on the file.  The return value of
 *  release is ignored.  Implementing this method is optional.
 * 
 *  - flush() is called when close() has been called on an open file.
 *  NOTE: this does not mean that the file is released (e.g. after
 *  fork() an open file will have two references which both must be
 *  closed before the file is released).  The flush() method may be
 *  called more than once for each open().  The return value of
 *  flush() is passed on to the close() system call.  Implementing
 *  this method is optional.
 * 
 *  - fsync() has a boolean 'datasync' parameter which if TRUE then do
 *  an fdatasync() operation.  Implementing this method is optional.
 */
struct fuse_operations {
    int (*getattr)     (const char *, struct stat *);
    int (*readlink)    (const char *, char *, size_t);
    int (*getdir)      (const char *, fuse_dirh_t, fuse_dirfil_t);
    int (*mknod)       (const char *, mode_t, dev_t);
    int (*mkdir)       (const char *, mode_t);
    int (*unlink)      (const char *);
    int (*rmdir)       (const char *);
    int (*symlink)     (const char *, const char *);
    int (*rename)      (const char *, const char *);
    int (*link)        (const char *, const char *);
    int (*chmod)       (const char *, mode_t);
    int (*chown)       (const char *, uid_t, gid_t);
    int (*truncate)    (const char *, off_t);
    int (*utime)       (const char *, struct utimbuf *);
    int (*open)        (const char *, int);
    int (*read)        (const char *, char *, size_t, off_t);
    int (*write)       (const char *, const char *, size_t, off_t);
    int (*statfs)      (const char *, struct statfs *);
    int (*flush)       (const char *);
    int (*release)     (const char *, int);
    int (*fsync)       (const char *, int);
    int (*setxattr)    (const char *, const char *, const char *, size_t, int);
    int (*getxattr)    (const char *, const char *, char *, size_t);
    int (*listxattr)   (const char *, char *, size_t);
    int (*removexattr) (const char *, const char *);
};

/** Extra context that may be needed by some filesystems */
struct fuse_context {
    uid_t uid;
    gid_t gid;
};

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Main function of FUSE.
 *
 * This is for the lazy.  This is all that has to be called from the
 * main() function.
 * 
 * This function does the following:
 *   - parses command line options (-d -s and -h)
 *   - passes relevant mount options to the fuse_mount()
 *   - installs signal handlers for INT, HUP, TERM and PIPE
 *   - registers an exit handler to unmount the filesystem on program exit
 *   - creates a fuse handle
 *   - registers the operations
 *   - calls either the single-threaded or the multi-threaded event loop
 *
 * @param argc the argument counter passed to the main() function
 * @param argv the argument vector passed to the main() function
 * @param op the file system operation 
 */
void fuse_main(int argc, char *argv[], const struct fuse_operations *op);

/*
 * Returns the fuse object created by fuse_main()
 * 
 * This is useful when fuse_get_context() is used.
 *
 * @return the fuse object
 */
struct fuse *fuse_get(void);

/**
 * Invalidate cached data of a file.
 *
 * Useful if the 'kernel_cache' mount option is given, since in that
 * case the cache is not invalidated on file open.
 *
 * @return 0 on success or -errno on failure
 */
int fuse_invalidate(struct fuse *f, const char *path);

/* ----------------------------------------------------------- *
 * More detailed API                                           *
 * ----------------------------------------------------------- */

/*
 * Create a FUSE mountpoint
 *
 * Returns a control file descriptor suitable for passing to
 * fuse_new()
 *
 * @param mountpoint the mount point path
 * @param opts a comma separated list of mount options.  Can be NULL.
 * @return the control file descriptor on success, -1 on failure
 */
int fuse_mount(const char *mountpoint, const char *opts);

/*
 * Umount a FUSE mountpoint
 *
 * @param mountpoint the mount point path
 */
void fuse_unmount(const char *mountpoint);

/**
 * Create a new FUSE filesystem.
 *
 * @param fd the control file descriptor
 * @param opts mount options to be used by the library
 * @param op the operations
 * @return the created FUSE handle
 */
struct fuse *fuse_new(int fd, const char *opts, 
                      const struct fuse_operations *op);

/**
 * Destroy the FUSE handle. 
 *
 * The filesystem is not unmounted.
 *
 * @param f the FUSE handle
 */
void fuse_destroy(struct fuse *f);

/**
 * 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);

/**
 * Exit from event loop
 *
 * @param f the FUSE handle
 */
void fuse_exit(struct fuse *f);

/**
 * FUSE event loop with multiple threads
 *
 * Requests from the kernel are processed, and the apropriate
 * operations are called.  Request are processed in parallel by
 * distributing them between multiple threads.
 *
 * Calling this function requires the pthreads library to be linked to
 * the application.
 *
 * @param f the FUSE handle
 */
void fuse_loop_mt(struct fuse *f);

/**
 * Get the current context
 * 
 * The context is only valid for the duration of a filesystem
 * operation, and thus must not be stored and used later.
 *
 * @param f the FUSE handle
 * @return the context 
 */
struct fuse_context *fuse_get_context(struct fuse *f);

/**
 * Check whether a mount option should be passed to the kernel or the
 * library
 *
 * @param opt the option to check
 * @return 1 if it is a library option, 0 otherwise
 */
int fuse_is_lib_option(const char *opt);


/* ----------------------------------------------------------- *
 * Advanced API for event handling, don't worry about this...  *
 * ----------------------------------------------------------- */

struct fuse_cmd;
typedef void (*fuse_processor_t)(struct fuse *, struct fuse_cmd *, void *);
struct fuse_cmd *__fuse_read_cmd(struct fuse *f);
void __fuse_process_cmd(struct fuse *f, struct fuse_cmd *cmd);
void __fuse_loop_mt(struct fuse *f, fuse_processor_t proc, void *data);
int __fuse_exited(struct fuse* f);

#ifdef __cplusplus
}
#endif

#endif /* _FUSE_H_ */
1	dpavlin	4	/*
2			FUSE: Filesystem in Userspace
3			Copyright (C) 2001-2004 Miklos Szeredi <miklos@szeredi.hu>
4
5			This program can be distributed under the terms of the GNU LGPL.
6			See the file COPYING.LIB.
7			*/
8
9			#ifndef _FUSE_H_
10			#define _FUSE_H_
11
12			/* This file defines the library interface of FUSE */
13
14			/** Major version of FUSE library interface */
15			#define FUSE_MAJOR_VERSION 2
16
17			/** Minor version of FUSE library interface */
18			#define FUSE_MINOR_VERSION 0
19
20			/* This interface uses 64 bit off_t */
21			#if _FILE_OFFSET_BITS != 64
22			#error Please add -D_FILE_OFFSET_BITS=64 to your compile flags!
23			#endif
24
25			#include <sys/types.h>
26			#include <sys/stat.h>
27			#include <sys/statfs.h>
28			#include <utime.h>
29
30			/* ----------------------------------------------------------- *
31			* Basic FUSE API *
32			* ----------------------------------------------------------- */
33
34			/** Handle for a FUSE filesystem */
35			struct fuse;
36
37			/** Handle for a getdir() operation */
38			typedef struct fuse_dirhandle *fuse_dirh_t;
39
40			/** Function to add an entry in a getdir() operation
41			*
42			* @param h the handle passed to the getdir() operation
43			* @param name the file name of the directory entry
44			* @param type the file type (0 if unknown) see <dirent.h>
45			* @return 0 on success, -errno on error
46			*/
47			typedef int (fuse_dirfil_t) (fuse_dirh_t h, const char name, int type);
48
49			/**
50			* The file system operations:
51			*
52			* Most of these should work very similarly to the well known UNIX
53			* file system operations. Exceptions are:
54			*
55			* - All operations should return the negated error value (-errno) on
56			* error.
57			*
58			* - Getattr() doesn't need to fill in the following fields:
59			* st_ino
60			* st_dev
61			* st_blksize
62			*
63			* - readlink() should fill the buffer with a null terminated string. The
64			* buffer size argument includes the space for the terminating null
65			* character. If the linkname is too long to fit in the buffer, it should
66			* be truncated. The return value should be 0 for success.
67			*
68			* - getdir() is the opendir(), readdir(), ..., closedir() sequence
69			* in one call. For each directory entry the filldir parameter should
70			* be called.
71			*
72			* - There is no create() operation, mknod() will be called for
73			* creation of all non directory, non symlink nodes.
74			*
75			* - open() should not return a filehandle, but 0 on success. No
76			* creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be
77			* passed to open(). Open should only check if the operation is
78			* permitted for the given flags.
79			*
80			* - read(), write() are not passed a filehandle, but rather a
81			* pathname. The offset of the read and write is passed as the last
82			* argument, like the pread() and pwrite() system calls. (NOTE:
83			* read() should always return the number of bytes requested, except
84			* at end of file)
85			*
86			* - release() is called when an open file has:
87			* 1) all file descriptors closed
88			* 2) all memory mappings unmapped
89			* For every open() call there will be exactly one release() call
90			* with the same flags. It is possible to have a file opened more
91			* than once, in which case only the last release will mean, that no
92			* more reads/writes will happen on the file. The return value of
93			* release is ignored. Implementing this method is optional.
94			*
95			* - flush() is called when close() has been called on an open file.
96			* NOTE: this does not mean that the file is released (e.g. after
97			* fork() an open file will have two references which both must be
98			* closed before the file is released). The flush() method may be
99			* called more than once for each open(). The return value of
100			* flush() is passed on to the close() system call. Implementing
101			* this method is optional.
102			*
103			* - fsync() has a boolean 'datasync' parameter which if TRUE then do
104			* an fdatasync() operation. Implementing this method is optional.
105			*/
106			struct fuse_operations {
107			int (getattr) (const char , struct stat *);
108			int (readlink) (const char , char *, size_t);
109			int (getdir) (const char , fuse_dirh_t, fuse_dirfil_t);
110			int (mknod) (const char , mode_t, dev_t);
111			int (mkdir) (const char , mode_t);
112			int (unlink) (const char );
113			int (rmdir) (const char );
114			int (symlink) (const char , const char *);
115			int (rename) (const char , const char *);
116			int (link) (const char , const char *);
117			int (chmod) (const char , mode_t);
118			int (chown) (const char , uid_t, gid_t);
119			int (truncate) (const char , off_t);
120			int (utime) (const char , struct utimbuf *);
121			int (open) (const char , int);
122			int (read) (const char , char *, size_t, off_t);
123			int (write) (const char , const char *, size_t, off_t);
124			int (statfs) (const char , struct statfs *);
125			int (flush) (const char );
126			int (release) (const char , int);
127			int (fsync) (const char , int);
128			int (setxattr) (const char , const char , const char , size_t, int);
129			int (getxattr) (const char , const char , char , size_t);
130			int (listxattr) (const char , char *, size_t);
131			int (removexattr) (const char , const char *);
132			};
133
134			/** Extra context that may be needed by some filesystems */
135			struct fuse_context {
136			uid_t uid;
137			gid_t gid;
138			};
139
140			#ifdef __cplusplus
141			extern "C" {
142			#endif
143
144			/*
145			* Main function of FUSE.
146			*
147			* This is for the lazy. This is all that has to be called from the
148			* main() function.
149			*
150			* This function does the following:
151			* - parses command line options (-d -s and -h)
152			* - passes relevant mount options to the fuse_mount()
153			* - installs signal handlers for INT, HUP, TERM and PIPE
154			* - registers an exit handler to unmount the filesystem on program exit
155			* - creates a fuse handle
156			* - registers the operations
157			* - calls either the single-threaded or the multi-threaded event loop
158			*
159			* @param argc the argument counter passed to the main() function
160			* @param argv the argument vector passed to the main() function
161			* @param op the file system operation
162			*/
163			void fuse_main(int argc, char argv[], const struct fuse_operations op);
164
165			/*
166			* Returns the fuse object created by fuse_main()
167			*
168			* This is useful when fuse_get_context() is used.
169			*
170			* @return the fuse object
171			*/
172			struct fuse *fuse_get(void);
173
174			/**
175			* Invalidate cached data of a file.
176			*
177			* Useful if the 'kernel_cache' mount option is given, since in that
178			* case the cache is not invalidated on file open.
179			*
180			* @return 0 on success or -errno on failure
181			*/
182			int fuse_invalidate(struct fuse f, const char path);
183
184			/* ----------------------------------------------------------- *
185			* More detailed API *
186			* ----------------------------------------------------------- */
187
188			/*
189			* Create a FUSE mountpoint
190			*
191			* Returns a control file descriptor suitable for passing to
192			* fuse_new()
193			*
194			* @param mountpoint the mount point path
195			* @param opts a comma separated list of mount options. Can be NULL.
196			* @return the control file descriptor on success, -1 on failure
197			*/
198			int fuse_mount(const char mountpoint, const char opts);
199
200			/*
201			* Umount a FUSE mountpoint
202			*
203			* @param mountpoint the mount point path
204			*/
205			void fuse_unmount(const char *mountpoint);
206
207			/**
208			* Create a new FUSE filesystem.
209			*
210			* @param fd the control file descriptor
211			* @param opts mount options to be used by the library
212			* @param op the operations
213			* @return the created FUSE handle
214			*/
215			struct fuse fuse_new(int fd, const char opts,
216			const struct fuse_operations *op);
217
218			/**
219			* Destroy the FUSE handle.
220			*
221			* The filesystem is not unmounted.
222			*
223			* @param f the FUSE handle
224			*/
225			void fuse_destroy(struct fuse *f);
226
227			/**
228			* FUSE event loop.
229			*
230			* Requests from the kernel are processed, and the apropriate
231			* operations are called.
232			*
233			* @param f the FUSE handle
234			*/
235			void fuse_loop(struct fuse *f);
236
237			/**
238			* Exit from event loop
239			*
240			* @param f the FUSE handle
241			*/
242			void fuse_exit(struct fuse *f);
243
244			/**
245			* FUSE event loop with multiple threads
246			*
247			* Requests from the kernel are processed, and the apropriate
248			* operations are called. Request are processed in parallel by
249			* distributing them between multiple threads.
250			*
251			* Calling this function requires the pthreads library to be linked to
252			* the application.
253			*
254			* @param f the FUSE handle
255			*/
256			void fuse_loop_mt(struct fuse *f);
257
258			/**
259			* Get the current context
260			*
261			* The context is only valid for the duration of a filesystem
262			* operation, and thus must not be stored and used later.
263			*
264			* @param f the FUSE handle
265			* @return the context
266			*/
267			struct fuse_context fuse_get_context(struct fuse f);
268
269			/**
270			* Check whether a mount option should be passed to the kernel or the
271			* library
272			*
273			* @param opt the option to check
274			* @return 1 if it is a library option, 0 otherwise
275			*/
276			int fuse_is_lib_option(const char *opt);
277
278
279			/* ----------------------------------------------------------- *
280			* Advanced API for event handling, don't worry about this... *
281			* ----------------------------------------------------------- */
282
283			struct fuse_cmd;
284			typedef void (fuse_processor_t)(struct fuse , struct fuse_cmd , void );
285			struct fuse_cmd __fuse_read_cmd(struct fuse f);
286			void __fuse_process_cmd(struct fuse f, struct fuse_cmd cmd);
287			void __fuse_loop_mt(struct fuse f, fuse_processor_t proc, void data);
288			int __fuse_exited(struct fuse* f);
289
290			#ifdef __cplusplus
291			}
292			#endif
293
294			#endif /* _FUSE_H_ */