SNMP\_ALARM(3) Net-SNMP SNMP\_ALARM(3)

# [NAME](#NAME)

snmp\_alarm\_register, snmp\_alarm\_register\_hr, snmp\_alarm\_unregister - alarm functions

# [SYNOPSIS](#SYNOPSIS)

**#include <net-snmp/utilities.h>**

**unsigned int**  
**snmp\_alarm\_register(unsigned int seconds,**  
**unsigned int flags,**  
**SNMPAlarmCallback \*f\_callback,**  
**void \*clientarg);**

**unsigned int**  
**snmp\_alarm\_register\_hr(struct timeval t,**  
**unsigned int flags,**  
**SNMPAlarmCallback \*f\_callback,**  
**void \*clientarg);**

**void**  
**snmp\_alarm\_unregister(unsigned int reg);**

# [DESCRIPTION](#DESCRIPTION)

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.

# [USAGE](#USAGE)

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:

**void my\_callback(unsigned int reg, void \*clientarg);**

Then, call **snmp\_alarm\_register()** to register your callback to be called *seconds* from now. The *flags* field should either be *SA\_REPEAT* or *NULL.* If flags is set with *SA\_REPEAT,* then the registered callback function will be called every *seconds.* If *flags* is *NULL* then the function will only be called once and then removed from the alarm system registration.

The *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.

The **snmp\_alarm\_register()** function returns a unique *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 **snmp\_alarm\_unregister()** function. If the **snmp\_alarm\_register()** call fails it returns zero. In particular, note that it is entirely permissible for an alarm function to unregister itself.

The **snmp\_alarm\_register\_hr()** function is identical in operation to the **snmp\_alarm\_register()** function, but takes a *struct timeval* as a first parameter, and schedules the callback after the period represented by *t* (the letters **hr** stand for "high resolution"). The operation of this function is dependent on the provision of the [**setitimer**(2)](/man/os/net-snmp/setitimer.2) system call by the operating system. If this system call is not available, the alarm will be scheduled as if **snmp\_alarm\_register()** had been called with a first argument equal to the value of the *tv\_sec* member of *t*. See, however, the notes below.

# [INITIALIZATION](#INITIALIZATION)

The **init\_snmp()** function initialises the snmp\_alarm subsystem by calling **init\_snmp\_alarm()** and then **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.

# [NOTES](#NOTES)

The default behaviour of the snmp\_alarm subsystem is to request *SIGALRM* signals from the operating system via the [**alarm**(2)](/man/os/net-snmp/alarm.2) or [**setitimer**(2)](/man/os/net-snmp/setitimer.2) system calls. This has the disadvantage, however, that no other part of the application can use the *SIGLARM* functionality (or, if some other part of the application *does* use the *SIGALRM* functionality, the snmp\_alarm subsystem will not work correctly).

If your application runs a [**select**(2)](/man/os/net-snmp/select.2)-based event loop, however, there is no need to use *SIGALRM* for the snmp\_alarm subsystem, leaving it available for other parts of the application. This is done by making the following call:

```
netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID, 


                       NETSNMP_DS_LIB_ALARM_DONT_USE_SIG, 1);
```

before calling **init\_snmp()**. Then, **snmp\_select\_info()** takes alarms into account when calculating the timeout value to be used for [**select**(2)](/man/os/net-snmp/select.2). All you need to do is call **run\_alarms()** when [**select**(2)](/man/os/net-snmp/select.2) times out (return value of zero). This is the approach taken in the agent; see *snmpd.c*. Furthermore, when using this method, high resolution alarms do not depend on the presence of the [**setitimer**(2)](/man/os/net-snmp/setitimer.2) system call, although overall precision is of course still determined by the underlying operating system. Recommended.

# [SEE ALSO](#SEE_ALSO)

[**netsnmp\_session\_api**(3)](/man/os/net-snmp/netsnmp_session_api.3), [**default\_store**(3)](/man/os/net-snmp/default_store.3), [**alarm**(2)](/man/os/net-snmp/alarm.2), [**setitimer**(2)](/man/os/net-snmp/setitimer.2), [**select**(2)](/man/os/net-snmp/select.2)

01 Aug 2002 V5.9.5.2

---

Document: snmp_alarm_unregister(3) from net-snmp 5.9.5.2-r11 (Chainguard OS)
Source: https://github.com/net-snmp/net-snmp.git