.\" 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.
.\"
.\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl>
.\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl>
.\" Modified 20 Dec 2001, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
.\" Modified 21 Dec 2001, aeb

.\" Translated 26 Jan 1997 by Vicente Pastor Gomez <VPASTORG@santandersupernet.com , vicpastor@hotmail.com>
.\" Translation revised Fri Oct 2 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Revisado por Miguel Pérez Ibars <mpi79470@alu.um.es> el 29-septiembre-2004
.\"
.TH SEMCTL 2 "21 diciembre 2001" "Linux 2.4.1" "Manual del Programador de Linux" 
.SH NOMBRE
semctl \- operaciones de control de semáforos
.SH SINOPSIS
.nf
.B #include <sys/types.h>
.B #include <sys/ipc.h>
.B #include <sys/sem.h>
.sp
.BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);"
.fi
.SH DESCRIPCIÓN
La función
.B semctl
realiza la operación de control especificada por
.I cmd
sobre el conjunto de semáforos identificado por
.IR semid ,
o en el semáforo
.IR semnum -th
de dicho conjunto.
(Los semáforos son númerados comenzando por el 0.)
.PP
Esta función tiene tres o cuatro argumentos. Cuando hay
cuatro, la llamada es
.BI semctl( semid , semnum , cmd , arg );
donde el cuarto argumento
.I arg
tiene como tipo
.B union semun
definido como sigue:

.nf
#if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED)
/* la union semun se define al incluir <sys/sem.h> */
#else
/* según X/OPEN tenemos que definirla nosostros mismos */
union semun {
        int val;                    /* valor para SETVAL */
        struct semid_ds *buf;       /* buffer para IPC_STAT, IPC_SET */
        unsigned short int *array;  /* array para GETALL, SETALL */
        struct seminfo *__buf;      /* buffer para IPC_INFO */
};
#endif
.fi
.PP
Valores válidos para
.I cmd
son:
.TP 12
.B IPC_STAT
Copiar información de la estructura de datos del conjunto de semáforos
en la estructura apuntada por
.IB arg .buf \fR.
El argumento
.I semnum
es ignorado.
El proceso que realiza la llamada debe tener privilegios de acceso de lectura
en el conjunto de semáforos.
.TP
.B IPC_SET
Escribir los valores de algunos miembros de la estructura
.B semid_ds
apuntada por
.IB arg .buf
a la estructura de datos del conjunto de semáforos, actualizando tambien
su miembro
.BR sem_ctime .
Los miembros de la estructura provista por el usuario
.B "struct semid_ds"
a los que apunta
.IB arg .buf
son
.nf
.sp
.ft B
        sem_perm.uid
        sem_perm.gid
        sem_perm.mode   \fR/* solo los 9 bits más bajos */\fP
