'\" te
.\" Copyright (c) 2007, 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]
.TH TD_SYNC_GET_INFO 3C_DB "Nov 22, 2018"
.SH 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
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... -lc_db [ \fIlibrary\fR... ]
#include <proc_service.h>
#include <thread_db.h>

\fBtd_err_e\fR \fBtd_sync_get_info\fR(\fBconst td_synchandle_t *\fR\fIsh_p\fR, \fBtd_syncinfo_t *\fR\fIsi_p\fR);
.fi

.LP
.nf
\fBtd_err_e\fR \fBtd_ta_sync_tracking_enable\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBint\fR \fIon_off\fR);
.fi

.LP
.nf
\fBtd_err_e\fR \fBtd_sync_get_stats\fR(\fBconst td_synchandle_t *\fR\fIsh_p\fR, \fBtd_syncstats_t *\fR\fIss_p\fR);
.fi

.LP
.nf
\fBtd_err_e\fR \fBtd_sync_setstate\fR(\fBconst td_synchandle_t *\fR\fIsh_p\fR, \fBint\fR \fIvalue\fR);
.fi

.LP
.nf
\fBtypedef int\fR \fBtd_thr_iter_f\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBvoid *\fR\fIcb_data_p\fR);
.fi

.LP
.nf
\fBtd_err_e\fR \fBtd_sync_waiters\fR(\fBconst td_synchandle_t *\fR\fIsh_p\fR, \fBtd_thr_iter_f *\fR\fIcb\fR,
     \fBvoid *\fR\fIcb_data_p\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Synchronization objects include mutexes, condition variables, semaphores, and
reader-writer locks. In the same way that thread operations use a thread handle
of type \fBtd_thrhandle_t\fR, operations on synchronization objects use a
synchronization object handle of type \fBtd_synchandle_t\fR.
.sp
.LP
The controlling process obtains synchronization object handles either by
calling the function \fBtd_ta_sync_iter()\fR to obtain handles for all
synchronization objects of the target process that are known to the
\fBlibc_db\fR library of interfaces, or by mapping the address of a
synchronization object in the address space of the target process to a handle
by calling \fBtd_ta_map_addr2sync\fR(3C_DB).
.sp
.LP
Not all synchronization objects that a process uses can be known to the
\fBlibc_db\fR library and returned by \fBtd_ta_sync_iter\fR(3C_DB). A
synchronization object is known to \fBlibc_db\fR only if it has been the target
of a synchronization primitive in the process (such as \fBmutex_lock()\fR,
described on the \fBmutex_init\fR(3C) manual page) after \fBtd_ta_new\fR(3C_DB)
has been called to attach to the process and \fBtd_ta_sync_tracking_enable()\fR
has been called to enable synchronization object tracking.
.sp
.LP
The \fBtd_ta_sync_tracking_enable()\fR function turns synchronization object
tracking on or off for the process identified by \fIta_p\fR, depending on
whether \fIon_off\fR is 0 (off) or non-zero (on).
.sp
.LP
The \fBtd_sync_get_info()\fR function fills in the \fBtd_syncinfo_t\fR
structure \fB*\fR\fIsi_p\fR with values for the synchronization object
identified by  \fBsh_p\fR. The \fBtd_syncinfo_t\fR structure contains the
following fields:
.sp
.ne 2
.na
\fB\fBtd_thragent_t *\fR\fIsi_ta_p\fR\fR
.ad
.RS 29n
The internal process handle identifying the target process through which this
synchronization object handle was obtained.  Synchronization objects may be
process-private or process-shared. In the latter case, the same synchronization
object may have multiple handles, one for each target process's "view" of the
synchronization object.
.RE

.sp
.ne 2
.na
\fB\fBpsaddr_t\fR \fIsi_sv_addr\fR\fR
.ad
.RS 29n
The address of the synchronization object in this target process's address
space.
.RE

.sp
.ne 2
.na
\fB\fBtd_sync_type_e\fR \fIsi_type\fR\fR
.ad
.RS 29n
The type of the synchronization variable: mutex, condition variable, semaphore,
or readers-writer lock.
.RE

.sp
.ne 2
.na
\fB\fBint\fR \fIsi_shared_type\fR\fR
.ad
.RS 29n
If \fIsi_shared_type\fR is non-zero, this synchronization object is
process-shared, otherwise it is process-private.
.RE

.sp
.ne 2
.na
\fB\fBtd_sync_flags_t\fR \fIsi_flags\fR\fR
.ad
.RS 29n
Flags dependent on the type of the synchronization object.
.RE

.sp
.ne 2
.na
\fB\fBint\fR \fIsi_state.sema_count\fR\fR
.ad
.RS 29n
Semaphores only.  The current value of the semaphore
.RE

.sp
.ne 2
.na
\fB\fBint\fR \fIsi_state.nreaders\fR\fR
.ad
.RS 29n
Readers-writer locks only. The number of readers currently holding the lock, or
\fB-1\fR, if a writer is currently holding the lock.
.RE

.sp
.ne 2
.na
\fB\fBint\fR \fIsi_state.mutex_locked\fR\fR
.ad
.RS 29n
For mutexes only. Non-zero if and only if the mutex is currently locked.
.RE

.sp
.ne 2
.na
\fB\fBint\fR \fIsi_size\fR\fR
.ad
.RS 29n
The size of the synchronization object.
.RE

.sp
.ne 2
.na
\fB\fBuint8_t\fR \fIsi_has_waiters\fR\fR
.ad
.RS 29n
Non-zero if and only if at least one thread is blocked on this synchronization
object.
.RE

.sp
.ne 2
.na
\fB\fBuint8_t\fR \fIsi_is_wlocked\fR\fR
.ad
.RS 29n
For reader-writer locks only. The value is non-zero if and only if this lock is
held by a writer.
.RE

.sp
.ne 2
.na
\fB\fBuint8_t\fR \fIsi_rcount\fR\fR
.ad
.RS 29n
\fBPTHREAD_MUTEX_RECURSIVE\fR mutexes only. If the mutex is held, the recursion
count.
.RE

.sp
.ne 2
.na
\fB\fBuint8_t\fR \fIsi_prioceiling\fR\fR
.ad
.RS 29n
\fBPTHREAD_PRIO_PROTECT\fR protocol mutexes only. The priority ceiling.
.RE

.sp
.ne 2
.na
\fB\fBtd_thrhandle_t\fR \fIsi_owner\fR\fR
.ad
.RS 29n
Mutexes and readers-writer locks only. This is the thread holding the mutex, or
the write lock, if this is a reader-writer lock. The value is    \fINULL\fR if
no one holds the mutex or write-lock.
.RE

.sp
.ne 2
.na
\fB\fBpid_t\fR \fIsi_ownerpid\fR\fR
.ad
.RS 29n
Mutexes only.  For a locked process-shared mutex, this is the process-ID of the
process containing the owning thread.
.RE

.sp
.LP
The \fBtd_sync_get_stats()\fR function fills in the \fBtd_syncstats_t\fR
structure *\fIss_p\fR with values for the synchronization object identified by
\fIsh_p\fR.  The \fBtd_syncstats_t\fR structure contains an embedded
\fBtd_syncinfo_t\fR structure that is filled in as described above for
\fBtd_sync_get_info()\fR.  In addition, usage statistics gathered since
\fBtd_ta_sync_tracking_enable()\fR was called to enable synchronization object
tracking are returned in the \fBss_un.mutex\fR, \fBss_un.cond\fR,
\fBss_un.rwlock\fR, or \fBss_un.sema\fR members of the \fBtd_syncstats_t\fR
structure, depending on the type of the synchronization object.
.sp
.LP
The \fBtd_sync_setstate\fR function modifies the state of synchronization
object \fIsi_p\fR, depending on the synchronization object type. For mutexes,
\fBtd_sync_setstate\fR is unlocked if the \fIvalue\fR is \fB0\fR. Otherwise it
is locked. For semaphores, the semaphore's count is set to the \fIvalue\fR. For
reader-writer locks, the reader count set to the \fIvalue\fR if \fIvalue\fR is
\fB>0\fR. The count is set to write-locked if \fIvalue\fR is \fB-1\fR\&.
It is set to unlocked if the \fIvalue\fR is \fB0\fR. Setting the state of a
synchronization object from a \fBlibc_db\fR interface may cause the
synchronization object's semantics to be violated from the point of view of
the threads in the target process. For example, if a thread holds a mutex,
and \fBtd_sync_setstate\fR is used to set the mutex to unlocked, then a
different thread  will also be able to subsequently acquire the same mutex.
.sp
.LP
The \fBtd_sync_waiters\fR function iterates over the set of thread handles of
threads blocked on \fIsh_p\fR. The callback function \fIcb\fR is called once
for each such thread handle, and is passed  the thread handle and
\fIcb_data_p\fR. If the callback function returns a non-zero value, iteration
is terminated early. See \fBtd_ta_thr_iter\fR(3C_DB).
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBTD_OK\fR \fR
.ad
.RS 13n
The call returned successfully.
.RE

.sp
.ne 2
.na
\fB\fBTD_BADTH\fR \fR
.ad
.RS 13n
An invalid thread handle was passed in.
.RE

.sp
.ne 2
.na
\fB\fBTD_DBERR\fR \fR
.ad
.RS 13n
A call to one of the imported interface routines failed.
.RE

.sp
.ne 2
.na
\fB\fBTD_ERR\fR \fR
.ad
.RS 13n
A libc_db-internal error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibc_db\fR(3LIB), \fBmutex_init\fR(3C), \fBtd_ta_map_addr2sync\fR(3C_DB),
\fBtd_ta_sync_iter\fR(3C_DB), \fBtd_ta_thr_iter\fR(3C_DB), \fBattributes\fR(7)