# perldoc > IPC::Semaphore

---
type: CommandReference
command: IPC::Semaphore
mode: perldoc
section: 
source: perldoc
---

## Quick Reference

- `IPC::Semaphore->new(KEY, NSEMS, FLAGS)` — create a new semaphore set
- `$sem->getall` — returns array of all semaphore values
- `$sem->setall(VALUES)` — set all semaphore values from a list
- `$sem->op(OPLIST)` — perform semaphore operations (semop)
- `$sem->remove` — remove and destroy the semaphore set
- `$sem->stat` — returns stat object with permission/ownership info
- `$sem->setval(N, VALUE)` — set the Nth semaphore value
- `$sem->getval(SEM)` — get current value of a single semaphore

## Name

SysV Semaphore IPC object class

## Synopsis

perl
use IPC::SysV qw(IPC_PRIVATE S_IRUSR S_IWUSR IPC_CREAT);
use IPC::Semaphore;

$sem = IPC::Semaphore->new(IPC_PRIVATE, 10, S_IRUSR | S_IWUSR | IPC_CREAT);
$sem->setall( (0) x 10);
@sem = $sem->getall;
$ncnt = $sem->getncnt;
$zcnt = $sem->getzcnt;
$ds = $sem->stat;
$sem->remove;
## Options (Methods)

### Creation

- `new(KEY, NSEMS, FLAGS)` — create a new semaphore set associated with `KEY`. `NSEMS` is the number of semaphores. A new set is created if `KEY` equals `IPC_PRIVATE` or if `KEY` does not already have a semaphore identifier and `FLAGS & IPC_CREAT` is true. On creation, `FLAGS` sets permissions. Do not set execute bits (may cause failures on some systems).

### Query

- `getall` — returns the values of the semaphore set as an array.
- `getncnt(SEM)` — returns number of processes waiting for semaphore `SEM` to become greater than its current value.
- `getpid(SEM)` — returns process ID of the last process that performed an operation on semaphore `SEM`.
- `getval(SEM)` — returns current value of semaphore `SEM`.
- `getzcnt(SEM)` — returns number of processes waiting for semaphore `SEM` to become zero.
- `id` — returns the system identifier for the semaphore set.
- `stat` — returns an object of type `IPC::Semaphore::stat` (subclass of `Class::Struct`) with fields: `uid`, `gid`, `cuid`, `cgid`, `mode`, `ctime`, `otime`, `nsems`.

### Modification

- `op(OPLIST)` — perform semaphore operations via `semop(2)`. `OPLIST` is a concatenation of lists, each with three values: semaphore number, operation, and flags. Example:
  ```perl
  $sem->op(
      0, -1, IPC_NOWAIT,
      1,  1, IPC_NOWAIT
  );
  
- `set(STAT)` or `set(NAME => VALUE [, ...])` — set `uid`, `gid`, and `mode` (permission bits only) of the semaphore set. Accepts either a stat object from `stat` method or a list of name-value pairs.
- `setall(VALUES)` — set all values in the semaphore set to the given list. The list must contain exactly `NSEMS` values.
- `setval(N, VALUE)` — set the Nth semaphore value (0-indexed) to `VALUE`.

### Removal

- `remove` — remove and destroy the semaphore set from the system.

## Examples

perl
use IPC::SysV qw(IPC_PRIVATE S_IRWXU IPC_CREAT IPC_NOWAIT);
use IPC::Semaphore;

# Create a semaphore set with 3 semaphores, all initialised to 0
my $sem = IPC::Semaphore->new(IPC_PRIVATE, 3, S_IRWXU | IPC_CREAT);
$sem->setall(0, 0, 0);

# Perform atomic operations: wait on sem 0, signal on sem 1
$sem->op(
    0, -1, IPC_NOWAIT,   # decrement sem 0, fail if would block
    1,  1, 0             # increment sem 1
);

# Get current values
my @vals = $sem->getall;
print "Semaphore values: @vals\n";

# Set value of sem 2 to 5
$sem->setval(2, 5);

# Examine stat
my $stat = $sem->stat;
print "Number of semaphores: $stat->nsems\n";

# Remove when done
$sem->remove;
## See Also

- [IPC::SysV](http://localhost/phpMan.php/perldoc/IPC%3A%3ASysV/markdown)
- [Class::Struct](http://localhost/phpMan.php/perldoc/Class%3A%3AStruct/markdown)
- [semget(2)](http://localhost/phpMan.php/man/semget/2/markdown)
- [semctl(2)](http://localhost/phpMan.php/man/semctl/2/markdown)
- [semop(2)](http://localhost/phpMan.php/man/semop/2/markdown)