mirror of https://github.com/mkerrisk/man-pages
New pages for inotify API
This commit is contained in:
Michael Kerrisk
parent
314093c9cd
commit
4d2b74dded
|
|
@ -0,0 +1,112 @@
|
|||
.\" man2/inotify_add_watch.2 - inotify_add_watch man page
|
||||
.\"
|
||||
.\" Copyright (C) 2005 Robert Love, 2006 Michael Kerrisk
|
||||
.\"
|
||||
.\" This is free documentation; you can redistribute it and/or
|
||||
.\" modify it under the terms of the GNU General Public License as
|
||||
.\" published by the Free Software Foundation; either version 2 of
|
||||
.\" the License, or (at your option) any later version.
|
||||
.\"
|
||||
.\" The GNU General Public License's references to "object code"
|
||||
.\" and "executables" are to be interpreted as the output of any
|
||||
.\" document formatting or typesetting system, including
|
||||
.\" intermediate and printed output.
|
||||
.\"
|
||||
.\" This manual is distributed in the hope that it will be useful,
|
||||
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
.\" GNU General Public License for more details.
|
||||
.\"
|
||||
.\" You should have received a copy of the GNU General Public
|
||||
.\" License along with this manual; if not, write to the Free
|
||||
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
||||
.\" USA.
|
||||
.\"
|
||||
.\" 2005-07-19 Robert Love <rlove@rlove.org> - initial version
|
||||
.\" 2006-02-07 mtk, various changes
|
||||
.\"
|
||||
.TH INOTIFY_ADD_WATCH 2 2006-02-07 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
inotify_add_watch \- add a watch to an initialized inotify instance
|
||||
.SH SYNOPSIS
|
||||
.B #include <inotify.h>
|
||||
.sp
|
||||
.BI "int inotify_add_watch(int " fd ", const char *" path ", uint32_t " mask );
|
||||
.SH DESCRIPTION
|
||||
.BR inotify_add_watch ()
|
||||
adds a watch on the file at pathname
|
||||
.I path
|
||||
to the inotify instance mapped by the file descriptor
|
||||
.I fd
|
||||
with the event mask given by the bitmask
|
||||
.IR mask .
|
||||
See
|
||||
.BR inotify (7)
|
||||
for a description of the bits that can be set in
|
||||
.IR mask .
|
||||
|
||||
A successful call to
|
||||
.BR inotify_add_watch ()
|
||||
returns the unique watch descriptor associated with
|
||||
.I path
|
||||
for this inotify instance.
|
||||
If
|
||||
.I path
|
||||
was not previously being watched by this inotify instance,
|
||||
then this is new unique watch descriptor.
|
||||
If
|
||||
.I path
|
||||
was already being watched, then the descriptor
|
||||
for the existing watch is returned.
|
||||
|
||||
The watch descriptor is returned by later
|
||||
.BR read (2)s
|
||||
from the inotify file descriptor.
|
||||
These reads fetch
|
||||
.I inotify_event
|
||||
structures indicating file system events;
|
||||
the returned watch descriptor identifies
|
||||
the object for which the event occurred.
|
||||
.SH "RETURN VALUE"
|
||||
On success,
|
||||
.BR inotify_add_watch ()
|
||||
returns a non-negative watch descriptor.
|
||||
On error \-1 is returned and
|
||||
.I errno
|
||||
is set appropriately.
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B EACCESS
|
||||
Read access to the given file is not permitted.
|
||||
.TP
|
||||
.B EBADF
|
||||
The given file descriptor is not valid.
|
||||
.TP
|
||||
.B EFAULT
|
||||
.I path
|
||||
points outside of the process's accessible address space.
|
||||
.TP
|
||||
.B EINVAL
|
||||
The given event mask contains no legal events.
|
||||
.TP
|
||||
.B ENOMEM
|
||||
Insufficient kernel memory was available.
|
||||
.TP
|
||||
.B ENOSPC
|
||||
The user limit on the total number of inotify watches was reached or the
|
||||
kernel failed to allocate a needed resource.
|
||||
.SH "HISTORY"
|
||||
Inotify was merged into the 2.6.13 Linux kernel.
|
||||
.SH "CONFORMING TO"
|
||||
This system call is Linux specific.
|
||||
.SH "BUGS"
|
||||
In kernels before 2.6.16, the
|
||||
.B IN_ONESHOT
|
||||
.I mask
|
||||
flag does not work.
|
||||
.\" FIXME To be confirmed that the fix made by Robert Love did
|
||||
.\" actually make it into 2.6.16.
|
||||
.SH "SEE ALSO"
|
||||
.BR inotify_init (2),
|
||||
.BR inotify_rm_watch (2),
|
||||
.BR inotify (7).
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
.\" man2/inotify_init.2 - inotify_init man page
|
||||
.\"
|
||||
.\" Copyright (C) 2005 Robert Love
|
||||
.\"
|
||||
.\" This is free documentation; you can redistribute it and/or
|
||||
.\" modify it under the terms of the GNU General Public License as
|
||||
.\" published by the Free Software Foundation; either version 2 of
|
||||
.\" the License, or (at your option) any later version.
|
||||
.\"
|
||||
.\" The GNU General Public License's references to "object code"
|
||||
.\" and "executables" are to be interpreted as the output of any
|
||||
.\" document formatting or typesetting system, including
|
||||
.\" intermediate and printed output.
|
||||
.\"
|
||||
.\" This manual is distributed in the hope that it will be useful,
|
||||
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
.\" GNU General Public License for more details.
|
||||
.\"
|
||||
.\" You should have received a copy of the GNU General Public
|
||||
.\" License along with this manual; if not, write to the Free
|
||||
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
||||
.\" USA.
|
||||
.\"
|
||||
.\" 2005-07-19 Robert Love <rlove@rlove.org> - initial version
|
||||
.\" 2006-02-07 mtk, minor changes
|
||||
.\"
|
||||
.TH INOTIFY_INOTIFY 2 2006-02-07 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
inotify_init \- initialize an inotify instance
|
||||
.SH SYNOPSIS
|
||||
.B #include <inotify.h>
|
||||
.sp
|
||||
.BI "int inotify_init(void)"
|
||||
.SH DESCRIPTION
|
||||
.BR inotify_init ()
|
||||
initializes a new inotify instance and returns a file descriptor associated
|
||||
with a new inotify event queue.
|
||||
.SH "RETURN VALUE"
|
||||
On success,
|
||||
.BR inotify_init ()
|
||||
returns a new file descriptor, or \-1 if an error occurred (in which
|
||||
case,
|
||||
.I errno
|
||||
is set appropriately).
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B EMFILE
|
||||
The user limit on the total number of inotify instances has been reached.
|
||||
.TP
|
||||
.B ENFILE
|
||||
The system limit on the total number of file descriptors has been reached.
|
||||
.TP
|
||||
.B ENOMEM
|
||||
Insufficient kernel memory is available.
|
||||
.SH "HISTORY"
|
||||
Inotify was merged into the 2.6.13 Linux kernel.
|
||||
.SH "CONFORMING TO"
|
||||
This system call is Linux specific.
|
||||
.SH "SEE ALSO"
|
||||
.BR inotify_add_watch (2),
|
||||
.BR inotify_rm_watch (2),
|
||||
.BR inotify (7).
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
.\" man2/inotify_rm_watch.2 - inotify_rm_watch man page
|
||||
.\"
|
||||
.\" Copyright (C) 2005 Robert Love
|
||||
.\"
|
||||
.\" This is free documentation; you can redistribute it and/or
|
||||
.\" modify it under the terms of the GNU General Public License as
|
||||
.\" published by the Free Software Foundation; either version 2 of
|
||||
.\" the License, or (at your option) any later version.
|
||||
.\"
|
||||
.\" The GNU General Public License's references to "object code"
|
||||
.\" and "executables" are to be interpreted as the output of any
|
||||
.\" document formatting or typesetting system, including
|
||||
.\" intermediate and printed output.
|
||||
.\"
|
||||
.\" This manual is distributed in the hope that it will be useful,
|
||||
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
.\" GNU General Public License for more details.
|
||||
.\"
|
||||
.\" You should have received a copy of the GNU General Public
|
||||
.\" License along with this manual; if not, write to the Free
|
||||
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
||||
.\" USA.
|
||||
.\"
|
||||
.\" 2005-07-19 Robert Love <rlove@rlove.org> - initial version
|
||||
.\" 2006-02-07 mtk, minor changes
|
||||
.\"
|
||||
.TH INOTIFY_RM_WATCH 2 2006-02-07 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
inotify_rm_watch \- remove an existing watch from an inotify instance
|
||||
.SH SYNOPSIS
|
||||
.B #include <inotify.h>
|
||||
.sp
|
||||
.BI "int inotify_rm_watch(int " fd ", uint32_t " wd );
|
||||
.SH DESCRIPTION
|
||||
.BR inotify_rm_watch ()
|
||||
removes the watch associated with the watch descriptor
|
||||
.I wd
|
||||
from the inotify instance associated with the file descriptor
|
||||
.IR fd .
|
||||
|
||||
Removing a watch causes an
|
||||
.B IN_IGNORED
|
||||
event to be generated for this watch descriptor. (See
|
||||
.BR inotify (7).)
|
||||
.SH "RETURN VALUE"
|
||||
On success,
|
||||
.BR inotify_rm_watch ()
|
||||
returns zero, or \-1 if an error occurred (in which case,
|
||||
.I errno
|
||||
is set appropriately).
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B EBADF
|
||||
. I fd
|
||||
is not a valid file descriptor.
|
||||
.TP
|
||||
.B EINVAL
|
||||
The watch descriptor
|
||||
.I wd
|
||||
is not valid.
|
||||
.SH "HISTORY"
|
||||
Inotify was merged into the 2.6.13 Linux kernel.
|
||||
.SH "CONFORMING TO"
|
||||
This system call is Linux specific.
|
||||
.SH "SEE ALSO"
|
||||
.BR inotify_init (2),
|
||||
.BR inotify_add_watch (2),
|
||||
.BR inotify (7).
|
||||
|
|
@ -0,0 +1,295 @@
|
|||
'\" t
|
||||
.\" Hey Emacs! This file is -*- nroff -*- source.
|
||||
.\"
|
||||
.\" Copyright (C) 2006 Michael Kerrisk <mtk-manpages@gmx.net>
|
||||
.\"
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
.\" preserved on all copies.
|
||||
.\"
|
||||
.\" Permission is granted to copy and distribute modified versions of this
|
||||
.\" manual under the conditions for verbatim copying, provided that the
|
||||
.\" entire resulting derived work is distributed under the terms of a
|
||||
.\" permission notice identical to this one.
|
||||
.\"
|
||||
.\" Since the Linux kernel and libraries are constantly changing, this
|
||||
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
||||
.\" responsibility for errors or omissions, or for damages resulting from
|
||||
.\" the use of the information contained herein.
|
||||
.\"
|
||||
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\"
|
||||
.TH INOTIFY 7 2006-02-07 "Linux 2.6.15" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
inotify - monitoring file system events
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.I inotify
|
||||
API provides a mechanism for monitoring file system events.
|
||||
Inotify can be used to monitor individual files,
|
||||
or to monitor directories.
|
||||
When a directory is monitored, inotify will return events
|
||||
for the directory itself, and for files inside the directory.
|
||||
|
||||
The following system calls are used with this API:
|
||||
.BR inotify_init (),
|
||||
.BR inotify_add_watch (),
|
||||
.BR read (),
|
||||
and
|
||||
.BR inotify_rm_watch (),
|
||||
and
|
||||
.BR close ().
|
||||
|
||||
.BR inotify_init (2)
|
||||
creates an inotify instance and returns a file descriptor
|
||||
referring to the inotify object.
|
||||
|
||||
.BR inotify_add_watch (2)
|
||||
manipulates the "watch list" associated with an inotify object.
|
||||
Each item ("watch") in the watch list specifies a pathname of
|
||||
a file or directory,
|
||||
along with some set of events that the kernel should monitor for the
|
||||
file referred to by that pathname.
|
||||
.BR inotify_add_watch ()
|
||||
either creates a new watch item, or modifies an existing watch.
|
||||
Each watch has a unique "watch descriptor", an integer
|
||||
returned by
|
||||
.BR inotify_add_watch ()
|
||||
when the watch is created.
|
||||
|
||||
.BR inotify_rm_watch (2)
|
||||
removes an item from an inotify watch list.
|
||||
|
||||
When all file descriptors referring to an inotify object have been closed,
|
||||
the underlying object and its resources are freed for re-use by the kernel;
|
||||
all associated watches are automatically freed.
|
||||
|
||||
To determine what events have occurred, an application
|
||||
.BR read (2)s
|
||||
from the inotify file descriptor.
|
||||
If no events have so far occurred, then,
|
||||
assuming a non-blocking file descriptor,
|
||||
.BR read ()
|
||||
will block until at least one event occurs.
|
||||
|
||||
Each successful
|
||||
.BR read ()
|
||||
returns a buffer containing one or more of the following structures:
|
||||
.in +0.25i
|
||||
.nf
|
||||
|
||||
struct inotify_event {
|
||||
int wd; /* Watch descriptor */
|
||||
uint32_t mask; /* Mask of events */
|
||||
uint32_t cookie; /* Unique cookie associating related
|
||||
events (for rename(2)) */
|
||||
uint32_t len; /* Size of 'name' field */
|
||||
char name[]; /* Optional null-terminated name */
|
||||
};
|
||||
.fi
|
||||
.in -0.25i
|
||||
|
||||
.I wd
|
||||
identifies the watch for which this event occurs.
|
||||
It is one of the watch descriptors returned by a previous call to
|
||||
.BR inotify_add_watch ().
|
||||
|
||||
.I mask
|
||||
contains bits that describe the event that occurred (see below).
|
||||
|
||||
.I cookie
|
||||
is a unique integer that connects related events.
|
||||
Currently this is only used for rename events, and
|
||||
allows the resulting pair of
|
||||
.B IN_MOVE_FROM
|
||||
and
|
||||
.B IN_MOVE_TO
|
||||
events to be connected by the application.
|
||||
|
||||
The
|
||||
.I name
|
||||
field is only present when an event is returned
|
||||
for a file inside a watched directory;
|
||||
it identifies the file pathname relative to the watched directory.
|
||||
This pathname is null-terminated,
|
||||
and may include further null bytes for alignment to a
|
||||
suitable address boundary.
|
||||
|
||||
The
|
||||
.I len
|
||||
field counts all of the bytes in
|
||||
.IR name ,
|
||||
including the null bytes;
|
||||
the length of each
|
||||
.I inotify_event
|
||||
structure is thus
|
||||
.IR "sizeof(inotify_event)+len" .
|
||||
.SS inotify events
|
||||
The
|
||||
.BR inotify_add_watch (2)
|
||||
.I mask
|
||||
argument and the
|
||||
.I mask
|
||||
field of the
|
||||
.I inotify_event
|
||||
structure returned when
|
||||
.BR read (2)ing
|
||||
an inotify file descriptor are both bit masks identifying
|
||||
inotify events.
|
||||
The following bits can be specified in
|
||||
.I mask
|
||||
when calling
|
||||
.BR inotify_add_watch ()
|
||||
and may be returned in the
|
||||
.I mask
|
||||
field returned by
|
||||
.BR read ():
|
||||
.in +0.25i
|
||||
.TS
|
||||
lB lB
|
||||
lB l.
|
||||
Bit Description
|
||||
IN_ACCESS File was accessed (read) (*)
|
||||
IN_ATTRIB Metadata changed (permissions, timestamps,
|
||||
extended attributes, etc.) (*)
|
||||
IN_CLOSE_WRITE File opened for writing was closed (*)
|
||||
IN_CLOSE_NOWRITE File not opened for writing was closed (*)
|
||||
IN_CREATE File/directory created in watched directory (*)
|
||||
IN_DELETE File/directory deleted from watched directory (*)
|
||||
IN_DELETE_SELF Watched file/directory was itself deleted
|
||||
IN_MODIFY File was modified (*)
|
||||
IN_MOVE_SELF Watched file/directory was itself moved
|
||||
IN_MOVED_FROM File moved out of watched directory (*)
|
||||
IN_MOVED_TO File moved into watched directory (*)
|
||||
IN_OPEN File was opened (*)
|
||||
.TE
|
||||
.in -0.25i
|
||||
.PP
|
||||
When monitoring a directory,
|
||||
the events marked with an asterisk (*) above can occur for
|
||||
files in the directory, in which case the
|
||||
.I name
|
||||
field in the returned
|
||||
.I inotify_event
|
||||
structure identifies the name of the file within the directory.
|
||||
.PP
|
||||
The
|
||||
.B IN_ALL_EVENTS
|
||||
macro is defined as a bit mask of all of the above events.
|
||||
This macro can be used as the
|
||||
.I mask
|
||||
argument when calling
|
||||
.BR inotify_add_watch ().
|
||||
|
||||
Two additional convenience macros are
|
||||
.BR IN_MOVE ,
|
||||
which equates to
|
||||
IN_MOVED_FROM|IN_MOVED_TO,
|
||||
and
|
||||
.BR IN_CLOSE
|
||||
which equates to
|
||||
IN_CLOSE_WRITE|IN_CLOSE_NOWRITE.
|
||||
.PP
|
||||
The following further bits can be specified in
|
||||
.I mask
|
||||
when calling
|
||||
.BR inotify_add_watch ():
|
||||
.in +0.25i
|
||||
.TS
|
||||
lB lB
|
||||
lB l.
|
||||
Bit Description
|
||||
IN_DONT_FOLLOW Don't dereference \fIpath\fP if it is a symbolic link
|
||||
IN_MASK_ADD Add (OR) events to watch mask for this path if
|
||||
it already exists (instead of replacing mask)
|
||||
IN_ONESHOT Monitor \fIpath\fP for one event, then remove from
|
||||
watch list
|
||||
IN_ONLYDIR Only watch \fIpath\fP if it is a directory
|
||||
.TE
|
||||
.in -0.25i
|
||||
.PP
|
||||
The following bits may be set in the
|
||||
.I mask
|
||||
field returned by
|
||||
.BR read ():
|
||||
.in +0.25i
|
||||
.TS
|
||||
lB lB
|
||||
lB l.
|
||||
Bit Description
|
||||
IN_IGNORED Watch was removed explicitly (\fBinotify_rm_watch\fP())
|
||||
or automatically (file was deleted, or
|
||||
file system was unmounted)
|
||||
IN_ISDIR Subject of this event is a directory
|
||||
IN_Q_OVERFLOW Event queue overflowed (\fIwd\fP is \-1 for this event)
|
||||
IN_UNMOUNT File system containing watched object was unmounted
|
||||
.TE
|
||||
.in -0.25i
|
||||
.SS /proc interfaces
|
||||
The following interfaces can be used to limit the amount of
|
||||
kernel memory consumed by inotify:
|
||||
.TP
|
||||
.IR /proc/sys/fs/inotify/max_queued_events
|
||||
The value in this file is used when an application calls
|
||||
.BR inotify_init (2)
|
||||
to set an upper limit on the number of events that can be
|
||||
queued to the corresponding inotify instance.
|
||||
Events in excess of this limit are dropped, but an
|
||||
.B IN_Q_OVERFLOW
|
||||
event is always generated.
|
||||
.TP
|
||||
.IR /proc/sys/fs/inotify/max_user_instances
|
||||
This specifies an upper limit on the number of inotify instances
|
||||
that can be created per real user ID.
|
||||
.TP
|
||||
.IR /proc/sys/fs/inotify/max_user_watches
|
||||
This specifies a limit on the number of watches that can be associated
|
||||
with each inotify instance.
|
||||
.SH "NOTES"
|
||||
Inotify file descriptors can be monitored using
|
||||
.BR select (2),
|
||||
.BR poll (2),
|
||||
and
|
||||
.BR epoll (4).
|
||||
|
||||
If successive output inotify events produced on the
|
||||
inotify file descriptor are identical (same
|
||||
.IR wd ,
|
||||
.IR mask ,
|
||||
.IR cookie ,
|
||||
and
|
||||
.IR name )
|
||||
then they are coalesced into a single event.
|
||||
|
||||
The events returned by reading from an inotify file descriptor
|
||||
form an ordered queue.
|
||||
Thus, for example, it is guaranteed that when renaming from
|
||||
one directory to another, events will be produced in the
|
||||
correct order on the inotify file descriptor.
|
||||
|
||||
The
|
||||
.B FIONREAD
|
||||
.BR ioctl ()
|
||||
returns the number of bytes available to read from an
|
||||
inotify file descriptor.
|
||||
|
||||
Inotify monitoring of directories is not recursive:
|
||||
to monitor subdirectories under a directory,
|
||||
additional watches must be created.
|
||||
.SH "HISTORY"
|
||||
Inotify was merged into the 2.6.13 Linux kernel.
|
||||
.SH "CONFORMING TO"
|
||||
The inotify API is Linux specific.
|
||||
Some other systems provide similar mechanisms, e.g.,
|
||||
FreeBSD has
|
||||
.IR kqueue ,
|
||||
and Solaris has
|
||||
.IR /dev/poll .
|
||||
.SH "SEE ALSO"
|
||||
.BR inotify_add_watch (2),
|
||||
.BR inotify_init (2),
|
||||
.BR inotify_rm_watch (2),
|
||||
.BR read (2),
|
||||
.BR stat (2),
|
||||
.IR Documentation/filesystems/inotify.txt .
|
||||
Loading…
Reference in New Issue