semctl - Opérations de contrôle sur les sémaphores.

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>

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

Cette fonction effectue l'opération de contrôle indiquée par cmd sur l'ensemble de sémaphores (ou sur le semno-ième sémaphore de l'ensemble) identifié par semid, (les sémaphores sont numérotés à partir de zéro).
Cette fonction prend trois ou quatre arguments. Lorsqu'il y en a quatre, l'appel est semctl(semid,semno,cmd,arg); où l'argument arg est de type union semun défini ainsi :

#if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED)
/* l'union semun est définie par l'inclusion de <sys/sem.h> */
#else
/* d'après X/OPEN il faut la définir nous-mêmes */
union semun {
      int val;                  /* valeur pour SETVAL */
      struct semid_ds *buf;     /* buffer pour IPC_STAT, IPC_SET */
      unsigned short *array;    /* table  pour GETALL, SETALL */
                                /* Spécificité Linux : */
      struct seminfo *__buf;    /* buffer pour IPC_INFO */
};
#endif

Les valeurs autorisées pour l'opération cmd sont :

IPC_STAT

copier dans la structure pointée par arg.buf la structure de données concernant l'ensemble de sémaphores. L'argument semno est alors ignoré. Le processus appelant doit avoir des privilèges de lecture sur le jeu de sémaphores

IPC_SET

Fixer la valeur de certains champs de la structure semid_ds pointée par arg.buf dans la structure de contrôle de l'ensemble de sémaphores, en mettant à jour son membre sem_ctime. Les champs de la structure struct semid_ds fournie dans arg.buf et copiés dans la structure de l'ensemble sont :

        sem_perm.uid
        sem_perm.gid
        sem_perm.mode   /* 9 bits poids faibles*/

L'UID effectif du processus appelant doit être soit celui du Super-User soit celui du créateur ou du propriétaire du jeu de sémaphores. L'argument semno est ignoré.

IPC_RMID

Supprimer immédiatement l'ensemble de sémaphores en réveillant tous les processus en attente. Ils obtiendront un code d'erreur, et errno aura la valeur EIDRM. L'UID effectif du processus appelant doit être soit celui du Super-User soit celui du créateur ou du propriétaire du jeu de sémaphores. L'argument semno est ignoré.

GETALL

Renvoyer la valeur semval de chaque sémaphore de l'ensemble dans le tableau arg.array. L'argument semno est ignoré. Le processus appelant doit avoir des privilèges de lecture sur le jeu de sémaphores.

GETNCNT

Renvoyer la valeur de semncnt pour le semno-ième sémaphore de l'ensemble (i.e. le nombre de processus en attente d'une incrémentation du champ semval du semno-ième sémaphore). Le processus appelant doit avoir des privilèges de lecture sur le jeu de sémaphores.

GETPID

Renvoyer la valeur de sempid pour le semno-ième sémaphore de l'ensemble (i.e. le PID du processus ayant exécute le dernier appel système semop sur le semno-ième sémaphore). Le processus appelant doit avoir des privilèges de lecture sur le jeu de sémaphores.

GETVAL

Renvoyer la valeur du champ semval du semno-ième sémaphore de l'ensemble Le processus appelant doit avoir des privilèges de lecture sur le jeu de sémaphores.

GETZCNT

Renvoyer la valeur du champ semzcnt du semno-ième sémaphore de l'ensemble. (i.e. le nombre de processus attendant que le champ semval du semno-ième sémaphore revienne à 0). Le processus appelant doit avoir des privilèges de lecture sur le jeu de sémaphores.

SETALL

Positionner le champ semval de tous les sémaphores de l'ensemble en utilisant le tableau arg.array et en mettant à jour le champ sem_ctime de la structure semid_ds de contrôle du jeu de sémaphores. Les processus en attente sont réveillés si semval devient 0 ou augmente. L'argument semno est ignoré. Le processus appelant doit avoir des privilèges d'écriture sur le jeu de sémaphores.

SETVAL

Placer la valeur arg.val dans le champ semval du semno-ième sémaphore de l'ensemble en mettant à jour le champ sem_ctime dans la structure semid_ds associée au jeu de sémaphores. Le processus appelant doit avoir des privilèges d'écriture sur le jeu de sémaphores Les processus en attente sont réveillés si semval devient 0 ou augmente.

En cas d'échec, l'appel-système renvoie -1 et errno contient le code d'erreur. Autrement, l'appel-système renvoie une valeur non-négative dépendant de l'argument cmd :

GETNCNT

la valeur de semncnt.

GETPID

La valeur sempid.

GETVAL

La valeur semval.

GETZCNT

La valeur semzcnt.

Toutes les autres commandes cmd renvoient zéro en cas de réussite.

EACCES Le processus appelant n'a pas les privilèges nécessaires pour exécuter la commande cmd.

EFAULT

arg.buf ou arg.array pointent en dehors de l'espace d'adressage accessible.

EIDRM

L'ensemble de sémaphores a été supprimé.

EINVAL

cmd ou semid a une valeur illégale.

EPERM

L'argument cmd réclame les commandes IPC_SET ou IPC_RMID mais l'UID effectif du processus appelant n'a pas les privilèges adéquats.

ERANGE

l'argument cmd réclame les commandes SETALL ou SETVAL et la valeur de semval (pour l'ensemble ou pour certains sémaphores) est inférieure à 0 ou supérieur à la valeur SEMVMX.

Les appels-système IPC_INFO, SEM_STAT et SEM_INFO sont utilisés par le programme ipcs(8) pour fournir des informations sur les ressources allouées. Ceci peut changer dans le futur, en utilisant l'interface d'un système de fichiers proc.
Divers champs de la struct semid_ds étaient des shorts sous Linux 2.2 et sont devenus longs sous Linux 2.4. Pour en tirer parti, une recompilation sous GlibC 2.1.91 ou ultérieure doit suffire. (Le noyau distingue les anciens et nouveaux appels par un drapeau IPC_64 dans cmd.)
La limite suivante influe sur l'appel-système semctl :

SEMVMX

Valeur maximale pour semval dépendant de l'implémentation (généralement 32767).

Pour améliorer la portabilité, il vaut mieux invoquer toujours semctl avec quatre arguments. Sous Linux, la fonction semctl n'est pas un véritable appel-système, mais est implémentée au moyen de l'appel-système commun ipc(2).

SVr4, SVID. SVr4 documente des conditions d'erreurs supplémentaires EINVAL et EOVERFLOW.

ipc(2), semget(2), semop(2), ipc(5)

Christophe Blaess, 1996-2003.