inotify kernel api
Subsystems (5)
RFC PATCH 1/1 inotify kernel api
The following patch against 2.6.17-rc1-mm1 introduces a kernel API for inotify.
I'm interested in an inotify kernel API because I would like to be able to update audit rules based on certain filesystem events. I can imagine it being useful to other kernel modules as well.
To provide the kernel API, I split the current inotify functionality into two
parts: core functionality (remains in inotify.c) and functionality supporting userspace (moved to inotify_user.c). This involved pulling core parts out of the inotify_device into a new inotify_handle.
While writing this patch, I attempted to minimize the impact to existing inotify users by retaining similar memory usage for inotify_watches. I also tried to keep the code paths for inotify operations relatively similar.
This patch does increase watch memory usage by one pointer, as the watch must now reference both the inotify_handle and the inotify_device.
Event processing is unchanged except for the indirection added for the callback. In inotify_user.c, an additional per-device mutex is held while adding watches to prevent adding the same watch twice. The design retains the original assumption that there will be more watches per inotify_handle than watches on any given inode, and performs the search for existing watches accordingly.
This patch makes the inotify_watch public so it can be embedded in callers' own watch structures, which avoids the use of a void ptr to caller data. Even though inotify_watch is public, callers must use the established interfaces to access inotify_watch contents. Was this the best choice?
I think the locking may be less than ideal, as the inode->inotify_mutex must be held to traverse the inode's watchlist, and thus must be held during the callback. The result is that the caller can't hold any locks taken during callback processing while calling any of the published inotify interfaces, making synchronization a little more difficult.
I would appreciate feedback on this approach. Does it seem sane and generally useful?
Thanks,
Amy
fs/Kconfig | 24 - fs/Makefile | 1 fs/inotify.c | 966 ++++++++++++----------------------------------- fs/inotify_user.c | 708 ++++++++++++++++++++++++++++++++++ include/linux/fsnotify.h | 29 - include/linux/inotify.h | 85 +++- include/linux/sched.h | 2 kernel/sysctl.c | 4 kernel/user.c | 2 9 files changed, 1094 insertions(+), 727 deletions(-)
fs/Kconfig +18 -6
@@ -395,18 +395,30 @@ config INOTIFY bool "Inotify file change notification support" default y ---help--- - Say Y here to enable inotify support and the associated system - calls. Inotify is a file change notification system and a - replacement for dnotify. Inotify fixes numerous shortcomings in - dnotify and introduces several new features. It allows monitoring - of both files and directories via a single open fd. Other features - include multiple file events, one-shot support, and unmount + Say Y here to enable inotify support. Inotify is a file change + notification system and a replacement for dnotify. Inotify fixes + numerous shortcomings in dnotify and introduces several new features + including multiple file events, one-shot support, and unmount notification. For more information, see Documentation/filesystems/inotify.txt If unsure, say Y. +config INOTIFY_USER + bool "Inotify support for userspace" + depends on INOTIFY + default y + ---help--- + Say Y here to enable inotify support for userspace, including the + associated system calls. Inotify allows monitoring of both files and + directories via a single open fd. Events are read from the file + descriptor, which is also select()- and poll()-able. + + For more information, see Documentation/filesystems/inotify.txt + + If unsure, say Y. + config QUOTA bool "Quota support" help
fs/Makefile +1 -0
@@ -13,6 +13,7 @@ obj-y := open.o read_write.o file_table. ioprio.o pnode.o drop_caches.o splice.o sync.o obj-$(CONFIG_INOTIFY) += inotify.o +obj-$(CONFIG_INOTIFY_USER) += inotify_user.o obj-$(CONFIG_EPOLL) += eventpoll.o obj-$(CONFIG_COMPAT) += compat.o compat_ioctl.o
fs/inotify.c +265 -701
1,199 lines not on this page · raw message
fs/inotify_user.c new file +708 -0
708 lines not on this page · raw message
include/linux/fsnotify.h +16 -13
@@ -54,16 +54,18 @@ static inline void fsnotify_move(structif (isdir) isdir =IN_ISDIR ; -inotify_inode_queue_event (old_dir,IN_MOVED_FROM |isdir,cookie,old_name); -inotify_inode_queue_event (new_dir,IN_MOVED_TO |isdir, cookie, new_name); +inotify_inode_queue_event (old_dir,IN_MOVED_FROM |isdir,cookie,old_name, + source); +inotify_inode_queue_event (new_dir,IN_MOVED_TO |isdir, cookie, new_name, + source);if (target) { -inotify_inode_queue_event (target,IN_DELETE_SELF ,0 ,NULL ); +inotify_inode_queue_event (target,IN_DELETE_SELF ,0 ,NULL ,NULL );inotify_inode_is_dead (target); }if (source) { -inotify_inode_queue_event (source,IN_MOVE_SELF ,0 ,NULL ); +inotify_inode_queue_event (source,IN_MOVE_SELF ,0 ,NULL ,NULL ); }audit_inode_child (old_name, source, old_dir->i_ino);audit_inode_child (new_name, target, new_dir->i_ino);
@@ -85,7 +87,7 @@ static inline void fsnotify_nameremove(s*/ static inline void fsnotify_inoderemove (struct inode *inode) { -inotify_inode_queue_event (inode,IN_DELETE_SELF ,0 ,NULL ); +inotify_inode_queue_event (inode,IN_DELETE_SELF ,0 ,NULL ,NULL );inotify_inode_is_dead (inode); }
@@ -95,7 +97,8 @@ static inline void fsnotify_inoderemove(static inline void fsnotify_create (struct inode *inode,struct dentry *dentry) {inode_dir_notify (inode,DN_CREATE ); -inotify_inode_queue_event (inode,IN_CREATE ,0 , dentry->d_name.name); +inotify_inode_queue_event (inode,IN_CREATE ,0 , dentry->d_name.name, + dentry->d_inode);audit_inode_child (dentry->d_name.name, dentry->d_inode, inode->i_ino); }
@@ -106,7 +109,7 @@ static inline void fsnotify_mkdir(struct {inode_dir_notify (inode,DN_CREATE );inotify_inode_queue_event (inode,IN_CREATE |IN_ISDIR ,0 , - dentry->d_name.name); + dentry->d_name.name, dentry->d_inode);audit_inode_child (dentry->d_name.name, dentry->d_inode, inode->i_ino); }
@@ -123,7 +126,7 @@ static inline void fsnotify_access(strucdnotify_parent (dentry,DN_ACCESS );inotify_dentry_parent_queue_event (dentry, mask,0 , dentry->d_name.name); -inotify_inode_queue_event (inode, mask,0 ,NULL ); +inotify_inode_queue_event (inode, mask,0 ,NULL ,NULL ); }/*
@@ -139,7 +142,7 @@ static inline void fsnotify_modify(strucdnotify_parent (dentry,DN_MODIFY );inotify_dentry_parent_queue_event (dentry, mask,0 , dentry->d_name.name); -inotify_inode_queue_event (inode, mask,0 ,NULL ); +inotify_inode_queue_event (inode, mask,0 ,NULL ,NULL ); }/*
@@ -154,7 +157,7 @@ static inline void fsnotify_open(struct mask |=IN_ISDIR ;inotify_dentry_parent_queue_event (dentry, mask,0 , dentry->d_name.name); -inotify_inode_queue_event (inode, mask,0 ,NULL ); +inotify_inode_queue_event (inode, mask,0 ,NULL ,NULL ); }/*
@@ -172,7 +175,7 @@ static inline void fsnotify_close(struct mask |=IN_ISDIR ;inotify_dentry_parent_queue_event (dentry, mask,0 , name); -inotify_inode_queue_event (inode, mask,0 ,NULL ); +inotify_inode_queue_event (inode, mask,0 ,NULL ,NULL ); }/*
@@ -187,7 +190,7 @@ static inline void fsnotify_xattr(struct mask |=IN_ISDIR ;inotify_dentry_parent_queue_event (dentry, mask,0 , dentry->d_name.name); -inotify_inode_queue_event (inode, mask,0 ,NULL ); +inotify_inode_queue_event (inode, mask,0 ,NULL ,NULL ); }/*
@@ -234,7 +237,7 @@ static inline void fsnotify_change(strucif (in_mask) {if (S_ISDIR (inode->i_mode)) in_mask |=IN_ISDIR ; -inotify_inode_queue_event (inode, in_mask,0 ,NULL ); +inotify_inode_queue_event (inode, in_mask,0 ,NULL ,NULL );inotify_dentry_parent_queue_event (dentry, in_mask,0 , dentry->d_name.name); }
include/linux/inotify.h +82 -3
120 lines not on this page · raw message
include/linux/sched.h +1 -1
@@ -499,7 +499,7 @@ struct user_struct {atomic_t processes;/* How many processes does this user have? */ atomic_t files;/* How many open files does this user have? */ atomic_t sigpending;/* How many pending signals does this user have? */ -#ifdef CONFIG_INOTIFY +#ifdef CONFIG_INOTIFY_USER atomic_t inotify_watches;/* How many inotify watches does this user have? */ atomic_t inotify_devs;/* How many inotify devs does this user have opened? */ #endif
kernel/sysctl.c +2 -2
@@ -155,7 +155,7 @@ extern ctl_table random_table[];#ifdef CONFIG_UNIX98_PTYS extern ctl_table pty_table[];#endif -#ifdef CONFIG_INOTIFY +#ifdef CONFIG_INOTIFY_USER extern ctl_table inotify_table[];#endif
@@ -1054,7 +1054,7 @@ static ctl_table fs_table[] = { .mode = 0644, .proc_handler = &proc_doulongvec_minmax, }, -#ifdef CONFIG_INOTIFY +#ifdef CONFIG_INOTIFY_USER { .ctl_name = FS_INOTIFY, .procname = "inotify",
kernel/user.c +1 -1
@@ -140,7 +140,7 @@ struct user_struct * alloc_uid(uid_t uidatomic_set (&new->processes,0 );atomic_set (&new->files,0 );atomic_set (&new->sigpending,0 ); -#ifdef CONFIG_INOTIFY +#ifdef CONFIG_INOTIFY_USER atomic_set (&new->inotify_watches,0 );atomic_set (&new->inotify_devs,0 );#endif
Quoted 2 lines · Amy Griffis
The following patch against 2.6.17-rc1-mm1 introduces a kernel API for inotify.
I realized that my first email assumed quite a bit of knowledge about inotify. Here is a description of the interface I'm proposing.
Each inotify instance is represented by an inotify_handle structure. For the inotify consumer supplying support to userspace, each inotify_device has an associated inotify_handle.
Each inotify watch is represented by an inotify_watch structure. Watches are chained off of each associated inode and inotify_handle.
Using the Inotify Kernel Interface
----------------------------------
First you must initialize an inotify instance.
struct inotify_handle *ih = inotify_init(my_event_handler);
You are given an opaque inotify_handle, which you use for any further calls to inotify. You provide a function to be called to process events on your registered watches.
void my_event_handle(struct inotify_watch *iwatch, u32 wd, u32 mask,
u32 cookie, const char *name, struct inode *inode)
iwatch - the pointer to the inotify_watch that triggered this call wd - the watch descriptor
mask - describes the event that occurred
cookie - an identifier for synchronizing events
name - the dentry name for affected files in a directory-based event inode - the affected inode in a directory-based event
You may add watches by providing a pre-allocated inotify_watch structure and specifying the inode to watch along with an inotify event mask. You must pin the inode during the call. You will likely wish to embed the inotify_watch structure in a structure of your own which contains other information about the watch.
s32 wd = inotify_add_watch(ih, &my_watch->iwatch, inode, mask);
You may use the watch descriptor (wd) or the address of the inotify_watch for other inotify operations. You must not directly read or manipulate data in the inotify_watch. Additionally, you must not call inotify_add_watch() more than once for a given inotify_watch structure, unless you have first called either inotify_rm_watch() or inotify_rm_wd().
To determine if you have already registered a watch for a given inode, you may call inotify_find_watch(), which gives you both the wd and the watch pointer for the inotify_watch, or an error if the watch does not exist.
wd = inotify_find_watch(ih, inode, &watchp);
You may use container_of() on the watch pointer to access your own data associated with a given watch.
Call inotify_find_update_watch() to update the event mask for an existing watch. inotify_find_update_watch() returns the wd of the updated watch, or an error if the watch does not exist.
wd = inotify_find_update_watch(ih, inode, mask);
An existing watch may be removed by calling either inotify_rm_watch() or inotify_rm_wd().
int ret = inotify_rm_watch(ih, &my_watch->iwatch);
int ret = inotify_rm_wd(ih, wd);Call inotify_destroy() to remove all watches from your inotify instance and release it.
inotify_destroy(ih);
When inotify removes a watch, it sends an IN_IGNORED event to your callback. You may use this event as an indication to free the watch memory. Note that inotify may remove a watch due to filesystem events, as well as by your request.
Function Prototypes
-------------------
struct inotify_handle *inotify_init(void (*cb)(struct inotify_watch *,
u32, u32, u32, const char *, struct inode *))
s32 inotify_add_watch(struct inotify_handle *ih, struct inotify_watch *watch,
struct inode *inode, u32 mask)
s32 inotify_find_watch(struct inotify_handle *ih, struct inode *inode,
struct inotify_watch **watchp)
s32 inotify_find_update_watch(struct inotify_handle *ih, struct inode *inode,
u32 mask)
int inotify_rm_wd(struct inotify_handle *ih, u32 wd)
int inotify_rm_watch(struct inotify_handle *ih, struct inotify_watch *watch)
void inotify_destroy(struct inotify_handle *ih)
Quoted 9 lines · Amy Griffis
The following patch against 2.6.17-rc1-mm1 introduces a kernel API for inotify.
Event processing is unchanged except for the indirection added for the callback. In
inotify_user.c, an additional per-device mutex is held while adding watches to prevent adding the same watch twice. The design retains the original assumption that there will be more watches perinotify_handlethan watches on any given inode, and performs the search for existing watches accordingly.
Why do we need the 'up_mutex' mutex? Was this a bug in the old code?
Quoted 6 lines
This patch makes the
inotify_watchpublic so it can be embedded in callers' own watch structures, which avoids the use of a void ptr to caller data. Even thoughinotify_watchis public, callers must use the established interfaces to accessinotify_watchcontents. Was this the best choice?
I suppose this is an alright change. As long as it is understood that there is no guarantee about the layout of the inotify_watch structure. A comment in inotify.h should do.
Quoted 7 lines
I think the locking may be less than ideal, as the
inode->inotify_mutexmust be held to traverse the inode's watchlist, and thus must be held during the callback. The result is that the caller can't hold any locks taken during callback processing while calling any of the published inotify interfaces, making synchronization a little more difficult.
Well, I think it's up for the kernel consumers to decide whether or not this is acceptable. It's probably a good idea to come up with some use cases for the kernel API and see if this _is_ a problem. Since the callbacks will be run inside the VFS ops, they need to be small and fast, so they probably should just be putting the event on a list and handling it later.
Looking over the patch, nothing jumps out at me as being wrong. But some stress testing would convince me faster than my eyes can.
Signature · 1 line
John McCutchan <[email protected]>
A message that is not in the archive (sent off-list or not yet received): [email protected]
John McCutchan wrote: [Mon Apr 10 2006, 02:36:28PM EDT]
Quoted 11 lines · Amy Griffis
Quoted 9 lines
The following patch against 2.6.17-rc1-mm1 introduces a kernel API for inotify.
Event processing is unchanged except for the indirection added for the callback. In
inotify_user.c, an additional per-device mutex is held while adding watches to prevent adding the same watch twice. The design retains the original assumption that there will be more watches perinotify_handlethan watches on any given inode, and performs the search for existing watches accordingly.
Quoted 1 line
Why do we need the '
up_mutex' mutex? Was this a bug in the old code?
The up_mutex is needed to ensure that a watch that does not exist when calling inotify_find_update_watch() still does not exist when calling inotify_add_watch(). It seemed to me that the find/update and add functions needed to be separated for the kernel api.
Unfortunately we can't use dev->ev_mutex here as it's taken during the callback.
Quoted 10 lines
Quoted 6 lines
This patch makes the
inotify_watchpublic so it can be embedded in callers' own watch structures, which avoids the use of a void ptr to caller data. Even thoughinotify_watchis public, callers must use the established interfaces to accessinotify_watchcontents. Was this the best choice?I suppose this is an alright change. As long as it is understood that there is no guarantee about the layout of the
inotify_watchstructure. A comment ininotify.hshould do.
Done.
* Callers must use the established inotify interfaces to access inotify_watch
* contents. The content of this structure is private to the inotify
* implementation.
Quoted 15 lines
Quoted 7 lines
I think the locking may be less than ideal, as the
inode->inotify_mutexmust be held to traverse the inode's watchlist, and thus must be held during the callback. The result is that the caller can't hold any locks taken during callback processing while calling any of the published inotify interfaces, making synchronization a little more difficult.Well, I think it's up for the kernel consumers to decide whether or not this is acceptable. It's probably a good idea to come up with some use cases for the kernel API and see if this _is_ a problem. Since the callbacks will be run inside the VFS ops, they need to be small and fast, so they probably should just be putting the event on a list and handling it later.
Quoted 2 lines
Looking over the patch, nothing jumps out at me as being wrong. But some stress testing would convince me faster than my eyes can.
I'll follow up with some stress test results.
Thanks,
Amy