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, ...);

semctl() 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, (dans un ensemble, les sémaphores sont numérotés à partir de zéro).

Cette fonction prend trois ou quatre arguments, selon cmd. Lorsqu’il y en a quatre, le quatrième a le type suivant : union semun. Le programme appelant doit définir cette union comme suit :

    union semun {
        int              val;    /* Valeur pour SETVAL */
        struct semid_ds *buf;    /* Tampon pour IPC_STAT, IPC_SET */
        unsigned short  *array;  /* Table  pour GETALL, SETALL */
        struct seminfo  *__buf;  /* Tampon pour IPC_INFO
                                    (Spécifique à Linux) */
    };

La structure de données semid_ds est définie dans <sys/sem.h> de la manière suivante :

    struct semid_ds {
        struct ipc_perm sem_perm;  /* Appartenance et permissions */
        time_t          sem_otime; /* Dernière heure semop */
        time_t          sem_ctime; /* Dernière heure de modification */
        unsigned short  sem_nsems; /* N° du semaphore dans le jeu */
    };

La structure ipc_perm est définie dans <sys/ipc.h> de la manière suivante (les champs mis en évidence peuvent être configurés avec IPC_SET) :

    struct ipc_perm {
        key_t key;            /* Clé fournie à semget() */
        uid_t uid;            /* UID effectif du propriétaire */
        gid_t gid;            /* GID effectif du propriétaire */
        uid_t cuid;           /* UID effectif du créateur */
        gid_t cgid;           /* GID effectif du créateur */
        unsigned short mode;  /* Permissions */
        unsigned short seq;   /* Nombre de séquences */
    };

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

IPC_STAT

Copier les informations de la structure de données noyau associé à semid dans la structure semid_ds pointée par arg.buf. L’argument semno est alors ignoré. Le processus appelant doit avoir la permission 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 données noyau associée au jeu de sémaphores, en mettant à jour son membre sem_ctime . Les membres suivants de la structure sont mis à jour : sem_perm.uid, sem_perm.gid et (les 9 bits de poids faible de) sem_perm.mode. L’UID effectif du processus appelant doit correspondre à celui du propriétaire (sem_perm.uid) ou celui du créateur (sem_perm.cuid) du jeu de sémaphore, ou l’appelant doit être privilégié. L’argument semno est ignoré.

IPC_RMID

Supprimer immédiatement l’ensemble de sémaphores en réveillant tous les processus bloqués dans l’appel semop() sur le jeu. Ils obtiendront un code d’erreur, et errno aura la valeur EIDRM. L’UID effectif du processus appelant doit être celui du créateur ou du propriétaire du jeu de sémaphores ou l’appelant doit être privilégié. L’argument semno est ignoré.

IPC_INFO (Spécifique à Linux)

Renvoyer l’information sur les paramètres et limites des sémaphores à l’échelle du système dans une structure pointée par arg.__buf. Cette structure est du type seminfo, définie dans <sys/sem.h> si la macro de test de fonctionnalité _GNU_SOURCE est définie :

  struct  seminfo {
      int semmap;  /* Nombre d’entrées dans la table des sémaphores ;
                      inutilisé */
      int semmni;  /* Nombre maximum de jeux de sémaphores */
      int semmns;  /* Nombre maximum de sémaphores dans
                      tous les jeux de sémaphores */
      int semmnu;  /* Nombre maximum de structure undo
                      à  l’échelle du système ; inutilisé */
      int semmsl;  /* Nombre maximum de sémaphores dans un jeu */
      int semopm;  /* Nombre maximum d’opérations pour semop() */
      int semume;  /* Nombre maximum d’entrées undo par
                      processus ; unuinutilisésed */
      int semusz;  /* taille de la structure sem_undo */
      int semvmx;  /* Valeur de sémaphore maximum */
      int semaem;  /* Valeur maximum qui puisse être enregistrée pour
                      un ajustement de sémaphore (SEM_UNDO) */
  };

Les réglages semmsl, semmns, semopm et semmni peuvent être modifiés via /proc/sys/kernel/sem ; voir proc(5) pour les détails.

SEM_INFO (Spécifique à Linux)

