NAME

       pmOpenLog - create a log file for diagnostics and debug output

C SYNOPSIS

       #include <pcp/pmapi.h>

       FILE *pmOpenLog(const char *progname, const char *logname, FILE *oldstream, int *status);

       cc ... -lpcp

DESCRIPTION

       pmOpenLog  reassigns  the  standard I/O stream oldstream (normally stderr) to be associated with the file
       logname.

       If logname is not "-" and the file already exists, it will be renamed to logname.prev else removed.   Due
       to  permissions  restrictions,  the  rename  or removal may not succeed, but in the common use cases log‐
       name.prev remains with the contents of the previous version of logname.  Then  logname  is  recreated  if
       possible (to ensure correct ownership and permissions from the caller to pmOpenLog).

       As a special case, if logname is "-" then no renaming, removal or reopening is performed and the function
       simply  sets status to 1 and returns oldstream.  This is useful when the caller wants diagnostics on old‐
       stream stream (normally stderr) rather than a file, e.g.  pmlogger -l- or pmcd -f -l-.  Logging to stderr
       is also useful for PMDAs in a containerized environment where it is beneficial for all PMDA  logs  to  be
       written  to  pmcd's  stderr stream (and thus to a single destination), whether that is a file such as pm‐
       cd.log or the original stream inherited from the shell.

       On return, the function value is the standard I/O stream, possibly replacing oldstream.  In the event  of
       an error, the return value will be oldstream unchanged and status will be 0.

       For success, status is 1, and a standard preamble is written to logname
            Log for progname on hostname started date and time
       and an atexit(3) handler is installed to write the postscript message to logname
            Log finished date and time
       when the processes exits.

       progname is only used to annotate messages.

SEE ALSO

       atexit(3) and freopen(3).

Performance Co-Pilot                                   PCP                                          PMOPENLOG(3)