X-Git-Url: http://git.rot13.org/?a=blobdiff_plain;f=userapps%2Fopensource%2Fnet-snmp%2Fman%2Fsnmp_alarm.3.def;fp=userapps%2Fopensource%2Fnet-snmp%2Fman%2Fsnmp_alarm.3.def;h=e4f6f793cd3d92f382276f6ccff6ab54ae178db2;hb=9dffd9f7659a1b28265e0dc9497343eb3d108d02;hp=0000000000000000000000000000000000000000;hpb=e48c2529a5a7e7dbf1797bb6d1bf964bc03e78a7;p=bcm963xx.git

diff --git a/userapps/opensource/net-snmp/man/snmp_alarm.3.def b/userapps/opensource/net-snmp/man/snmp_alarm.3.def
new file mode 100644
index 00000000..e4f6f793
--- /dev/null
+++ b/userapps/opensource/net-snmp/man/snmp_alarm.3.def
@@ -0,0 +1,169 @@
+.TH SNMP_ALARM 3 "07 Mar 2002" VVERSIONINFO "Net-SNMP"
+.UC 5
+.SH NAME
+snmp_alarm_register, snmp_alarm_register_hr, snmp_alarm_unregister - alarm functions
+.SH SYNOPSIS
+.B #include <net-snmp/utilities.h>
+.PP
+.B "unsigned int"
+.br
+.BI "snmp_alarm_register(unsigned int " seconds ","
+.br
+.BI "                    unsigned int " flags ","
+.br
+.BI "                    SNMPAlarmCallback *" f_callback ","
+.br
+.BI "                    void *" clientarg ");"
+.PP
+.B "unsigned int"
+.br
+.BI "snmp_alarm_register_hr(struct timeval " t ","
+.br
+.BI "                       unsigned int " flags ","
+.br
+.BI "                       SNMPAlarmCallback *" f_callback ","
+.br
+.BI "                       void *" clientarg ");"
+.PP
+.B "void
+.br
+.BI "snmp_alarm_unregister(unsigned int " reg ");"
+.SH DESCRIPTION
+.PP
+These functions implement support for a generic timer handling
+mechanism for multiple parts of an application to register function
+callbacks to happen at a particular time in the future.
+.SH USAGE
+.PP
+The usage is fairly simple and straight-forward:  Simply create a
+function you want called back at some point in the future.  The
+function definition should be similar to:
+.RS 4
+.PP
+.BI "void my_callback(unsigned int " reg ", void *" clientarg ");"
+.RE
+.PP
+Then, call
+.B snmp_alarm_register()
+to register your callback to be called
+.I seconds
+from now.  The
+.I flags
+field should either be 
+.I SA_REPEAT
+or
+.I NULL.
+If flags is set with
+.I SA_REPEAT,
+then the registered callback function will be called every
+.I seconds.
+If
+.I flags
+is
+.I NULL
+then the function will only be called once and then removed from the
+alarm system registration.
+.PP
+The
+.I clientarg
+parameter in the registration function is used only by
+the client function and is stored and passed back directly to them on
+every call to the system.
+.PP
+The 
+.B snmp_alarm_register()
+function returns a unique
+.I "unsigned int"
+(which is also passed as the first argument of each callback), which
+can then be used to remove the callback from the queue at a later
+point in the future using the
+.B snmp_alarm_unregister()
+function. If the
+.B snmp_alarm_register()
+call fails it returns zero.  In particular, note that it is entirely
+permissible for an alarm function to unregister itself.
+.PP
+The
+.B snmp_alarm_register_hr()
+function is identical in operation to the
+.B snmp_alarm_register()
+function, but takes a
+.I "struct timeval"
+as a first parameter, and schedules the callback after the period
+represented by
+.I t
+(the letters
+.B hr
+stand for "high resolution").  The operation of this function is
+dependent on the provision of the
+.BR setitimer (2)
+system call by the operating system.  If this system call is not
+available, the alarm will be scheduled as if
+.B snmp_alarm_register()
+had been called with a first argument equal to the value of the
+.I tv_sec
+member of
+.IR "t".
+See, however, the notes below.
+.SH INITIALIZATION
+The
+.B init_snmp()
+function initialises the snmp_alarm subsystem by calling 
+.B init_snmp_alarm()
+and then 
+.B init_alarm_post_config()
+to set up the first timer to initialise the callback function.  These
+two functions should not be used directly by applications.
+.SH "NOTES"
+The default behaviour of the snmp_alarm subsystem is to request
+.I SIGALRM
+signals from the operating system via the
+.BR alarm (2)
+or
+.BR setitimer (2)
+system calls.  This has the disadvantage, however, that no other part
+of the application can use the
+.I SIGLARM
+functionality (or, if some other part of the application
+.I does
+use the
+.I SIGALRM
+functionality, the snmp_alarm subsystem will not work correctly).
+.PP
+If your application runs a 
+.BR select (2)-based
+event loop, however, there is no need to use
+.I SIGALRM
+for the snmp_alarm subsystem, leaving it available for other parts of
+the application.  This is done by making the following call:
+.PP
+.nf
+netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID, 
+                       NETSNMP_DS_LIB_ALARM_DONT_USE_SIG, 1);
+.fi
+.PP
+before calling
+.BR "init_snmp()".
+Then, 
+.BR snmp_select_info()
+takes alarms into account when calculating the timeout value to be
+used for
+.BR select (2).
+All you need to do is call
+.BR run_alarms()
+when
+.BR select (2)
+times out (return value of zero).  This is the approach taken in the
+agent; see
+.IR "snmpd.c".
+Furthermore, when using this method, high resolution alarms do not
+depend on the presence of the
+.BR setitimer (2)
+system call, although overall precision is of course still determined
+by the underlying operating system.  Recommended.
+.SH "SEE ALSO"
+.BR snmp_api "(3), " default_store "(3), " snmp_select_info "(3), "
+.BR alarm "(2), " setitimer "(2), " select "(2)"
+.\" Local Variables:
+.\"  mode: nroff
+.\" End: