comp • gb.inotify • watch

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.

This class is
Create a new watch for the given path.
creatable
.

Static properties

Constants
A cookie used to associate events. This is currently only used to connect MoveFrom and MoveTo events of the same file.
Cookie  
Return whether the event subject is/was a directory.
IsDir  
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.
Name  
Return whether the filesystem on which the watched path resided, was unmounted. In this case, the Watch object is invalidated just after the event.
Unmount  
Watch all events.
All  
Watch for the Close event.
Close  
Watch for the Create event.
Create  
Watch for the Delete event.
Delete  
Watch for the Move event.
Move  
Watch for the MoveFrom event.
MoveFrom  
Watch for the MoveTo event.
MoveTo  
Watch for the Open event.
Open  
Watch for the Read event.
Read  
Watch for the Stat event.
Stat  
Watch for the Write event.
Write  

Properties

Methods Events
Return a virtual class to specify the event monitoring bitmask.
Events  
Returns if the watch is paused.
IsPaused  
Return the watched path.
Path  
This Variant is free for use by the Gambas programmer.
Tag  
Pauses the watch, i.e. disables event generation.
Pause  
Resumes the watch if it was paused.
Resume  
This event is raised when the watched file or a file in the watched directory is closed.
Close  
This event is raised when a file or directory was created in the watched directory.
Create  
This event is raised when an entry was deleted from the watched directory or the path itself was deleted.
Delete  
This event is raised when the watched file or directory was moved.
Move  
This event is raised for the source directory when a file is being moved.
MoveFrom  
This event is raised for the destination directory when a file is being moved.
MoveTo  
This event is raised when the watched file or an entry in the watched directory was opened.
Open  
This event is raised when the watched file or entry in the watched directory was accessed, i.e. read, executed, ....
Read  
This event is raised when file attributes/meta data changes. From $ man 7 inotify:
Stat  
This event is raised when the watched file or entry in the watched directory was modified, i.e. written to, truncated, ....
Write  

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