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.
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.65 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> ».