View source for DosRequestMutexSem

DosRequestMutexSem blocks until ownership of a mutex semaphore may be obtained.
Ownership of a semaphore with multiple threads requesting it is granted to the thread with the highest priority. Among threads with the same priority, ownership is granted in a First-In-First-Out (FIFO) manner.

==Syntax==
 DosRequestMutexSem( hmtxSemaphore, ulTimeOut )

==Parameters==
;HMTX ''hmtxSemaphore'' (input):The handle of the semaphore to be released.
;ULONG ''ulTimeout'' (input):The number of milliseconds the function will wait before
returning.
* Set to '''SEM_IMMEDIATE_RETURN''' (0), the function will return immediately regardless of whether or not the semaphore is free.
* Set to '''SEM_INDEFINITE_WAIT''' (-1), the function will block indefinitely (forever) until the semaphore becomes free and ownership is obtained.
 
=== Returns ===
;APIRET rc:The following values can be returned
{|class="wikitable"
|0
|NO_ERROR
|Successfully obtained semaphore ownership
|-
|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
|-
|95
|ERROR_INTERRUPT
|Error, The thread has become unblocked by an external event such as an exception, ownership has not been obtained
|-
|103
|ERROR_TOO_MANY_SEM_REQUESTS
|Error, The semaphore usage count system limit, of 65535, has been exceeded
|-
|105
|ERROR_SEM_OWNER_DIED
|Error, The semaphore owner has died without releasing the semaphore
|-
|640
|ERROR_TIMEOUT
|Error, The caller was blocked for ''ulTimeout'' milliseconds but ownership of the semaphore could not be obtained within this time limit, Time has expired
|}
 
=== Gotchas ===
The process calling DosRequestMutexSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned.

=== Sample Code ===
<pre>
#define INCL_DOSSEMAPHORES
#include <os2.h>

HMTX  hmtxMySemaphore;     /* MySemaphore handle */
ULONG TimeOut= -1;         /* the number of milliseconds the */
                           /* the caller will block for the sem */
                           /* this example will block forever */

	/* access is gained to the semaphore in question */
	/* either by DosCreateMutexSem ... */
	/* ... or by DosOpenMutexSem */
	/* its handle is placed in hmtxMySemaphore */

	rc = DosRequestMutexSem(hmtxMySemaphore, TimeOut);

	if (rc != 0)
	{
	  /* We got an error to take care of. */
	}
</pre>

=== See Also ===
*[[DosCloseMutexSem]]
*[[DosCreateMutexSem]]
*[[DosOpenMutexSem]]
*[[DosQueryMutexSem]]
*[[DosReleaseMutexSem]] 

[[Category:Dos]]