---
name: "oid_usmNotInTimeWindows"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/FIND_OBJECT_INT"
---

# oid\_usmNotInTimeWindows(3)

SNMP daemon loadable module interface

Part of [FIND\_OBJECT\_INT(3)](/FIND_OBJECT_INT/3.md).

## NAME

**INSERT\_OBJECT\_OID\_LINK\_INDEX**, **INSERT\_OBJECT\_INT\_LINK\_INDEX**, **FIND\_OBJECT\_OID\_LINK\_INDEX**, **NEXT\_OBJECT\_OID\_LINK\_INDEX**, **FIND\_OBJECT\_INT\_LINK\_INDEX**, **NEXT\_OBJECT\_INT\_LINK\_INDEX**, **INSERT\_OBJECT\_OID\_LINK**, **INSERT\_OBJECT\_INT\_LINK**, **FIND\_OBJECT\_OID\_LINK**, **NEXT\_OBJECT\_OID\_LINK**, **FIND\_OBJECT\_INT\_LINK**, **NEXT\_OBJECT\_INT\_LINK**, **INSERT\_OBJECT\_OID**, **INSERT\_OBJECT\_INT**, **FIND\_OBJECT\_OID**, **FIND\_OBJECT\_INT**, **NEXT\_OBJECT\_OID**, **NEXT\_OBJECT\_INT**, **this\_tick**, **start\_tick**, **get\_ticks**, **systemg**, **comm\_define**, **community**, **oid\_zeroDotZero**, **oid\_usmUnknownEngineIDs**, **oid\_usmNotInTimeWindows**, **reqid\_allocate**, **reqid\_next**, **reqid\_base**, **reqid\_istype**, **reqid\_type**, **timer\_start**, **timer\_start\_repeat**, **timer\_stop**, **fd\_select**, **fd\_deselect**, **fd\_suspend**, **fd\_resume**, **or\_register**, **or\_unregister**, **buf\_alloc**, **buf\_size**, **snmp\_input\_start**, **snmp\_input\_finish**, **snmp\_output**, **snmp\_send\_port**, **snmp\_send\_trap**, **snmp\_pdu\_auth\_access** **string\_save**, **string\_commit**, **string\_rollback**, **string\_get**, **string\_get\_max**, **string\_free**, **ip\_save**, **ip\_rollback**, **ip\_commit**, **ip\_get**, **oid\_save**, **oid\_rollback**, **oid\_commit**, **oid\_get**, **index\_decode**, **index\_compare**, **index\_compare\_off**, **index\_append**, **index\_append\_off**, **snmpd\_usmstats**, **bsnmpd\_get\_usm\_stats**, **bsnmpd\_reset\_usm\_stats**, **usm\_first\_user**, **usm\_next\_user**, **usm\_find\_user**, **usm\_new\_user**, **usm\_delete\_user**, **usm\_flush\_users**, **usm\_user**, **snmpd\_target\_stat**, **bsnmpd\_get\_target\_stats**, **target\_first\_address**, **target\_next\_address**, **target\_new\_address**, **target\_activate\_address**, **target\_delete\_address**, **target\_first\_param**, **target\_next\_param**, **target\_new\_param**, **target\_delete\_param**, **target\_first\_notify**, **target\_next\_notify**, **target\_new\_notify**, **target\_delete\_notify**, **target\_flush\_all**, **target\_address**, **target\_param**, **target\_notify** – SNMP daemon loadable module interface

## LIBRARY

Begemot SNMP library (libbsnmp, -lbsnmp)

## SYNOPSIS

**#include \<bsnmp/snmpmod.h\>**

**INSERT\_OBJECT\_OID\_LINK\_INDEX**(*PTR*, *LIST*, *LINK*, *INDEX*);

**INSERT\_OBJECT\_INT\_LINK\_INDEX**(*PTR*, *LIST*, *LINK*, *INDEX*);

**FIND\_OBJECT\_OID\_LINK\_INDEX**(*LIST*, *OID*, *SUB*, *LINK*, *INDEX*);

**FIND\_OBJECT\_INT\_LINK\_INDEX**(*LIST*, *OID*, *SUB*, *LINK*, *INDEX*);

**NEXT\_OBJECT\_OID\_LINK\_INDEX**(*LIST*, *OID*, *SUB*, *LINK*, *INDEX*);

**NEXT\_OBJECT\_INT\_LINK\_INDEX**(*LIST*, *OID*, *SUB*, *LINK*, *INDEX*);

**INSERT\_OBJECT\_OID\_LINK**(*PTR*, *LIST*, *LINK*);

**INSERT\_OBJECT\_INT\_LINK**(*PTR*, *LIST*, *LINK*);

