Technical Reference: Base Operating System and Extensions, Volume 1

getthrds Subroutine

Purpose

Gets kernel thread table entries.

Library

Standard C library (libc.a)

Syntax

#include <procinfo.h>
#include <sys/types.h>

int
getthrds ( ProcessIdentifier, ThreadBuffer, ThreadSize, IndexPointer, Count)
pid_t ProcessIdentifier;
struct thrdsinfo *ThreadBuffer;
or struct thrdsinfo64 *ThreadBuffer;
int ThreadSize;
tid_t *IndexPointer;
int Count;

int
getthrds64 ( ProcessIdentifier, ThreadBuffer, ThreadSize, IndexPointer, Count)
pid_t ProcessIdentifier;
struct thrdentry64 *ThreadBuffer;
int ThreadSize;
tid64_t *IndexPointer;
int Count;

Description

The getthrds subroutine returns information about kernel threads, including kernel thread table information defined by the thrdsinfo or thrdsinfo64 structure.

The getthrds subroutine retrieves up to Count kernel thread table entries, starting with the entry corresponding to the thread identifier indicated by IndexPointer, and places them in the array of thrdsinfo or thrdsinfo64, or thrdentry64 structures indicated by the ThreadBuffer parameter.

On return, the kernel thread identifier referenced by IndexPointer is updated to indicate the next kernel thread table entry to be retrieved. The getthrds subroutine returns the number of kernel thread table entries retrieved.

If the ProcessIdentifier parameter indicates a process identifier, only kernel threads belonging to that process are considered. If this parameter is set to -1, all kernel threads are considered.

The getthrds subroutine is normally called repeatedly in a loop, starting with a kernel thread identifier of zero, and looping until the return value is less than Count, indicating that there are no more entries to retrieve.

1. Do not use information from the procsinfo structure (see the getprocs (getprocs Subroutine) subroutine) to determine the value of the Count parameter; a process may create or destroy kernel threads in the interval between a call to getprocs and a subsequent call to getthrds.
2. The kernel thread table may change while the getthrds subroutine is accessing it. Returned entries will always be consistent, but since kernel threads can be created or destroyed while the getthrds subroutine is running, there is no guarantee that retrieved entries will still exist, or that all existing kernel threads have been retrieved.

When used in 32-bit mode, limits larger than can be represented in 32 bits are truncated to RLIM_INFINITY. Large values are truncated to INT_MAX. 64-bit applications are required to use getthrds64() and struct thrdentry64. Note that struct thrdentry64 contains the same information as struct thrdsinfo64 with the only difference being support for the 64-bit tid_t and the 256-bit sigset_t. Application developers are also encouraged to use getthrds64() in 32-bit applications to obtain 64-bit thread information as this interface provides the new, larger types. The getthrds() interface will still be supported for 32-bit applications using struct thrdsinfo or struct thrdsinfo64, but will not be available to 64-bit applications.

Parameters

ProcessIdentifier

Specifies the process identifier of the process whose kernel threads are to be retrieved. If this parameter is set to -1, all kernel threads in the kernel thread table are retrieved.

ThreadBuffer

Specifies the starting address of an array of thrdsinfo or thrdsinfo64, or thrdentry64 structures which will be filled in with kernel thread table entries. If a value of NULL is passed for this parameter, the getthrds subroutine scans the kernel thread table and sets return values as normal, but no kernel thread table entries are retrieved.

ThreadSize

Specifies the size of a single thrdsinfo, thrdsinfo64, or thrdentry64 structure.

IndexPointer

Specifies the address of a kernel thread identifier which indicates the required kernel thread table entry (this does not have to correspond to an existing kernel thread). A kernel thread identifier of zero selects the first entry in the table. The kernel thread identifier is updated to indicate the next entry to be retrieved.

Count

Specifies the number of kernel thread table entries requested.

Return Value

If successful, the getthrds subroutine returns the number of kernel thread table entries retrieved; if this is less than the number requested, the end of the kernel thread table has been reached. Otherwise, a value of -1 is returned, and the errno global variable is set to indicate the error.

Error Codes

The getthrds subroutine fails if the following are true:

Implementation Specifics

This subroutine is part of the Base Operating System (BOS) Runtime.

Related Information

The getpid (getpid, getpgrp, or getppid Subroutine), getpgrp (getpid, getpgrp, or getppid Subroutine), or getppid (getpid, getpgrp, or getppid Subroutine) subroutines, the getprocs (getprocs Subroutine) subroutine.

The ps command.