semctl, semctl64 - Semaphor-Steueroperationen anwenden

Definition

#include <sys/sem.h>

int semctl(int semid, int semnum, int cmd, ...);

CRTE111A30

int semctl64(int semid, int semnum, int cmd, ...); (Ende)

Beschreibung

semctl() bietet eine Vielzahl von Operationen für die Semaphor-Steuerung.

Mit cmd werden die im Folgenden aufgeführten Semaphor-Steueroperationen angegeben, mit semid und semnum das Semaphor, für das die angegebene Operation ausgeführt werden soll. Die für die jeweilige Operation erforderlichen Zugriffsrechte werden bei den entsprechenden Kommandos angegeben (siehe auch Abschnittt "Interprozesskommunikation“).

Der Typ des vierten Argumentes ist abhängig vom Wert von cmd.

Die Funktion semctl64() verhält sich wie die Funktion semctl(), außer dass sie für die cmd-Werte IPC_STAT und IPC_SET eine semid_ds64 Datenstruktur anstelle einer  semid_ds Datenstruktur verwendet und daher auch über den 19.1.2038 03:14:07 Uhr UTC hinaus korrekt funktioniert.

Die Struktur semid_ds enthält die folgenden Elemente:

struct ipc_perm sem_perm;       /* operation permission struct */
struct sem      *sem_base;      /* ptr to first semaphore in set */
ushort_t        sem_nsems;      /* # of semaphores in set */
time_t          sem_otime;      /* last semop time */
time_t          sem_ctime;      /* last change time */

Die Elemente der Struktur semid_ds 64 sind wie die von semid_ds definiert, mit Ausnahme folgender Komponenten:

time64_t        sem_otime;
time64_t        sem_ctime;

Die symbolischen Namen für die Werte von cmd sind in der Include-Datei sys/sem.h definiert:

GETVAL	Wert von semval liefern (siehe auch sys/sem.h). Leserecht erforderlich.
SETVAL	Wert von semval auf den Wert des vierten Arguments vom Typ int setzen. Nach erfolgreicher Durchführung von cmd ist der dem angegebenen Semaphor entsprechende semadj-Wert in allen Prozessen gelöscht. Änderungsberechtigung erforderlich (siehe auch Abschnitt "Interprozesskommunikation“).
GETPID	Wert von sempid liefern. Leserecht erforderlich.
GETNCNT	Wert von semncnt liefern. Leserecht erforderlich.
GETZCNT	Wert von semzcnt liefern. Leserecht erforderlich.

Folgende Kommandos wirken auf jeden semval aus der Menge der zulässigen Semaphore:

GETALL	Wert von semval zurückgeben und in den Vektor eintragen, auf den arg.array zeigt. Leserecht erforderlich.
SETALL	semval auf den Wert des Vektors vom Typ unsigned short setzen, auf das das vierte Argument von semctl() zeigt. Nach erfolgreicher Ausführung dieses Kommandos sind die den angegebenen Semaphoren entsprechenden semadj-Werte in allen Prozessen gelöscht. Änderungsberechtigung erforderlich.

Folgende Kommandos sind außerdem verfügbar:

IPC_STAT	den aktuellen Wert jedes Elements der semid_ds bzw. semid_ds64 Datenstruktur, die zu semid gehört, in die semid_ds bzw. semid_ds64 Struktur schreiben, auf die das vierte Argument von semctl() zeigt.
IPC_SET	den Wert der folgenden Elemente der semid_ds bzw. semid_ds64 Datenstruktur, die zu semid gehört, auf den entsprechenden Wert setzen, der in der semid_ds bzw. semid_ds64 Struktur gefunden wurde, auf die das vierte Argument von semctl() zeigt: sem_perm.uid sem_perm.gid sem_perm.mode /* nur 9 niederwertige Bits */ Dieses Kommando kann nur von einem Prozess ausgeführt werden, dessen effektive Benutzernummer die eines Prozesses mit Sonderrechten ist oder mit sem_perm.cuid oder sem_perm.uid in der semid zugeordneten Datenstruktur übereinstimmt.
IPC_RMID	Die mit semid angegebene Semaphorkennzahl im System sowie die Semaphorenmenge samt zugeordneter Datenstruktur löschen. Dieses Kommando kann nur von einem Prozess ausgeführt werden, dessen effektive Benutzernummer die eines Prozesses mit Sonderrechten ist oder mit sem_perm.cuid oder sem_perm.uid in der semid zugeordneten Datenstruktur übereinstimmt.

Returnwert

Bei Erfolg liefern semctl() und semctl64() je nach cmd-Wert einen der folgenden Returnwerte:

Wert von semval

wenn für cmd GETVAL angegeben wurde.

Wert von sempid

wenn für cmd GETPID angegeben wurde.

Wert von semcnt

wenn für cmd GETCNT angegeben wurde.

Wert von semzcnt

wenn für cmd GETZCNT angegeben wurde.

0

wenn andere cmd-Werte angegeben wurden.

-1

bei Fehler. errno wird gesetzt, um den Fehler anzuzeigen.

Fehler

semctl() und semctl64() schlagen fehl, wenn gilt: 

 

EACCES

Der aufrufende Prozess hat für das auszuführende Kommando nicht die erforderliche Zugriffsrecht (sieh Abschnitt "Interprozesskommunikation“).

 

Erweiterung

 

EFAULT

msgp verweist auf eine unzulässige Adresse. (Ende)

 

EINVAL

semid ist keine gültige Semaphorkennzahl, semnum hat einen Wert kleiner 0 oder größer sem_nsems oder cmd ist kein gültiges Kommando.

EPERM

cmd ist gleich IPC_RMID oder IPC_SET, die effektive Benutzernummer des aufrufenden Prozesses ist nicht die eines Prozesses mit Sonderrechten und stimmt nicht mit sem_perm.cuid oder sem_perm.uid in der semid zugeordneten Datenstruktur überein.

ERANGE

cmd ist gleich SETVAL oder SETALL und der Wert, auf den semval gesetzt werden soll, ist größer als der im System zulässige Höchstwert.

semctl() schlägt fehl, wenn gilt:

Erweiterung

 

EOVERFLOW

cmd ist gleich IPC_STAT  und ein Zeitstempel ist zu groß für eine time-t Komponente (dies wird nach dem 19.1.2038 03:14:07 Uhr UTC der Fall sein). (Ende)

semctl 64() schlägt fehl, wenn gilt:

 

EINVAL

POSIX-BC Korrekturstand < A47.

Hinweise

Das vierte Argument im Abschnitt „Syntax“ ist im XPG4 mit ... gekennzeichnet, um einen Widerspruch zum ISO C-Standard zu vermeiden. Der vierte Parameter kann vom Anwendungsprogrammierer wie folgt definiert werden:

union semun 
{  int val;
   struct semid_ds *buf;
   unsigned short *array;
} arg;

Siehe auch

auch semget(), semop(), sys/sem.h, Abschnitt "Interprozesskommunikation“ .