Pike v8.0 release 1738

Method System.Inotify._Instance()->add_watch()


Method add_watch

int add_watch(string path, int mask)

Description

Add a watch for a certain file or directory and specific events.

Adding more than one watch for a path will overwrite the previous watch unless System.Inotify.IN_MASK_ADD is contained in the mask.

Parameter path

Path of the file or directory.

Parameter mask

Integer mask specifying the event type. This can be a combination of different event types using bitwise OR. See the inotify manpage for possible values and their description. The values defined by the inotify header file are exported by System.Inotify as constants using the same names (e.g. System.Inotify.IN_CREATE).

Returns

Returns a watch descriptor on success, and -1 on filesystem-related failures, in which case errno() will indicate the cause. These typically indicate time of check, time of use race conditions. For other failures errors are thrown.

Note

Subdirectories are not watched. If you want to watch subdirectories as well, you need to add watches for them individually.

Note

At creation of a watch for a directory, simulated IN_CREATE-events with cookie 0x7fffffff will be added for the initial contents of the directory. This is to reduce the risk of losing state changes due to races. Note that is is not known whether these paths are in flux or not. Note also that there may be multiple notifications for content that is created at the moment the watch is created.

Note

In old versions of Pike errors were thrown for all failures.

See also

rm_watch(), parse_event()