171861610b
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. Sponsored by <The NetBSD Foundation>
152 lines
4.5 KiB
Groff
152 lines
4.5 KiB
Groff
.\" $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.
|