Source-Changes-HG archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

[src/trunk]: src Add initial documentation (man-pages) for libpthread_dbg



details:   https://anonhg.NetBSD.org/src/rev/145afffee981
branches:  trunk
changeset: 349053:145afffee981
user:      kamil <kamil%NetBSD.org@localhost>
date:      Mon Nov 21 20:43:25 2016 +0000

description:
Add initial documentation (man-pages) for libpthread_dbg

Document libpthread_dbg and basic function calls: td_open() and td_close()

Sponsored by <The NetBSD Foundation>

diffstat:

 distrib/sets/lists/comp/mi                   |   11 +-
 external/bsd/mdocml/dist/lib.in              |    1 +
 external/gpl2/groff/dist/tmac/doc-syms       |   69 ++++++------
 external/gpl2/groff/dist/tmac/groff_mdoc.man |    2 +
 lib/libpthread_dbg/Makefile                  |    7 +-
 lib/libpthread_dbg/pthread_dbg.3             |  145 +++++++++++++++++++++++++++
 lib/libpthread_dbg/td_open.3                 |   79 ++++++++++++++
 7 files changed, 278 insertions(+), 36 deletions(-)

diffs (truncated from 415 to 300 lines):

diff -r b9d51f2936e2 -r 145afffee981 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Mon Nov 21 20:16:21 2016 +0000
+++ b/distrib/sets/lists/comp/mi        Mon Nov 21 20:43:25 2016 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.2069 2016/11/20 13:26:28 pho Exp $
+#      $NetBSD: mi,v 1.2070 2016/11/21 20:43:25 kamil Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 ./etc/mtree/set.comp                           comp-sys-root
@@ -8443,6 +8443,7 @@
 ./usr/share/man/cat3/pthread_condattr_setpshared.0     comp-c-catman   .cat
 ./usr/share/man/cat3/pthread_create.0          comp-c-catman           .cat
 ./usr/share/man/cat3/pthread_curcpu_np.0       comp-c-catman           .cat
+./usr/share/man/cat3/pthread_dbg.0             comp-c-catman           .cat
 ./usr/share/man/cat3/pthread_detach.0          comp-c-catman           .cat
 ./usr/share/man/cat3/pthread_equal.0           comp-c-catman           .cat
 ./usr/share/man/cat3/pthread_exit.0            comp-c-catman           .cat
@@ -9361,6 +9362,8 @@
 ./usr/share/man/cat3/tcsendbreak.0             comp-c-catman           .cat
 ./usr/share/man/cat3/tcsetattr.0               comp-c-catman           .cat
 ./usr/share/man/cat3/tcsetpgrp.0               comp-c-catman           .cat
+./usr/share/man/cat3/td_close.0                        comp-c-catman           .cat
+./usr/share/man/cat3/td_open.0                 comp-c-catman           .cat
 ./usr/share/man/cat3/tdelete.0                 comp-c-catman           .cat
 ./usr/share/man/cat3/telldir.0                 comp-c-catman           .cat
 ./usr/share/man/cat3/tempnam.0                 comp-c-catman           .cat
@@ -15734,6 +15737,7 @@
 ./usr/share/man/html3/pthread_condattr_setpshared.html comp-c-htmlman  html
 ./usr/share/man/html3/pthread_create.html      comp-c-htmlman          html
 ./usr/share/man/html3/pthread_curcpu_np.html   comp-c-htmlman          html
+./usr/share/man/html3/pthread_dbg.html         comp-c-htmlman          html
 ./usr/share/man/html3/pthread_detach.html      comp-c-htmlman          html
 ./usr/share/man/html3/pthread_equal.html       comp-c-htmlman          html
 ./usr/share/man/html3/pthread_exit.html                comp-c-htmlman          html
@@ -16616,6 +16620,8 @@
 ./usr/share/man/html3/tcsendbreak.html         comp-c-htmlman          html
 ./usr/share/man/html3/tcsetattr.html           comp-c-htmlman          html
 ./usr/share/man/html3/tcsetpgrp.html           comp-c-htmlman          html
