Ubuntu Manpage: semctl - operaciones de control de semáforos

NOMBRE

       semctl - operaciones de control de semáforos

SINOPSIS

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/sem.h>

       int semctl(int semid, int semnum, int cmd, ...);

DESCRIPCIÓN

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.

VALOR DEVUELTO

       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.

ERRORES

       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.

OBSERVACIONES

       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).

CONFORME A

       SVr4, SVID.  SVr4 documenta adicionalmente las condiciones de error EINVAL y EOVERFLOW.

VÉASE TAMBIÉN

       ipc(2), shmget(2), shmat(2), shmdt(2), ipc(5)

Linux 2.4.1                                     21 diciembre 2001                                      SEMCTL(2)