SEMGET(2)

NAZWA
semget - pobranie identyfikatora zestawu semaforów

SKŁADNIA
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>

int semget(key_t key, int nsems, int semflg);

OPIS
Wywołanie systemowe semget() zwraca identyfikator zestawu semaforów skojarzonego z parametrem key. Nowy zestaw składający się z nsems semaforów zostanie utworzony, jeśli parametr key będzie mieć wartość IPC_PRIVATE lub gdy zestaw semaforów skojarzony z key nie istnieje, a w parametrze semflg zostanie przekazany znacznik IPC_CREAT.

Jeśli w parametrze semflg podano zarówno IPC_CREAT, jak i IPC_EXCL oraz już istnieje zestaw semaforów o kluczu key, to semget() kończy się błędem, ustawiając errno na wartość EEXIST. (Działa to analogicznie do O_CREAT | O_EXCL w open(2)).

Podczas tworzenia 9 najmniej znaczących bitów argumentu semflg określa prawa dostępu do zestawu semaforów (dla właściciela, grupy i innych). Bity te mają ten sam format i takie samo znaczenie, jak parametr mode wywołania open(2) (prawa uruchamiania nie są istotne dla semaforów, natomiast prawa zapisu oznaczają możliwość zmiany wartości semaforów).

Wartości semaforów w nowo utworzonym zestawie są nieokreślone (POSIX.1-2001 jasno o tym mówi). Mimo że Linux, tak jak i wiele innych implementacji, nadaje im wartość początkową równą 0, to przenośne aplikacje nie powinny zależeć od tego zachowania i zamiast tego powinny wyraźnie inicjować semafory żądanymi wartościami.

Podczas tworzenia nowego zestawu semaforów semget() inicjuje związaną z zestawem semaforów strukturę semid_ds (patrz semctl(2)) w następujący sposób:

    sem_perm.cuid i sem_perm.uid przyjmują wartość efektywnego identyfikatora właściciela procesu wywołującego.

    sem_perm.cgid i sem_perm.gid przyjmują wartość efektywnego identyfikatora grupy procesu wywołującego.

    9 najmniej znaczących bitów pola sem_perm.mode jest kopiowanych z 9 najmniej znaczących bitów semflg.

    sem_nsems jest ustawiane na wartość nsems.

    sem_otime przyjmie wartość 0.

    sem_ctime przypisywany jest bieżący czas.

Parametr nsems może mieć wartość 0 (nie jest brany pod uwagę), jeśli nie będzie tworzony zestaw semaforów. W przeciwnym przypadku parametr nsems musi być większy od 0 i mniejszy lub równy maksymalnej liczbie semaforów w zestawie (SEMMSL).

Jeżeli zestaw semaforów już istnieje, to weryfikowane są uprawnienia.

WARTOŚĆ ZWRACANA
W przypadku pomyślnego zakończenia, funkcja zwraca identyfikator zestawu semaforów (liczbę nieujemną), a w przeciwnym przypadku zwraca -1 i przypisuje zmiennej errno stosowną wartość.

BŁĘDY
W przypadku niepowodzenia, zmiennej errno zostanie przypisana jedna z następujących wartości:

EACCES
    Zestaw semaforów identyfikowany kluczem key istnieje, ale proces wywołujący ani nie ma praw dostępu do niego, ani nie ma ustawionego atrybutu CAP_IPC_OWNER.

EEXIST
    Zestaw semaforów o identyfikatorze key istnieje, ale w parametrze semflg przekazane zostały jednocześnie oba znaczniki IPC_CREAT i IPC_EXCL.

EINVAL
    nsems jest mniejsze niż 0 lub większe niż ograniczenie liczby semaforów w zestawie (SEMMSL), lub zestaw semaforów, do którego odnosi się key już istnieje oraz nsems jest większe niż liczba semaforów w tym zestawie.

ENOENT
    Nie ma zestawu semaforów o identyfikatorze key i znacznik IPC_CREAT nie został przekazany w parametrze semflg.

ENOMEM
    Zestaw semaforów powinien zostać utworzony, ale w systemie brak jest pamięci na utworzenie nowej struktury danych.

ENOSPC
    Nastąpiła próba przekroczenia ograniczenia liczby zestawów (SEMMNI) lub łącznej liczby semaforów w systemie (SEMMNS).

ZGODNE Z
SVr4, POSIX.1-2001.

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. IPC_PRIVATE nie jest znacznikiem, ale szczególną wartością typu key_t. Jeśli wartość ta zostanie użyta jako parametr key, to system uwzględni jedynie 9 najniższych bitów parametru msgflg i (w razie powodzenia) utworzy nowy zestaw semaforów.

Wywołania semget() dotyczą następujące ograniczenia zasobów związanych z zestawami semaforów:

SEMMNI
    Maksymalna liczba zestawów semaforów w systemie: wartość zależna od lokalnych ustawień (pod Linuksem to ograniczenie można odczytać i zmienić, używając czwartego pola pliku /proc/sys/kernel/sem).

SEMMSL
    Maksymalna liczba semaforów dla danego semid: wartość zależna od implementacji (pod Linuksem to ograniczenie można odczytać i zmienić, używając pierwszego pola pliku /proc/sys/kernel/sem).

SEMMNS
    Maksymalna liczba semaforów w systemie: wartość zależna od lokalnych ustawień (pod Linuksem to ograniczenie można odczytać i zmienić, używając drugiego pola pliku /proc/sys/kernel/sem). Wartości większe niż SEMMSL * SEMMNI nie mają znaczenia.

USTERKI
Nazwa IPC_PRIVATE prawdopodobnie nie jest najszczęśliwsza. IPC_NEW w sposób bardziej przejrzysty odzwierciedlałoby rolę tej wartości.

semget() nie inicjuje semaforów w zestawie semaforów. Aby zainicjować semafory, należy na zestawie semaforów użyć operacji SETVAL lub SETALL wywołania semctl(2) (W sytuacji gdy wiele procesów nie wie, który pierwszy zainicjuje zestaw semaforów, to aby uniknąć sytuacji wyścigu, można sprawdzić, czy pole sem_otime powiązanej struktury danych zwracanej przez operację IPC_STAT wywołania semctl(2) ma wartość niezerową).

ZOBACZ TAKŻE
semctl(2), semop(2), ftok(3), capabilities(7), sem_overview(7), svipc(7)

O STRONIE
Angielska wersja tej strony pochodzi z wydania 3.50 projektu Linux man-pages. Opis projektu oraz informacje dotyczące zgłaszania błędów można znaleźć pod adresem http://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ą 3.50 oryginału.