source: project/wiki/eggref/5/inotify @ 37499

Last change on this file since 37499 was 37499, checked in by wasamasa, 11 months ago

inotify: Add C5 docs

File size: 8.4 KB
Line 
1== inotify
2
3[[toc:]]
4
5=== Introduction
6
7This egg provides a nearly complete set of bindings to the Linux
8inotify API for watching file events.  The authoritative source on its
9behavior is [[http://man7.org/linux/man-pages/man7/inotify.7.html|inotify(7)]].
10
11=== Author
12
13Vasilij Schneidermann
14
15=== Repository
16
17[[https://github.com/wasamasa/inotify]]
18
19=== Current state of the bindings
20
21* Every inotify function except {{inotify_init1}} is covered
22* The low-level API provides the absolute basics for watching files. It is intended to be used by library authors who want to incorporate file watching into their egg.  All API calls require a {{FD}} argument.
23* The high-level API stores the user instance file descriptor in a parameter and provides further convenience procedures.  It is intended to be used by application authors.
24
25=== Requirements
26
27This library requires a sufficiently recent Linux kernel, but has been
28tested on Linux 4.8.13 only.  Please report any incompatibilities you
29run into with older Linux versions.
30
31=== Common API
32
33==== Events
34
35<procedure>(event? X)</procedure>
36<procedure>(event-wd EVENT)</procedure>
37<procedure>(event-flags EVENT)</procedure>
38<procedure>(event-cookie EVENT)</procedure>
39<procedure>(event-name EVENT)</procedure>
40
41Event predicate and accessors for event records.  An event has a watch
42descriptor for associating it with a watch, a list of flags associated
43with the event, a cookie that is set for {{rename}} events to allow
44connecting the old and new file name and a name that is set for file
45events inside a watched directory.
46
47The event flag list consists of at least one of the following symbols:
48
49* {{access}}
50* {{attrib}}
51* {{close-write}}
52* {{close-nowrite}}
53* {{create}}
54* {{delete}}
55* {{delete-self}}
56* {{ignore}}
57* {{isdir}}
58* {{modify}}
59* {{move-self}}
60* {{moved-from}}
61* {{moved-to}}
62* {{open}}
63* {{q-overflow}}
64* {{unmount}}
65
66=== Low-level API
67
68==== Setup and Teardown
69
70<procedure>(%init!)</procedure>
71
72Initializes an user instance and returns its file descriptor.
73
74<procedure>(%clean-up! FD)</procedure>
75
76Frees the user instance associated with {{FD}} and all associated
77watches.
78
79==== Watches
80
81<procedure>(%add-watch! FD PATH FLAGS)</procedure>
82
83Adds a watch for {{PATH}} which must be an absolute or relative path
84pointing to a file or directory.  {{FLAGS}} is a list of at least one
85symbol describing the events one is interested in.  Returns a watch
86descriptor associated with the watch.
87
88The event flag list consists of at least one of the following event
89type symbols:
90
91* {{access}}
92* {{attrib}}
93* {{close-write}}
94* {{close-nowrite}}
95* {{create}}
96* {{delete}}
97* {{delete-self}}
98* {{modify}}
99* {{move-self}}
100* {{moved-from}}
101* {{moved-to}}
102* {{open}}
103
104Further convenience flags:
105
106* {{move}} (equivalent to {{(moved-from moved-to)}})
107* {{close}} (equivalent to {{(close-write close-nowrite)}})
108* {{all-events}} (catches all event types)
109
110Further options:
111
112* {{dont-follow}}
113* {{excl-unlink}}
114* {{mask-add}}
115* {{oneshot}}
116* {{onlydir}}
117
118<procedure>(%remove-watch! FD WD)</procedure>
119
120Removes a watch as identified by the given watch descriptor {{WD}}.
121
122==== Events
123
124<procedure>(%next-events! FD)</procedure>
125
126Blocks the current thread to wait for events and returns a list of
127at least one event record.  Note that calling this procedure does
128''not'' block other SRFI-18 threads.  In other words, it is possible
129to have a background thread reacting to file events while other
130threads proceed normally.
131
132=== High-level API
133
134==== Setup and Teardown
135
136<procedure>(init!)</procedure>
137
138Initializes an user instance, returning {{#t}} when successful and
139{{#f}} if it has been initialized before.  This procedure must be
140called before manipulating watches and fetching events.
141
142<procedure>(clean-up!)</procedure>
143
144Frees the user instance and all associated watches, returning {{#t}}
145when successful and {{#f}} on subsequent attempts.
146
147<parameter>(%fd)</parameter>
148<parameter>(%fd FD)</parameter>
149
150Parameter holding the user instance file descriptor.  You shouldn't
151need to mess with this unless you insist on using more than one user
152instance for watching events.
153
154==== Watches
155
156<procedure>(add-watch! PATH FLAGS)</procedure>
157
158Adds a watch for {{PATH}} which must be an absolute or relative path
159pointing to a file or directory.  {{FLAGS}} is a list of at least one
160symbol describing the events one is interested in.  Returns a watch
161descriptor associated with the watch.
162
163The event flag list consists of at least one of the following event
164type symbols:
165
166* {{access}}
167* {{attrib}}
168* {{close-write}}
169* {{close-nowrite}}
170* {{create}}
171* {{delete}}
172* {{delete-self}}
173* {{modify}}
174* {{move-self}}
175* {{moved-from}}
176* {{moved-to}}
177* {{open}}
178
179Further convenience flags:
180
181* {{move}} (equivalent to {{(moved-from moved-to)}})
182* {{close}} (equivalent to {{(close-write close-nowrite)}})
183* {{all-events}} (catches all event types)
184
185Further options:
186
187* {{dont-follow}}
188* {{excl-unlink}}
189* {{mask-add}}
190* {{oneshot}}
191* {{onlydir}}
192
193<procedure>(remove-watch! WD)</procedure>
194
195Removes a watch as identified by the given watch descriptor {{WD}}.
196
197<procedure>(add-watch-recursively! PATH FLAGS)</procedure>
198
199Adds a watch for {{PATH}} and traverses it recursively to add watches
200for any directories found in it.  Each watch is applied with
201{{FLAGS}}, refer to the documentation of {{add-watch!}} for further
202details.  Returns a list of watch descriptors associated with each
203established watch.  Note that this procedure does ''not'' work in an
204atomic manner, it cannot be guaranteed that all directories in
205{{PATH}} will receive watches.
206
207<procedure>(wd->path WD)</procedure>
208
209Returns the path the watch associated with {{WD}} was created with.
210
211<procedure>(wd-list)</procedure>
212
213Returns a list of all known watch descriptors.
214
215<procedure>(path-list)</procedure>
216
217Returns a list of all watched paths.
218
219==== Events
220
221<procedure>(next-events!)</procedure>
222
223Blocks the current thread to wait for events and returns a list of
224at least one event record.  Note that calling this procedure does
225''not'' block other SRFI-18 threads.  In other words, it is possible
226to have a background thread reacting to file events while other
227threads proceed normally.
228
229<parameter>(%events)</parameter>
230<procedure>(next-event!)</procedure>
231
232Convenience procedure for fetching one event at a time.  This calls
233{{next-events!}} internally for filling up an event queue and returns
234one event from it.  The event queue itself is available under
235{{%events}} and can be manipulated with the queue procedures from the
236{{data-structures}} unit.
237
238<procedure>(event->pathname EVENT)</procedure>
239
240Convenience procedure for reconstructing the full path name from an event.
241
242==== /proc Interface
243
244<procedure>(max-queued-events)</procedure>
245<procedure>(max-user-instances)</procedure>
246<procedure>(max-user-watches)</procedure>
247
248Convenience procedures for querying usage limits from
249{{/proc/sys/fs/inotify}}.
250
251=== Examples
252
253<enscript highlight="scheme">
254(import inotify)
255
256(init!)
257(on-exit clean-up!)
258(add-watch! "." '(all-events))
259
260(let loop ()
261  (print (next-event!)))
262</enscript>
263
264More realistic examples can be found
265[[https://github.com/wasamasa/inotify/blob/master/examples/fallkiste.scm|in the repository]].
266
267=== License
268
269 Copyright (c) 2017, Vasilij Schneidermann
270 
271 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
272 
273 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
274 
275 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
276
277=== Version History
278
279==== 1.0
280
281* C5 port
282
283==== 0.3
284
285* Fix packaging mistake
286
287==== 0.2
288
289* Split up the API into a low-level and high-level one
290* Incorporated some feedback about the C code (thanks, florz!)
291* Added one more example
292
293==== 0.1
294
295* Initial release
Note: See TracBrowser for help on using the repository browser.