'\"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 PMOPENLOG 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmOpenLog\f1 \- create a log file for diagnostics and debug output
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
.ad l
.hy 0
.in +8n
.ti -8n
FILE *pmOpenLog(const char *\fIprogname\fP, const char *\fIlogname\fP, FILE\ *\fIoldstream\fP, int\ *\fIstatus\fP);
.sp
.in
.hy
.ad
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
.B pmOpenLog
reassigns the standard I/O stream
.I oldstream
(normally
.BR stderr )
to be associated with the file
.IR logname .
.PP
If
.I logname
is not \fB"\-"\fP
and the file already exists,
it will be renamed to
.IB logname .prev
else removed.
Due to permissions restrictions, the rename or removal may not
succeed, but in the common use cases
.IB logname .prev
remains with the contents of the previous version of
.IR logname .
Then
.I logname
is recreated if possible (to ensure correct ownership
and permissions from the caller to
.BR pmOpenLog ).
.PP
As a special case, if
.I logname
is "\fB\-\fR"
then no renaming, removal or reopening is performed and
the function simply sets
.I status
to
.B 1
and returns
.IR oldstream .
This is useful when the caller wants diagnostics on
.I oldstream
stream (normally
.BR stderr )
rather than a file, e.g.
.B "pmlogger \-l\-"
or
.BR "pmcd \-f \-l\-" .
Logging to
.B stderr
is also useful for PMDAs in a containerized environment where
it is beneficial for all PMDA logs to be written to
.BR pmcd 's
.B stderr
stream (and thus to a single destination), whether that is a file such as
.B pmcd.log
or the original
stream inherited from the shell.
.PP
On return, the function value is the standard I/O stream, possibly replacing
.IR oldstream .
In the
event of an error, the return value will be
.I oldstream
unchanged and
.I status
will be
.BR 0 .
.PP
For success,
.I status
is
.BR 1 ,
and a standard preamble is written to
.I logname
.ti +0.5i
.ft B
Log for \fIprogname\fB on \fIhostname\fB started \fIdate and time\fB
.ft R
.br
and an
.BR atexit (3)
handler is installed to write the postscript message to
.I logname
.ti +0.5i
.ft B
Log finished \fIdate and time\fB
.ft R
.br
when the processes exits.
.PP
.I progname
is only used to annotate messages.
.SH SEE ALSO
.BR atexit (3)
and
.BR freopen (3).