Manpages

NOM

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

SYNOPSIS

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

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

DESCRIPTION

Cette fonction effectue l’opération de contrôle indiquée par cmd sur l’ensemble de sémaphores System V (ou sur le semnum-ième sémaphore de l’ensemble) identifié par semid. (Les sémaphores sont numérotés à partir de zéro.)

La fonction a trois ou quatre arguments, selon la valeur de cmd. Quand il y en a quatre, le quatrième est de type union semun. Le programme appelant doit définir cette union de la façon suivante :

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 semid_ds est définie dans <sys/sem.h> comme suit :

struct semid_ds {
    struct ipc_perm sem_perm;   /* Permissions d’accès */
    time_t          sem_otime;  /* Heure dernier semop() */
    time_t          sem_ctime;  /* Heure dernier changement */
    unsigned long   sem_nsems;  /* Nombre de sémaphores dans l’ensemble */
};

La structure ipc_perm est définie de la façon suivante (les champs en gras peuvent être modifiés en utilisant 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; /* Numéro de séquence */
};

Les valeurs autorisées pour cmd sont :

IPC_STAT

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

IPC_SET

Écrire les valeurs de certains des membres de la structure semid_ds pointée par arg.buf dans la structure de données du noyau associée à cet ensemble de sémaphores, en mettant à jour son champ sem_ctime. Les membres suivants de la structure sont mis à jour : sem_perm.uid, sem_perm.gid et les neuf bits de poids faible de sem_perm.mode. L’UID effectif du processus appelant doit être celui du propriétaire (sem_perm.uid) ou du créateur (sem_perm.cuid) de l’ensemble de sémaphores, ou l’appelant doit être privilégié. L’argument semnum est ignoré.

IPC_RMID

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

IPC_INFO (spécifique à Linux)

Renvoyer des informations sur les limites et paramètres du système concernant les sémaphores dans la structure pointée par arg.__buf. Cette structure est de type seminfo, défini dans <sys/sem.h> si la macro _GNU_SOURCE est définie :

struct  seminfo {
    int semmap;  /* Nombre d’entrées dans la table de sémaphores ;
                    pas utilisé par le noyau */
    int semmni;  /* Nombre maximal d’ensembles de sémaphores */
    int semmns;  /* Nombre maximal de sémaphores dans tous les
                    ensembles de sémaphores */
    int semmnu;  /* Nombre maximal de structures « undo »
                    sur le système ; pas utilisé par le noyau */
    int semmsl;  /* Nombre maximal de sémaphores dans un ensemble */
    int semopm;  /* Nombre maximal d’opérations pour semop(2) */
    int semume;  /* Nombre maximal d’entrées « undo » par
                    processus ; pas utilisé par le noyau */
    int semusz;  /* Taille de struct sem_undo */
    int semvmx;  /* Valeur maximale d’un sémaphore */
    int semaem;  /* Valeur maximale pouvant être enregistrée pour
                    la mise à jour d’un sémaphore (SEM_UNDO) */
};

Les paramètres semmsl, semmns, semopm et semmni peuvent être modifiés via /proc/sys/kernel/sem ; consultez 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, sauf les champs suivants qui sont remplis avec des informations sur les ressources système actuellement utilisées par les sémaphores : le champ semusz renvoie le nombre d’ensembles de sémaphores existants sur le système, et le champ semaem renvoie le nombre total de sémaphores dans tous les ensembles de sémaphores du système.

SEM_STAT (spécifique à Linux)

Renvoyer une structure semid_ds comme pour IPC_STAT. Cependant, l’argument semid n’est pas un identifiant de sémaphore, mais un index dans la table interne du noyau qui contient des informations sur tous les ensembles de sémaphores du système.

SEM_STAT_ANY (Linux-specific, since Linux 4.17)

Return a seminfo structure containing the same information as for SEM_STAT. However, sem_perm.mode is not checked for read access for semid meaning that any user can employ this operation (just as any user may read /proc/sysvipc/sem to obtain the same information).

GETALL

Renvoyer la valeur semval de chaque sémaphore de l’ensemble dans le tableau arg.array. L’argument semnum 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 semnum-ième sémaphore de l’ensemble (c’est-à-dire le nombre de processus attendant pour une augmentation de semval du semnum-ième sémaphore de l’ensemble). Le processus appelant doit avoir des privilèges de lecture sur le jeu de sémaphores.

GETPID

Renvoyer la valeur de sempid pour le semnum-ième sémaphore de l’ensemble. Il s’agit du PID du processus ayant exécuté la dernière opération sur ce sémaphore (voir les NOTES). Le processus appelant doit avoir des privilèges de lecture sur le jeu de sémaphores.

GETVAL

