Provided by: manpages-pl-dev_0.7-2_all bug

NAZWA

       semctl - sterowanie semaforami Systemu V

SKŁADNIA

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

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

OPIS

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

       W  zależności  od  cmd  funkcja  przyjmuje  trzy lub cztery argumenty. Jeśli są cztery, to
       czwarty jest typu union semun. Program wywołujący musi zdefiniować tę unię jako:

           union semun {
               int              val;    /* Wartość dla SETVAL */
               struct semid_ds *buf;    /* Bufor dla IPC_STAT, IPC_SET */
               unsigned short  *array;  /* Tablica dla GETALL, SETALL */
               struct seminfo  *__buf;  /* Bufor dla IPC_INFO
                                           (specyficzne dla Linuksa) */
           };

       Struktura danych semid_ds jest zdefiniowana w <sys/sem.h> następująco:

           struct semid_ds {
               struct ipc_perm sem_perm;  /* Prawa dostępu */
               time_t          sem_otime; /* Czas ostatniej operacji semop */
               time_t          sem_ctime; /* Czas ostatniej zmiany */
               unsigned long   sem_nsems; /* Liczba semaforów w zestawie */
           };

       Struktura ipc_perm jest zdefiniowana następująco (wyróżnione pola można ustawić za  pomocą
       IPC_SET):

           struct ipc_perm {
               key_t          __key; /* Klucz podany w semget(2) */
               uid_t          uid;   /* Efektywny UID właściciela */
               gid_t          gid;   /* Efektywny GID właściciela */
               uid_t          cuid;  /* Efektywny UID twórcy */
               gid_t          cgid;  /* Efektywny GID twórcy */
               unsigned short mode;  /* Uprawnienia */
               unsigned short __seq; /* Numer sekwencji */
           };

       Poprawne wartości parametru cmd to:

       IPC_STAT  Kopiuje  informacje  ze  struktury  kontrolnej  jądra  skojarzonej  z  semid  do
                 struktury semid_ds wskazywanej przez arg.__buf. Argument semnum jest ignorowany.
                 Wywołujący musi mieć uprawnienie odczytu zestawu semaforów.

       IPC_SET   Zapisuje  wartości niektórych pól struktury semid_ds wskazywanej przez arg.__buf
                 do struktury danych jądra powiązanej  z  tym  zestawem  semaforów,  aktualizując
                 także  pole  sem_ctime.  Następujące  pola  mogą  być  zmieniane:  sem_perm.uid,
                 sem_perm.gid oraz (9 najmniej znaczących bitów  pola)  sem_perm.mode.  Efektywny
                 identyfikator  użytkownika  procesu wywołującego musi być równy identyfikatorowi
                 właściciela (sem_perm.uid) lub twórcy (sem_perm.cuid) segmentu pamięci dzielonej
                 albo   proces   wywołujący   musi  być  uprzywilejowany.  Argument  semnum  jest
                 ignorowany.

       IPC_RMID  Usuwa natychmiast zestaw semaforów.  Wznawia  wszystkie  procesy  zablokowane  w
                 wywołaniu  semop(2)  (wywołanie  to zasygnalizuje błąd i ustawi zmienną errno na
                 EIDRM). Efektywny identyfikator użytkownika procesu wywołującego musi odpowiadać
                 twórcy  lub  właścicielowi  zestawu  semaforów  albo  proces wywołujący musi być
                 uprzywilejowany. Argument semnum jest pomijany.

       IPC_INFO (specyficzne dla Linuksa)
                 Zwraca w strukturze, na  którą  wskazuje  arg.__buf,  informacje  o  systemowych
                 ograniczeniach  i  parametrach  semaforów.  Struktura  jest  typu seminfo i jest
                 zdefiniowana  w  <sys/shm.h>,  pod  warunkiem,  że  zdefiniowano  również  makro
                 _GNU_SOURCE:

                     struct  seminfo {
                         int semmap;  /* Liczba wpisów w mapie semaforów
                                         nieużywane przez jądro */
                         int semmni;  /* Maksymalna liczba zestawów semaforów */
                         int semmns;  /* Maksymalna liczba semaforów we wszystkich
                                         zestawach semaforów */
                         int semmnu;  /* Maksymalna liczba struktur wycofania (undo)
                                         w systemie; nieużywane przez jądro*/
                         int semmsl;  /* Maksymalna liczba semaforów
                                         w zestawie */
                         int semopm;  /* Maksymalna liczba operacji dla
                                         semop(2) */
                         int semume;  /* Maksymalna liczba wpisów wycofania (undo)
                                         procesu; nieużywane przez jądro */
                         int semusz;  /* Rozmiar struktury sem_undo */
                         int semvmx;  /* Maksymalna wartość semafora */
                         int semaem;  /* Maksymalna wartość możliwa do zapamiętania
                                         dla regulacji semafora (SEM_UNDO) */
                     };

                 Ustawienia  semmsl,  semmns, semopm oraz semmni można zmienić za pomocą plików w
                 /proc/sys/kernel/sem; szczegóły można znaleźć w podręczniku proc(5).

       SEM_INFO (specyficzne dla Linuksa)
                 Zwraca strukturę seminfo zawierającą te same informacje co w przypadku IPC_INFO,
                 z  tym   wyjątkiem,  że w następujących polach zwracane są informacje o zasobach
                 systemowych wykorzystywanych przez semafory: pole semusz zwraca liczbę  zestawów
                 semaforów  istniejących  obecnie w systemie; pole semaem zwraca całkowitą liczbę
                 semaforów we wszystkich zestawach semaforów w systemie.

       SEM_STAT (specyficzne dla Linuksa)
                 Zwraca strukturę semid_ds, taką jak dla IPC_STAT. Jednakże  parametr  semid  nie
                 jest   identyfikatorem   segmentu,   ale   indeksem  wewnętrznej  tablicy  jądra
                 przechowującej  informacje  o  wszystkich  segmentach  zestawach   semaforów   w
                 systemie.

       GETALL    Zwraca (bieżącą) wartość semval dla wszystkich semaforów z zestawu, umieszczając
                 je w tablicy arg.array. Argument semnum jest pomijany.  Proces  wywołujący  musi
                 mieć prawa do odczytu zestawu semaforów.

       GETNCNT   Zwraca wartość semncnt skojarzoną z semaforem numer semnum (tzn. liczbę procesów
                 oczekujących na zwiększenie się wartości semval skojarzonej  z  semaforem  numer
                 semnum). Proces wywołujący 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 wykonał ostatnią operację na tym semaforze  (ale
                 zob. UWAGI). Proces wywołujący musi mieć prawa do odczytu zestawu semaforów.

       GETVAL    Zwraca  wartość  semval  semafora  o numerze semnum w zestawie semaforów. Proces
                 wywołujący 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 musi mieć prawa do odczytu zestawu semaforów.

       SETALL    Przypisuje wartości semval wszystkim semaforom zestawu,  korzystając  z  tablicy
                 arg.array,   jednocześnie   aktualizuje   pole   sem_ctime   struktury  semid_ds
                 skojarzonej z zestawem. Wpisy wycofania (undo; patrz semop(2)) są czyszczone dla
                 wszystkich zmienianych semaforów we wszystkich procesach. Jeżeli zmiany wartości
                 semaforów  pozwoliłyby  na  odblokowanie  procesów  oczekujących  w  wywołaniach
                 semop(2),  to  te  procesy  są  wznawiane. Argument semnum jest pomijany. Proces
                 wywołujący musi mieć prawa do modyfikacji (zapisu) zestawu semaforów.

       SETVAL    Przypisuje wartość semval do arg.val  semafora  o  numerze  semnum  w  zestawie,
                 aktualizując  jednocześnie  pole  sem_ctime  struktury  semid_ds  skojarzonej  z
                 zestawem  semaforów.  Wpisy  wycofania  (undo)  są  czyszczone  dla  zmienianych
                 semaforów  we wszystkich procesach. Jeżeli zmiany wartości semaforów pozwoliłyby
                 na odblokowanie procesów oczekujących w wywołaniach semop(2), to te  procesy  są
                 wznawiane.  Proces  wywołujący  funkcję  musi  mieć prawa do modyfikacji zestawu
                 semaforów.

