System.Linux.Inotify

Documentation

data Inotify

Instances

Eq Inotify

Ord Inotify

Show Inotify

Typeable Inotify

data Event

Constructors

Event

Fields

wd :: !Watch

mask :: !(Mask EventFlag)

cookie :: !Cookie

name :: !ByteString

The proper interpretation of this seems to be to use getForeignEncoding and then unpack it to a String or decode it using the text package.

Instances

Eq Event

Show Event

Typeable Event

newtype Watch

Constructors

Watch CInt

Instances

Eq Watch

Ord Watch

Show Watch

Typeable Watch

newtype Mask a

Represents the mask, which in inotify terminology is a union of flags that are used when setting up watches and receiving event notifications.

The type parameter is a phantom type that tracks whether a particular flag is used to set up a watch (WatchFlag) or when receiving an event. (EventFlag) Polymorphic parameters mean that the flag may appear in either context.

Constructors

Mask CUInt

Instances

Typeable1 Mask

Eq (Mask a)

Show (Mask a)

Monoid (Mask a)

Computes the union of two Masks.

isect :: Mask a -> Mask a -> Mask a

isSubset :: Mask a -> Mask a -> Bool

hasOverlap :: Mask a -> Mask a -> Bool

data WatchFlag

An empty type used to denote Mask values that can be sent to the kernel when setting up an inotify watch.

data EventFlag

An empty type used to denote Mask values that can be received from the kernel in an inotify event message.

newtype Cookie

Constructors

Cookie CUInt

Instances

Eq Cookie

Ord Cookie

Show Cookie

Typeable Cookie

init :: IO Inotify

Creates an inotify socket descriptor that watches can be added to and events can be read from.

initWith :: InotifyOptions -> IO Inotify

newtype InotifyOptions

Constructors

InotifyOptions

Fields

bufferSize :: Int

defaultInotifyOptions :: InotifyOptions

addWatch :: Inotify -> FilePath -> Mask WatchFlag -> IO Watch

Adds a watch on the inotify descriptor, returns a watch descriptor. This function is thread safe.

addWatch_ :: Inotify -> RawFilePath -> Mask WatchFlag -> IO Watch

A variant of addWatch that operates on a RawFilePath, which is a file path represented as strict ByteString. One weakness of the current implementation is that if addWatch_ throws an IOException, then any unicode paths will be mangled in the error message.

rmWatch :: Inotify -> Watch -> IO ()

Stops watching a path for changes. This watch descriptor must be associated with the particular inotify port, otherwise undefined behavior can happen.

This function is thread safe. This binding ignores inotify_rm_watch's errno when it is EINVAL, so it is ok to delete a previously removed or non-existent watch descriptor.

However long lived applications that set and remove many watches should still endeavor to avoid calling rmWatch on removed watch descriptors, due to possible wrap-around bugs.

getEvent :: Inotify -> IO Event

Returns an inotify event, blocking until one is available.

It is not safe to call this function from multiple threads at the same time. Though this could be fixed, I do not see why it would be useful.

getEventNonBlocking :: Inotify -> IO (Maybe Event)

Returns an inotify event only if one is immediately available.

One possible downside of the current implementation is that returning Nothing necessarily results in a system call.

getEventFromBuffer :: Inotify -> IO (Maybe Event)

Returns an inotify event only if one is available in Inotifys buffer. This won't ever make a system call.

peekEvent :: Inotify -> IO Event

Returns an inotify event, blocking until one is available.

If this returns an event, then the next read from the inotify descriptor will return the same event and the second read will not result in a system call.

It is not safe to call this function from multiple threads at the same time. Though this could be fixed, I do not see why it would be useful.

peekEventNonBlocking :: Inotify -> IO (Maybe Event)

Returns an inotify event only if one is immediately available.

If this returns an event, then the next read from the inotify descriptor will return the same event and the second read will not result in a system call.

One possible downside of the current implementation is that returning Nothing necessarily results in a system call.

peekEventFromBuffer :: Inotify -> IO (Maybe Event)

Returns an inotify event only if one is available in Inotifys buffer. This won't ever make a system call.

If this returns an event, then the next read from the inotify descriptor will return the same event and the second read will not result in a system call.

close :: Inotify -> IO ()

Closes an inotify descriptor, freeing the resources associated with it. This will also raise an IOException in any threads that are blocked on getEvent.

Although using a descriptor after it is closed is likely to raise an exception, it is not safe to use the descriptor after it is closed. However, it is safe to call close multiple times; this binding ensures that only one system call will be made.

Descriptors will be closed after they are garbage collected, via a finalizer, although it is often preferable to call close yourself.

in_ACCESS :: Mask a

File was accessed. Includes the files of a watched directory.

in_ATTRIB :: Mask a

Metadata changed, e.g., permissions, timestamps, extended attributes, link count (since Linux 2.6.25), UID, GID, etc. Includes the files of a watched directory.

in_CLOSE :: Mask a

File was closed. This is not a separate flag, but a convenience definition such that in_CLOSE == in_CLOSE_WRITE <> in_CLOSE_NOWRITE

in_CLOSE_WRITE :: Mask a

File opened for writing was closed. Includes the files of a watched directory.

in_CLOSE_NOWRITE :: Mask a

File not opened for writing was closed. Includes the files of a watched directory.

in_CREATE :: Mask a

File/directory created in watched directory.

in_DELETE :: Mask a

File/directory deleted from watched directory.

in_DELETE_SELF :: Mask a

Watched file/directory was itself deleted.

in_MODIFY :: Mask a

File was modified. Includes the files of a watched directory.

in_MOVE_SELF :: Mask a

Watched file/directory was itself moved.

in_MOVE :: Mask a

File was moved. This is not a separate flag, but a convenience definition such that in_MOVE == in_MOVED_FROM <> in_MOVED_TO.

in_MOVED_FROM :: Mask a

File moved out of watched directory. Includes the files of a watched directory.

in_MOVED_TO :: Mask a

File moved into watched directory. Includes the files of a watched directory.

in_OPEN :: Mask a

File was opened. Includes the files of a watched directory.

in_ALL_EVENTS :: Mask a

A union of all flags above; this is not a separate flag but a convenience definition.

in_DONT_FOLLOW :: Mask WatchFlag

(since Linux 2.6.15) Don't dereference pathname if it is a symbolic link.

in_EXCL_UNLINK :: Mask WatchFlag

(since Linux 2.6.36) By default, when watching events on the children of a directory, events are generated for children even after they have been unlinked from the directory. This can result in large numbers of uninteresting events for some applications (e.g., if watching /tmp, in which many applications create temporary files whose names are immediately unlinked). Specifying IN_EXCL_UNLINK changes the default behavior, so that events are not generated for children after they have been unlinked from the watched directory.

in_MASK_ADD :: Mask WatchFlag

Add (OR) events to watch mask for this pathname if it already exists (instead of replacing mask).

in_ONESHOT :: Mask WatchFlag

Monitor pathname for one event, then remove from watch list.

in_ONLYDIR :: Mask WatchFlag

(since Linux 2.6.15) Only watch pathname if it is a directory.

in_IGNORED :: Mask EventFlag

Watch was removed explicitly (rmWatch) or automatically (file was deleted, or file system was unmounted).

in_ISDIR :: Mask EventFlag

Subject of this event is a directory.

in_Q_OVERFLOW :: Mask EventFlag

Event queue overflowed (wd is -1 for this event).

in_UNMOUNT :: Mask EventFlag

File system containing watched object was unmounted.