-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Thinner binding to the Linux Kernel's inotify interface -- -- This is a binding for GHC 7 to the Linux Kernel's inotify interface, -- which provides notifications to applications regarding file system -- events, such as file creation, modification, deletion, etc. -- -- Some of the advantages over hinotify are: -- --
    --
  1. linux-inotify provides a plain getEvent operator that blocks, -- instead of implementing a callback API.
    2. --
  2. linux-inotify avoids most of GHC's standard IO handling code, -- relying on plain system calls with minimal overhead in Haskell-land. -- (However, it still does make good use of GHC's IO manager via -- nonblocking inotify sockets and threadWaitRead, so getEvent is still -- efficient.)
    3. --
  3. linux-inotify does not call forkIO, which means less context -- switching and scheduling overhead, especially in contexts where -- hinotify's particular event router isn't a very good fit for your -- application; e.g. you are implementing a following log file -- processor.
    4. --
-- -- Some of the disadvantages compared to hinotify are: -- --
    --
  1. Due to the use of inotify_init1, `linux-inotify` currently -- requires linux 2.6.27 or later, even though inotify support -- debuted in linux 2.6.13. You can check which version of linux is on a -- machine via uname `-a`. I would like to fix this at some point, -- but it isn't a personal priority.
    2. --
  2. `linux-inotify` requires GHC 7.8.1 or later, whereas -- hinotify works with many versions of GHC 6. I have no plans to -- fix this.
    3. --
