Provided by:
manpages-pl-dev_20051117-1_all 
NAZWA
semctl - sterowanie semaforami
SKŁADNIA
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semctl(int semid, int semnum, int cmd, ...);
OPIS
Funkcja semctl wykonuje operację sterującą określoną przez cmd na
zestawie semaforów określonym przez semid lub na semnum-tym semaforze
tego zestawu. (Numeracja semaforów zaczyna się od 0.)
Funkcja ta posiada trzy lub cztery argumenty. Gdy jest ich cztery,
wywołanie ma postać semctl(semid,semnum,cmd,arg), gdzie czwarty
argument arg jest typu union semun zdefiniowanego następująco:
#if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED)
/* union semun jest zdefiniowana w <sys/sem.h> */
#else
/* dla zgodności z X/OPEN musimy sami sobie zdefiniować */
union semun {
int val; /* wartość dla SETVAL */
struct semid_ds *buf; /* bufor dla IPC_STAT i IPC_SET */
unsigned short *array; /* tablica dla GETALL i SETALL */
/* Część specyficzna dla Linuksa: */
struct seminfo *__buf; /* bufor dla IPC_INFO */
};
#endif
Dozwolone wartości parametru cmd to:
IPC_STAT Kopiowanie informacji ze struktury kontrolnej zestawu
semaforów do struktury wskazywanej przez arg.buf. Argument
semnum jest pomijany. Proces wywołujący funkcję musi mieć
prawa do odczytu zestawu semaforów.
IPC_SET Zapis wartości niektórych pól struktury semid_ds
wskazywanej przez arg.buf do struktury kontrolnej zestawu
semaforów z jednoczesnym uaktualnieniem pola sem_ctime (tj.
przypisaniem mu aktualnego wskazania czasu). Pola zadanej
struktury struct semid_ds wskazywanej przez arg.buf,
których wartości są kopiowane to:
sem_perm.uid
sem_perm.gid
sem_perm.mode /* tylko 9 najmniej znaczących bitów */
Efektywny identyfikator użytkownika procesu wywołującego
musi wskazywać na administratora systemu, twórcę zestawu
semaforów lub jego właściciela. Argument semnum jest
pomijany.
IPC_RMID Natychmiastowe usunięcie zestawu semaforów i związanych z
nim struktur danych. Wszystkie procesy oczekujące zostaną
wznowione i wywołania, które wykonywały zasygnalizują błąd
(przypisując zmiennej errno wartość EIDRM). Efektywny
identyfikator użytkownika procesu wywołającego funkcję musi
wskazywać na administratora systemu, twórce zestawu
semaforów lub jego właściciela. Argument semnum jest
pomijany.
GETALL Zwraca wartości semval wszystkich semaforów z zestawu
umieszczając je w tablicy arg.array. Argument semnum jest
pomijany. Proces wywołujący funkcję musi mieć prawa do
odczytu zestawu semaforów.
GETNCNT Zwraca wartość semncnt skojarzoną z semaforem numer semnum
semaforem (tzn. liczbę procesów oczekujących na zwiększenie
się wartości semval skojarzonej z semaforem numer semnum).
Proces wywołujący funkcję 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
ostatnio wykonał semop na semaforze). Proces wywołujący
funkcję musi mieć prawa do odczytu zestawu semaforów.
GETVAL Zwraca wartość semval semafora o numerze semnum w zestawie.
Proces wywołujący funkcję 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 funkcję musi mieć prawa do odczytu
zestawu semaforów.
SETALL Przypisuje wartości semval wszystkim semaforom zestawu,
korzystając z tablicy arg.array, jednocześnie uaktualnia
pole sem_ctime struktury semid_ds skojarzonej z zestawem.
Wszystkie struktury sem_undo skojarzone z zestawem są we
wszystkich procesach zwalniane. Procesy oczekujące na
osiągnięcie przez poszczególne semafory określonych
wartości są wznawiane, jeśli któraś z wartości semval
stanie się zerowa lub wzrośnie. Argument semnum jest
pomijany. Proces wywołujący funkcję musi mieć prawa do
modyfikacji zestawu semaforów.
SETVAL Przypisuje wartość arg.val polu semval semafora o numerze
semnum w zestawie. Pole sem_ctime struktury semid_ds
skojarzonej z semaforem jest uaktualniane. Wszystkie
struktury sem_undo skojarzone z semaforem są zwalniane.
Procesy oczekujące na osiągnięcie przez semafor określonych
wartości zostaną wznowione, jeśli semval stanie się równe
zeru lub wzrośnie. Proces wywołujący funkcję musi mieć
prawa do odczytu zestawu semaforów.
WARTOŚĆ ZWRACANA
W przypadku wystąpienia błędu, semctl zwróci -1, przypisując zmiennej
errno wartość określającą rodzaj błędu. W przeciwnym przypadku
zwrócona zostanie nieujemna wartość zależna od określonej przez cmd
wykonywanej operacji w następujący sposób:
GETNCNT wartość semncnt.
GETPID wartość sempid.
GETVAL wartość semval.
GETZCNT wartość semzcnt.
Dla wszystkich pozostałych wartości cmd w razie pomyślnego zakończenia
zwracane jest 0.
BŁĘDY
W przypadku wystąpienia błędu, zmienna errno przyjmie jedną z
następujących wartośći:
EACCES Proces wywołujący funkcję nie ma odpowiednich praw
wymaganych do wykonania operacji cmd.
EFAULT Adres wskazywany przez arg.buf lub arg.array jest
niedostępny.
EIDRM Zestaw semaforów został usunięty.
EINVAL Niewłaściwa wartość parametru cmd lub semid.
EPERM Argument cmd ma wartość IPC_SET lub IPC_RMID, ale proces
wywołujący funkcję nie ma uprawnień upoważniających do
wykonania tego polecenia.
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.
UWAGI
Polecenia sterujące IPC_INFO, SEM_STAT i SEM_INFO są używane przez
program ipcs(8) do pobierania informacji o używanych zasobach w
systemie. Jeśli zajdzie potrzeba, polecenia te mogą w przyszłości ulec
zmianie lub ich obsługa może zostać zawarta w systemie plików /proc.
Niektóre pola struktury struct semid_ds były w Linuksie 2.2 typu short
a 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 i nowe wywołania za pomocą znacznika IPC_64 w cmd.)
Dla wywołania semctl obowiązują następujące ograniczenia systemowe:
SEMVMX Maksymalna wartość semval: zależna od implementacji (32767).
W celu uzyskania lepszej przenośności, najlepiet zawsze wywoływać
semctl z czterema argumentami.
Pod Linuksem funkcja semctl nie jest funkcją systemową, ale jest
zaimplementowana poprzez funkcję systemową ipc(2).
ZGODNE Z
SVr4, SVID. W SVr4 udokumntowano jeszcze EINVAL i EOVERFLOW.
ZOBACZ TAKŻE
ipc(2), shmget(2), shmat(2), shmdt(2), ipc(5)