Difference between revisions of "DosQueryMutexSem"

From EDM2
Jump to: navigation, search
m
 
(3 intermediate revisions by one user not shown)
Line 1: Line 1:
=== Syntax ===
+
DosQueryMutexSem returns the process ID, thread ID and request count of the owner of the mutex semaphore referred to by ''hmtxSemaphore''.
  rc = DosQueryMutexSem( ''hmtxSemaphore'',  
+
 
                        ''ppidSemaphoreOwner'',  
+
== Syntax ==
                        ''ptidSemaphoreOwner'',  
+
  DosQueryMutexSem( ''hmtxSemaphore'', ''ppidSemaphoreOwner'', ''ptidSemaphoreOwner'', ''pulRequestCount'' )
                        ''pulRequestCount'' );
+
  
 
=== Parameters ===
 
=== Parameters ===
'''HMTX ''hmtxSemaphore'' (input)'''
+
;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.
The handle (HMTX) of the semaphore to
+
;PTID ''ptidSemaphoreOwner'' (output):A pointer to the thread ID structure (TID) that will get the ID of the current semaphore owner.
be queried.   
+
;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).
 
+
'''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 ===
 
=== Returns ===
APIRET rc
+
;APIRET rc:The following values can be returned
The following values can be returned
+
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 51: Line 31:
 
this dead owner
 
this dead owner
 
|}
 
|}
 
=== Include Info ===
 
#define INCL_DOSSEMAPHORES
 
#include <os2.h>
 
  
 
=== Usage Explanation ===
 
=== Usage Explanation ===
DosQueryMutexSem returns the process ID, thread ID and request count of the owner of the mutex semaphore refered to by ''hmtxSemaphore''.
+
The process calling DosQueryMutexSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned.
 
+
=== 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 ===
+
== Sample Code ==
 
<pre>
 
<pre>
 
#define INCL_DOSSEMAPHORES
 
#define INCL_DOSSEMAPHORES
#include  
+
#include <os2.h>
  
 
HMTX  hmtxMySemaphore;    /* pointer to my semaphore handle */
 
HMTX  hmtxMySemaphore;    /* pointer to my semaphore handle */
Line 90: Line 61:
 
</pre>  
 
</pre>  
  
=== See Also ===
+
== See Also ==
[[OS2 API:CPI:DosCloseMutexSem|DosCloseMutexSem]],
+
*[[DosCloseMutexSem]]
[[OS2 API:CPI:DosCreateMutexSem|DosCreateMutexSem]],
+
*[[DosCreateMutexSem]]
[[OS2 API:CPI:DosOpenMutexSem|DosOpenMutexSem]],
+
*[[DosOpenMutexSem]]
[[OS2 API:CPI:DosReleaseMutexSem|DosReleaseMutexSem]],
+
*[[DosReleaseMutexSem]]
[[OS2 API:CPI:DosRequestMutexSem|DosRequestMutexSem]]
+
*[[DosRequestMutexSem]]
  
[[Category:The OS/2 API Project]]
+
[[Category:Dos]]

Latest revision as of 10:05, 12 October 2018

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

Syntax

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
0 NO_ERROR Semaphore queried successfully
6 ERROR_INVALID_HANDLE Error, The value in phmtxSemaphore does not point to a valid semaphore, The calling process must first have access to the semaphore in question
87 ERROR_INVALID_PARAMETER Error, One or more parameters is not recognized, See parameters above
105 ERROR_SEM_OWNER_DIED Error, The process that owns the semaphore has died before releasing it, The values returned in ppidSemaphoreOwner and ptidSemaphoreOwner refer to

this dead owner

Usage Explanation

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