NAME
imctr_get, imctr_free, imctr_load - MTA channel counters
utilities.
SYNOPSIS
#include <imta.h>
int imctr_load(imctr_t *ctr, char *channel);
int imctr_get(imctr_t ctr, int index, imctr_type_t counter,
char **channel);
void imctr_free(imctr_t ctr);
DESCRIPTION
The SIMS IMTA accumulates in the form of counters or message
traffic statistics for each of its channels. These statis-
tics, referred to as "channel counters," correspond to those
used by the Mail Monitoring MIB (RFC 1566) with an IMTA
channel representing a "group" as defined by RFC 1566.
imctr_load() may be used to gather these counters for one or
more channels specified by channel. To obtain counters for
more than one channel at a time, use wild cards in the chan-
nel name. The only wild-card character available is "*".
It stands for 0 or more characters. For instance, to obtain
counters for all TCP/IP channels use the name "tcp_*". Simi-
larly, to obtain counters for all channels, use the name
"*". imctr_load() returns the number of channels matching
channel for which counters were found.
Once the counters have been gathered, individual channel
counters may then be obtained by calling imctr_get(). ctr
is the imctr_t handle on the counters datastructures gath-
ered with a previous call. If the channel argument passed
to imctr_load() led to gathering counters for more than one
channel, the counters corresponding to each of these chan-
nels can be retrieved by using values of index located
between 0 and the value returned by imctr_load() less 1.
each call places the name of the corresponding channel in a
buffer referenced by channel. counter must be set to the
type of counter desired. The available types are:
IMCTR_RECEIVED_MSGS
cumulative count of messages enqueued to
the channel
IMCTR_SUBMITTED_MSGS
cumulative count of messages enqueued by
the channel
IMCTR_STORED_MSGS total number of messages currently stored
for the channel
IMCTR_DELIVERED_MSGS
cumulative count of messages dequeued by
the channel
IMCTR_REJECTED_MSGS
cumulative count of messages which, upon
trying to be enqueued to the channel, were
rejected.
IMCTR_FAILED_MSGS cumulative count of messages enqueued to
the channel which, when processed, failed
to be delivered for one or more recipients
owing to permanent errors of some sort (
e.g., invalid recipient address).
IMCTR_ATTEMPTED_MSGS
cumulative count of messages enqueued to
the channel whose delivery has been
attempted.
IMCTR_RECEIVED_VOLUME
cumulative volume of messages enqueued to
the channel as measured in Kilobytes
IMCTR_SUBMITTED_VOLUME
cumulative volume of messages enqueued by
the channel as measured in Kilobytes
IMCTR_STORED_VOLUME
volume of messages currently stored for
the channel as measured in Kilobytes
IMCTR_DELIVERED_VOLUME
cumulative volume of messages dequeued by
the channel as measured in Kilobytes
IMCTR_REJECTED_VOLUME
cumulative volume of messages which, upon
trying to be enqueued to the channel, were
rejected.
IMCTR_FAILED_VOLUME
cumulative volume of messages enqueued to
the channel which, when processed, failed
to be delivered for one or more recipients
owing to permanent errors of some sort (
e.g., invalid recipient address).
IMCTR_ATTEMPTED_VOLUME
cumulative volume of messages enqueued to
the channel whose delivery has been
attempted.
IMCTR_RECEIVED_RCPTS
total number of recipients specified in
all messages enqueued to the channel
IMCTR_SUBMITTED_RCPTS
total number of recipients specified in
all messages enqueued by the channel
IMCTR_STORED_RCPTS
total number of recipients specified in
all messages currently stored for the
channel
IMCTR_DELIVERED_RCPTS
total number of recipients specified in
all messages delivered by the channel
IMCTR_REJECTED_RCPTS
cumulative count of recipient addresses
which, upon trying to be enqueued to the
channel, were rejected.
IMCTR_FAILED_RCPTS
cumulative count of recipients enqueued to
the channel which, when processed, failed
to be delivered owing to permanent errors
of some sort ( e.g., invalid recipient
address).
IMCTR_ATTEMPTED_RCPTS
cumulative count of recipients enqueued to
the channel whose delivery has been
attempted.
After the counters have been used, the memory allocated to
store the counters must be freed with imctr_free(). The
argument ctr points to the channel counters structure
returned by a previous call to imctr_get().
RETURN VALUES
If successful, imctr_load returns the number of channels
matching channel for which counters were found.
If successful, imctr_get returns the requested counter
value.
Otherwise, these functions can fail for one of the following
reasons:
IMRC_INVALID_COUNTER_TYPE
The counter requested via imctr_get() is
unknown.
IMRC_OUT_OF_MEMORY
The system is out for memory, and
imctr_load() is not able to allocate the
necessary values.
IMRC_LOCK_ERROR imctr_load() fails due to a contention to
access counters information in the MTA.
IMRC_CHANNEL_NAME_TOO_LONG
The string argument channel passed to
imctr_load() is longer than IM_CHANNEL_LEN
bytes.
ATTRIBUTES
_______________________________________
| Attribute Type | Attribute Value|
|____________________|_________________|
| Architecture | sparc, x86 |
|____________________|_________________|
| Availability | SUNWimsdk |
|____________________|_________________|
| MT-Level | MT-Safe |
|____________________|_________________|
| Interface Stability| Stable |
|____________________|_________________|
SEE ALSO
imta.cnf(4).