fsnotify_backend.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452
  1. /*
  2. * Filesystem access notification for Linux
  3. *
  4. * Copyright (C) 2008 Red Hat, Inc., Eric Paris <eparis@redhat.com>
  5. */
  6. #ifndef __LINUX_FSNOTIFY_BACKEND_H
  7. #define __LINUX_FSNOTIFY_BACKEND_H
  8. #ifdef __KERNEL__
  9. #include <linux/idr.h> /* inotify uses this */
  10. #include <linux/fs.h> /* struct inode */
  11. #include <linux/list.h>
  12. #include <linux/path.h> /* struct path */
  13. #include <linux/spinlock.h>
  14. #include <linux/types.h>
  15. #include <asm/atomic.h>
  16. /*
  17. * IN_* from inotfy.h lines up EXACTLY with FS_*, this is so we can easily
  18. * convert between them. dnotify only needs conversion at watch creation
  19. * so no perf loss there. fanotify isn't defined yet, so it can use the
  20. * wholes if it needs more events.
  21. */
  22. #define FS_ACCESS 0x00000001 /* File was accessed */
  23. #define FS_MODIFY 0x00000002 /* File was modified */
  24. #define FS_ATTRIB 0x00000004 /* Metadata changed */
  25. #define FS_CLOSE_WRITE 0x00000008 /* Writtable file was closed */
  26. #define FS_CLOSE_NOWRITE 0x00000010 /* Unwrittable file closed */
  27. #define FS_OPEN 0x00000020 /* File was opened */
  28. #define FS_MOVED_FROM 0x00000040 /* File was moved from X */
  29. #define FS_MOVED_TO 0x00000080 /* File was moved to Y */
  30. #define FS_CREATE 0x00000100 /* Subfile was created */
  31. #define FS_DELETE 0x00000200 /* Subfile was deleted */
  32. #define FS_DELETE_SELF 0x00000400 /* Self was deleted */
  33. #define FS_MOVE_SELF 0x00000800 /* Self was moved */
  34. #define FS_UNMOUNT 0x00002000 /* inode on umount fs */
  35. #define FS_Q_OVERFLOW 0x00004000 /* Event queued overflowed */
  36. #define FS_IN_IGNORED 0x00008000 /* last inotify event here */
  37. #define FS_OPEN_PERM 0x00010000 /* open event in an permission hook */
  38. #define FS_ACCESS_PERM 0x00020000 /* access event in a permissions hook */
  39. #define FS_EXCL_UNLINK 0x04000000 /* do not send events if object is unlinked */
  40. #define FS_IN_ISDIR 0x40000000 /* event occurred against dir */
  41. #define FS_IN_ONESHOT 0x80000000 /* only send event once */
  42. #define FS_DN_RENAME 0x10000000 /* file renamed */
  43. #define FS_DN_MULTISHOT 0x20000000 /* dnotify multishot */
  44. /* This inode cares about things that happen to its children. Always set for
  45. * dnotify and inotify. */
  46. #define FS_EVENT_ON_CHILD 0x08000000
  47. /* This is a list of all events that may get sent to a parernt based on fs event
  48. * happening to inodes inside that directory */
  49. #define FS_EVENTS_POSS_ON_CHILD (FS_ACCESS | FS_MODIFY | FS_ATTRIB |\
  50. FS_CLOSE_WRITE | FS_CLOSE_NOWRITE | FS_OPEN |\
  51. FS_MOVED_FROM | FS_MOVED_TO | FS_CREATE |\
  52. FS_DELETE)
  53. #define FS_MOVE (FS_MOVED_FROM | FS_MOVED_TO)
  54. #define ALL_FSNOTIFY_EVENTS (FS_ACCESS | FS_MODIFY | FS_ATTRIB | \
  55. FS_CLOSE_WRITE | FS_CLOSE_NOWRITE | FS_OPEN | \
  56. FS_MOVED_FROM | FS_MOVED_TO | FS_CREATE | \
  57. FS_DELETE | FS_DELETE_SELF | FS_MOVE_SELF | \
  58. FS_UNMOUNT | FS_Q_OVERFLOW | FS_IN_IGNORED | \
  59. FS_OPEN_PERM | FS_ACCESS_PERM | FS_EXCL_UNLINK | \
  60. FS_IN_ISDIR | FS_IN_ONESHOT | FS_DN_RENAME | \
  61. FS_DN_MULTISHOT | FS_EVENT_ON_CHILD)
  62. struct fsnotify_group;
  63. struct fsnotify_event;
  64. struct fsnotify_mark;
  65. struct fsnotify_event_private_data;
  66. /*
  67. * Each group much define these ops. The fsnotify infrastructure will call
  68. * these operations for each relevant group.
  69. *
  70. * should_send_event - given a group, inode, and mask this function determines
  71. * if the group is interested in this event.
  72. * handle_event - main call for a group to handle an fs event
  73. * free_group_priv - called when a group refcnt hits 0 to clean up the private union
  74. * freeing-mark - this means that a mark has been flagged to die when everything
  75. * finishes using it. The function is supplied with what must be a
  76. * valid group and inode to use to clean up.
  77. */
  78. struct fsnotify_ops {
  79. bool (*should_send_event)(struct fsnotify_group *group, struct inode *inode,
  80. struct vfsmount *mnt, struct fsnotify_mark *inode_mark,
  81. struct fsnotify_mark *vfsmount_mark,
  82. __u32 mask, void *data, int data_type);
  83. int (*handle_event)(struct fsnotify_group *group,
  84. struct fsnotify_mark *inode_mark,
  85. struct fsnotify_mark *vfsmount_mark,
  86. struct fsnotify_event *event);
  87. void (*free_group_priv)(struct fsnotify_group *group);
  88. void (*freeing_mark)(struct fsnotify_mark *mark, struct fsnotify_group *group);
  89. void (*free_event_priv)(struct fsnotify_event_private_data *priv);
  90. };
  91. /*
  92. * A group is a "thing" that wants to receive notification about filesystem
  93. * events. The mask holds the subset of event types this group cares about.
  94. * refcnt on a group is up to the implementor and at any moment if it goes 0
  95. * everything will be cleaned up.
  96. */
  97. struct fsnotify_group {
  98. /*
  99. * How the refcnt is used is up to each group. When the refcnt hits 0
  100. * fsnotify will clean up all of the resources associated with this group.
  101. * As an example, the dnotify group will always have a refcnt=1 and that
  102. * will never change. Inotify, on the other hand, has a group per
  103. * inotify_init() and the refcnt will hit 0 only when that fd has been
  104. * closed.
  105. */
  106. atomic_t refcnt; /* things with interest in this group */
  107. const struct fsnotify_ops *ops; /* how this group handles things */
  108. /* needed to send notification to userspace */
  109. struct mutex notification_mutex; /* protect the notification_list */
  110. struct list_head notification_list; /* list of event_holder this group needs to send to userspace */
  111. wait_queue_head_t notification_waitq; /* read() on the notification file blocks on this waitq */
  112. unsigned int q_len; /* events on the queue */
  113. unsigned int max_events; /* maximum events allowed on the list */
  114. /* stores all fastpath marks assoc with this group so they can be cleaned on unregister */
  115. spinlock_t mark_lock; /* protect marks_list */
  116. atomic_t num_marks; /* 1 for each mark and 1 for not being
  117. * past the point of no return when freeing
  118. * a group */
  119. struct list_head marks_list; /* all inode marks for this group */
  120. /* groups can define private fields here or use the void *private */
  121. union {
  122. void *private;
  123. #ifdef CONFIG_INOTIFY_USER
  124. struct inotify_group_private_data {
  125. spinlock_t idr_lock;
  126. struct idr idr;
  127. u32 last_wd;
  128. struct fasync_struct *fa; /* async notification */
  129. struct user_struct *user;
  130. } inotify_data;
  131. #endif
  132. #ifdef CONFIG_FANOTIFY
  133. struct fanotify_group_private_data {
  134. #ifdef CONFIG_FANOTIFY_ACCESS_PERMISSIONS
  135. /* allows a group to block waiting for a userspace response */
  136. struct mutex access_mutex;
  137. struct list_head access_list;
  138. wait_queue_head_t access_waitq;
  139. #endif /* CONFIG_FANOTIFY_ACCESS_PERMISSIONS */
  140. int f_flags;
  141. } fanotify_data;
  142. #endif /* CONFIG_FANOTIFY */
  143. };
  144. };
  145. /*
  146. * A single event can be queued in multiple group->notification_lists.
  147. *
  148. * each group->notification_list will point to an event_holder which in turns points
  149. * to the actual event that needs to be sent to userspace.
  150. *
  151. * Seemed cheaper to create a refcnt'd event and a small holder for every group
  152. * than create a different event for every group
  153. *
  154. */
  155. struct fsnotify_event_holder {
  156. struct fsnotify_event *event;
  157. struct list_head event_list;
  158. };
  159. /*
  160. * Inotify needs to tack data onto an event. This struct lets us later find the
  161. * correct private data of the correct group.
  162. */
  163. struct fsnotify_event_private_data {
  164. struct fsnotify_group *group;
  165. struct list_head event_list;
  166. };
  167. /*
  168. * all of the information about the original object we want to now send to
  169. * a group. If you want to carry more info from the accessing task to the
  170. * listener this structure is where you need to be adding fields.
  171. */
  172. struct fsnotify_event {
  173. /*
  174. * If we create an event we are also likely going to need a holder
  175. * to link to a group. So embed one holder in the event. Means only
  176. * one allocation for the common case where we only have one group
  177. */
  178. struct fsnotify_event_holder holder;
  179. spinlock_t lock; /* protection for the associated event_holder and private_list */
  180. /* to_tell may ONLY be dereferenced during handle_event(). */
  181. struct inode *to_tell; /* either the inode the event happened to or its parent */
  182. /*
  183. * depending on the event type we should have either a file or inode
  184. * We hold a reference on file, but NOT on inode. Since we have the ref on
  185. * the file, it may be dereferenced at any point during this object's
  186. * lifetime. That reference is dropped when this object's refcnt hits
  187. * 0. If this event contains an inode instead of a file, the inode may
  188. * ONLY be used during handle_event().
  189. */
  190. union {
  191. struct file *file;
  192. struct inode *inode;
  193. };
  194. /* when calling fsnotify tell it if the data is a path or inode */
  195. #define FSNOTIFY_EVENT_NONE 0
  196. #define FSNOTIFY_EVENT_FILE 1
  197. #define FSNOTIFY_EVENT_INODE 2
  198. int data_type; /* which of the above union we have */
  199. atomic_t refcnt; /* how many groups still are using/need to send this event */
  200. __u32 mask; /* the type of access, bitwise OR for FS_* event types */
  201. u32 sync_cookie; /* used to corrolate events, namely inotify mv events */
  202. const unsigned char *file_name;
  203. size_t name_len;
  204. struct pid *tgid;
  205. #ifdef CONFIG_FANOTIFY_ACCESS_PERMISSIONS
  206. __u32 response; /* userspace answer to question */
  207. #endif /* CONFIG_FANOTIFY_ACCESS_PERMISSIONS */
  208. struct list_head private_data_list; /* groups can store private data here */
  209. };
  210. /*
  211. * Inode specific fields in an fsnotify_mark
  212. */
  213. struct fsnotify_inode_mark {
  214. struct inode *inode; /* inode this mark is associated with */
  215. struct hlist_node i_list; /* list of marks by inode->i_fsnotify_marks */
  216. struct list_head free_i_list; /* tmp list used when freeing this mark */
  217. };
  218. /*
  219. * Mount point specific fields in an fsnotify_mark
  220. */
  221. struct fsnotify_vfsmount_mark {
  222. struct vfsmount *mnt; /* vfsmount this mark is associated with */
  223. struct hlist_node m_list; /* list of marks by inode->i_fsnotify_marks */
  224. struct list_head free_m_list; /* tmp list used when freeing this mark */
  225. };
  226. /*
  227. * a mark is simply an object attached to an in core inode which allows an
  228. * fsnotify listener to indicate they are either no longer interested in events
  229. * of a type matching mask or only interested in those events.
  230. *
  231. * these are flushed when an inode is evicted from core and may be flushed
  232. * when the inode is modified (as seen by fsnotify_access). Some fsnotify users
  233. * (such as dnotify) will flush these when the open fd is closed and not at
  234. * inode eviction or modification.
  235. */
  236. struct fsnotify_mark {
  237. __u32 mask; /* mask this mark is for */
  238. /* we hold ref for each i_list and g_list. also one ref for each 'thing'
  239. * in kernel that found and may be using this mark. */
  240. atomic_t refcnt; /* active things looking at this mark */
  241. struct fsnotify_group *group; /* group this mark is for */
  242. struct list_head g_list; /* list of marks by group->i_fsnotify_marks */
  243. spinlock_t lock; /* protect group and inode */
  244. union {
  245. struct fsnotify_inode_mark i;
  246. struct fsnotify_vfsmount_mark m;
  247. };
  248. __u32 ignored_mask; /* events types to ignore */
  249. struct list_head free_g_list; /* tmp list used when freeing this mark */
  250. #define FSNOTIFY_MARK_FLAG_INODE 0x01
  251. #define FSNOTIFY_MARK_FLAG_VFSMOUNT 0x02
  252. #define FSNOTIFY_MARK_FLAG_OBJECT_PINNED 0x04
  253. #define FSNOTIFY_MARK_FLAG_IGNORED_SURV_MODIFY 0x08
  254. #define FSNOTIFY_MARK_FLAG_ALIVE 0x10
  255. unsigned int flags; /* vfsmount or inode mark? */
  256. struct list_head destroy_list;
  257. void (*free_mark)(struct fsnotify_mark *mark); /* called on final put+free */
  258. };
  259. #ifdef CONFIG_FSNOTIFY
  260. /* called from the vfs helpers */
  261. /* main fsnotify call to send events */
  262. extern int fsnotify(struct inode *to_tell, __u32 mask, void *data, int data_is,
  263. const unsigned char *name, u32 cookie);
  264. extern void __fsnotify_parent(struct file *file, struct dentry *dentry, __u32 mask);
  265. extern void __fsnotify_inode_delete(struct inode *inode);
  266. extern void __fsnotify_vfsmount_delete(struct vfsmount *mnt);
  267. extern u32 fsnotify_get_cookie(void);
  268. static inline int fsnotify_inode_watches_children(struct inode *inode)
  269. {
  270. /* FS_EVENT_ON_CHILD is set if the inode may care */
  271. if (!(inode->i_fsnotify_mask & FS_EVENT_ON_CHILD))
  272. return 0;
  273. /* this inode might care about child events, does it care about the
  274. * specific set of events that can happen on a child? */
  275. return inode->i_fsnotify_mask & FS_EVENTS_POSS_ON_CHILD;
  276. }
  277. /*
  278. * Update the dentry with a flag indicating the interest of its parent to receive
  279. * filesystem events when those events happens to this dentry->d_inode.
  280. */
  281. static inline void __fsnotify_update_dcache_flags(struct dentry *dentry)
  282. {
  283. struct dentry *parent;
  284. assert_spin_locked(&dcache_lock);
  285. assert_spin_locked(&dentry->d_lock);
  286. parent = dentry->d_parent;
  287. if (parent->d_inode && fsnotify_inode_watches_children(parent->d_inode))
  288. dentry->d_flags |= DCACHE_FSNOTIFY_PARENT_WATCHED;
  289. else
  290. dentry->d_flags &= ~DCACHE_FSNOTIFY_PARENT_WATCHED;
  291. }
  292. /*
  293. * fsnotify_d_instantiate - instantiate a dentry for inode
  294. * Called with dcache_lock held.
  295. */
  296. static inline void __fsnotify_d_instantiate(struct dentry *dentry, struct inode *inode)
  297. {
  298. if (!inode)
  299. return;
  300. assert_spin_locked(&dcache_lock);
  301. spin_lock(&dentry->d_lock);
  302. __fsnotify_update_dcache_flags(dentry);
  303. spin_unlock(&dentry->d_lock);
  304. }
  305. /* called from fsnotify listeners, such as fanotify or dnotify */
  306. /* get a reference to an existing or create a new group */
  307. extern struct fsnotify_group *fsnotify_alloc_group(const struct fsnotify_ops *ops);
  308. /* drop reference on a group from fsnotify_alloc_group */
  309. extern void fsnotify_put_group(struct fsnotify_group *group);
  310. /* take a reference to an event */
  311. extern void fsnotify_get_event(struct fsnotify_event *event);
  312. extern void fsnotify_put_event(struct fsnotify_event *event);
  313. /* find private data previously attached to an event and unlink it */
  314. extern struct fsnotify_event_private_data *fsnotify_remove_priv_from_event(struct fsnotify_group *group,
  315. struct fsnotify_event *event);
  316. /* attach the event to the group notification queue */
  317. extern struct fsnotify_event *fsnotify_add_notify_event(struct fsnotify_group *group,
  318. struct fsnotify_event *event,
  319. struct fsnotify_event_private_data *priv,
  320. struct fsnotify_event *(*merge)(struct list_head *,
  321. struct fsnotify_event *));
  322. /* true if the group notification queue is empty */
  323. extern bool fsnotify_notify_queue_is_empty(struct fsnotify_group *group);
  324. /* return, but do not dequeue the first event on the notification queue */
  325. extern struct fsnotify_event *fsnotify_peek_notify_event(struct fsnotify_group *group);
  326. /* return AND dequeue the first event on the notification queue */
  327. extern struct fsnotify_event *fsnotify_remove_notify_event(struct fsnotify_group *group);
  328. /* functions used to manipulate the marks attached to inodes */
  329. /* run all marks associated with a vfsmount and update mnt->mnt_fsnotify_mask */
  330. extern void fsnotify_recalc_vfsmount_mask(struct vfsmount *mnt);
  331. /* run all marks associated with an inode and update inode->i_fsnotify_mask */
  332. extern void fsnotify_recalc_inode_mask(struct inode *inode);
  333. extern void fsnotify_init_mark(struct fsnotify_mark *mark, void (*free_mark)(struct fsnotify_mark *mark));
  334. /* find (and take a reference) to a mark associated with group and inode */
  335. extern struct fsnotify_mark *fsnotify_find_inode_mark(struct fsnotify_group *group, struct inode *inode);
  336. /* find (and take a reference) to a mark associated with group and vfsmount */
  337. extern struct fsnotify_mark *fsnotify_find_vfsmount_mark(struct fsnotify_group *group, struct vfsmount *mnt);
  338. /* copy the values from old into new */
  339. extern void fsnotify_duplicate_mark(struct fsnotify_mark *new, struct fsnotify_mark *old);
  340. /* set the ignored_mask of a mark */
  341. extern void fsnotify_set_mark_ignored_mask_locked(struct fsnotify_mark *mark, __u32 mask);
  342. /* set the mask of a mark (might pin the object into memory */
  343. extern void fsnotify_set_mark_mask_locked(struct fsnotify_mark *mark, __u32 mask);
  344. /* attach the mark to both the group and the inode */
  345. extern int fsnotify_add_mark(struct fsnotify_mark *mark, struct fsnotify_group *group,
  346. struct inode *inode, struct vfsmount *mnt, int allow_dups);
  347. /* given a mark, flag it to be freed when all references are dropped */
  348. extern void fsnotify_destroy_mark(struct fsnotify_mark *mark);
  349. /* run all the marks in a group, and clear all of the vfsmount marks */
  350. extern void fsnotify_clear_vfsmount_marks_by_group(struct fsnotify_group *group);
  351. /* run all the marks in a group, and clear all of the inode marks */
  352. extern void fsnotify_clear_inode_marks_by_group(struct fsnotify_group *group);
  353. /* run all the marks in a group, and clear all of the marks where mark->flags & flags is true*/
  354. extern void fsnotify_clear_marks_by_group_flags(struct fsnotify_group *group, unsigned int flags);
  355. /* run all the marks in a group, and flag them to be freed */
  356. extern void fsnotify_clear_marks_by_group(struct fsnotify_group *group);
  357. extern void fsnotify_get_mark(struct fsnotify_mark *mark);
  358. extern void fsnotify_put_mark(struct fsnotify_mark *mark);
  359. extern void fsnotify_unmount_inodes(struct list_head *list);
  360. /* put here because inotify does some weird stuff when destroying watches */
  361. extern struct fsnotify_event *fsnotify_create_event(struct inode *to_tell, __u32 mask,
  362. void *data, int data_is,
  363. const unsigned char *name,
  364. u32 cookie, gfp_t gfp);
  365. /* fanotify likes to change events after they are on lists... */
  366. extern struct fsnotify_event *fsnotify_clone_event(struct fsnotify_event *old_event);
  367. extern int fsnotify_replace_event(struct fsnotify_event_holder *old_holder,
  368. struct fsnotify_event *new_event);
  369. #else
  370. static inline int fsnotify(struct inode *to_tell, __u32 mask, void *data, int data_is,
  371. const unsigned char *name, u32 cookie)
  372. {
  373. return 0;
  374. }
  375. static inline void __fsnotify_parent(struct file *file, struct dentry *dentry, __u32 mask)
  376. {}
  377. static inline void __fsnotify_inode_delete(struct inode *inode)
  378. {}
  379. static inline void __fsnotify_vfsmount_delete(struct vfsmount *mnt)
  380. {}
  381. static inline void __fsnotify_update_dcache_flags(struct dentry *dentry)
  382. {}
  383. static inline void __fsnotify_d_instantiate(struct dentry *dentry, struct inode *inode)
  384. {}
  385. static inline u32 fsnotify_get_cookie(void)
  386. {
  387. return 0;
  388. }
  389. static inline void fsnotify_unmount_inodes(struct list_head *list)
  390. {}
  391. #endif /* CONFIG_FSNOTIFY */
  392. #endif /* __KERNEL __ */
  393. #endif /* __LINUX_FSNOTIFY_BACKEND_H */