lib/libpmc/pmc_attach.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 25, 2007
  27 .Dt PMC_ATTACH 3
  28 .Os
  29 .Sh NAME
  30 .Nm pmc_attach ,
  31 .Nm pmc_detach
  32 .Nd attaching and detaching process scope PMCs to target processes
  33 .Sh LIBRARY
  34 .Lb libpmc
  35 .Sh SYNOPSIS
  36 .In pmc.h
  37 .Ft int
  38 .Fn pmc_attach "pmc_id_t pmcid" "pid_t pid"
  39 .Ft int
  40 .Fn pmc_detach "pmc_id_t pmcid" "pid_t pid"
  41 .Sh DESCRIPTION
  42 These functions control the set of target processes tracked by a
  43 process scope PMC.
  44 .Pp
  45 Function
  46 .Fn pmc_attach
  47 is used to attach a process scope PMC specified by argument
  48 .Fa pmcid
  49 to a target process specified by argument
  50 .Fa pid .
  51 Argument
  52 .Fa pid
  53 may be zero to denote the current process.
  54 If the PMC was allocated with modifier
  55 .Dv PMC_F_DESCENDANTS ,
  56 the PMC will additionally attach to current and future descendents of
  57 the specified target process.
  58 The PMC should be in a quiescent state (i.e., not running).
  59 .Pp
  60 Function
  61 .Fn pmc_detach
  62 is used to detach a process scope PMC specified by argument
  63 .Fa pmcid
  64 from a process specified by argument
  65 .Fa pid .
  66 Argument
  67 .Fa pid
  68 may be zero to denote the current process.
  69 .Sh RETURN VALUES
  70 .Rv -std
  71 .Sh ERRORS
  72 A call to function
  73 .Fn pmc_attach
  74 may fail with the following errors:
  75 .Bl -tag -width Er
  76 .It Bq Er EBUSY
  77 Argument
  78 .Fa pmcid
  79 specified a PMC that was not in a quiescent state.
  80 .It Bq Er EBUSY
  81 The target process specified by function
  82 .Fa pmc_attach
  83 is being tracked by another process scope PMC that uses the same PMC
  84 hardware resources.
  85 .It Bq Er EEXIST
  86 The target process is already being tracked by the specified PMC.
  87 .It Bq Er EINVAL
  88 Argument
  89 .Fa pmcid
  90 specified a PMC with system scope.
  91 .It Bq Er EINVAL
  92 Argument
  93 .Fa pid
  94 specified an illegal process id.
  95 .It Bq Er EINVAL
  96 The current process does not own a PMC with the handle specified in
  97 argument
  98 .Fa pmcid .
  99 .It Bq Er EPERM
 100 The caller lacked the privilege needed to attach PMCs to
 101 the specified target process.
 102 .It Bq Er EPERM
 103 (i386 and amd64 architectures) The PMC specified by argument
 104 .Fa pmcid
 105 has been setup to allow the use of the RDPMC instruction for
 106 self measurement.
 107 .It Bq Er ESRCH
 108 The current process does not own any PMCs.
 109 .It Bq Er ESRCH
 110 The process specified by argument
 111 .Fa pid
 112 did not exist.
 113 .El
 114 .Pp
 115 A call to function
 116 .Fn pmc_detach
 117 may fail with the following errors:
 118 .Bl -tag -width Er
 119 .It Bq Er EINVAL
 120 Argument
 121 .Fa pmcid
 122 specified a PMC with system scope.
 123 .It Bq Er EINVAL
 124 Argument
 125 .Fa pid
 126 specified an illegal process id.
 127 .It Bq Er EINVAL
 128 The current process does not own a PMC with the handle specified in
 129 argument
 130 .Fa pmcid .
 131 .It Bq Er EINVAL
 132 The specified PMC was not attached to the target process.
 133 .It Bq Er ESRCH
 134 The current process does not own any PMCs.
 135 .It Bq Er ESRCH
 136 The process specified by argument
 137 .Fa pid
 138 is not being monitored by
 139 .Xr hwpmc 4 .
 140 .It Bq Er ESRCH
 141 The process specified by argument
 142 .Fa pid
 143 did not exist.
 144 .El
 145 .Sh SEE ALSO
 146 .Xr pmc 3 ,
 147 .Xr pmc_start 3 ,
 148 .Xr pmc_stop 3 ,
 149 .Xr hwpmc 4