Technical Reference: Base Operating System and Extensions, Volume 1

pthread_getrusage_np Subroutine

Purpose

Enable or disable pthread library resource collection, and retrieve resource information for any pthread in the current process.

Syntax

#include <pthread.h>
 
int pthread_getrusage_np ( pthread_t Ptid, struct rusage *RUsage, int Mode )
pthread_t Ptid;
struct rusage *RUsage;
int Mode;

The pthread_getrusage_np enables and disables resource collection in the pthread library and collects resource information for any pthread in the current process. When compiled in 64-bit mode, resource usage (rusage) counters are 64-bits for the calling thread. When compiled in 32-bit mode, rusage counters are 32-bits for the calling pthread.

The enable and disable rusage mechanism in the pthread library can also be triggered by an environment variable named AIXTHREAD_ENRUSG. Setting this variable to ON enables the functionality, while setting it to OFF disables it. The environment variable can be used along with the PTHRDSINFO_RUSAGE_START value passed to the pthread_getrusage_np subroutine Mode parameter. If the environment variable is not to be used, it should be set to NULL.

Parameters

Ptid Specifies the target thread. Must be within the current process.

RUsage

Points to a buffer described in the /usr/include/sys/resource.h file. The fields are define as follows:

ru_utime: The total amount of time running in user mode.
ru_stime: The total amount of time spent in the system executing on behalf of the processes.
ru_maxrss: The maximum size, in kilobytes, of the used resident set size.
ru_ixrss: An integral value indicating the amount of memory used by the text segment that was also shared among other processes. This value is expressed in units of kilobytes X seconds-of-execution and is calculated by adding the number of shared memory pages in use each time the internal system clock ticks, and then averaging over one-second intervals.
ru_idrss: An integral value of the amount of unshared memory in the data segment of a process, which is expressed in units of kilobytes X seconds-of-execution.
ru_minflt: The number of page faults serviced without any I/O activity. In this case, I/O activity is avoided by reclaiming a page frame from the list of pages awaiting reallocation.
ru_majflt: The number of page faults serviced that required I/O activity.
ru_nswap: The number of times that a process was swapped out of main memory.
ru_inblock: The number of times that the file system performed input.
ru_oublock: The number of times that the file system performed output.
Note: The numbers that the ru_inblock and ru_oublock fields display account for real I/O only; data supplied by the caching mechanism is charged only to the first process that reads or writes the data.
ru_msgsnd: The number of IPC messages sent.
ru_msgrcv: The number of IPC messages received.
ru_nsignals: The number of signals delivered.
ru_nvcsw: The number of times a context switch resulted because a process voluntarily gave up the processor before its time slice was completed. This usually occurs while the process waits for a resource to become available.
ru_nivcsw: The number of times a context switch resulted because a higher priority process ran or because the current process exceeded its time slice.

Mode

Indicates the task the routine should perform. Acceptable values are as follows:

PTHRDSINFO_RUSAGE_START: Enables resource collection in pthread library for all pthreads.
PTHRDSINFO_RUSAGE_STOP: Disables resource collection in pthread library for all pthreads.
PTHRDSINFO_RUSAGE_COLLECT: Collects resource information for the target thread.

Return Values

Upon successful completion, the pthread_getrusage_np subroutine returns a value of 0. Otherwise, an error number is returned to indicate the error.

Error Codes

The pthread_getrusage_np subroutine fails if:
ENOSYS	The calling pthread has given PTHRDSINFO_RUSAGE_COLLECT for Mode but the routine was not previously called with PTHRDSINFO_RUSAGE_START for Mode.
EINVAL	The address specified for RUsage is null or not valid or a null value for Ptid was given.
ESRCH	Either no thread could be found corresponding to the ID thread of the Ptid thread or the thread corresponding to the Ptid thread ID was not in the current process.

Related Information

The pthreads.h subroutine.