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