Guardian Procedure Calls Reference Manual

Recovery: Check to make sure the specified process is active. Run the program calling BINSEM_GETSTATS_
on the same processor where the process of interest is running.
BINSEM_RET_EPERM4001
This process does not have the appropriate access ID to obtain statistics on the process of interest.
Recovery: Only users with appropriate privileges to a process are able to successfully call BINSEM_GETSTATS_.
Considerations
The BINSEM_GETSTATS_ interface is designed for iterative query of all the binary semaphores in
a target process. For the first call to BINSEM_GETSTATS_, pass BINSEM_STAT_INIT_CONTEXT
as the semID to obtain statistics for the first binary semaphore in the process:
• If BINSEM_OK (0) is returned, then subsequent calls to BINSEM_GETSTATS_ (passing the
BINSEM ID returned in statsP) provide statistics for the next binary semaphore.
• If BINSEM_RET_EOF (1) is returned, then there are no more binary semaphores in the process.
To query the status of a particular binary semaphore with semaphore ID n, pass n – 1 as the semID
context parameter:
• If the response is BINSEM_OK (0) and the BINSEM ID in statsP is n, statsP contains the
requested information.
• If the response is BINSEM_RET_EOF (1), the requested BINSEM ID does not exist and none
exist above the requested semID.
• If the response is BINSEM_OK (0) and the reported BINSEM ID is not n, the requested BINSEM
ID does not exist in the process; however, statistics are returned for the next highest binary
semaphore above n.
NOTE: If the return value is not BINSEM_RET_OK (0), the contents of the statsP structure are
unchanged and no binary semaphore counters are modified.
Table 6 lists the fields and their descriptions of the binSemStats_t data structure.
Table 6 binSemStats_t Data Structure
DescriptionField
The BINSEM ID in this process.semID
The serial number of creation (since processor load): uniquely identifies the same binary semaphore
shared by multiple processes.
serialNUM
The time the binary semaphore was created.createTime
The number of times the binary semaphore was acquired.acquisitions
The number of times the binary semaphore was found locked and the process is put on the contentions
list. The maximum value for this field is 4 GB – 1.
contentions
The number of times the binary semaphore was found locked and contended. The maximum value
for this field is 2^32 – 1.
multiCont
The number of times a timeout occurred when a process tried to acquire a binary semaphore. The
maximum value for this field is 2^32 – 1.
timeouts
The number of times a process stole the binary semaphore from an unresponsive process. The maximum
value for this field is 2^16 – 1.
forced
The number of times a process abandoned ownership of a binary semaphore. The maximum value
for this field is 2^16 – 1.
forsaken
The number of processes waiting for the binary semaphore.contenders
The maximum number of contenders for a binary semaphore.maxContend
BINSEM_GETSTATS_ Procedure 95