semctl

SEMCTL(2)               Manual del Programador de Linux              SEMCTL(2)



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)