te
All Rights Reserved Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved
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.
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.
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]
td_ta_sync_iter, td_ta_thr_iter, td_ta_tsd_iter - iterator functions on process handles from libc_db

cc [ flag... ] file... -lc_db [ library... ]
#include <proc_service.h>
#include <thread_db.h>

typedef int td_sync_iter_f(const td_synchandle_t *sh_p, void *cbdata_p);

typedef int td_thr_iter_f(const td_thrhandle_t *th_p, void *cbdata_p);

typedef int td_key_iter_f(thread_key_t key, void (*destructor)(), void *cbdata_p);

td_err_e td_ta_sync_iter(const td_thragent_t *ta_p, td_sync_iter_f *cb,
 void *cbdata_p);

td_err_e td_ta_thr_iter(const td_thragent_t *ta_p, td_thr_iter_f *cb,
 void *cbdata_p, td_thr_state_e state, int ti_pri, sigset_t *ti_sigmask_p,
 unsigned ti_user_flags);

td_err_e td_ta_tsd_iter(const td_thragent_t *ta_p, td_key_iter_f *cb,
 void *cbdata_p);

The td_ta_sync_iter(), td_ta_thr_iter(), and td_ta_tsd_iter() functions are iterator functions that when given a target process handle as an argument, return sets of handles for objects associated with the target process. The method is to call back a client-provided function once for each associated object, passing back a handle as well as the client-provided pointer cb_data_p. This enables a client to easily build a linked list of the associated objects. If the client-provided function returns non-zero, the iteration terminates, even if there are members remaining in the set of associated objects.

The td_ta_sync_iter() function returns handles of synchronization objects (mutexes, readers-writer locks, semaphores, and condition variables) associated with a process. Some synchronization objects might not be known to libc_db and will not be returned. If the process has initialized the synchronization object (by calling mutex_init(3C), for example) or a thread in the process has called a synchronization primitive (mutex_lock(), for example) using this object after td_ta_new(3C_DB) was called to attach to the process and td_ta_sync_tracking_enable() was called to enable synchronization object tracking, then a handle for the synchronization object will be passed to the callback function. See td_sync_get_info(3C_DB) for operations that can be performed on synchronization object handles.

The td_ta_thr_iter() function returns handles for threads that are part of the target process. For td_ta_thr_iter(), the caller specifies several criteria to select a subset of threads for which the callback function should be called. Any of these selection criteria may be wild-carded. If all of them are wild-carded, then handles for all threads in the process will be returned.

The selection parameters and corresponding wild-card values are: state (TD_THR_ANY_STATE):

ti_pri (TD_THR_LOWEST_PRIORITY): ti_sigmask_p (TD_SIGNO_MASK): ti_user_flags (TD_THR_ANY_USER_FLAGS):

The td_ta_tsd_iter() function returns the thread-specific data keys in use by the current process. Thread-specific data for a particular thread and key can be obtained by calling td_thr_tsd(3C_DB).

TD_OK TD_BADTA TD_DBERR TD_ERR

See attributes(5) for description of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

MT-Level Safe

libc_db(3LIB), mutex_init(3C), td_sync_get_info(3C_DB), td_thr_get_info(3C_DB), td_thr_tsd(3C_DB), attributes(5)