Sync usage with man page.
[netbsd-mini2440.git] / lib / libpthread_dbg / pthread_dbg.h
blob583379bbc6a24b6a8e9f30468e9cc47ba05f148d
1 /* $NetBSD: pthread_dbg.h,v 1.4 2004/06/02 21:13:43 nathanw Exp $ */
3 /*-
4 * Copyright (c) 2002 Wasabi Systems, Inc.
5 * All rights reserved.
7 * Written by Nathan J. Williams for Wasabi Systems, Inc.
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 * 2. Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in the
16 * documentation and/or other materials provided with the distribution.
17 * 3. All advertising materials mentioning features or use of this software
18 * must display the following acknowledgement:
19 * This product includes software developed for the NetBSD Project by
20 * Wasabi Systems, Inc.
21 * 4. The name of Wasabi Systems, Inc. may not be used to endorse
22 * or promote products derived from this software without specific
23 * prior written permission.
25 * THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
26 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC
29 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35 * POSSIBILITY OF SUCH DAMAGE.
38 #include <sys/types.h>
39 #include <signal.h>
41 struct td_proc_st;
42 struct td_thread_st;
43 struct td_sync_st;
45 typedef struct td_proc_st td_proc_t;
46 typedef struct td_thread_st td_thread_t;
47 typedef struct td_sync_st td_sync_t;
49 struct td_proc_callbacks_t {
50 int (*proc_read)(void *arg, caddr_t addr, void *buf, size_t size);
51 int (*proc_write)(void *arg, caddr_t addr, void *buf, size_t size);
52 int (*proc_lookup)(void *arg, char *sym, caddr_t *addr);
53 int (*proc_regsize)(void *arg, int regset, size_t *size);
54 int (*proc_getregs)(void *arg, int regset, int lwp, void *buf);
55 int (*proc_setregs)(void *arg, int regset, int lwp, void *buf);
59 typedef struct td_thread_info_st {
60 caddr_t thread_addr; /* Address of data structure */
61 int thread_state; /* TD_STATE_*; see below */
62 int thread_type; /* TD_TYPE_*; see below */
63 int thread_id;
64 stack_t thread_stack;
65 int thread_hasjoiners; /* 1 if threads are waiting */
66 caddr_t thread_tls;
67 int thread_errno;
68 sigset_t thread_sigmask;
69 sigset_t thread_sigpending;
70 long pad[32];
71 } td_thread_info_t;
73 #define TD_STATE_UNKNOWN 0
74 #define TD_STATE_RUNNING 1 /* On a processor */
75 #define TD_STATE_RUNNABLE 2 /* On a run queue */
76 #define TD_STATE_BLOCKED 3 /* Blocked in the kernel */
77 #define TD_STATE_SLEEPING 4 /* Blocked on a sync object */
78 #define TD_STATE_ZOMBIE 5
79 #define TD_STATE_SUSPENDED 6 /* Removed from run queues */
81 #define TD_TYPE_UNKNOWN 0
82 #define TD_TYPE_USER 1
83 #define TD_TYPE_SYSTEM 2
85 typedef struct {
86 caddr_t sync_addr; /* Address within the process */
87 int sync_type; /* TD_SYNC_*; see below */
88 size_t sync_size;
89 int sync_haswaiters; /* 1 if threads are known to be waiting */
90 union {
91 struct {
92 int locked;
93 td_thread_t *owner;
94 } mutex;
95 struct {
96 int locked;
97 } spin;
98 struct {
99 td_thread_t *thread;
100 } join;
101 struct {
102 int locked;
103 int readlocks;
104 td_thread_t *writeowner;
105 } rwlock;
106 long pad[8];
107 } sync_data;
108 } td_sync_info_t;
110 #define TD_SYNC_UNKNOWN 0
111 #define TD_SYNC_MUTEX 1 /* pthread_mutex_t */
112 #define TD_SYNC_COND 2 /* pthread_cond_t */
113 #define TD_SYNC_SPIN 3 /* pthread_spinlock_t */
114 #define TD_SYNC_JOIN 4 /* thread being joined */
115 #define TD_SYNC_RWLOCK 5 /* pthread_rwlock_t */
117 /* Error return codes */
118 #define TD_ERR_OK 0
119 #define TD_ERR_ERR 1 /* Generic error */
120 #define TD_ERR_NOSYM 2 /* Symbol not found (proc_lookup) */
121 #define TD_ERR_NOOBJ 3 /* No object matched the request */
122 #define TD_ERR_BADTHREAD 4 /* Request is not meaningful for that thread */
123 #define TD_ERR_INUSE 5 /* The process is already being debugged */
124 #define TD_ERR_NOLIB 6 /* The process is not using libpthread */
125 #define TD_ERR_NOMEM 7 /* malloc() failed */
126 #define TD_ERR_IO 8 /* A callback failed to read or write */
127 #define TD_ERR_INVAL 9 /* Invalid parameter */
129 /* Make a connection to a threaded process */
130 int td_open(struct td_proc_callbacks_t *, void *arg, td_proc_t **);
131 int td_close(td_proc_t *);
133 /* Iterate over the threads in the process */
134 int td_thr_iter(td_proc_t *, int (*)(td_thread_t *, void *), void *);
136 /* Get information on a thread */
137 int td_thr_info(td_thread_t *, td_thread_info_t *);
139 /* Get the user-assigned name of a thread */
140 int td_thr_getname(td_thread_t *, char *, int);
142 /* Get register state of a thread */
143 int td_thr_getregs(td_thread_t *, int, void *);
145 /* Set register state of a thread */
146 int td_thr_setregs(td_thread_t *, int, void *);
148 /* Iterate over the set of threads that are joining with the given thread */
149 int td_thr_join_iter(td_thread_t *, int (*)(td_thread_t *, void *), void *);
151 /* Get the synchronization object that the thread is sleeping on */
152 int td_thr_sleepinfo(td_thread_t *, td_sync_t **);
154 /* Get information on a synchronization object */
155 int td_sync_info(td_sync_t *, td_sync_info_t *);
157 /* Iterate over the set of threads waiting on a synchronization object */
158 int td_sync_waiters_iter(td_sync_t *, int (*)(td_thread_t *, void *), void *);
160 /* Convert the process address to a synchronization handle, if possible */
161 int td_map_addr2sync(td_proc_t *, caddr_t addr, td_sync_t **);
163 /* Convert the pthread_t to a thread handle, if possible */
164 int td_map_pth2thr(td_proc_t *, pthread_t, td_thread_t **);
166 /* Convert the thread ID to a thread handle, if possible */
167 int td_map_id2thr(td_proc_t *, int, td_thread_t **);
169 /* Return the thread handle of the thread running on the given LWP */
170 int td_map_lwp2thr(td_proc_t *, int, td_thread_t **);
173 * Establish a mapping between threads and LWPs. Must be called
174 * every time a live process runs before calling td_thr_getregs() or
175 * td_thr_setregs().
177 int td_map_lwps(td_proc_t *);
179 /* Iterate over the set of TSD keys in the process */
180 int td_tsd_iter(td_proc_t *, int (*)(pthread_key_t, void (*)(void *), void *),
181 void *);
183 /* Get a TSD value from a thread */
184 int td_thr_tsd(td_thread_t *, pthread_key_t, void **);
186 /* Suspend a thread from running */
187 int td_thr_suspend(td_thread_t *);
189 /* Restore a suspended thread to its previous state */
190 int td_thr_resume(td_thread_t *);