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 *ptid;
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. The thread thread must be in suspended state to provide register information for threads.

Parameters

Table 1. Parameters
Item	Description
`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_TLS get the thread-local storage information. This value can be or'ed with any value of the mode parameter. The thread-local storage information is returned to the caller in a caller-provided buffer, `regbuf`. If the buffer is too small for the data, the buffer is filled up to the end of the buffer and ERANGE is returned. The caller also provides the size of the buffer, `regbufsize`, which on return is changed to the size of the thread local storage information even if it does not fit into a buffer. The thread-local storage information is returned in form of an array of touplets: memory address and TLS region (unique number assigned by the loader). The TLS region is also included in the loader info structure returned by `loadquery`. If you need any additional information such as TLS size, you can find it in that structure. `#typedef struct __pthrdstlsinfo{ void *pti_vaddr; int pti_region; } PTHRDS_TLS_INFO;` PTHRDSINFO_QUERY_EXTCTX get the extended machine context PTHRDSINFO_QUERY_ALL get everything (except for the extended context, which must be explicitly requested)
`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) If the `PTHRDSINFO_QUERY_EXTCTX` mode is requested, then the buf specifies the address of a `_pthrdsinfox` structure, which, in addition to all of the preceding information, also contains the following: __pi_ec The thread's extended context (extended register state)
`bufsize`	The size of the `__pthrdsinfo` or `__pthrdsinfox` structure in bytes.
`regbuf`	The location of the buffer to hold the register save data and to pass the TLS information 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 and pass the TLS information. 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:

Table 2. Error codes
Item	Description
`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.