lib/libpmc/pmc_name_of_capability.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 .\" $FreeBSD$
  25 .\"
  26 .Dd November 24, 2007
  27 .Dt PMC_NAME_OF_CAPABILITY 3
  28 .Os
  29 .Sh NAME
  30 .Nm pmc_name_of_capability ,
  31 .Nm pmc_name_of_class ,
  32 .Nm pmc_name_of_cputype ,
  33 .Nm pmc_name_of_disposition ,
  34 .Nm pmc_name_of_event ,
  35 .Nm pmc_name_of_mode ,
  36 .Nm pmc_name_of_state
  37 .Nd human readable names for numeric constants used by
  38 .Xr pmc 3
  39 and
  40 .Xr hwpmc 4
  41 .Sh LIBRARY
  42 .Lb libpmc
  43 .Sh SYNOPSIS
  44 .In pmc.h
  45 .Ft "const char *"
  46 .Fn pmc_name_of_capability "enum pmc_caps pc"
  47 .Ft "const char *"
  48 .Fn pmc_name_of_class "enum pmc_class pc"
  49 .Ft "const char *"
  50 .Fn pmc_name_of_cputype "enum pmc_cputype ct"
  51 .Ft "const char *"
  52 .Fn pmc_name_of_disposition "enum pmc_disp pd"
  53 .Ft "const char *"
  54 .Fn pmc_name_of_event "enum pmc_event pe"
  55 .Ft "const char *"
  56 .Fn pmc_name_of_mode "enum pmc_mode pm"
  57 .Ft "const char *"
  58 .Fn pmc_name_of_state "enum pmc_state ps"
  59 .Sh DESCRIPTION
  60 These convenience functions translate numeric constants used by the
  61 .Lb libpmc
  62 to
  63 .Vt "const char *"
  64 pointers to human readable representations of their arguments.
  65 .Pp
  66 Function
  67 .Fn pmc_name_of_capability
  68 translates a PMC capability flag given in argument
  69 .Fa pc
  70 to a human readable string.
  71 PMC capabilities are described in
  72 .Xr pmc 3 .
  73 .Pp
  74 Function
  75 .Fn pmc_name_of_class
  76 translates the PMC class value specified in argument
  77 .Fa pc
  78 to a human readable name.
  79 PMC classes are described in
  80 .Xr pmc 3 .
  81 .Pp
  82 Function
  83 .Fn pmc_name_of_cputype
  84 translates the CPU type value specified in argument
  85 .Fa ct
  86 to a human readable name.
  87 CPU types known to the library are described in
  88 .Xr pmc 3 .
  89 .Pp
  90 Function
  91 .Fn pmc_name_of_disposition
  92 translates the PMC row disposition specified in argument
  93 .Fa pd
  94 to a human readable name.
  95 PMC row dispositions are described in
  96 .Xr hwpmc 4 .
  97 .Pp
  98 Function
  99 .Fn pmc_name_of_event
 100 translates the PMC event number specified by argument
 101 .Fa pe
 102 to a string.
 103 PMC event names are documented in section
 104 .Sx EVENT SPECIFIERS
 105 of
 106 .Xr pmc 3 .
 107 .Pp
 108 Function
 109 .Fn pmc_name_of_mode
 110 translates the PMC mode specified by argument
 111 .Fa pm
 112 to a human readable string.
 113 PMC modes are described in
 114 .Xr pmc 3 .
 115 .Pp
 116 Function
 117 .Fn pmc_name_of_state
 118 translates the value of argument
 119 .Fa ps
 120 to a human readable name.
 121 .Sh IMPLEMENTATION NOTES
 122 The returned pointers point to static storage inside the PMC
 123 library and should not be freed by the caller.
 124 .Sh RETURN VALUES
 125 These functions return a non-NULL pointer on successful completion.
 126 In case of an error, a NULL pointer is returned and the global
 127 variable
 128 .Va errno
 129 is set to indicate the error.
 130 .Sh ERRORS
 131 A call to these functions may fail with the following errors:
 132 .Bl -tag -width Er
 133 .It Bq Er EINVAL
 134 The function argument specified an invalid value.
 135 .El
 136 .Sh SEE ALSO
 137 .Xr pmc 3 ,
 138 .Xr pmc_cpuinfo 3 ,
 139 .Xr pmc_pmcinfo 3 ,
 140 .Xr hwpmc 4