.\" 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 SEMOP 2 "8 Avril 1997" Linux "Manuel du programmeur Linux"
.SH NOM
semop \- Oprations sur les smaphores.
.SH SYNOPSIS
.nf
.B
# include <sys/types.h>
.B
# include <sys/ipc.h>
.B
# include <sys/sem.h>
.fi
.sp
.BI "int semop ( int " semid ,
.BI "struct sembuf *" sops ,
.BI "unsigned " nsops " )"
.SH DESCRIPTION
Cette fonction effectue des oprations sur les membres slectionns
de l'ensemble de smaphores identifi par
.IR semid .
Chacun des
.I nsops
lments dans le tableau point par
.I sops
indique une opration  effectuer sur un smaphore 
en utilisant une structure
.B "struct sembuf"
dfinie comme suit:

.nf
  short sem_num;  /* Numero du smaphore (0=premier) */ 
  short sem_op;   /* Oeration sur le smaphore      */
  short sem_flg;  /* Options pour l'opration        */
.fi

Les options possibles pour
.B sem_flg
sont
.B IPC_NOWAIT
et
.BR SEM_UNDO .
Si une opration indique l'option
.BR SEM_UNDO ,
elle sera annule lorsque le processus se terminera.
.PP
La smantique de cet appel systme assure qu'un appel systme
ne sera effectu que si toutes ses oprations russissent.
Chaque opration est effectue sur le
.BR sem_num \-ime
smaphore de l'ensemble. Le premier smaphore est le numro
.B 0 .
Pour chaque smaphore l'opration est l'une des trois dcrites ci-dessous.
.PP
Si l'argument
.B sem_op
est un entier positif, la fonction ajoute cette valeur 
.BR  semval .
De plus si
.B SEM_UNDO
est demand, le systme met  jour le compteur "undo" du smaphore.
Cette opration n'est jamais bloquante.
Le processus appelant doit avoir l'autorisation de modification
sur le jeu de smaphores.
.PP
Si 
.B sem_op
vaut zro le processus attend que 
.B semval
soit nul. Plusieurs cas sont possibles :

Si
.B semval
vaut zro, l'appel systme continue immdiatement

Sinon, si l'on a reclam
.B IPC_NOWAIT
dans
.BR sem_flg ,
l'appel systme choue (en annulant les actions prcdentes)
et
.B errno
contient le code d'erreur
.BR EAGAIN .

