[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

DosQueryMutexSem

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

 rc = DosQueryMutexSem( hmtxSemaphore, ppidSemaphoreOwner, ptidSemaphoreOwner, pulRequestCount );

Parameters
HMTX hmtxSemaphore (input)
The handle (HMTX) of the semaphore to be queried.

PPID ppidSemaphoreOwner (output)
A pointer to the process ID structure (PID) that will get the ID of the semaphore owner.

PTID ptidSemaphoreOwner (output)
A pointer to the thread ID structure (TID) that will get the ID of the current semaphore owner.

PUL pulRequestCount (output)
A pointer to the ULONG that is to get the request count of the queried mutex semaphore. The request count is calculated by subtracting the number of releases from the number of requests made on the mutex semaphore. If the semaphore currently has no owner then the request count is zero (0).

Returns
APIRET rc
The following values can be returned
0NO_ERRORSemaphore queried successfully
6ERROR_INVALID_HANDLEError, The value in phmtxSemaphore does not point to a valid semaphore, The calling process must first have access to the semaphore in question
87ERROR_INVALID_PARAMETERError, One or more parameters is not recognized, See parameters above
105ERROR_SEM_OWNER_DIEDError, The process that owns the semaphore has died before releasing it, The values returned in ppidSemaphoreOwner and ptidSemaphoreOwner refer to this dead owner

Include Info

 #define INCL_DOSSEMAPHORES
#include <os2.h>

Usage Explanation

 DosQueryMutexSem returns the process ID, thread ID and request count of the owner of the mutex semaphore refered to by hmtxSemaphore.

Relevant Structures

Gotchas

 The process calling DosQueryMutexSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned.

Sample Code

 #define INCL_DOSSEMAPHORES #include <os2.h> HMTX hmtxMySemaphore; /* pointer to my semaphore handle */ PID pidSemaphoreOwner; /* will get PID of sem owner */ TID tidSempahoreOwner; /* will get TID of sem owner */ ULONG ulRequestCount; /* will get the request count for the sem */ /* access is gained to the semaphore in question */ /* either by DosCreateMutexSem ... */ /* ... or by DosOpenMutexSem */ /* its handle is placed in hmtxMySemaphore */ rc = DosQueryMutexSem(hmtxMySemaphore, &pidSemaphoreOwner, &tidSemaphoreOwner, &ulRequestCount); if (rc != 0) { /* We got an error to take care of. */ }

See Also

 DosCloseMutexSem, DosCreateMutexSem, DosOpenMutexSem, DosReleaseMutexSem, DosRequestMutexSem

Author

Joe Phillips - jaiger@eng2.uconn.edu

Additions

Last modified May 27/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

DosQueryMutexSem