{
    "content": [
        {
            "type": "text",
            "text": "# Linux::Inotify2 (perldoc)\n\n## NAME\n\nLinux::Inotify2 - scalable directory/file change notification\n\n## DESCRIPTION\n\nThis module implements an interface to the Linux 2.6.13 and later Inotify file/directory change\nnotification system.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (2 subsections)\n- **DESCRIPTION** (3 subsections)\n- **SEE ALSO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Linux::Inotify2",
        "section": "",
        "mode": "perldoc",
        "summary": "Linux::Inotify2 - scalable directory/file change notification",
        "synopsis": "",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Callback Interface",
                        "lines": 25
                    },
                    {
                        "name": "Streaming Interface",
                        "lines": 15
                    }
                ]
            },
            {
                "name": "DESCRIPTION",
                "lines": 15,
                "subsections": [
                    {
                        "name": "The Linux::Inotify2 Class",
                        "lines": 119
                    },
                    {
                        "name": "The Linux::Inotify2::Event Class",
                        "lines": 51
                    },
                    {
                        "name": "The Linux::Inotify2::Watch Class",
                        "lines": 21
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 3,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Linux::Inotify2 - scalable directory/file change notification\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "",
                "subsections": [
                    {
                        "name": "Callback Interface",
                        "content": "use Linux::Inotify2;\n\n# create a new object\nmy $inotify = new Linux::Inotify2\nor die \"unable to create new inotify object: $!\";\n\n# add watchers\n$inotify->watch (\"/etc/passwd\", INACCESS, sub {\nmy $e = shift;\nmy $name = $e->fullname;\nprint \"$name was accessed\\n\" if $e->INACCESS;\nprint \"$name is no longer mounted\\n\" if $e->INUNMOUNT;\nprint \"$name is gone\\n\" if $e->INIGNORED;\nprint \"events for $name have been lost\\n\" if $e->INQOVERFLOW;\n\n# cancel this watcher: remove no further events\n$e->w->cancel;\n});\n\n# integration into AnyEvent (works with EV, Glib, Tk, POE...)\nmy $inotifyw = AE::io $inotify->fileno, 0, sub { $inotify->poll };\n\n# manual event loop\n$inotify->poll while 1;\n"
                    },
                    {
                        "name": "Streaming Interface",
                        "content": "use Linux::Inotify2;\n\n# create a new object\nmy $inotify = new Linux::Inotify2\nor die \"Unable to create new inotify object: $!\";\n\n# create watch\n$inotify->watch (\"/etc/passwd\", INACCESS)\nor die \"watch creation failed\";\n\nwhile () {\nmy @events = $inotify->read;\nprintf \"mask\\t%d\\n\", $->mask foreach @events;\n}\n"
                    }
                ]
            },
            "DESCRIPTION": {
                "content": "This module implements an interface to the Linux 2.6.13 and later Inotify file/directory change\nnotification system.\n\nIt has a number of advantages over the Linux::Inotify module:\n\n- it is portable (Linux::Inotify only works on x86)\n- the equivalent of fullname works correctly\n- it is better documented\n- it has callback-style interface, which is better suited for\nintegration.\n\nAs for the inotify API itself - it is a very tricky, and somewhat unreliable API. For a good\noverview of the challenges you might run into, see this LWN article:\n<https://lwn.net/Articles/605128/>.\n",
                "subsections": [
                    {
                        "name": "The Linux::Inotify2 Class",
                        "content": "my $inotify = new Linux::Inotify2\nCreate a new notify object and return it. A notify object is kind of a container that stores\nwatches on file system names and is responsible for handling event data.\n\nOn error, \"undef\" is returned and $! will be set accordingly. The following errors are\ndocumented:\n\nENFILE   The system limit on the total number of file descriptors has been reached.\nEMFILE   The user limit on the total number of inotify instances has been reached.\nENOMEM   Insufficient kernel memory is available.\n\nExample:\n\nmy $inotify = new Linux::Inotify2\nor die \"Unable to create new inotify object: $!\";\n\n$watch = $inotify->watch ($name, $mask[, $cb])\nAdd a new watcher to the given notifier. The watcher will create events on the pathname\n$name as given in $mask, which can be any of the following constants (all exported by\ndefault) ORed together. Constants unavailable on your system will evaluate to 0.\n\n\"file\" refers to any file system object in the watched object (always a directory), that is\nfiles, directories, symlinks, device nodes etc., while \"object\" refers to the object the\nwatcher has been set on itself:\n\nINACCESS            object was accessed\nINMODIFY            object was modified\nINATTRIB            object metadata changed\nINCLOSEWRITE       writable fd to file / to object was closed\nINCLOSENOWRITE     readonly fd to file / to object closed\nINOPEN              object was opened\nINMOVEDFROM        file was moved from this object (directory)\nINMOVEDTO          file was moved to this object (directory)\nINCREATE            file was created in this object (directory)\nINDELETE            file was deleted from this object (directory)\nINDELETESELF       object itself was deleted\nINMOVESELF         object itself was moved\nINALLEVENTS        all of the above events\n\nINONESHOT           only send event once\nINONLYDIR           only watch the path if it is a directory\nINDONTFOLLOW       don't follow a sym link (Linux 2.6.15+)\nINEXCLUNLINK       don't create events for unlinked objects (Linux 2.6.36+)\nINMASKADD          not supported with the current version of this module\n\nINCLOSE             same as INCLOSEWRITE | INCLOSENOWRITE\nINMOVE              same as INMOVEDFROM | INMOVEDTO\n\n$cb is a perl code reference that, if given, is called for each event. It receives a\n\"Linux::Inotify2::Event\" object.\n\nThe returned $watch object is of class \"Linux::Inotify2::Watch\".\n\nOn error, \"undef\" is returned and $! will be set accordingly. The following errors are\ndocumented:\n\nEBADF    The given file descriptor is not valid.\nEINVAL   The given event mask contains no legal events.\nENOMEM   Insufficient kernel memory was available.\nENOSPC   The user limit on the total number of inotify watches was reached or the kernel failed to allocate a needed resource.\nEACCESS  Read access to the given file is not permitted.\n\nExample, show when \"/etc/passwd\" gets accessed and/or modified once:\n\n$inotify->watch (\"/etc/passwd\", INACCESS | INMODIFY, sub {\nmy $e = shift;\nprint \"$e->{w}{name} was accessed\\n\" if $e->INACCESS;\nprint \"$e->{w}{name} was modified\\n\" if $e->INMODIFY;\nprint \"$e->{w}{name} is no longer mounted\\n\" if $e->INUNMOUNT;\nprint \"events for $e->{w}{name} have been lost\\n\" if $e->INQOVERFLOW;\n\n$e->w->cancel;\n});\n\n$inotify->fileno\nReturns the file descriptor for this notify object. When in non-blocking mode, you are\nresponsible for calling the \"poll\" method when this file descriptor becomes ready for\nreading.\n\n$inotify->fh\nSimilar to \"fileno\", but returns a perl file handle instead.\n\n$inotify->blocking ($blocking)\nClears ($blocking true) or sets ($blocking false) the \"ONONBLOCK\" flag on the file\ndescriptor.\n\n$count = $inotify->poll\nReads events from the kernel and handles them. If the notify file descriptor is blocking\n(the default), then this method waits for at least one event. Otherwise it returns\nimmediately when no pending events could be read.\n\nReturns the count of events that have been handled (which can be 0 in case events have been\nreceived but have been ignored or handled internally).\n\nCroaks when an error occurs.\n\n@events = $inotify->read\nReads events from the kernel. Blocks when the file descriptor is in blocking mode (default)\nuntil any event arrives. Returns list of \"Linux::Inotify2::Event\" objects or empty list if\nnone (non-blocking mode or events got ignored).\n\nCroaks on error.\n\nNormally you shouldn't use this function, but instead use watcher callbacks and call\n\"->poll\".\n\n$inotify->onoverflow ($cb->($ev))\nSets the callback to be used for overflow handling (default: \"undef\"): When \"read\" receives\nan event with \"INQOVERFLOW\" set, it will invoke this callback with the event.\n\nWhen the callback is \"undef\", then it broadcasts the event to all registered watchers, i.e.,\n\"undef\" is equivalent to:\n\nsub { $inotify->broadcast ($[0]) }\n\n$inotify->broadcast ($ev)\nInvokes all registered watcher callbacks and passes the given event to them. Most useful in\noverflow handlers.\n"
                    },
                    {
                        "name": "The Linux::Inotify2::Event Class",
                        "content": "Objects of this class are handed as first argument to the watcher callback. It has the following\nmembers and methods:\n\n$event->w\n$event->{w}\nThe watcher object for this event, if one is available. Generally, you cna only rely on the\nvalue of this member inside watcher callbacks.\n\n$event->name\n$event->{name}\nThe path of the file system object, relative to the watched name.\n\n$event->fullname\nReturns the \"full\" name of the relevant object, i.e. including the \"name\" member of the\nwatcher (if the watch object is on a directory and a directory entry is affected), or simply\nthe \"name\" member itself when the object is the watch object itself.\n\nThis call requires \"$event->{w}\" to be valid, which is generally only the case within\nwatcher callbacks.\n\n$event->mask\n$event->{mask}\nThe received event mask. In addition to the events described for \"$inotify->watch\", the\nfollowing flags (exported by default) can be set:\n\nINISDIR             event object is a directory\nINQOVERFLOW        event queue overflowed\n\n# when any of the following flags are set,\n# then watchers for this event are automatically canceled\nINUNMOUNT           filesystem for watched object was unmounted\nINIGNORED           file was ignored/is gone (no more events are delivered)\nINONESHOT           only one event was generated\nINQOVERFLOW        queue overflow - event might not be specific to a watcher\n\n$event->INxxx\nReturns a boolean that returns true if the event mask contains any events specified by the\nmask. All of the \"INxxx\" constants can be used as methods.\n\n$event->cookie\n$event->{cookie}\nThe event cookie to \"synchronize two events\". Normally zero, this value is set when two\nevents relating to the same file are generated. As far as I know, this only happens for\n\"INMOVEDFROM\" and \"INMOVEDTO\" events, to identify the old and new name of a file.\n\nNote that the inotify API makes it impossible to know whether there will be a \"INMOVEDTO\"\nevent - you might receive only one of the events, and even if you receive both, there might\nbe any number of events in between. The best approach seems to be to implement a small\ntimeout after \"INMOVEDFROM\" to see if a matching \"INMOVEDTO\" event will be received -\n2ms seem to work relatively well.\n"
                    },
                    {
                        "name": "The Linux::Inotify2::Watch Class",
                        "content": "Watcher objects are created by calling the \"watch\" method of a notifier.\n\nIt has the following members and methods:\n\n$watch->name\n$watch->{name}\nThe name as specified in the \"watch\" call. For the object itself, this is the empty string.\nFor directory watches, this is the name of the entry without leading path elements.\n\n$watch->mask\n$watch->{mask}\nThe mask as specified in the \"watch\" call.\n\n$watch->cb ([new callback])\n$watch->{cb}\nThe callback as specified in the \"watch\" call. Can optionally be changed.\n\n$watch->cancel\nCancels/removes this watcher. Future events, even if already queued queued, will not be\nhandled and resources will be freed.\n"
                    }
                ]
            },
            "SEE ALSO": {
                "content": "AnyEvent, Linux::Inotify.\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Marc Lehmann <schmorp@schmorp.de>\nhttp://home.schmorp.de/\n",
                "subsections": []
            }
        }
    }
}