]>
Commit | Line | Data |
---|---|---|
efa25b17 MK |
1 | .\" Copyright (C) 2005 Robert Love |
2 | .\" and Copyright, 2006 Michael Kerrisk | |
4d2b74dd | 3 | .\" |
e4a74ca8 | 4 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
4d2b74dd MK |
5 | .\" |
6 | .\" 2005-07-19 Robert Love <rlove@rlove.org> - initial version | |
7 | .\" 2006-02-07 mtk, various changes | |
8 | .\" | |
4c1c5274 | 9 | .TH inotify_add_watch 2 (date) "Linux man-pages (unreleased)" |
4d2b74dd MK |
10 | .SH NAME |
11 | inotify_add_watch \- add a watch to an initialized inotify instance | |
c5e23766 AC |
12 | .SH LIBRARY |
13 | Standard C library | |
8fc3b2cf | 14 | .RI ( libc ", " \-lc ) |
4d2b74dd | 15 | .SH SYNOPSIS |
c7db92b9 | 16 | .nf |
6e969f22 | 17 | .B #include <sys/inotify.h> |
c6d039a3 | 18 | .P |
93440c02 | 19 | .BI "int inotify_add_watch(int " fd ", const char *" pathname ", uint32_t " mask ); |
c7db92b9 | 20 | .fi |
4d2b74dd MK |
21 | .SH DESCRIPTION |
22 | .BR inotify_add_watch () | |
c13182ef | 23 | adds a new watch, or modifies an existing watch, |
dd28cb72 MK |
24 | for the file whose location is specified in |
25 | .IR pathname ; | |
26 | the caller must have read permission for this file. | |
c13182ef | 27 | The |
4d2b74dd | 28 | .I fd |
dd28cb72 MK |
29 | argument is a file descriptor referring to the |
30 | inotify instance whose watch list is to be modified. | |
31 | The events to be monitored for | |
32 | .I pathname | |
33 | are specified in the | |
34 | .I mask | |
35 | bit-mask argument. | |
4d2b74dd MK |
36 | See |
37 | .BR inotify (7) | |
38 | for a description of the bits that can be set in | |
39 | .IR mask . | |
c6d039a3 | 40 | .P |
4d2b74dd MK |
41 | A successful call to |
42 | .BR inotify_add_watch () | |
7499e6bc | 43 | returns a unique watch descriptor for this inotify instance, |
30e2a22a | 44 | for the filesystem object (inode) that corresponds to |
7499e6bc MK |
45 | .IR pathname . |
46 | If the filesystem object | |
4d2b74dd | 47 | was not previously being watched by this inotify instance, |
c13182ef | 48 | then the watch descriptor is newly allocated. |
7499e6bc MK |
49 | If the filesystem object was already being watched |
50 | (perhaps via a different link to the same object), then the descriptor | |
4d2b74dd | 51 | for the existing watch is returned. |
c6d039a3 | 52 | .P |
4d2b74dd MK |
53 | The watch descriptor is returned by later |
54 | .BR read (2)s | |
c13182ef | 55 | from the inotify file descriptor. |
4d2b74dd MK |
56 | These reads fetch |
57 | .I inotify_event | |
325f18da MK |
58 | structures (see |
59 | .BR inotify (7)) | |
9ee4a2b6 | 60 | indicating filesystem events; |
325f18da | 61 | the watch descriptor inside this structure identifies |
4d2b74dd | 62 | the object for which the event occurred. |
47297adb | 63 | .SH RETURN VALUE |
4d2b74dd MK |
64 | On success, |
65 | .BR inotify_add_watch () | |
ed09120a | 66 | returns a watch descriptor (a nonnegative integer). |
dec985f9 | 67 | On error, \-1 is returned and |
4d2b74dd | 68 | .I errno |
f6a4078b | 69 | is set to indicate the error. |
4d2b74dd MK |
70 | .SH ERRORS |
71 | .TP | |
1b3fc756 | 72 | .B EACCES |
4d2b74dd MK |
73 | Read access to the given file is not permitted. |
74 | .TP | |
75 | .B EBADF | |
76 | The given file descriptor is not valid. | |
77 | .TP | |
49a2a105 MK |
78 | .B EEXIST |
79 | .I mask | |
80 | contains | |
81 | .B IN_MASK_CREATE | |
82 | and | |
83 | .I pathname | |
84 | refers to a file already being watched by the same | |
85 | .IR fd . | |
86 | .TP | |
4d2b74dd | 87 | .B EFAULT |
93440c02 | 88 | .I pathname |
4d2b74dd MK |
89 | points outside of the process's accessible address space. |
90 | .TP | |
91 | .B EINVAL | |
e935e108 | 92 | The given event mask contains no valid events; or |
4e821a8a HW |
93 | .I mask |
94 | contains both | |
95 | .B IN_MASK_ADD | |
96 | and | |
6f202877 MK |
97 | .BR IN_MASK_CREATE ; |
98 | or | |
9f5774a9 MK |
99 | .I fd |
100 | is not an inotify file descriptor. | |
4d2b74dd | 101 | .TP |
d54837e8 MK |
102 | .B ENAMETOOLONG |
103 | .I pathname | |
104 | is too long. | |
105 | .TP | |
6a03b9dd MK |
106 | .B ENOENT |
107 | A directory component in | |
108 | .I pathname | |
109 | does not exist or is a dangling symbolic link. | |
110 | .TP | |
4d2b74dd MK |
111 | .B ENOMEM |
112 | Insufficient kernel memory was available. | |
113 | .TP | |
114 | .B ENOSPC | |
115 | The user limit on the total number of inotify watches was reached or the | |
116 | kernel failed to allocate a needed resource. | |
12507e51 PM |
117 | .TP |
118 | .B ENOTDIR | |
119 | .I mask | |
120 | contains | |
121 | .B IN_ONLYDIR | |
122 | and | |
123 | .I pathname | |
124 | is not a directory. | |
3113c7f3 | 125 | .SH STANDARDS |
4131356c AC |
126 | Linux. |
127 | .SH HISTORY | |
128 | Linux 2.6.13. | |
a14af333 | 129 | .SH EXAMPLES |
232057c3 MK |
130 | See |
131 | .BR inotify (7). | |
47297adb | 132 | .SH SEE ALSO |
4d2b74dd | 133 | .BR inotify_init (2), |
c13182ef | 134 | .BR inotify_rm_watch (2), |
ccd2b351 | 135 | .BR inotify (7) |