'\"macro stdmacro
.\"
.\" Copyright (c) 2022 Red Hat.
.\" 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 PMPARSEINTERVAL 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmParseInterval\f1 \- convert interval string to binary time structure
.SH "C SYNOPSIS"
.ft 3
.ad l
.hy 0
#include <pcp/pmapi.h>
.sp
int pmParseInterval(const char *\fIstring\fP,
'in +\w'int pmParseInterval('u
struct\ timespec\ *\fIrslt\fP,
char\ **\fIerrmsg\fP);
.in
.sp
cc ... \-lpcp
.hy
.ad
.ft 1
.de CR
.ie t \f(CR\\$1\f1\\$2
.el \fI\\$1\f1\\$2
..
.SH DESCRIPTION
.B pmParseInterval
parses the argument
.I string
specifying an interval of time and fills in the
.B tv_sec
and
.B tv_nsec
components of the
.I rslt
structure to represent that interval (nanosecond precision).
.PP
The input
.I string
is most commonly the argument following a
.BR \-t
command line option to a PCP application, and
the syntax is fully described in
.BR PCPIntro (1).
.SH DIAGNOSTICS
.B pmParseInterval
returns 0 and
.I errmsg
is undefined if the parsing is successful.
.PP
If the given
.I string
does not conform to the required syntax
.B pmParseInterval
returns \-1 and a dynamically allocated
error message string in
.IR errmsg .
The error message
is terminated with a newline and
includes the text of the input
.I string
along with an indicator of the position at which the error was detected,
e.g.
.br
.in +1i
.CR "\&4minutes 30mumble"
.br
.CR "\&           ^ -- unexpected value"
.in -1i
.PP
In the case of an error, the caller is responsible for calling
.BR free (3)
to release the space allocated for
.IR errmsg .
.SH COMPATIBILITY
Prior to PCP 7.0 the
.I rslt
argument was a \f(CRstruct timeval\fP.
To support PMAPI transition, the old interface and semantics can be
used if applications are recompiled with
.BR \-DPMAPI_VERSION=2 .
.PP
For a time in PCP 6.x there was a
routine with the same semantics as the current
.B pmParseInterval
called
.B pmParseHighResInterval
although this is now deprecated and compile-time support for
.B pmParseHighResInterval
will be removed in a future release.
.SH SEE ALSO
.BR PCPIntro (1),
.BR free (3),
.BR PMAPI (3)
and
.BR pmParseTimeWindow (3).