Renvoie une structure seminfo contenant la même information que pour IPC_INFO, excepté que les champs suivants sont renvoyés avec des informations sur les ressources système consommées par les sémaphores ; le champ semusz renvoie le nombre de jeux de sémaphores qui existent actuellement sur le système ; et le champ semaem renvoie le nombre total de sémaphores dans tous les jeux de sémaphores du système.

SEM_STAT (Spécifique à Linux)

Renvoie une structure semid_ds comme pour IPC_STAT. Toutefois, l’argument semid n’est pas un identifiant de sémaphore, mais plutôt un index dans un tableau interne du noyau qui contient les informations de tous les jeux de sémaphores du système.

GETALL

Renvoyer la valeur semval (c’est-à -dire la valeur courante) de chaque sémaphore de l’ensemble dans le tableau arg.array. L’argument semno est ignoré. Le processus appelant doit avoir la permission de lecture sur le jeu de sémaphores.

GETNCNT

Renvoyer la valeur de semncnt (c’est-à -dire le nombre de processus en attente d’une incrémentation de la valeur de ce sémaphore) pour le semno−ième sémaphore de l’ensemble (c’est-à -dire le nombre de processus en attente d’une incrémentation du champ semval du semno−ième sémaphore). Le processus appelant doit avoir la permission de lecture sur le jeu de sémaphores.

GETPID

Renvoyer la valeur de sempid pour le semno−ième sémaphore de l’ensemble (c.-à -d. le PID du processus ayant exécuté le dernier appel système semop() sur le semno−ième sémaphore). Le processus appelant doit avoir la permission 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 la permission de lecture sur le jeu de sémaphores.

GETZCNT

Renvoyer la valeur du champ semzcnt (c’est-à -dire le nombre de processus en attente d’une mise à zéro de la valeur du sémaphore) du semno−ième sémaphore de l’ensemble. (c’est-à -dire le nombre de processus attendant que le champ semval du semno−ième sémaphore revienne à 0). Le processus appelant doit avoir la permission 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 la permission 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. Les champs « undo » (voir semop(2)) de tous les sémaphores modifiés sont effacés dans tous les processus. Si les modifications apportées dans les compteurs des sémaphores permettent de débloquer d’autres processus en attente sur semop(), ces derniers sont réveillés. 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.

IPC_INFO

L’index de la plus grande entrée utilisée dans le tableau interne du noyau enregistrant les informations sur tous les jeux de sémaphores. (Cette opération peut être utilisée avec des opérations SEM_STAT répétées pour obtenir les informations sur tous les jeux de sémaphores du système.)

SEM_INFO

Comme pour IPC_INFO.

SEM_STAT

L’identifiant du jeu de sémaphore dont l’index a été fourni à semid.

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

EACCES L’argument cmd a l’une des valeurs suivantes GETALL, GETPID, GETVAL, GETNCNT, GETZCNT, IPC_STAT, SEM_STAT, SETALL ou SETVAL et le processus appelant n’a pas les permissions nécessaires sur le jeu de sémaphore et n’a pas la capacité CAP_IPC_OWNER.

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. Ou, pour une opération SEM_STAT la valeur d’index spécifiée dans semid fait référence à un emplacement du tableau qui est actuellement inutilisé.

EPERM

L’argument cmd réclame les commandes IPC_SET ou IPC_RMID mais l’UID effectif du processus appelant n’est pas le créateur (comme dans sem_perm.cuid) ou le propriétaire (comme dans sem_perm.uid) du jeu de sémaphore, et le processus n’a pas la capacité CAP_SYS_ADMIN.

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 opérations 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.)

Dans certaines versions précédentes de la glibc, l’union semun était définie dans <sys/sem.h>, mais POSIX.1-2001 demande que l’appelant définisse cette union. Dans les versions de la glibc où cette union n’est pas définie, la macro _SEM_SEMUN_UNDEFINED est définie dans <sys/sem.h>.

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, 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, POSIX.1-2001.

ipc(2), semget(2), semop(2), capabilities(7), sem_overview(7), svipc(7)

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 15 octobre 1996 et révisée le 14 août 2006.

L’équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 2 semctl ». N’hésitez pas à signaler à l’auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.