PTHREAD_DBG(3)

NAME
pthread_dbg - POSIX Debug Threads Library

LIBRARY
libpthread_dbg

SYNOPSIS
#include <pthread_dbg.h>

cc [flags] files -lpthread_dbg [libraries]

DESCRIPTION
The pthread_dbg library provides an implementation of the standard POSIX threads library debugging facilities.

The NetBSD implementation is based on 1:1 thread model, therefore each pthread(3) has a kernel thread, called a light-weight process (LWP).

Note that the system private thread interfaces upon which the pthread(3) library is built are subject to change without notice. In order to remain compatible with future NetBSD releases, programs must be linked against the dynamic version of the thread library. Statically linked programs using the POSIX threads framework may not work when run on a future version of the system.

The pthread_dbg library is designed to be used in debuggers and to control and introspect the NetBSD implementation of the POSIX threads. Software may use native LWP threads without pthread(3) layer, in that case pthread_dbg cannot be used.

  Error codes
The following error codes are defined in pthread_dbg functions:

TD_ERR_OK | Success
TD_ERR_ERR | Generic error
TD_ERR_NOSYM | Symbol not found (proc_lookup)
TD_ERR_NOOBJ | No object matched the request
TD_ERR_BADTHREAD | Request is not meaningful for that thread
TD_ERR_INUSE | The process is already being debugged
TD_ERR_NOLIB | The process is not using libpthread
TD_ERR_NOMEM | Memory allocation failed
TD_ERR_IO | A callback failed to read or write
TD_ERR_INVAL | Invalid parameter

FUNCTIONS
The following functions comprise the core of the pthread_dbg library:
Function | Description
td_close(3) | close connection to a threaded process
td_map_pth2thr(3) | convert a pthread_t to a thread handle
td_open(3) | make connection to a threaded process
td_thr_getname(3) | get the user-assigned name of a thread
td_thr_info(3) | get information on a thread
td_thr_iter(3) | iterate over the threads in the process

SEE ALSO
pthread(3)

STANDARDS
The pthread_dbg library is a NetBSD extension.

HISTORY
The pthread_dbg library first appeared in NetBSD 2.0 along with the Scheduler Activation thread interface. This interface was authored by Nathan J. Williams and merged by Jason R. Thorpe. In NetBSD 5.0 the pthread_dbg library was moved to the new 1:1 thread model.

This library was detached from the base distribution in NetBSD 8.0 and moved to pkgsrc.

AUTHORS
-nosplit Nathan J. Williams <nathanw@NetBSD.org>

This manual page was written by Kamil Rytarowski <kamil@NetBSD.org>.

BUGS
It is not possible to debug the NetBSD library with a debugger that is using pthread_dbg internally.