**FIND\_OBJECT\_OID\_LINK**(*LIST*, *OID*, *SUB*, *LINK*);

**FIND\_OBJECT\_INT\_LINK**(*LIST*, *OID*, *SUB*, *LINK*);

**NEXT\_OBJECT\_OID\_LINK**(*LIST*, *OID*, *SUB*, *LINK*);

**NEXT\_OBJECT\_INT\_LINK**(*LIST*, *OID*, *SUB*, *LINK*);

**INSERT\_OBJECT\_OID**(*PTR*, *LIST*);

**INSERT\_OBJECT\_INT**(*PTR*, *LIST*);

**FIND\_OBJECT\_OID**(*LIST*, *OID*, *SUB*);

**FIND\_OBJECT\_INT**(*LIST*, *OID*, *SUB*);

**NEXT\_OBJECT\_OID**(*LIST*, *OID*, *SUB*);

**NEXT\_OBJECT\_INT**(*LIST*, *OID*, *SUB*); *extern* *uint64\_t* *this\_tick*; *extern* *uint64\_t* *start\_tick*;

*uint64\_t*\

**get\_ticks**(*void*); *extern* *struct* *systemg* *systemg*;

*u\_int*\

**comm\_define**(*u\_int priv*, *const char \*descr*, *struct lmodule \*mod*, *const char \*str*);

*const* *char* *\**\

**comm\_string**(*u\_int comm*); *extern* *u\_int* *community*; *extern* *const* *struct* *asn\_oid* *oid\_zeroDotZero*;

*u\_int*\

**reqid\_allocate**(*int size*, *struct lmodule \*mod*);

*int32\_t*\

**reqid\_next**(*u\_int type*);

*int32\_t*\

**reqid\_base**(*u\_int type*);

*int*\

**reqid\_istype**(*int32\_t reqid*, *u\_int type*);

*u\_int*\

**reqid\_type**(*int32\_t reqid*);

*void* *\**\

**timer\_start**(*u\_int ticks*, *void (\*func)(void \*)*, *void \*uarg*, *struct lmodule \*mod*);

*void* *\**\

**timer\_start\_repeat**(*u\_int ticks*, *u\_int repeat\_ticks*, *void (\*func)(void \*)*, *void \*uarg*, *struct lmodule \*mod*);

*void*\

**timer\_stop**(*void \*timer\_id*);

*void* *\**\

**fd\_select**(*int fd*, *void (\*func)(int, void \*)*, *void \*uarg*, *struct lmodule \*mod*);

*void*\

**fd\_deselect**(*void \*fd\_id*);

*void*\

**fd\_suspend**(*void \*fd\_id*);

*int*\

**fd\_resume**(*void \*fd\_id*);

*u\_int*\

**or\_register**(*const struct asn\_oid \*oid*, *const char \*descr*, *struct lmodule \*mod*);

*void*\

**or\_unregister**(*u\_int or\_id*);

*void* *\**\

**buf\_alloc**(*int tx*);

*size\_t*\

**buf\_size**(*int tx*);

*enum* *snmpd\_input\_err*\

**snmp\_input\_start**(*const u\_char \*buf*, *size\_t len*, *const char \*source*, *struct snmp\_pdu \*pdu*, *int32\_t \*ip*, *size\_t \*pdulen*);

*enum* *snmpd\_input\_err*\

**snmp\_input\_finish**(*struct snmp\_pdu \*pdu*, *const u\_char \*rcvbuf*, *size\_t rcvlen*, *u\_char \*sndbuf*, *size\_t \*sndlen*, *const char \*source*, *enum snmpd\_input\_err ierr*, *int32\_t ip*, *void \*data*);

*void*\

**snmp\_output**(*struct snmp\_pdu \*pdu*, *u\_char \*sndbuf*, *size\_t \*sndlen*, *const char \*dest*);

*void*\

**snmp\_send\_port**(*void \*trans*, *const struct asn\_oid \*port*, *struct snmp\_pdu \*pdu*, *const struct sockaddr \*addr*, *socklen\_t addrlen*);

*void*\

**snmp\_send\_trap**(*const struct asn\_oid \*oid*, *...*);

*enum* *snmp\_code*\

**snmp\_pdu\_auth\_access**(*struct snmp\_pdu \*pdu*, *int32\_t \*ip*);

*int*\

**string\_save**(*struct snmp\_value \*val*, *struct snmp\_context \*ctx*, *ssize\_t req\_size*, *u\_char \*\*strp*);

*void*\

**string\_commit**(*struct snmp\_context \*ctx*);

*void*\

