semctl

SEMCTL(2)                 Manuel du programmeur Linux                SEMCTL(2)



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 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   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 (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.70 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 Ã
       <perkamon-fr@traduc.org>.

       Vous pouvez toujours avoir accès à la version anglaise de ce document
       en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».



Linux                             3 juin 2013                        SEMCTL(2)