+./usr/share/man/html3/td_close.html            comp-c-htmlman          html
+./usr/share/man/html3/td_open.html             comp-c-htmlman          html
 ./usr/share/man/html3/tdelete.html             comp-c-htmlman          html
 ./usr/share/man/html3/telldir.html             comp-c-htmlman          html
 ./usr/share/man/html3/tempnam.html             comp-c-htmlman          html
@@ -23018,6 +23024,7 @@
 ./usr/share/man/man3/pthread_condattr_setpshared.3     comp-c-man      .man
 ./usr/share/man/man3/pthread_create.3          comp-c-man              .man
 ./usr/share/man/man3/pthread_curcpu_np.3       comp-c-man              .man
+./usr/share/man/man3/pthread_dbg.3             comp-c-man              .man
 ./usr/share/man/man3/pthread_detach.3          comp-c-man              .man
 ./usr/share/man/man3/pthread_equal.3           comp-c-man              .man
 ./usr/share/man/man3/pthread_exit.3            comp-c-man              .man
@@ -23932,6 +23939,8 @@
 ./usr/share/man/man3/tcsendbreak.3             comp-c-man              .man
 ./usr/share/man/man3/tcsetattr.3               comp-c-man              .man
 ./usr/share/man/man3/tcsetpgrp.3               comp-c-man              .man
+./usr/share/man/man3/td_close.3                        comp-c-man              .man
+./usr/share/man/man3/td_open.3                 comp-c-man              .man
 ./usr/share/man/man3/tdelete.3                 comp-c-man              .man
 ./usr/share/man/man3/telldir.3                 comp-c-man              .man
 ./usr/share/man/man3/tempnam.3                 comp-c-man              .man
diff -r b9d51f2936e2 -r 145afffee981 external/bsd/mdocml/dist/lib.in
--- a/external/bsd/mdocml/dist/lib.in   Mon Nov 21 20:16:21 2016 +0000
+++ b/external/bsd/mdocml/dist/lib.in   Mon Nov 21 20:43:25 2016 +0000
@@ -94,6 +94,7 @@
 LINE("libproc",                "Process Manipulation Library (libproc, \\-lproc)")
 LINE("libprop",                "Property Container Object Library (libprop, \\-lprop)")
 LINE("libpthread",     "POSIX Threads Library (libpthread, \\-lpthread)")
+LINE("libpthread_dbg", "POSIX Debug Threads Library (libpthread_dbg, \\-lpthread_dbg)")
 LINE("libpuffs",       "puffs Convenience Library (libpuffs, \\-lpuffs)")
 LINE("libquota",       "Disk Quota Access and Control Library (libquota, \\-lquota)")
 LINE("libradius",      "RADIUS Client Library (libradius, \\-lradius)")
diff -r b9d51f2936e2 -r 145afffee981 external/gpl2/groff/dist/tmac/doc-syms
--- a/external/gpl2/groff/dist/tmac/doc-syms    Mon Nov 21 20:16:21 2016 +0000
+++ b/external/gpl2/groff/dist/tmac/doc-syms    Mon Nov 21 20:43:25 2016 +0000
@@ -680,40 +680,41 @@
 .\" NS
 .\" NS width register `Lb' defined in doc-common
 .