**string\_rollback**(*struct snmp\_context \*ctx*, *u\_char \*\*strp*);

*int*\

**string\_get**(*struct snmp\_value \*val*, *const u\_char \*str*, *ssize\_t len*);

*int*\

**string\_get\_max**(*struct snmp\_value \*val*, *const u\_char \*str*, *ssize\_t len*, *size\_t maxlen*);

*void*\

**string\_free**(*struct snmp\_context \*ctx*);

*int*\

**ip\_save**(*struct snmp\_value \*val*, *struct snmp\_context \*ctx*, *u\_char \*ipa*);

*void*\

**ip\_rollback**(*struct snmp\_context \*ctx*, *u\_char \*ipa*);

*void*\

**ip\_commit**(*struct snmp\_context \*ctx*);

*int*\

**ip\_get**(*struct snmp\_value \*val*, *u\_char \*ipa*);

*int*\

**oid\_save**(*struct snmp\_value \*val*, *struct snmp\_context \*ctx*, *struct asn\_oid \*oid*);

*void*\

**oid\_rollback**(*struct snmp\_context \*ctx*, *struct asn\_oid \*oid*);

*void*\

**oid\_commit**(*struct snmp\_context \*ctx*);

*int*\

**oid\_get**(*struct snmp\_value \*val*, *const struct asn\_oid \*oid*);

*int*\

**index\_decode**(*const struct asn\_oid \*oid*, *u\_int sub*, *u\_int code*, *...*);

*int*\

**index\_compare**(*const struct asn\_oid \*oid1*, *u\_int sub*, *const struct asn\_oid \*oid2*);

*int*\

**index\_compare\_off**(*const struct asn\_oid \*oid1*, *u\_int sub*, *const struct asn\_oid \*oid2*, *u\_int off*);

*void*\

**index\_append**(*struct asn\_oid \*dst*, *u\_int sub*, *const struct asn\_oid \*src*);

*void*\

**index\_append\_off**(*struct asn\_oid \*dst*, *u\_int sub*, *const struct asn\_oid \*src*, *u\_int off*); *extern* *struct* *snmpd\_usmstat* *snmpd\_usmstats*;

*struct* *snmpd\_usmstat* *\**\

**bsnmpd\_get\_usm\_stats**(*void*);

*void*\

**bsnmpd\_reset\_usm\_stats**(*void*);

*struct* *usm\_user* *\**\

**usm\_first\_user**(*void*);

*struct* *usm\_user* *\**\

**usm\_next\_user**(*struct usm\_user \*uuser*);

*struct* *usm\_user* *\**\

**usm\_find\_user**(*uint8\_t \*engine*, *uint32\_t elen*, *char \*uname*);

*struct* *usm\_user* *\**\

**usm\_new\_user**(*uint8\_t \*engine*, *uint32\_t elen*, *char \*uname*);

*void*\

**usm\_delete\_user**(*struct usm\_user \**);

*void*\

**usm\_flush\_users**(*void*); *extern* *struct* *usm\_user* *\*usm\_user;*

*struct* *snmpd\_target\_stats* *\**\

**bsnmpd\_get\_target\_stats**(*void*);

*struct* *target\_address* *\**\

**target\_first\_address**(*void*);

*struct* *target\_address* *\**\

**target\_next\_address**(*struct target\_address \**);

*struct* *target\_address* *\**\

**target\_new\_address**(*char \**);

*int*\

**target\_activate\_address**(*struct target\_address \**);

*int*\

**target\_delete\_address**(*struct target\_address \**);

*struct* *target\_param* *\**\

**target\_first\_param**(*void*);

*struct* *target\_param* *\**\

**target\_next\_param**(*struct target\_param \**);

*struct* *target\_param* *\**\

**target\_new\_param**(*char \**);

*int*\

**target\_delete\_param**(*struct target\_param \**);

*struct* *target\_notify* *\**\

**target\_first\_notify**(*void*);

*struct* *target\_notify* *\**\

**target\_next\_notify**(*struct target\_notify \**);

*struct* *target\_notify* *\**\

**target\_new\_notify**(*char \**);

*int*\

**target\_delete\_notify**(*struct target\_notify \**);

*void*\

**target\_flush\_all**(*void*); *extern* *const* *struct* *asn\_oid* *oid\_usmUnknownEngineIDs;* *extern* *const* *struct* *asn\_oid* *oid\_usmNotInTimeWindows;*

## DESCRIPTION

The [bsnmpd(1)](/bsnmpd/1.md) SNMP daemon implements a minimal MIB which consists of the system group, part of the SNMP MIB, a private configuration MIB, a trap destination table, a UDP port table, a community table, a module table, a statistics group and a debugging group. All other MIBs are support through loadable modules. This allows [bsnmpd(1)](/bsnmpd/1.md) to use for task, that are not the classical SNMP task.

