[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

pthread_getthrds_np Subroutine

Purpose

Retrieves register and stack information for threads.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

int pthread_getthrds_np (thread, mode, buf, bufsize, regbuf, regbufsize)
pthread_t *thread;
int mode;
struct __pthrdsinfo *buf;
int bufsize;
void *regbuf;
int *regbufsize;

Description

The pthread_getthrds_np subroutine retrieves information on the state of the thread thread and its underlying kernel thread, including register and stack information.

Parameters

thread The pointer to the thread. On input it identifies the target thread of the operation, or 0 to operate on the first entry in the list of threads. On output it identifies the next entry in the list of threads, or 0 if the end of the list has been reached. pthread_getthrds_np can be used to traverse the whole list of threads by starting with thread pointing to 0 and calling pthread_getthrds_np repeatedly until it returns with thread pointing to 0.
mode Specifies the type of query. These values can be bitwise or'ed together to specify more than one type of query.
PTHRDSINFO_QUERY_GPRS
get general purpose registers
PTHRDSINFO_QUERY_SPRS
get special purpose registers
PTHRDSINFO_QUERY_FPRS
get floating point registers
PTHRDSINFO_QUERY_REGS
get all of the above registers
PTHRDSINFO_QUERY_TID
get the kernel thread id
PTHRDSINFO_QUERY_ALL
get everything
buf Specifies the address of the struct __pthrdsinfo structure that will be filled in by pthread_getthrds_np. On return, this structure holds the following data (depending on the type of query requested):
__pi_ptid
The thread's thread identifier
__pi_tid
The thread's kernel thread id, or 0 if the thread does not have a kernel thread
__pi_state
The state of the thread, equal to one of the following:
PTHRDSINFO_STATE_RUN
The thread is running
PTHRDSINFO_STATE_READY
The thread is ready to run
PTHRDSINFO_STATE_IDLE
The thread is being initialized
PTHRDSINFO_STATE_SLEEP
The thread is sleeping
PTHRDSINFO_STATE_TERM
The thread is terminated
PTHRDSINFO_STATE_NOTSUP
Error condition
__pi_suspended
1 if the thread is suspended, 0 if it is not
__pi_returned
The return status of the thread
__pi_ustk
The thread's user stack pointer
__pi_context
The thread's context (register information)
bufsize The size of the __pthrdsinfo structure in bytes.
regbuf The location of the buffer to hold the register save data from the kernel if the thread is in a system call.
regbufsize The pointer to the size of the regbuf buffer. On input, it identifies the maximum size of the buffer in bytes. On output, it identifies the number of bytes of register save data. If the thread is not in a system call, there is no register save data returned from the kernel, and regbufsize is 0. If the size of the register save data is larger than the input value of regbufsize, the number of bytes specified by the input value of regbufsize is copied to regbuf, pthread_getthrds_np() returns ERANGE, and the output value of regbufsize specifies the number of bytes required to hold all of the register save data.

Return Values

If successful, the pthread_getthrds_np function returns zero. Otherwise, an error number is returned to indicate the error.

Error Codes

The pthread_getthrds_np function will fail if:

EINVAL Either thread or buf is NULL, or bufsize is not equal to the size of the __pthrdsinfo structure in the library.
ESRCH No thread could be found corresponding to that specified by the thread ID thread.
ERANGE regbuf was not large enough to handle all of the register save data.
ENOMEM Insufficient memory exists to perform this operation.

Related Information

The pthread.h file.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]