1/*
2  FUSE: Filesystem in Userspace
3  Copyright (C) 2001-2007  Miklos Szeredi <miklos@szeredi.hu>
4
5  This program can be distributed under the terms of the GNU LGPLv2.
6  See the file COPYING.LIB.
7*/
8
9#ifndef _FUSE_H_
10#define _FUSE_H_
11
12/** @file
13 *
14 * This file defines the library interface of FUSE
15 */
16
17#include "fuse_common.h"
18
19#include <fcntl.h>
20#include <time.h>
21#include <utime.h>
22#include <sys/types.h>
23#include <sys/stat.h>
24#include <sys/statvfs.h>
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
30/* ----------------------------------------------------------- *
31 * Basic FUSE API					       *
32 * ----------------------------------------------------------- */
33
34/** Handle for a FUSE filesystem */
35struct fuse;
36
37/** Structure containing a raw command */
38struct fuse_cmd;
39
40/** Function to add an entry in a readdir() operation
41 *
42 * @param buf the buffer passed to the readdir() operation
43 * @param name the file name of the directory entry
44 * @param stat file attributes, can be NULL
45 * @param off offset of the next entry or zero
46 * @return 1 if buffer is full, zero otherwise
47 */
48typedef int (*fuse_fill_dir_t) (void *buf, const char *name,
49				const struct stat *stbuf, off_t off);
50
51/**
52 * The file system operations:
53 *
54 * Most of these should work very similarly to the well known UNIX
55 * file system operations.  A major exception is that instead of
56 * returning an error in 'errno', the operation should return the
57 * negated error value (-errno) directly.
58 *
59 * All methods are optional, but some are essential for a useful
60 * filesystem (e.g. getattr).  Open, flush, release, fsync, opendir,
61 * releasedir, fsyncdir, access, create, ftruncate, fgetattr, lock,
62 * init and destroy are special purpose methods, without which a full
63 * featured filesystem can still be implemented.
64 *
65 * Almost all operations take a path which can be of any length.
66 *
67 * Changed in fuse 2.8.0 (regardless of API version)
68 * Previously, paths were limited to a length of PATH_MAX.
69 */
70struct fuse_operations {
71	/** Get file attributes.
72	 *
73	 * Similar to stat().  The 'st_dev' and 'st_blksize' fields are
74	 * ignored.	 The 'st_ino' field is ignored except if the 'use_ino'
75	 * mount option is given.
76	 */
77	int (*getattr) (const char *, struct stat *);
78
79	/** Read the target of a symbolic link
80	 *
81	 * The buffer should be filled with a null terminated string.  The
82	 * buffer size argument includes the space for the terminating
83	 * null character.	If the linkname is too long to fit in the
84	 * buffer, it should be truncated.	The return value should be 0
85	 * for success.
86	 */
87	int (*readlink) (const char *, char *, size_t);
88
89	/** Create a file node
90	 *
91	 * This is called for creation of all non-directory, non-symlink
92	 * nodes.  If the filesystem defines a create() method, then for
93	 * regular files that will be called instead.
94	 */
95	int (*mknod) (const char *, mode_t, dev_t);
96
97	/** Create a directory
98	 *
99	 * Note that the mode argument may not have the type specification
100	 * bits set, i.e. S_ISDIR(mode) can be false.  To obtain the
101	 * correct directory type bits use  mode|S_IFDIR
102	 * */
103	int (*mkdir) (const char *, mode_t);
104
105	/** Remove a file */
106	int (*unlink) (const char *);
107
108	/** Remove a directory */
109	int (*rmdir) (const char *);
110
111	/** Create a symbolic link */
112	int (*symlink) (const char *, const char *);
113
114	/** Rename a file */
115	int (*rename) (const char *, const char *);
116
117	/** Create a hard link to a file */
118	int (*link) (const char *, const char *);
119
120	/** Change the permission bits of a file */
121	int (*chmod) (const char *, mode_t);
122
123	/** Change the owner and group of a file */
124	int (*chown) (const char *, uid_t, gid_t);
125
126	/** Change the size of a file */
127	int (*truncate) (const char *, off_t);
128
129	/** Change the access and/or modification times of a file
130	 *
131	 * Deprecated, use utimens() instead.
132	 */
133	int (*utime) (const char *, struct utimbuf *);
134
135	/** File open operation
136	 *
137	 * No creation (O_CREAT, O_EXCL) and by default also no
138	 * truncation (O_TRUNC) flags will be passed to open(). If an
139	 * application specifies O_TRUNC, fuse first calls truncate()
140	 * and then open(). Only if 'atomic_o_trunc' has been
141	 * specified and kernel version is 2.6.24 or later, O_TRUNC is
142	 * passed on to open.
143	 *
144	 * Unless the 'default_permissions' mount option is given,
145	 * open should check if the operation is permitted for the
146	 * given flags. Optionally open may also return an arbitrary
147	 * filehandle in the fuse_file_info structure, which will be
148	 * passed to all file operations.
149	 *
150	 * Changed in version 2.2
151	 */
152	int (*open) (const char *, struct fuse_file_info *);
153
154	/** Read data from an open file
155	 *
156	 * Read should return exactly the number of bytes requested except
157	 * on EOF or error, otherwise the rest of the data will be
158	 * substituted with zeroes.	 An exception to this is when the
159	 * 'direct_io' mount option is specified, in which case the return
160	 * value of the read system call will reflect the return value of
161	 * this operation.
162	 *
163	 * Changed in version 2.2
164	 */
165	int (*read) (const char *, char *, size_t, off_t,
166		     struct fuse_file_info *);
167
168	/** Write data to an open file
169	 *
170	 * Write should return exactly the number of bytes requested
171	 * except on error.	 An exception to this is when the 'direct_io'
172	 * mount option is specified (see read operation).
173	 *
174	 * Changed in version 2.2
175	 */
176	int (*write) (const char *, const char *, size_t, off_t,
177		      struct fuse_file_info *);
178
179	/** Get file system statistics
180	 *
181	 * The 'f_frsize', 'f_favail', 'f_fsid' and 'f_flag' fields are ignored
182	 *
183	 * Replaced 'struct statfs' parameter with 'struct statvfs' in
184	 * version 2.5
185	 */
186	int (*statfs) (const char *, struct statvfs *);
187
188	/** Possibly flush cached data
189	 *
190	 * BIG NOTE: This is not equivalent to fsync().  It's not a
191	 * request to sync dirty data.
192	 *
193	 * Flush is called on each close() of a file descriptor.  So if a
194	 * filesystem wants to return write errors in close() and the file
195	 * has cached dirty data, this is a good place to write back data
196	 * and return any errors.  Since many applications ignore close()
197	 * errors this is not always useful.
198	 *
199	 * NOTE: The flush() method may be called more than once for each
200	 * open().	This happens if more than one file descriptor refers
201	 * to an opened file due to dup(), dup2() or fork() calls.	It is
202	 * not possible to determine if a flush is final, so each flush
203	 * should be treated equally.  Multiple write-flush sequences are
204	 * relatively rare, so this shouldn't be a problem.
205	 *
206	 * Filesystems shouldn't assume that flush will always be called
207	 * after some writes, or that if will be called at all.
208	 *
209	 * Changed in version 2.2
210	 */
211	int (*flush) (const char *, struct fuse_file_info *);
212
213	/** Release an open file
214	 *
215	 * Release is called when there are no more references to an open
216	 * file: all file descriptors are closed and all memory mappings
217	 * are unmapped.
218	 *
219	 * For every open() call there will be exactly one release() call
220	 * with the same flags and file descriptor.	 It is possible to
221	 * have a file opened more than once, in which case only the last
222	 * release will mean, that no more reads/writes will happen on the
223	 * file.  The return value of release is ignored.
224	 *
225	 * Changed in version 2.2
226	 */
227	int (*release) (const char *, struct fuse_file_info *);
228
229	/** Synchronize file contents
230	 *
231	 * If the datasync parameter is non-zero, then only the user data
232	 * should be flushed, not the meta data.
233	 *
234	 * Changed in version 2.2
235	 */
236	int (*fsync) (const char *, int, struct fuse_file_info *);
237
238	/** Set extended attributes */
239	int (*setxattr) (const char *, const char *, const char *, size_t, int);
240
241	/** Get extended attributes */
242	int (*getxattr) (const char *, const char *, char *, size_t);
243
244	/** List extended attributes */
245	int (*listxattr) (const char *, char *, size_t);
246
247	/** Remove extended attributes */
248	int (*removexattr) (const char *, const char *);
249
250	/** Open directory
251	 *
252	 * This method should check if the open operation is permitted for
253	 * this  directory
254	 *
255	 * Introduced in version 2.3
256	 */
257	int (*opendir) (const char *, struct fuse_file_info *);
258
259	/** Read directory
260	 *
261	 * The filesystem may choose between two modes of operation:
262	 *
263	 * 1) The readdir implementation ignores the offset parameter, and
264	 * passes zero to the filler function's offset.  The filler
265	 * function will not return '1' (unless an error happens), so the
266	 * whole directory is read in a single readdir operation.
267	 *
268	 * 2) The readdir implementation keeps track of the offsets of the
269	 * directory entries.  It uses the offset parameter and always
270	 * passes non-zero offset to the filler function.  When the buffer
271	 * is full (or an error happens) the filler function will return
272	 * '1'.
273	 *
274	 * Introduced in version 2.3
275	 */
276	int (*readdir) (const char *, void *, fuse_fill_dir_t, off_t,
277			struct fuse_file_info *);
278
279	/** Release directory
280	 *
281	 * Introduced in version 2.3
282	 */
283	int (*releasedir) (const char *, struct fuse_file_info *);
284
285	/** Synchronize directory contents
286	 *
287	 * If the datasync parameter is non-zero, then only the user data
288	 * should be flushed, not the meta data
289	 *
290	 * Introduced in version 2.3
291	 */
292	int (*fsyncdir) (const char *, int, struct fuse_file_info *);
293
294	/**
295	 * Initialize filesystem
296	 *
297	 * The return value will passed in the private_data field of
298	 * fuse_context to all file operations and as a parameter to the
299	 * destroy() method.
300	 *
301	 * Introduced in version 2.3
302	 * Changed in version 2.6
303	 */
304	void *(*init) (struct fuse_conn_info *conn);
305
306	/**
307	 * Clean up filesystem
308	 *
309	 * Called on filesystem exit.
310	 *
311	 * Introduced in version 2.3
312	 */
313	void (*destroy) (void *);
314
315	/**
316	 * Check file access permissions
317	 *
318	 * This will be called for the access() system call.  If the
319	 * 'default_permissions' mount option is given, this method is not
320	 * called.
321	 *
322	 * This method is not called under Linux kernel versions 2.4.x
323	 *
324	 * Introduced in version 2.5
325	 */
326	int (*access) (const char *, int);
327
328	/**
329	 * Create and open a file
330	 *
331	 * If the file does not exist, first create it with the specified
332	 * mode, and then open it.
333	 *
334	 * If this method is not implemented or under Linux kernel
335	 * versions earlier than 2.6.15, the mknod() and open() methods
336	 * will be called instead.
337	 *
338	 * Introduced in version 2.5
339	 */
340	int (*create) (const char *, mode_t, struct fuse_file_info *);
341
342	/**
343	 * Change the size of an open file
344	 *
345	 * This method is called instead of the truncate() method if the
346	 * truncation was invoked from an ftruncate() system call.
347	 *
348	 * If this method is not implemented or under Linux kernel
349	 * versions earlier than 2.6.15, the truncate() method will be
350	 * called instead.
351	 *
352	 * Introduced in version 2.5
353	 */
354	int (*ftruncate) (const char *, off_t, struct fuse_file_info *);
355
356	/**
357	 * Get attributes from an open file
358	 *
359	 * This method is called instead of the getattr() method if the
360	 * file information is available.
361	 *
362	 * Currently this is only called after the create() method if that
363	 * is implemented (see above).  Later it may be called for
364	 * invocations of fstat() too.
365	 *
366	 * Introduced in version 2.5
367	 */
368	int (*fgetattr) (const char *, struct stat *, struct fuse_file_info *);
369
370	/**
371	 * Perform POSIX file locking operation
372	 *
373	 * The cmd argument will be either F_GETLK, F_SETLK or F_SETLKW.
374	 *
375	 * For the meaning of fields in 'struct flock' see the man page
376	 * for fcntl(2).  The l_whence field will always be set to
377	 * SEEK_SET.
378	 *
379	 * For checking lock ownership, the 'fuse_file_info->owner'
380	 * argument must be used.
381	 *
382	 * For F_GETLK operation, the library will first check currently
383	 * held locks, and if a conflicting lock is found it will return
384	 * information without calling this method.	 This ensures, that
385	 * for local locks the l_pid field is correctly filled in.	The
386	 * results may not be accurate in case of race conditions and in
387	 * the presence of hard links, but it's unlikly that an
388	 * application would rely on accurate GETLK results in these
389	 * cases.  If a conflicting lock is not found, this method will be
390	 * called, and the filesystem may fill out l_pid by a meaningful
391	 * value, or it may leave this field zero.
392	 *
393	 * For F_SETLK and F_SETLKW the l_pid field will be set to the pid
394	 * of the process performing the locking operation.
395	 *
396	 * Note: if this method is not implemented, the kernel will still
397	 * allow file locking to work locally.  Hence it is only
398	 * interesting for network filesystems and similar.
399	 *
400	 * Introduced in version 2.6
401	 */
402	int (*lock) (const char *, struct fuse_file_info *, int cmd,
403		     struct flock *);
404
405	/**
406	 * Change the access and modification times of a file with
407	 * nanosecond resolution
408	 *
409	 * Introduced in version 2.6
410	 */
411	int (*utimens) (const char *, const struct timespec tv[2]);
412
413	/**
414	 * Map block index within file to block index within device
415	 *
416	 * Note: This makes sense only for block device backed filesystems
417	 * mounted with the 'blkdev' option
418	 *
419	 * Introduced in version 2.6
420	 */
421	int (*bmap) (const char *, size_t blocksize, uint64_t *idx);
422};
423
424/** Extra context that may be needed by some filesystems
425 *
426 * The uid, gid and pid fields are not filled in case of a writepage
427 * operation.
428 */
429struct fuse_context {
430	/** Pointer to the fuse object */
431	struct fuse *fuse;
432
433	/** User ID of the calling process */
434	uid_t uid;
435
436	/** Group ID of the calling process */
437	gid_t gid;
438
439	/** Thread ID of the calling process */
440	pid_t pid;
441
442	/** Private filesystem data */
443	void *private_data;
444};
445
446/* ----------------------------------------------------------- *
447 * More detailed API					       *
448 * ----------------------------------------------------------- */
449
450/**
451 * Create a new FUSE filesystem.
452 *
453 * @param ch the communication channel
454 * @param args argument vector
455 * @param op the filesystem operations
456 * @param op_size the size of the fuse_operations structure
457 * @param user_data user data supplied in the context during the init() method
458 * @return the created FUSE handle
459 */
460struct fuse *fuse_new(struct fuse_chan *ch, struct fuse_args *args,
461		      const struct fuse_operations *op, size_t op_size,
462		      void *user_data);
463
464/**
465 * Destroy the FUSE handle.
466 *
467 * The communication channel attached to the handle is also destroyed.
468 *
469 * NOTE: This function does not unmount the filesystem.	 If this is
470 * needed, call fuse_unmount() before calling this function.
471 *
472 * @param f the FUSE handle
473 */
474void fuse_destroy(struct fuse *f);
475
476/**
477 * FUSE event loop.
478 *
479 * Requests from the kernel are processed, and the appropriate
480 * operations are called.
481 *
482 * @param f the FUSE handle
483 * @return 0 if no error occurred, -1 otherwise
484 */
485int fuse_loop(struct fuse *f);
486
487/**
488 * Exit from event loop
489 *
490 * @param f the FUSE handle
491 */
492void fuse_exit(struct fuse *f);
493
494/**
495 * Get the current context
496 *
497 * The context is only valid for the duration of a filesystem
498 * operation, and thus must not be stored and used later.
499 *
500 * @return the context
501 */
502struct fuse_context *fuse_get_context(void);
503
504/**
505 * Check if a request has already been interrupted
506 *
507 * @param req request handle
508 * @return 1 if the request has been interrupted, 0 otherwise
509 */
510int fuse_interrupted(void);
511
512/*
513 * Stacking API
514 */
515
516/**
517 * Fuse filesystem object
518 *
519 * This is opaque object represents a filesystem layer
520 */
521struct fuse_fs;
522
523/*
524 * These functions call the relevant filesystem operation, and return
525 * the result.
526 *
527 * If the operation is not defined, they return -ENOSYS, with the
528 * exception of fuse_fs_open, fuse_fs_release, fuse_fs_opendir,
529 * fuse_fs_releasedir and fuse_fs_statfs, which return 0.
530 */
531
532int fuse_fs_getattr(struct fuse_fs *fs, const char *path, struct stat *buf);
533int fuse_fs_fgetattr(struct fuse_fs *fs, const char *path, struct stat *buf,
534		     struct fuse_file_info *fi);
535int fuse_fs_rename(struct fuse_fs *fs, const char *oldpath,
536		   const char *newpath);
537int fuse_fs_unlink(struct fuse_fs *fs, const char *path);
538int fuse_fs_rmdir(struct fuse_fs *fs, const char *path);
539int fuse_fs_symlink(struct fuse_fs *fs, const char *linkname,
540		    const char *path);
541int fuse_fs_link(struct fuse_fs *fs, const char *oldpath, const char *newpath);
542int fuse_fs_release(struct fuse_fs *fs,	 const char *path,
543		    struct fuse_file_info *fi);
544int fuse_fs_open(struct fuse_fs *fs, const char *path,
545		 struct fuse_file_info *fi);
546int fuse_fs_read(struct fuse_fs *fs, const char *path, char *buf, size_t size,
547		 off_t off, struct fuse_file_info *fi);
548int fuse_fs_write(struct fuse_fs *fs, const char *path, const char *buf,
549		  size_t size, off_t off, struct fuse_file_info *fi);
550int fuse_fs_fsync(struct fuse_fs *fs, const char *path, int datasync,
551		  struct fuse_file_info *fi);
552int fuse_fs_flush(struct fuse_fs *fs, const char *path,
553		  struct fuse_file_info *fi);
554int fuse_fs_statfs(struct fuse_fs *fs, const char *path, struct statvfs *buf);
555int fuse_fs_opendir(struct fuse_fs *fs, const char *path,
556		    struct fuse_file_info *fi);
557int fuse_fs_readdir(struct fuse_fs *fs, const char *path, void *buf,
558		    fuse_fill_dir_t filler, off_t off,
559		    struct fuse_file_info *fi);
560int fuse_fs_fsyncdir(struct fuse_fs *fs, const char *path, int datasync,
561		     struct fuse_file_info *fi);
562int fuse_fs_releasedir(struct fuse_fs *fs, const char *path,
563		       struct fuse_file_info *fi);
564int fuse_fs_create(struct fuse_fs *fs, const char *path, mode_t mode,
565		   struct fuse_file_info *fi);
566int fuse_fs_lock(struct fuse_fs *fs, const char *path,
567		 struct fuse_file_info *fi, int cmd, struct flock *lock);
568int fuse_fs_chmod(struct fuse_fs *fs, const char *path, mode_t mode);
569int fuse_fs_chown(struct fuse_fs *fs, const char *path, uid_t uid, gid_t gid);
570int fuse_fs_truncate(struct fuse_fs *fs, const char *path, off_t size);
571int fuse_fs_ftruncate(struct fuse_fs *fs, const char *path, off_t size,
572		      struct fuse_file_info *fi);
573int fuse_fs_utimens(struct fuse_fs *fs, const char *path,
574		    const struct timespec tv[2]);
575int fuse_fs_access(struct fuse_fs *fs, const char *path, int mask);
576int fuse_fs_readlink(struct fuse_fs *fs, const char *path, char *buf,
577		     size_t len);
578int fuse_fs_mknod(struct fuse_fs *fs, const char *path, mode_t mode,
579		  dev_t rdev);
580int fuse_fs_mkdir(struct fuse_fs *fs, const char *path, mode_t mode);
581int fuse_fs_setxattr(struct fuse_fs *fs, const char *path, const char *name,
582		     const char *value, size_t size, int flags);
583int fuse_fs_getxattr(struct fuse_fs *fs, const char *path, const char *name,
584		     char *value, size_t size);
585int fuse_fs_listxattr(struct fuse_fs *fs, const char *path, char *list,
586		      size_t size);
587int fuse_fs_removexattr(struct fuse_fs *fs, const char *path,
588			const char *name);
589int fuse_fs_bmap(struct fuse_fs *fs, const char *path, size_t blocksize,
590		 uint64_t *idx);
591void fuse_fs_init(struct fuse_fs *fs, struct fuse_conn_info *conn);
592void fuse_fs_destroy(struct fuse_fs *fs);
593
594/**
595 * Create a new fuse filesystem object
596 *
597 * This is usually called from the factory of a fuse module to create
598 * a new instance of a filesystem.
599 *
600 * @param op the filesystem operations
601 * @param op_size the size of the fuse_operations structure
602 * @param user_data user data supplied in the context during the init() method
603 * @return a new filesystem object
604 */
605struct fuse_fs *fuse_fs_new(const struct fuse_operations *op, size_t op_size,
606			    void *user_data);
607
608/* ----------------------------------------------------------- *
609 * Advanced API for event handling, don't worry about this...  *
610 * ----------------------------------------------------------- */
611
612/* NOTE: the following functions are deprecated, and will be removed
613   from the 3.0 API.  Use the lowlevel session functions instead */
614
615/** Get session from fuse object */
616struct fuse_session *fuse_get_session(struct fuse *f);
617
618#ifdef __cplusplus
619}
620#endif
621
622#endif /* _FUSE_H_ */
623