'\"macro stdmacro
.\"
.\" Copyright (c) 2017 Red Hat.
.\"
.\" 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 PMSPRINTF 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmsprintf\f1 \- formatted string conversion
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
int pmsprintf(char *\fIstr\fP, size_t \fIsize\fP, const char *\fIfmt\fP, ... /*\fIargs\fP*/);
.sp
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
Safe string formatting interface that wraps the
.BR vsnprintf (3)
call.
.PP
It differs primarily in that
.B pmsprintf
guarantees that the output buffer
.I str
will be null-terminated even when the provided buffer
.I size
is insufficient to contain the formatted string.
In this case a null-terminated truncated string will be returned in
.IR str .
.PP
In the case of a failure in the underlying
.I vsnprintf
interface,
a null-terminated empty string will be returned in
.IR str ,
and the return value will be zero.
.SH DIAGNOSTICS
On successful completion,
.B pmsprintf
returns the number of characters written to the supplied buffer,
not including the null terminator.
.PP
The return code is always zero or more, never negative.
.SH SEE ALSO
.BR vsnprintf (3),
.BR pmprintf (3)
and
.BR PMAPI (3).