pm_set_program_group Subroutine

Purpose

Sets Performance Monitor programmation for a target thread and creates a counting group.

Library

Performance Monitor APIs Library (libpmapi.a)

Syntax

#include <pmapi.h>

int pm_set_program_group ( pid,  tid,  *prog)
pid_t pid;
tid_t tid;
pm_prog_t *prog;

Description

This subroutine supports only the 1:1 threading model. It has been superseded by the pm_set_program_pgroup subroutine, which supports both the 1:1 and the M:N threading models. A call to this subroutine is equivalent to a call to the pm_set_program_pgroup subroutine with a ptid parameter equal to 0.

The pm_set_program_group subroutine sets the Performance Monitor programmation for a target kernel thread. The thread must be stopped and must be part of a debuggee process, under the control of the calling process. The setting includes the events to be counted and a mode in which to count. The events to count are in a list of event identifiers. The identifiers must be selected from the lists returned by the pm_init subroutine.

This call also creates a counting group, which includes the target thread and any thread which it, or any of its descendants, will create in the future. Optionally, the group can be defined as also containing all the existing and future threads belonging to the target process.

The counting mode includes User Mode and/or Kernel Mode, and the Initial Counting State. The defaults are set to Off for User Mode and Kernel Mode, and the initial default state is set to delay counting until the pm_start_group subroutine is called.

If the list includes an event which can be used with a threshold (as indicated by the pm_init subroutine), a threshold value can also be specified.

Parameters

Item Description
pid Process ID of target thread. Target process must be a debuggee of a calling process.
tid Thread ID of target thread.
*prog
PM_USER
Counts processes running in User Mode (default is set to Off)
PM_KERNEL
Counts processes running in Kernel Mode (default is set to Off)
PM_COUNT
Starts counting immediately (default is set to Not to Start Counting)
PM_PROCESS
Creates a process-level counting group

Return Values

Item Description
0 Operation completed successfully.
Positive error code Refer to the pm_error Subroutine to decode the error code.

Error Codes

Refer to the pm_error Subroutine.

Files

Item Description
/usr/include/pmapi.h Defines standard macros, data types, and subroutines.