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►  ◄Changes►               ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSSEMAPHORES
 
USHORT DosCreateSem(fExclusive, phssm, pszSemName)
USHORT fExclusive;    /* exclusive/nonexclusive ownership flag    */
PHSYSSEM phssm;       /* pointer to variable for semaphore handle */
PSZ pszSemName;       /* pointer to semaphore name                */
 
The DosCreateSem function creates a system semaphore and copies the
semaphore handle to a variable. A process can use a system semaphore to
indicate to another process a change in the status of a shared resource.
 
Parameter   Description
────────────────────────────────────────────────────────────────────────────
 
fExclusive  Specifies ownership of the semaphore. If this parameter is
            CSEM_PRIVATE, the process receives exclusive ownership. If this
            parameter is CSEM_PUBLIC, the process does not receive exclusive
            ownership.
 
phssm       Points to the variable that receives the semaphore handle.
 
pszSemName  Points to a null-terminated string that identifies the
            semaphore. The string must have the form \sem\name. The string
            name, name, must have the same format as an MS OS/2 filename and
            must be unique.
 
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_ALREADY_EXISTS
     ERROR_INVALID_NAME
     ERROR_INVALID_PARAMETER
     ERROR_TOO_MANY_SEMAPHORES
 
Comments
 
The process calling DosSemCreate receives exclusive ownership of the
semaphore if the CSEM_PRIVATE flag is set in the fExclusive parameter.
Exclusive ownership prevents other processes from setting or clearing the
semaphore. Other processes can open the semaphore and wait for it to change
status, but they cannot change its status. Another process can obtain
ownership of the semaphore, however, by calling the DosSemRequest function.
If ownership of the semaphore changed through DosSemRequest, the process
that originally called DosCreateSem no longer has ownership. It cannot
change the status of the semaphore until it regains ownership by calling
DosSemRequest.
 
Example
 
This example calls DosCreateSem to create a system semaphore, and then calls
DosSemSet to set it and DosSemClear to clear it:
 
HSYSSEM hssm;               /* handle to semaphore */
DosCreateSem(CSEM_PRIVATE,  /* specifies ownership */
    &hssm,                  /* address of handle   */
    "\\sem\\abc.sem");      /* name of semaphore   */
DosSemSet(hssm);            /* sets semaphore      */
    .
    .
    .
DosSemClear(hssm);          /* clears semaphore    */
 
See Also
 
DosCloseSem, DosMuxSemWait, DosOpenSem, DosSemClear, DosSemRequest,
DosSemSet, DosSemSetWait, DosSemWait
 
                                      ♦