.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com>
.\" Modified 2002-01-08, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com>
.\" Modified 2004-05-27, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\"	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.
.\"
.\"*******************************************************************
.\" This file is distributed under the same license as original manpage
.\" Copyright of the original manpage:
.\" Copyright © 1993 Giorgio Ciucci 
.\" Copyright © of Polish translation:
.\" Rafał Lewczuk (PTM) <R.Lewczuk@elka.pw.edu.p>, 1999.
.\" Andrzej Krzysztofowicz (PTM) <ankry@mif.pg.gda.pl>, 2002.
.\" Robert Luberda <robert@debian.org>, 2013.
.\" Michał Kułach <michal.kulach@gmail.com>, 2013, 2014.
.TH SEMOP 2 2014\-05\-10 Linux "Podręcznik programisty Linuksa"
.SH NAZWA
semop, semtimedop \- operacje na semaforach Systemu V
.SH SKŁADNIA
.nf
\fB#include <sys/types.h>\fP
\fB#include <sys/ipc.h>\fP
\fB#include <sys/sem.h>\fP
.sp
\fBint semop(int \fP\fIsemid\fP\fB, struct sembuf *\fP\fIsops\fP\fB, size_t \fP\fInsops\fP\fB);\fP
.sp
\fBint semtimedop(int \fP\fIsemid\fP\fB, struct sembuf *\fP\fIsops\fP\fB, size_t \fP\fInsops\fP\fB,\fP
\fB               const struct timespec *\fP\fItimeout\fP\fB);\fP
.fi
.sp
.in -4n
Wymagane ustawienia makr biblioteki glibc (patrz \fBfeature_test_macros\fP(7)):
.in
.sp
\fBsemtimedop\fP(): _GNU_SOURCE
.SH OPIS
Z każdym semaforem w zestawie semaforów Systemu\ V są skojarzone następujące
wartości:
.sp
.in +4n
.nf
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;   /* identyfikator procesu, który wykonał
                             ostatnią operację */
.sp
.in -4n
.fi
\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 określa operację, która ma być wykonana na pojedynczym
semaforze. Struktura \fIstruct sembuf\fP zawiera następujące pola:
.sp
.in +4n
.nf
unsigned short sem_num;  /* numer semafora */
short          sem_op;   /* operacja na semaforze */
short          sem_flg;  /* znaczniki operacji */
.sp
.in -4n
.fi
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.
.PP
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.

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.
.PP
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.
.PP
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.
.IP \(bu
Upłynął limit czasu podany w parametrze \fItimeout\fP wywołania
\fBsemtimedop\fP(): wywołanie systemowe  kończy się niepowodzeniem, ustawiając
zmienną \fIerrno\fP na \fBEAGAIN\fP.
.PP
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.
.IP \(bu
Upłynął limit czasu podany w parametrze \fItimeout\fP wywołania
\fBsemtimedop\fP(): wywołanie systemowe  kończy się niepowodzeniem, ustawiając
zmienną \fIerrno\fP na \fBEAGAIN\fP.
.PP
.\" 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.
.PP
\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().
.SH "WARTOŚĆ ZWRACANA"
\fBsemop\fP() i \fBsemtimedop\fP zwracają 0, jeśli zakończą się pomyślnie. W
przeciwnym wypadku zwracają \-1 i przypisują zmiennej \fIerrno\fP wartość
wskazującą na rodzaj błędu.
.SH BŁĘDY
W przypadku wystąpienia błędu, zmiennej \fIerrno\fP przypisywana jest jedna z
następujących wartości:
.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 atrybutu \fBCAP_IPC_OWNER\fP.
.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 WERSJE
\fBsemtimedop\fP()  po raz pierwszy pojawiło się w Linuksie 2.5.52, ale zostało
przeniesione (backport) do jądra 2.4.22. Biblioteka glibc obsługuje
\fBsemtimedop\fP() od wersji 2.3.3.
.SH "ZGODNE Z"
.\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC.
SVr4, POSIX.1\-2001.
.SH UWAGI
.\" Like Linux, the FreeBSD man pages still document
.\" the inclusion of these header files.
Dołączenie \fI<sys/types.h>\fP i \fI<sys/ipc.h>\fP 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.

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).
.PP
\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.

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 \- 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 BŁĘDY). 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.
.PP
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
.\" This /proc file is not available in Linux 2.2 and earlier -- MTK
Maksymalna liczba operacji dozwolonych dla pojedynczego wywołania
\fBsemop\fP(): 32 (pod Linuksem to ograniczenie można odczytać i zmienić,
używając trzeciego pola w pliku \fI/proc/sys/kernel/sem\fP).
.TP 
\fBSEMVMX\fP
Maksymalna dozwolona wartość \fIsemval\fP: zależy od implementacji (32767).
.PP
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.

.\" 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
Jądra 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 jądrze 2.6.11.
.SH PRZYKŁAD
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.
.nf

    struct sembuf sops[2];
    int semid;

    /* Pominięto kod ustawiający \fIsemid\fP */

    sops[0].sem_num = 0;        /* Działaj na semaforze 0 */
    sops[0].sem_op = 0;         /* Czekaj na wartość równą 0 */
    sops[0].sem_flg = 0;

    sops[1].sem_num = 0;        /* Działaj na semaforze 0 */
    sops[1].sem_op = 1;         /* Zwiększ wartość o jeden */
    sops[1].sem_flg = 0;

    if (semop(semid, sops, 2) == \-1) {
        perror("semop");
        exit(EXIT_FAILURE);
    }
.fi
.SH "ZOBACZ TAKŻE"
\fBclone\fP(2), \fBsemctl\fP(2), \fBsemget\fP(2), \fBsigaction\fP(2),
\fBcapabilities\fP(7), \fBsem_overview\fP(7), \fBsvipc\fP(7), \fBtime\fP(7)
.SH "O STRONIE"
Angielska wersja tej strony pochodzi z wydania 3.71 projektu Linux
\fIman\-pages\fP. Opis projektu, informacje dotyczące zgłaszania błędów, oraz
najnowszą wersję oryginału można znaleźć pod adresem
\%http://www.kernel.org/doc/man\-pages/.
.SH 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>.
.PP
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ą \fB 3.71 \fPoryginału.