.\" -*- coding: UTF-8 -*- .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified 1996-10-22, Eric S. Raymond .\" Modified 2002-01-08, Michael Kerrisk .\" Modified 2003-04-28, Ernie Petrides .\" Modified 2004-05-27, Michael Kerrisk .\" Modified, 11 Nov 2004, Michael Kerrisk .\" Language and formatting clean-ups .\" Added notes on /proc files .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop() .\" 2007-07-09, mtk, Added an EXAMPLE code segment. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH semop 2 "2 maja 2024 r." "Linux man\-pages 6.9.1" .SH NAZWA semop, semtimedop \- operacje na semaforach Systemu V .SH BIBLIOTEKA Standardowa biblioteka C (\fIlibc\fP, \fI\-lc\fP) .SH SKŁADNIA .nf \fB#include \fP .P \fBint semop(int \fP\fIsemid\fP\fB, struct sembuf *\fP\fIsops\fP\fB, size_t \fP\fInsops\fP\fB);\fP \fBint semtimedop(int \fP\fIsemid\fP\fB, struct sembuf *\fP\fIsops\fP\fB, size_t \fP\fInsops\fP\fB,\fP \fB const struct timespec *_Nullable \fP\fItimeout\fP\fB);\fP .fi .P .RS -4 Wymagane ustawienia makr biblioteki glibc (patrz \fBfeature_test_macros\fP(7)): .RE .P \fBsemtimedop\fP(): .nf _GNU_SOURCE .fi .SH OPIS Z każdym semaforem w zestawie semaforów Systemu\ V są skojarzone następujące wartości: .P .in +4n .EX unsigned short semval; /* wartość semafora */ unsigned short semzcnt; /* liczba oczekujących na zero */ unsigned short semncnt; /* liczba oczekujących na zwiększenie */ pid_t sempid; /* PID procesu, który jako ostatni zmodyfikował wartość semafora */ .EE .in .P \fBsemop\fP() wykonuje operacje na wybranych semaforach z zestawu wskazywanego przez \fIsemid\fP. Każdy z \fInsops\fP elementów tablicy wskazywanej przez parametr \fIsops\fP jest strukturą określającą operację, która ma być wykonana na pojedynczym semaforze. Struktura \fIstruct sembuf\fP zawiera następujące pola: .P .in +4n .EX unsigned short sem_num; /* numer semafora */ short sem_op; /* operacja na semaforze */ short sem_flg; /* znaczniki operacji */ .EE .in .P W \fIsem_flg\fP mogą zostać ustawione znaczniki operacji: \fBIPC_NOWAIT\fP i \fBSEM_UNDO\fP. Jeśli podano znaczniki \fBSEM_UNDO\fP, to operacja zostanie automatycznie cofnięta w chwili, gdy proces zakończy działanie. .P Zestaw operacji zawartych w \fIsops\fP jest wykonywany w \fIkolejności elementów tablicy\fP oraz \fIatomowo\fP, co oznacza, że operacje są wykonywane albo w całości, albo wcale. Zachowanie wywołania systemowego w sytuacji, gdy nie wszystkie operacje mogą być wykonane natychmiast, zależy od ustawienia znacznika \fBIPC_NOWAIT\fP w poszczególnych polach \fIsem_flg\fP, jak to opisano poniżej. .P Każda z operacji jest wykonywana na semaforze o numerze \fIsem_num\fP w zestawie, przy czym pierwszy semafor ma numer 0. Są trzy rodzaje operacji rozróżniane na podstawie wartości \fIsem_op\fP. .P Jeśli \fIsem_op\fP jest liczbą dodatnią, to wartość semafora (\fIsemval\fP) zostanie zwiększona o tę liczbę. Ponadto jeśli przekazano znacznik \fBSEM_UNDO\fP, to system odejmuje wartość (\fIsemop\fP) od wartości dopasowania (\fIsemadj\fP) tego semafora. Operacja ta zawsze może być wykonana \[em] nigdy nie spowoduje wstrzymania wątku. Proces wywołujący funkcję musi mieć prawo do modyfikacji zestawu semaforów. .P Jeśli \fIsem_op\fP jest równe 0, proces musi mieć prawo do odczytu zestawu semaforów. Jest to operacja "oczekiwania na zero" (wait\-for\-zero): gdy \fIsemval\fP ma wartość 0, operacja może być kontynuowana bezzwłocznie. W przeciwnym razie, jeśli w \fIsem_flg\fP przekazany został znacznik \fBIPC_NOWAIT\fP, wówczas \fBsemop\fP() zgłosi błąd, zaś zmienna \fIerrno\fP przyjmie wartość \fBEAGAIN\fP (i żadna z operacji z \fIsops\fP nie zostanie wykonana). Jeżeli proces zostanie wstrzymany przez system, wówczas wartość \fIsemzcnt\fP (liczby wątków oczekujących na osiągnięcie przez semafor wartości zero) zostanie zwiększona o 1, a wątek będzie zawieszony aż do chwili, gdy spełniony zostanie jeden z poniższych warunków: .IP \[bu] 3 \fIsemval\fP osiągnie wartość 0; wówczas wartość pola \fIsemzcnt\fP zostanie zmniejszona o 1. .IP \[bu] Zestaw semaforów zostanie usunięty: \fBsemop\fP() się nie powiedzie i przypisze zmiennej \fIerrno\fP wartość \fBEIDRM\fP. .IP \[bu] Wątek wywołujący funkcję przechwyci sygnał: wartość \fIsemzcnt\fP zostanie zmniejszona, a \fBsemop\fP() zakończy się niepowodzeniem i przypisze zmiennej \fIerrno\fP wartość \fBEINTR\fP. .P Jeśli \fIsem_op\fP ma wartość mniejszą od 0, to proces musi mieć prawo do modyfikacji zestawu semaforów. Jeśli wówczas wartość semafora \fIsemval\fP jest większa lub równa wartości bezwzględnej \fIsem_op\fP, to operacja może być kontynuowana bezzwłocznie: wartość semafora \fIsemval\fP zostanie zmniejszona o wartość bezwzględną \fIsem_op\fP. Ponadto, jeśli przekazano znacznik \fBSEM_UNDO\fP, to system dodaje całkowitą wartość \fIsem_op\fP do wartości dopasowania (\fIsemadj\fP) tego semafora. Jeśli wartość bezwzględna \fIsem_op\fP jest większa niż \fIsemval\fP, a w \fIsem_flg\fP przekazano znacznik \fBIPC_NOWAIT\fP, to \fBsemop\fP() zakończy się niepomyślnie, przypisując zmiennej \fIerrno\fP wartość \fBEAGAIN\fP (i żadna z operacji z \fIsops\fP nie zostanie wykonana). W przeciwnym wypadku \fIsemncnt\fP (licznik wątków oczekujących na zwiększenie wartości tego semafora) zostanie zwiększony o 1, a wątek nie zostanie wznowiony aż do chwili wystąpienia jednego z następujących zdarzeń: .IP \[bu] 3 \fIsemval\fP staje się większa lub równa wartości całkowitej \fIsem_op\fP: operacja przebiega teraz zgodnie z opisem powyżej. .IP \[bu] Zestaw zostanie usunięty z systemu: \fBsemop\fP() zwróci błąd i ustawi zmienną \fIerrno\fP na wartość \fBEIDRM\fP. .IP \[bu] Wątek wywołujący funkcję przechwyci sygnał: wartość \fIsemncnt\fP zostanie zmniejszona, a \fBsemop\fP() zakończy się niepowodzeniem i przypisze zmiennej \fIerrno\fP wartość \fBEINTR\fP. .P .\" and .\" .I sem_ctime Jeśli operacja zostanie zakończona pomyślnie, to wartości \fIsempid\fP każdego z semaforów wyszczególnionych w tablicy wskazywanej przez \fIsops\fP przypisany zostanie identyfikator procesu (PID) wywołującego. Ponadto polu \fIsem_otime\fP przypisany zostanie bieżący czas. .SS semtimedop() \fBsemtimedop\fP() zachowuje się tak samo jak \fBsemop\fP(), poza tym że w tych przypadkach, gdy wątek wywołujący by spał, czas trwania spania jest ograniczony przez czas określony w strukturze \fItimespec\fP, której adres jest przekazywany w parametrze \fItimeout\fP (interwał zostanie zaokrąglony w górę do dokładności zegara, a występowanie opóźnienia planisty jądra oznacza, że ten interwał może być nieznacznie przekroczony). Jeśli osiągnięto określony limit czasu, to \fBsemtimedop\fP() zwraca błąd, ustawiając \fIerrno\fP na \fBEAGAIN\fP (i żadna z operacji w \fIsops\fP nie jest wykonywana). Jeżeli parametr \fItimeout\fP jest NULL, to \fBsemtimedop\fP() zachowuje się dokładnie tak samo jak \fBsemop\fP(). .P Proszę zauważyć, że jeśli \fBsemtimedop\fP() zostanie przerwane przez sygnał, co spowoduje niepomyślne zakończenie wywołania z błędem \fBEINTR\fP, zawartość \fItimeout\fP pozostanie bez zmian. .SH "WARTOŚĆ ZWRACANA" \fBsemop\fP() i \fBsemtimedop\fP zwracają 0, jeśli zakończą się pomyślnie. W przypadku błędu zwracają \-1 i ustawiają \fIerrno\fP wskazując błąd. .SH BŁĘDY .TP \fBE2BIG\fP Wartość \fInsops\fP przekracza \fBSEMOPM\fP, maksymalną liczbę operacji wykonywanych w jednym wywołaniu. .TP \fBEACCES\fP Proces wywołujący nie ma wystarczających uprawnień do wykonania podanych operacji na semaforach 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 \fBEAGAIN\fP Operacja opatrzona znacznikiem \fBIPC_NOWAIT\fP w \fIsem_flg\fP nie może być natychmiast wykonana lub upłynął limit czasu określony w parametrze \fItimeout\fP. .TP \fBEFAULT\fP Adres wskazywany przez parametr \fIsops\fP lub \fItimeout\fP jest niedostępny. .TP \fBEFBIG\fP Numer semafora \fIsem_num\fP, do którego odnosi się jedna z operacji, jest mniejszy od 0 albo większy lub równy liczbie semaforów w zestawie. .TP \fBEIDRM\fP Zestaw semaforów został usunięty. .TP \fBEINTR\fP Wątek przechwycił sygnał podczas oczekiwania na odebranie komunikatu; patrz \fBsignal\fP(7). .TP \fBEINVAL\fP Zestaw semaforów nie istnieje lub wartość \fIsemid\fP jest mniejsza od zera, lub wartość \fInsops\fP nie jest liczbą dodatnią. .TP \fBENOMEM\fP Znacznik \fBSEM_UNDO\fP został ustawiony w \fIsem_flg\fP dla pewnej operacji, a w systemie nie ma wystarczającej ilości pamięci na utworzenie nowej struktury do przechowywania informacji o zmianach. .TP \fBERANGE\fP Dla pewnej operacji wartość \fIsem_op+semval\fP przekroczyła \fBSEMVMX\fP, czyli zależną od implementacji maksymalną wartość \fIsemval\fP. .SH STANDARDY POSIX.1\-2008. .SH WERSJE .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC. Linux 2.5.52 (przeniesione również na Linuksa 2.4.22), glibc 2.3.3. POSIX.1\-2001, SVr4. .SH UWAGI Struktury \fIsem_undo\fP nie są dziedziczone przez dzieci tworzone za pomocą \fBfork\fP(2), ale są dziedziczone przez wywołanie systemowe \fBexecve\fP(2). .P \fBsemop\fP() nie jest nigdy automatycznie uruchamiana ponownie po przerwaniu przez funkcję obsługi sygnału, niezależnie od ustawień znacznika \fBSA_RESTART\fP używanego podczas tworzenia funkcji obsługi sygnału. .P Wartość dopasowania semafora (\fIsemadj\fP) jest przypisana do procesu i semafora i jest sumą wszystkich operacji na semaforze z flagą \fBSEM_UNDO\fP, ze znakiem przeciwnym. Każdy proces ma listę wartości \fIsemadj\fP \[em] po jednej dla każdego semafora na której operuje za pomocą \fBSEM_UNDO\fP. Gdy proces się kończy wszystkie jego wartości \fIsemadj\fP przypisane do poszczególnych semaforów są do nich dodawane, co powoduje przywrócenie wartości semafora sprzed działania procesu (zob. jednak na USTERKI). Gdy wartość semafora jest ustawiane bezpośrednio za pomocą żądań \fBSETVAL\fP lub \fBSETALL\fP do \fBsemctl\fP(2), to odpowiadające wartości \fIsemadj\fP we wszystkich procesach są czyszczone. Flaga \fBCLONE_SYSVSEM\fP \fBclone\fP(2) pozwala to dzielenie listy \fIsemadj\fP przez więcej niż jeden proces, więcej szczegółów w podręczniku \fBclone\fP(2). .P Wartości \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP i \fIsemnct\fP dla semafora można odczytać za pomocą odpowiednich wywołań \fBsemctl\fP(2). .SS "Limity semaforów" Wywołania \fBsemop\fP() dotyczą następujące ograniczenia zasobów związanych z zestawami semaforów: .TP \fBSEMOPM\fP .\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK .\" See comment in Linux 3.19 source file include/uapi/linux/sem.h Maksymalna liczba dozwolonych operacji na jedno wywołanie \fBsemop\fP(). Przed Linuksem 3.19 domyślna wartość tego limitu wynosiła 32. Od Linuksa 3.19 jest to 500. Pod Linuksem, limit ten można odczytać i zmodyfikować w trzecim polu pliku \fI/proc/sys/kernel/sem\fP. \fIUwaga\fP: limit ten nie powinien wynosić ponad 1000, ponieważ istnieje ryzyko, że \fBsemop\fP() nie powiedzie się z powodu fragmentacji pamięci jądra przy przydzielaniu pamięci dla kopii tablicy \fIsops\fP. .TP \fBSEMVMX\fP Maksymalna dozwolona wartość \fIsemval\fP: zależy od implementacji (32767). .P Implementacja w systemie Linux nie nakłada wewnętrznych ograniczeń na zmianę wartości semafora podczas zakończenia procesu (\fBSEMAEM\fP), na ogólnosystemową maksymalną liczbę struktur przechowujących informacje o zmianach stanu semaforów (\fBSEMMNU\fP), ani na maksymalną dla procesu liczbę struktur przechowujących informacje o zmianach stanu semaforów. .SH USTERKI Gdy proces kończy działanie, zestaw skojarzonych z nim struktur \fIsemadj\fP jest wykorzystywany do cofnięcia efektów wszystkich operacji na semaforach, które ten proces wykonał z ustawionym znacznikiem \fBSEM_UNDO\fP. Wprowadza to trudność: jeżeli jedna (lub więcej) spośród tych zmian semaforów spowodowałby próbę zmniejszenia wartości semafora poniżej zera, to co implementacja powinna uczynić? Jednym z możliwych podejść do tego zadadnienia mogło by być zablokowanie do chwili, gdy przeprowadzenie wszystkich zmian semaforów będzie możliwe. Jest to jednakże niepożądane, gdyż spowodowałoby wymuszenie zablokowania zakończenia procesu na dowolnie długi okres. Inną możliwością jest zignorowanie wszystkich takich zmian semaforów (nieco analogiczne do niepomyślnego zakończenia, gdy dla operacji na semaforze podany jest znacznik \fBIPC_NOWAIT\fP). Linux przyjął trzecie rozwiązanie: zmniejszenie wartości semafora na tyle, na ile jest to możliwe (tzn. do zera) i umożliwienie natychmiastowej kontynuacji kończenia działania procesu. .P .\" The bug report: .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2 .\" the fix: .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2 Linux 2.6.x, gdzie x <= 10, zawierają błąd, który w pewnych okolicznościach spowoduje, że wątek czekający na zmniejszenie wartości semafora do zera nie zostanie obudzony, gdy ta wartość rzeczywiście osiągnie zero. Błąd został poprawiony w Linuksie 2.6.11. .SH PRZYKŁADY Następujący fragment kodu używa \fBsemop\fP() do atomowego oczekiwania na to, by wartość semafora 0 doszła do zera. Następnie wartość semafora jest zwiększana o jeden. .P .in +4n .EX struct sembuf sops[2]; int semid; \& /* Pomięto kod służący do ustawienia \fIsemid\fP */ \& sops[0].sem_num = 0; /* Działanie na semaforze 0 */ sops[0].sem_op = 0; /* Oczekiwanie na przyjęcie wartości 0 */ sops[0].sem_flg = 0; \& sops[1].sem_num = 0; /* Działanie na semaforze 0 */ sops[1].sem_op = 1; /* Zwiększenie wartości o jeden */ sops[1].sem_flg = 0; \& if (semop(semid, sops, 2) == \-1) { perror("semop"); exit(EXIT_FAILURE); } .EE .in .P Kolejny przykład użycia \fBsemop\fP() znajduje się w podręczniku \fBshmop\fP(2). .SH "ZOBACZ TAKŻE" \fBclone\fP(2), \fBsemctl\fP(2), \fBsemget\fP(2), \fBsigaction\fP(2), \fBcapabilities\fP(7), \fBsem_overview\fP(7), \fBsysvipc\fP(7), \fBtime\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 .