WARTOŚĆ ZWRACANA

       W razie błędu semctl() zwraca -1, a zmiennej errno  zostanie  nadana  wartość  określająca
       rodzaj błędu.

       W przeciwnym przypadku zwrócona zostanie nieujemna wartość zależna od parametru cmd:

       GETNCNT   wartość semncnt.

       GETPID    wartość sempid.

       GETVAL    wartość semval.

       GETZCNT   wartość semzcnt.

       IPC_INFO  indeks  najwyższego  używanego  wpisu w wewnętrznej tablicy jądra przechowującej
                 informacje o wszystkich  zestawach  semaforów.  (Informacji  tej  można  użyć  w
                 operacjach  SEM_STAT, aby otrzymać informacje o wszystkich zestawach semaforów w
                 systemie).

       SEM_INFO  tak jak IPC_INFO.

       SEM_STAT  identyfikator zestawu semaforów, którego indeks został podany w semid.

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

BŁĘDY

       Po niepomyślnym zakończeniu, zmienna errno przyjmie jedną z następujących wartości:

       EACCES Parametr cmd  ma  jedną  z  wartości  GETALL,  GETPID,  GETVAL,  GETNCNT,  GETZCNT,
              IPC_STAT,  SEM_STAT, SETALL lub SETVAL, a proces wywołujący  nie ma wystarczających
              uprawnień do działania na  zbiorze  semaforów  oraz  nie  ma  ustawionego  atrybutu
              CAP_IPC_OWNER.

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

       EIDRM  Zestaw semaforów został usunięty.

       EINVAL Niepoprawna  wartość  parametru  cmd lub semid. Albo: w przypadku operacji SEM_STAT
              wartość indeksu podana w parametrze semid odwoływała się  do  obecnie  nieużywanego
              elementu tablicy.

       EPERM  Parametr  cmd  jest  równy  IPC_SET  lub  IPC_RMID,  ale  identyfikator efektywnego
              użytkownika procesu wywołującego nie jest twórcą (określonym w  sem_perm.cuid)  ani
              właścicielem  (określonym  w  sem_perm.uid)  zestawu  semaforów,  a  proces  nie ma
              ustawionego atrybutu CAP_SYS_ADMIN.

       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.

