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