Watch (gb.inotify)
This class represents a monitored filesystem object.
Inotify events are reported asynchronously and the kernel makes no guarantees to deliver events in a timely manner. If for example a file is created and then immediately deleted in a directory you watch, it can happen that you get the Create event after the file is already deleted. If you are not careful and try to read the file named by
Watch.Name,
your program will crash with "No such file or directory".
You should read the "Limitations and caveats" section of the inotify manpage (
man 7 inotify). This same manpage is a good source for additional information.
Watching a directory is NOT recursive, i.e. you will only receive events from the directory itself and its immediate entries. If you want to go deeper, you must add recursive watches manually.
Constants
Static properties
|
Cookie
|
A cookie used to associate events. This is currently only used to connect MoveFrom and MoveTo events of the same file.
|
|
IsDir
|
Return whether the event subject is/was a directory.
|
|
Name
|
The name of the file or directory which is subject to the event, relative
to the Watch object which triggered the event. If Null, the directory
itself is subject.
|
|
Unmount
|
Return whether the filesystem on which the watched path resided, was
unmounted. In this case, the Watch object is invalidated just after the
event.
|
Properties
|
Events
|
Return a virtual class to specify the event monitoring bitmask.
|
|
IsPaused
|
Returns if the watch is paused.
|
|
Path
|
Return the watched path.
|
|
Tag
|
This Variant is free for use by the Gambas programmer.
|
Methods
|
Pause
|
Pauses the watch, i.e. disables event generation.
|
|
Resume
|
Resumes the watch if it was paused.
|
Events
|
Close
|
This event is raised when the watched file or a file in the watched directory is closed.
|
|
Create
|
This event is raised when a file or directory was created in the watched directory.
|
|
Delete
|
This event is raised when an entry was deleted from the watched directory or the path itself was deleted.
|
|
Move
|
This event is raised when the watched file or directory was moved.
|
|
MoveFrom
|
This event is raised for the source directory when a file is being moved.
|
|
MoveTo
|
This event is raised for the destination directory when a file is being moved.
|
|
Open
|
This event is raised when the watched file or an entry in the watched directory was opened.
|
|
Read
|
This event is raised when the watched file or entry in the watched directory was accessed, i.e. read, executed, ....
|
|
Stat
|
This event is raised when file attributes/meta data changes. From $ man 7 inotify:
|
|
Write
|
This event is raised when the watched file or entry in the watched directory was modified, i.e. written to, truncated, ....
|
The static properties are used to store data from the kernel during event management. Use them only in event handlers.
Example
Use "gb.inotify"
'The above line is required for Gambas Script only, in full Gambas IDE, see Project Components.
Private $hWatch As Watch
Public Sub Main()
Dim sFile1 As String = Temp$(), sFile2 As String = Temp$()
$hWatch = New Watch(File.Dir(Temp$()), True) As "Watcher"
' This line is redundant: a Watch object will automatically subscribe to events for which an event handler exists!
'$hWatch.Events[Watch.Create Or Watch.Delete] = True
Print "I'm watching... "
' Create two files
File.Save(sFile1, "abc")
File.Save(sFile2, "def")
Wait 0.1 ' enter event loop to see events
' Delete one file
Kill sFile2
Wait 0.1
' Delete the second file. The Delete event was unsubscribed at this point (see Watcher_Delete), so no event is raised for this.
Kill sFile1
Wait 1
Quit
End
Public Sub Watcher_Create()
Print "Create: " & Watch.Name
End
Public Sub Watcher_Delete()
Print "Delete: " & Watch.Name
' Unsubscribe from deletions after the first one.
Last.Events[Watch.Delete] = False
End
I'm watching...
Create: 1.tmp
Create: 2.tmp
Delete: 2.tmp