.\" -*- coding: UTF-8 -*- '\" t .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) .\" and Copyright 2004, 2005 Michael Kerrisk .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond .\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer .\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer .\" Modified 20 Dec 2001, Michael Kerrisk .\" Modified 21 Dec 2001, aeb .\" Modified 27 May 2004, Michael Kerrisk .\" Added notes on CAP_IPC_OWNER requirement .\" Modified 17 Jun 2004, Michael Kerrisk .\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID .\" Modified, 11 Nov 2004, Michael Kerrisk .\" Language and formatting clean-ups .\" Rewrote semun text .\" Added semid_ds and ipc_perm structure definitions .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. .\" 2018-03-20, dbueso: Added SEM_STAT_ANY description. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH semctl 2 "2 maja 2024 r." "Linux man\-pages 6.9.1" .SH NAZWA semctl \- steruje semaforami Systemu V .SH BIBLIOTEKA Standardowa biblioteka C (\fIlibc\fP, \fI\-lc\fP) .SH SKŁADNIA .nf \fB#include \fP .P \fBint semctl(int \fP\fIsemid\fP\fB, int \fP\fIsemnum\fP\fB, int \fP\fIop\fP\fB, ...);\fP .fi .SH OPIS \fBsemctl\fP() wykonuje operację sterującą, określoną przez \fIop\fP, na zestawie semaforów Systemu\ V określonym przez \fIsemid\fP lub na semaforze o numerze \fIsemnum\fP z tego zestawu (numeracja semaforów w zestawie semaforów zaczyna się od 0). .P W zależności od \fIop\fP funkcja przyjmuje trzy lub cztery argumenty. Jeśli są cztery, to czwarty jest typu \fIunion semun\fP. \fIProgram wywołujący\fP musi zdefiniować tę unię jako: .P .in +4n .EX 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) */ }; .EE .in .P Struktura danych \fIsemid_ds\fP jest zdefiniowana w \fI\fP następująco: .P .in +4n .EX struct semid_ds { struct ipc_perm sem_perm; /* Prawa dostępu */ time_t sem_otime; /* Czas ostatniej operacji semop */ time_t sem_ctime; /* Czas utworzenia/ostatniej zmiany za pomocą semctl() */ unsigned long sem_nsems; /* Liczba semaforów w zestawie */ }; .EE .in .P Pola struktury \fIsemid_ds\fP są następujące: .TP 11 \fIsem_perm\fP Jest to struktura \fIipc_perm\fP (zob. niżej), która określa prawa dostępu do zestawu semaforów. .TP \fIsem_otime\fP Czas ostatniego wywołania funkcji systemowej \fBsemop\fP(2). .TP \fIsem_ctime\fP Czas utworzenia zestawu semaforów albo czas ostatniej operacji \fBIPCSET\fP, \fBSETVAL\fP lub \fBSETALL\fP z \fBSETVAL\fP(). .TP \fIsem_nsems\fP Liczba semaforów w zestawie. Każdy semafor zestawu jest identyfikowany przez nieujemną liczbę całkowitą z zakresu od \fB0\fP do \fIsem_nsems\-1\fP. .P Struktura \fIipc_perm\fP jest zdefiniowana następująco (wyróżnione pola można ustawić za pomocą \fBIPC_SET\fP): .P .in +4n .EX struct ipc_perm { key_t __key; /* Klucz podany w semget(2) */ uid_t \fBuid\fP; /* Efektywny UID właściciela */ gid_t \fBgid\fP; /* Efektywny GID właściciela */ uid_t cuid; /* Efektywny UID twórcy */ gid_t cgid; /* Efektywny GID twórcy */ unsigned short \fBmode\fP; /* Uprawnienia */ unsigned short __seq; /* Numer sekwencji */ }; .EE .in .P Najmniej znaczące 9 bitów pola \fImode\fP struktury \fIipc_perm\fP definiuje uprawnienia dostępu do segmentu pamięci dzielonej. Istnieją następujące bity uprawnień: .TS l l. 0400 Odczyt przez użytkownika 0200 Zapis przez użytkownika 0040 Odczyt przez grupę 0020 Zapis przez grupę 0004 Odczyt przez pozostałych 0002 Zapis przez pozostałych .TE .P Dla zestawu semaforów \[Bq]zapis\[rq] znaczy w praktyce \[Bq]modyfikację\[rq]. Bity 0100, 0010 i 0001 (bity praw do uruchamiania) nie są przez system wykorzystywane. .P Poprawne wartości parametru \fIop\fP to: .TP \fBIPC_STAT\fP Kopiuje informacje ze struktury kontrolnej jądra skojarzonej z \fIsemid\fP do struktury \fIsemid_ds\fP wskazywanej przez \fIarg.__buf\fP. Argument \fIsemnum\fP jest ignorowany. Wywołujący musi mieć uprawnienie odczytu zestawu semaforów. .TP \fBIPC_SET\fP Zapis wartości niektórych pól struktury \fBsemid_ds\fP wskazywanej przez parametr \fIarg.buf\fP do struktury kontrolnej zestawu semaforów. Pole \fBsem_ctime\fP zostanie automatycznie uaktualnione. .IP Zaktualizowane mogą również zostać następujące pola tej struktury: \fIsem_perm.uid\fP, \fIsem_perm.gid\fP i (9 najmniej znaczących bitów z) \fIsem_perm.mode\fP. .IP Efektywny identyfikator użytkownika procesu wywołującego musi odpowiadać właścicielowi (\fIsem_perm.uid\fP) lub twórcy (\fIsem_perm.cuid\fP) zestawu semaforów albo wywołujący musi być uprzywilejowany. Argument \fIsemnum\fP jest pomijany. .TP \fBIPC_RMID\fP Usuwa natychmiast zestaw semaforów. Wznawia wszystkie procesy zablokowane w wywołaniu \fBsemop\fP(2) (wywołanie to zasygnalizuje błąd i ustawi zmienną \fIerrno\fP na \fBEIDRM\fP). 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 \fIsemnum\fP jest pomijany. .TP \fBIPC_INFO\fP (specyficzne dla Linuksa) Zwraca w strukturze, na którą wskazuje \fIarg.__buf\fP, informacje o systemowych ograniczeniach i parametrach semaforów. Struktura jest typu \fIseminfo\fP i jest zdefiniowana w \fI\fP, pod warunkiem, że zdefiniowano również makro \fB_GNU_SOURCE\fP: .IP .in +4n .EX 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) */ }; .EE .in .IP Ustawienia \fIsemmsl\fP, \fIsemmns\fP, \fIsemopm\fP oraz \fIsemmni\fP można zmienić za pomocą plików w \fI/proc/sys/kernel/sem\fP; szczegóły można znaleźć w podręczniku \fBproc\fP(5). .TP \fBSEM_INFO\fP (specyficzne dla Linuksa) Zwraca strukturę \fIseminfo\fP zawierającą te same informacje co w przypadku \fBIPC_INFO\fP, z tym wyjątkiem, że w następujących polach zwracane są informacje o zasobach systemowych wykorzystywanych przez semafory: pole \fIsemusz\fP zwraca liczbę zestawów semaforów istniejących obecnie w systemie; pole \fIsemaem\fP zwraca całkowitą liczbę semaforów we wszystkich zestawach semaforów w systemie. .TP \fBSEM_STAT\fP (specyficzne dla Linuksa) Zwraca strukturę \fIsemid_ds\fP, taką jak dla \fBIPC_STAT\fP. Jednakże parametr \fIsemid\fP nie jest identyfikatorem segmentu, ale indeksem wewnętrznej tablicy jądra przechowującej informacje o wszystkich segmentach zestawach semaforów w systemie. .TP \fBSEM_STAT_ANY\fP (specyficzne dla Linuksa, od Linuksa 4.17) Zwraca strukturę \fIsemid_ds\fP, jak dla \fBSEM_STAT\fP. Jednak \fIsem_perm.mode\fP nie jest sprawdzany pod kątem uprawnień odczytu do \fIsemid\fP co oznacza, że każdy użytkownik może wykonać tę operację (podobnie jak każdy użytkownik może odczytać \fI/proc/sysvipc/sem\fP, pozyskując te same informacje). .TP \fBGETALL\fP Zwraca (bieżącą) wartość \fBsemval\fP dla wszystkich semaforów z zestawu, umieszczając je w tablicy \fIarg.array\fP. Argument \fIsemnum\fP jest pomijany. Proces wywołujący musi mieć prawa do odczytu zestawu semaforów. .TP \fBGETNCNT\fP Zwraca wartość \fBsemncnt\fP skojarzoną z semaforem o numerze \fIsemnum\fP w zestawie (tzn. liczbę procesów oczekujących na zwiększenie wartości przez semafor). Proces wywołujący musi mieć prawa do odczytu zestawu semaforów. .TP \fBGETPID\fP Zwraca wartość \fBsempid\fP skojarzoną z semaforem o numerze \fIsemnum\fP 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. .TP \fBGETVAL\fP Zwraca \fBsemval\fP (tj. wartość semafora) semafora o numerze \fIsemnum\fP w zestawie semaforów. Proces wywołujący musi mieć prawa do odczytu zestawu semaforów. .TP \fBGETZCNT\fP Zwraca wartość \fBsemzcnt\fP skojarzoną z semaforem o numerze \fIsemnum\fP w zestawie (tzn. liczbę procesów oczekujących na osiągnięcie przez semafor wartości 0). Proces wywołujący musi mieć prawa do odczytu zestawu semaforów. .TP \fBSETALL\fP Przypisuje wartości \fBsemval\fP wszystkim semaforom zestawu, korzystając z tablicy \fIarg.array\fP, jednocześnie aktualizuje pole \fIsem_ctime\fP struktury \fIsemid_ds\fP skojarzonej z zestawem. Wpisy wycofania (undo; patrz \fBsemop\fP(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 \fBsemop\fP(2), to te procesy są wznawiane. Argument \fIsemnum\fP jest pomijany. Proces wywołujący musi mieć prawa do modyfikacji (zapisu) zestawu semaforów. .TP \fBSETVAL\fP Przypisuje wartość \fBsemval\fP do \fIarg.val\fP semafora o numerze \fIsemnum\fP w zestawie, aktualizując jednocześnie pole \fIsem_ctime\fP struktury \fIsemid_ds\fP 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 \fBsemop\fP(2), to te procesy są wznawiane. Proces wywołujący funkcję musi mieć prawa do modyfikacji zestawu semaforów. .SH "WARTOŚĆ ZWRACANA" Po pomyślnym zakończeniu, \fBsemctl\fP() zwraca nieujemną wartość zależną od parametru \fIop\fP: .TP \fBGETNCNT\fP wartość \fBsemncnt\fP. .TP \fBGETPID\fP wartość \fBsempid\fP. .TP \fBGETVAL\fP wartość \fBsemval\fP. .TP \fBGETZCNT\fP wartość \fBsemzcnt\fP. .TP \fBIPC_INFO\fP 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 \fBSEM_STAT\fP lub \fBSEM_STAT_ANY\fP, aby otrzymać informacje o wszystkich zestawach semaforów w systemie). .TP \fBSEM_INFO\fP tak jak \fBIPC_INFO\fP. .TP \fBSEM_STAT\fP identyfikator zestawu semaforów, którego indeks został podany w \fIsemid\fP. .TP \fBSEM_STAT_ANY\fP tak jak \fBSEM_STAT\fP. .P Dla wszystkich pozostałych wartości \fIop\fP w razie pomyślnego zakończenia zwracane jest 0. .P W razie błędu \fBsemctl\fP() zwraca \-1, a zmiennej \fIerrno\fP zostanie nadana wartość określająca rodzaj błędu. .SH BŁĘDY .TP \fBEACCES\fP Argument \fIop\fP ma jedną z wartości: \fBGETALL\fP, \fBGETPID\fP, \fBGETVAL\fP, \fBGETNCNT\fP, \fBGETZCNT\fP, \fBIPC_STAT\fP, \fBSEM_STAT\fP, \fBSEM_STAT_ANY\fP, \fBSETALL\fP, lub \fBSETVAL\fP, a proces wywołujący nie ma wystarczających uprawnień do działania na zbiorze semaforów oraz nie ma ustawionego przywileju \fBCAP_IPC_OWNER\fP (ang. capability) w przestrzeni nazw użytkownika, która zarządza jego przestrzenią nazw IPC. .TP \fBEFAULT\fP Adres wskazywany przez \fIarg.buf\fP lub \fIarg.array\fP jest niedostępny. .TP \fBEIDRM\fP Zestaw semaforów został usunięty. .TP \fBEINVAL\fP Niepoprawna wartość parametru \fIop\fP lub \fIsemid\fP. Albo: w przypadku operacji \fBSEM_STAT\fP wartość indeksu podana w parametrze \fIsemid\fP odwoływała się do obecnie nieużywanego elementu tablicy. .TP \fBEPERM\fP Parametr \fIop\fP jest równy \fBIPC_SET\fP lub \fBIPC_RMID\fP, ale identyfikator efektywnego użytkownika procesu wywołującego nie jest twórcą (określonym w \fIsem_perm.cuid\fP) ani właścicielem (określonym w \fIsem_perm.uid\fP) zestawu semaforów, a proces nie ma przywileju \fBCAP_SYS_ADMIN\fP. .TP \fBERANGE\fP Argument \fIop\fP ma wartość \fBSETALL\fP lub \fBSETVAL\fP, ale przekazywana wartość semafora \fBsemval\fP (dla któregoś z semaforów zestawu) jest mniejsza od 0 lub większa od wartości ograniczenia systemowego \fBSEMVMX\fP. .SH WERSJE .\" POSIX.1-2001, POSIX.1-2008 .\" POSIX.1 określa pole \fIsem_nsems\fP struktury \fIsemid_ds\fP jako będące typu \fIunsigned\ short\fP 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 \fIunsigned\ long\fP. .SS "Wartość sempid" POSIX.1 definiuje \fIsempid\fP jako "identyfikator procesu ostatniej operacji" na semaforze i wprost zauważa, że wartość tak jest ustawiana przez pomyślne wywołanie \fBsemop\fP(2), z implikacją, że żaden inny interfejs nie wpływa na wartość \fIsempid\fP. .P .\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin 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ą \fIsempid\fP również przy innych operacjach aktualizujących wartość semafora: operacjach \fBSETVAL\fP i \fBSETALL\fP, jak również dostosowaniach semafora wykonywanych przy zakończeniu procesu jako konsekwencji użycia flagi \fBSEM_UNDO\fP (zob. \fBsemop\fP(2)). .P .\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f Linux aktualizuje \fIsempid\fP również przy operacjach \fBSETVAL\fP i dostosowaniach semafora. Jednak, nieco niekonsekwentnie, do wersji Linuksa 4.5 włącznie, jądro nie aktualizowało \fIsempid\fP przy operacjach \fBSETALL\fP. Skorygowano to w Linuksie 4.6. .SH STANDARDY POSIX.1\-2008. .SH HISTORIA .\" SVr4 documents more error conditions EINVAL and EOVERFLOW. POSIX.1\-2001, SVr4. .P Niektóre pola struktury \fIstruct semid_ds\fP były w Linuksie 2.2 typu \fIshort\fP, ale stały się typu \fIlong\fP 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 \fBIPC_64\fP w \fIop\fP). .P .\" POSIX.1-2001, POSIX.1-2008 We wcześniejszych wersjach biblioteki glibc unia \fIsemun\fP była zdefiniowana w \fI\fP, jednakże POSIX.1 wymaga, żeby to program wywołujący definiował tę unię. Wersje glibc, które \fInie\fP definiują tej unii, definiują makro \fB_SEM_SEMUN_UNDEFINED\fP w \fI\fP. .SH UWAGI Operacje \fBIPC_INFO\fP, \fBSEM_STAT\fP oraz \fBSEM_INFO\fP są używane przez program \fBipcs\fP(1) w celu dostarczenia informacji o zajmowanych zasobach. W przyszłości operacje te mogą zostać zmodyfikowane lub przeniesione do interfejsu systemu plików \fI/proc\fP. .P Na wywołanie \fBsemctl\fP() wpływa następujące ograniczenie systemowe dotyczące zbioru semaforów: .TP \fBSEMVMX\fP Maksymalna wartość \fBsemval\fP: zależna od implementacji (32767). .P W celu uzyskania lepszej przenośności, najlepiej zawsze wywoływać \fBsemctl\fP() z czterema argumentami. .SH PRZYKŁADY Zobacz \fBshmop\fP(2). .SH "ZOBACZ TAKŻE" \fBipc\fP(2), \fBsemget\fP(2), \fBsemop\fP(2), \fBcapabilities\fP(7), \fBsem_overview\fP(7), \fBsysvipc\fP(7) .PP .SH TŁUMACZENIE Tłumaczenie niniejszej strony podręcznika: Rafał Lewczuk , Andrzej Krzysztofowicz , Robert Luberda i Michał Kułach . .PP Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License w wersji 3 .UE lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI. .PP Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej .MT manpages-pl-list@lists.sourceforge.net .ME .