Renvoyer la valeur du champ semval du semnum-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 semnum-ième sémaphore de l’ensemble (c’est-à-dire le nombre de processus attendant que le champ semval du semnum-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 entrées « undo » (consultez 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 sont réveillés. L’argument semnum 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 semnum-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 entrées « undo » 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 sont réveillés. Le processus appelant doit avoir des privilèges d’écriture sur le jeu de sémaphores.

VALEUR DE RETOUR

semctl() renvoie -1 s’il échoue auquel cas 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

the index of the highest used entry in the kernel’s internal array recording information about all semaphore sets. (This information can be used with repeated SEM_STAT or SEM_STAT_ANY operations to obtain information about all semaphore sets on the system.)

SEM_INFO

Comme pour IPC_INFO.

SEM_STAT

L’identifiant de l’ensemble de sémaphores dont l’indice était donné dans semid.

SEM_STAT_ANY

as for SEM_STAT.

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

The argument cmd has one of the values GETALL, GETPID, GETVAL, GETNCNT, GETZCNT, IPC_STAT, SEM_STAT, SEM_STAT_ANY, SETALL, or SETVAL and the calling process does not have the required permissions on the semaphore set and does not have the CAP_IPC_OWNER capability in the user namespace that governs its IPC namespace.

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

Valeur de cmd ou semid non valable. Ou bien, pour une opération SEM_STAT, l’indice indiqué dans semid référence une entrée actuellement inutilisée de la table.

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

CONFORMITÉ

POSIX.1-2001, POSIX.1-2008, SVr4.

POSIX.1 spécifie le champ sem_nsems de la structure semid_ds comme de type unsigned short, ce qui est suivi par de nombreux systèmes. Ce champ était défini ainsi dans Linux 2.2 et dans les versions précédentes. Depuis Linux 2.4, ce champ est de type unsigned long.

NOTES

L’inclusion de <sys/types.h> et <sys/ipc.h> n’est pas nécessaire sous Linux et n’est exigée par aucune version de POSIX. Cependant, certaines implémentations anciennes nécessitent l’inclusion de ces fichiers d’en-tête, et le SVID documente aussi leur inclusion. Les applications ayant pour but d’être portables pourraient inclure ces fichiers d’en-tête.

Les appels système IPC_INFO, SEM_STAT et SEM_INFO sont utilisés par le programme ipcs(1) pour fournir des informations sur les ressources allouées. Cela 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 glibc, l’union semun était définie dans <sys/sem.h>, mais POSIX.1 documente que l’appelant doit définir cette union. Dans les versions de 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.

La valeur sempid
POSIX.1 définit sempid comme l’« ID du processus de la dernière opération » sur un sémaphore, et note explicitement que cette valeur est réglée par un appel semop réussi, avec l’implication qu’aucune autre interface n’affecte la valeur sempid.

Bien que certaines implémentations respectent le comportement défini dans POSIX.1, d’autres ne le font pas (le tort revient ici probablement à POSIX.1 qui n’a pas réussi à englober tous les comportements implémentés existants). Diverses autres implémentations mettent également à jour sempid pour d’autres opérations qui mettent à jour la valeur d’un sémaphore : les opérations SETVAL et SETALL, ainsi que les ajustements de sémaphores exécutés en fin de processus du fait de l’utilisation de l’option SEM_UNDO (voir semop(2)).

Linux modifie également sempid pour les opérations SETVAL et les ajustements de sémaphores. Cependant, de façon plutôt incohérente, Linux ne mettait pas à jour sempid pour les opérations SETALL jusqu’à la version 4.5 incluse. Cela a été corrigé avec la version 4.6.

VOIR AUSSI

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

COLOPHON

Cette page fait partie de la publication 5.05 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l’adresse https://www.kernel.org/doc/man-pages/.

TRADUCTION

La traduction française de cette page de manuel a été créée par Christophe Blaess <http://www.blaess.fr/christophe/>;, Stéphan Rafin <stephan.rafin [AT] laposte.net>, Thierry Vignaud <tvignaud [AT] mandriva.com>, François Micaux, Alain Portal <aportal [AT] univ-montp2.fr>, Jean-Philippe Guérard <fevrier [AT] tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon [AT] wanadoo.fr>, Julien Cristau <jcristau [AT] debian.org>, Thomas Huriaux <thomas.huriaux [AT] gmail.com>, Nicolas François <nicolas.francois [AT] centraliens.net>, Florentin Duneau <fduneau [AT] gmail.com>, Simon Paillard <simon.paillard [AT] resel.fr>, Denis Barbier <barbier [AT] debian.org> et David Prévot <david [AT] tilapin.org>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n’y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à <debian-l10n-french [AT] lists.org>.