QFileMonitor Class Reference
[QtBaseModule]

Detailed Description

The QFileMonitor class allows applications to asynchronously monitor files for changes.

Using QFileMonitor, clients will be notified through the fileChanged() signal when the contents of a file are changed, the file is deleted or when the file is created.

The QFileMonitor uses different mechanisms for monitoring file changes depending on the capabilities of the underlying system. The following methods are presently available:

DNotify

DNotify is available on all Linux kernels in the 2.4 series and later. Monitoring a file using DNotify has the consequence of "pinning" the containing directory until the QFileMonitor instance has been destroyed. A pinned directory cannot be removed and the filesystem exporting it cannot be unmounted.

In order to detect directory removal, the DNotify strategy must poll directories for existance once every 5 seconds.

INotify

INotify is available in Linux kernel versions 2.6.13 and later. Unlike DNotify, use of INotify does not pin the containing directory. If a directory is removed, while monitoring contained files the QFileMonitor will emit a fileChanged() signal as expected. However, should the directory be recreated the QFileMonitor will not resume monitoring files within it. The QFileMonitor instance must be destroyed and recreated for monitoring to resume.

Poll

While polling files for change is available on all systems, it is the least responsive strategy. Every 5 seconds the QFileMonitor manually polls all monitored files for changes. Polling should only be used as a last-resort fallback.

To avoid race conditions when using QFileMonitor to trigger re-reading of file contents, you should always construct QFileMonitor and only then read the initial file contents.

Member Type Documentation

enum QFileMonitor::Strategy

Represents the monitoring strategy being used by the QFileMonitor instance.

Member Function Documentation

QFileMonitor::QFileMonitor ( QObject * parent = 0 )

Constructs an invalid file monitor with the specified parent.

QFileMonitor::QFileMonitor ( const QString & fileName, Strategy strategy = Auto, QObject * parent = 0 )

Constructs a file monitor for the file fileName using the specified file monitoring strategy and parent.

QFileMonitor::~QFileMonitor ()   [virtual]

Destroys the file monitor.

void QFileMonitor::fileChanged ( const QString & file )   [signal]

Emitted whenever the files contents change, the file is created or the file is removed. file is set to the name of the monitored file.

QString QFileMonitor::fileName () const

Returns the name of the file being monitored.

bool QFileMonitor::isValid () const

Returns true if the file is being actively monitored.

Strategy QFileMonitor::strategy () const

Returns the method used to monitor files.