SEMCTL(2)

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

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

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

DESCRIPTION
semctl() effectue l'opération de contrôle indiquée par cmd sur le jeu de sémaphores (ou sur le semno-ième sémaphore du jeu) identifié par semid. (Les sémaphores sont numérotés à partir de zéro.)

Cette fonction prend trois ou quatre arguments, selon la valeur de cmd. Lorsqu'il y en a quatre, le quatrième est de type : 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;  /* Tableau 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; /* Heure dernier semop */
    time_t          sem_ctime; /* Heure dernière modification */
    unsigned short  sem_nsems; /* N° du semaphore dans le jeu */
};

La structure ipc_perm est définie dans <sys/ipc.h> de la façon suivante (les champs en gras peuvent être configurés avec IPC_SET) :

struct ipc_perm {
    key_t key;            /* Clé fournie à semget(2) */
    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
    Écrire les valeurs de certains champs de la structure semid_ds pointée par arg.buf dans la structure de données noyau associée à ce 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émaphores, ou l'appelant doit être privilégié. L'argument semno est ignoré.

IPC_RMID
    Supprimer immédiatement le jeu de sémaphores en réveillant tous les processus bloqués dans l'appel semop(2) 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 des informations sur les paramètres et limites des sémaphores à l'échelle du système dans la structure pointée par arg.__buf. Cette structure est de type seminfo, défini 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é dans le noyau */
        int semmni;  /* Nombre maximal de jeux de sémaphores */
        int semmns;  /* Nombre maximal de sémaphores dans
                        tous les jeux de sémaphores */
        int semmnu;  /* Nombre maximal de structures undo à l'échelle
                        du système ; inutilisé dans le noyau */
        int semmsl;  /* Nombre maximal de sémaphores dans un jeu */
        int semopm;  /* Nombre maximal d'opérations pour semop(2) */
        int semume;  /* Nombre maximal d'entrées undo par
                        processus ; inutilisé dans le noyau */
        int semusz;  /* Taille de la structure sem_undo */
        int semvmx;  /* Valeur de sémaphore maximum */
        int semaem;  /* Valeur maximale pouvant être enregistrée pour
                        un ajustement de sémaphore (SEM_UNDO) */
    };
    Les paramètres semmsl, semmns, semopm et semmni peuvent être modifiés via /proc/sys/kernel/sem ; voir proc(5) pour plus de détails.

SEM_INFO (spécifique à Linux)
    Renvoyer une structure seminfo contenant les mêmes informations 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)
    Renvoyer 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 la table interne du noyau qui contient des informations sur tous les jeux de sémaphores du système.

GETALL
    Renvoyer la valeur semval (c'est-à-dire la valeur courante) de chaque sémaphore du jeu 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 du jeu (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 du jeu (c'est-à-dire le PID du processus ayant exécuté le dernier appel système semop(2) 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 du jeu 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 du jeu. (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 du jeu 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 entrées « undo » semop(2)) sont effacées de tous les processus pour les sémaphores modifiés. Si la nouvelle valeur du sémaphore permet des appels semop(2) bloqués dans d'autres processus de se poursuivre, ces processus en attente sont réveillés. 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 du jeu en mettant à jour le champ sem_ctime dans la structure semid_ds associée au jeu de sémaphores. Les entrées « undo » de tous les sémaphores modifiés sont effacées 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(2), ces derniers sont réveillés. Le processus appelant doit avoir des privilèges d'écriture sur le jeu de sémaphores.

VALEUR RENVOYÉE
En cas d'échec, semctl() 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
    Le plus grand indice d'une entrée utilisée dans la table interne du noyau contenant des informations sur tous les jeux de sémaphores. (Cette information peut ensuite être utilisée pour des opérations SEM_STAT répétées afin d'obtenir des 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émaphores dont l'indice a été fourni à semid.

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

ERREURS
En cas d'échec, errno prend l'une des valeurs suivantes : 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
    Le jeu de sémaphores a été supprimé.

EINVAL
    cmd ou semid a une valeur invalide. Ou bien, pour une opération SEM_STAT l'indice indiqué dans semid fait référence à une entrée de la table actuellement inutilisée.

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émaphores, 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 le jeu ou pour certains sémaphores) est inférieure à 0 ou supérieur à la valeur SEMVMX.

CONFORMITÉ
SVr4, POSIX.1-2001.

NOTES
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 de type short sous Linux 2.2 et sont devenus des long 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 antérieures 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.

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

TRADUCTION

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 23 juin 2008.

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.