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/** @file */
10
11#if !defined(_FUSE_H_) && !defined(_FUSE_LOWLEVEL_H_)
12#error "Never include <fuse_common.h> directly; use <fuse.h> or <fuse_lowlevel.h> instead."
13#endif
14
15#ifndef _FUSE_COMMON_H_
16#define _FUSE_COMMON_H_
17
18#include "fuse_opt.h"
19#include <stdint.h>
20#include <sys/types.h>
21
22/** Major version of FUSE library interface */
23#define FUSE_MAJOR_VERSION 2
24
25/** Minor version of FUSE library interface */
26#define FUSE_MINOR_VERSION 9
27
28#define FUSE_MAKE_VERSION(maj, min)  ((maj) * 10 + (min))
29#define FUSE_VERSION FUSE_MAKE_VERSION(FUSE_MAJOR_VERSION, FUSE_MINOR_VERSION)
30
31/* This interface uses 64 bit off_t */
32#if _FILE_OFFSET_BITS != 64
33#error Please add -D_FILE_OFFSET_BITS=64 to your compile flags!
34#endif
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/**
41 * Information about open files
42 *
43 * Changed in version 2.5
44 */
45struct fuse_file_info {
46	/** Open flags.	 Available in open() and release() */
47	int flags;
48
49	/** Old file handle, don't use */
50	unsigned long fh_old;
51
52	/** In case of a write operation indicates if this was caused by a
53	    writepage */
54	int writepage;
55
56	/** Can be filled in by open, to use direct I/O on this file.
57	    Introduced in version 2.4 */
58	unsigned int direct_io : 1;
59
60	/** Can be filled in by open, to indicate, that cached file data
61	    need not be invalidated.  Introduced in version 2.4 */
62	unsigned int keep_cache : 1;
63
64	/** Indicates a flush operation.  Set in flush operation, also
65	    maybe set in highlevel lock operation and lowlevel release
66	    operation.	Introduced in version 2.6 */
67	unsigned int flush : 1;
68
69	/** Can be filled in by open, to indicate that the file is not
70	    seekable.  Introduced in version 2.8 */
71	unsigned int nonseekable : 1;
72
73	/* Indicates that flock locks for this file should be
74	   released.  If set, lock_owner shall contain a valid value.
75	   May only be set in ->release().  Introduced in version
76	   2.9 */
77	unsigned int flock_release : 1;
78
79	/** Padding.  Do not use*/
80	unsigned int padding : 27;
81
82	/** File handle.  May be filled in by filesystem in open().
83	    Available in all other file operations */
84	uint64_t fh;
85
86	/** Lock owner id.  Available in locking operations and flush */
87	uint64_t lock_owner;
88};
89
90/**
91 * Capability bits for 'fuse_conn_info.capable' and 'fuse_conn_info.want'
92 *
93 * FUSE_CAP_ASYNC_READ: filesystem supports asynchronous read requests
94 * FUSE_CAP_POSIX_LOCKS: filesystem supports "remote" locking
95 * FUSE_CAP_ATOMIC_O_TRUNC: filesystem handles the O_TRUNC open flag
96 * FUSE_CAP_EXPORT_SUPPORT: filesystem handles lookups of "." and ".."
97 * FUSE_CAP_BIG_WRITES: filesystem can handle write size larger than 4kB
98 * FUSE_CAP_DONT_MASK: don't apply umask to file mode on create operations
99 * FUSE_CAP_SPLICE_WRITE: ability to use splice() to write to the fuse device
100 * FUSE_CAP_SPLICE_MOVE: ability to move data to the fuse device with splice()
101 * FUSE_CAP_SPLICE_READ: ability to use splice() to read from the fuse device
102 * FUSE_CAP_IOCTL_DIR: ioctl support on directories
103 */
104#define FUSE_CAP_ASYNC_READ	(1 << 0)
105#define FUSE_CAP_POSIX_LOCKS	(1 << 1)
106#define FUSE_CAP_ATOMIC_O_TRUNC	(1 << 3)
107#define FUSE_CAP_EXPORT_SUPPORT	(1 << 4)
108#define FUSE_CAP_BIG_WRITES	(1 << 5)
109#define FUSE_CAP_DONT_MASK	(1 << 6)
110#define FUSE_CAP_SPLICE_WRITE	(1 << 7)
111#define FUSE_CAP_SPLICE_MOVE	(1 << 8)
112#define FUSE_CAP_SPLICE_READ	(1 << 9)
113#define FUSE_CAP_FLOCK_LOCKS	(1 << 10)
114#define FUSE_CAP_IOCTL_DIR	(1 << 11)
115
116/* Indicate support for Haiku-specific extensions in struct fuse_operations and fuse_ll_ops */
117#define FUSE_CAP_HAIKU_FUSE_EXTENSIONS	(1 << 31)
118
119#define FUSE_HAIKU_GET_DRIVE_INFO (((uint32_t)'H' << 24) | ((uint32_t)'G' << 16) \
120	| ((uint32_t)'D' << 8) | (uint32_t)'I')
121
122/**
123 * Ioctl flags
124 *
125 * FUSE_IOCTL_COMPAT: 32bit compat ioctl on 64bit machine
126 * FUSE_IOCTL_UNRESTRICTED: not restricted to well-formed ioctls, retry allowed
127 * FUSE_IOCTL_RETRY: retry with new iovecs
128 * FUSE_IOCTL_DIR: is a directory
129 *
130 * FUSE_IOCTL_MAX_IOV: maximum of in_iovecs + out_iovecs
131 */
132#define FUSE_IOCTL_COMPAT	(1 << 0)
133#define FUSE_IOCTL_UNRESTRICTED	(1 << 1)
134#define FUSE_IOCTL_RETRY	(1 << 2)
135#define FUSE_IOCTL_DIR		(1 << 4)
136
137#define FUSE_IOCTL_MAX_IOV	256
138
139/**
140 * Connection information, passed to the ->init() method
141 *
142 * Some of the elements are read-write, these can be changed to
143 * indicate the value requested by the filesystem.  The requested
144 * value must usually be smaller than the indicated value.
145 */
146struct fuse_conn_info {
147	/**
148	 * Major version of the protocol (read-only)
149	 */
150	unsigned proto_major;
151
152	/**
153	 * Minor version of the protocol (read-only)
154	 */
155	unsigned proto_minor;
156
157	/**
158	 * Is asynchronous read supported (read-write)
159	 */
160	unsigned async_read;
161
162	/**
163	 * Maximum size of the write buffer
164	 */
165	unsigned max_write;
166
167	/**
168	 * Maximum readahead
169	 */
170	unsigned max_readahead;
171
172	/**
173	 * Capability flags, that the kernel supports
174	 */
175	unsigned capable;
176
177	/**
178	 * Capability flags, that the filesystem wants to enable
179	 */
180	unsigned want;
181
182	/**
183	 * Maximum number of backgrounded requests
184	 */
185	unsigned max_background;
186
187	/**
188	 * Kernel congestion threshold parameter
189	 */
190	unsigned congestion_threshold;
191
192	/**
193	 * For future use.
194	 */
195	unsigned reserved[23];
196};
197
198struct fuse_session;
199struct fuse_chan;
200struct fuse_pollhandle;
201
202/**
203 * Create a FUSE mountpoint
204 *
205 * Returns a control file descriptor suitable for passing to
206 * fuse_new()
207 *
208 * @param mountpoint the mount point path
209 * @param args argument vector
210 * @return the communication channel on success, NULL on failure
211 */
212struct fuse_chan *fuse_mount(const char *mountpoint, struct fuse_args *args);
213
214/**
215 * Umount a FUSE mountpoint
216 *
217 * @param mountpoint the mount point path
218 * @param ch the communication channel
219 */
220void fuse_unmount(const char *mountpoint, struct fuse_chan *ch);
221
222/**
223 * Parse common options
224 *
225 * The following options are parsed:
226 *
227 *   '-f'	     foreground
228 *   '-d' '-odebug'  foreground, but keep the debug option
229 *   '-s'	     single threaded
230 *   '-h' '--help'   help
231 *   '-ho'	     help without header
232 *   '-ofsname=..'   file system name, if not present, then set to the program
233 *		     name
234 *
235 * All parameters may be NULL
236 *
237 * @param args argument vector
238 * @param mountpoint the returned mountpoint, should be freed after use
239 * @param multithreaded set to 1 unless the '-s' option is present
240 * @param foreground set to 1 if one of the relevant options is present
241 * @return 0 on success, -1 on failure
242 */
243int fuse_parse_cmdline(struct fuse_args *args, char **mountpoint,
244		       int *multithreaded, int *foreground);
245
246/**
247 * Go into the background
248 *
249 * @param foreground if true, stay in the foreground
250 * @return 0 on success, -1 on failure
251 */
252int fuse_daemonize(int foreground);
253
254/**
255 * Get the version of the library
256 *
257 * @return the version
258 */
259int fuse_version(void);
260
261/**
262 * Destroy poll handle
263 *
264 * @param ph the poll handle
265 */
266void fuse_pollhandle_destroy(struct fuse_pollhandle *ph);
267
268/* ----------------------------------------------------------- *
269 * Data buffer						       *
270 * ----------------------------------------------------------- */
271
272/**
273 * Buffer flags
274 */
275enum fuse_buf_flags {
276	/**
277	 * Buffer contains a file descriptor
278	 *
279	 * If this flag is set, the .fd field is valid, otherwise the
280	 * .mem fields is valid.
281	 */
282	FUSE_BUF_IS_FD		= (1 << 1),
283
284	/**
285	 * Seek on the file descriptor
286	 *
287	 * If this flag is set then the .pos field is valid and is
288	 * used to seek to the given offset before performing
289	 * operation on file descriptor.
290	 */
291	FUSE_BUF_FD_SEEK	= (1 << 2),
292
293	/**
294	 * Retry operation on file descriptor
295	 *
296	 * If this flag is set then retry operation on file descriptor
297	 * until .size bytes have been copied or an error or EOF is
298	 * detected.
299	 */
300	FUSE_BUF_FD_RETRY	= (1 << 3),
301};
302
303/**
304 * Buffer copy flags
305 */
306enum fuse_buf_copy_flags {
307	/**
308	 * Don't use splice(2)
309	 *
310	 * Always fall back to using read and write instead of
311	 * splice(2) to copy data from one file descriptor to another.
312	 *
313	 * If this flag is not set, then only fall back if splice is
314	 * unavailable.
315	 */
316	FUSE_BUF_NO_SPLICE	= (1 << 1),
317
318	/**
319	 * Force splice
320	 *
321	 * Always use splice(2) to copy data from one file descriptor
322	 * to another.  If splice is not available, return -EINVAL.
323	 */
324	FUSE_BUF_FORCE_SPLICE	= (1 << 2),
325
326	/**
327	 * Try to move data with splice.
328	 *
329	 * If splice is used, try to move pages from the source to the
330	 * destination instead of copying.  See documentation of
331	 * SPLICE_F_MOVE in splice(2) man page.
332	 */
333	FUSE_BUF_SPLICE_MOVE	= (1 << 3),
334
335	/**
336	 * Don't block on the pipe when copying data with splice
337	 *
338	 * Makes the operations on the pipe non-blocking (if the pipe
339	 * is full or empty).  See SPLICE_F_NONBLOCK in the splice(2)
340	 * man page.
341	 */
342	FUSE_BUF_SPLICE_NONBLOCK= (1 << 4),
343};
344
345/**
346 * Single data buffer
347 *
348 * Generic data buffer for I/O, extended attributes, etc...  Data may
349 * be supplied as a memory pointer or as a file descriptor
350 */
351struct fuse_buf {
352	/**
353	 * Size of data in bytes
354	 */
355	size_t size;
356
357	/**
358	 * Buffer flags
359	 */
360	enum fuse_buf_flags flags;
361
362	/**
363	 * Memory pointer
364	 *
365	 * Used unless FUSE_BUF_IS_FD flag is set.
366	 */
367	void *mem;
368
369	/**
370	 * File descriptor
371	 *
372	 * Used if FUSE_BUF_IS_FD flag is set.
373	 */
374	int fd;
375
376	/**
377	 * File position
378	 *
379	 * Used if FUSE_BUF_FD_SEEK flag is set.
380	 */
381	off_t pos;
382};
383
384/**
385 * Data buffer vector
386 *
387 * An array of data buffers, each containing a memory pointer or a
388 * file descriptor.
389 *
390 * Allocate dynamically to add more than one buffer.
391 */
392struct fuse_bufvec {
393	/**
394	 * Number of buffers in the array
395	 */
396	size_t count;
397
398	/**
399	 * Index of current buffer within the array
400	 */
401	size_t idx;
402
403	/**
404	 * Current offset within the current buffer
405	 */
406	size_t off;
407
408	/**
409	 * Array of buffers
410	 */
411	struct fuse_buf buf[1];
412};
413
414/* Initialize bufvec with a single buffer of given size */
415#define FUSE_BUFVEC_INIT(size__) 				\
416	((struct fuse_bufvec) {					\
417		/* .count= */ 1,				\
418		/* .idx =  */ 0,				\
419		/* .off =  */ 0,				\
420		/* .buf =  */ { /* [0] = */ {			\
421			/* .size =  */ (size__),		\
422			/* .flags = */ (enum fuse_buf_flags) 0,	\
423			/* .mem =   */ NULL,			\
424			/* .fd =    */ -1,			\
425			/* .pos =   */ 0,			\
426		} }						\
427	} )
428
429/**
430 * Get total size of data in a fuse buffer vector
431 *
432 * @param bufv buffer vector
433 * @return size of data
434 */
435size_t fuse_buf_size(const struct fuse_bufvec *bufv);
436
437/**
438 * Copy data from one buffer vector to another
439 *
440 * @param dst destination buffer vector
441 * @param src source buffer vector
442 * @param flags flags controlling the copy
443 * @return actual number of bytes copied or -errno on error
444 */
445ssize_t fuse_buf_copy(struct fuse_bufvec *dst, struct fuse_bufvec *src,
446		      enum fuse_buf_copy_flags flags);
447
448/* ----------------------------------------------------------- *
449 * Signal handling					       *
450 * ----------------------------------------------------------- */
451
452/**
453 * Exit session on HUP, TERM and INT signals and ignore PIPE signal
454 *
455 * Stores session in a global variable.	 May only be called once per
456 * process until fuse_remove_signal_handlers() is called.
457 *
458 * @param se the session to exit
459 * @return 0 on success, -1 on failure
460 */
461int fuse_set_signal_handlers(struct fuse_session *se);
462
463/**
464 * Restore default signal handlers
465 *
466 * Resets global session.  After this fuse_set_signal_handlers() may
467 * be called again.
468 *
469 * @param se the same session as given in fuse_set_signal_handlers()
470 */
471void fuse_remove_signal_handlers(struct fuse_session *se);
472
473/* ----------------------------------------------------------- *
474 * Compatibility stuff					       *
475 * ----------------------------------------------------------- */
476
477#if FUSE_USE_VERSION < 26
478#    if defined(__FreeBSD__) || defined(__HAIKU__)
479#	 if FUSE_USE_VERSION < 25
480#	     error On FreeBSD API version 25 or greater must be used
481#	 endif
482#    endif
483#    include "fuse_common_compat.h"
484#    undef FUSE_MINOR_VERSION
485#    undef fuse_main
486#    define fuse_unmount fuse_unmount_compat22
487#    if FUSE_USE_VERSION == 25
488#	 define FUSE_MINOR_VERSION 5
489#	 define fuse_mount fuse_mount_compat25
490#    elif FUSE_USE_VERSION == 24 || FUSE_USE_VERSION == 22
491#	 define FUSE_MINOR_VERSION 4
492#	 define fuse_mount fuse_mount_compat22
493#    elif FUSE_USE_VERSION == 21
494#	 define FUSE_MINOR_VERSION 1
495#	 define fuse_mount fuse_mount_compat22
496#    elif FUSE_USE_VERSION == 11
497#	 warning Compatibility with API version 11 is deprecated
498#	 undef FUSE_MAJOR_VERSION
499#	 define FUSE_MAJOR_VERSION 1
500#	 define FUSE_MINOR_VERSION 1
501#	 define fuse_mount fuse_mount_compat1
502#    else
503#	 error Compatibility with API version other than 21, 22, 24, 25 and 11 not supported
504#    endif
505#endif
506
507#ifdef __cplusplus
508}
509#endif
510
511#endif /* _FUSE_COMMON_H_ */
512