SEMCTL(2)

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
Uwaga! To tłumaczenie może być nieaktualne!

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)

INFORMACJE O TŁUMACZENIU
Powyższe tłumaczenie pochodzi z nieistniejącego już Projektu Tłumaczenia Manuali i może nie być aktualne. W razie zauważenia różnic między powyższym opisem a rzeczywistym zachowaniem opisywanego programu lub funkcji, prosimy o zapoznanie się z oryginalną (angielską) wersją strony podręcznika za pomocą polecenia:

    man --locale=C 2 semctl

Prosimy o pomoc w aktualizacji stron man - więcej informacji można znaleźć pod adresem http://sourceforge.net/projects/manpages-pl/.