Linux Certif

Toute la documentation sur la certification Linux LPI

semctl

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)