| .\" Copyright (C) 2005 Robert Love |
| .\" and Copyright, 2006 Michael Kerrisk |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" 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, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 2005-07-19 Robert Love <rlove@rlove.org> - initial version |
| .\" 2006-02-07 mtk, various changes |
| .\" |
| .TH INOTIFY_ADD_WATCH 2 2020-04-11 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| inotify_add_watch \- add a watch to an initialized inotify instance |
| .SH SYNOPSIS |
| .B #include <sys/inotify.h> |
| .PP |
| .BI "int inotify_add_watch(int " fd ", const char *" pathname ", uint32_t " mask ); |
| .SH DESCRIPTION |
| .BR inotify_add_watch () |
| adds a new watch, or modifies an existing watch, |
| for the file whose location is specified in |
| .IR pathname ; |
| the caller must have read permission for this file. |
| The |
| .I fd |
| argument is a file descriptor referring to the |
| inotify instance whose watch list is to be modified. |
| The events to be monitored for |
| .I pathname |
| are specified in the |
| .I mask |
| bit-mask argument. |
| See |
| .BR inotify (7) |
| for a description of the bits that can be set in |
| .IR mask . |
| .PP |
| A successful call to |
| .BR inotify_add_watch () |
| returns a unique watch descriptor for this inotify instance, |
| for the filesystem object (inode) that corresponds to |
| .IR pathname . |
| If the filesystem object |
| was not previously being watched by this inotify instance, |
| then the watch descriptor is newly allocated. |
| If the filesystem object was already being watched |
| (perhaps via a different link to the same object), then the descriptor |
| for the existing watch is returned. |
| .PP |
| The watch descriptor is returned by later |
| .BR read (2)s |
| from the inotify file descriptor. |
| These reads fetch |
| .I inotify_event |
| structures (see |
| .BR inotify (7)) |
| indicating filesystem events; |
| the watch descriptor inside this structure identifies |
| the object for which the event occurred. |
| .SH RETURN VALUE |
| On success, |
| .BR inotify_add_watch () |
| returns a watch descriptor (a nonnegative integer). |
| On error, \-1 is returned and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .TP |
| .B EACCES |
| Read access to the given file is not permitted. |
| .TP |
| .B EBADF |
| The given file descriptor is not valid. |
| .TP |
| .B EEXIST |
| .I mask |
| contains |
| .B IN_MASK_CREATE |
| and |
| .I pathname |
| refers to a file already being watched by the same |
| .IR fd . |
| .TP |
| .B EFAULT |
| .I pathname |
| points outside of the process's accessible address space. |
| .TP |
| .B EINVAL |
| The given event mask contains no valid events; or |
| .I mask |
| contains both |
| .B IN_MASK_ADD |
| and |
| .BR IN_MASK_CREATE ; |
| or |
| .I fd |
| is not an inotify file descriptor. |
| .TP |
| .B ENAMETOOLONG |
| .I pathname |
| is too long. |
| .TP |
| .B ENOENT |
| A directory component in |
| .I pathname |
| does not exist or is a dangling symbolic link. |
| .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. |
| .TP |
| .B ENOTDIR |
| .I mask |
| contains |
| .B IN_ONLYDIR |
| and |
| .I pathname |
| is not a directory. |
| .SH VERSIONS |
| Inotify was merged into the 2.6.13 Linux kernel. |
| .SH CONFORMING TO |
| This system call is Linux-specific. |
| .SH EXAMPLES |
| See |
| .BR inotify (7). |
| .SH SEE ALSO |
| .BR inotify_init (2), |
| .BR inotify_rm_watch (2), |
| .BR inotify (7) |