Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSSEMAPHORES
 
USHORT DosSemWait(hsem, lTimeOut)
HSEM hsem;        /* semaphore handle */
LONG lTimeOut;    /* time-out         */
 
The DosSemWait function waits for a specified semaphore to be cleared.
DosSemWait waits until a thread uses the DosSemClear function to clear the
semaphore or until a time-out occurs. If no previous thread has set the
semaphore, DosSemWait returns immediately.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hsem       Identifies the semaphore to set. This value can be the handle of
           a system semaphore that has been previously created or opened by
           using the DosCreateSem or DosOpenSem function, or it can be the
           address of a RAM semaphore.
 
lTimeOut   Specifies how long to wait for the semaphore to clear. If the
           value is greater then zero, this parameter specifies the number
           of milliseconds to wait before returning. If the value is
           SEM_IMMEDIATE_RETURN, the function returns immediately. If the
           value is SEM_INDEFINITE_WAIT, the function waits indefinitely.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_EXCL_SEM_ALREADY_OWNED
     ERROR_INTERRUPT
     ERROR_SEM_TIMEOUT
 
Comments
 
The DosSemWait function cannot be used to wait for a system semaphore that
is owned by another process unless the semaphore is nonexclusive.
 
If more than one thread is setting and clearing the semaphore, the thread
calling DosSemWait may have to wait through several changes of the semaphore
before it continues (depending on which thread clears the semaphore and when
the system scheduler passes control to the calling thread). The thread must
wait for as long as the semaphore is set, even if the semaphore has been
cleared and reset since the thread originally called the function.
 
Example
 
This example calls the DosSemWait function to wait for up to 5 seconds for a
RAM semaphore. If a time-out occurs before the semaphore handle is
retrieved, the function returns an ERROR_SEM_TIMEOUT error value.
 
ULONG hsem = 0;
if (DosSemWait(&hsem, 5000L) == ERROR_SEM_TIMEOUT) {
    .
    . /* error processing */
    .
}
else {
 
See Also
 
DosCreateSem, DosMuxSemWait, DosOpenSem, DosSemClear, DosSemRequest,
DosSemSetWait, WinMsgSemWait
 
                                      ♦