Debian Codegraph @

upstream/debian-unstable/man2/inotify_add_watch.2

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