diff options
Diffstat (limited to 'shared/inotify/doc/man/man3/Inotify.3')
| -rw-r--r-- | shared/inotify/doc/man/man3/Inotify.3 | 376 |
1 files changed, 215 insertions, 161 deletions
diff --git a/shared/inotify/doc/man/man3/Inotify.3 b/shared/inotify/doc/man/man3/Inotify.3 index 23188784..84579325 100644 --- a/shared/inotify/doc/man/man3/Inotify.3 +++ b/shared/inotify/doc/man/man3/Inotify.3 @@ -1,4 +1,4 @@ -.TH "Inotify" 3 "18 Apr 2007" "Version 0.7.2" "inotify-cxx" \" -*- nroff -*- +.TH "Inotify" 3 "9 Dec 2009" "Version 0.7.3" "inotify-cxx" \" -*- nroff -*- .ad l .nh .SH NAME @@ -46,11 +46,11 @@ Inotify \- inotify class .br .RI "\fIRemoves all watches. \fP" .ti -1c -.RI "size_t \fBGetWatchCount\fP () const" +.RI "size_t \fBGetWatchCount\fP () const " .br .RI "\fIReturns the count of watches. \fP" .ti -1c -.RI "size_t \fBGetEnabledCount\fP () const" +.RI "size_t \fBGetEnabledCount\fP () const " .br .RI "\fIReturns the count of enabled watches. \fP" .ti -1c @@ -86,7 +86,7 @@ Inotify \- inotify class .br .RI "\fISearches for a watch by a filesystem path. \fP" .ti -1c -.RI "int \fBGetDescriptor\fP () const" +.RI "int \fBGetDescriptor\fP () const " .br .RI "\fIReturns the file descriptor. \fP" .ti -1c @@ -134,6 +134,37 @@ Inotify \- inotify class .br .RI "\fISets the maximum number of inotify watches per instance. \fP" .in -1c +.SS "Static Private Member Functions" + +.in +1c +.ti -1c +.RI "static std::string \fBGetCapabilityPath\fP (\fBInotifyCapability_t\fP cap) throw (InotifyException)" +.br +.in -1c +.SS "Private Attributes" + +.in +1c +.ti -1c +.RI "int \fBm_fd\fP" +.br +.RI "\fIfile descriptor \fP" +.ti -1c +.RI "\fBIN_WATCH_MAP\fP \fBm_watches\fP" +.br +.RI "\fIwatches (by descriptors) \fP" +.ti -1c +.RI "\fBIN_WP_MAP\fP \fBm_paths\fP" +.br +.RI "\fIwatches (by paths) \fP" +.ti -1c +.RI "unsigned char \fBm_buf\fP [INOTIFY_BUFLEN]" +.br +.RI "\fIbuffer for events \fP" +.ti -1c +.RI "std::deque< \fBInotifyEvent\fP > \fBm_events\fP" +.br +.RI "\fIevent queue \fP" +.in -1c .SS "Friends" .in +1c @@ -148,7 +179,6 @@ inotify class It holds information about the inotify device descriptor and manages the event queue. .PP If the INOTIFY_THREAD_SAFE is defined this class is thread-safe. -.PP .SH "Constructor & Destructor Documentation" .PP .SS "Inotify::Inotify () throw (\fBInotifyException\fP)" @@ -170,17 +200,13 @@ Destructor. Calls \fBClose()\fP due to clean-up. .SH "Member Function Documentation" .PP -.SS "void Inotify::Close ()" -.PP -Removes all watches and closes the inotify device. -.PP -.SS "void Inotify::Add (\fBInotifyWatch\fP * pWatch) throw (\fBInotifyException\fP)" +.SS "void Inotify::Add (\fBInotifyWatch\fP & rWatch) throw (\fBInotifyException\fP)\fC [inline]\fP" .PP Adds a new watch. .PP \fBParameters:\fP .RS 4 -\fIpWatch\fP inotify watch +\fIrWatch\fP inotify watch .RE .PP \fBExceptions:\fP @@ -189,13 +215,13 @@ Adds a new watch. .RE .PP -.SS "void Inotify::Add (\fBInotifyWatch\fP & rWatch) throw (\fBInotifyException\fP)\fC [inline]\fP" +.SS "void Inotify::Add (\fBInotifyWatch\fP * pWatch) throw (\fBInotifyException\fP)" .PP Adds a new watch. .PP \fBParameters:\fP .RS 4 -\fIrWatch\fP inotify watch +\fIpWatch\fP inotify watch .RE .PP \fBExceptions:\fP @@ -204,58 +230,85 @@ Adds a new watch. .RE .PP -.SS "void Inotify::Remove (\fBInotifyWatch\fP * pWatch) throw (\fBInotifyException\fP)" +.SS "void Inotify::Close ()" .PP -Removes a watch. +Removes all watches and closes the inotify device. .PP -If the given watch is not present it does nothing. +.SS "\fBInotifyWatch\fP * Inotify::FindWatch (const std::string & rPath)" +.PP +Searches for a watch by a filesystem path. +.PP +It tries to find a watch by the given filesystem path. .PP \fBParameters:\fP .RS 4 -\fIpWatch\fP inotify watch +\fIrPath\fP filesystem path .RE .PP -\fBExceptions:\fP +\fBReturns:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if removing failed +pointer to a watch; NULL if no such watch exists +.RE +.PP +\fBAttention:\fP +.RS 4 +The path must be exactly identical to the one used for the searched watch. Be careful about absolute/relative and case-insensitive paths. .RE .PP -.SS "void Inotify::Remove (\fBInotifyWatch\fP & rWatch) throw (\fBInotifyException\fP)\fC [inline]\fP" +.SS "\fBInotifyWatch\fP * Inotify::FindWatch (int iDescriptor)" .PP -Removes a watch. +Searches for a watch by a watch descriptor. .PP -If the given watch is not present it does nothing. +It tries to find a watch by the given descriptor. .PP \fBParameters:\fP .RS 4 -\fIrWatch\fP inotify watch +\fIiDescriptor\fP watch descriptor .RE .PP -\fBExceptions:\fP +\fBReturns:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if removing failed +pointer to a watch; NULL if no such watch exists .RE .PP -.SS "void Inotify::RemoveAll ()" +.SS "uint32_t Inotify::GetCapability (\fBInotifyCapability_t\fP cap) throw (\fBInotifyException\fP)\fC [static]\fP" .PP -Removes all watches. +Acquires a particular inotify capability/limit. .PP -.SS "size_t Inotify::GetWatchCount () const\fC [inline]\fP" +\fBParameters:\fP +.RS 4 +\fIcap\fP capability/limit identifier +.RE .PP -Returns the count of watches. +\fBReturns:\fP +.RS 4 +capability/limit value +.RE .PP -This is the total count of all watches (regardless whether enabled or not). +\fBExceptions:\fP +.RS 4 +\fI\fBInotifyException\fP\fP thrown if the given value cannot be acquired +.RE +.PP + +.SS "std::string Inotify::GetCapabilityPath (\fBInotifyCapability_t\fP cap) throw (\fBInotifyException\fP)\fC [static, private]\fP" +.PP +.SS "int Inotify::GetDescriptor () const\fC [inline]\fP" +.PP +Returns the file descriptor. +.PP +The descriptor can be used in standard low-level file functions (poll(), select(), fcntl() etc.). .PP \fBReturns:\fP .RS 4 -count of watches +valid file descriptor or -1 for inactive object .RE .PP \fBSee also:\fP .RS 4 -\fBGetEnabledCount()\fP +\fBSetNonBlock()\fP .RE .PP @@ -274,37 +327,20 @@ count of enabled watches .RE .PP -.SS "void Inotify::WaitForEvents (bool fNoIntr = \fCfalse\fP) throw (\fBInotifyException\fP)" +.SS "bool Inotify::GetEvent (\fBInotifyEvent\fP & rEvt) throw (\fBInotifyException\fP)\fC [inline]\fP" .PP -Waits for inotify events. +Extracts a queued inotify event. .PP -It waits until one or more events occur. When called in nonblocking mode it only retrieves occurred events to the internal queue and exits. +The extracted event is removed from the queue. .PP \fBParameters:\fP .RS 4 -\fIfNoIntr\fP if true it re-calls the system call after a handled signal +\fIrEvt\fP event object .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if reading events failed -.RE -.PP -\fBSee also:\fP -.RS 4 -\fBSetNonBlock()\fP -.RE -.PP - -.SS "size_t Inotify::GetEventCount ()\fC [inline]\fP" -.PP -Returns the count of received and queued events. -.PP -This number is related to the events in the queue inside this object, not to the events pending in the kernel. -.PP -\fBReturns:\fP -.RS 4 -count of events +\fI\fBInotifyException\fP\fP thrown only in very anomalous cases .RE .PP @@ -325,181 +361,156 @@ The extracted event is removed from the queue. If the pointer is NULL it does no .RE .PP -.SS "bool Inotify::GetEvent (\fBInotifyEvent\fP & rEvt) throw (\fBInotifyException\fP)\fC [inline]\fP" -.PP -Extracts a queued inotify event. +.SS "size_t Inotify::GetEventCount ()\fC [inline]\fP" .PP -The extracted event is removed from the queue. +Returns the count of received and queued events. .PP -\fBParameters:\fP -.RS 4 -\fIrEvt\fP event object -.RE +This number is related to the events in the queue inside this object, not to the events pending in the kernel. .PP -\fBExceptions:\fP +\fBReturns:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown only in very anomalous cases +count of events .RE .PP -.SS "bool Inotify::PeekEvent (\fBInotifyEvent\fP * pEvt) throw (\fBInotifyException\fP)" -.PP -Extracts a queued inotify event (without removing). +.SS "static uint32_t Inotify::GetMaxEvents () throw (\fBInotifyException\fP)\fC [inline, static]\fP" .PP -The extracted event stays in the queue. If the pointer is NULL it does nothing. +Returns the maximum number of events in the kernel queue. .PP -\fBParameters:\fP +\fBReturns:\fP .RS 4 -\fIpEvt\fP event object +maximum number of events in the kernel queue .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if the provided pointer is NULL +\fI\fBInotifyException\fP\fP thrown if the given value cannot be acquired .RE .PP -.SS "bool Inotify::PeekEvent (\fBInotifyEvent\fP & rEvt) throw (\fBInotifyException\fP)\fC [inline]\fP" +.SS "static uint32_t Inotify::GetMaxInstances () throw (\fBInotifyException\fP)\fC [inline, static]\fP" .PP -Extracts a queued inotify event (without removing). +Returns the maximum number of inotify instances per process. .PP -The extracted event stays in the queue. +It means the maximum number of open inotify file descriptors per running process. .PP -\fBParameters:\fP +\fBReturns:\fP .RS 4 -\fIrEvt\fP event object +maximum number of inotify instances .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown only in very anomalous cases +\fI\fBInotifyException\fP\fP thrown if the given value cannot be acquired .RE .PP -.SS "\fBInotifyWatch\fP * Inotify::FindWatch (int iDescriptor)" +.SS "static uint32_t Inotify::GetMaxWatches () throw (\fBInotifyException\fP)\fC [inline, static]\fP" .PP -Searches for a watch by a watch descriptor. +Returns the maximum number of inotify watches per instance. .PP -It tries to find a watch by the given descriptor. +It means the maximum number of inotify watches per inotify file descriptor. .PP -\fBParameters:\fP +\fBReturns:\fP .RS 4 -\fIiDescriptor\fP watch descriptor +maximum number of inotify watches .RE .PP -\fBReturns:\fP +\fBExceptions:\fP .RS 4 -pointer to a watch; NULL if no such watch exists +\fI\fBInotifyException\fP\fP thrown if the given value cannot be acquired .RE .PP -.SS "\fBInotifyWatch\fP * Inotify::FindWatch (const std::string & rPath)" -.PP -Searches for a watch by a filesystem path. +.SS "size_t Inotify::GetWatchCount () const\fC [inline]\fP" .PP -It tries to find a watch by the given filesystem path. +Returns the count of watches. .PP -\fBParameters:\fP -.RS 4 -\fIrPath\fP filesystem path -.RE +This is the total count of all watches (regardless whether enabled or not). .PP \fBReturns:\fP .RS 4 -pointer to a watch; NULL if no such watch exists +count of watches .RE .PP -\fBAttention:\fP +\fBSee also:\fP .RS 4 -The path must be exactly identical to the one used for the searched watch. Be careful about absolute/relative and case-insensitive paths. +\fBGetEnabledCount()\fP .RE .PP -.SS "int Inotify::GetDescriptor () const\fC [inline]\fP" +.SS "bool Inotify::PeekEvent (\fBInotifyEvent\fP & rEvt) throw (\fBInotifyException\fP)\fC [inline]\fP" .PP -Returns the file descriptor. +Extracts a queued inotify event (without removing). .PP -The descriptor can be used in standard low-level file functions (poll(), select(), fcntl() etc.). +The extracted event stays in the queue. .PP -\fBReturns:\fP +\fBParameters:\fP .RS 4 -valid file descriptor or -1 for inactive object +\fIrEvt\fP event object .RE .PP -\fBSee also:\fP +\fBExceptions:\fP .RS 4 -\fBSetNonBlock()\fP +\fI\fBInotifyException\fP\fP thrown only in very anomalous cases .RE .PP -.SS "void Inotify::SetNonBlock (bool fNonBlock) throw (\fBInotifyException\fP)" -.PP -Enables/disables non-blocking mode. +.SS "bool Inotify::PeekEvent (\fBInotifyEvent\fP * pEvt) throw (\fBInotifyException\fP)" .PP -Use this mode if you want to monitor the descriptor (acquired thru \fBGetDescriptor()\fP) in functions such as poll(), select() etc. +Extracts a queued inotify event (without removing). .PP -Non-blocking mode is disabled by default. +The extracted event stays in the queue. If the pointer is NULL it does nothing. .PP \fBParameters:\fP .RS 4 -\fIfNonBlock\fP enable/disable non-blocking mode +\fIpEvt\fP event object .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if setting mode failed -.RE -.PP -\fBSee also:\fP -.RS 4 -\fBGetDescriptor()\fP, \fBSetCloseOnExec()\fP +\fI\fBInotifyException\fP\fP thrown if the provided pointer is NULL .RE .PP -.SS "void Inotify::SetCloseOnExec (bool fClOnEx) throw (\fBInotifyException\fP)" -.PP -Enables/disables closing on exec. +.SS "void Inotify::Remove (\fBInotifyWatch\fP & rWatch) throw (\fBInotifyException\fP)\fC [inline]\fP" .PP -Enable this if you want to close the descriptor when executing another program. Otherwise, the descriptor will be inherited. +Removes a watch. .PP -Closing on exec is disabled by default. +If the given watch is not present it does nothing. .PP \fBParameters:\fP .RS 4 -\fIfClOnEx\fP enable/disable closing on exec +\fIrWatch\fP inotify watch .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if setting failed -.RE -.PP -\fBSee also:\fP -.RS 4 -\fBGetDescriptor()\fP, \fBSetNonBlock()\fP +\fI\fBInotifyException\fP\fP thrown if removing failed .RE .PP -.SS "uint32_t Inotify::GetCapability (\fBInotifyCapability_t\fP cap) throw (\fBInotifyException\fP)\fC [static]\fP" +.SS "void Inotify::Remove (\fBInotifyWatch\fP * pWatch) throw (\fBInotifyException\fP)" .PP -Acquires a particular inotify capability/limit. +Removes a watch. .PP -\fBParameters:\fP -.RS 4 -\fIcap\fP capability/limit identifier -.RE +If the given watch is not present it does nothing. .PP -\fBReturns:\fP +\fBParameters:\fP .RS 4 -capability/limit value +\fIpWatch\fP inotify watch .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if the given value cannot be acquired +\fI\fBInotifyException\fP\fP thrown if removing failed .RE .PP +.SS "void Inotify::RemoveAll ()" +.PP +Removes all watches. +.PP .SS "void Inotify::SetCapability (\fBInotifyCapability_t\fP cap, uint32_t val) throw (\fBInotifyException\fP)\fC [static]\fP" .PP Modifies a particular inotify capability/limit. @@ -522,18 +533,27 @@ Using this function requires root privileges. Beware of setting extensive values .RE .PP -.SS "static uint32_t Inotify::GetMaxEvents () throw (\fBInotifyException\fP)\fC [inline, static]\fP" +.SS "void Inotify::SetCloseOnExec (bool fClOnEx) throw (\fBInotifyException\fP)" .PP -Returns the maximum number of events in the kernel queue. +Enables/disables closing on exec. .PP -\fBReturns:\fP +Enable this if you want to close the descriptor when executing another program. Otherwise, the descriptor will be inherited. +.PP +Closing on exec is disabled by default. +.PP +\fBParameters:\fP .RS 4 -maximum number of events in the kernel queue +\fIfClOnEx\fP enable/disable closing on exec .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if the given value cannot be acquired +\fI\fBInotifyException\fP\fP thrown if setting failed +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBGetDescriptor()\fP, \fBSetNonBlock()\fP .RE .PP @@ -557,26 +577,29 @@ Using this function requires root privileges. Beware of setting extensive values .RE .PP -.SS "static uint32_t Inotify::GetMaxInstances () throw (\fBInotifyException\fP)\fC [inline, static]\fP" -.PP -Returns the maximum number of inotify instances per process. +.SS "static void Inotify::SetMaxInstances (uint32_t val) throw (\fBInotifyException\fP)\fC [inline, static]\fP" .PP -It means the maximum number of open inotify file descriptors per running process. +Sets the maximum number of inotify instances per process. .PP -\fBReturns:\fP +\fBParameters:\fP .RS 4 -maximum number of inotify instances +\fIval\fP new value .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if the given value cannot be acquired +\fI\fBInotifyException\fP\fP thrown if the given value cannot be set +.RE +.PP +\fBAttention:\fP +.RS 4 +Using this function requires root privileges. Beware of setting extensive values - the greater value is set here the more physical memory may be used for the inotify infrastructure. .RE .PP -.SS "static void Inotify::SetMaxInstances (uint32_t val) throw (\fBInotifyException\fP)\fC [inline, static]\fP" +.SS "static void Inotify::SetMaxWatches (uint32_t val) throw (\fBInotifyException\fP)\fC [inline, static]\fP" .PP -Sets the maximum number of inotify instances per process. +Sets the maximum number of inotify watches per instance. .PP \fBParameters:\fP .RS 4 @@ -594,40 +617,49 @@ Using this function requires root privileges. Beware of setting extensive values .RE .PP -.SS "static uint32_t Inotify::GetMaxWatches () throw (\fBInotifyException\fP)\fC [inline, static]\fP" +.SS "void Inotify::SetNonBlock (bool fNonBlock) throw (\fBInotifyException\fP)" .PP -Returns the maximum number of inotify watches per instance. +Enables/disables non-blocking mode. .PP -It means the maximum number of inotify watches per inotify file descriptor. +Use this mode if you want to monitor the descriptor (acquired thru \fBGetDescriptor()\fP) in functions such as poll(), select() etc. .PP -\fBReturns:\fP +Non-blocking mode is disabled by default. +.PP +\fBParameters:\fP .RS 4 -maximum number of inotify watches +\fIfNonBlock\fP enable/disable non-blocking mode .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if the given value cannot be acquired +\fI\fBInotifyException\fP\fP thrown if setting mode failed +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBGetDescriptor()\fP, \fBSetCloseOnExec()\fP .RE .PP -.SS "static void Inotify::SetMaxWatches (uint32_t val) throw (\fBInotifyException\fP)\fC [inline, static]\fP" +.SS "void Inotify::WaitForEvents (bool fNoIntr = \fCfalse\fP) throw (\fBInotifyException\fP)" .PP -Sets the maximum number of inotify watches per instance. +Waits for inotify events. +.PP +It waits until one or more events occur. When called in nonblocking mode it only retrieves occurred events to the internal queue and exits. .PP \fBParameters:\fP .RS 4 -\fIval\fP new value +\fIfNoIntr\fP if true it re-calls the system call after a handled signal .RE .PP \fBExceptions:\fP .RS 4 -\fI\fBInotifyException\fP\fP thrown if the given value cannot be set +\fI\fBInotifyException\fP\fP thrown if reading events failed .RE .PP -\fBAttention:\fP +\fBSee also:\fP .RS 4 -Using this function requires root privileges. Beware of setting extensive values - the greater value is set here the more physical memory may be used for the inotify infrastructure. +\fBSetNonBlock()\fP .RE .PP @@ -635,6 +667,28 @@ Using this function requires root privileges. Beware of setting extensive values .PP .SS "friend class \fBInotifyWatch\fP\fC [friend]\fP" .PP +.SH "Member Data Documentation" +.PP +.SS "unsigned char \fBInotify::m_buf\fP[INOTIFY_BUFLEN]\fC [private]\fP" +.PP +buffer for events +.PP +.SS "std::deque<\fBInotifyEvent\fP> \fBInotify::m_events\fP\fC [private]\fP" +.PP +event queue +.PP +.SS "int \fBInotify::m_fd\fP\fC [private]\fP" +.PP +file descriptor +.PP +.SS "\fBIN_WP_MAP\fP \fBInotify::m_paths\fP\fC [private]\fP" +.PP +watches (by paths) +.PP +.SS "\fBIN_WATCH_MAP\fP \fBInotify::m_watches\fP\fC [private]\fP" +.PP +watches (by descriptors) +.PP .SH "Author" |