Registers or unregisters an advanced accounting handler.
#include <sys/aacct.h>
int acct_interval_register(trid, cmds, handler, arg, reg_token, reg_name)
int trid;
int cmds;
int (*handler)(int trid, int cmds, void *arg);
void *arg;
unsigned long *reg_token;
char *reg_name;
int acct_interval_unregister(reg_token)
unsigned long reg_token;| Item | Description |
|---|---|
| trid | Transaction identifier |
| cmds | Invocations supported by the advanced accounting handler |
| handler | Function descriptor for the handler |
| arg | Identifies the instance of the kernel extension |
| reg_token | Token that is returned to caller naming the instance of the registration |
| reg_name | Identifies the transaction using a string |
The acct_interval_register kernel service registers accounting records that are produced by the kernel extension with the advanced accounting subsystem. These accounting records are named through accounting transaction identifiers, which are provided by the caller. Transaction identifiers are persistent in nature, because they are used by report and analysis utilities to interpret transaction-specific accounting data. The transaction identifier is implicitly mapped to a template.
Transaction identifiers (and associated templates) used by AIX® are defined in the sys/aacct.h file. Identifiers in the range of 0 – 127 are reserved for AIX. Vendors can choose any value in the range 128 – 256 for their accounting records. If two vendors choose the same value, report and analysis programs must reference other fields in the accounting record header to uniquely identify the source of the transaction; that way, they can apply the appropriate template. The subproject field (which specifies the command name of the logger) and length field can be used to identify the source of the transaction. Collisions are very unlikely to occur. The transaction identifier and the transaction name, which is provided by the reg_name field, are presented to the system administrator. Vendors should choose representative names for their transactions. The maximum length of a transaction name is 15 bytes.
Administrators can enable and disable transactions, and thereby drive callouts to the kernel extension. A function descriptor for the advanced accounting handler is provided through the handler parameter. The interface of this handler is:
int handler(int trid, int cmd, void *arg); The trid parameter is the transaction being acted on. The cmd parameter describes the action. The arg parameter is a value that was specified at registration for this particular instance of the handler. The arg parameter is specific to the kernel extension.
| Item | Description |
|---|---|
| ACCT_CMD_ENABLE | The transaction is being enabled; start collecting. |
| ACCT_CMD_DISABLE | The transaction is being disabled; stop collecting. |
| ACCT_CMD_INTERVAL | The system interval has expired; provide accounting data. |
| ACCT_CMD_FSWITCH | The active accounting file has changed; provide meta data. |
The handler is invoked in the process environment from a dedicated kernel-only thread that is part of the advanced accounting subsystem. The kernel extension registers for the callouts that should be made by logically ORing cmd values. The cmds parameter to the acct_interval_register kernel service is provided for this purpose.
When a transaction is enabled, the kernel extension should allocate accounting structures and start collecting statistics. When a transaction is disabled, the kernel extension should quit collecting statistics and free accounting structures. If a transaction is not enabled, the kernel subsystem should not collect statistics for the transaction. The kernel extension relies on the callout mechanism to provide notification when a transaction is enabled. This way, accounting records that are not required for the report are not collected and the accounting overhead is minimized.
If the kernel extension registers for interval accounting, the extension is called when the system interval expires. The handler should record its data using the acct_put kernel service and should reset its counters so that only delta statistics are produced in the next interval. The acct_zero_LL and acct_add_LL kernel services are provided so that statistics can be reported and zeroed atomically. When the system interval is disabled, the system automatically generates an interval callout to collect the last round of statistics.
The file switch callout is provided, so that subsystems can record accounting data in each accounting file. Most subsystems are not expected to use this option.
The acct_interval_register kernel service can be called from the process environment only.
The acct_interval_unregister kernel service can be called from either the interrupt environment or the process environment.
Upon successful completion, 0 is returned. If unsuccessful, errno is set to a value that explains the error.