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