Provided by: manpages-fr-dev_3.57d1p1-1_all 
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 faibles de sem_perm.mode. L'UID effectif du processus appelant doit être
celle 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'ensemble de sémaphores existant 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.
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 L'appel système renvoie 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
(c'est-à-dire le PID du processus ayant exécuté le dernier appel système
semop(2) sur le semnum-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 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 RENVOYÉE
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 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 SEM_STAT répétées
afin d'obtenir des informations sur tous les ensembles de sémaphores du
système.
SEM_INFO Comme pour IPC_INFO.
SEM_STAT L'identifiant de l'ensemble de sémaphores dont l'indice était donné dans
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 Valeur de cmd ou semid invalide. 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É
SVr4, POSIX.1-2001.
POSIX.1-2001 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 et 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. 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 glibc, l'union semun était définie dans
<sys/sem.h>, mais POSIX.1-2001 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.
VOIR AUSSI
ipc(2), semget(2), semop(2), capabilities(7), sem_overview(7), svipc(7)
COLOPHON
Cette page fait partie de la publication 3.57 du projet man-pages Linux. Une description
du projet et des instructions pour signaler des anomalies peuvent être trouvées à
l'adresse http://www.kernel.org/doc/man-pages/.
TRADUCTION
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet
perkamon <http://perkamon.alioth.debian.org/>.
Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal
<http://manpagesfr.free.fr/> (2003-2006). Julien Cristau et l'équipe francophone de
traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le paquet
manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la
commande « man -L C <section> <page_de_man> ».