td_sync_get_info(3T)

NAME

td_sync_get_info, td_sync_setstate, td_sync_waiters − operations on a synchronization object in libthread_db

SYNOPSIS

cc [ flag ... ] file ... /lib/libthread_db.so.1 [ library ... ]

#include <proc_service.h>
#include <thread_db.h>

td_err_e td_sync_get_info(const td_synchandle_t ∗sh_p, td_syncinfo_t ∗si_p);

td_err_e td_sync_setstate(const td_synchandle_t ∗sh_p, int value);

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 variables, semaphores, and reader-writer locks. In the same way that thread operations use a thread handle of type td_thrhandle_t, operations on synchronization objects use a synchronization object handle of type td_synchandle_t.

The controlling process obtains synchronization object handles either by calling the function td_ta_sync_iter() to obtain handles for all synchronization objects of the target process that are known to the libthread_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 calling td_ta_map_addr2sync().

Note that not all synchronization objects that a process uses may be known to the libthread_db library and returned by td_ta_sync_iter. A synchronization object is known to libthread_db only if it was ever waited on after libthread_db was attached to the process. For example, a mutex may have been widely used, but if no thread ever blocked waiting to acquire it, it will not be known to libthread_db interfaces.

td_sync_get_info()
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 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.

psaddr_t si_sv_addr
The address of the synchronization object in this target process’s address space.

td_sync_type_e si_type
The type of the synchronization variable: mutex, condition variable, semaphore, or reader-writer lock.

int si_shared_type
USYNC_THREAD if this synchronization object is process-private; USYNC_PROCESS if it is process-shared.

td_sync_flags_t si_flags
Flags dependent on the type of the synchronization object.

int si_state.sema_count
Semaphores only. The current value of the semaphore

int si_state.nreaders
Reader-writer locks only. The number of readers currently holding 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.

uchar_t si_has_waiters
Non-zero if and only if at least one thread is blocked on this synchronization object.

uchar_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.

td_thrhandle_t si_owner
Mutexes and reader-writer locks only. This is the thread holding the mutex, or the write lock, if this is a reader-writer lock. The value is NULL if no one holds the mutex or write-lock.

psaddr_t si_data
A pointer to optional data associated with the synchronization object. Currently useful only for debugging libthread() interfaces.

td_sync_setstate modifies the state of synchronization 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, the semaphore’s count is set to the value. For reader-writer locks, the reader count set to the value if value is >0. The count is set to write-locked if value is −1. It is set to unlocked if the value is 0.
Setting the state of a synchronization object from a libthread_db 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 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.

td_sync_waiters 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 passed the thread handle and cb_data_p. If the callback function returns a non-zero value, iteration is terminated early. See also td_ta_thr_iter(3T).

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 routines failed.

TD_ERR A libthread_db-internal error occurred.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT Level	Safe

Museum