semget Subroutine

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 is 4096 for operating system releases before AIX® 4.3.2, 131072 for releases AIX 4.3.2 through AIX 5.2, and 1048576 for release AIX 5.3 and later.
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.

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.