semctl

SEMCTL(2)               PodrÄcznik programisty Linuksa               SEMCTL(2)



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.



Linux                             2016-03-15                         SEMCTL(2)