Stephan revised fanotify_init(2) after some comments from Eric. ---------- Forwarded message ---------- From: Stephan Mueller <stephan.mueller@xxxxxxxxx> Date: Thu, Oct 27, 2011 at 9:48 AM Subject: Re: fanotify_init(2) and fanotify_mark(2) man pages To: Eric Paris <eparis@xxxxxxxxxx> Cc: linux-man <linux-man@xxxxxxxxxxxxxxx> On 26.10.2011 16:46:52, -0400, Eric Paris <eparis@xxxxxxxxxx> wrote: Hi Eric, > On Mon, 2011-10-17 at 11:51 +0200, Stephan Mueller wrote: >> Hi, >> >> Though, there is one area which should warrant another review: the >> struct fanotify_response discussion, in particular I am not sure about >> the explanation of the fd member variable. > > File Descriptor Usage: [...] I tried to incorporate all of your suggestions. See man page attached. > > If I were to write an example program (or more likely trim my example > program, would that be appreciated here?) That would be a great inclusion to the man page. I think that the system call is quite complex and the description is still not obvious. Therefore, an example would be highly appreciated. > > -Eric > > -- Ciao Stephan -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Author of "The Linux Programming Interface"; http://man7.org/tlpi/
.\" Copyright (c) 2011, Stephan Mueller <smueller@xxxxxxxxx> .\" supported by Eric Paris <eparis@xxxxxxxxxx> who provided the .\" initial information at .\" http://marc.info/?l=linux-kernel&m=125701492503938 .\" .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" * Neither the name of the atsec information security corp. .\" nor the names of its contributors may be used to endorse or .\" promote products derived from this software without specific prior .\" written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY atsec information security corp. .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE <copyright-holder> .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT .\" OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH FANOTIFY_INIT 2 2011-09-15 "Linux" "Linux Programmer's Manual" .SH NAME fanotify_init \- initialize a fanotify group .SH SYNOPSIS .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags ");" .SH DESCRIPTION .BR fanotify_init () initializes a new fanotify instance and returns a file descriptor associated with the new fanotify event queue. The calling process must possess the .I CAP_SYS_ADMIN capability to invoke this system call. However, it is likely that this capability requirement will change in the future. Therefore, this system call implements additional capability checks as outlined below which will remain unchanged. .SH "FILE DESCRIPTOR USAGE" The .BR fanotify_init () system call returns a file descriptor that provides access to a .B fanotify group. When reading from that file descriptor the caller is returned all events the kernel collected for the .B fanotify group. When the file descriptor possesses the flag .I O_NONBLOCK the kernel will still return multiple events if they exist, but it will return .B EAGAIN if no events exist. .PP A .B fanotify group is a "thing" that wants to receive notification about filesystem events. .PP One .B fanotify events is defined by struct .IR fsnotify_event . This data structure specifies the precise information of the file system object for which the event occured. .PP In addition to reading from the .B fanotify file descriptor, the calling process may also write to the file descriptor. User space must write data using the following data structure: .in +4n .nf struct fanotify_response { __s32 fd; /* file descriptor */ __u32 response; /* response flags */ }; .fi .in .PP Writing to the file descriptor only makes sense in .I FAN_CLASS_CONTENT or .IR FAN_CLASS_PRE_CONTENT . In one of those classes a mark can be added which requires permissions handling. If upon reading the fanotify file descriptor an event for .I FAN_*_PERM is returned userspace should write back to the fanotify file descriptor using the data structure .B fanotify_response shown above. The .I fd file descriptor in the data structure should be the file descriptor supplied in the original event. Therefore, the .I fd file descriptor identifies a particular response stored for the .B fanotify group. The .I response flag allows user space to specify one of the following responses: .TP .B FAN_ALLOW Allow the operation. .TP .B FAN_DENY Deny the operation. .PP In addition, the following IOCTL can be invoked with the file descriptor: .TP .B FIONREAD This IOCTL returns number of events present in the event queue for the .B fanotify group. .SH "SYSTEM CALL ARGUMENTS" .PP The following values can be OR'd into the .I flags field: .PP .TP .B FAN_NONBLOCK Set the .I O_NONBLOCK file status flag on the new open file description. Using this flag saves extra calls to .BR fcntl (2) to achieve the same result. .TP .B FAN_CLOEXEC Set the close-on-exec ( .I FD_CLOEXEC ) flag on the new file descriptor. See the description of the .I O_CLOEXEC flag in .BR open (2) for reasons why this may be useful. .TP .B FAN_CLASS_NOTIF Using this priority level, .B fanotify groups may not use synchronous notification marks which means that they cannot make access decisions for users. .TP .B FAN_CLASS_CONTENT This priority level is intended for groups which which need access to the file contents to make access decisions. These could be things like anti virus scanners or integrity monitors. .TP .B FAN_CLASS_PRE_CONTENT This priority level is intended for groups which will place content into the given file before it is used. This priority level is indended for something like a hierarchical storage manager which needs to retrieve data from tape. .TP .B FAN_READONLY_FALLBACK Setting this flag will cause the kernel to try to open a file attached to an event read only if the .I event_f_flags indicated it should be opened read/write and that open failed. .TP .B FAN_UNLIMITED_QUEUE Set the size of the fanotify event queue to unlimited. This flag requires the caller to possess the .I CAP_SYS_ADMIN capability. .TP .B FAN_UNLIMITED_MARKS Set the number of the fanotify data mark maintained by the fanotify group to unlimited. This flag requires the caller to possess the .B CAP_SYS_ADMIN capability. .PP Note that only one of the .B FAN_CLASS_* priority levels shall be selected per group. If none is chosen, .B FAN_CLASS_NOTIF is used as default. .PP The .I event_f_flags takes any of the same options as the .I flags argument of the .BR open (2) system call. Those flags are used when opening a file descriptor which is supplied with the event. .SH "RETURN VALUE" On success, this system call return a new file descriptor. On error, -1 is returned, and errno is set to indicate the error. .SH ERRORS .TP .B EINVAL An invalid value was specified in the .I flags argument. .TB .B EINVAL An invalid invalid .B FAN_CLASS_* value was selected. .TP .B EINVAL .B FAN_READONLY_FALLBACK was set but the access mode to the file descriptor supplied in .I event_f_flags is not .IR O_RDWR . .TP .B EINVAL A non-zero valid was passed in the .I event_f_flags argument. .TP .B EMFILE The system limit on the total number of file descriptors has been reached. .TP .B ENOMEM Insufficient kernel memory is available. .TP .B EPERM The calling process does not possess the .I CAP_SYS_ADMIN capability. .SH "CONFORMING TO" These system calls are Linux-specific. .SH NOTES The system calls, the file handle data structure, as well as the file handle types are not yet exported via glibc or another library. The system calls must be invoked using the .BR syscall () function. .SH "SEE ALSO" .BR fanotify_mark (2), .BR open (2), .BR syscall (2)
