SEMCTL
Section : Manuel du programmeur Linux (
2)
Mise à jour de la version anglaise : 20 mai 2008
Index
Menu principal
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.
Index
- NOM
-
- SYNOPSIS
-
- DESCRIPTION
-
- VALEUR RENVOYÉE
-
- ERREURS
-
- CONFORMITÉ
-
- NOTES
-
- VOIR AUSSI
-
- TRADUCTION
-
Dernière mise à jour : 23 juin 2008