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

   1 '\" te
   2 .\"  All Rights Reserved  Copyright (c) 2001, 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_TA_SYNC_ITER 3C_DB "Jun 19, 2001"
   7 .SH NAME
   8 td_ta_sync_iter, td_ta_thr_iter, td_ta_tsd_iter \- iterator functions on
   9 process handles from libc_db
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR... ] \fIfile\fR... -lc_db [ \fIlibrary\fR... ]
  14 #include <proc_service.h>
  15 #include <thread_db.h>
  16
  17 \fBtypedef int\fR \fBtd_sync_iter_f\fR(\fBconst td_synchandle_t *\fR\fIsh_p\fR, \fBvoid *\fR\fIcbdata_p\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBtypedef int\fR \fBtd_thr_iter_f\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBvoid *\fR\fIcbdata_p\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBtypedef int\fR \fBtd_key_iter_f\fR(\fBthread_key_t\fR \fIkey\fR, \fBvoid (*\fR\fIdestructor\fR)(), \fBvoid *\fR\fIcbdata_p\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBtd_err_e\fR \fBtd_ta_sync_iter\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBtd_sync_iter_f *\fR\fIcb\fR,
  33      \fBvoid *\fR\fIcbdata_p\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBtd_err_e\fR \fBtd_ta_thr_iter\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBtd_thr_iter_f *\fR\fIcb\fR,
  39      \fBvoid *\fR\fIcbdata_p\fR, \fBtd_thr_state_e\fR \fIstate\fR, \fBint\fR \fIti_pri\fR, \fBsigset_t *\fR\fIti_sigmask_p\fR,
  40      \fBunsigned\fR \fIti_user_flags\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBtd_err_e\fR \fBtd_ta_tsd_iter\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBtd_key_iter_f *\fR\fIcb\fR,
  46      \fBvoid *\fR\fIcbdata_p\fR);
  47 .fi
  48
  49 .SH DESCRIPTION
  50 .sp
  51 .LP
  52 The \fBtd_ta_sync_iter()\fR, \fBtd_ta_thr_iter()\fR, and \fBtd_ta_tsd_iter()\fR
  53 functions are iterator functions that when given a target process handle as an
  54 argument, return sets of handles for objects associated with the target
  55 process. The method is to call back a client-provided function once for each
  56 associated object, passing back a handle as well as the client-provided pointer
  57 \fIcb_data_p\fR. This enables a client to easily build a linked list of the
  58 associated objects. If the client-provided function returns non-zero, the
  59 iteration terminates, even if there are members remaining in the set of
  60 associated objects.
  61 .sp
  62 .LP
  63 The \fBtd_ta_sync_iter()\fR function returns handles of synchronization objects
  64 (mutexes, readers-writer locks, semaphores, and condition variables) associated
  65 with a process.  Some synchronization objects might not be known to
  66 \fBlibc_db\fR and will not be returned. If the process has initialized the
  67 synchronization object (by calling \fBmutex_init\fR(3C), for example) or a
  68 thread in the process has called a synchronization primitive
  69 (\fBmutex_lock()\fR, for example) using this object after
  70 \fBtd_ta_new\fR(3C_DB) was called to attach to the process and
  71 \fBtd_ta_sync_tracking_enable()\fR was called to enable synchronization object
  72 tracking, then a handle for the synchronization object will be passed to the
  73 callback function. See \fBtd_sync_get_info\fR(3C_DB) for operations that can be
  74 performed on synchronization object handles.
  75 .sp
  76 .LP
  77 The \fBtd_ta_thr_iter()\fR function returns handles for threads that are part
  78 of the target process. For  \fBtd_ta_thr_iter()\fR, the caller specifies
  79 several criteria to select a subset of threads for which the callback function
  80 should be called.  Any of these selection criteria may be wild-carded. If all
  81 of them are wild-carded, then handles for all threads in the process will be
  82 returned.
  83 .sp
  84 .LP
  85 The selection parameters and corresponding wild-card values are:
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBstate (TD_THR_ANY_STATE\fR):\fR
  90 .ad
  91 .sp .6
  92 .RS 4n
  93 Select only threads whose state matches \fBstate\fR. See
  94 \fBtd_thr_get_info\fR(3C_DB) for a list of thread states.
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBti_pri (TD_THR_LOWEST_PRIORITY\fR):\fR
 101 .ad
 102 .sp .6
 103 .RS 4n
 104 Select only threads for which the priority is at least \fBti_pri\fR.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBti_sigmask_p (TD_SIGNO_MASK\fR):\fR
 111 .ad
 112 .sp .6
 113 .RS 4n
 114 Select only threads whose signal mask exactly matches *\fIti_sigmask_p\fR.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBti_user_flags (TD_THR_ANY_USER_FLAGS\fR):\fR
 121 .ad
 122 .sp .6
 123 .RS 4n
 124 Select only threads whose user flags (specified at thread creation time)
 125 exactly match \fIti_user_flags\fR.
 126 .RE
 127
 128 .sp
 129 .LP
 130 The \fBtd_ta_tsd_iter()\fR function returns the thread-specific data keys in
 131 use by the current process.  Thread-specific data for a particular thread and
 132 key can be obtained by calling \fBtd_thr_tsd\fR(3C_DB).
 133 .SH RETURN VALUES
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBTD_OK\fR\fR
 138 .ad
 139 .RS 12n
 140 The call completed successfully.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBTD_BADTA\fR\fR
 147 .ad
 148 .RS 12n
 149 An invalid process handle was passed.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fBTD_DBERR\fR\fR
 156 .ad
 157 .RS 12n
 158 A call to one of the imported interface routines failed.
 159 .RE
 160
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fBTD_ERR\fR\fR
 165 .ad
 166 .RS 12n
 167 The call did not complete successfully.
 168 .RE
 169
 170 .SH ATTRIBUTES
 171 .sp
 172 .LP
 173 See \fBattributes\fR(5) for description of the following attributes:
 174 .sp
 175
 176 .sp
 177 .TS
 178 box;
 179 c | c
 180 l | l .
 181 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 182 _
 183 MT-Level        Safe
 184 .TE
 185
 186 .SH SEE ALSO
 187 .sp
 188 .LP
 189 \fBlibc_db\fR(3LIB), \fBmutex_init\fR(3C), \fBtd_sync_get_info\fR(3C_DB),
 190 \fBtd_thr_get_info\fR(3C_DB), \fBtd_thr_tsd\fR(3C_DB), \fBattributes\fR(5)