You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

1516 lines
44 KiB

  1. /*
  2. FUSE: Filesystem in Userspace
  3. Copyright (C) 2001-2007 Miklos Szeredi <miklos@szeredi.hu>
  4. This program can be distributed under the terms of the GNU LGPLv2.
  5. See the file COPYING.LIB.
  6. */
  7. #ifndef _FUSE_LOWLEVEL_H_
  8. #define _FUSE_LOWLEVEL_H_
  9. #include "extern_c.h"
  10. #include "fuse_common.h"
  11. #include "fuse_kernel.h"
  12. #include <fcntl.h>
  13. #include <stdint.h>
  14. #include <sys/stat.h>
  15. #include <sys/statvfs.h>
  16. #include <sys/types.h>
  17. #include <sys/uio.h>
  18. #include <utime.h>
  19. EXTERN_C_BEGIN
  20. /* ----------------------------------------------------------- *
  21. * Miscellaneous definitions *
  22. * ----------------------------------------------------------- */
  23. /** The node ID of the root inode */
  24. #define FUSE_ROOT_ID 1
  25. /** Request pointer type */
  26. typedef struct fuse_req *fuse_req_t;
  27. /**
  28. * Session
  29. *
  30. * This provides hooks for processing requests, and exiting
  31. */
  32. struct fuse_session;
  33. /**
  34. * Channel
  35. *
  36. * A communication channel, providing hooks for sending and receiving
  37. * messages
  38. */
  39. struct fuse_chan;
  40. /** Directory entry parameters supplied to fuse_reply_entry() */
  41. struct fuse_entry_param
  42. {
  43. /** Unique inode number
  44. *
  45. * In lookup, zero means negative entry (from version 2.5)
  46. * Returning ENOENT also means negative entry, but by setting zero
  47. * ino the kernel may cache negative entries for entry_timeout
  48. * seconds.
  49. */
  50. uint64_t ino;
  51. /** Generation number for this entry.
  52. *
  53. * If the file system will be exported over NFS, the
  54. * ino/generation pairs need to be unique over the file
  55. * system's lifetime (rather than just the mount time). So if
  56. * the file system reuses an inode after it has been deleted,
  57. * it must assign a new, previously unused generation number
  58. * to the inode at the same time.
  59. *
  60. * The generation must be non-zero, otherwise FUSE will treat
  61. * it as an error.
  62. *
  63. */
  64. uint64_t generation;
  65. /** Inode attributes.
  66. *
  67. * Even if attr_timeout == 0, attr must be correct. For example,
  68. * for open(), FUSE uses attr.st_size from lookup() to determine
  69. * how many bytes to request. If this value is not correct,
  70. * incorrect data will be returned.
  71. */
  72. struct stat attr;
  73. fuse_timeouts_t timeout;
  74. };
  75. /** Additional context associated with requests */
  76. struct fuse_ctx
  77. {
  78. /** User ID of the calling process */
  79. uid_t uid;
  80. /** Group ID of the calling process */
  81. gid_t gid;
  82. /** Thread ID of the calling process */
  83. pid_t pid;
  84. /** Umask of the calling process (introduced in version 2.8) */
  85. mode_t umask;
  86. };
  87. /* ----------------------------------------------------------- *
  88. * Request methods and replies *
  89. * ----------------------------------------------------------- */
  90. /**
  91. * Low level filesystem operations
  92. *
  93. * Most of the methods (with the exception of init and destroy)
  94. * receive a request handle (fuse_req_t) as their first argument.
  95. * This handle must be passed to one of the specified reply functions.
  96. *
  97. * This may be done inside the method invocation, or after the call
  98. * has returned. The request handle is valid until one of the reply
  99. * functions is called.
  100. *
  101. * Other pointer arguments (name, fuse_file_info, etc) are not valid
  102. * after the call has returned, so if they are needed later, their
  103. * contents have to be copied.
  104. *
  105. * The filesystem sometimes needs to handle a return value of -ENOENT
  106. * from the reply function, which means, that the request was
  107. * interrupted, and the reply discarded. For example if
  108. * fuse_reply_open() return -ENOENT means, that the release method for
  109. * this file will not be called.
  110. */
  111. struct fuse_lowlevel_ops
  112. {
  113. /**
  114. * Initialize filesystem
  115. *
  116. * Called before any other filesystem method
  117. *
  118. * There's no reply to this function
  119. *
  120. * @param userdata the user data passed to fuse_lowlevel_new()
  121. */
  122. void (*init)(void *userdata, struct fuse_conn_info *conn);
  123. /**
  124. * Clean up filesystem
  125. *
  126. * Called on filesystem exit
  127. *
  128. * There's no reply to this function
  129. *
  130. * @param userdata the user data passed to fuse_lowlevel_new()
  131. */
  132. void (*destroy)(void *userdata);
  133. /**
  134. * Look up a directory entry by name and get its attributes.
  135. *
  136. * Valid replies:
  137. * fuse_reply_entry
  138. * fuse_reply_err
  139. *
  140. * @param req request handle
  141. * @param parent inode number of the parent directory
  142. * @param name the name to look up
  143. */
  144. void (*lookup)(fuse_req_t req,
  145. struct fuse_in_header *hdr);
  146. /**
  147. * Forget about an inode
  148. *
  149. * This function is called when the kernel removes an inode
  150. * from its internal caches.
  151. *
  152. * The inode's lookup count increases by one for every call to
  153. * fuse_reply_entry and fuse_reply_create. The nlookup parameter
  154. * indicates by how much the lookup count should be decreased.
  155. *
  156. * Inodes with a non-zero lookup count may receive request from
  157. * the kernel even after calls to unlink, rmdir or (when
  158. * overwriting an existing file) rename. Filesystems must handle
  159. * such requests properly and it is recommended to defer removal
  160. * of the inode until the lookup count reaches zero. Calls to
  161. * unlink, remdir or rename will be followed closely by forget
  162. * unless the file or directory is open, in which case the
  163. * kernel issues forget only after the release or releasedir
  164. * calls.
  165. *
  166. * Note that if a file system will be exported over NFS the
  167. * inodes lifetime must extend even beyond forget. See the
  168. * generation field in struct fuse_entry_param above.
  169. *
  170. * On unmount the lookup count for all inodes implicitly drops
  171. * to zero. It is not guaranteed that the file system will
  172. * receive corresponding forget messages for the affected
  173. * inodes.
  174. *
  175. * Valid replies:
  176. * fuse_reply_none
  177. *
  178. * @param req request handle
  179. * @param ino the inode number
  180. * @param nlookup the number of lookups to forget
  181. */
  182. void (*forget)(fuse_req_t req,
  183. struct fuse_in_header *hdr);
  184. /**
  185. * Get file attributes
  186. *
  187. * Valid replies:
  188. * fuse_reply_attr
  189. * fuse_reply_err
  190. */
  191. void (*getattr)(fuse_req_t req,
  192. struct fuse_in_header *hdr);
  193. /**
  194. * Set file attributes
  195. *
  196. * In the 'attr' argument only members indicated by the 'to_set'
  197. * bitmask contain valid values. Other members contain undefined
  198. * values.
  199. *
  200. * If the setattr was invoked from the ftruncate() system call
  201. * under Linux kernel versions 2.6.15 or later, the fi->fh will
  202. * contain the value set by the open method or will be undefined
  203. * if the open method didn't set any value. Otherwise (not
  204. * ftruncate call, or kernel version earlier than 2.6.15) the fi
  205. * parameter will be NULL.
  206. *
  207. * Valid replies:
  208. * fuse_reply_attr
  209. * fuse_reply_err
  210. *
  211. * @param req request handle
  212. * @param ino the inode number
  213. * @param attr the attributes
  214. * @param to_set bit mask of attributes which should be set
  215. * @param fi file information, or NULL
  216. *
  217. * Changed in version 2.5:
  218. * file information filled in for ftruncate
  219. */
  220. void (*setattr)(fuse_req_t req,
  221. struct fuse_in_header *hdr);
  222. /**
  223. * Read symbolic link
  224. *
  225. * Valid replies:
  226. * fuse_reply_readlink
  227. * fuse_reply_err
  228. *
  229. * @param req request handle
  230. * @param ino the inode number
  231. */
  232. void (*readlink)(fuse_req_t req,
  233. struct fuse_in_header *hdr);
  234. /**
  235. * Create file node
  236. *
  237. * Create a regular file, character device, block device, fifo or
  238. * socket node.
  239. *
  240. * Valid replies:
  241. * fuse_reply_entry
  242. * fuse_reply_err
  243. *
  244. * @param req request handle
  245. * @param parent inode number of the parent directory
  246. * @param name to create
  247. * @param mode file type and mode with which to create the new file
  248. * @param rdev the device number (only valid if created file is a device)
  249. */
  250. void (*mknod)(fuse_req_t req,
  251. struct fuse_in_header *hdr);
  252. /**
  253. * Create a directory
  254. *
  255. * Valid replies:
  256. * fuse_reply_entry
  257. * fuse_reply_err
  258. *
  259. * @param req request handle
  260. * @param parent inode number of the parent directory
  261. * @param name to create
  262. * @param mode with which to create the new file
  263. */
  264. void (*mkdir)(fuse_req_t req,
  265. struct fuse_in_header *hdr);
  266. /**
  267. * Remove a file
  268. *
  269. * If the file's inode's lookup count is non-zero, the file
  270. * system is expected to postpone any removal of the inode
  271. * until the lookup count reaches zero (see description of the
  272. * forget function).
  273. *
  274. * Valid replies:
  275. * fuse_reply_err
  276. *
  277. * @param req request handle
  278. * @param parent inode number of the parent directory
  279. * @param name to remove
  280. */
  281. void (*unlink)(fuse_req_t req,
  282. struct fuse_in_header *hdr);
  283. /**
  284. * Remove a directory
  285. *
  286. * If the directory's inode's lookup count is non-zero, the
  287. * file system is expected to postpone any removal of the
  288. * inode until the lookup count reaches zero (see description
  289. * of the forget function).
  290. *
  291. * Valid replies:
  292. * fuse_reply_err
  293. *
  294. * @param req request handle
  295. * @param parent inode number of the parent directory
  296. * @param name to remove
  297. */
  298. void (*rmdir)(fuse_req_t req,
  299. struct fuse_in_header *hdr);
  300. /**
  301. * Create a symbolic link
  302. *
  303. * Valid replies:
  304. * fuse_reply_entry
  305. * fuse_reply_err
  306. *
  307. * @param req request handle
  308. * @param link the contents of the symbolic link
  309. * @param parent inode number of the parent directory
  310. * @param name to create
  311. */
  312. void (*symlink)(fuse_req_t req,
  313. struct fuse_in_header *hdr);
  314. /** Rename a file
  315. *
  316. * If the target exists it should be atomically replaced. If
  317. * the target's inode's lookup count is non-zero, the file
  318. * system is expected to postpone any removal of the inode
  319. * until the lookup count reaches zero (see description of the
  320. * forget function).
  321. *
  322. * Valid replies:
  323. * fuse_reply_err
  324. *
  325. * @param req request handle
  326. * @param parent inode number of the old parent directory
  327. * @param name old name
  328. * @param newparent inode number of the new parent directory
  329. * @param newname new name
  330. */
  331. void (*rename)(fuse_req_t req,
  332. struct fuse_in_header *hdr);
  333. /**
  334. * Create a hard link
  335. *
  336. * Valid replies:
  337. * fuse_reply_entry
  338. * fuse_reply_err
  339. *
  340. * @param req request handle
  341. * @param ino the old inode number
  342. * @param newparent inode number of the new parent directory
  343. * @param newname new name to create
  344. */
  345. void (*link)(fuse_req_t req,
  346. struct fuse_in_header *hdr);
  347. /**
  348. * Open a file
  349. *
  350. * Open flags (with the exception of O_CREAT, O_EXCL, O_NOCTTY and
  351. * O_TRUNC) are available in fi->flags.
  352. *
  353. * Filesystem may store an arbitrary file handle (pointer, index,
  354. * etc) in fi->fh, and use this in other all other file operations
  355. * (read, write, flush, release, fsync).
  356. *
  357. * Filesystem may also implement stateless file I/O and not store
  358. * anything in fi->fh.
  359. *
  360. * There are also some flags (direct_io, keep_cache) which the
  361. * filesystem may set in fi, to change the way the file is opened.
  362. * See fuse_file_info structure in <fuse_common.h> for more details.
  363. *
  364. * Valid replies:
  365. * fuse_reply_open
  366. * fuse_reply_err
  367. *
  368. * @param req request handle
  369. * @param ino the inode number
  370. * @param fi file information
  371. */
  372. void (*open)(fuse_req_t req,
  373. struct fuse_in_header *hdr);
  374. /**
  375. * Read data
  376. *
  377. * Read should send exactly the number of bytes requested except
  378. * on EOF or error, otherwise the rest of the data will be
  379. * substituted with zeroes. An exception to this is when the file
  380. * has been opened in 'direct_io' mode, in which case the return
  381. * value of the read system call will reflect the return value of
  382. * this operation.
  383. *
  384. * fi->fh will contain the value set by the open method, or will
  385. * be undefined if the open method didn't set any value.
  386. *
  387. * Valid replies:
  388. * fuse_reply_buf
  389. * fuse_reply_iov
  390. * fuse_reply_data
  391. * fuse_reply_err
  392. *
  393. * @param req request handle
  394. * @param ino the inode number
  395. * @param size number of bytes to read
  396. * @param off offset to read from
  397. * @param fi file information
  398. */
  399. void (*read)(fuse_req_t req,
  400. struct fuse_in_header *hdr);
  401. /**
  402. * Write data
  403. *
  404. * Write should return exactly the number of bytes requested
  405. * except on error. An exception to this is when the file has
  406. * been opened in 'direct_io' mode, in which case the return value
  407. * of the write system call will reflect the return value of this
  408. * operation.
  409. *
  410. * fi->fh will contain the value set by the open method, or will
  411. * be undefined if the open method didn't set any value.
  412. *
  413. * Valid replies:
  414. * fuse_reply_write
  415. * fuse_reply_err
  416. *
  417. * @param req request handle
  418. * @param ino the inode number
  419. * @param buf data to write
  420. * @param size number of bytes to write
  421. * @param off offset to write to
  422. * @param fi file information
  423. */
  424. void (*write)(fuse_req_t req,
  425. struct fuse_in_header *hdr);
  426. /**
  427. * Flush method
  428. *
  429. * This is called on each close() of the opened file.
  430. *
  431. * Since file descriptors can be duplicated (dup, dup2, fork), for
  432. * one open call there may be many flush calls.
  433. *
  434. * Filesystems shouldn't assume that flush will always be called
  435. * after some writes, or that if will be called at all.
  436. *
  437. * fi->fh will contain the value set by the open method, or will
  438. * be undefined if the open method didn't set any value.
  439. *
  440. * NOTE: the name of the method is misleading, since (unlike
  441. * fsync) the filesystem is not forced to flush pending writes.
  442. * One reason to flush data, is if the filesystem wants to return
  443. * write errors.
  444. *
  445. * If the filesystem supports file locking operations (setlk,
  446. * getlk) it should remove all locks belonging to 'fi->owner'.
  447. *
  448. * Valid replies:
  449. * fuse_reply_err
  450. *
  451. * @param req request handle
  452. * @param ino the inode number
  453. * @param fi file information
  454. */
  455. void (*flush)(fuse_req_t req,
  456. struct fuse_in_header *hdr);
  457. /**
  458. * Release an open file
  459. *
  460. * Release is called when there are no more references to an open
  461. * file: all file descriptors are closed and all memory mappings
  462. * are unmapped.
  463. *
  464. * For every open call there will be exactly one release call.
  465. *
  466. * The filesystem may reply with an error, but error values are
  467. * not returned to close() or munmap() which triggered the
  468. * release.
  469. *
  470. * fi->fh will contain the value set by the open method, or will
  471. * be undefined if the open method didn't set any value.
  472. * fi->flags will contain the same flags as for open.
  473. *
  474. * Valid replies:
  475. * fuse_reply_err
  476. *
  477. * @param req request handle
  478. * @param ino the inode number
  479. * @param fi file information
  480. */
  481. void (*release)(fuse_req_t req,
  482. struct fuse_in_header *hdr);
  483. /**
  484. * Synchronize file contents
  485. *
  486. * If the datasync parameter is non-zero, then only the user data
  487. * should be flushed, not the meta data.
  488. *
  489. * Valid replies:
  490. * fuse_reply_err
  491. *
  492. * @param req request handle
  493. * @param ino the inode number
  494. * @param datasync flag indicating if only data should be flushed
  495. * @param fi file information
  496. */
  497. void (*fsync)(fuse_req_t req,
  498. struct fuse_in_header *hdr);
  499. /**
  500. * Open a directory
  501. *
  502. * Filesystem may store an arbitrary file handle (pointer, index,
  503. * etc) in fi->fh, and use this in other all other directory
  504. * stream operations (readdir, releasedir, fsyncdir).
  505. *
  506. * Filesystem may also implement stateless directory I/O and not
  507. * store anything in fi->fh, though that makes it impossible to
  508. * implement standard conforming directory stream operations in
  509. * case the contents of the directory can change between opendir
  510. * and releasedir.
  511. *
  512. * Valid replies:
  513. * fuse_reply_open
  514. * fuse_reply_err
  515. *
  516. * @param req request handle
  517. * @param ino the inode number
  518. * @param fi file information
  519. */
  520. void (*opendir)(fuse_req_t req,
  521. struct fuse_in_header *hdr);
  522. /**
  523. * Read directory
  524. *
  525. * Send a buffer filled using fuse_add_direntry(), with size not
  526. * exceeding the requested size. Send an empty buffer on end of
  527. * stream.
  528. *
  529. * fi->fh will contain the value set by the opendir method, or
  530. * will be undefined if the opendir method didn't set any value.
  531. *
  532. * Valid replies:
  533. * fuse_reply_buf
  534. * fuse_reply_data
  535. * fuse_reply_err
  536. *
  537. * @param req request handle
  538. * @param ino the inode number
  539. * @param size maximum number of bytes to send
  540. * @param off offset to continue reading the directory stream
  541. * @param fi file information
  542. */
  543. void (*readdir)(fuse_req_t req,
  544. struct fuse_in_header *hdr);
  545. void (*readdir_plus)(fuse_req_t req,
  546. struct fuse_in_header *hdr);
  547. /**
  548. * Release an open directory
  549. *
  550. * For every opendir call there will be exactly one releasedir
  551. * call.
  552. *
  553. * fi->fh will contain the value set by the opendir method, or
  554. * will be undefined if the opendir method didn't set any value.
  555. *
  556. * Valid replies:
  557. * fuse_reply_err
  558. *
  559. * @param req request handle
  560. * @param ino the inode number
  561. * @param fi file information
  562. */
  563. void (*releasedir)(fuse_req_t req,
  564. struct fuse_in_header *hdr);
  565. /**
  566. * Synchronize directory contents
  567. *
  568. * If the datasync parameter is non-zero, then only the directory
  569. * contents should be flushed, not the meta data.
  570. *
  571. * fi->fh will contain the value set by the opendir method, or
  572. * will be undefined if the opendir method didn't set any value.
  573. *
  574. * Valid replies:
  575. * fuse_reply_err
  576. *
  577. * @param req request handle
  578. * @param ino the inode number
  579. * @param datasync flag indicating if only data should be flushed
  580. * @param fi file information
  581. */
  582. void (*fsyncdir)(fuse_req_t req,
  583. struct fuse_in_header *hdr);
  584. /**
  585. * Get file system statistics
  586. *
  587. * Valid replies:
  588. * fuse_reply_statfs
  589. * fuse_reply_err
  590. *
  591. * @param req request handle
  592. * @param ino the inode number, zero means "undefined"
  593. */
  594. void (*statfs)(fuse_req_t req,
  595. struct fuse_in_header *hdr);
  596. /**
  597. * Set an extended attribute
  598. *
  599. * Valid replies:
  600. * fuse_reply_err
  601. */
  602. void (*setxattr)(fuse_req_t req,
  603. struct fuse_in_header *hdr);
  604. /**
  605. * Get an extended attribute
  606. *
  607. * If size is zero, the size of the value should be sent with
  608. * fuse_reply_xattr.
  609. *
  610. * If the size is non-zero, and the value fits in the buffer, the
  611. * value should be sent with fuse_reply_buf.
  612. *
  613. * If the size is too small for the value, the ERANGE error should
  614. * be sent.
  615. *
  616. * Valid replies:
  617. * fuse_reply_buf
  618. * fuse_reply_data
  619. * fuse_reply_xattr
  620. * fuse_reply_err
  621. *
  622. * @param req request handle
  623. * @param ino the inode number
  624. * @param name of the extended attribute
  625. * @param size maximum size of the value to send
  626. */
  627. void (*getxattr)(fuse_req_t req,
  628. struct fuse_in_header *hdr);
  629. /**
  630. * List extended attribute names
  631. *
  632. * If size is zero, the total size of the attribute list should be
  633. * sent with fuse_reply_xattr.
  634. *
  635. * If the size is non-zero, and the null character separated
  636. * attribute list fits in the buffer, the list should be sent with
  637. * fuse_reply_buf.
  638. *
  639. * If the size is too small for the list, the ERANGE error should
  640. * be sent.
  641. *
  642. * Valid replies:
  643. * fuse_reply_buf
  644. * fuse_reply_data
  645. * fuse_reply_xattr
  646. * fuse_reply_err
  647. *
  648. * @param req request handle
  649. * @param ino the inode number
  650. * @param size maximum size of the list to send
  651. */
  652. void (*listxattr)(fuse_req_t req,
  653. struct fuse_in_header *hdr);
  654. /**
  655. * Remove an extended attribute
  656. *
  657. * Valid replies:
  658. * fuse_reply_err
  659. *
  660. * @param req request handle
  661. * @param ino the inode number
  662. * @param name of the extended attribute
  663. */
  664. void (*removexattr)(fuse_req_t req,
  665. const struct fuse_in_header *hdr);
  666. /**
  667. * Check file access permissions
  668. *
  669. * This will be called for the access() system call. If the
  670. * 'default_permissions' mount option is given, this method is not
  671. * called.
  672. *
  673. * This method is not called under Linux kernel versions 2.4.x
  674. *
  675. * Introduced in version 2.5
  676. *
  677. * Valid replies:
  678. * fuse_reply_err
  679. *
  680. * @param req request handle
  681. * @param ino the inode number
  682. * @param mask requested access mode
  683. */
  684. void (*access)(fuse_req_t req,
  685. struct fuse_in_header *hdr);
  686. /**
  687. * Create and open a file
  688. *
  689. * If the file does not exist, first create it with the specified
  690. * mode, and then open it.
  691. *
  692. * Open flags (with the exception of O_NOCTTY) are available in
  693. * fi->flags.
  694. *
  695. * Filesystem may store an arbitrary file handle (pointer, index,
  696. * etc) in fi->fh, and use this in other all other file operations
  697. * (read, write, flush, release, fsync).
  698. *
  699. * There are also some flags (direct_io, keep_cache) which the
  700. * filesystem may set in fi, to change the way the file is opened.
  701. * See fuse_file_info structure in <fuse_common.h> for more details.
  702. *
  703. * If this method is not implemented or under Linux kernel
  704. * versions earlier than 2.6.15, the mknod() and open() methods
  705. * will be called instead.
  706. *
  707. * Introduced in version 2.5
  708. *
  709. * Valid replies:
  710. * fuse_reply_create
  711. * fuse_reply_err
  712. *
  713. * @param req request handle
  714. * @param parent inode number of the parent directory
  715. * @param name to create
  716. * @param mode file type and mode with which to create the new file
  717. * @param fi file information
  718. */
  719. void (*create)(fuse_req_t req,
  720. struct fuse_in_header *hdr);
  721. /**
  722. * Test for a POSIX file lock
  723. *
  724. * Introduced in version 2.6
  725. *
  726. * Valid replies:
  727. * fuse_reply_lock
  728. * fuse_reply_err
  729. *
  730. * @param req request handle
  731. * @param ino the inode number
  732. * @param fi file information
  733. * @param lock the region/type to test
  734. */
  735. void (*getlk)(fuse_req_t req,
  736. const struct fuse_in_header *hdr);
  737. /**
  738. * Acquire, modify or release a POSIX file lock
  739. *
  740. * For POSIX threads (NPTL) there's a 1-1 relation between pid and
  741. * owner, but otherwise this is not always the case. For checking
  742. * lock ownership, 'fi->owner' must be used. The l_pid field in
  743. * 'struct flock' should only be used to fill in this field in
  744. * getlk().
  745. *
  746. * Note: if the locking methods are not implemented, the kernel
  747. * will still allow file locking to work locally. Hence these are
  748. * only interesting for network filesystems and similar.
  749. *
  750. * Introduced in version 2.6
  751. *
  752. * Valid replies:
  753. * fuse_reply_err
  754. *
  755. * @param req request handle
  756. * @param ino the inode number
  757. * @param fi file information
  758. * @param lock the region/type to set
  759. * @param sleep locking operation may sleep
  760. */
  761. void (*setlk)(fuse_req_t req, uint64_t ino,
  762. fuse_file_info_t *fi,
  763. struct flock *lock, int sleep);
  764. /**
  765. * Map block index within file to block index within device
  766. *
  767. * Note: This makes sense only for block device backed filesystems
  768. * mounted with the 'blkdev' option
  769. *
  770. * Introduced in version 2.6
  771. *
  772. * Valid replies:
  773. * fuse_reply_bmap
  774. * fuse_reply_err
  775. *
  776. * @param req request handle
  777. * @param ino the inode number
  778. * @param blocksize unit of block index
  779. * @param idx block index within file
  780. */
  781. void (*bmap)(fuse_req_t req,
  782. const struct fuse_in_header *hdr);
  783. /**
  784. * Ioctl
  785. *
  786. * Note: For unrestricted ioctls (not allowed for FUSE
  787. * servers), data in and out areas can be discovered by giving
  788. * iovs and setting FUSE_IOCTL_RETRY in @flags. For
  789. * restricted ioctls, kernel prepares in/out data area
  790. * according to the information encoded in cmd.
  791. *
  792. * Introduced in version 2.8
  793. *
  794. * Valid replies:
  795. * fuse_reply_ioctl_retry
  796. * fuse_reply_ioctl
  797. * fuse_reply_ioctl_iov
  798. * fuse_reply_err
  799. *
  800. * @param req request handle
  801. * @param ino the inode number
  802. * @param cmd ioctl command
  803. * @param arg ioctl argument
  804. * @param fi file information
  805. * @param flags for FUSE_IOCTL_* flags
  806. * @param in_buf data fetched from the caller
  807. * @param in_bufsz number of fetched bytes
  808. * @param out_bufsz maximum size of output data
  809. */
  810. void (*ioctl)(fuse_req_t req,
  811. const struct fuse_in_header *hdr);
  812. /**
  813. * Poll for IO readiness
  814. *
  815. * Introduced in version 2.8
  816. *
  817. * Note: If ph is non-NULL, the client should notify
  818. * when IO readiness events occur by calling
  819. * fuse_lowelevel_notify_poll() with the specified ph.
  820. *
  821. * Regardless of the number of times poll with a non-NULL ph
  822. * is received, single notification is enough to clear all.
  823. * Notifying more times incurs overhead but doesn't harm
  824. * correctness.
  825. *
  826. * The callee is responsible for destroying ph with
  827. * fuse_pollhandle_destroy() when no longer in use.
  828. *
  829. * Valid replies:
  830. * fuse_reply_poll
  831. * fuse_reply_err
  832. *
  833. * @param req request handle
  834. * @param ino the inode number
  835. * @param fi file information
  836. * @param ph poll handle to be used for notification
  837. */
  838. void (*poll)(fuse_req_t req,
  839. const struct fuse_in_header *hdr);
  840. /**
  841. * Callback function for the retrieve request
  842. *
  843. * Introduced in version 2.9
  844. *
  845. * Valid replies:
  846. * fuse_reply_none
  847. *
  848. * @param req request handle
  849. * @param cookie user data supplied to fuse_lowlevel_notify_retrieve()
  850. * @param ino the inode number supplied to fuse_lowlevel_notify_retrieve()
  851. * @param offset the offset supplied to fuse_lowlevel_notify_retrieve()
  852. * @param bufv the buffer containing the returned data
  853. */
  854. void (*retrieve_reply)(fuse_req_t req,
  855. void *cookie,
  856. uint64_t ino,
  857. off_t offset);
  858. /**
  859. * Forget about multiple inodes
  860. *
  861. * See description of the forget function for more
  862. * information.
  863. *
  864. * Introduced in version 2.9
  865. *
  866. * Valid replies:
  867. * fuse_reply_none
  868. *
  869. * @param req request handle
  870. */
  871. void (*forget_multi)(fuse_req_t req,
  872. struct fuse_in_header *hdr);
  873. /**
  874. * Acquire, modify or release a BSD file lock
  875. *
  876. * Note: if the locking methods are not implemented, the kernel
  877. * will still allow file locking to work locally. Hence these are
  878. * only interesting for network filesystems and similar.
  879. *
  880. * Introduced in version 2.9
  881. *
  882. * Valid replies:
  883. * fuse_reply_err
  884. *
  885. * @param req request handle
  886. * @param ino the inode number
  887. * @param fi file information
  888. * @param op the locking operation, see flock(2)
  889. */
  890. void (*flock)(fuse_req_t req, uint64_t ino,
  891. fuse_file_info_t *fi, int op);
  892. /**
  893. * Allocate requested space. If this function returns success then
  894. * subsequent writes to the specified range shall not fail due to the lack
  895. * of free space on the file system storage media.
  896. *
  897. * Introduced in version 2.9
  898. *
  899. * Valid replies:
  900. * fuse_reply_err
  901. *
  902. * @param req request handle
  903. * @param ino the inode number
  904. * @param offset starting point for allocated region
  905. * @param length size of allocated region
  906. * @param mode determines the operation to be performed on the given range,
  907. * see fallocate(2)
  908. */
  909. void (*fallocate)(fuse_req_t req,
  910. const struct fuse_in_header *hdr);
  911. /**
  912. * Copy a range of data from one file to another
  913. *
  914. * Performs an optimized copy between two file descriptors without
  915. * the
  916. * additional cost of transferring data through the FUSE kernel
  917. * module
  918. * to user space (glibc) and then back into the FUSE filesystem
  919. * again.
  920. *
  921. * In case this method is not implemented, glibc falls back to
  922. * reading
  923. * data from the source and writing to the destination. Effectively
  924. * doing an inefficient copy of the data.
  925. *
  926. * If this request is answered with an error code of ENOSYS, this is
  927. * treated as a permanent failure with error code EOPNOTSUPP,
  928. * i.e. all
  929. * future copy_file_range() requests will fail with EOPNOTSUPP
  930. * without
  931. * being send to the filesystem process.
  932. *
  933. * Valid replies:
  934. * fuse_reply_write
  935. * fuse_reply_err
  936. *
  937. * @param req request handle
  938. * @param ino_in the inode number of the source file
  939. * @param off_in starting point from were the data should be read
  940. * @param fi_in file information of the source file
  941. * @param ino_out the inode number of the destination file
  942. * @param off_out starting point where the data should be written
  943. * @param fi_out file information of the destination file
  944. * @param len maximum size of the data to copy
  945. * @param flags passed along with the copy_file_range() syscall
  946. */
  947. void (*copy_file_range)(fuse_req_t req,
  948. const struct fuse_in_header *hdr);
  949. };
  950. /**
  951. * Reply with an error code or success
  952. *
  953. * Possible requests:
  954. * all except forget
  955. *
  956. * unlink, rmdir, rename, flush, release, fsync, fsyncdir, setxattr,
  957. * removexattr and setlk may send a zero code
  958. *
  959. * @param req request handle
  960. * @param err the positive error value, or zero for success
  961. * @return zero for success, -errno for failure to send reply
  962. */
  963. int fuse_reply_err(fuse_req_t req, int err);
  964. /**
  965. * Don't send reply
  966. *
  967. * Possible requests:
  968. * forget
  969. *
  970. * @param req request handle
  971. */
  972. void fuse_reply_none(fuse_req_t req);
  973. /**
  974. * Reply with a directory entry
  975. *
  976. * Possible requests:
  977. * lookup, mknod, mkdir, symlink, link
  978. *
  979. * Side effects:
  980. * increments the lookup count on success
  981. *
  982. * @param req request handle
  983. * @param e the entry parameters
  984. * @return zero for success, -errno for failure to send reply
  985. */
  986. int fuse_reply_entry(fuse_req_t req, const struct fuse_entry_param *e);
  987. /**
  988. * Reply with a directory entry and open parameters
  989. *
  990. * currently the following members of 'fi' are used:
  991. * fh, direct_io, keep_cache
  992. *
  993. * Possible requests:
  994. * create
  995. *
  996. * Side effects:
  997. * increments the lookup count on success
  998. *
  999. * @param req request handle
  1000. * @param e the entry parameters
  1001. * @param fi file information
  1002. * @return zero for success, -errno for failure to send reply
  1003. */
  1004. int fuse_reply_create(fuse_req_t req, const struct fuse_entry_param *e,
  1005. const fuse_file_info_t *fi);
  1006. /**
  1007. * Reply with attributes
  1008. *
  1009. * Possible requests:
  1010. * getattr, setattr
  1011. *
  1012. * @param req request handle
  1013. * @param attr the attributes
  1014. * @param attr_timeout validity timeout (in seconds) for the attributes
  1015. * @return zero for success, -errno for failure to send reply
  1016. */
  1017. int fuse_reply_attr(fuse_req_t req,
  1018. const struct stat *attr,
  1019. const uint64_t timeout);
  1020. /**
  1021. * Reply with the contents of a symbolic link
  1022. *
  1023. * Possible requests:
  1024. * readlink
  1025. *
  1026. * @param req request handle
  1027. * @param link symbolic link contents
  1028. * @return zero for success, -errno for failure to send reply
  1029. */
  1030. int fuse_reply_readlink(fuse_req_t req, const char *link);
  1031. /**
  1032. * Reply with open parameters
  1033. *
  1034. * currently the following members of 'fi' are used:
  1035. * fh, direct_io, keep_cache
  1036. *
  1037. * Possible requests:
  1038. * open, opendir
  1039. *
  1040. * @param req request handle
  1041. * @param fi file information
  1042. * @return zero for success, -errno for failure to send reply
  1043. */
  1044. int fuse_reply_open(fuse_req_t req,
  1045. const fuse_file_info_t *fi);
  1046. /**
  1047. * Reply with number of bytes written
  1048. *
  1049. * Possible requests:
  1050. * write
  1051. *
  1052. * @param req request handle
  1053. * @param count the number of bytes written
  1054. * @return zero for success, -errno for failure to send reply
  1055. */
  1056. int fuse_reply_write(fuse_req_t req, size_t count);
  1057. /**
  1058. * Reply with data
  1059. *
  1060. * Possible requests:
  1061. * read, readdir, getxattr, listxattr
  1062. *
  1063. * @param req request handle
  1064. * @param buf buffer containing data
  1065. * @param size the size of data in bytes
  1066. * @return zero for success, -errno for failure to send reply
  1067. */
  1068. int fuse_reply_buf(fuse_req_t req, const char *buf, size_t size);
  1069. /**
  1070. * Reply with data copied/moved from buffer(s)
  1071. *
  1072. * Possible requests:
  1073. * read, readdir, getxattr, listxattr
  1074. *
  1075. * @param req request handle
  1076. * @param bufv buffer vector
  1077. * @param flags flags controlling the copy
  1078. * @return zero for success, -errno for failure to send reply
  1079. */
  1080. int fuse_reply_data(fuse_req_t req, struct fuse_bufvec *bufv,
  1081. enum fuse_buf_copy_flags flags);
  1082. /**
  1083. * Reply with data vector
  1084. *
  1085. * Possible requests:
  1086. * read, readdir, getxattr, listxattr
  1087. *
  1088. * @param req request handle
  1089. * @param iov the vector containing the data
  1090. * @param count the size of vector
  1091. * @return zero for success, -errno for failure to send reply
  1092. */
  1093. int fuse_reply_iov(fuse_req_t req, const struct iovec *iov, int count);
  1094. /**
  1095. * Reply with filesystem statistics
  1096. *
  1097. * Possible requests:
  1098. * statfs
  1099. *
  1100. * @param req request handle
  1101. * @param stbuf filesystem statistics
  1102. * @return zero for success, -errno for failure to send reply
  1103. */
  1104. int fuse_reply_statfs(fuse_req_t req, const struct statvfs *stbuf);
  1105. /**
  1106. * Reply with needed buffer size
  1107. *
  1108. * Possible requests:
  1109. * getxattr, listxattr
  1110. *
  1111. * @param req request handle
  1112. * @param count the buffer size needed in bytes
  1113. * @return zero for success, -errno for failure to send reply
  1114. */
  1115. int fuse_reply_xattr(fuse_req_t req, size_t count);
  1116. /**
  1117. * Reply with file lock information
  1118. *
  1119. * Possible requests:
  1120. * getlk
  1121. *
  1122. * @param req request handle
  1123. * @param lock the lock information
  1124. * @return zero for success, -errno for failure to send reply
  1125. */
  1126. int fuse_reply_lock(fuse_req_t req, const struct flock *lock);
  1127. /**
  1128. * Reply with block index
  1129. *
  1130. * Possible requests:
  1131. * bmap
  1132. *
  1133. * @param req request handle
  1134. * @param idx block index within device
  1135. * @return zero for success, -errno for failure to send reply
  1136. */
  1137. int fuse_reply_bmap(fuse_req_t req, uint64_t idx);
  1138. /**
  1139. * Reply to ask for data fetch and output buffer preparation. ioctl
  1140. * will be retried with the specified input data fetched and output
  1141. * buffer prepared.
  1142. *
  1143. * Possible requests:
  1144. * ioctl
  1145. *
  1146. * @param req request handle
  1147. * @param in_iov iovec specifying data to fetch from the caller
  1148. * @param in_count number of entries in in_iov
  1149. * @param out_iov iovec specifying addresses to write output to
  1150. * @param out_count number of entries in out_iov
  1151. * @return zero for success, -errno for failure to send reply
  1152. */
  1153. int fuse_reply_ioctl_retry(fuse_req_t req,
  1154. const struct iovec *in_iov, size_t in_count,
  1155. const struct iovec *out_iov, size_t out_count);
  1156. /**
  1157. * Reply to finish ioctl
  1158. *
  1159. * Possible requests:
  1160. * ioctl
  1161. *
  1162. * @param req request handle
  1163. * @param result result to be passed to the caller
  1164. * @param buf buffer containing output data
  1165. * @param size length of output data
  1166. */
  1167. int fuse_reply_ioctl(fuse_req_t req, int result, const void *buf, uint32_t size);
  1168. /**
  1169. * Reply to finish ioctl with iov buffer
  1170. *
  1171. * Possible requests:
  1172. * ioctl
  1173. *
  1174. * @param req request handle
  1175. * @param result result to be passed to the caller
  1176. * @param iov the vector containing the data
  1177. * @param count the size of vector
  1178. */
  1179. int fuse_reply_ioctl_iov(fuse_req_t req, int result, const struct iovec *iov,
  1180. int count);
  1181. /**
  1182. * Reply with poll result event mask
  1183. *
  1184. * @param req request handle
  1185. * @param revents poll result event mask
  1186. */
  1187. int fuse_reply_poll(fuse_req_t req, unsigned revents);
  1188. /* ----------------------------------------------------------- *
  1189. * Notification *
  1190. * ----------------------------------------------------------- */
  1191. /**
  1192. * Notify IO readiness event
  1193. *
  1194. * For more information, please read comment for poll operation.
  1195. *
  1196. * @param ph poll handle to notify IO readiness event for
  1197. */
  1198. int fuse_lowlevel_notify_poll(fuse_pollhandle_t *ph);
  1199. /**
  1200. * Notify to invalidate cache for an inode
  1201. *
  1202. * @param ch the channel through which to send the invalidation
  1203. * @param ino the inode number
  1204. * @param off the offset in the inode where to start invalidating
  1205. * or negative to invalidate attributes only
  1206. * @param len the amount of cache to invalidate or 0 for all
  1207. * @return zero for success, -errno for failure
  1208. */
  1209. int fuse_lowlevel_notify_inval_inode(struct fuse_chan *ch, uint64_t ino,
  1210. off_t off, off_t len);
  1211. /**
  1212. * Notify to invalidate parent attributes and the dentry matching
  1213. * parent/name
  1214. *
  1215. * To avoid a deadlock don't call this function from a filesystem operation and
  1216. * don't call it with a lock held that can also be held by a filesystem
  1217. * operation.
  1218. *
  1219. * @param ch the channel through which to send the invalidation
  1220. * @param parent inode number
  1221. * @param name file name
  1222. * @param namelen strlen() of file name
  1223. * @return zero for success, -errno for failure
  1224. */
  1225. int fuse_lowlevel_notify_inval_entry(struct fuse_chan *ch, uint64_t parent,
  1226. const char *name, size_t namelen);
  1227. /**
  1228. * Notify to invalidate parent attributes and delete the dentry matching
  1229. * parent/name if the dentry's inode number matches child (otherwise it
  1230. * will invalidate the matching dentry).
  1231. *
  1232. * To avoid a deadlock don't call this function from a filesystem operation and
  1233. * don't call it with a lock held that can also be held by a filesystem
  1234. * operation.
  1235. *
  1236. * @param ch the channel through which to send the notification
  1237. * @param parent inode number
  1238. * @param child inode number
  1239. * @param name file name
  1240. * @param namelen strlen() of file name
  1241. * @return zero for success, -errno for failure
  1242. */
  1243. int fuse_lowlevel_notify_delete(struct fuse_chan *ch,
  1244. uint64_t parent, uint64_t child,
  1245. const char *name, size_t namelen);
  1246. /**
  1247. * Store data to the kernel buffers
  1248. *
  1249. * Synchronously store data in the kernel buffers belonging to the
  1250. * given inode. The stored data is marked up-to-date (no read will be
  1251. * performed against it, unless it's invalidated or evicted from the
  1252. * cache).
  1253. *
  1254. * If the stored data overflows the current file size, then the size
  1255. * is extended, similarly to a write(2) on the filesystem.
  1256. *
  1257. * If this function returns an error, then the store wasn't fully
  1258. * completed, but it may have been partially completed.
  1259. *
  1260. * @param ch the channel through which to send the invalidation
  1261. * @param ino the inode number
  1262. * @param offset the starting offset into the file to store to
  1263. * @param bufv buffer vector
  1264. * @param flags flags controlling the copy
  1265. * @return zero for success, -errno for failure
  1266. */
  1267. int fuse_lowlevel_notify_store(struct fuse_chan *ch, uint64_t ino,
  1268. off_t offset, struct fuse_bufvec *bufv,
  1269. enum fuse_buf_copy_flags flags);
  1270. /**
  1271. * Retrieve data from the kernel buffers
  1272. *
  1273. * Retrieve data in the kernel buffers belonging to the given inode.
  1274. * If successful then the retrieve_reply() method will be called with
  1275. * the returned data.
  1276. *
  1277. * Only present pages are returned in the retrieve reply. Retrieving
  1278. * stops when it finds a non-present page and only data prior to that is
  1279. * returned.
  1280. *
  1281. * If this function returns an error, then the retrieve will not be
  1282. * completed and no reply will be sent.
  1283. *
  1284. * This function doesn't change the dirty state of pages in the kernel
  1285. * buffer. For dirty pages the write() method will be called
  1286. * regardless of having been retrieved previously.
  1287. *
  1288. * @param ch the channel through which to send the invalidation
  1289. * @param ino the inode number
  1290. * @param size the number of bytes to retrieve
  1291. * @param offset the starting offset into the file to retrieve from
  1292. * @param cookie user data to supply to the reply callback
  1293. * @return zero for success, -errno for failure
  1294. */
  1295. int fuse_lowlevel_notify_retrieve(struct fuse_chan *ch, uint64_t ino,
  1296. size_t size, off_t offset, void *cookie);
  1297. /* ----------------------------------------------------------- *
  1298. * Utility functions *
  1299. * ----------------------------------------------------------- */
  1300. /**
  1301. * Get the userdata from the request
  1302. *
  1303. * @param req request handle
  1304. * @return the user data passed to fuse_lowlevel_new()
  1305. */
  1306. void *fuse_req_userdata(fuse_req_t req);
  1307. /**
  1308. * Get the context from the request
  1309. *
  1310. * The pointer returned by this function will only be valid for the
  1311. * request's lifetime
  1312. *
  1313. * @param req request handle
  1314. * @return the context structure
  1315. */
  1316. const struct fuse_ctx *fuse_req_ctx(fuse_req_t req);
  1317. /**
  1318. * Get the current supplementary group IDs for the specified request
  1319. *
  1320. * Similar to the getgroups(2) system call, except the return value is
  1321. * always the total number of group IDs, even if it is larger than the
  1322. * specified size.
  1323. *
  1324. * The current fuse kernel module in linux (as of 2.6.30) doesn't pass
  1325. * the group list to userspace, hence this function needs to parse
  1326. * "/proc/$TID/task/$TID/status" to get the group IDs.
  1327. *
  1328. * This feature may not be supported on all operating systems. In
  1329. * such a case this function will return -ENOSYS.
  1330. *
  1331. * @param req request handle
  1332. * @param size size of given array
  1333. * @param list array of group IDs to be filled in
  1334. * @return the total number of supplementary group IDs or -errno on failure
  1335. */
  1336. int fuse_req_getgroups(fuse_req_t req, int size, gid_t list[]);
  1337. /* ----------------------------------------------------------- *
  1338. * Filesystem setup *
  1339. * ----------------------------------------------------------- */
  1340. /* Deprecated, don't use */
  1341. int fuse_lowlevel_is_lib_option(const char *opt);
  1342. /**
  1343. * Create a low level session
  1344. *
  1345. * @param args argument vector
  1346. * @param op the low level filesystem operations
  1347. * @param op_size sizeof(struct fuse_lowlevel_ops)
  1348. * @param userdata user data
  1349. * @return the created session object, or NULL on failure
  1350. */
  1351. struct fuse_session *fuse_lowlevel_new(struct fuse_args *args,
  1352. const struct fuse_lowlevel_ops *op,
  1353. size_t op_size, void *userdata);
  1354. /* ----------------------------------------------------------- *
  1355. * Session interface *
  1356. * ----------------------------------------------------------- */
  1357. struct fuse_session *fuse_session_new(void *data,
  1358. void *receive_buf,
  1359. void *process_buf,
  1360. void *destroy);
  1361. void fuse_session_add_chan(struct fuse_session *se, struct fuse_chan *ch);
  1362. void fuse_session_remove_chan(struct fuse_chan *ch);
  1363. void fuse_session_destroy(struct fuse_session *se);
  1364. void fuse_session_exit(struct fuse_session *se);
  1365. int fuse_session_exited(struct fuse_session *se);
  1366. void fuse_session_reset(struct fuse_session *se);
  1367. void *fuse_session_data(struct fuse_session *se);
  1368. int fuse_session_receive(struct fuse_session *se,
  1369. struct fuse_buf *buf);
  1370. void fuse_session_process(struct fuse_session *se,
  1371. const void *buf,
  1372. const size_t bufsize);
  1373. int fuse_session_loop_mt(struct fuse_session *se,
  1374. const int read_thread_count,
  1375. const int process_thread_count);
  1376. /* ----------------------------------------------------------- *
  1377. * Channel interface *
  1378. * ----------------------------------------------------------- */
  1379. struct fuse_chan *fuse_chan_new(int fd, size_t bufsize);
  1380. /**
  1381. * Query the file descriptor of the channel
  1382. *
  1383. * @param ch the channel
  1384. * @return the file descriptor passed to fuse_chan_new()
  1385. */
  1386. int fuse_chan_fd(struct fuse_chan *ch);
  1387. /**
  1388. * Query the minimal receive buffer size
  1389. *
  1390. * @param ch the channel
  1391. * @return the buffer size passed to fuse_chan_new()
  1392. */
  1393. size_t fuse_chan_bufsize(struct fuse_chan *ch);
  1394. /**
  1395. * Query the user data
  1396. *
  1397. * @param ch the channel
  1398. * @return the user data passed to fuse_chan_new()
  1399. */
  1400. void *fuse_chan_data(struct fuse_chan *ch);
  1401. /**
  1402. * Query the session to which this channel is assigned
  1403. *
  1404. * @param ch the channel
  1405. * @return the session, or NULL if the channel is not assigned
  1406. */
  1407. struct fuse_session *fuse_chan_session(struct fuse_chan *ch);
  1408. void fuse_chan_destroy(struct fuse_chan *ch);
  1409. EXTERN_C_END
  1410. #endif /* _FUSE_LOWLEVEL_H_ */