d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ab8f652cd7
freebsd-skq/lib/libpmc/pmc_attach.3

150 lines
4.1 KiB
Groff
Raw Normal View History

Move the following functions into their own manual pages: - pmc_attach(), pmc_detach(). - pmc_capabilities(), pmc_cpuinfo(), pmc_ncpu(), pmc_npmc(), pmc_pmcinfo(), pmc_width(). - pmc_get_driver_stats(). - pmc_get_msr(). - pmc_read(), pmc_rw(), pmc_write(). - pmc_set(). - pmc_start(), pmc_stop().
2007-11-25 06:38:55 +00:00
.\" Copyright (c) 2007 Joseph Koshy. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" This software is provided by Joseph Koshy ``as is'' and
.\" any express or implied warranties, including, but not limited to, the
.\" implied warranties of merchantability and fitness for a particular purpose
.\" are disclaimed. in no event shall Joseph Koshy be liable
.\" for any direct, indirect, incidental, special, exemplary, or consequential
.\" damages (including, but not limited to, procurement of substitute goods
.\" or services; loss of use, data, or profits; or business interruption)
.\" however caused and on any theory of liability, whether in contract, strict
.\" liability, or tort (including negligence or otherwise) arising in any way
.\" out of the use of this software, even if advised of the possibility of
.\" such damage.
.\"
.\" $FreeBSD$
.\"
Use our canonical .Dd format. Submitted by: Ulrich Spoerlein
2009-11-02 12:35:38 +00:00
.Dd November 25, 2007
Move the following functions into their own manual pages: - pmc_attach(), pmc_detach(). - pmc_capabilities(), pmc_cpuinfo(), pmc_ncpu(), pmc_npmc(), pmc_pmcinfo(), pmc_width(). - pmc_get_driver_stats(). - pmc_get_msr(). - pmc_read(), pmc_rw(), pmc_write(). - pmc_set(). - pmc_start(), pmc_stop().
2007-11-25 06:38:55 +00:00
.Dt PMC_ATTACH 3
mdoc: order prologue macros consistently by Dd/Dt/Os Although groff_mdoc(7) gives another impression, this is the ordering most widely used and also required by mdocml/mandoc. Reviewed by: ru Approved by: philip, ed (mentors)
2010-04-14 19:08:06 +00:00
.Os
Move the following functions into their own manual pages: - pmc_attach(), pmc_detach(). - pmc_capabilities(), pmc_cpuinfo(), pmc_ncpu(), pmc_npmc(), pmc_pmcinfo(), pmc_width(). - pmc_get_driver_stats(). - pmc_get_msr(). - pmc_read(), pmc_rw(), pmc_write(). - pmc_set(). - pmc_start(), pmc_stop().
2007-11-25 06:38:55 +00:00
.Sh NAME
.Nm pmc_attach ,
.Nm pmc_detach
.Nd attaching and detaching process scope PMCs to target processes
.Sh LIBRARY
.Lb libpmc
.Sh SYNOPSIS
.In pmc.h
.Ft int
.Fn pmc_attach "pmc_id_t pmcid" "pid_t pid"
.Ft int
.Fn pmc_detach "pmc_id_t pmcid" "pid_t pid"
.Sh DESCRIPTION
These functions control the set of target processes tracked by a
process scope PMC.
.Pp
Function
.Fn pmc_attach
is used to attach a process scope PMC specified by argument
.Fa pmcid
to a target process specified by argument
.Fa pid .
Argument
.Fa pid
may be zero to denote the current process.
If the PMC was allocated with modifier
.Dv PMC_F_DESCENDANTS ,
the PMC will additionally attach to current and future descendents of
the specified target process.
The PMC should be in a quiescent state (i.e., not running).
.Pp
Function
.Fn pmc_detach
is used to detach a process scope PMC specified by argument
.Fa pmcid
from a process specified by argument
.Fa pid .
Argument
.Fa pid
may be zero to denote the current process.
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
A call to function
.Fn pmc_attach
may fail with the following errors:
.Bl -tag -width Er
.It Bq Er EBUSY
Argument
.Fa pmcid
specified a PMC that was not in a quiescent state.
.It Bq Er EBUSY
The target process specified by function
.Fa pmc_attach
is being tracked by another process scope PMC that uses the same PMC
hardware resources.
.It Bq Er EEXIST
The target process is already being tracked by the specified PMC.
.It Bq Er EINVAL
Argument
.Fa pmcid
specified a PMC with system scope.
.It Bq Er EINVAL
Argument
.Fa pid
specified an illegal process id.
.It Bq Er EINVAL
The current process does not own a PMC with the handle specified in
argument
.Fa pmcid .
.It Bq Er EPERM
The caller lacked the privilege needed to attach PMCs to
the specified target process.
.It Bq Er EPERM
(i386 and amd64 architectures) The PMC specified by argument
.Fa pmcid
has been setup to allow the use of the RDPMC instruction for
self measurement.
.It Bq Er ESRCH
The current process does not own any PMCs.
.It Bq Er ESRCH
The process specified by argument
.Fa pid
did not exist.
.El
.Pp
A call to function
.Fn pmc_detach
may fail with the following errors:
.Bl -tag -width Er
.It Bq Er EINVAL
Argument
.Fa pmcid
specified a PMC with system scope.
.It Bq Er EINVAL
Argument
.Fa pid
specified an illegal process id.
.It Bq Er EINVAL
The current process does not own a PMC with the handle specified in
argument
.Fa pmcid .
.It Bq Er EINVAL
The specified PMC was not attached to the target process.
.It Bq Er ESRCH
The current process does not own any PMCs.
.It Bq Er ESRCH
The process specified by argument
.Fa pid
is not being monitored by
.Xr hwpmc 4 .
.It Bq Er ESRCH
The process specified by argument
.Fa pid
did not exist.
.El
.Sh SEE ALSO
.Xr pmc 3 ,
.Xr pmc_start 3 ,
.Xr pmc_stop 3 ,
.Xr hwpmc 4
Reference in New Issue Copy Permalink