semctl(2) System Calls Manual semctl(2) NOM semctl - Operations de controle sur les semaphores System V BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include int semctl(int semid, int semnum, int cmd, ...); DESCRIPTION Cette fonction effectue l'operation de controle indiquee par cmd sur l'ensemble de semaphores System V (ou sur le semnum-ieme semaphore de l'ensemble) identifie par semid. (Les semaphores sont numerotes a partir de zero.) La fonction a trois ou quatre arguments, selon la valeur de cmd. Quand il y en a quatre, le quatrieme est de type union semun. Le programme appelant doit definir cette union de la facon 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 (specifique a Linux) */ }; La structure semid_ds est definie dans comme suit : struct semid_ds { struct ipc_perm sem_perm; /* Permissions d'acces */ time_t sem_otime; /* Heure dernier semop() */ time_t sem_ctime; /* Heure de creation/heure du */ dernier changement avec semctl() */ unsigned long sem_nsems; /* Nombre de semaphores dans l'ensemble */ }; Les champs de la structure semid_ds sont les suivants : sem_perm Il s'agit d'une structure ipc_perm (voir plus bas) qui specifie les d'acces sur le jeu de semaphores. sem_otime Heure du dernier appel systeme semop(2). sem_ctime Heure de creation du jeu de semaphores ou heure de la derniere operation IPCSET, SETVAL ou SETALL de semctl(). sem_nsems Nombre de semaphores dans l'ensemble. Chaque semaphore est reference par un entier positif ou nul, compris dans l'intervalle 0 a sem_nsems-1. La structure ipc_perm est definie de la facon suivante (les champs en gras peuvent etre modifies en utilisant IPC_SET) : struct ipc_perm { key_t __key; /* Cle fournie a semget(2) */ uid_t uid; /* UID effectif du proprietaire */ gid_t gid; /* GID effectif du proprietaire */ uid_t cuid; /* UID effectif du createur */ gid_t cgid; /* GID effectif du createur */ unsigned short mode; /* Permissions */ unsigned short __seq; /* Numero de sequence */ }; Les 9 bits les moins significatifs du champ mode de la structure ipc_perm definissent les droits d'acces aux segments de la memoire partagee. Les bits de permission sont les suivants : 0400 Lisible par l'utilisateur 0200 Droit d'ecriture pour l'utilisateur 0040 Lisible par le groupe 0020 Autorisation d'ecriture pour le groupe 0004 Lisible par les autres 0002 Ecrit par d'autres En realite, << ecrire >> signifie << modifier >> pour un jeu de semaphores. Les bits 0100, 0010 et 0001 (les bits d'execution) ne sont pas utilises par le systeme. Les valeurs autorisees pour cmd sont : IPC_STAT Copier dans la structure semid_ds pointee par arg.buf la structure de donnees du noyau concernant l'ensemble de semaphores. L'argument semnum est alors ignore. Le processus appelant doit avoir des privileges de lecture sur le jeu de semaphores. IPC_SET Ecrire la valeur de certains membres de la structure semid_ds pointes par arg.buf dans la structure de donnees du noyau associee a ce jeu de semaphores, en mettant aussi a jour son membre sem_ctime. Les membres suivants de la structure sont mis a 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 au proprietaire (sem_perm.uid) ou au createur (sem_perm.cuid) du jeu de semaphores ou l'appelant doit etre privilegie. L'argument semnum est ignore. IPC_RMID Supprimer immediatement l'ensemble de semaphores en reveillant 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 etre soit celui du createur ou du proprietaire du jeu de semaphores, ou l'appelant doit etre privilegie. L'argument semnum est ignore. IPC_INFO (specifique a Linux) Renvoyer des informations sur les limites et parametres du systeme concernant les semaphores dans la structure pointee par arg.__buf. Cette structure est de type seminfo, defini dans si la macro _GNU_SOURCE est definie : struct seminfo { int semmap; /* Nombre d'entrees dans la table de semaphores ; pas utilise par le noyau */ int semmni; /* Nombre maximal d'ensembles de semaphores */ int semmns; /* Nombre maximal de semaphores dans tous les ensembles de semaphores */ int semmnu; /* Nombre maximal de structures << undo >> sur le systeme ; pas utilise par le noyau */ int semmsl; /* Nombre maximal de semaphores dans un ensemble */ int semopm; /* Nombre maximal d'operations pour semop(2) */ int semume; /* Nombre maximal d'entrees << undo >> par processus ; pas utilise par le noyau */ int semusz; /* Taille de struct sem_undo */ int semvmx; /* Valeur maximale d'un semaphore */ int semaem; /* Valeur maximale pouvant etre enregistree pour la mise a jour d'un semaphore (SEM_UNDO) */ }; Les parametres semmsl, semmns, semopm et semmni peuvent etre modifies via /proc/sys/kernel/sem ; consultez proc(5) pour plus de details. SEM_INFO (specifique a Linux) Renvoyer une structure seminfo contenant les memes informations que pour IPC_INFO, sauf les champs suivants qui sont remplis avec des informations sur les ressources systeme actuellement utilisees par les semaphores : le champ semusz renvoie le nombre d'ensembles de semaphores existants sur le systeme, et le champ semaem renvoie le nombre total de semaphores dans tous les ensembles de semaphores du systeme. SEM_STAT (specifique a Linux) Renvoyer une structure semid_ds comme pour IPC_STAT. Cependant, l'argument semid n'est pas un identifiant de semaphore, mais un index dans la table interne du noyau qui contient des informations sur tous les ensembles de semaphores du systeme. SEM_STAT_ANY (specifique a Linux depuis Linux 4.17) Renvoyer une structure semid_ds comme pour SEM_STAT. Neanmoins, l'acces en lecture pour semid n'est pas verifie dans sem_perm.mode ce qui signifie que tous les utilisateurs peuvent utiliser cette operation (de la meme maniere qu'ils peuvent lire /proc/sysvipc/sem pour obtenir la meme information). GETALL Renvoyer la valeur semval de chaque semaphore de l'ensemble dans le tableau arg.array. L'argument semnum est ignore. Le processus appelant doit avoir des privileges de lecture sur le jeu de semaphores. GETNCNT Renvoyer la valeur du champ semzcnt du semnum-ieme semaphore de l'ensemble (c'est-a-dire le nombre de processus attendant que la valeur du semaphore augmente). Le processus appelant doit avoir des privileges de lecture sur le jeu de semaphores. GETPID Renvoyer la valeur de sempid pour le semnum-ieme semaphore de l'ensemble. Il s'agit du PID du processus ayant execute la derniere operation sur ce semaphore (voir les NOTES). Le processus appelant doit avoir des privileges de lecture sur le jeu de semaphores. GETVAL Renvoyer semval (c'est-a-dire la valeur du semaphore) pour le semnum-ieme semaphore de l'ensemble. Le processus appelant doit avoir des privileges de lecture sur le jeu de semaphores. GETZCNT Renvoyer la valeur du champ semzcnt du semnum-ieme semaphore de l'ensemble (c'est-a-dire le nombre de processus attendant que la valeur du semaphore revienne a 0). Le processus appelant doit avoir des privileges de lecture sur le jeu de semaphores. SETALL Positionner la valeur du champ semval de tous les semaphores de l'ensemble en utilisant le tableau arg.array et en mettant a jour le champ sem_ctime de la structure semid_ds de controle du jeu de semaphores. Les entrees << undo >> (consultez semop(2)) sont effacees de tous les processus pour les semaphores modifies. Si la nouvelle valeur du semaphore permet a des appels semop(2) bloques dans d'autres processus de se poursuivre, ces processus sont reveilles. L'argument semnum est ignore. Le processus appelant doit avoir des privileges d'ecriture sur le jeu de semaphores. SETVAL Positionner la valeur du semaphore (semval) a arg.val pour le semnum-ieme semaphore de l'ensemble en mettant aussi a jour le champ sem_ctime dans la structure semid_ds associee au jeu de semaphores. Les entrees << undo >> sont effacees de tous les processus pour les semaphores modifies. Si la nouvelle valeur du semaphore permet a des appels semop(2) bloques dans d'autres processus de se poursuivre, ces processus sont reveilles. Le processus appelant doit avoir des privileges d'ecriture sur le jeu de semaphores. VALEUR RENVOYEE En cas de reussite, semctl() renvoie une valeur non negative dependant 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 entree utilisee dans la table interne du noyau contenant des informations sur tous les ensembles de semaphores. Cette information peut ensuite etre utilisee pour des operations SEM_STAT ou SEM_STAT_ANY repetees afin d'obtenir des informations sur tous les ensembles de semaphores du systeme. SEM_INFO Comme pour IPC_INFO. SEM_STAT L'identifiant de l'ensemble de semaphores dont l'indice etait donne dans semid. SEM_STAT_ANY comme pour SEM_STAT Toutes les autres commandes cmd renvoient zero en cas de reussite. semctl() renvoie -1 s'il echoue auquel cas errno contient le code d'erreur. ERREURS EACCES L'argument cmd a l'une des valeurs suivantes GETALL, GETPID, GETVAL, GETNCNT, GETZCNT, IPC_STAT, SEM_STAT, SEM_STAT_ANY, SETALL ou SETVAL, et le processus appelant n'a pas les permissions necessaires sur le jeu de semaphores et n'a pas la capacite CAP_IPC_OWNER dans l'espace de noms utilisateur qui regit son espace de noms IPC. EFAULT arg.buf ou arg.array pointent en dehors de l'espace d'adressage accessible. EIDRM Le jeu de semaphores a ete supprime. EINVAL Valeur de cmd ou semid non valable. Ou bien, pour une operation SEM_STAT, l'indice indique dans semid reference une entree actuellement inutilisee de la table. EPERM L'argument cmd reclame les commandes IPC_SET ou IPC_RMID mais l'UID effectif du processus appelant n'est pas le createur (comme dans sem_perm.cuid) ou le proprietaire (comme dans sem_perm.uid) du jeu de semaphores, et le processus n'a pas la capacite CAP_SYS_ADMIN. ERANGE L'argument cmd reclame les commandes SETALL ou SETVAL et la valeur de semval (pour l'ensemble ou pour certains semaphores) est inferieure a 0 ou superieure a la valeur SEMVMX. VERSIONS POSIX.1 specifie le champ sem_nsems de la structure semid_ds comme de type unsigned short, ce qui est suivi par de nombreux systemes. Ce champ etait defini ainsi dans Linux 2.2 et dans les versions precedentes. Depuis Linux 2.4, ce champ est de type unsigned long. La valeur sempid POSIX.1 definit sempid comme l'<< ID du processus de la derniere operation >> sur un semaphore, et note explicitement que cette valeur est reglee par un appel semop reussi, avec l'implication qu'aucune autre interface n'affecte la valeur sempid. Bien que certaines implementations respectent le comportement defini dans POSIX.1, d'autres ne le font pas (le tort revient ici probablement a POSIX.1 qui n'a pas reussi a englober tous les comportements implementes existants). Diverses autres implementations mettent egalement a jour sempid pour d'autres operations qui mettent a jour la valeur d'un semaphore : les operations SETVAL et SETALL, ainsi que les ajustements de semaphores executes en fin de processus du fait de l'utilisation de l'option SEM_UNDO (voir semop(2)). Linux modifie egalement sempid pour les operations SETVAL et les ajustements de semaphores. Cependant, de facon plutot incoherente, le noyau ne mettait pas a jour sempid pour les operations SETALL jusqu'a la version 4.5 de Linux incluse. Cela a ete corrige avec la version 4.6. STANDARDS POSIX.1-2008. HISTORIQUE POSIX.1-2001, SVr4. Divers champs de la struct semid_ds etaient de type short sous Linux 2.2 et sont devenus de type long sous Linux 2.4. Pour en tirer parti, une recompilation sous la glibc 2.1.91 ou ulterieure doit suffire. (Le noyau distingue les anciens et nouveaux appels par un drapeau IPC_64 dans cmd.) Dans certaines versions anterieures de la glibc, l'union semun etait definie dans , mais POSIX.1 documente que l'appelant doit definir cette union. Dans les versions de la glibc ou cette union n'est pas definie, la macro _SEM_SEMUN_UNDEFINED est definie dans . NOTES Les appels systeme IPC_INFO, SEM_STAT et SEM_INFO sont utilises par le programme ipcs(1) pour fournir des informations sur les ressources allouees. Cela peut changer dans le futur, en utilisant l'interface d'un systeme de fichiers /proc. La limite suivante du systeme sur les jeux de semaphore affecte l'appel systeme semctl() : SEMVMX Valeur maximale pour semval dependant de l'implementation (generalement 32767). Pour ameliorer la portabilite, il vaut mieux invoquer toujours semctl() avec quatre arguments. EXEMPLES Consultez shmop(2). VOIR AUSSI ipc(2), semget(2), semop(2), capabilities(7), sem_overview(7), sysvipc(7) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot , Thomas Vincent et Jean- Pierre Giraud Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 semctl(2)