pmc_attach(3) [freebsd man page]

PMC_ATTACH(3)						   BSD Library Functions Manual 					     PMC_ATTACH(3)

NAME

     pmc_attach, pmc_detach -- attaching and detaching process scope PMCs to target processes

LIBRARY

     Performance Counters Library (libpmc, -lpmc)

SYNOPSIS

     #include <pmc.h>

     int
     pmc_attach(pmc_id_t pmcid, pid_t pid);

     int
     pmc_detach(pmc_id_t pmcid, pid_t pid);

DESCRIPTION

     These functions control the set of target processes tracked by a process scope PMC.

     Function pmc_attach() is used to attach a process scope PMC specified by argument pmcid to a target process specified by argument pid.  Argu-
     ment pid may be zero to denote the current process.  If the PMC was allocated with modifier PMC_F_DESCENDANTS, the PMC will additionally
     attach to current and future descendents of the specified target process.	The PMC should be in a quiescent state (i.e., not running).

     Function pmc_detach() is used to detach a process scope PMC specified by argument pmcid from a process specified by argument pid.	Argument
     pid may be zero to denote the current process.

RETURN VALUES

     Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable errno is set to indicate the
     error.

ERRORS

     A call to function pmc_attach() may fail with the following errors:

     [EBUSY]		Argument pmcid specified a PMC that was not in a quiescent state.

     [EBUSY]		The target process specified by function pmc_attach is being tracked by another process scope PMC that uses the same PMC
			hardware resources.

     [EEXIST]		The target process is already being tracked by the specified PMC.

     [EINVAL]		Argument pmcid specified a PMC with system scope.

     [EINVAL]		Argument pid specified an illegal process id.

     [EINVAL]		The current process does not own a PMC with the handle specified in argument pmcid.

     [EPERM]		The caller lacked the privilege needed to attach PMCs to the specified target process.

     [EPERM]		(i386 and amd64 architectures) The PMC specified by argument pmcid has been setup to allow the use of the RDPMC instruc-
			tion for self measurement.

     [ESRCH]		The current process does not own any PMCs.

     [ESRCH]		The process specified by argument pid did not exist.

     A call to function pmc_detach() may fail with the following errors:

     [EINVAL]		Argument pmcid specified a PMC with system scope.

     [EINVAL]		Argument pid specified an illegal process id.

     [EINVAL]		The current process does not own a PMC with the handle specified in argument pmcid.

     [EINVAL]		The specified PMC was not attached to the target process.

     [ESRCH]		The current process does not own any PMCs.

     [ESRCH]		The process specified by argument pid is not being monitored by hwpmc(4).

     [ESRCH]		The process specified by argument pid did not exist.

SEE ALSO

     pmc(3), pmc_start(3), pmc_stop(3), hwpmc(4)

BSD
								 November 25, 2007							       BSD

PMC_ALLOCATE(3) 					   BSD Library Functions Manual 					   PMC_ALLOCATE(3)

NAME

     pmc_allocate, pmc_release -- allocate and free performance monitoring counters

LIBRARY

     Performance Counters Library (libpmc, -lpmc)

SYNOPSIS

     #include <pmc.h>

     int
     pmc_allocate(const char *eventspecifier, enum pmc_mode mode, uint32_t flags, int cpu, pmc_id_t *pmcid);

     int
     pmc_release(pmc_id_t pmc);

DESCRIPTION

     Function pmc_allocate() allocates a performance monitoring counter that measures the events named by argument eventspecifier, and writes the
     allocated handle to the location pointed to by argument pmcid.

     Argument eventspecifier comprises an PMC event name followed by an optional comma separated list of keywords and qualifiers.  The allowed
     syntax for argument eventspecifier is processor specific and is listed in section EVENT SPECIFIERS in the pmc(3) manual page.

     The desired PMC mode is specified by argument mode.  Legal values for the mode argument are:
     PMC_MODE_SC  Allocate a system-scope counting PMC.
     PMC_MODE_SS  Allocate a system-scope sampling PMC.
     PMC_MODE_TC  Allocate a process-scope counting PMC.
     PMC_MODE_TS  Allocate a process-scope sampling PMC.

     Mode specific modifiers may be specified using argument flags.  The flags supported at PMC allocation time are:
     PMC_F_DESCENDANTS	 For process-scope PMCs, automatically track descendants of attached processes.
     PMC_F_LOG_PROCCSW	 For process-scope counting PMCs, generate a log event at every context switch containing the incremental number of hard-
			 ware events seen by the process during the time it was executing on the CPU.
     PMC_F_LOG_PROCEXIT  For process-scope counting PMCs, accumulate hardware events seen when the process was executing on a CPU and generate a
			 log event when an attached process exits.
     PMCs allocated with flags PMC_F_LOG_PROCCSW and PMC_F_LOG_PROCEXIT need a log file to be configured before they are started.

     For system scope PMCs, the argument cpu is a non-negative value that specifies the CPU number that the PMC is to be allocated on.	Process
     scope PMC allocations should specify the constant PMC_CPU_ANY for this argument.

     Function pmc_release() releases the PMC denoted by argument pmcid.

RETURN VALUES

     If successful, function pmc_allocate() sets the location specified by argument pmcid to the handle of the allocated PMC and returns 0.  In
     case of an error, the function returns -1 and sets the global variable errno to indicate the error.

     The pmc_release() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to
     indicate the error.

ERRORS

     [EINVAL]		The argument mode to function pmc_allocate() had an invalid value.

     [EINVAL]		Argument cpu to function pmc_allocate() had an invalid CPU number.

     [EINVAL]		Argument flags contained flags that were unsupported or otherwise incompatible with the requested PMC mode.

     [EINVAL]		Argument eventspecifier to function pmc_allocate() specified an event not supported by hardware or contained a syntax
			error.

     [ENXIO]		Function pmc_allocate() requested the use of a hardware resource that was absent or administratively disabled.

     [EOPNOTSUPP]	The underlying hardware does not support the capabilities needed for a PMC being allocated by a call to pmc_allocate().

     [EPERM]		A system scope PMC allocation was attempted without adequate process privilege.

     [ESRCH]		Function pmc_release() was called without first having allocated a PMC.

     [EINVAL]		Argument pmcid to function pmc_release() did not specify a PMC previously allocated by this process.

SEE ALSO

     pmc(3), pmc_attach(3), pmc_configure_logfile(3), pmc_start(3), hwpmc(4)

BSD
								September 22, 2008							       BSD