PMC_ATTACH(3)          FreeBSD 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.  Argument
     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 instruction 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)

FreeBSD 13.1-RELEASE-p6        November 25, 2007       FreeBSD 13.1-RELEASE-p6