.\"	$NetBSD: pthread_dbg.3,v 1.1 2017/02/08 01:02:19 kamil Exp $
.\"
.\"
.\" Copyright (c) 2016 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd November 21, 2016
.Dt PTHREAD_DBG 3
.Os
.Sh NAME
.Nm pthread_dbg
.Nd POSIX Debug Threads Library
.Sh LIBRARY
.Lb libpthread_dbg
.Sh SYNOPSIS
.In pthread_dbg.h
.Pp
.Nm cc
.Op Ar flags
.Ar files
.Fl lpthread_dbg
.Op Ar libraries
.Sh DESCRIPTION
The
.Nm
library provides an implementation of the standard
.Tn POSIX
threads library debugging facilities.
.Pp
The
.Nx
implementation is based on 1:1 thread model, therefore each
.Xr pthread 3
has a kernel thread, called a light-weight process (LWP).
.Pp
Note that the system private thread interfaces upon which the
.Xr pthread 3
library is built are subject to change without notice.
In order to remain compatible with future
.Nx
releases, programs must be linked against the dynamic version of the
thread library.
Statically linked programs using the
.Tn POSIX
threads framework may not work when run on a future version of the system.
.Pp
The
.Nm
library is designed to be used in debuggers and to control and introspect the
.Nx
implementation of the
.Tn POSIX
threads.
Software may use native
.Tn LWP
threads without
.Xr pthread 3
layer,
in that case
.Nm
cannot be used.
.Ss Error codes
The following error codes are defined in
.Nm
functions:
.Pp
.Bl -column ".Sy TD_ERR_BADTHREAD" "Request is not meaningful for that thread" -compact
.\".It Sy "Symbol" Ta Sy "Descriptive name"
.It Dv TD_ERR_OK Ta "Success"
.It Dv TD_ERR_ERR Ta "Generic error"
.It Dv TD_ERR_NOSYM Ta "Symbol not found (proc_lookup)"
.It Dv TD_ERR_NOOBJ Ta "No object matched the request"
.It Dv TD_ERR_BADTHREAD Ta "Request is not meaningful for that thread"
.It Dv TD_ERR_INUSE Ta "The process is already being debugged"
.It Dv TD_ERR_NOLIB Ta "The process is not using libpthread"
.It Dv TD_ERR_NOMEM Ta "Memory allocation failed"
.It Dv TD_ERR_IO Ta "A callback failed to read or write"
.It Dv TD_ERR_INVAL Ta "Invalid parameter"
.El
.Sh FUNCTIONS
The following functions comprise the core of the
.Nm
library:
.Bl -column -offset indent "td_thr_getname(3)" "convert the pthread_t to a thread handle"
.It Sy Function Ta Sy Description
.It Xr td_close 3       Ta close connection to a threaded process
.It Xr td_map_pth2thr 3 Ta convert a pthread_t to a thread handle
.It Xr td_open 3        Ta make connection to a threaded process
.It Xr td_thr_getname 3 Ta get the user-assigned name of a thread
.It Xr td_thr_info 3    Ta get information on a thread
.It Xr td_thr_iter 3    Ta iterate over the threads in the process
.El
.Sh SEE ALSO
.Xr pthread 3
.Sh STANDARDS
The
.Nm
library is a
.Nx
extension.
.Sh HISTORY
The
.Nm
library first appeared in
.Nx 2.0
along with the Scheduler Activation thread interface.
This interface was authored by
.An Nathan J. Williams
and merged by
.An Jason R. Thorpe .
In
.Nx 5.0
the
.Nm
library was moved to the new 1:1 thread model.
.Pp
This library was detached from the base distribution in
.Nx 8.0
and moved to pkgsrc.
.Sh AUTHORS
.An -nosplit
.An Nathan J. Williams Aq Mt nathanw@NetBSD.org
.Pp
This manual page was written by
.An Kamil Rytarowski Aq Mt kamil@NetBSD.org .
.Sh BUGS
It is not possible to debug the
.Nx
library with a debugger that is using
.Nm
internally.