Gambas Documentation
Application Repository
Code Snippets
Compilation & Installation
Components
gb
gb.args
gb.cairo
gb.chart
gb.clipper
gb.complex
gb.compress
gb.crypt
gb.data
gb.db
gb.db.form
gb.db.mysql
gb.db.odbc
gb.db.postgresql
gb.db.sqlite2
gb.db.sqlite3
gb.dbus
gb.dbus.trayicon
gb.debug
gb.desktop
gb.desktop.gnome.keyring
gb.desktop.x11
gb.eval
gb.eval.highlight
gb.form
gb.form.dialog
gb.form.editor
gb.form.htmlview
gb.form.mdi
gb.form.print
gb.form.stock
gb.form.terminal
gb.gmp
gb.gsl
gb.gtk
gb.gtk.opengl
gb.gtk3
gb.gtk3.opengl
gb.gtk3.webview
gb.gui
gb.gui.opengl
gb.gui.qt
gb.gui.qt.ext
gb.gui.qt.opengl
gb.gui.qt.webkit
gb.gui.trayicon
gb.gui.webview
gb.hash
gb.highlight
gb.image
gb.image.effect
gb.image.imlib
gb.image.io
gb.inotify
.Watch.Events
Watch
_get ?
_new
All
Close
Close
Cookie
Create
Create
Delete
Delete
Events
IsDir
IsPaused
Move
Move
MoveFrom
MoveFrom
MoveTo
MoveTo
Name
Open
Open
Path
Pause
Read
Read
Resume
Stat
Stat
Tag
Unmount
Write
Write
gb.jit
gb.libxml
gb.logging
gb.map
gb.markdown
gb.media
gb.media.form
gb.memcached
gb.mime
gb.mongodb
gb.mysql
gb.ncurses
gb.net
gb.net.curl
gb.net.pop3
gb.net.smtp
gb.openal
gb.opengl
gb.opengl.glsl
gb.opengl.glu
gb.opengl.sge
gb.openssl
gb.option
gb.pcre
gb.pdf
gb.poppler
gb.qt4
gb.qt4.ext
gb.qt4.opengl
gb.qt4.webkit
gb.qt4.webview
gb.qt5
gb.qt5.ext
gb.qt5.opengl
gb.qt5.webkit
gb.qt5.webview
gb.qt6
gb.qt6.ext
gb.qt6.opengl
gb.qt6.webview
gb.report
gb.report2
gb.scanner
gb.sdl
gb.sdl.sound
gb.sdl2
gb.sdl2.audio
gb.settings
gb.signal
gb.term
gb.test
gb.util
gb.util.web
gb.v4l
gb.vb
gb.web
gb.web.feed
gb.web.form
gb.web.gui
gb.xml
gb.xml.html
gb.xml.rpc
gb.xml.xslt
Controls pictures
Deprecated components
Developer Documentation
Development Environment Documentation
Documents
Error Messages
Gambas Playground
How To's
Language Index
Language Overviews
Last Changes
Lexicon
README
Search the wiki
To Do
Topics
Tutorials
Wiki License
Wiki Manual

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 creatable.

Constants
All   Watch all events.
Close   Watch for the Close event.
Create   Watch for the Create event.
Delete   Watch for the Delete event.
Move   Watch for the Move event.
MoveFrom   Watch for the MoveFrom event.
MoveTo   Watch for the MoveTo event.
Open   Watch for the Open event.
Read   Watch for the Read event.
Stat   Watch for the Stat event.
Write   Watch for the Write event.

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