Sous-routine semctl

Editer en ligne

Objectif

Contrôle les opérations de sémaphore.

Bibliothèque

Bibliothèque C standard (libc.a)

Syntaxe

#include <sys/sem.h>

int semctl (SemaphoreID, SemaphoreNumber, Command, arg)
OR
int semctl (SemaphoreID, SemaphoreNumber, Command)

int  SemaphoreID;
int  SemaphoreNumber;
int  Command;
union semun {
         int val;
         struct semid_ds *buf;
         unsigned short *array;
} arg;
Si le quatrième argument est requis pour l'opération demandée, il doit être de type union semun et explicitement déclaré comme indiqué ci-dessus.

Descriptif

La sous-routine semctl effectue diverses opérations de contrôle de sémaphore, comme indiqué par le paramètre Command . Pour plus d'informations sur les limites de sémaphore, voir: Limites de communication interprocessus.

Paramètres

SemaphoreID
Indique l'identificateur de sémaphore.
SemaphoreNumber
Indique le numéro de sémaphore.
arg.val
Indique la valeur du sémaphore pour la commande SETVAL .
arg.buf
Indique la mémoire tampon pour les informations de statut des commandes IPC_STAT et IPC_SET .
arg.array
Indique les valeurs de tous les sémaphores d'un ensemble pour les commandes GETALL et SETALL .
Commande
Indique les opérations de contrôle de sémaphore.

Les valeurs de paramètre Command suivantes sont exécutées par rapport au sémaphore spécifié par les paramètres SemaphoreID et SemaphoreNumber . Ces opérations extraient et définissent les valeurs d'une structure sem , qui est définie dans le fichier sys/sem.h .

GETVAL
Renvoie la valeur semval , si le processus en cours dispose de droits de lecture.
SETVAL
Définit la valeur semval sur la valeur spécifiée par le paramètre arg.val , si le processus en cours dispose de droits d'accès en écriture. Lorsque ce paramètre Commande est exécuté avec succès, la valeur semadj correspondant au sémaphore spécifié est effacée dans tous les processus.
GETPID
Renvoie la valeur dusempidsi le processus en cours dispose de droits d'accès en lecture.
GETNCNT
Renvoie la valeur dusemncntsi le processus en cours dispose de droits d'accès en lecture.
GETZCNT
Renvoie la valeur dusemzcntsi le processus en cours dispose de droits d'accès en lecture.

Les valeurs de paramètre Command suivantes renvoient et définissent chaque valeur semval dans l'ensemble de sémaphores. Ces opérations extraient et définissent les valeurs d'une structure sem , qui est définie dans le fichier sys/sem.h .

GETALL
Stocke les valeurs semvals dans le tableau désigné par le paramètre arg.array , si le processus en cours dispose de droits en lecture.
SETALL
Définit des valeurs semvals en fonction du tableau désigné par le paramètre arg.array , si le processus en cours dispose de droits d'accès en écriture. Lorsque ce paramètre Commande est exécuté avec succès, la valeur semadj correspondant à chaque sémaphore spécifié est effacée dans tous les processus.

Les valeurs de paramètre Commandes suivantes obtiennent et définissent les valeurs d'une structure semid_ds , définie dans le fichier sys/sem.h . Ces opérations extraient et définissent les valeurs d'une structure sem , qui est définie dans le fichier sys/sem.h .

IPC_STAT
Obtient des informations de statut sur le sémaphore identifié par le paramètre SemaphoreID . Ces informations sont stockées dans la zone indiquée par le paramètre arg.buf .
IPC_SET
Définit les ID d'utilisateur et de groupe propriétaires, ainsi que les droits d'accès pour l'ensemble de sémaphores associés au paramètre SemaphoreID . L'opération IPC_SET utilise comme entrée les valeurs trouvées dans la structure de paramètre arg.buf .
IPC_SET définit les zones suivantes:
Article Descriptif
sem_perm.uid ID utilisateur du propriétaire
sem_perm.gid ID de groupe du propriétaire
sem_perm.mode Bits d'autorisation uniquement
sem_perm.cuid ID utilisateur du créateur

IPC_SET ne peut être exécuté que par un processus disposant de droits d'utilisateur root ou d'un ID utilisateur effectif égal à la valeur desem_perm.uidousem_perm.cuiddans la structure de données associée au paramètre SemaphoreID .

IPC_RMID
Supprime l'identificateur de sémaphore spécifié par le paramètre SemaphoreID du système et détruit l'ensemble de sémaphores et de structures de données qui lui sont associés. Ce paramètre Commande ne peut être exécuté que par un processus disposant des droits d'accès de l'utilisateur root ou d'un ID utilisateur effectif égal à la valeur du paramètresem_perm.uidousem_perm.cuiddans la structure de données associée au paramètre SemaphoreID .

Valeurs renvoyées

Une fois l'opération terminée, la valeur renvoyée dépend du paramètre Command comme suit:

Commande Valeur renvoyée
GETVAL Renvoie la valeur dusemval:NONE.
GETPID Renvoie la valeur dusempid:NONE.
GETNCNT Renvoie la valeur dusemncnt:NONE.
GETZCNT Renvoie la valeur dusemzcnt:NONE.
Tous les autres Renvoie la valeur 0.

Si la sous-routine semctl échoue, la valeur -1 est renvoyée et la variable globale errno est définie pour indiquer l'erreur.

Codes d'erreur

La sous-routine semctl échoue si l'une des conditions suivantes est vérifiée:

Article Descriptif
EINVAL Le paramètre SemaphoreID n'est pas un identificateur de sémaphore valide.
EINVAL Le paramètre SemaphoreNumber est inférieur à 0 ou supérieur ou égal à la valeur sem_nsems .
EINVAL Le paramètre Commande n'est pas une commande valide.
EACCES L'autorisation du processus appelant est refusée pour l'opération spécifiée.
ERANGE Le paramètre Commande est égal à la valeur SETVAL ou SETALL et la valeur à laquelle la valeur semval doit être définie est supérieure à la valeur maximale imposée par le système.
EPERM Le paramètre Command est égal à la valeur IPC_RMID ou IPC_SET et le processus appelant ne dispose pas des droits de superutilisateur ou d'un ID utilisateur effectif égal à la valeur de lasem_perm.uidousem_perm.cuiddans la structure de données associée au paramètre SemaphoreID .
EFAULT Le paramètre arg.buf ou arg.array pointe hors de l'espace adresse alloué du processus.
ENOMEM Le système ne dispose pas de suffisamment de mémoire pour exécuter la sous-routine.