.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Traduction 15/10/1996 par Christophe Blaess (ccb@club-internet.fr)
.\" Mise a Jour 8/04/97
.TH SEMGET 2 "8 Avril 1997" Linux "Manuel du programmeur Linux"
.SH NOM
semget \- Obtenir l'identificateur d'un ensemble de semaphores.
.SH SYNOPSIS
.nf
.B
# include <sys/types.h>
.B
# include <sys/ipc.h>
.B
# include <sys/sem.h>
.fi
.sp
.BI "int semget ( key_t " key ,
.BI "int " nsems ,
.BI "int " semflg " )"
.SH DESCRIPTION
Cette fonction retourne l'identificateur de l'ensemble de 
semaphores associe a la valeur cle
.IR key .
Un nouvel ensemble contenant
.I nsems
semaphores est cree si 
.I key
a la valeur
.B IPC_PRIVATE
ou si aucun ensemble n'est associe a
.IR key ,
et si l'option
.B IPC_CREAT
est presente dans
.I semflg.

La presence de
.B IPC_CREAT
et
.B IPC_EXCL
dans le champ
.I semflg
joue le meme role, par rapport a l'existence du
jeu de semaphores, que la presence de
.B O_CREAT
et
.B O_EXCL
dans l'argument de mode de l'appel systeme
.BR open (2)
i.e. la fonction
.B semget
echouera si
.I semflg
demande a la fois
.B IPC_CREAT
et
.B IPC_EXCL
et si un semaphore associe a
.I key 
existe deja.
.PP
Pendant la creation, les 9 bits de poids faibles de
l'argument
.I semflg
definissent les permissions d'access (pour le proprietaire,
le groupe et les autres) au jeu de semaphores, en utilisant
le meme format et la meme signification  que les droits
d'access dans
.BR open (2)
ou
.BR creat (2).

Les permissions d'executions ne sont pas utilisees par le systeme, et
pour un jeu de semaphores, l'autorisation d'ecriture signifie
autorisation de modification.
.PP
Durant la creation, la structure de donnees
.B semid_ds
controlant le jeu de semaphores est initialisee ainsi :
.IP
.B sem_perm.cuid
et
.B sem_perm.uid
contiennent l'UID effectif du processus apppelant.
.IP
.B sem_perm.cgid
et
.B sem_perm.gid
contiennent le GID effectif du processus appelant.
.IP
le 9 bits de poids faibles de
.B sem_perm.mode
sont remplis avec les 9 bits de poids faibles de
.IR semflg .
.IP
.B sem_nsems
recoit la valeur
.IR nsems .
.IP
.B sem_otime
est mis a 0.
.IP
.B sem_ctime
est rempli avec l'heure actuelle.
.PP
l'argument
.I nsems
peut valoir
.B 0
(ignore)
si l'appel systeme n'est pas une creation d'ensemble de semaphores.
Autrement
.I nsems
doit etre superieur a
.B 0
et inferieur ou egal au nombre maximal de semaphores par ensemble,
.RB ( SEMMSL ).
.PP
Si le jeu de semaphores existe deja, les permissions d'acces sont
controlees, et l'on verifie si l'ensemble est sur le point
d'etre detruit.
.SH "VALEUR RENVOYEE"
Si l'appel reussit, il renvoie l'identificateur de l'ensemble (un
entier positif), sinon il renvoie
.B \-1
et
.B errno
contient le code d'erreur.
.SH ERREURS
.TP 11
.B EACCES
Le jeu de semaphore associe a
.IR key 
existe, mais le processus n'a aucun droit d'acces sur lui
.TP
.B EEXIST
Le jeu de semaphore associe a
.B key
existe mais l'argument
.I semflg
precise a la fois
.B IPC_CREAT
et
.BR IPC_EXCL .
.TP
.B EIDRM
le jeu de semaphores est pret a etre detruit
.TP
.B ENOENT
Aucun jeu de semaphore associe a
.I key
n'existe
et l'argument
.I semflg
ne precise pas
.BR IPC_CREAT .
.TP
.B ENOMEM
Pas assez de memoire pour creer les structures necessaires.
.TP
.B ENOSPC
Le nombre maximal de jeux de semaphores sur le systeme
.RB ( SEMMNI )
est atteint,
ou le nombre maximal de semaphores sur le systeme est atteint
.RB ( SEMMNS ).
.SH NOTES
.B IPC_PRIVATE
n'est pas une option, mais un objet de type
.BR key_t .
Si l'on utilise cette valeur speciale dans l'argument
.IR key ,
l'appel systeme ne se preoccupera que des 9 bits de poids
faibles de
.I semflg
et tentera de creer un nouveau jeu de semaphores.
.PP
Les limites suivantes concernent l'appel systeme
.B semget :
.TP 11
.B SEMMNI
Nombre maximal d'ensembles de semaphores sur le systeme.
.TP
.B SEMMSL
Nombre maximal de semaphores par ensemble.
.TP
.B SEMMNS
Nombre maximal de semaphores sur le systeme.
.SH BUGS
L'utilisation de 
.B IPC_PRIVATE
n'empeche pas les autres processus d'acceder au jeu de semaphores alloue.
.PP
Comme pour les fichiers, il n'existe actuellement aucun moyen intrinseque
pour un processus de se garantir un acces exclusif a un ensemble de semaphores.
Reclamer a la fois
.B IPC_CREAT
et
.B IPC_EXCL
dans l'argument
.I semflg
garantit seulement la creation d'un nouvel ensemble, et non
pas un acces exclusif.
.PP
Les structures de donnees associees a chaque semaphore dans l'ensemble
ne sont pas initialisees lors de l'appel systeme.
Pour effectuer cette initialisation, il faut executer un appel a
.BR semctl (2)
avec les commandes
.B SETVAL
ou
.B SETALL.
.SH CONFORMITE
SVr4, SVID.  SVr4 documente des conditions d'erreur supplementairs
EINVAL, EFBIG, E2BIG, EAGAIN, ERANGE, et EFAULT.
.SH "VOIR AUSSI"
.BR ftok (3),
.BR ipc (5),
.BR semctl (2),
.BR semop (2).