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