### MODULE LOADING AND UNLOADING

Modules are loaded by writing to the module table. This table is indexed by a string, that identifies the module to the daemon. This identifier is used to select the correct configuration section from the configuration files and to identify resources allocated to this module. A row in the module table is created by writing a string of non-zero length to the *begemotSnmpdModulePath* column. This string must be the complete path to the file containing the module. A module can be unloaded by writing a zero length string to the path column of an existing row.

Modules may depend on each other an hence must be loaded in the correct order. The dependencies are listed in the corresponding manual pages.

Upon loading a module the SNMP daemon expects the module file to a export a global symbol *config*. This symbol should be a variable of type *struct* *snmp\_module*:

```
typedef enum snmpd_proxy_err (*proxy_err_f)(struct snmp_pdu *, void *,
    const struct asn_oid *, const struct sockaddr *, socklen_t,
    enum snmpd_input_err, int32_t);
struct snmp_module {
	const char *comment;
	int (*init)(struct lmodule *, int argc, char *argv[]);
	int (*fini)(void);
	void (*idle)(void);
	void (*dump)(void);
	void (*config)(void);
	void (*start)(void);
	proxy_err_f proxy;
	const struct snmp_node *tree;
	u_int tree_size;
	void (*loading)(const struct lmodule *, int);
};
```

This structure must be statically initialized and its fields have the following functions:

- *comment*

  This is a string that will be visible in the module table. It should give some hint about the function of this module.

- *init*

  This function is called upon loading the module. The module pointer should be stored by the module because it is needed in other calls and the argument vector will contain the arguments to this module from the daemons command line. This function should return 0 if everything is ok or an UNIX error code (see [errno(3)](/errno/3.md)). Once the function returns 0, the *fini* function is called when the module is unloaded.

- *fini*

  The module is unloaded. This gives the module a chance to free resources that are not automatically freed. Be sure to free all memory, because daemons tend to run very long. This function pointer may be NULL if it is not needed.

- *idle*

  If this function pointer is not NULL, the function pointed to by it is called whenever the daemon is going to wait for an event. Try to avoid using this feature.

- *dump*

  Whenever the daemon receives a SIGUSR1 it dumps it internal state via [syslog(3)](/syslog/3.md). If the *dump* field is not NULL it is called by the daemon to dump the state of the module.

- *config*

  Whenever the daemon receives a SIGHUP signal it re-reads its configuration file. If the *config* field is not NULL it is called after reading the configuration file to give the module a chance to adapt to the new configuration.

- *start*

  If not NULL this function is called after successful loading and initializing the module to start its actual operation.

- *proxy*

  If the daemon receives a PDU and that PDU has a community string whose community was registered by this module and *proxy* is not NULL than this function is called to handle the PDU.

- *tree*

  This is a pointer to the node array for the MIB tree implemented by this module.

- *tree\_size*

  This is the number of nodes in *tree*.

- *loading*

  If this pointer is not NULL it is called whenever another module was loaded or unloaded. It gets a pointer to that module and a flag that is 0 for unloading and 1 for loading.

When everything is ok, the daemon merges the module's MIB tree into its current global tree, calls the modules **init**() function. If this function returns an error, the modules MIB tree is removed from the global one and the module is unloaded. If initialization is successful, the modules **start**() function is called. After it returns the **loaded**() functions of all modules (including the loaded one) are called.

When the module is unloaded, its MIB tree is removed from the global one, the communities, request id ranges, running timers and selected file descriptors are released, the **fini**() function is called, the module file is unloaded and the **loaded**() functions of all other modules are called.

### IMPLEMENTING TABLES

There are a number of macros designed to help implementing SNMP tables. A problem while implementing a table is the support for the GETNEXT operator. The GETNEXT operation has to find out whether, given an arbitrary OID, the lessest table row, that has an OID higher than the given OID. The easiest way to do this is to keep the table as an ordered list of structures each one of which contains an OID that is the index of the table row. This allows easy removal, insertion and search.

