1677d4530SJoseph Koshy.\" Copyright (c) 2007 Joseph Koshy. All rights reserved. 2677d4530SJoseph Koshy.\" 3677d4530SJoseph Koshy.\" Redistribution and use in source and binary forms, with or without 4677d4530SJoseph Koshy.\" modification, are permitted provided that the following conditions 5677d4530SJoseph Koshy.\" are met: 6677d4530SJoseph Koshy.\" 1. Redistributions of source code must retain the above copyright 7677d4530SJoseph Koshy.\" notice, this list of conditions and the following disclaimer. 8677d4530SJoseph Koshy.\" 2. Redistributions in binary form must reproduce the above copyright 9677d4530SJoseph Koshy.\" notice, this list of conditions and the following disclaimer in the 10677d4530SJoseph Koshy.\" documentation and/or other materials provided with the distribution. 11677d4530SJoseph Koshy.\" 12*026dbd29SChristian Brueffer.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13*026dbd29SChristian Brueffer.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14*026dbd29SChristian Brueffer.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15*026dbd29SChristian Brueffer.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16*026dbd29SChristian Brueffer.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17*026dbd29SChristian Brueffer.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18*026dbd29SChristian Brueffer.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19*026dbd29SChristian Brueffer.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20*026dbd29SChristian Brueffer.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21*026dbd29SChristian Brueffer.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22*026dbd29SChristian Brueffer.\" SUCH DAMAGE. 23677d4530SJoseph Koshy.\" 24cf6c5eebSChristian Brueffer.Dd November 25, 2007 25677d4530SJoseph Koshy.Dt PMC_ATTACH 3 26aa12cea2SUlrich Spörlein.Os 27677d4530SJoseph Koshy.Sh NAME 28677d4530SJoseph Koshy.Nm pmc_attach , 29677d4530SJoseph Koshy.Nm pmc_detach 30677d4530SJoseph Koshy.Nd attaching and detaching process scope PMCs to target processes 31677d4530SJoseph Koshy.Sh LIBRARY 32677d4530SJoseph Koshy.Lb libpmc 33677d4530SJoseph Koshy.Sh SYNOPSIS 34677d4530SJoseph Koshy.In pmc.h 35677d4530SJoseph Koshy.Ft int 36677d4530SJoseph Koshy.Fn pmc_attach "pmc_id_t pmcid" "pid_t pid" 37677d4530SJoseph Koshy.Ft int 38677d4530SJoseph Koshy.Fn pmc_detach "pmc_id_t pmcid" "pid_t pid" 39677d4530SJoseph Koshy.Sh DESCRIPTION 40677d4530SJoseph KoshyThese functions control the set of target processes tracked by a 41677d4530SJoseph Koshyprocess scope PMC. 42677d4530SJoseph Koshy.Pp 43677d4530SJoseph KoshyFunction 44677d4530SJoseph Koshy.Fn pmc_attach 45677d4530SJoseph Koshyis used to attach a process scope PMC specified by argument 46677d4530SJoseph Koshy.Fa pmcid 47677d4530SJoseph Koshyto a target process specified by argument 48677d4530SJoseph Koshy.Fa pid . 49677d4530SJoseph KoshyArgument 50677d4530SJoseph Koshy.Fa pid 51677d4530SJoseph Koshymay be zero to denote the current process. 52677d4530SJoseph KoshyIf the PMC was allocated with modifier 53677d4530SJoseph Koshy.Dv PMC_F_DESCENDANTS , 54677d4530SJoseph Koshythe PMC will additionally attach to current and future descendents of 55677d4530SJoseph Koshythe specified target process. 56677d4530SJoseph KoshyThe PMC should be in a quiescent state (i.e., not running). 57677d4530SJoseph Koshy.Pp 58677d4530SJoseph KoshyFunction 59677d4530SJoseph Koshy.Fn pmc_detach 60677d4530SJoseph Koshyis used to detach a process scope PMC specified by argument 61677d4530SJoseph Koshy.Fa pmcid 62677d4530SJoseph Koshyfrom a process specified by argument 63677d4530SJoseph Koshy.Fa pid . 64677d4530SJoseph KoshyArgument 65677d4530SJoseph Koshy.Fa pid 66677d4530SJoseph Koshymay be zero to denote the current process. 67677d4530SJoseph Koshy.Sh RETURN VALUES 68677d4530SJoseph Koshy.Rv -std 69677d4530SJoseph Koshy.Sh ERRORS 70677d4530SJoseph KoshyA call to function 71677d4530SJoseph Koshy.Fn pmc_attach 72677d4530SJoseph Koshymay fail with the following errors: 73677d4530SJoseph Koshy.Bl -tag -width Er 74677d4530SJoseph Koshy.It Bq Er EBUSY 75677d4530SJoseph KoshyArgument 76677d4530SJoseph Koshy.Fa pmcid 77677d4530SJoseph Koshyspecified a PMC that was not in a quiescent state. 78677d4530SJoseph Koshy.It Bq Er EBUSY 79677d4530SJoseph KoshyThe target process specified by function 80677d4530SJoseph Koshy.Fa pmc_attach 81677d4530SJoseph Koshyis being tracked by another process scope PMC that uses the same PMC 82677d4530SJoseph Koshyhardware resources. 83677d4530SJoseph Koshy.It Bq Er EEXIST 84677d4530SJoseph KoshyThe target process is already being tracked by the specified PMC. 85677d4530SJoseph Koshy.It Bq Er EINVAL 86677d4530SJoseph KoshyArgument 87677d4530SJoseph Koshy.Fa pmcid 88677d4530SJoseph Koshyspecified a PMC with system scope. 89677d4530SJoseph Koshy.It Bq Er EINVAL 90677d4530SJoseph KoshyArgument 91677d4530SJoseph Koshy.Fa pid 92677d4530SJoseph Koshyspecified an illegal process id. 93677d4530SJoseph Koshy.It Bq Er EINVAL 94677d4530SJoseph KoshyThe current process does not own a PMC with the handle specified in 95677d4530SJoseph Koshyargument 96677d4530SJoseph Koshy.Fa pmcid . 97677d4530SJoseph Koshy.It Bq Er EPERM 98677d4530SJoseph KoshyThe caller lacked the privilege needed to attach PMCs to 99677d4530SJoseph Koshythe specified target process. 100677d4530SJoseph Koshy.It Bq Er EPERM 101677d4530SJoseph Koshy(i386 and amd64 architectures) The PMC specified by argument 102677d4530SJoseph Koshy.Fa pmcid 103677d4530SJoseph Koshyhas been setup to allow the use of the RDPMC instruction for 104677d4530SJoseph Koshyself measurement. 105677d4530SJoseph Koshy.It Bq Er ESRCH 106677d4530SJoseph KoshyThe current process does not own any PMCs. 107677d4530SJoseph Koshy.It Bq Er ESRCH 108677d4530SJoseph KoshyThe process specified by argument 109677d4530SJoseph Koshy.Fa pid 110677d4530SJoseph Koshydid not exist. 111677d4530SJoseph Koshy.El 112677d4530SJoseph Koshy.Pp 113677d4530SJoseph KoshyA call to function 114677d4530SJoseph Koshy.Fn pmc_detach 115677d4530SJoseph Koshymay fail with the following errors: 116677d4530SJoseph Koshy.Bl -tag -width Er 117677d4530SJoseph Koshy.It Bq Er EINVAL 118677d4530SJoseph KoshyArgument 119677d4530SJoseph Koshy.Fa pmcid 120677d4530SJoseph Koshyspecified a PMC with system scope. 121677d4530SJoseph Koshy.It Bq Er EINVAL 122677d4530SJoseph KoshyArgument 123677d4530SJoseph Koshy.Fa pid 124677d4530SJoseph Koshyspecified an illegal process id. 125677d4530SJoseph Koshy.It Bq Er EINVAL 126677d4530SJoseph KoshyThe current process does not own a PMC with the handle specified in 127677d4530SJoseph Koshyargument 128677d4530SJoseph Koshy.Fa pmcid . 129677d4530SJoseph Koshy.It Bq Er EINVAL 130677d4530SJoseph KoshyThe specified PMC was not attached to the target process. 131677d4530SJoseph Koshy.It Bq Er ESRCH 132677d4530SJoseph KoshyThe current process does not own any PMCs. 133677d4530SJoseph Koshy.It Bq Er ESRCH 134677d4530SJoseph KoshyThe process specified by argument 135677d4530SJoseph Koshy.Fa pid 136677d4530SJoseph Koshyis not being monitored by 137677d4530SJoseph Koshy.Xr hwpmc 4 . 138677d4530SJoseph Koshy.It Bq Er ESRCH 139677d4530SJoseph KoshyThe process specified by argument 140677d4530SJoseph Koshy.Fa pid 141677d4530SJoseph Koshydid not exist. 142677d4530SJoseph Koshy.El 143677d4530SJoseph Koshy.Sh SEE ALSO 144677d4530SJoseph Koshy.Xr pmc 3 , 145677d4530SJoseph Koshy.Xr pmc_start 3 , 146677d4530SJoseph Koshy.Xr pmc_stop 3 , 147677d4530SJoseph Koshy.Xr hwpmc 4 148