-.ds doc-str-Lb-libarm      ARM Architecture Library (libarm, \-larm)
-.ds doc-str-Lb-libarm32    ARM32 Architecture Library (libarm32, \-larm32)
-.ds doc-str-Lb-libc        Standard C\~Library (libc, \-lc)
-.ds doc-str-Lb-libcdk      Curses Development Kit Library (libcdk, \-lcdk)
-.ds doc-str-Lb-libcompat   Compatibility Library (libcompat, \-lcompat)
-.ds doc-str-Lb-libcrypt    Crypt Library (libcrypt, \-lcrypt)
-.ds doc-str-Lb-libcurses   Curses Library (libcurses, \-lcurses)
-.ds doc-str-Lb-libedit     Command Line Editor Library (libedit, \-ledit)
-.ds doc-str-Lb-libelf      ELF Object Manipulation Library (libelf, \-lelf)
-.ds doc-str-Lb-libevent    Event Notification Library (libevent, \-levent)
-.ds doc-str-Lb-libform     Curses Form Library (libform, \-lform)
-.ds doc-str-Lb-libi386     i386 Architecture Library (libi386, \-li386)
-.ds doc-str-Lb-libintl     Internationalized Message Handling Library (libintl, \-lintl)
-.ds doc-str-Lb-libipsec    IPsec Policy Control Library (libipsec, \-lipsec)
-.ds doc-str-Lb-libkvm      Kernel Data Access Library (libkvm, \-lkvm)
-.ds doc-str-Lb-libm        Math Library (libm, \-lm)
-.ds doc-str-Lb-libm68k     m68k Architecture Library (libm68k, \-lm68k)
-.ds doc-str-Lb-libmagic    Magic Number Recognition Library (libmagic, \-lmagic)
-.ds doc-str-Lb-libmenu     Curses Menu Library (libmenu, \-lmenu)
-.ds doc-str-Lb-libossaudio OSS Audio Emulation Library (libossaudio, \-lossaudio)
-.ds doc-str-Lb-libpam      Pluggable Authentication Module Library (libpam, \-lpam)
-.ds doc-str-Lb-libpanel    Z-order for curses windows (libpanel, \-lpanel)
-.ds doc-str-Lb-libpcap     Packet Capture Library (libpcap, \-lpcap)
-.ds doc-str-Lb-libpci      PCI Bus Access Library (libpci, \-lpci)
-.ds doc-str-Lb-libpmc      Performance Counters Library (libpmc, \-lpmc)
-.ds doc-str-Lb-libposix    \*[Px] \*[doc-str-Lb]Compatibility Library (libposix, \-lposix)
-.ds doc-str-Lb-libpthread  \*[Px] \*[doc-str-Lb]Threads Library (libpthread, \-lpthread)
-.ds doc-str-Lb-libresolv   DNS Resolver Library (libresolv, \-lresolv)
-.ds doc-str-Lb-librt       \*[Px] \*[doc-str-Lb]Real-time Library (librt, \-lrt)
-.ds doc-str-Lb-libtermcap  Termcap Access Library (libtermcap, \-ltermcap)
-.ds doc-str-Lb-libusbhid   USB Human Interface Devices Library (libusbhid, \-lusbhid)
-.ds doc-str-Lb-libutil     System Utilities Library (libutil, \-lutil)
-.ds doc-str-Lb-libx86_64   x86_64 Architecture Library (libx86_64, \-lx86_64)
-.ds doc-str-Lb-libz        Compression Library (libz, \-lz)
+.ds doc-str-Lb-libarm         ARM Architecture Library (libarm, \-larm)
+.ds doc-str-Lb-libarm32       ARM32 Architecture Library (libarm32, \-larm32)
+.ds doc-str-Lb-libc           Standard C\~Library (libc, \-lc)
+.ds doc-str-Lb-libcdk         Curses Development Kit Library (libcdk, \-lcdk)
+.ds doc-str-Lb-libcompat      Compatibility Library (libcompat, \-lcompat)
+.ds doc-str-Lb-libcrypt       Crypt Library (libcrypt, \-lcrypt)
+.ds doc-str-Lb-libcurses      Curses Library (libcurses, \-lcurses)
+.ds doc-str-Lb-libedit        Command Line Editor Library (libedit, \-ledit)
+.ds doc-str-Lb-libelf         ELF Object Manipulation Library (libelf, \-lelf)
+.ds doc-str-Lb-libevent       Event Notification Library (libevent, \-levent)
+.ds doc-str-Lb-libform        Curses Form Library (libform, \-lform)
+.ds doc-str-Lb-libi386        i386 Architecture Library (libi386, \-li386)
+.ds doc-str-Lb-libintl        Internationalized Message Handling Library (libintl, \-lintl)
+.ds doc-str-Lb-libipsec       IPsec Policy Control Library (libipsec, \-lipsec)
+.ds doc-str-Lb-libkvm         Kernel Data Access Library (libkvm, \-lkvm)
+.ds doc-str-Lb-libm           Math Library (libm, \-lm)
+.ds doc-str-Lb-libm68k        m68k Architecture Library (libm68k, \-lm68k)
+.ds doc-str-Lb-libmagic       Magic Number Recognition Library (libmagic, \-lmagic)
+.ds doc-str-Lb-libmenu        Curses Menu Library (libmenu, \-lmenu)
+.ds doc-str-Lb-libossaudio    OSS Audio Emulation Library (libossaudio, \-lossaudio)
+.ds doc-str-Lb-libpam         Pluggable Authentication Module Library (libpam, \-lpam)
+.ds doc-str-Lb-libpanel       Z-order for curses windows (libpanel, \-lpanel)
+.ds doc-str-Lb-libpcap        Packet Capture Library (libpcap, \-lpcap)
+.ds doc-str-Lb-libpci         PCI Bus Access Library (libpci, \-lpci)
+.ds doc-str-Lb-libpmc         Performance Counters Library (libpmc, \-lpmc)
+.ds doc-str-Lb-libposix       \*[Px] \*[doc-str-Lb]Compatibility Library (libposix, \-lposix)
+.ds doc-str-Lb-libpthread     \*[Px] \*[doc-str-Lb]Threads Library (libpthread, \-lpthread)
+.ds doc-str-Lb-libpthread_dbg \*[Px] \*[doc-str-Lb]Threads Debug Library (libpthread_dbg, \-lpthread_dbg)
+.ds doc-str-Lb-libresolv      DNS Resolver Library (libresolv, \-lresolv)
+.ds doc-str-Lb-librt          \*[Px] \*[doc-str-Lb]Real-time Library (librt, \-lrt)
+.ds doc-str-Lb-libtermcap     Termcap Access Library (libtermcap, \-ltermcap)
+.ds doc-str-Lb-libusbhid      USB Human Interface Devices Library (libusbhid, \-lusbhid)
+.ds doc-str-Lb-libutil        System Utilities Library (libutil, \-lutil)
+.ds doc-str-Lb-libx86_64      x86_64 Architecture Library (libx86_64, \-lx86_64)
+.ds doc-str-Lb-libz           Compression Library (libz, \-lz)
 .
 .de Lb
 .  if !\n[doc-arg-limit] \{\
diff -r b9d51f2936e2 -r 145afffee981 external/gpl2/groff/dist/tmac/groff_mdoc.man
--- a/external/gpl2/groff/dist/tmac/groff_mdoc.man      Mon Nov 21 20:16:21 2016 +0000
+++ b/external/gpl2/groff/dist/tmac/groff_mdoc.man      Mon Nov 21 20:43:25 2016 +0000
@@ -1718,6 +1718,8 @@
 .Lb libposix
 .It Li libpthread
 .Lb libpthread
+.It Li libpthread_dbg
+.Lb libpthread_dbg
 .It Li libresolv
 .Lb libresolv
 .It Li librt
diff -r b9d51f2936e2 -r 145afffee981 lib/libpthread_dbg/Makefile
--- a/lib/libpthread_dbg/Makefile       Mon Nov 21 20:16:21 2016 +0000
+++ b/lib/libpthread_dbg/Makefile       Mon Nov 21 20:43:25 2016 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.11 2014/03/04 14:58:14 joerg Exp $
+#      $NetBSD: Makefile,v 1.12 2016/11/21 20:43:25 kamil Exp $
 #
 
 WARNS?=                5
@@ -40,6 +40,11 @@
 INCS=  pthread_dbg.h
 INCSDIR=/usr/include
 
+MAN+=  pthread_dbg.3
+MAN+=  td_open.3
+
+MLINKS+=       td_open.3 td_close.3
+
 .include <bsd.lib.mk>
 
 .else
diff -r b9d51f2936e2 -r 145afffee981 lib/libpthread_dbg/pthread_dbg.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libpthread_dbg/pthread_dbg.3  Mon Nov 21 20:43:25 2016 +0000
@@ -0,0 +1,145 @@
+.\"    $NetBSD: pthread_dbg.3,v 1.1 2016/11/21 20:43:25 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
+.Nx
+implementation of the
+.Tn POSIX
+threads.
+Software may use native
+.Tn LWP
+threads without
+.Xr libpthread 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_info(3)" "XXX"
+.It Sy Function Ta Sy Description
+.It Xr td_close 3 Ta close connection to a threaded process
+.It Xr td_open 3 Ta make connection to a threaded process
+.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



Home | Main Index | Thread Index | Old Index