msgctl(2) System Calls Manual msgctl(2) NAZWA msgctl - sterowanie kolejkami komunikatow Systemu V BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include int msgctl(int msqid, int cmd, struct msqid_ds *buf); OPIS msgctl() wykonuje operacje okreslona przez parametr cmd na kolejce komunikatow Systemu V o identyfikatorze msqid. Struktura danych msqid_ds jest zdefiniowana w nastepujaco: struct msqid_ds { struct ipc_perm msg_perm; /* Ownership and permissions */ time_t msg_stime; /* Time of last msgsnd(2) */ time_t msg_rtime; /* Time of last msgrcv(2) */ time_t msg_ctime; /* Time of creation or last modification by msgctl() */ unsigned long msg_cbytes; /* # of bytes in queue */ msgqnum_t msg_qnum; /* # number of messages in queue */ msglen_t msg_qbytes; /* Maximum # of bytes in queue */ pid_t msg_lspid; /* PID of last msgsnd(2) */ pid_t msg_lrpid; /* PID of last msgrcv(2) */ }; The fields of the msqid_ds structure are as follows: msg_perm This is an ipc_perm structure (see below) that specifies the access permissions on the message queue. msg_stime Czas ostatniego wykonania funkcji systemowej msgsnd(2). msg_rtime Czas ostatniego wykonania funkcji systemowej msgrcv(2). msg_ctime Time of creation of queue or time of last msgctl() IPC_SET operation. msg_cbytes Number of bytes in all messages currently on the message queue. This is a nonstandard Linux extension that is not specified in 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 */ }; The least significant 9 bits of the mode field of the ipc_perm structure define the access permissions for the message queue. The permission bits are as follows: 0400 Read by user 0200 Write by user 0040 Read by group 0020 Write by group 0004 Read by others 0002 Write by others Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. Poprawne wartosci parametru cmd 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 (przynajmniej 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: atrybut 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 of entries in message map; 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) Return a msqid_ds structure as for MSG_STAT. However, msg_perm.mode is not checked for read access for msqid meaning that any user can employ this operation (just as any user may read /proc/sysvipc/msg to obtain the same information). 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. On failure, -1 is returned and errno is set to indicate the error. BLEDY EACCES The argument cmd is equal to IPC_STAT or MSG_STAT, but the calling process does not have read permission on the message queue msqid, and does not have the CAP_IPC_OWNER capability in the user namespace that governs its IPC namespace. EFAULT Parametr cmd ma wartosc IPC_SET lub IPC_STAT, ale buf wskazuje na niedostepny obszar pamieci. EIDRM Kolejka komunikatow zostala usunieta. EINVAL Niepoprawna wartosc parametru cmd lub msqid. Albo: w przypadku operacji MSG_STAT wartosc indeksu podana w parametrze msqid odwolywala sie do obecnie nieuzywanego elementu tablicy. EPERM Parametr cmd 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 ustawionego atrybutu CAP_SYS_ADMIN). EPERM Podjeto probe (IPC_SET) zwiekszenia msg_qbytes ponad parametr systemowy MSGMNB, lecz wywolujacy nie jest uprzywilejowany (Linux: nie posiada mozliwosci 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 cmd). 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.06 31 pazdziernika 2023 r. msgctl(2)