.\" -*- coding: UTF-8 -*-
'\" t
.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl>
.\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl>
.\" Modified 20 Dec 2001, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Modified 21 Dec 2001, aeb
.\" Modified 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Added notes on CAP_IPC_OWNER requirement
.\" Modified 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Language and formatting clean-ups
.\" Rewrote semun text
.\" Added semid_ds and ipc_perm structure definitions
.\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions.
.\" 2018-03-20, dbueso: Added SEM_STAT_ANY description.
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH semctl 2 "15 décembre 2022" "Pages du manuel de Linux 6.03"
.SH NOM
semctl \- Opérations de contrôle sur les sémaphores System\ V
.SH BIBLIOTHÈQUE
Bibliothèque C standard (\fIlibc\fP, \fI\-lc\fP)
.SH SYNOPSIS
.nf
\fB#include <sys/sem.h>\fP
.PP
\fBint semctl(int \fP\fIsemid\fP\fB, int \fP\fIsemnum\fP\fB, int \fP\fIcmd\fP\fB, ...);\fP
.fi
.SH DESCRIPTION
Cette fonction effectue l'opération de contrôle indiquée par \fIcmd\fP sur
l'ensemble de sémaphores System\ V (ou sur le \fIsemnum\fP\-ième sémaphore de
l'ensemble) identifié par \fIsemid\fP. (Les sémaphores sont numérotés à partir
de zéro.)
.PP
La fonction a trois ou quatre arguments, selon la valeur de \fIcmd\fP. Quand il
y en a quatre, le quatrième est de type \fIunion semun\fP. Le \fIprogramme appelant\fP doit définir cette union de la façon suivante\ :
.PP
.in +4n
.EX
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) */
};
.EE
.in
.PP
La structure \fIsemid_ds\fP est définie dans \fI<sys/sem.h>\fP comme
suit\ :
.PP
.in +4n
.EX
struct semid_ds {
struct ipc_perm sem_perm; /* Permissions d'accès */
time_t sem_otime; /* Heure dernier semop() */
time_t sem_ctime; /* Heure de création/heure du */
dernier changement avec semctl() */
unsigned long sem_nsems; /* Nombre de sémaphores dans l'ensemble */
};
.EE
.in
.PP
Les champs de la structure \fIsemid_ds\fP sont les suivants\ :
.TP 11
\fIsem_perm\fP
Il s'agit d'une structure \fIipc_perm\fP (voir plus bas) qui spécifie les
d'accès sur le jeu de sémaphores.
.TP
\fIsem_otime\fP
Heure du dernier appel système \fBsemop\fP(2).
.TP
\fIsem_ctime\fP
Heure de création du jeu de sémaphores ou heure de la dernière opération
\fBIPCSET\fP, \fBSETVAL\fP ou \fBSETALL\fP de \fBsemctl\fP().
.TP
\fIsem_nsems\fP
Nombre de sémaphores dans l'ensemble. Chaque sémaphore est référencé par un
entier positif ou nul, compris dans l'intervalle \fB0\fP à \fIsem_nsems\-1\fP.
.PP
La structure \fIipc_perm\fP est définie de la façon suivante (les champs en
gras peuvent être modifiés en utilisant \fBIPC_SET\fP)\ :
.PP
.in +4n
.EX
struct ipc_perm {
key_t __key; /* Clé fournie à semget(2) */
uid_t \fBuid\fP; /* UID effectif du propriétaire */
gid_t \fBgid\fP; /* GID effectif du propriétaire */
uid_t cuid; /* UID effectif du créateur */
gid_t cgid; /* GID effectif du créateur */
unsigned short \fBmode\fP; /* Permissions */
unsigned short __seq; /* Numéro de séquence */
};
.EE
.in
.PP
Les 9 bits les moins significatifs du champ \fImode\fP de la structure
\fIipc_perm\fP définissent les droits d'accès aux segments de la mémoire
partagée. Les bits de permission sont les suivants\ :
.TS
l l.
0400 Lisible par l'utilisateur
0200 Droit d'écriture pour l'utilisateur
0040 Lisible par le groupe
0020 Autorisation d'écriture pour le groupe
0004 Lisible par les autres
0002 Écrit par d'autres
.TE
.PP
En réalité, «\ écrire\ » signifie «\ modifier\ » pour un jeu de sémaphores. Les
bits 0100, 0010 et 0001 (les bits d'exécution) ne sont pas utilisés par le
système.
.PP
Les valeurs autorisées pour \fIcmd\fP sont\ :
.TP
\fBIPC_STAT\fP
Copier dans la structure \fIsemid_ds\fP pointée par \fIarg.buf\fP la structure de
données du noyau concernant l'ensemble de sémaphores. L'argument \fIsemnum\fP
est alors ignoré. Le processus appelant doit avoir des privilèges de lecture
sur le jeu de sémaphores.
.TP
\fBIPC_SET\fP
Écrire la valeur de certains membres de la structure \fIsemid_ds\fP pointés par
\fIarg.buf\fP dans la structure de données du noyau associée à ce jeu de
sémaphores, en mettant aussi à jour son membre \fIsem_ctime\fP.
.IP
Les membres suivants de la structure sont mis à jour\ : \fIsem_perm.uid\fP,
\fIsem_perm.gid\fP et (les 9\ bits de poids faible de) \fIsem_perm.mode\fP.
.IP
L'UID effectif du processus appelant doit correspondre au propriétaire
(\fIsem_perm.uid\fP) ou au créateur (\fIsem_perm.cuid\fP) du jeu de sémaphores ou
l'appelant doit être privilégié. L'argument \fIsemnum\fP est ignoré.
.TP
\fBIPC_RMID\fP
Supprimer immédiatement l'ensemble de sémaphores en réveillant tous les
processus en attente dans \fBsemop\fP(2). Ils obtiendront un code d'erreur, et
\fIerrno\fP aura la valeur \fBEIDRM\fP. 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 \fIsemnum\fP est ignoré.
.TP
\fBIPC_INFO\fP (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 \fIarg.__buf\fP. Cette
structure est de type \fIseminfo\fP, défini dans \fI<sys/sem.h>\fP si la
macro \fB_GNU_SOURCE\fP est définie\ :
.IP
.in +4n
.EX
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) */
};
.EE
.in
.IP
Les paramètres \fIsemmsl\fP, \fIsemmns\fP, \fIsemopm\fP et \fIsemmni\fP peuvent être
modifiés via \fI/proc/sys/kernel/sem\fP\ ; consultez \fBproc\fP(5) pour plus de
détails.
.TP
\fBSEM_INFO\fP (spécifique à Linux)
Renvoyer une structure \fIseminfo\fP contenant les mêmes informations que pour
\fBIPC_INFO\fP, sauf les champs suivants qui sont remplis avec des informations
sur les ressources système actuellement utilisées par les sémaphores\ : le
champ \fIsemusz\fP renvoie le nombre d'ensembles de sémaphores existants sur le
système, et le champ \fIsemaem\fP renvoie le nombre total de sémaphores dans
tous les ensembles de sémaphores du système.
.TP
\fBSEM_STAT\fP (spécifique à Linux)
Renvoyer une structure \fIsemid_ds\fP comme pour \fBIPC_STAT\fP. Cependant,
l'argument \fIsemid\fP 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.
.TP
\fBSEM_STAT_ANY\fP (spécifique à Linux depuis Linux\ 4.17)
Renvoyer une structure \fIsemid_ds\fP comme pour \fBSEM_STAT\fP. Néanmoins,
l'accès en lecture pour \fIsemid\fP n'est pas vérifié dans \fIsem_perm.mode\fP ce
qui signifie que tous les utilisateurs peuvent utiliser cette opération (de
la même manière qu'ils peuvent lire \fI/proc/sysvipc/sem\fP pour obtenir la
même information).
.TP
\fBGETALL\fP
Renvoyer la valeur \fBsemval\fP de chaque sémaphore de l'ensemble dans le
tableau \fIarg.array\fP. L'argument \fIsemnum\fP est ignoré. Le processus appelant
doit avoir des privilèges de lecture sur le jeu de sémaphores.
.TP
\fBGETNCNT\fP
Renvoyer la valeur du champ \fBsemzcnt\fP du \fIsemnum\fP\-ième sémaphore de
l'ensemble (c'est\-à\-dire le nombre de processus attendant que la valeur du
sémaphore augmente). Le processus appelant doit avoir des privilèges de
lecture sur le jeu de sémaphores.
.TP
\fBGETPID\fP
Renvoyer la valeur de \fBsempid\fP pour le \fIsemnum\fP\-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.
.TP
\fBGETVAL\fP
Renvoyer \fBsemval\fP (c'est\-à\-dire la valeur du sémaphore) pour le
\fIsemnum\fP\-ième sémaphore de l'ensemble. Le processus appelant doit avoir des
privilèges de lecture sur le jeu de sémaphores.
.TP
\fBGETZCNT\fP
Renvoyer la valeur du champ \fBsemzcnt\fP du \fIsemnum\fP\-ième sémaphore de
l'ensemble (c'est\-à\-dire le nombre de processus attendant que la valeur du
sémaphore revienne à\ 0). Le processus appelant doit avoir des privilèges de
lecture sur le jeu de sémaphores.
.TP
\fBSETALL\fP
Positionner la valeur du champ \fBsemval\fP de tous les sémaphores de
l'ensemble en utilisant le tableau \fIarg.array\fP et en mettant à jour le
champ \fIsem_ctime\fP de la structure \fIsemid_ds\fP de contrôle du jeu de
sémaphores. Les entrées «\ undo\ » (consultez \fBsemop\fP(2)) sont effacées de
tous les processus pour les sémaphores modifiés. Si la nouvelle valeur du
sémaphore permet à des appels \fBsemop\fP(2) bloqués dans d'autres processus de
se poursuivre, ces processus sont réveillés. L'argument \fIsemnum\fP est
ignoré. Le processus appelant doit avoir des privilèges d'écriture sur le
jeu de sémaphores.
.TP
\fBSETVAL\fP
Positionner la valeur du sémaphore (\fBsemval\fP) à \fIarg.val\fP pour le
\fIsemnum\fP\-ième sémaphore de l'ensemble en mettant aussi à jour le champ
\fIsem_ctime\fP dans la structure \fIsemid_ds\fP 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 \fBsemop\fP(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.
.SH "VALEUR RENVOYÉE"
En cas de réussite, \fBsemctl\fP() renvoie une valeur non négative dépendant de
l'argument \fIcmd\fP\ :
.TP
\fBGETNCNT\fP
La valeur de \fBsemncnt\fP.
.TP
\fBGETPID\fP
La valeur \fBsempid\fP.
.TP
\fBGETVAL\fP
La valeur \fBsemval\fP.
.TP
\fBGETZCNT\fP
La valeur \fBsemzcnt\fP.
.TP
\fBIPC_INFO\fP
Le plus grand indice d'une entrée utilisée dans la table interne du noyau
contenant des informations sur tous les ensembles de sémaphores. Cette
information peut ensuite être utilisée pour des opérations \fBSEM_STAT\fP ou
\fBSEM_STAT_ANY\fP répétées afin d'obtenir des informations sur tous les
ensembles de sémaphores du système.
.TP
\fBSEM_INFO\fP
Comme pour \fBIPC_INFO\fP.
.TP
\fBSEM_STAT\fP
L'identifiant de l'ensemble de sémaphores dont l'indice était donné dans
\fIsemid\fP.
.TP
\fBSEM_STAT_ANY\fP
comme pour \fBSEM_STAT\fP
.PP
Toutes les autres commandes \fIcmd\fP renvoient zéro en cas de réussite.
.PP
\fBsemctl\fP() renvoie\ \fB\-1\fP s'il échoue auquel cas \fIerrno\fP contient le code
d'erreur.
.SH ERREURS
.TP
\fBEACCES\fP
L'argument \fIcmd\fP a l'une des valeurs suivantes \fBGETALL\fP, \fBGETPID\fP,
\fBGETVAL\fP, \fBGETNCNT\fP, \fBGETZCNT\fP, \fBIPC_STAT\fP, \fBSEM_STAT\fP,
\fBSEM_STAT_ANY\fP, \fBSETALL\fP ou \fBSETVAL\fP, et le processus appelant n'a pas
les permissions nécessaires sur le jeu de sémaphores et n'a pas la capacité
\fBCAP_IPC_OWNER\fP dans l'espace de noms utilisateur qui régit son espace de
noms IPC.
.TP
\fBEFAULT\fP
\fIarg.buf\fP ou \fIarg.array\fP pointent en dehors de l'espace d'adressage
accessible.
.TP
\fBEIDRM\fP
Le jeu de sémaphores a été supprimé.
.TP
\fBEINVAL\fP
Valeur de \fIcmd\fP ou \fIsemid\fP non valable. Ou bien, pour une opération
\fBSEM_STAT\fP, l'indice indiqué dans \fIsemid\fP référence une entrée
actuellement inutilisée de la table.
.TP
\fBEPERM\fP
L'argument \fIcmd\fP réclame les commandes \fBIPC_SET\fP ou \fBIPC_RMID\fP mais l'UID
effectif du processus appelant n'est pas le créateur (comme dans
\fIsem_perm.cuid\fP) ou le propriétaire (comme dans \fIsem_perm.uid\fP) du jeu de
sémaphores, et le processus n'a pas la capacité \fBCAP_SYS_ADMIN\fP.
.TP
\fBERANGE\fP
L'argument \fIcmd\fP réclame les commandes \fBSETALL\fP ou \fBSETVAL\fP et la valeur
de \fBsemval\fP (pour l'ensemble ou pour certains sémaphores) est inférieure
à\ 0 ou supérieure à la valeur \fBSEMVMX\fP.
.SH STANDARDS
.\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
POSIX.1\-2001, POSIX.1\-2008, SVr4.
.PP
.\" POSIX.1-2001, POSIX.1-2008
POSIX.1 spécifie le champ \fIsem_nsems\fP de la structure \fIsemid_ds\fP comme de
type \fIunsigned\ short\fP, 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 \fIunsigned\ long\fP.
.SH NOTES
Les appels système \fBIPC_INFO\fP, \fBSEM_STAT\fP et \fBSEM_INFO\fP sont utilisés par
le programme \fBipcs\fP(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 \fI/proc\fP.
.PP
Divers champs de la \fIstruct semid_ds\fP étaient de type \fIshort\fP sous
Linux\ 2.2 et sont devenus de type \fIlong\fP sous Linux\ 2.4. Pour en tirer
parti, une recompilation sous la glibc\ 2.1.91 ou ultérieure doit
suffire. (Le noyau distingue les anciens et nouveaux appels par un drapeau
\fBIPC_64\fP dans \fIcmd\fP.)
.PP
.\" POSIX.1-2001, POSIX.1-2008
Dans certaines versions antérieures de la glibc, l'union \fIsemun\fP était
définie dans \fI<sys/sem.h>\fP, mais POSIX.1 documente que l'appelant
doit définir cette union. Dans les versions de la glibc où cette union n'est
\fIpas\fP définie, la macro \fB_SEM_SEMUN_UNDEFINED\fP est définie dans
\fI<sys/sem.h>\fP.
.PP
La limite suivante du système sur les jeux de sémaphore affecte l'appel
système \fBsemctl\fP()\ :
.TP
\fBSEMVMX\fP
Valeur maximale pour \fBsemval\fP dépendant de l'implémentation (généralement
32767).
.PP
.\"
Pour améliorer la portabilité, il vaut mieux invoquer toujours \fBsemctl\fP()
avec quatre arguments.
.SS "La valeur sempid"
POSIX.1 définit \fIsempid\fP 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 \fBsemop\fP réussi, avec l'implication qu'aucune autre
interface n'affecte la valeur \fIsempid\fP.
.PP
.\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin
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
\fIsempid\fP pour d'autres opérations qui mettent à jour la valeur d'un
sémaphore\ : les opérations \fBSETVAL\fP et \fBSETALL\fP, ainsi que les ajustements
de sémaphores exécutés en fin de processus du fait de l'utilisation de
l'option \fBSEM_UNDO\fP (voir \fBsemop\fP(2)).
.PP
.\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f
Linux modifie également \fIsempid\fP pour les opérations \fBSETVAL\fP et les
ajustements de sémaphores. Cependant, de façon plutôt incohérente, le noyau
ne mettait pas à jour \fIsempid\fP pour les opérations \fBSETALL\fP jusqu'à la
version\ 4.5 de Linux incluse. Cela a été corrigé avec la version\ 4.6.
.SH EXEMPLES
Consultez \fBshmop\fP(2).
.SH "VOIR AUSSI"
\fBipc\fP(2), \fBsemget\fP(2), \fBsemop\fP(2), \fBcapabilities\fP(7),
\fBsem_overview\fP(7), \fBsysvipc\fP(7)
.PP
.SH TRADUCTION
La traduction française de cette page de manuel a été créée par
Christophe Blaess <https://www.blaess.fr/christophe/>,
Stéphan Rafin <stephan.rafin@laposte.net>,
Thierry Vignaud <tvignaud@mandriva.com>,
François Micaux,
Alain Portal <aportal@univ-montp2.fr>,
Jean-Philippe Guérard <fevrier@tigreraye.org>,
Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>,
Julien Cristau <jcristau@debian.org>,
Thomas Huriaux <thomas.huriaux@gmail.com>,
Nicolas François <nicolas.francois@centraliens.net>,
Florentin Duneau <fduneau@gmail.com>,
Simon Paillard <simon.paillard@resel.enst-bretagne.fr>,
Denis Barbier <barbier@debian.org>,
David Prévot <david@tilapin.org>,
Thomas Vincent <tvincent@debian.org>
et
Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>
.
.PP
Cette traduction est une documentation libre ; veuillez vous reporter à la
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License version 3
.UE
concernant les conditions de copie et
de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
.PP
Si vous découvrez un bogue dans la traduction de cette page de manuel,
veuillez envoyer un message à
.MT debian-l10n-french@lists.debian.org
.ME .