NSPR Reference: Chapter 30 IPC Semaphores
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 30 IPC Semaphores

This chapter describes the NSPR API for using interprocess communication semaphores.

NSPR provides an interprocess communication mechanism using a counting semaphore model similar to that which is provided in Unix and Windows platforms.

See also Chapter 28 "Named Shared Memory."

## IPC Semaphore Functions

`PR_OpenSemaphore`
`PR_WaitSemaphore`
`PR_PostSemaphore`
`PR_CloseSemaphore`
`PR_DeleteSemaphore`

#### PR_OpenSemaphore

Creates or opens a named semaphore with the specified name

##### Syntax

`#include <pripcsem.h>`

`#define PR_SEM_CREATE 0x1 /* create if not exist */`

`#define PR_SEM_EXCL 0x2 /* fail if already exists */`

`NSPR_API(PRSem *) PR_OpenSemaphore(
const char *name,
PRIntn flags,
PRIntn mode,
PRUintn value
);`

##### Parameters

The function has the following parameters:

    name
| The name to be given the semaphore.
    flags
| How to create or open the semaphore.
    mode
| Unix style file mode to be used when creating the semaphore.
    value
| The initial value assigned to the semaphore.

##### Returns

A pointer to a `PRSem` structure or `NULL` on error.

##### Description

If the named semaphore doesn't exist and the `PR_SEM_CREATE` flag is specified, the named semaphore is created. The created semaphore needs to be removed from the system with a `PR_DeleteSemaphore` call.

If `PR_SEM_CREATE` is specified, the third argument is the access permission bits of the new semaphore (same interpretation as the mode argument to `PR_Open`) and the fourth argument is the initial value of the new semaphore. If `PR_SEM_CREATE` is not specified, the third and fourth arguments are ignored.

#### PR_WaitSemaphore

Returns the value of the environment variable.

##### Syntax

    #include <pripcsem.h>

    NSPR_API(PRStatus) PR_WaitSemaphore(PRSem *sem);

##### Parameters

The function has the following parameter:

    sem
| A pointer to a PRSem structure returned from a call to `PR_OpenSemaphore`.

##### Returns

`PRStatus`.

##### Description

`PR_WaitSemaphore` tests the value of the semaphore. If the value of the semaphore is > 0, the value of the semaphore is decremented and the function returns. If the value of the semaphore is 0, the function blocks until the value becomes > 0, then the semaphore is decremented and the function returns.

The "test and decrement" operation is performed atomically.

#### PR_PostSemaphore

Increments the value of a specified semaphore.

##### Syntax

    #include <pripcsem.h>

    NSPR_API(PRStatus) PR_PostSemaphore(PRSem *sem);

##### Parameters

The function has the following parameter:

    sem
| A pointer to a `PRSem` structure returned from a call to `PR_OpenSemaphore`.

##### Returns

`PRStatus`

#### PR_CloseSemaphore

Closes a specified semaphore.

##### Syntax

`#include <pripcsem.h>`

`NSPR_API(PRStatus) PR_CloseSemaphore(PRSem *sem);`

##### Parameters

The function has the following parameter:

    sem
| A pointer to a `PRSem` structure returned from a call to `PR_OpenSemaphore`.

##### Returns

`PRStatus`.

#### PR_DeleteSemaphore

Removes a semaphore specified by name from the system.

##### Syntax

    #include <pripcsem.h>

    NSPR_API(PRStatus) PR_DeleteSemaphore(const char *name);

##### Parameters

The function has the following parameter:

    name
| The name of a semaphore that was previously created via a call to `PR_OpenSemaphore`.

##### Returns

PRStatus.

Previous Contents Next

Last Updated May 18, 2001