@package linux-inotify @version 0.3.0.2 -- | 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 module System.Linux.Inotify -- | 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. data Inotify -- | 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. newtype Watch Watch :: CInt -> Watch data Event Event :: {-# UNPACK #-} !Watch -> {-# UNPACK #-} !Mask EventFlag -> {-# UNPACK #-} !Cookie -> {-# UNPACK #-} !ByteString -> Event -- | Identifies the watch for which this event occurs. It is one of the -- watch descriptors returned by a previous call to addWatch or -- addWatch_. [wd] :: Event -> {-# UNPACK #-} !Watch -- | contains bits that describe the event that occurred [mask] :: Event -> {-# UNPACK #-} !Mask EventFlag -- | 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. [cookie] :: Event -> {-# UNPACK #-} !Cookie -- | 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 -- getFileSystemEncoding and then unpack it to a String or -- decode it using the text package. [name] :: Event -> {-# UNPACK #-} !ByteString -- | 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. newtype Mask a Mask :: Word32 -> Mask a -- | Compute the intersection (bitwise and) of two masks isect :: Mask a -> Mask a -> Mask a -- | Are the bits of the first mask a subset of the bits of the second? isSubset :: Mask a -> Mask a -> Bool -- | Do the two masks have any bits in common? hasOverlap :: Mask a -> Mask a -> Bool -- | An empty type used to denote Mask values that can be sent to -- the kernel when setting up an inotify watch. data WatchFlag -- | An empty type used to denote Mask values that can be received -- from the kernel in an inotify event message. data EventFlag -- | A newtype wrapper for the cookie field of the Event. newtype Cookie Cookie :: Word32 -> Cookie -- | Creates an inotify socket descriptor that watches can be added to and -- events can be read from. init :: IO Inotify -- | Closes an inotify descriptor, freeing the resources associated with -- it. This will also raise an IOException in any threads that are -- blocked on getEvent. -- -- Attempting to use a descriptor after it is closed will safely raise an -- exception. It is perfectly safe to call close multiple times, -- which is idempotent and will not result in an exception. -- -- Descriptors will be closed after they are garbage collected, via a -- finalizer, although it is often preferable to call close -- yourself. close :: Inotify -> IO () -- | Has the inotify descriptor been closed? isClosed :: Inotify -> IO Bool -- | Creates an inotify socket descriptor with custom configuration -- options. Calls inotify_init1(IN_NONBLOCK | IN_CLOEXEC). initWith :: InotifyOptions -> IO Inotify -- | Additional configuration options for creating an Inotify descriptor. newtype InotifyOptions InotifyOptions :: Int -> InotifyOptions -- | The size of the buffer used to receive events from the kernel. This is -- an artifact of this binding, not inotify itself. [bufferSize] :: InotifyOptions -> Int -- | Default configuration options defaultInotifyOptions :: InotifyOptions -- | 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 -> FilePath -> 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. addWatch_ :: Inotify -> RawFilePath -> Mask WatchFlag -> IO Watch -- | 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. rmWatch :: Inotify -> Watch -> IO () -- | Returns an inotify event, blocking until one is available. -- -- If the inotify descriptor is closed, this function will return an -- event from the buffer, if available. Otherwise, it will throw an -- IOException. -- -- It is safe to call this function from multiple threads at the same -- time. getEvent :: Inotify -> IO Event -- | Returns an inotify event only if one is immediately available. -- -- If the inotify descriptor is closed, this function will return an -- event from the buffer, if available. Otherwise, it will throw an -- IOException. -- -- One possible downside of the current implementation is that returning -- Nothing necessarily results in a system call. -- -- It is safe to call this function from multiple threads at the same -- time. getEventNonBlocking :: Inotify -> IO (Maybe Event) -- | Returns an inotify event only if one is available in 'Inotify'\'s -- buffer. This won't ever make a system call, and should not ever throw -- an exception. -- -- It is safe to call this function from multiple threads at the same -- time. getEventFromBuffer :: Inotify -> IO (Maybe Event) -- | 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. -- -- If the inotify descriptor is closed, this function will return an -- event from the buffer, if available. Otherwise, it will throw an -- IOException. -- -- It is safe to call this function from multiple threads at the same -- time. peekEvent :: Inotify -> IO 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 this read will not result -- in a system call. -- -- If the inotify descriptor is closed, this function will return an -- event from the buffer, if available. Otherwise, it will throw an -- IOException. -- -- One possible downside of the current implementation is that returning -- Nothing necessarily results in a system call. -- -- It is safe to call this function from multiple threads at the same -- time. peekEventNonBlocking :: Inotify -> IO (Maybe Event) -- | Returns an inotify event only if one is available in 'Inotify'\'s -- buffer. This won't ever make a system call, and should not ever throw -- an exception. -- -- 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. -- -- It is safe to call this function from multiple threads at the same -- time. peekEventFromBuffer :: Inotify -> IO (Maybe Event) -- | File was accessed. Includes the files of a watched directory. in_ACCESS :: 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_ATTRIB :: 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 :: Mask a -- | File opened for writing was closed. Includes the files of a watched -- directory. in_CLOSE_WRITE :: Mask a -- | File not opened for writing was closed. Includes the files of a -- watched directory. in_CLOSE_NOWRITE :: Mask a -- | File/directory created in watched directory. in_CREATE :: Mask a -- | File/directory deleted from watched directory. in_DELETE :: Mask a -- | Watched file/directory was itself deleted. in_DELETE_SELF :: Mask a -- | File was modified. Includes the files of a watched directory. in_MODIFY :: Mask a -- | Watched file/directory was itself moved. in_MOVE_SELF :: 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_MOVE :: Mask a -- | File moved out of watched directory. Includes the files of a watched -- directory. in_MOVED_FROM :: Mask a -- | File moved into watched directory. Includes the files of a watched -- directory. in_MOVED_TO :: Mask a -- | File was opened. Includes the files of a watched directory. in_OPEN :: Mask a -- | A union of all flags above; this is not a separate flag but a -- convenience definition. in_ALL_EVENTS :: Mask a -- | (since Linux 2.6.15) Don't dereference pathname if it is a symbolic -- link. in_DONT_FOLLOW :: 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_EXCL_UNLINK :: Mask WatchFlag -- | Add (OR) events to watch mask for this pathname if it already exists -- (instead of replacing mask). in_MASK_ADD :: Mask WatchFlag -- | Monitor pathname for one event, then remove from watch list. in_ONESHOT :: Mask WatchFlag -- | (since Linux 2.6.15) Only watch pathname if it is a directory. in_ONLYDIR :: Mask WatchFlag -- | Watch was removed explicitly (rmWatch) or automatically (file -- was deleted, or file system was unmounted). in_IGNORED :: Mask EventFlag -- | Subject of this event is a directory. in_ISDIR :: Mask EventFlag -- | Event queue overflowed (wd is -1 for this event). The size of the -- queue is available at -- procsysfsinotify/max_queued_events. in_Q_OVERFLOW :: Mask EventFlag -- | File system containing watched object was unmounted. in_UNMOUNT :: Mask EventFlag instance GHC.Show.Show System.Linux.Inotify.Event instance GHC.Classes.Eq System.Linux.Inotify.Event instance Data.Hashable.Class.Hashable System.Linux.Inotify.Cookie instance GHC.Show.Show System.Linux.Inotify.Cookie instance GHC.Classes.Ord System.Linux.Inotify.Cookie instance GHC.Classes.Eq System.Linux.Inotify.Cookie instance GHC.Show.Show (System.Linux.Inotify.Mask a) instance GHC.Classes.Eq (System.Linux.Inotify.Mask a) instance GHC.Show.Show System.Linux.Inotify.Watch instance GHC.Classes.Ord System.Linux.Inotify.Watch instance GHC.Classes.Eq System.Linux.Inotify.Watch instance GHC.Classes.Eq System.Linux.Inotify.Inotify instance GHC.Base.Semigroup (System.Linux.Inotify.Mask a) instance GHC.Base.Monoid (System.Linux.Inotify.Mask a) instance Data.Hashable.Class.Hashable System.Linux.Inotify.Watch instance GHC.Show.Show System.Linux.Inotify.Inotify instance GHC.Classes.Ord System.Linux.Inotify.Inotify