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 Joseph Koshy ``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 Joseph Koshy 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 .\" $FreeBSD$
  25 .\"
  26 .Dd November 24, 2007
  27 .Os
  28 .Dt PMC_CONFIGURE_LOGFILE 3
  29 .Sh NAME
  30 .Nm pmc_configure_logfile ,
  31 .Nm pmc_flush_logfile ,
  32 .Nm pmc_writelog
  33 .Nd log file management
  34 .Sh LIBRARY
  35 .Lb libpmc
  36 .Sh SYNOPSIS
  37 .In pmc.h
  38 .Ft int
  39 .Fn pmc_configure_logfile "int fd"
  40 .Ft int
  41 .Fn pmc_flush_logfile void
  42 .Ft int
  43 .Fn pmc_writelog "uint32_t userdata"
  44 .Sh DESCRIPTION
  45 The functions manage logging of
  46 .Xr hwpmc 4
  47 events.
  48 .Pp
  49 Function
  50 .Fn pmc_configure_logfile
  51 is used to turn on and turn off logging.
  52 If argument
  53 .Fa fd
  54 is a valid file handle returned by a prior call to
  55 .Xr open 2
  56 or
  57 .Xr socket 2
  58 then performance events will be logged to the file corresponding
  59 to the specified handle.
  60 If the value of argument
  61 .Fa fd
  62 is -1 then logging will be stopped after any pending data is flushed.
  63 .Pp
  64 Function
  65 .Fn pmc_flush_logfile
  66 will force all log data queued inside the
  67 .Xr hwpmc 4
  68 driver to be written out.
  69 .Pp
  70 Function
  71 .Fn pmc_writelog
  72 will append a log entry containing the value of argument
  73 .Fa userdata
  74 to the log file.
  75 .Sh RETURN VALUES
  76 .Rv -std
  77 .Sh ERRORS
  78 A call to
  79 .Fn pmc_configure_logfile
  80 may fail with the following errors:
  81 .Bl -tag -width Er
  82 .It Bq Er EAGAIN
  83 The
  84 .Xr hwpmc 4
  85 driver was not able to create a helper process due to system limits
  86 being reached.
  87 .It Bq Er EBUSY
  88 Function
  89 .Fn pmc_configure_logfile
  90 was called with a log file already configured.
  91 .It Bq Er EINVAL
  92 Function
  93 .Fn pmc_configure_logfile
  94 was called with an argument of -1 without a log file being previously
  95 configured.
  96 .It Bq Er ENOMEM
  97 The system encountered a memory shortage when servicing this request.
  98 .El
  99 .Pp
 100 A call to
 101 .Fn pmc_flush_logfile
 102 may fail with the following errors:
 103 .Bl -tag -width Er
 104 .It Bq Er EINVAL
 105 Function
 106 .Fn pmc_flush_logfile
 107 was called without a log file being previously configured.
 108 .El
 109 .Pp
 110 A call to
 111 .Fn pmc_writelog
 112 may fail with the following errors:
 113 .Bl -tag -width Er
 114 .It Bq Er EINVAL
 115 Function
 116 .Fn pmc_writelog
 117 was called without a log file being previously configured.
 118 .It Bq Er ENOMEM
 119 The system encountered a memory shortage when servicing this
 120 request.
 121 .El
 122 .Sh SEE ALSO
 123 .Xr pmc 3 ,
 124 .Xr hwpmc 4