linux-inotify-0.2.0.1: Thinner binding to the Linux Kernel's inotify interface

Maintainerleon@melding-monads.com
Safe HaskellNone

System.Linux.Inotify

Description

Although this module copies portions of inotify's manual page, it may be useful to consult the original in conjunction with this documentation:

http://man7.org/linux/man-pages/man7/inotify.7.html

Synopsis

Documentation

data Inotify Source

Inotify represents an inotify descriptor, to which watches can be added and events can be read from. Internally, it also includes a buffer of events that have been delivered to the application from the kernel but haven't been processed.

newtype Watch Source

Watch represents a watch descriptor, which is used to identify events and to cancel the watch. Every watch descriptor is associated with a particular inotify descriptor and can only be used with that descriptor; incorrect behavior will otherwise result.

Constructors

Watch CInt 

data Event Source

Constructors

Event 

Fields

wd :: !Watch

Identifies the watch for which this event occurs. It is one of the watch descriptors returned by a previous call to addWatch or addWatch_.

mask :: !(Mask EventFlag)

contains bits that describe the event that occurred

cookie :: !Cookie

A unique integer that connects related events. Currently this is only used for rename events, and allows the resulting pair of in_MOVE_FROM and in_MOVE_TO events to be connected by the application.

name :: !ByteString

The name field is only present when an event is returned for a file inside a watched directory; it identifies the file pathname relative to the watched directory.

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

newtype Mask a Source

Represents the mask, which in inotify terminology is a union of bit flags representing various event types and watch options.

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 Word32 

Instances

Typeable1 Mask 
Eq (Mask a) 
Show (Mask a) 
Monoid (Mask a)

Computes the union of two Masks.

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

Compute the intersection (bitwise and) of two masks

isSubset :: Mask a -> Mask a -> BoolSource

Are the bits of the first mask a subset of the bits of the second?

hasOverlap :: Mask a -> Mask a -> BoolSource

Do the two masks have any bits in common?

data WatchFlag Source

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

data EventFlag Source

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

newtype Cookie Source

A newtype wrapper for the cookie field of the Event.

Constructors

Cookie Word32 

init :: IO InotifySource

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

close :: Inotify -> IO ()Source

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.

initWith :: InotifyOptions -> IO InotifySource

Creates an inotify socket descriptor with custom configuration options. Calls inotify_init1(IN_NONBLOCK | IN_CLOEXEC).

newtype InotifyOptions Source

Additional configuration options for creating an Inotify descriptor.

Constructors

InotifyOptions 

Fields

bufferSize :: Int

The size of the buffer used to receive events from the kernel. This is an artifact of this binding, not inotify itself.

defaultInotifyOptions :: InotifyOptionsSource

Default configuration options

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

Adds a watch on the inotify descriptor, returns a watch descriptor. The mask controls which events are delivered to your application, as well as some additional options. This function is thread safe.

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

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 ()Source

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 EventSource

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)Source

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)Source

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

peekEvent :: Inotify -> IO EventSource

Returns an inotify event, blocking until one is available.

After this returns an event, the next read from the inotify descriptor will return the same event. This 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)Source

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 this 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)Source

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 this read will not result in a system call.

in_ACCESS :: Mask aSource

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

in_ATTRIB :: Mask aSource

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 aSource

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 aSource

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

in_CLOSE_NOWRITE :: Mask aSource

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

in_CREATE :: Mask aSource

File/directory created in watched directory.

in_DELETE :: Mask aSource

File/directory deleted from watched directory.

in_DELETE_SELF :: Mask aSource

Watched file/directory was itself deleted.

in_MODIFY :: Mask aSource

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

in_MOVE_SELF :: Mask aSource

Watched file/directory was itself moved.

in_MOVE :: Mask aSource

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 aSource

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

in_MOVED_TO :: Mask aSource

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

in_OPEN :: Mask aSource

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

in_ALL_EVENTS :: Mask aSource

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

in_DONT_FOLLOW :: Mask WatchFlagSource

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

in_EXCL_UNLINK :: Mask WatchFlagSource

(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 WatchFlagSource

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

in_ONESHOT :: Mask WatchFlagSource

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

in_ONLYDIR :: Mask WatchFlagSource

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

in_IGNORED :: Mask EventFlagSource

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

in_ISDIR :: Mask EventFlagSource

Subject of this event is a directory.

in_Q_OVERFLOW :: Mask EventFlagSource

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

in_UNMOUNT :: Mask EventFlagSource

File system containing watched object was unmounted.