xref: /openbmc/qemu/include/qemu/filemonitor.h (revision 683685e7)
1 /*
2  * QEMU file monitor helper
3  *
4  * Copyright (c) 2018 Red Hat, Inc.
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18  *
19  */
20 
21 #ifndef QEMU_FILEMONITOR_H
22 #define QEMU_FILEMONITOR_H
23 
24 
25 
26 typedef struct QFileMonitor QFileMonitor;
27 
28 typedef enum {
29     /* File has been created in a dir */
30     QFILE_MONITOR_EVENT_CREATED,
31     /* File has been modified in a dir */
32     QFILE_MONITOR_EVENT_MODIFIED,
33     /* File has been deleted in a dir */
34     QFILE_MONITOR_EVENT_DELETED,
35     /* File has attributes changed */
36     QFILE_MONITOR_EVENT_ATTRIBUTES,
37     /* Dir is no longer being monitored (due to deletion) */
38     QFILE_MONITOR_EVENT_IGNORED,
39 } QFileMonitorEvent;
40 
41 
42 /**
43  * QFileMonitorHandler:
44  * @id: id from qemu_file_monitor_add_watch()
45  * @event: the file change that occurred
46  * @filename: the name of the file affected
47  * @opaque: opaque data provided to qemu_file_monitor_add_watch()
48  *
49  * Invoked whenever a file changes. If @event is
50  * QFILE_MONITOR_EVENT_IGNORED, @filename will be
51  * empty.
52  *
53  */
54 typedef void (*QFileMonitorHandler)(int64_t id,
55                                     QFileMonitorEvent event,
56                                     const char *filename,
57                                     void *opaque);
58 
59 /**
60  * qemu_file_monitor_new:
61  * @errp: pointer to a NULL-initialized error object
62  *
63  * Create a handle for a file monitoring object.
64  *
65  * This object does locking internally to enable it to be
66  * safe to use from multiple threads
67  *
68  * If the platform does not support file monitoring, an
69  * error will be reported. Likewise if file monitoring
70  * is supported, but cannot be initialized
71  *
72  * Currently this is implemented on Linux platforms with
73  * the inotify subsystem.
74  *
75  * Returns: the new monitoring object, or NULL on error
76  */
77 QFileMonitor *qemu_file_monitor_new(Error **errp);
78 
79 /**
80  * qemu_file_monitor_free:
81  * @mon: the file monitor context
82  *
83  * Free resources associated with the file monitor,
84  * including any currently registered watches.
85  */
86 void qemu_file_monitor_free(QFileMonitor *mon);
87 
88 /**
89  * qemu_file_monitor_add_watch:
90  * @mon: the file monitor context
91  * @dirpath: the directory whose contents to watch
92  * @filename: optional filename to filter on
93  * @cb: the function to invoke when @dirpath has changes
94  * @opaque: data to pass to @cb
95  * @errp: pointer to a NULL-initialized error object
96  *
97  * Register to receive notifications of changes
98  * in the directory @dirpath. All files in the
99  * directory will be monitored. If the caller is
100  * only interested in one specific file, @filename
101  * can be used to filter events.
102  *
103  * Returns: a positive integer watch ID, or -1 on error
104  */
105 int64_t qemu_file_monitor_add_watch(QFileMonitor *mon,
106                                     const char *dirpath,
107                                     const char *filename,
108                                     QFileMonitorHandler cb,
109                                     void *opaque,
110                                     Error **errp);
111 
112 /**
113  * qemu_file_monitor_remove_watch:
114  * @mon: the file monitor context
115  * @dirpath: the directory whose contents to unwatch
116  * @id: id of the watch to remove
117  *
118  * Removes the file monitoring watch @id, associated
119  * with the directory @dirpath. This must never be
120  * called from a QFileMonitorHandler callback, or a
121  * deadlock will result.
122  */
123 void qemu_file_monitor_remove_watch(QFileMonitor *mon,
124                                     const char *dirpath,
125                                     int64_t id);
126 
127 #endif /* QEMU_FILEMONITOR_H */
128