msgctl(2) System Calls Manual msgctl(2) NAZWA msgctl - steruje kolejkami komunikatow Systemu V BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include int msgctl(int msqid, int op, struct msqid_ds *buf); OPIS msgctl() wykonuje operacje okreslona przez parametr op na kolejce komunikatow Systemu V o identyfikatorze msqid. Struktura danych msqid_ds jest zdefiniowana w nastepujaco: struct msqid_ds { struct ipc_perm msg_perm; /* Wlasnosci i uprawnienia */ time_t msg_stime; /* Czas ostatniego msgsnd(2) */ time_t msg_rtime; /* Czas ostatniego msgrcv(2) */ time_t msg_ctime; /* Czas utworzenia lub ostatniej zmiany przez msgctl() */ unsigned long msg_cbytes; /* # bajtow w kolejce */ msgqnum_t msg_qnum; /* # liczba komunikatow w kolejce */ msglen_t msg_qbytes; /* Maksymalna # bajtow w kolejce */ pid_t msg_lspid; /* PID ostatniego msgsnd(2) */ pid_t msg_lrpid; /* PID ostatniego msgrcv(2) */ }; Pola struktury msqid_ds sa nastepujace: msg_perm Jest to struktura ipc_perm (zob. nizej), ktora okresla prawa dostepu do kolejki komunikatow. msg_stime Czas ostatniego wykonania funkcji systemowej msgsnd(2). msg_rtime Czas ostatniego wykonania funkcji systemowej msgrcv(2). msg_ctime Czas utworzenia kolejki lub czas ostatniej operacji IPC_SET msgctl(). msg_cbytes Liczba bajtow we wszystkich komunikatach znajdujacych sie aktualnie w kolejce. Jest to niestandardowe rozszerzenie Linuksa, ktore nie jest okreslone przez POSIX. msg_qnum Liczba komunikatow znajdujacych sie aktualnie w kolejce. msg_qbytes Maksymalna liczba bajtow tekstu komunikatu, na jaka pozwala kolejka. msg_lspid Identyfikator procesu, ktory ostatni wykonal funkcje systemowa msgsnd(2). msg_lrpid identyfikator procesu, ktory ostatni wykonal funkcje systemowa msgrcv(2). Struktura ipc_perm jest zdefiniowana nastepujaco (wyroznione pola mozna ustawic za pomoca IPC_SET): struct ipc_perm { key_t __key; /* Klucz podany w msgget(2) */ uid_t uid; /* Efektywny UID wlasciciela */ gid_t gid; /* Efektywny GID wlasciciela */ uid_t cuid; /* Efektywny UID tworcy */ gid_t cgid; /* Efektywny GID tworcy */ unsigned short mode; /* Uprawnienia */ unsigned short __seq; /* Numer sekwencji */ }; Najmniej znaczace 9 bitow pola mode struktury ipc_perm definiuje uprawnienia dostepu do kolejki komunikatow. Istnieja nastepujace bity uprawnien: 0400 Odczyt przez uzytkownika 0200 Zapis przez uzytkownika 0040 Odczyt przez grupe 0020 Zapis przez grupe 0004 Odczyt przez pozostalych 0002 Zapis przez pozostalych Bity 0100, 0010 i 0001 (bity praw do uruchamiania) nie sa przez system wykorzystywane. Poprawne wartosci parametru op to: IPC_STAT Kopiowanie informacji ze struktury kontrolnej kolejki komunikatow skojarzonej z msqid do struktury wskazywanej przez buf. Wywolujacy musi miec prawo odczytu kolejki komunikatow. IPC_SET Zapis wartosci niektorych pol struktury msqid_ds wskazywanej przez parametr buf do struktury kontrolnej kolejki komunikatow. Pole msg_ctime zostanie automatycznie uaktualnione. Zaktualizowane moga rowniez zostac nastepujace pola tej struktury: msg_qbytes, msg_perm.uid, msg_perm.gid i (9 najmniej znaczacych bitow z) msg_perm.mode. Efektywny identyfikator uzytkownika musi wskazywac na wlasciciela (msg_perm.uid) lub na tworce (msg_perm.uid) kolejki komunikatow albo proces wywolujacy musi byc uprzywilejowany. Odpowiednie uprawnienia (Linux: przywilej CAP_SYS_RESOURCE) sa rowniez wymagane, aby nadac polu msg_qbytes wartosc wieksza niz parametr systemowy MSGMNB. IPC_RMID Usuwa natychmiast kolejke komunikatow. Wznawia wszystkie procesy oczekujace na zapis lub odczyt z kolejki (wywolania, ktore sie wykonywaly zasygnalizuja blad i ustawia zmienna errno na EIDRM). Proces wywolujacy te funkcje musi miec odpowiednie uprawnienia albo jego efektywny identyfikator uzytkownika musi wskazywac na tworce lub na wlasciciela kolejki komunikatow. Trzeci argument do msgctl() jest w tym wypadku ignorowany. IPC_INFO (specyficzne dla Linuksa) Zwraca w strukturze, na ktora wskazuje buf, informacje o systemowych ograniczeniach i parametrach kolejek komunikatow. Struktura jest typu msginfo (dlatego wymagane jest rzutowanie) i jest zdefiniowana w , pod warunkiem, ze zdefiniowano rowniez makro _GNU_SOURCE: struct msginfo { int msgpool; /* Rozmiar w kibibajtach puli buforow uzywanej do przechowywania danych komunikatu; nieuzywane przez jadro */ int msgmap; /* Maksymalna liczba wpisow w mapie komuni- katu; nieuzywane przez jadro */ int msgmax; /* Maksymalna liczba bajtow, ktore mozna zapisac w pojedynczej wiadomosci */ int msgmnb; /* Maksymalna liczba bajtow, ktore mozna zapisac do kolejki; uzywane do inicjowania msg_qbytes podczas tworzenia kolejki (msgget(2)) */ int msgmni; /* Maksymalna liczba kolejek komunikatow */ int msgssz; /* Rozmiar segmentu komunikatu; nieuzywane przez jadro */ int msgtql; /* Maksymalna liczba komunikatow we wszystkich kolejkach w systemie; nieuzywane przez jadro */ unsigned short msgseg; /* Maksymalna liczba segmentow; nieuzywane przez jadro */ }; Ustawienia msgmni, msgmax oraz msgmnb mozna zmienic za pomoca plikow /proc o nazwach takich samych, jak nazwy tych ustawien; szczegoly mozna znalezc w podreczniku proc(5). MSG_INFO (specyficzne dla Linuksa) Zwraca strukture msginfo zawierajaca te same informacje co w przypadku IPC_INFO, z tym wyjatkiem, ze w nastepujacych polach zwracane sa informacje o zasobach systemowych wykorzystywanych przez kolejki komunikatow: pole msgpool zwraca liczbe kolejek komunikatow istniejacych obecnie w systemie; pole msgmap zwraca calkowita liczbe komunikatow we wszystkich kolejkach w systemie, a pole msgtql zwraca calkowita liczbe bajtow we wszystkich komunikatach z wszystkich kolejek w systemie. MSG_STAT (specyficzne dla Linuksa) Zwraca strukture msqid_ds, taka jak dla IPC_STAT. Jednakze parametr msqid nie jest identyfikatorem kolejki, ale indeksem wewnetrznej tablicy jadra przechowujacej informacje o wszystkich kolejkach w systemie. MSG_STAT_ANY (specyficzne dla Linuksa, od Linuks 4.17) Zwraca strukture msqid_ds, jak dla MSG_STAT. Jednak msg_perm.mode nie jest sprawdzany pod katem uprawnien odczytu do msqid co oznacza, ze kazdy uzytkownik moze wykonac te operacje (podobnie jak kazdy uzytkownik moze odczytac /proc/sysvipc/msg, pozyskujac te same informacje). WARTOSC ZWRACANA W razie powodzenia IPC_STAT, IPC_SET i IPC_RMID zwracaja 0. Pomyslnie zakonczone operacje IPC_INFO i MSG_INFO zwracaja indeks najwyzszego uzywanego wpisu w wewnetrznej tablicy jadra przechowujacej informacje o wszystkich kolejkach komunikatow. (Informacji tej mozna uzyc w operacjach MSG_STAT lub MSG_STAT_ANY, aby otrzymac informacje o wszystkich kolejkach w systemie). Pomyslnie zakonczona operacja MSG_STAT lub MSG_STAT_ANY zwraca identyfikator kolejki o indeksie przekazanym w msqid. W razie niepowodzenia zwracane jest -1 i ustawiane jest errno wskazujac rodzaj bledu. BLEDY EACCES Parametr op jest rowny IPC_STAT lub MSG_STAT, ale proces wywolujacy funkcje nie ma prawa do odczytu kolejki komunikatow wskazywanej przez msqid ani nie ma przywileju CAP_IPC_OWNER (ang. capability) w przestrzeni nazw uzytkownika, ktora zarzadza jego przestrzenia nazw IPC. EFAULT Argument op ma wartosc IPC_SET lub IPC_STAT, ale buf wskazuje na niedostepny obszar pamieci. EIDRM Kolejka komunikatow zostala usunieta. EINVAL Niepoprawna wartosc parametru op lub msqid. Albo: w przypadku operacji MSG_STAT wartosc indeksu podana w parametrze msqid odwolywala sie do obecnie nieuzywanego elementu tablicy. EPERM Argument op jest rowny IPC_SET lub IPC_RMID, ale proces wywolujacy funkcje nie jest tworca (okreslonym w msg_perm.cuid) ani wlascicielem (okreslonym w msg_perm.uid) kolejki komunikatow, a wywolujacy nie jest uprzywilejowany (Linux: nie ma przywileju CAP_SYS_ADMIN). EPERM Podjeto probe (IPC_SET) zwiekszenia msg_qbytes ponad parametr systemowy MSGMNB, lecz wywolujacy nie jest uprzywilejowany (Linux: nie ma przywileju CAP_SYS_RESOURCE). STANDARDY POSIX.1-2008. HISTORIA POSIX.1-2001, SVr4. Niektore pola struktury struct msqid_ds byly w Linuksie 2.2 typu short, ale staly sie typu long w Linuksie 2.4. Aby to wykorzystac, powinna wystarczyc rekompilacja pod glibc-2.1.91 lub nowsza. (Jadro rozroznia stare wywolania od nowych za pomoca znacznika IPC_64 w op). UWAGI Operacje IPC_INFO, MSG_STAT oraz MSG_INFO sa uzywane przez program ipcs(1) w celu dostarczenia informacji o zajmowanych zasobach. W przyszlosci operacje te moga zostac zmodyfikowane lub przeniesione do interfejsu systemu plikow /proc. ZOBACZ TAKZE msgget(2), msgrcv(2), msgsnd(2), capabilities(7), mq_overview(7), sysvipc(7) TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Rafal Lewczuk , Andrzej Krzysztofowicz , Robert Luberda i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.8 2 maja 2024 r. msgctl(2)