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