.fi
.ft R
.sp
El identificador de usuario efectivo del proceso invocador debe ser el del
super\-usuario, o coincidir con el del creador o propietario del conjunto de semáforos.
El argumento
.I semnum
es ignorado.
.TP
.B IPC_RMID
Borrar inmediatamente el conjunto de semáforos y sus estructuras de datos,
despertando todos los procesos en espera (devuelve un error, y
.B errno
puesto a
.BR EIDRM ).
El identificador de usuario efectivo del proceso invocador debe ser el del
super\-usuario, o coincidir con el del creador o propietario del conjunto de semáforos.
El argumento
.I semnum
es ignorado.
.TP
.B GETALL
Devuelve
.B semval
para todos los semáforos del conjunto, en
.IB arg .array \fR.
El argumento
.I semnum
es ignorado.
El proceso que realiza la llamada ha de tener privilegios de lectura en
el conjunto de semáforos.
.TP
.B GETNCNT
La llamada al sistema devuelve el valor de
.B semncnt
para el 
.IR semnum \-avo
semáforo del conjunto
(p.ej. el número de procesos esperando que aumente
.B semval
para el
.IR semnum \-avo
semáforo del conjunto).
El proceso que realiza la llamada ha de tener privilegios de lectura en el
conjunto de semáforos.
.TP
.B GETPID
La llamada al sistema devuelve el valor de
.B sempid
para el
.IR semnum \-avo
semáforo del conjunto
(p.ej. el pid del proceso que ejecutó la última llamada
.B semop
para el
.IR semnum \-avo
semáforo del conjunto).
El proceso que realiza la llamada ha de tener privilegios de lectura en el
conjunto de semáforos.
.TP
.B GETVAL
La llamada al sistema devuelve el valor de
.B semval
para el
.IR semnum \-avo
semáforo del conjunto.
El proceso que realiza la llamada ha de tener privilegios de lectura en el
conjunto de semáforos.
.TP
.B GETZCNT
La llamada al sistema devuelve el valor de
.B semzcnt
para el
.IR semnum \-avo
semáforo del conjunto
(p.ej. el número de procesos que esperan que
.B semval
del
.IR semnum \-avo
semáforo del conjunto se ponga a 0).
El proceso que realiza la llamada ha de tener privilegios de lectura en el
conjunto de semáforos.
.TP
.B SETALL
Poner
.B semval
para todos los semáforos del conjunto usando
.IB arg .array \fR,
actualizando también el miembro
.B sem_ctime
de la estructura
.B semid_ds
asociada al conjunto.
Los registros de anulación son limpiados, para los semáforos cambiados, en
todos los procesos. Los procesos que están durmiendo en la cola de espera son
despertados si algún
.B semval
se pone a 0 o se incrementa.
El argumento
.I semnum
es ignorado.
El proceso que realiza la llamada ha de tener privilegios de modificación en el
conjunto de semáforos.
.TP
.B SETVAL
Poner el valor de
.B semval
a
.IB arg .val
para el
.IR semnum \-avo
semáforo del conjunto, actualizando también el miembro
.B sem_ctime
de la estructura
.B semid_ds
asociada al conjunto.
El registro de anulación es limpiado, para el semáforo alterado, en todos
los procesos.
Los procesos que están durmiendo en la cola de espera son despertados si
.B semval
se pone a 0 o se incrementa.
El proceso que realiza la llamada ha de tener privilegios de escritura en el
conjunto de semáforos.
.SH "VALOR DEVUELTO"
En caso de fallo
.B semctl
devuelve
.BR \-1 ,
mientras
.B errno
indica el error.
De otro modo, la llamada al sistema devuelve un
valor no negativo, dependiendo de
.I cmd
como sigue:
.TP 11
.B GETNCNT
el valor de
.BR semncnt .
.TP
.B GETPID
el valor de
.BR sempid .
.TP
.B GETVAL
el valor de
.BR semval .
.TP
.B GETZCNT
el valor de
.BR semzcnt .
.LP
Todos los demás valores
.I cmd
devuelven 0 en caso de éxito.
.SH ERRORES
En caso de error,
.B errno
tendrá uno de los siguientes valores:
.TP 11
.B EACCESS
El proceso que reliza la llamada no tiene los permisos necesarios para ejecutar
.IR cmd .
.TP
.B EFAULT
La dirección a la que apunta
.IB arg .buf
o
.IB arg .array
no es accesible.
.TP
.B EIDRM
El conjunto de semáforos se borró.
.TP
.B EINVAL
Valor no válido para
.I cmd
o
.IR semid .
.TP
.B EPERM
El argumento
.I cmd
tiene valor
.B IPC_SET
o
.B IPC_RMID
pero el proceso invocador no tiene suficientes privilegios para ejecutar la orden.
.TP
.B ERANGE
El argumento
.I cmd
tiene el valor
.B SETALL
o
.B SETVAL
y el valor al que ha de ser puesto
.B semval
(para algún semáforo del conjunto) es menor que 0 o mayor que el valor
.BR SEMVMX
de la implementación.
.SH OBSERVACIONES
Las llamadas de control
.BR IPC_INFO ,
.BR SEM_STAT
y
.B SEM_INFO
son utilizadas por el programa
.BR ipcs (8)
para proveer información sobre recursos asignados.
En el futuro pueden ser modificadas según se necesite, o llevadas al interfaz
del sistema de ficheros proc.
.LP
Varios campos de la estructura \fIsemid_ds\fP eran de tipo short bajo Linux 2.2
y se han convertido a tipo long bajo Linux 2.4. Para aprovechar esto,
sería suficiente volver a compilar bajo glibc-2.1.91 o posterior.
(El núcleo distingue las llamadas antiguas y nuevas por una opción IPC_64 en
.IR cmd .)
.PP
El siguiente límite de sistema para conjuntos de semáforos afecta a la llamada
.BR semctl :
.TP 11
.B SEMVMX
Valor máximo para
.BR semval :
depende de la implementación (32767).
.LP
Para una mayor portabilidad siempre es mejor llamar a
.B semctl
con cuatro argumentos.
.LP
Bajo Linux, la función
.B semctl
no es una llamada al sistema, sino que es implementada a través de 
la llamada al sistema
.BR ipc (2).
.SH "CONFORME A"
SVr4, SVID.  SVr4 documenta adicionalmente las condiciones de error EINVAL y
EOVERFLOW.
.SH "VÉASE TAMBIÉN"
.BR ipc (2),
.BR shmget (2),
.BR shmat (2),
.BR shmdt (2),
.BR ipc (5)