lib/libpmc/pmc_configure_logfile.3

   1 .\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .Dd November 24, 2007
  25 .Dt PMC_CONFIGURE_LOGFILE 3
  26 .Os
  27 .Sh NAME
  28 .Nm pmc_configure_logfile ,
  29 .Nm pmc_flush_logfile ,
  30 .Nm pmc_writelog ,
  31 .Nm pmc_close_logfile
  32 .Nd log file management
  33 .Sh LIBRARY
  34 .Lb libpmc
  35 .Sh SYNOPSIS
  36 .In pmc.h
  37 .Ft int
  38 .Fn pmc_configure_logfile "int fd"
  39 .Ft int
  40 .Fn pmc_flush_logfile void
  41 .Ft int
  42 .Fn pmc_writelog "uint32_t userdata"
  43 .Ft int
  44 .Fn pmc_close_logfile void
  45 .Sh DESCRIPTION
  46 The functions manage logging of
  47 .Xr hwpmc 4
  48 events.
  49 .Pp
  50 Function
  51 .Fn pmc_configure_logfile
  52 is used to turn on and turn off logging.
  53 If argument
  54 .Fa fd
  55 is a valid file handle returned by a prior call to
  56 .Xr open 2
  57 or
  58 .Xr socket 2
  59 then performance events will be logged to the file corresponding
  60 to the specified handle.
  61 If the value of argument
  62 .Fa fd
  63 is -1 then logging will be stopped after any pending data is flushed.
  64 .Pp
  65 Function
  66 .Fn pmc_flush_logfile
  67 will force all log data queued inside the
  68 .Xr hwpmc 4
  69 driver to be written out.
  70 .Pp
  71 Function
  72 .Fn pmc_writelog
  73 will append a log entry containing the value of argument
  74 .Fa userdata
  75 to the log file.
  76 .Pp
  77 Function
  78 .Fn pmc_close_logfile
  79 will flush all pending log data and close
  80 .Xr hwpmc 4 Ns Ap s
  81 side of the stream.
  82 .Sh RETURN VALUES
  83 .Rv -std
  84 .Sh ERRORS
  85 A call to
  86 .Fn pmc_configure_logfile
  87 may fail with the following errors:
  88 .Bl -tag -width Er
  89 .It Bq Er EAGAIN
  90 The
  91 .Xr hwpmc 4
  92 driver was not able to create a helper process due to system limits
  93 being reached.
  94 .It Bq Er EBUSY
  95 Function
  96 .Fn pmc_configure_logfile
  97 was called with a log file already configured.
  98 .It Bq Er EINVAL
  99 Function
 100 .Fn pmc_configure_logfile
 101 was called with an argument of -1 without a log file being previously
 102 configured.
 103 .It Bq Er ENOMEM
 104 The system encountered a memory shortage when servicing this request.
 105 .El
 106 .Pp
 107 A call to
 108 .Fn pmc_flush_logfile
 109 may fail with the following errors:
 110 .Bl -tag -width Er
 111 .It Bq Er EINVAL
 112 Function
 113 .Fn pmc_flush_logfile
 114 was called without a log file being previously configured.
 115 .El
 116 .Pp
 117 A call to
 118 .Fn pmc_writelog
 119 may fail with the following errors:
 120 .Bl -tag -width Er
 121 .It Bq Er EINVAL
 122 Function
 123 .Fn pmc_writelog
 124 was called without a log file being previously configured.
 125 .It Bq Er ENOMEM
 126 The system encountered a memory shortage when servicing this
 127 request.
 128 .El
 129 .Sh SEE ALSO
 130 .Xr pmc 3 ,
 131 .Xr hwpmc 4