libwlm(3)libwlm(3)NAME
libwlm - HP-UX Workload Manager data collector API library
SYNOPSIS
cc -I/opt/wlm/include -L/opt/wlm/lib -lwlm [ flag ... ] file ...
#include <wlm.h>
int wlm_mon_attach(const char *metric_name);
ssize_t wlm_mon_write(int handle_id, const void *buf, size_t numbytes);
int wlm_mon_detach(int handle_id);
DESCRIPTION
The routines are for user-supplied data collectors spawned by These
routines allow data collectors to attach to a communication channel to
the WLM daemon, send data to be read by the WLM daemon, and detach from
the communication channel.
Items to be aware of:
· These functions are not thread-safe: Multiple threads cannot call
the same function at the same time.
· WLM runs data collectors with UID set to root. If a data collector
that uses the WLM API changes its UID, all subsequent calls to the
WLM API will fail.
· If a data collector sends multiple values for metric_name in a sin‐
gle WLM interval, the WLM daemon uses only the most recent value.
Use the metric metric_name in your WLM configuration in a or statement.
Place your data collector in a structure--named for the metric--in your
WLM configuration file:
tune metric_name {
coll_argv = /path/to/my/data_collector ;
}
WLM will start the collector when you activate the configuration with
or
All accesses to the communication channel begin with a call to The
channel descriptor returned from this call is a required parameter to
all of the other calls. The complete API consists of the following
functions:
Allows the data collector process to open a communication
channel to the WLM daemon for the purpose of
reporting data. The data collector attaches
to the communication channel that is created
by the WLM daemon and is identified by the
metric_name parameter. metric_name is the
name of the metric being passed on this com‐
munication channel. This string must
exactly match the metric string used in the
WLM configuration file for the specification
of the goal and can be extracted from the
environment variable (This variable is
available only if the WLM daemon starts your
collector, which happens when you specify
your collector in a statement in your WLM
configuration.)
Allows the data collector process to send metric data
on the communication channel to the WLM dae‐
mon. This function writes numbytes bytes of
data, starting at address buf, to the commu‐
nication channel identified by handle_id.
numbytes must equal and buf must point to a
Allows the data collector process to close the communication
channel to the WLM daemon when it is no
longer needed. The supplied handle_id iden‐
tifies the communication channel from which
to detach.
RETURN VALUE
Each function returns -1 and sets errno in the case of failure.
If successful, returns a handle_id that is passed to the other routines
and is used to identify the communication channel.
returns the number of bytes written, if successful. If this function
fails (returns -1) and errno is not EAGAIN, your data collector should
exit.
returns 0 if successful.
EXAMPLES
Attach to the communication channel, write data, and detach from the
communication channel:
attach_write_detach(char *metric_name)
{
int handle_id;
ssize_t bytes;
double data;
int rc;
handle_id = wlm_mon_attach(metric_name);
if (handle_id == -1) {
return(1);
}
data = get_performance_data();
bytes = wlm_mon_write(handle_id, &data, sizeof(data));
if (bytes != sizeof(data)) {
return(1);
}
rc = wlm_mon_detach(handle_id);
if (rc == -1) {
return(1);
}
return(0);
}
ENVIRONMENT
For each data collector started by WLM, the WLM daemon sets:
· The environment variable to the metric used in naming the structure
in which the data collector is specified
(If a metric is used in an SLO but not in naming a structure, WLM
starts an instance of the data collector specified in the global
structure--if any, setting its to the metric's name.)
· to /opt/wlm/bin:/usr/bin
· stdout and stderr to /dev/null
(Use in your WLM configuration to redirect stderr.)
AUTHOR
was developed by HP.
FEEDBACK
If you would like to comment on the current HP-UX WLM functionality or
make suggestions for future releases, please send email to:
wlmfeedback@rsn.hp.com
FILES
contains the function prototypes
PA-RISC version of libwlm
32-bit Itanium-based version of libwlm
SEE ALSOwlmd(1M), wlmconf(4), wlm(5)
HP-UX Workload Manager User's Guide (/opt/wlm/share/doc/WLMug.pdf)
"Writing a Better WLM Data Collector" white paper
(/opt/wlm/share/doc/howto/perfmon.html)
HP-UX Workload Manager homepage (http://www.hp.com/go/wlm)
libwlm(3)