From c4a638e4ab7cbb2aad3504810165300ce71a4ae1 Mon Sep 17 00:00:00 2001 From: jkoshy Date: Sat, 24 Nov 2007 11:05:36 +0000 Subject: Describe convenience functions `pmc_name_of_{capability,class,cputype, disposition,event,mode,state}' in their own manual page. --- lib/libpmc/Makefile | 14 ++-- lib/libpmc/pmc_name_of_capability.3 | 140 ++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+), 7 deletions(-) create mode 100644 lib/libpmc/pmc_name_of_capability.3 diff --git a/lib/libpmc/Makefile b/lib/libpmc/Makefile index b1b35a4..43bcfe1 100644 --- a/lib/libpmc/Makefile +++ b/lib/libpmc/Makefile @@ -8,12 +8,12 @@ INCS= pmc.h pmclog.h WARNS?= 6 MAN= pmc.3 pmc_allocate.3 pmc_disable.3 pmc_event_names_of_class.3 +MAN+= pmc_name_of_capability.3 MAN+= pmclog.3 MLINKS+= \ pmc_allocate.3 pmc_release.3 \ pmc.3 pmc_attach.3 \ - pmc.3 pmc_capabilities.3 \ pmc.3 pmc_configure_logfile.3 \ pmc.3 pmc_cpuinfo.3 \ pmc.3 pmc_detach.3 \ @@ -21,12 +21,12 @@ MLINKS+= \ pmc.3 pmc_flush_logfile.3 \ pmc.3 pmc_get_driver_stats.3 \ pmc.3 pmc_init.3 \ - pmc.3 pmc_name_of_capability.3 \ - pmc.3 pmc_name_of_class.3 \ - pmc.3 pmc_name_of_cputype.3 \ - pmc.3 pmc_name_of_event.3 \ - pmc.3 pmc_name_of_mode.3 \ - pmc.3 pmc_name_of_state.3 \ + pmc_name_of_capability.3 pmc_name_of_class.3 \ + pmc_name_of_capability.3 pmc_name_of_cputype.3 \ + pmc_name_of_capability.3 pmc_name_of_disposition.3 \ + pmc_name_of_capability.3 pmc_name_of_event.3 \ + pmc_name_of_capability.3 pmc_name_of_mode.3 \ + pmc_name_of_capability.3 pmc_name_of_state.3 \ pmc.3 pmc_ncpu.3 \ pmc.3 pmc_npmc.3 \ pmc.3 pmc_pmcinfo.3 \ diff --git a/lib/libpmc/pmc_name_of_capability.3 b/lib/libpmc/pmc_name_of_capability.3 new file mode 100644 index 0000000..53ddfdf --- /dev/null +++ b/lib/libpmc/pmc_name_of_capability.3 @@ -0,0 +1,140 @@ +.\" Copyright (c) 2007 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" $FreeBSD$ +.\" +.Dd November 24, 2007 +.Os +.Dt PMC_NAME_OF_CAPABILITY 3 +.Sh NAME +.Nm pmc_name_of_capability , +.Nm pmc_name_of_class , +.Nm pmc_name_of_cputype , +.Nm pmc_name_of_disposition , +.Nm pmc_name_of_event , +.Nm pmc_name_of_mode , +.Nm pmc_name_of_state +.Nd human readable names for numeric constants used by +.Xr pmc 3 +and +.Xr hwpmc 4 +.Sh LIBRARY +.Lb libpmc +.Sh SYNOPSIS +.In pmc.h +.Ft "const char *" +.Fn pmc_name_of_capability "enum pmc_caps pc" +.Ft "const char *" +.Fn pmc_name_of_class "enum pmc_class pc" +.Ft "const char *" +.Fn pmc_name_of_cputype "enum pmc_cputype ct" +.Ft "const char *" +.Fn pmc_name_of_disposition "enum pmc_disp pd" +.Ft "const char *" +.Fn pmc_name_of_event "enum pmc_event pe" +.Ft "const char *" +.Fn pmc_name_of_mode "enum pmc_mode pm" +.Ft "const char *" +.Fn pmc_name_of_state "enum pmc_state ps" +.Sh DESCRIPTION +These convenience functions translate numeric constants used by the +.Lb libpmc +to +.Vt "const char *" +pointers to human readable representations of their arguments. +.Pp +Function +.Fn pmc_name_of_capability +translates a PMC capability flag given in argument +.Fa pc +to a human readable string. +PMC capabilities are described in +.Xr pmc 3 . +.Pp +Function +.Fn pmc_name_of_class +translates the PMC class value specified in argument +.Fa pc +to a human readable name. +PMC classes are described in +.Xr pmc 3 . +.Pp +Function +.Fn pmc_name_of_cputype +translates the CPU type value specified in argument +.Fa ct +to a human readable name. +CPU types known to the library are described in +.Xr pmc 3 . +.Pp +Function +.Fn pmc_name_of_disposition +translates the PMC row disposition specified in argument +.Fa pd +to a human readable name. +PMC row dispositions are described in +.Xr hwpmc 4 . +.Pp +Function +.Fn pmc_name_of_event +translates the PMC event number specified by argument +.Fa pe +to a string. +PMC event names are documented in section +.Sx EVENT SPECIFIERS +of +.Xr pmc 3 . +.Pp +Function +.Fn pmc_name_of_mode +translates the PMC mode specified by argument +.Fa pm +to a human readable string. +PMC modes are described in +.Xr pmc 3 . +.Pp +Function +.Fn pmc_name_of_state +translates the value of argument +.Fa ps +to a human readable name. +.Sh IMPLEMENTATION NOTES +The returned pointers point to static storage inside the PMC +library and should not be freed by the caller. +.Sh RETURN VALUES +These functions return a non-NULL pointer on successful completion. +In case of an error, a NULL pointer is returned and the global +variable +.Va errno +is set to indicate the error. +.Sh ERRORS +A call to these functions may fail with the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The function argument specified an invalid value. +.El +.Sh SEE ALSO +.Xr pmc 3 , +.Xr pmc_cpuinfo 3 , +.Xr pmc_pmcinfo 3 , +.Xr hwpmc 4 -- cgit v1.1