ZGODNE Z

       POSIX.1-2001, POSIX.1-2001, SVr4.

       POSIX.1 określa pole sem_nsems struktury semid_ds jako będące typu  unsigned short  i  tak
       też  jest  ono  zdefiniowane  w  większości  systemów.  Tak  było również w Linuksie 2.2 i
       wcześniejszych, lecz od Linuksa 2.4 pole to jest typu unsigned long.

UWAGI

       Dołączenie <sys/types.h> i <sys/ipc.h> nie jest wymagane na Linuksie  ani  przez  żadną  z
       wersji  POSIX.  Jednak  niektóre  stare  implementacje  wymagają  dołączenia  tych  plików
       nagłówkowych, SVID również dokumentuje ich dołączenie. Aplikacje które mają być  przenośne
       na tego typu stare systemy mogą wymagać dołączenia omawianych plików nagłówkowych.

       Operacje  IPC_INFO,  SEM_STAT  oraz  SEM_INFO  są  używane  przez  program  ipcs(1) w celu
       dostarczenia informacji o zajmowanych zasobach. W  przyszłości  operacje  te  mogą  zostać
       zmodyfikowane lub przeniesione do interfejsu systemu plików /proc.

       Niektóre pola struktury struct semid_ds były w Linuksie 2.2 typu short, ale 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 wywołania od nowych za pomocą znacznika IPC_64 w cmd).

       We  wcześniejszych  wersjach  biblioteki glibc unia semun była zdefiniowana w <sys/sem.h>,
       jednakże POSIX.1 wymaga, żeby to program wywołujący  definiował  tę  unię.  Wersje  glibc,
       które nie definiują tej unii, definiują makro _SEM_SEMUN_UNDEFINED w <sys/sem.h>.

       Na   wywołanie   semctl()  wpływa  następujące  ograniczenie  systemowe  dotyczące  zbioru
       semaforów:

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

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

   Wartość sempid
       POSIX.1  definiuje  sempid  jako "identyfikator procesu ostatniej operacji" na semaforze i
       wprost zauważa, że wartość  tak  jest  ustawiana  przez  pomyślne  wywołanie  semop(2),  z
       implikacją, że żaden inny interfejs nie wpływa na wartość sempid.

       Choć  niektóre  implementacje  są zgodne  z zachowaniem opisanym w POSIX.1, to inne nie są
       (błąd prawdopodobnie leży tu w specyfikacji  POSIX.1,  jako  że  nie  zauważyła  ona  tylu
       przykładów  istniejących  implementacji).  Różne  inne  implementacje  aktualizują  sempid
       również przy innych operacjach  aktualizujących  wartość  semafora:  operacjach  SETVAL  i
       SETALL,  jak  również dostosowaniach  semafora  wykonywanych przy zakończeniu procesu jako
       konsekwencji użycia flagi SEM_UNDO (zob. semop(2)).

       Linux aktualizuje sempid również przy operacjach SETVAL i dostosowaniach semafora. Jednak,
       nieco  niekonsekwentnie,  do  wersji  4.5  włącznie,  Linux  nie  aktualizował sempid przy
       operacjach SETALL. Skorygowano to w Linuksie 4.6.

ZOBACZ TAKŻE

       ipc(2), semget(2), semop(2), capabilities(7), sem_overview(7), svipc(7)

O STRONIE

       Angielska wersja tej strony  pochodzi  z  wydania  4.07  projektu  Linux  man-pages.  Opis
       projektu,  informacje  dotyczące  zgłaszania błędów, oraz najnowszą wersję oryginału można
       znaleźć pod adresem https://www.kernel.org/doc/man-pages/.

TŁUMACZENIE

       Autorami polskiego tłumaczenia niniejszej strony podręcznika man są: Rafał  Lewczuk  (PTM)
       <R.Lewczuk@elka.pw.edu.p>,  Andrzej  Krzysztofowicz  (PTM)  <ankry@mif.pg.gda.pl>,  Robert
       Luberda <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>.

       Polskie tłumaczenie jest częścią projektu manpages-pl; uwagi, pomoc, zgłaszanie błędów  na
       stronie   http://sourceforge.net/projects/manpages-pl/.   Jest   zgodne   z  wersją   4.07
       oryginału.