semget Subroutine

Edit online

Purpose

Gets a set of semaphores.

Library

Standard C Library (libc.a)

Syntax

#include <sys/sem.h>
int semget (Key, NumberOfSemaphores, SemaphoreFlag)
key_t  Key;
int  NumberOfSemaphores,  SemaphoreFlag;

Description

The semget subroutine returns the semaphore identifier associated with the Key parameter value.

The semget subroutine creates a data structure for the semaphore ID and an array containing the NumberOfSemaphores parameter semaphores if one of the following conditions is true:

  • The Key parameter is equal to the IPC_PRIVATE operation.
  • The Key parameter does not already have a semaphore identifier associated with it, and the IPC_CREAT value is set.

Upon creation, the data structure associated with the new semaphore identifier is initialized as follows:

  • The sem_perm.cuid and sem_perm.uid fields are set equal to the effective user ID of the calling process.
  • The sem_perm.cgid and sem_perm.gid fields are set equal to the effective group ID of the calling process.
  • The low-order 9 bits of the sem_perm.mode field are set equal to the low-order 9 bits of the SemaphoreFlag parameter.
  • The sem_nsems field is set equal to the value of the NumberOfSemaphores parameter.
  • The sem_otime field is set equal to 0 and the sem_ctime field is set equal to the current time.

The data structure associated with each semaphore in the set is not initialized. The semctl (semctl Subroutine) subroutine (with the Command parameter values SETVAL or SETALL) can be used to initialize each semaphore.

If the Key parameter value is not IPC_PRIVATE, the IPC_EXCL value is not set, and a semaphore identifier already exists for the specified Key parameter, the value of the NumberOfSemaphores parameter specifies the number of semaphores that the current process needs.

If the NumberOfSemaphores parameter has a value of 0, any number of semaphores is acceptable. If the NumberOfSemaphores parameter is not 0, the semget subroutine is unsuccessful if the set contains fewer than the value of the NumberOfSemaphores parameter.

The following limits apply to semaphores:

  • Maximum number of semaphore IDs 1048576.
  • Maximum number of semaphores per ID is 65,535.
  • Maximum number of operations per call by the semop subroutine is 1024.
  • Maximum number of undo entries per procedure is 1024.
  • Maximum semaphore value is 32,767.
  • Maximum adjust-on-exit value is 16,384.

Parameters

Item Description
Key Specifies either the IPC_PRIVATE value or an IPC key constructed by the ftok subroutine (or a similar algorithm).
NumberOfSemaphores Specifies the number of semaphores in the set.
SemaphoreFlag Constructed by logically ORing one or more of the following values:
IPC_CREAT
Creates the data structure if it does not already exist.
IPC_EXCL
Causes the semget subroutine to fail if the IPC_CREAT value is also set and the data structure already exists.
S_IRUSR
Permits the process that owns the data structure to read it.
S_IWUSR
Permits the process that owns the data structure to modify it.
S_IRGRP
Permits the group associated with the data structure to read it.
S_IWGRP
Permits the group associated with the data structure to modify it.
S_IROTH
Permits others to read the data structure.
S_IWOTH
Permits others to modify the data structure.

Values that begin with the S_I prefix are defined in the sys/mode.h file and are a subset of the access permissions that apply to files.

Return Values

Upon successful completion, the semget subroutine returns a semaphore identifier. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The semget subroutine is unsuccessful if one or more of the following conditions is true:

Item Description
EACCES A semaphore identifier exists for the Key parameter but operation permission, as specified by the low-order 9 bits of the SemaphoreFlag parameter, is not granted.
EINVAL A semaphore identifier does not exist and the NumberOfSemaphores parameter is less than or equal to a value of 0, or greater than the system-imposed value.
EINVAL A semaphore identifier exists for the Key parameter, but the number of semaphores in the set associated with it is less than the value of the NumberOfSemaphores parameter and the NumberOfSemaphores parameter is not equal to 0.
ENOENT A semaphore identifier does not exist for the Key parameter and the IPC_CREAT value is not set.
ENOSPC Creating a semaphore identifier would exceed the maximum number of identifiers allowed systemwide.
EEXIST A semaphore identifier exists for the Key parameter, but both the IPC_CREAT and IPC_EXCL values are set.
ENOMEM There is not enough memory to complete the operation.