semctl - operaciones de control de semáforos
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semctl(int semid, int semnum, int cmd, ...);
La función semctl realiza la operación de
control especificada por cmd sobre el conjunto de semáforos
identificado por semid, o en el semáforo semnum-th de
dicho conjunto. (Los semáforos son númerados comenzando por el
0.)
Esta función tiene tres o cuatro argumentos. Cuando hay
cuatro, la llamada es
semctl(semid,semnum,cmd,arg);
donde el cuarto argumento arg tiene como tipo union semun
definido como sigue:
#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
Valores válidos para cmd son:
- IPC_STAT
- Copiar información de la estructura de datos del conjunto de
semáforos en la estructura apuntada por
arg.buf. El argumento semnum es ignorado. El
proceso que realiza la llamada debe tener privilegios de acceso de lectura
en el conjunto de semáforos.
- IPC_SET
- Escribir los valores de algunos miembros de la estructura semid_ds
apuntada por arg.buf a la estructura de datos del conjunto
de semáforos, actualizando tambien su miembro sem_ctime. Los
miembros de la estructura provista por el usuario struct semid_ds a
los que apunta arg.buf son
sem_perm.uid
sem_perm.gid
sem_perm.mode /* solo los 9 bits más bajos */
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 semnum
es ignorado.
- IPC_RMID
- Borrar inmediatamente el conjunto de semáforos y sus estructuras de
datos, despertando todos los procesos en espera (devuelve un error, y
errno puesto a 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
semnum es ignorado.
- GETALL
- Devuelve semval para todos los semáforos del conjunto, en
arg.array. El argumento semnum es ignorado. El
proceso que realiza la llamada ha de tener privilegios de lectura en el
conjunto de semáforos.
- GETNCNT
- La llamada al sistema devuelve el valor de semncnt para el
semnum-avo semáforo del conjunto (p.ej. el número de
procesos esperando que aumente semval para el semnum-avo
semáforo del conjunto). El proceso que realiza la llamada ha de
tener privilegios de lectura en el conjunto de semáforos.
- GETPID
- La llamada al sistema devuelve el valor de sempid para el
semnum-avo semáforo del conjunto (p.ej. el pid del proceso
que ejecutó la última llamada semop para el
semnum-avo semáforo del conjunto). El proceso que realiza la
llamada ha de tener privilegios de lectura en el conjunto de
semáforos.
- GETVAL
- La llamada al sistema devuelve el valor de semval para el
semnum-avo semáforo del conjunto. El proceso que realiza la
llamada ha de tener privilegios de lectura en el conjunto de
semáforos.
- GETZCNT
- La llamada al sistema devuelve el valor de semzcnt para el
semnum-avo semáforo del conjunto (p.ej. el número de
procesos que esperan que semval del 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.
- SETALL
- Poner semval para todos los semáforos del conjunto usando
arg.array, actualizando también el miembro
sem_ctime de la estructura 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 semval se pone
a 0 o se incrementa. El argumento semnum es ignorado. El proceso
que realiza la llamada ha de tener privilegios de modificación en
el conjunto de semáforos.
- SETVAL
- Poner el valor de semval a arg.val para el
semnum-avo semáforo del conjunto, actualizando
también el miembro sem_ctime de la estructura
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 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.
En caso de fallo semctl devuelve -1, mientras
errno indica el error. De otro modo, la llamada al sistema devuelve
un valor no negativo, dependiendo de cmd como sigue:
- GETNCNT
- el valor de semncnt.
- GETPID
- el valor de sempid.
- GETVAL
- el valor de semval.
- GETZCNT
- el valor de semzcnt.
Todos los demás valores cmd devuelven 0 en caso de
éxito.
En caso de error, errno tendrá uno de los siguientes
valores:
- EACCESS
- El proceso que reliza la llamada no tiene los permisos necesarios para
ejecutar cmd.
- EFAULT
- La dirección a la que apunta arg.buf o
arg.array no es accesible.
- EIDRM
- El conjunto de semáforos se borró.
- EINVAL
- Valor no válido para cmd o semid.
- EPERM
- El argumento cmd tiene valor IPC_SET o IPC_RMID pero
el proceso invocador no tiene suficientes privilegios para ejecutar la
orden.
- ERANGE
- El argumento cmd tiene el valor SETALL o SETVAL y el
valor al que ha de ser puesto semval (para algún
semáforo del conjunto) es menor que 0 o mayor que el valor
SEMVMX de la implementación.
Las llamadas de control IPC_INFO, SEM_STAT y
SEM_INFO son utilizadas por el programa 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.
Varios campos de la estructura semid_ds 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 cmd.)
El siguiente límite de sistema para conjuntos de
semáforos afecta a la llamada semctl:
- SEMVMX
- Valor máximo para semval: depende de la
implementación (32767).
Para una mayor portabilidad siempre es mejor llamar a
semctl con cuatro argumentos.
Bajo Linux, la función semctl no es una llamada al
sistema, sino que es implementada a través de la llamada al sistema
ipc(2).
SVr4, SVID. SVr4 documenta adicionalmente las condiciones de error
EINVAL y EOVERFLOW.