Autrement
.B semzcnt
est increment de 1 et le processus s'endort jusqu' ce que l'un
des vnements suivants se produise :
.IP
.RS
.IP \(bu
.B semval
devient gal  0, alors
.B semzcnt
est dcrment. L'appel systme continue
.IP \(bu
Le jeu de smaphores est suprim. L'appel systme
choue et
.B errno
contient le code d'erreur
.BR EIDRM .
.IP \(bu
Le processus reoit un signal  intercepter, la
valeur de 
.B semzcnt
est dcrmente et l'appel systme choue avec
.B errno
contenant le code d'erreur
.BR EINTR .

.RE
Le processus appelant doit avoir l'autorisation de lecture
sur le jeu de smaphores.
.PP
Si
.B sem_op
est infrieur  zro, le processus appelant doit avoir 
l'autorisation de modification sur le jeu de smaphores.

Si
.B semval
est suprieur ou gal  la valeur absolue de
.BR sem_op ,
la valeur absolue de 
.B sem_op
est soustraite de
.BR semval .
Si 
.B SEM_UNDO
est indiqu, le systme met  jour le compteur "undo" du
smaphore. Puis l'appel systme continue.
Autrement si l'on a rclam
.B IPC_NOWAIT
dans
.BR sem_flg ,
l'appel systme choue (annulant les actions prcdentes
et
.B errno
contient le code d'erreur
.BR EAGAIN .
Sinon
.B semncnt
est dcrment de un et le processus s'endort jusqu' ce
que l'un des vnements suivants se produise :
.IP
.RS
.IP \(bu
.B semval
devient suprieur ou gal  la valeur absolue de 
.BR sem_op ,
alors la valeur
.B semncnt
est dcrmente, la valeur absolue de
.B sem_op
est soustraite de
.B semval
et si
.B SEM_UNDO
est demand le systme met  jour le compteur "undo" du
smaphore. Puis l'appel systme continue.
.IP \(bu
Le jeu de smaphores est suprim. L'appel systme
choue et
.B errno
contient le code d'erreur
.BR EIDRM .
.IP \(bu
Le processus reoit un signal  intercepter, la
valeur de 
.B semncnt
est dcrmente et l'appel systme choue avec
.B errno
contenant le code d'erreur
.BR EINTR .
.RE
.PP
en cas de succs, le membre 
.B sempid
de la structure
.B sem
de chacun des smaphores indiqus dans le tableau point par
.I sops
est rempli avec le PID du processus appelant.
Enfin
.B sem_otime
et
.B sem_ctime
sont fixs  l'heure actuelle.
.SH "VALEUR RENVOYE"
. semop
renvoie la valeur
.BR 0 ,
s'il russit et
.B \-1
s'il choue auquel cas 
.B errno
contient le code d'erreur.
.SH ERREURS
.TP 11
.B E2BIG
l'argument
.I nsops
est suprieur 
.BR SEMOPM ,
le nombre maximal d'oprations par appel systme.
.TP
.B EACCES
Le processus appelant n'a pas les permissions d'accs ncssaires.
.TP
.B EAGAIN
Une operation a chou et
.BR IPC_NOWAIT
a t indiqu dans l'argument
.IB sem_flg .
.TP
.B EFAULT
.I sops
pointe en dehors de l'espace d'adressage accessible.
.TP
.B EFBIG
La valeur de
.B sem_num
est infrieure  0 ou suprieure ou gale au nombre de
smaphores dans l'ensemble.
.TP
.B EIDRM
Le jeu de smaphores a t supprim.
.TP
.B EINTR
Un signal a t reu pendant l'attente.
.TP
.B EINVAL
L'ensemble de smaphores n'existe pas ou
.I semid
est infrieur  zro, ou
.I nsops
n'a pas une valeur positive.
.TP
.B ENOMEM
Pas assez de mmoire pour allouer les structures ncessaires.
.TP
.B ERANGE
.B semop + semval
est suprieur 
.BR SEMVMX.
.SH NOTES
Les structures
.B sem_undo
d'un processus ne sont pas hrites par ses enfants lors d'un
.BR fork (2).
par contre elles sont transmises lors d'un
.BR execve (2).
.PP
Les limites systme suivantes concernent
.B semop :
.TP 11
.B SEMOPM
Nombre maximal d'oprations pour un appel systme
.B semop .
.TP
.B SEMVMX
Valeur maximale pour
.BR semval .
.PP
.SH BUGS
Le systme maintient une structure 
.B sem_undo
par processus pour chaque smaphore modifi par le processus avec 
une requte "undo". Ces structures sont libres  la sortie
du processus. Le probleme principal avec le mcanisme undo est
qu'il viole le principe d'un jeu d'oprations lmentaires
sur les smaphores.
La requte "undo" ncessite une table et chaque smaphore peut
avoir particip  de nombreux appels
.B semopt.
Le processus doit-il s'endormir en se terminant ou doit-il
appliquer les oprations undo avec un comportement
.B IPC_NOWAIT ?
Actuellement les oprations "undo" qui russissent immdiatement
sont appliques, et les autres sont ignores silencieusement.
Il vaut donc mieux n'utiliser les requtes undo que dans le
cas d'ensembles de smaphores privs.
.SH "CONFORMIT"
SVr4, SVID.  SVr4 documente les conditions d'erreur supplmentaires
EINVAL, EFBIG, et ENOSPC.
.SH "VOIR AUSSI"
.BR ipc (5),
.BR semctl (2),
.BR semget (2).

.SH TRADUCTION
Christophe Blaess, 1997.