'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMPRINTVALUE 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmPrintValue\f1 \- print a performance metric value
.SH "C SYNOPSIS"
.ft 3
.ad l
.hy 0
#include <stdio.h>
.br
#include <pcp/pmapi.h>
.sp
void pmPrintValue(FILE *\fIf\fP,
'in +\w'void pmPrintValue('u
int\ \fIvalfmt\fP,
int\ \fItype\fP,
const\ pmValue\ *\fIval\fP,
int\ \fIminwidth\fP);
.in
.sp
cc ... \-lpcp
.hy
.ad
.ft 1
.SH DESCRIPTION
.de CR
.ie t \f(CR\\$1\f1\\$2
.el \fI\\$1\f1\\$2
..
The value of a single performance metric (as identified by
.IR val )
is printed on the standard I/O stream identified by
.IR f .
.PP
The value of the performance metric is interpreted according to the format of
.I val
as
defined by
.I valfmt
(from a
.CR pmValueSet
within a
.CR pmResult
structure; see
.BR pmFetch (3))
and the generic description of the metrics type
passed in via
.IR type .
.PP
The value for
.I type
is typically extracted from a
.CR pmDesc
structure, following a call to
.BR pmLookupDesc (3)
for a particular performance metric.
.PP
The output will be optionally padded to be at least
.I minwidth
characters wide.
.PP
.B pmPrintValue
is most useful for displaying values of performance metrics from
.BR pmFetch (3)
(which returns a set of
.I valfmt
and
.I val
pairs for each requested metric), based upon the
metrics type as returned from
.BR pmLookupDesc (3).
.SH ENVIRONMENT
Output of string metric values can be further controlled using
.BR PCP_SQUASH_NEWLINES .
When set in the environment of the calling process, and the
.I type
is set to PM_TYPE_STRING or PM_TYPE_AGGREGATE, then the output
value is guaranteed to be free of embedded newline characters.
If the given value contained such characters, they will have been
replaced by a space before being printed.
.SH SEE ALSO
.BR PMAPI (3),
.BR pmAtomStr (3),
.BR pmConvScale (3),
.BR pmExtractValue (3),
.BR pmFetch (3),
.BR pmLookupDesc (3),
.BR pmTypeStr (3)
and
.BR pmUnitsStr (3).

.\" control lines for scripts/man-spell
.\" +ok+ PCP_SQUASH_NEWLINES {env var}