usr/src/man/man3c_db/td_thr_get_info.3c_db

   1 '\" te
   2 .\"  All Rights Reserved  Copyright (c) 1998, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH TD_THR_GET_INFO 3C_DB "Oct 20, 1998"
   7 .SH NAME
   8 td_thr_get_info \- get thread information in libc_db library of interfaces
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 cc [ \fIflag\fR... ] \fIfile\fR... -lc_db [ \fIlibrary\fR... ]
  13 #include <proc_service.h>
  14 #include <thread_db.h>
  15
  16 \fBtd_err_e\fR \fBtd_thr_get_info\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBtd_thrinfo_t *\fR\fIti_p\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBtd_thr_get_info()\fR function fills in the \fBtd_thrinfo_t\fR structure
  23 *\fIti_p\fR with values for the thread identified by  \fIth_p\fR.
  24 .sp
  25 .LP
  26 The \fBtd_thrinfo_t\fR structure contains the following fields:
  27 .sp
  28 .in +2
  29 .nf
  30 typedef struct td_thrinfo_t {
  31   td_thragen_tx    *ti_ta_p           /* internal process handle */
  32   unsigned         ti_user_flags;     /* value of flags parameter */
  33   thread_t         ti_tid;            /* thread identifier */
  34   char             *ti_tls;           /* pointer to thread-local storage*/
  35   paddr            ti_startfunc;      /* address of function at which thread
  36                                          execution began*/
  37   paddr            ti_stkbase;        /* base of thread's stack area*/
  38   int              ti_stksize;        /* size in bytes of thread's allocated
  39                                          stack region*/
  40   paddr            ti_ro_area;        /* address of ulwp_t structure*/
  41   int              ti_ro_size         /* size of the ulwp_t structure in
  42                                          bytes */
  43   td_thr_state_e   ti_state           /* state of the thread */
  44   uchar_t          ti_db_suspended    /* non-zero if thread suspended by
  45                                          td_thr_dbsuspend*/
  46   td_thr_type_e    ti_type            /* type of the thread*/
  47   int              ti_pc              /* value of thread's program counter*/
  48   int              ti_sp              /* value of thread's stack counter*/
  49   short            ti_flags           /* set of special flags used by
  50                                          libc*/
  51   int              ti_pri             /* priority of thread returned by
  52                                          thr_getprio(3T)*/
  53   lwpid_t          ti_lid             /* id of light weight process (LWP)
  54                                          executing this thread*/
  55   sigset_t         ti_sigmask         /* thread's signal mask.  See
  56                                          thr_sigsetmask(3T)*/
  57   u_char           ti_traceme         /* non-zero if event tracing is on*/
  58   u_char_t         ti_preemptflag     /* non-zero if thread preempted when
  59                                          last active*/
  60   u_char_t         ti_pirecflag      /* non-zero if thread runs priority
  61                                         beside regular */
  62   sigset_t         ti_pending        /* set of signals pending for this
  63                                         thread*/
  64   td_thr_events_t  ti_events         /* bitmap of events enabled for this
  65                                         thread*/
  66 } ;
  67 .fi
  68 .in -2
  69
  70 .sp
  71 .LP
  72 The \fBti_ta_p\fR member is the internal process handle identifying the process
  73 of which the thread is a member.
  74 .sp
  75 .LP
  76 The \fBti_user_flags\fR member is the value of the flags parameter passed to
  77 \fBthr_create\fR(3C) when the thread was created.
  78 .sp
  79 .LP
  80 The \fBti_tid\fR member is the thread identifier for the thread returned by
  81 \fBthr_create\fR(3C).
  82 .sp
  83 .LP
  84 The \fBti_tls\fR member is the thread's pointer to thread-local storage.
  85 .sp
  86 .LP
  87 The \fBti_startfunc\fR member is the address of the function at which thread
  88 execution began, as specified when the thread was created with
  89 \fBthr_create\fR(3C).
  90 .sp
  91 .LP
  92 The \fBti_stkbase\fR member is the base of the thread's stack area.
  93 .sp
  94 .LP
  95 The \fBti_stksize\fR member is the size in bytes of the thread's allocated
  96 stack region.
  97 .sp
  98 .LP
  99 The \fBti_ro_area\fR member is the address of the \fBulwp_t\fR structure for
 100 this thread.  Since accessing the \fBulwp_t\fR structure directly violates the
 101 encapsulation provided by \fBlibc_db\fR, this member should generally not be
 102 used.  However, it might be useful as a prototype for extensions.
 103 .sp
 104 .LP
 105 The \fBti_state\fR member is the state of the thread.  The \fBtd_thr_state_e\fR
 106 enumeration type can contain the following values:
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBTD_THR_ANY_STATE\fR \fR
 111 .ad
 112 .RS 26n
 113 This value is never returned by \fBtd_thr_get_info()\fR but is used as a
 114 wildcard to select threads in \fBtd_ta_thr_iter()\fR.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBTD_THR_UNKNOWN\fR \fR
 121 .ad
 122 .RS 26n
 123 The \fBlibc_db\fR library cannot determine the state of the thread.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBTD_THR_STOPPED\fR \fR
 130 .ad
 131 .RS 26n
 132 The thread has been stopped by a call to  \fBthr_suspend\fR(3C).
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBTD_THR_RUN\fR \fR
 139 .ad
 140 .RS 26n
 141 The thread is runnable, but it is not currently assigned to an \fBLWP\fR.
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBTD_THR_ACTIVE\fR \fR
 148 .ad
 149 .RS 26n
 150 The thread is currently executing on an  \fBLWP\fR.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBTD_THR_ZOMBIE\fR \fR
 157 .ad
 158 .RS 26n
 159 The thread has exited, but it has not yet been deallocated by a call to
 160 \fBthr_join\fR(3C).
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBTD_THR_SLEEP\fR \fR
 167 .ad
 168 .RS 26n
 169 The thread is not currently runnable.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBTD_THR_STOPPED_ASLEEP\fR \fR
 176 .ad
 177 .RS 26n
 178 The thread is both blocked by  \fBTD_THR_SLEEP\fR and stopped by a call to
 179 \fBtd_thr_dbsuspend\fR(3C_DB).
 180 .RE
 181
 182 .sp
 183 .LP
 184 The \fBti_db_suspended\fR member is non-zero if and only if this thread is
 185 currently suspended because the controlling process has called
 186 \fBtd_thr_dbsuspend\fR on it.
 187 .sp
 188 .LP
 189 The \fBti_type\fR member is a type of thread.  It is either \fBTD_THR_USER\fR
 190 for a user thread (one created by the application), or \fBTD_THR_SYSTEM\fR for
 191 one created by \fBlibc\fR.
 192 .sp
 193 .LP
 194 The \fBti_pc\fR member is the value of the thread's program counter, provided
 195 that the thread's \fBti_state\fR value is \fBTD_THR_SLEEP\fR,
 196 \fBTD_THR_STOPPED\fR, or \fBTD_THR_STOPPED_ASLEEP\fR. Otherwise, the value of
 197 this member is undefined.
 198 .sp
 199 .LP
 200 The \fBti_sp\fR member is the value of the thread's stack pointer, provided
 201 that the thread's \fBti_state\fR value is \fBTD_THR_SLEEP\fR,
 202 \fBTD_THR_STOPPED\fR, or \fBTD_THR_STOPPED_ASLEEP\fR. Otherwise, the value of
 203 this member is undefined.
 204 .sp
 205 .LP
 206 The \fBti_flags\fR member is a set of special flags used by \fBlibc\fR,
 207 currently of use only to those debugging \fBlibc\fR.
 208 .sp
 209 .LP
 210 The \fBti_pri\fR member is the thread's priority as it would be returned by
 211 \fBthr_getprio\fR(3C).
 212 .sp
 213 .LP
 214 The \fBti_lid\fR member is the ID of the \fBLWP\fR executing this thread, or
 215 the ID of the  \fBLWP\fR that last executed this thread, if this thread is not
 216 currently assigned to an\fBLWP\fR.
 217 .sp
 218 .LP
 219 The \fBti_sigmask\fR member is this thread's signal mask. See
 220 \fBthr_sigsetmask\fR(3C).
 221 .sp
 222 .LP
 223 The \fBti_traceme\fR member is non-zero if and only if event tracing for this
 224 thread is on.
 225 .sp
 226 .LP
 227 The \fBti_preemptflag\fR member is non-zero if and only if the thread was
 228 preempted the last time it was active.
 229 .sp
 230 .LP
 231 The \fBti_pirecflag\fR member is non-zero if and only if due to priority
 232 inheritance the thread is currently running at a priority other than its
 233 regular priority.
 234 .sp
 235 .LP
 236 The \fBti_events\fR member is the bitmap of events enabled for this thread.
 237 .SH RETURN VALUES
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBTD_OK\fR\fR
 242 .ad
 243 .RS 12n
 244 The call completed successfully.
 245 .RE
 246
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBTD_BADTH\fR\fR
 251 .ad
 252 .RS 12n
 253 An invalid thread handle was passed in.
 254 .RE
 255
 256 .sp
 257 .ne 2
 258 .na
 259 \fB\fBTD_DBERR\fR\fR
 260 .ad
 261 .RS 12n
 262 A call to one of the imported interface routines failed.
 263 .RE
 264
 265 .sp
 266 .ne 2
 267 .na
 268 \fB\fBTD_ERR\fR\fR
 269 .ad
 270 .RS 12n
 271 The call did not complete successfully.
 272 .RE
 273
 274 .SH ATTRIBUTES
 275 .sp
 276 .LP
 277 See \fBattributes\fR(5) for description of the following attributes:
 278 .sp
 279
 280 .sp
 281 .TS
 282 box;
 283 c | c
 284 l | l .
 285 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 286 _
 287 MT-Level        Safe
 288 .TE
 289
 290 .SH SEE ALSO
 291 .sp
 292 .LP
 293 \fBlibc_db\fR(3LIB), \fBtd_ta_thr_iter\fR(3C_DB),
 294 \fBtd_thr_dbsuspend\fR(3C_DB), \fBthr_create\fR(3C), \fBthr_getprio\fR(3C),
 295 \fBthr_join\fR(3C), \fBthr_sigsetmask\fR(3C), \fBthr_suspend\fR(3C),
 296 \fBattributes\fR(5), \fBthreads\fR(5)