Provided by: manpages-pl-dev_20060617-1_all bug

NAZWA

       semctl - sterowanie semaforami

SKŁADNIA

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

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

OPIS

       Funkcja  semctl  wykonuje  operację  sterującą  określoną  przez cmd na
       zestawie semaforów określonym przez semid lub na  semnum-tym  semaforze
       tego zestawu. (Numeracja semaforów zaczyna się od 0.)

       Funkcja  ta  posiada  trzy  lub  cztery argumenty. Gdy jest ich cztery,
       wywołanie  ma  postać   semctl(semid,semnum,cmd,arg),   gdzie   czwarty
       argument arg jest typu union semun zdefiniowanego następująco:

       #if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED)
       /* union semun jest zdefiniowana w <sys/sem.h> */
       #else
       /* dla zgodności z X/OPEN musimy sami sobie zdefiniować */
       union semun {
             int val;                  /* wartość dla SETVAL */
             struct semid_ds *buf;     /* bufor dla IPC_STAT i IPC_SET */
             unsigned short *array;    /* tablica dla GETALL i SETALL */
                                       /* Część specyficzna dla Linuksa: */
             struct seminfo *__buf;    /* bufor dla IPC_INFO */
       };
       #endif

       Dozwolone wartości parametru cmd to:

       IPC_STAT    Kopiowanie   informacji  ze  struktury  kontrolnej  zestawu
                   semaforów do struktury wskazywanej przez arg.buf.  Argument
                   semnum  jest pomijany.  Proces wywołujący funkcję musi mieć
                   prawa do odczytu zestawu semaforów.

       IPC_SET     Zapis   wartości   niektórych   pól   struktury    semid_ds
                   wskazywanej  przez  arg.buf do struktury kontrolnej zestawu
                   semaforów z jednoczesnym uaktualnieniem pola sem_ctime (tj.
                   przypisaniem  mu aktualnego wskazania czasu).  Pola zadanej
                   struktury  struct  semid_ds  wskazywanej   przez   arg.buf,
                   których wartości są kopiowane to:

                        sem_perm.uid
                        sem_perm.gid
                        sem_perm.mode  /* tylko 9 najmniej znaczących bitów */

                   Efektywny  identyfikator  użytkownika  procesu wywołującego
                   musi wskazywać na administratora  systemu,  twórcę  zestawu
                   semaforów  lub  jego  właściciela.   Argument  semnum  jest
                   pomijany.

       IPC_RMID    Natychmiastowe usunięcie zestawu semaforów i  związanych  z
                   nim  struktur danych.  Wszystkie procesy oczekujące zostaną
                   wznowione i wywołania, które wykonywały zasygnalizują  błąd
                   (przypisując  zmiennej  errno  wartość  EIDRM).   Efektywny
                   identyfikator użytkownika procesu wywołającego funkcję musi
                   wskazywać   na   administratora   systemu,  twórce  zestawu
                   semaforów  lub  jego  właściciela.  Argument  semnum   jest
                   pomijany.

       GETALL      Zwraca  wartości  semval  wszystkich  semaforów  z  zestawu
                   umieszczając je w tablicy arg.array.  Argument semnum  jest
                   pomijany.   Proces  wywołujący  funkcję  musi mieć prawa do
                   odczytu zestawu semaforów.

       GETNCNT     Zwraca wartość semncnt skojarzoną z semaforem numer  semnum
                   semaforem (tzn. liczbę procesów oczekujących na zwiększenie
                   się wartości semval skojarzonej z semaforem numer  semnum).
                   Proces  wywołujący  funkcję  musi  mieć  prawa  do  odczytu
                   zestawu semaforów.

       GETPID      Zwraca wartość sempid  skojarzoną  z  semaforem  o  numerze
                   semnum  w  zestawie.  (jest to identyfikator procesu, który
                   ostatnio wykonał semop na  semaforze).   Proces  wywołujący
                   funkcję musi mieć prawa do odczytu zestawu semaforów.

       GETVAL      Zwraca wartość semval semafora o numerze semnum w zestawie.
                   Proces  wywołujący  funkcję  musi  mieć  prawa  do  odczytu
                   zestawu semaforów.

       GETZCNT     Zwraca  wartość  semzcnt  skojarzoną  z semaforem o numerze
                   semnum w zestawie.  (tzn. liczbę procesów  oczekujących  na
                   osiągnięcie  przez  semafor  o  numerze semnum wartości 0).
                   Proces  wywołujący  funkcję  musi  mieć  prawa  do  odczytu
                   zestawu semaforów.

       SETALL      Przypisuje  wartości  semval  wszystkim  semaforom zestawu,
                   korzystając z tablicy  arg.array,  jednocześnie  uaktualnia
                   pole  sem_ctime  struktury semid_ds skojarzonej z zestawem.
                   Wszystkie struktury sem_undo skojarzone z  zestawem  są  we
                   wszystkich  procesach  zwalniane.   Procesy  oczekujące  na
                   osiągnięcie   przez   poszczególne   semafory   określonych
                   wartości  są  wznawiane,  jeśli  któraś  z  wartości semval
                   stanie się  zerowa  lub  wzrośnie.   Argument  semnum  jest
                   pomijany.   Proces  wywołujący  funkcję  musi mieć prawa do
                   modyfikacji zestawu semaforów.

       SETVAL      Przypisuje wartość arg.val polu semval semafora  o  numerze
                   semnum   w  zestawie.  Pole  sem_ctime  struktury  semid_ds
                   skojarzonej  z  semaforem  jest  uaktualniane.    Wszystkie
                   struktury  sem_undo  skojarzone  z  semaforem są zwalniane.
                   Procesy oczekujące na osiągnięcie przez semafor określonych
                   wartości  zostaną  wznowione, jeśli semval stanie się równe
                   zeru lub wzrośnie.  Proces  wywołujący  funkcję  musi  mieć
                   prawa do odczytu zestawu semaforów.