The helper macros assume, that the table is organized as a TAILQ (see [queue(3)](/queue/3.md) and each structure contains a *struct* *asn\_oid* that is used as index. For simple tables with only a integer or unsigned index, an alternate form of the macros is available, that presume the existence of an integer or unsigned field as index field.

The macros have name of the form

```
{INSERT,FIND,NEXT}_OBJECT_{OID,INT}[_LINK[_INDEX]]
```

The **INSERT\_\***() macros are used in the SET operation to insert a new table row into the table. The **FIND\_\***() macros are used in the GET operation to find a specific row in the table. The **NEXT\_\***() macros are used in the GETNEXT operation to find the next row in the table. The last two macros return a pointer to the row structure if a row is found, NULL otherwise. The macros **\*\_OBJECT\_OID\_\***() assume the existence of a *struct* *asn\_oid* that is used as index, the macros **\*\_OBJECT\_INT\_\***() assume the existence of an unsigned integer field that is used as index.

The macros **\*\_INDEX**() allow the explicit naming of the index field in the parameter *INDEX*, whereas the other macros assume that this field is named *index*. The macros **\*\_LINK\_\***() allow the explicit naming of the link field of the tail queues, the others assume that the link field is named *link*. Explicitly naming the link field may be necessary if the same structures are held in two or more different tables.

The arguments to the macros are as follows:

- *PTR*

  A pointer to the new structure to be inserted into the table.

- *LIST*

  A pointer to the tail queue head.

- *LINK*

  The name of the link field in the row structure.

- *INDEX*

  The name of the index field in the row structure.

- *OID*

  Must point to the *var* field of the *value* argument to the node operation callback. This is the OID to search for.

- *SUB*

  This is the index of the start of the table index in the OID pointed to by *OID*. This is usually the same as the *sub* argument to the node operation callback.

### DAEMON TIMESTAMPS

The variable *this\_tick* contains the tick (there are 100 SNMP ticks in a second) when the current PDU processing was started. The variable *start\_tick* contains the tick when the daemon was started. The function **get\_ticks**() returns the current tick. The number of ticks since the daemon was started is

```
get_ticks() - start_tick
```

### THE SYSTEM GROUP

The scalar fields of the system group are held in the global variable *systemg*:

```
struct systemg {
	u_char		*descr;
	struct asn_oid	object_id;
	u_char		*contact;
	u_char		*name;
	u_char		*location;
	uint32_t	services;
	uint32_t	or_last_change;
};
```

### COMMUNITIES

The SNMP daemon implements a community table. On receipt of a request message the community string in that message is compared to each of the community strings in that table, if a match is found, the global variable *community* is set to the community identifier for that community. Community identifiers are unsigned integers. For the three standard communities there are three constants defined:

```
#define COMM_INITIALIZE	0
#define COMM_READ	1
#define COMM_WRITE	2
```

*community* is set to COMM\_INITIALIZE while the assignments in the configuration file are processed. To COMM\_READ or COMM\_WRITE when the community strings for the read-write or read-only community are found in the incoming PDU.

Modules can define additional communities. This may be necessary to provide transport proxying (a PDU received on one communication link is proxied to another link) or to implement non-UDP access points to SNMP. A new community is defined with the function **comm\_define**(). It takes the following parameters:

- *priv*

  This is an integer identifying the community to the module. Each module has its own namespace with regard to this parameter. The community table is indexed with the module name and this identifier.

- *descr*

  This is a string providing a human readable description of the community. It is visible in the community table.

- *mod*

  This is the module defining the community.

- *str*

  This is the initial community string.

The function returns a globally unique community identifier. If a SNMPv1 or SNMPv2 PDU is received who's community string matches, this identifier is set into the global *community*.

The function **comm\_string**() returns the current community string for the given community.

All communities defined by a module are automatically released when the module is unloaded.

### THE USER-BASED SECURITY GROUP

The scalar statistics of the USM group are held in the global variable *snmpd\_usmstats*:

```
struct snmpd_usmstat {
	uint32_t	unsupported_seclevels;
	uint32_t	not_in_time_windows;
	uint32_t	unknown_users;
	uint32_t	unknown_engine_ids;
	uint32_t	wrong_digests;
	uint32_t	decrypt_errors;
};
```

**bsnmpd\_get\_usm\_stats**() returns a pointer to the global structure containing the statistics. **bsnmpd\_reset\_usm\_stats**() clears the statistics of the USM group.

A global list of configured USM users is maintained by the daemon.

```
struct usm_user {
	struct snmp_user		suser;
	uint8_t				user_engine_id[SNMP_ENGINE_ID_SIZ];
	uint32_t			user_engine_len;
	char				user_public[SNMP_ADM_STR32_SIZ];
	uint32_t			user_public_len;
	int32_t				status;
	int32_t				type;
	SLIST_ENTRY(usm_user)		up;
};
```

This structure represents an USM user. The daemon only responds to SNMPv3 PDUs with user credentials matching an USM user entry in its global list. If a SNMPv3 PDU is received, whose security model is USM, the global *usm\_user* is set to point at the user entry that matches the credentials contained in the PDU. However, the daemon does not create or remove USM users, it gives an interface to external loadable module(s) to manage the list. **usm\_new\_user**() adds an user entry in the list, and **usm\_delete\_user**() deletes an existing entry from the list. **usm\_flush\_users**() is used to remove all configured USM users. **usm\_first\_user**() will return the first user in the list, or NULL if the list is empty. **usm\_next\_user**() will return  the next user of a given entry if one exists, or NULL. The list is sorted according to the USM user name and Engine ID. **usm\_find\_user**() returns the USM user entry matching the given *engine* and *uname* or NULL if an user with the specified name and engine id is not present in the list.

### THE MANAGEMENT TARGET GROUP

The Management Target group holds target address information used when sending SNMPv3 notifications.

The scalar statistics of the Management Target group are held in the global variable *snmpd\_target\_stats*:

```
struct snmpd_target_stats {
	uint32_t			unavail_contexts;
	uint32_t			unknown_contexts;
};
```

**bsnmpd\_get\_target\_stats**() returns a pointer to the global structure containing the statistics.

Three global lists of configured management target addresses, parameters and notifications respectively are maintained by the daemon.

```
struct target_address {
	char				name[SNMP_ADM_STR32_SIZ];
	uint8_t				address[SNMP_UDP_ADDR_SIZ];
	int32_t				timeout;
	int32_t				retry;
	char				taglist[SNMP_TAG_SIZ];
	char				paramname[SNMP_ADM_STR32_SIZ];
	int32_t				type;
	int32_t				socket;
	int32_t				status;
	SLIST_ENTRY(target_address)	ta;
};
```

This structure represents a SNMPv3 Management Target address. Each time a SNMP TRAP is send the daemon will send the Trap to all active Management Target addresses in its global list.

```
struct target_param {
	char				name[SNMP_ADM_STR32_SIZ];
	int32_t				mpmodel;
	int32_t				sec_model;
	char				secname[SNMP_ADM_STR32_SIZ];
	enum snmp_usm_level		sec_level;
	int32_t				type;
	int32_t				status;
	SLIST_ENTRY(target_param)	tp;
};
```

This structure represents the information used to generate SNMP messages to the associated SNMPv3 Management Target addresses.

```
struct target_notify {
	char				name[SNMP_ADM_STR32_SIZ];
	char				taglist[SNMP_TAG_SIZ];
	int32_t				notify_type;
	int32_t				type;
	int32_t				status;
	SLIST_ENTRY(target_notify)	tn;
};
```

This structure represents Notification Tag entries - SNMP notifications are sent to the Target address for each entry in the Management Target Address list that has a tag matching the specified tag in this structure.

The daemon does not create or remove entries in the Management Target group lists, it gives an interface to external loadable module(s) to manage the lists. **target\_new\_address**() adds a target address entry, and **target\_delete\_address**() deletes an existing entry from the target address list. **target\_activate\_address**() creates a socket associated with the target address entry so that SNMP notifications may actually be send to that target address. **target\_first\_address**() will return a pointer to the first target address entry in the list, while **target\_next\_address**() will return a pointer to the next target address of a given entry if one exists. **target\_new\_param**() adds a target parameters' entry, and **target\_delete\_param**() deletes an existing entry from the target parameters list. **target\_first\_param**() will return a pointer to the first target parameters' entry in the list, while **target\_next\_param**() will return a pointer to the next target parameters of a given entry if one exists. **target\_new\_notify**() adds a notification target entry, and **target\_delete\_notify**() deletes an existing entry from the notification target list. **target\_first\_notify**() will return a pointer to the first notification target entry in the list, while **target\_next\_notify**() will return a pointer to the next notification target of a given entry if one exists. **target\_flush\_all**() is used to remove all configured data from the three global Management Target Group lists.

### WELL KNOWN OIDS

The global variable *oid\_zeroDotZero* contains the OID 0.0. The global variables *oid\_usmUnknownEngineIDs* *oid\_usmNotInTimeWindows* contains the OIDs 1.3.6.1.6.3.15.1.1.4.0 and  1.3.6.1.6.3.15.1.1.2.0 used in the SNMPv3 USM Engine Discovery.

### REQUEST ID RANGES

For modules that implement SNMP client functions besides SNMP agent functions it may be necessary to identify SNMP requests by their identifier to allow easier routing of responses to the correct sub-system. Request id ranges provide a way to acquire globally non-overlapping sub-ranges of the entire 31-bit id range.

A request id range is allocated with **reqid\_allocate**(). The arguments are: the size of the range and the module allocating the range. For example, the call

```
id = reqid_allocate(1000, module);
```

allocates a range of 1000 request ids. The function returns the request id range identifier or 0 if there is not enough identifier space. The function **reqid\_base**() returns the lowest request id in the given range.

Request id are allocated starting at the lowest one linear throughout the range. If the client application may have a lot of outstanding request the range must be large enough so that an id is not reused until it is really expired. **reqid\_next**() returns the sequentially next id in the range.

The function **reqid\_istype**() checks whether the request id *reqid* is within the range identified by *type*. The function **reqid\_type**() returns the range identifier for the given *reqid* or 0 if the request id is in none of the ranges.

### TIMERS

The SNMP daemon supports an arbitrary number of timers with SNMP tick granularity. The function **timer\_start**() arranges for the callback *func* to be called with the argument *uarg* after *ticks* SNMP ticks have expired. *mod* is the module that starts the timer. These timers are one-shot, they are not restarted. Repeatable timers are started with **timer\_start\_repeat**() which takes an additional argument *repeat\_ticks*. The argument *ticks* gives the number of ticks until the first execution of the callback, while *repeat\_ticks* is the number of ticks between invocations of the callback. Note, that currently the number of initial ticks silently may be set identical to the number of ticks between callback invocations. The function returns a timer identifier that can be used to stop the timer via **timer\_stop**(). If a module is unloaded all timers started by the module that have not expired yet are stopped.

### FILE DESCRIPTOR SUPPORT

A module may need to get input from socket file descriptors without blocking the daemon (for example to implement alternative SNMP transports).

The function **fd\_select**() causes the callback function *func* to be called with the file descriptor *fd* and the user argument *uarg* whenever the file descriptor *fd* can be read or has a close condition. If the file descriptor is not in non-blocking mode, it is set to non-blocking mode. If the callback is not needed anymore, **fd\_deselect**() may be called with the value returned from **fd\_select**(). All file descriptors selected by a module are automatically deselected when the module is unloaded.

To temporarily suspend the file descriptor registration **fd\_suspend**() can be called. This also causes the file descriptor to be switched back to blocking mode if it was blocking prior the call to **fd\_select**(). This is necessary to do synchronous input on a selected socket. The effect of **fd\_suspend**() can be undone with **fd\_resume**().

### OBJECT RESOURCES

The system group contains an object resource table. A module may create an entry in this table by calling **or\_register**() with the *oid* to be registered, a textual description in *str* and a pointer to the module *mod*. The registration can be removed with **or\_unregister**(). All registrations of a module are automatically removed if the module is unloaded.

### TRANSMIT AND RECEIVE BUFFERS

A buffer is allocated via **buf\_alloc**(). The argument must be 1 for transmit and 0 for receive buffers. The function may return NULL if there is no memory available. The current buffersize can be obtained with **buf\_size**().

## PROCESSING PDUS

For modules that need to do their own PDU processing (for example for proxying) the following functions are available:

Function **snmp\_input\_start**() decodes the PDU, searches the community, and sets the global *this\_tick*. It returns one of the following error codes:

- SNMPD\_INPUT\_OK

  Everything ok, continue with processing.

- SNMPD\_INPUT\_FAILED

  The PDU could not be decoded, has a wrong version or an unknown community string.

- SNMPD\_INPUT\_VALBADLEN

  A SET PDU had a value field in a binding with a wrong length field in an ASN.1 header.

- SNMPD\_INPUT\_VALRANGE

  A SET PDU had a value field in a binding with a value that is out of range for the given ASN.1 type.

- SNMPD\_INPUT\_VALBADENC

  A SET PDU had a value field in a binding with wrong ASN.1 encoding.

- SNMPD\_INPUT\_TRUNC

  The buffer appears to contain a valid begin of a PDU, but is too short. For streaming transports this means that the caller must save what he already has and trying to obtain more input and reissue this input to the function. For datagram transports this means that part of the datagram was lost and the input should be ignored.

The function **snmp\_input\_finish**() does the other half of processing: if **snmp\_input\_start**() did not return OK, tries to construct an error response. If the start was OK, it calls the correct function from [bsnmpagent(3)](/bsnmpagent/3.md) to execute the request and depending on the outcome constructs a response or error response PDU or ignores the request PDU. It returns either SNMPD\_INPUT\_OK or SNMPD\_INPUT\_FAILED. In the first case a response PDU was constructed and should be sent.

The function **snmp\_output**() takes a PDU and encodes it.

The function **snmp\_send\_port**() takes a PDU, encodes it and sends it through the given port (identified by the transport and the index in the port table) to the given address.

The function **snmp\_send\_trap**() sends a trap to all trap destinations. The arguments are the *oid* identifying the trap and a NULL-terminated list of *struct* *snmp\_value* pointers that are to be inserted into the trap binding list. **snmp\_pdu\_auth\_access**() verifies whether access to the object IDs contained in the *pdu*\
  should be granted or denied, according to the configured View-Based Access rules. *ip* contains the index of the first varbinding to which access was denied, or 0 if access to all varbindings in the PDU is granted.

### SIMPLE ACTION SUPPORT

For simple scalar variables that need no dependencies a number of support functions is available to handle the set, commit, rollback and get.

The following functions are used for OCTET STRING scalars, either NUL terminated or not:

- **string\_save**()

  should be called for SNMP\_OP\_SET. *value* and *ctx* are the resp. arguments to the node callback. *valp* is a pointer to the pointer that holds the current value and *req\_size* should be -1 if any size of the string is acceptable or a number larger or equal zero if the string must have a specific size. The function saves the old value in the scratch area (note, that any initial value must have been allocated by [malloc(3)](/malloc/3.md)), allocates a new string, copies over the new value, NUL-terminates it and sets the new current value.

- **string\_commit**()

  simply frees the saved old value in the scratch area.

- **string\_rollback**()

  frees the new value, and puts back the old one.

- **string\_get**()

  is used for GET or GETNEXT. The function

- **string\_get\_max**()

  can be used instead of **string\_get**() to ensure that the returned string has a certain maximum length. If *len* is -1, the length is computed via [strlen(3)](/strlen/3.md) from the current string value. If the current value is NULL, a OCTET STRING of zero length is returned.

- **string\_free**()

  must be called if either rollback or commit fails to free the saved old value.

The following functions are used to process scalars of type IP-address:

- **ip\_save**()

  Saves the current value in the scratch area and sets the new value from *valp*.

- **ip\_commit**()

  Does nothing.

- **ip\_rollback**()

  Restores the old IP address from the scratch area.

- **ip\_get**()

  Retrieves the IP current address.

The following functions handle OID-typed variables:

- **oid\_save**()

  Saves the current value in the scratch area by allocating a *struct* *asn\_oid* with [malloc(3)](/malloc/3.md) and sets the new value from *oid*.

- **oid\_commit**()

  Frees the old value in the scratch area.

- **oid\_rollback**()

  Restores the old OID from the scratch area and frees the old OID.

- **oid\_get**()

  Retrieves the OID

### TABLE INDEX HANDLING

The following functions help in handling table indexes:

- **index\_decode**()

  Decodes the index part of the OID. The parameter *oid* must be a pointer to the *var* field of the *value* argument of the node callback. The *sub* argument must be the index of the start of the index in the OID (this is the *sub* argument to the node callback). *code* is the index expression (parameter *idx* to the node callback). These parameters are followed by parameters depending on the syntax of the index elements as follows:

  - INTEGER

    *int32\_t* *\** expected as argument.

  - COUNTER64

    *uint64\_t* *\** expected as argument. Note, that this syntax is illegal for indexes.

  - OCTET STRING

    A *u\_char* *\*\** and a *size\_t* *\** expected as arguments. A buffer is allocated to hold the decoded string.

  - OID

    A *struct* *asn\_oid* *\** is expected as argument.

  - IP ADDRESS

    A *u\_int8\_t* *\** expected as argument that points to a buffer of at least four byte.

  - COUNTER, GAUGE, TIMETICKS

    A *u\_int32\_t* expected.

  - NULL

    No argument expected.

- **index\_compare**()

  compares the current variable with an OID. *oid1* and *sub* come from the node callback arguments *value-\>var* and *sub* resp. *oid2* is the OID to compare to. The function returns -1, 0, +1 when the variable is lesser, equal, higher to the given OID. *oid2* must contain only the index part of the table column.

- **index\_compare\_off**()

  is equivalent to **index\_compare**() except that it takes an additional parameter *off* that causes it to ignore the first *off* components of both indexes.

- **index\_append**()

  appends OID *src* beginning at position *sub* to *dst*.

- **index\_append\_off**()

  appends OID *src* beginning at position *off* to *dst* beginning at position *sub* + *off*.

## SEE ALSO

[gensnmptree(1)](/gensnmptree/1.md), [bsnmpd(1)](/bsnmpd/1.md), [bsnmpagent(3)](/bsnmpagent/3.md), [bsnmpclient(3)](/bsnmpclient/3.md), [bsnmplib(3)](/bsnmplib/3.md)

## STANDARDS

This implementation conforms to the applicable IETF RFCs and ITU-T recommendations.

## AUTHORS

Hartmut Brandt ⟨harti@FreeBSD.org⟩