Threads Debugging Library Functions td_sync_get_info(3C_DB)
NAME
td_sync_get_info, td_ta_sync_tracking_enable,
td_sync_get_stats, td_sync_setstate, td_sync_waiters -
operations on a synchronization object in libc_db
SYNOPSIS
cc [ flag... ] file... -lc_db [ library... ]
#include
#include
td_err_e td_sync_get_info(const td_synchandle_t *sh_p, td_syncinfo_t *si_p);
td_err_e td_ta_sync_tracking_enable(const td_thragent_t *ta_p, int on_off);
td_err_e td_sync_get_stats(const td_synchandle_t *sh_p, td_syncstats_t *ss_p);
td_err_e td_sync_setstate(const td_synchandle_t *sh_p);
typedef int td_thr_iter_f(const td_thrhandle_t *th_p, void *cb_data_p);
td_err_e td_sync_waiters(const td_synchandle_t *sh_p, td_thr_iter_f *cb,
void *cb_data_p);
DESCRIPTION
Synchronization objects include mutexes, condition vari-
ables, semaphores, and reader-writer locks. In the same way
that thread operations use a thread handle of typetd_thrhandle_t, operations on synchronization objects use a
synchronization object handle of type td_synchandle_t.
The controlling process obtains synchronization object han-
dles either by calling the function td_ta_sync_iter() to
obtain handles for all synchronization objects of the targetprocess that are known to the libc_db library of interfaces,
or by mapping the address of a synchronization object in the address space of the target process to a handle by callingtd_ta_map_addr2sync(3C_DB).
Not all synchronization objects that a process uses can beknown to the libc_db library and returned by
td_ta_sync_iter(3C_DB). A synchronization object is known to
libc_db only if it has been the target of a synchronization
primitive in the process (such as mutex_lock(), described on
the mutex_init(3C) manual page) after td_ta_new(3C_DB) has
SunOS 5.11 Last change: 5 Jun 2007 1
Threads Debugging Library Functions td_sync_get_info(3C_DB)
been called to attach to the process andtd_ta_sync_tracking_enable() has been called to enable syn-
chronization object tracking.The td_ta_sync_tracking_enable() function turns synchroniza-
tion object tracking on or off for the process identified byta_p, depending on whether on_off is 0 (off) or non-zero
(on).The td_sync_get_info() function fills in the td_syncinfo_t
structure *si_p with values for the synchronization object
identified by sh_p. The td_syncinfo_t structure contains
the following fields:td_thragent_t *si_ta_p The internal process handle
identifying the target processthrough which this synchroniza-
tion object handle was obtained. Synchronizationobjects may be process-private
or process-shared. In the
latter case, the same synchron-
ization object may have multi-
ple handles, one for each tar-
get process's "view" of the synchronization object.psaddr_t si_sv_addr The address of the synchroniza-
tion object in this target process's address space.td_sync_type_e si_type The type of the synchronization
variable: mutex, condition variable, semaphore, orreaders-writer lock.
int si_shared_type If si_shared_type is non-zero,
this synchronization object isprocess-shared, otherwise it is
process-private.
td_sync_flags_t si_flags Flags dependent on the type of
the synchronization object.SunOS 5.11 Last change: 5 Jun 2007 2
Threads Debugging Library Functions td_sync_get_info(3C_DB)
int si_state.sema_count Semaphores only. The current
value of the semaphoreint si_state.nreaders Readers-writer locks only. The
number of readers currentlyholding the lock, or -1, if a
writer is currently holding the lock.int si_state.mutex_locked For mutexes only. Non-zero if
and only if the mutex is currently locked.int si_size The size of the synchronization
object.uint8_t si_has_waiters Non-zero if and only if at
least one thread is blocked on this synchronization object.uint8_t si_is_wlocked For reader-writer locks only.
The value is non-zero if and
only if this lock is held by a writer.uint8_t si_rcount PTHREAD_MUTEX_RECURSIVE mutexes
only. If the mutex is held, the recursion count.uint8_t si_prioceiling PTHREAD_PRIO_PROTECT protocol
mutexes only. The priority ceiling.td_thrhandle_t si_owner Mutexes and readers-writer
locks only. This is the thread holding the mutex, or the writelock, if this is a reader-
writer lock. The value is NULL if no one holds the mutexor write-lock.
pid_t si_ownerpid Mutexes only. For a locked
process-shared mutex, this is
SunOS 5.11 Last change: 5 Jun 2007 3
Threads Debugging Library Functions td_sync_get_info(3C_DB)
the process-ID of the process
containing the owning thread.The td_sync_get_stats() function fills in the td_syncstats_t
structure *ss_p with values for the synchronization object
identified by sh_p. The td_syncstats_t structure contains
an embedded td_syncinfo_t structure that is filled in as
described above for td_sync_get_info(). In addition, usage
statistics gathered since td_ta_sync_tracking_enable() was
called to enable synchronization object tracking arereturned in the ss_un.mutex, ss_un.cond, ss_un.rwlock, or
ss_un.sema members of the td_syncstats_t structure, depend-
ing on the type of the synchronization object.The td_sync_setstate function modifies the state of syn-
chronization object si_p, depending on the synchronization
object type. For mutexes, td_sync_setstate is unlocked if
the value is 0. Otherwise it is locked. For semaphores, thesemaphore's count is set to the value. For reader-writer
locks, the reader count set to the value if value is >0. Thecount is set to write-locked if value is -1. It is set to
unlocked if the value is 0. Setting the state of a syn-
chronization object from a libc_db interface may cause the
synchronization object's semantics to be violated from the point of view of the threads in the target process. Forexample, if a thread holds a mutex, and td_sync_setstate is
used to set the mutex to unlocked, then a different thread will also be able to subsequently acquire the same mutex.The td_sync_waiters function iterates over the set of thread
handles of threads blocked on sh_p. The callback function cb
is called once for each such thread handle, and is passedthe thread handle and cb_data_p. If the callback function
returns a non-zero value, iteration is terminated early. See
td_ta_thr_iter(3C_DB).
RETURN VALUES
TD_OK The call returned successfully.
TD_BADTH An invalid thread handle was passed in.
TD_DBERR A call to one of the imported interface rou-
tines failed.SunOS 5.11 Last change: 5 Jun 2007 4
Threads Debugging Library Functions td_sync_get_info(3C_DB)
TD_ERR A libc_db-internal error occurred.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libc_db(3LIB), mutex_init(3C), td_ta_map_addr2sync(3C_DB),
td_ta_sync_iter(3C_DB), td_ta_thr_iter(3C_DB), attributes(5)
SunOS 5.11 Last change: 5 Jun 2007 5