WARTOŚĆ ZWRACANA

       W  przypadku  wystąpienia błędu, semctl zwróci -1, przypisując zmiennej
       errno  wartość  określającą  rodzaj  błędu.   W  przeciwnym   przypadku
       zwrócona  zostanie  nieujemna  wartość  zależna od określonej przez cmd
       wykonywanej operacji w następujący sposób:

       GETNCNT    wartość semncnt.

       GETPID     wartość sempid.

       GETVAL     wartość semval.

       GETZCNT    wartość semzcnt.

       Dla wszystkich pozostałych wartości cmd w razie pomyślnego  zakończenia
       zwracane jest 0.

BŁĘDY

       W   przypadku   wystąpienia  błędu,  zmienna  errno  przyjmie  jedną  z
       następujących wartośći:

       EACCES     Proces  wywołujący  funkcję   nie   ma   odpowiednich   praw
                  wymaganych do wykonania operacji cmd.

       EFAULT     Adres   wskazywany   przez   arg.buf   lub   arg.array  jest
                  niedostępny.

       EIDRM      Zestaw semaforów został usunięty.

       EINVAL     Niewłaściwa wartość parametru cmd lub semid.

       EPERM      Argument cmd ma wartość IPC_SET  lub  IPC_RMID,  ale  proces
                  wywołujący  funkcję  nie  ma  uprawnień  upoważniających  do
                  wykonania tego polecenia.

       ERANGE     Argument cmd ma wartość SETALL lub SETVAL  ale  przekazywana
                  wartość  semafora  semval (dla któregoś z semaforów zestawu)
                  jest mniejsza od 0  lub  większa  od  wartości  ograniczenia
                  systemowego SEMVMX.

UWAGI

       Polecenia  sterujące  IPC_INFO,  SEM_STAT  i  SEM_INFO są używane przez
       program  ipcs(8)  do  pobierania  informacji  o  używanych  zasobach  w
       systemie.  Jeśli zajdzie potrzeba, polecenia te mogą w przyszłości ulec
       zmianie lub ich obsługa może zostać zawarta w systemie plików /proc.

       Niektóre pola struktury struct semid_ds były w Linuksie 2.2 typu  short
       a  stały  się  typu  long  w  Linuksie 2.4. Aby to wykorzystać, powinna
       wystarczyć rekompilacja pod glibc-2.1.91 lub nowszą.  (Jądro  rozróżnia
       stare i nowe wywołania za pomocą znacznika IPC_64 w cmd.)

       Dla wywołania semctl obowiązują następujące ograniczenia systemowe:

       SEMVMX     Maksymalna wartość semval: zależna od implementacji (32767).

       W celu  uzyskania  lepszej  przenośności,  najlepiet  zawsze  wywoływać
       semctl z czterema argumentami.

       Pod  Linuksem  funkcja  semctl  nie  jest  funkcją  systemową, ale jest
       zaimplementowana poprzez funkcję systemową ipc(2).

ZGODNE Z

       SVr4, SVID. W SVr4 udokumntowano jeszcze EINVAL i EOVERFLOW.

ZOBACZ TAKŻE

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