semctl

Autres langues

Langue: pl

Autres versions - même langue

Version: 2001-12-21 (fedora - 25/11/07)

Section: 2 (Appels système)

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)