msgctl(2)

NAZWA
msgctl - steruje kolejkami komunikatów Systemu V

BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)

SKŁADNIA
#include <sys/msg.h>

int msgctl(int msqid, int op, struct msqid_ds *buf);

OPIS
msgctl() wykonuje operację określoną przez parametr op na kolejce komunikatów Systemu V o identyfikatorze msqid.

Struktura danych msqid_ds jest zdefiniowana w <sys/msg.h> następująco:

    struct msqid_ds {
        struct ipc_perm msg_perm;   /* Własności 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; /* # bajtów w kolejce */
        msgqnum_t       msg_qnum;   /* # liczba komunikatów w kolejce */
        msglen_t        msg_qbytes; /* Maksymalna # bajtów w kolejce */
        pid_t           msg_lspid;  /* PID ostatniego msgsnd(2) */
        pid_t           msg_lrpid;  /* PID ostatniego msgrcv(2) */
    };

Pola struktury msqid_ds są następujące:

msg_perm
    Jest to struktura ipc_perm (zob. niżej), która określa prawa dostępu do kolejki komunikatów.

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 bajtów we wszystkich komunikatach znajdujących się aktualnie w kolejce. Jest to niestandardowe rozszerzenie Linuksa, które nie jest określone przez POSIX.

msg_qnum
    Liczba komunikatów znajdujących się aktualnie w kolejce.

msg_qbytes
    Maksymalna liczba bajtów tekstu komunikatu, na jaką pozwala kolejka.

msg_lspid
    Identyfikator procesu, który ostatni wykonał funkcję systemową msgsnd(2).

msg_lrpid
    identyfikator procesu, który ostatni wykonał funkcję systemową msgrcv(2).

Struktura ipc_perm jest zdefiniowana następująco (wyróżnione pola można ustawić za pomocą IPC_SET):

    struct ipc_perm {
        key_t          __key;       /* Klucz podany w msgget(2) */
        uid_t          uid;         /* Efektywny UID właściciela */
        gid_t          gid;         /* Efektywny GID właściciela */
        uid_t          cuid;        /* Efektywny UID twórcy */
        gid_t          cgid;        /* Efektywny GID twórcy */
        unsigned short mode;        /* Uprawnienia */
        unsigned short __seq;       /* Numer sekwencji */
    };

Najmniej znaczące 9 bitów pola mode struktury ipc_perm definiuje uprawnienia dostępu do kolejki komunikatów. Istnieją następujące bity uprawnień:
0400 | Odczyt przez użytkownika
0200 | Zapis przez użytkownika
0040 | Odczyt przez grupę
0020 | Zapis przez grupę
0004 | Odczyt przez pozostałych
0002 | Zapis przez pozostałych

Bity 0100, 0010 i 0001 (bity praw do uruchamiania) nie są przez system wykorzystywane.

Poprawne wartości parametru op to:

IPC_STAT
    Kopiowanie informacji ze struktury kontrolnej kolejki komunikatów skojarzonej z msqid do struktury wskazywanej przez buf. Wywołujący musi mieć prawo odczytu kolejki komunikatów.

IPC_SET
    Zapis wartości niektórych pól struktury msqid_ds wskazywanej przez parametr buf do struktury kontrolnej kolejki komunikatów. Pole msg_ctime zostanie automatycznie uaktualnione.

    Zaktualizowane mogą również zostać następujące pola tej struktury: msg_qbytes, msg_perm.uid, msg_perm.gid i (9 najmniej znaczących bitów z) msg_perm.mode.

    Efektywny identyfikator użytkownika musi wskazywać na właściciela (msg_perm.uid) lub na twórcę (msg_perm.uid) kolejki komunikatów albo proces wywołujący musi być uprzywilejowany. Odpowiednie uprawnienia (Linux: przywilej CAP_SYS_RESOURCE) są również wymagane, aby nadać polu msg_qbytes wartość większą niż parametr systemowy MSGMNB.

IPC_RMID
    Usuwa natychmiast kolejkę komunikatów. Wznawia wszystkie procesy oczekujące na zapis lub odczyt z kolejki (wywołania, które się wykonywały zasygnalizują błąd i ustawią zmienną errno na EIDRM). Proces wywołujący tę funkcję musi mieć odpowiednie uprawnienia albo jego efektywny identyfikator użytkownika musi wskazywać na twórcę lub na właściciela kolejki komunikatów. Trzeci argument do msgctl() jest w tym wypadku ignorowany.

IPC_INFO (specyficzne dla Linuksa)
    Zwraca w strukturze, na którą wskazuje buf, informacje o systemowych ograniczeniach i parametrach kolejek komunikatów. Struktura jest typu msginfo (dlatego wymagane jest rzutowanie) i jest zdefiniowana w <sys/msg.h>, pod warunkiem, że zdefiniowano również makro _GNU_SOURCE:

        struct msginfo {
            int msgpool; /* Rozmiar w kibibajtach puli buforów
                            używanej do przechowywania danych
                            komunikatu; nieużywane przez jądro */
            int msgmap;  /* Maksymalna liczba wpisów w mapie komuni-
                            katu; nieużywane przez jądro */
            int msgmax;  /* Maksymalna liczba bajtów, które można
                            zapisać w pojedynczej wiadomości */
            int msgmnb;  /* Maksymalna liczba bajtów, które można
                            zapisać do kolejki; używane do inicjowania
                            msg_qbytes podczas tworzenia kolejki
                            (msgget(2)) */
            int msgmni;  /* Maksymalna liczba kolejek komunikatów */
            int msgssz;  /* Rozmiar segmentu komunikatu;
                            nieużywane przez jądro */
            int msgtql;  /* Maksymalna liczba komunikatów we wszystkich
                            kolejkach w systemie; nieużywane przez jądro */
            unsigned short msgseg;
                         /* Maksymalna liczba segmentów;
                            nieużywane przez jądro */
        };

    Ustawienia msgmni, msgmax oraz msgmnb można zmienić za pomocą plików /proc o nazwach takich samych, jak nazwy tych ustawień; szczegóły można znaleźć w podręczniku proc(5).

MSG_INFO (specyficzne dla Linuksa)
    Zwraca strukturę msginfo zawierającą te same informacje co w przypadku IPC_INFO, z tym wyjątkiem, że w następujących polach zwracane są informacje o zasobach systemowych wykorzystywanych przez kolejki komunikatów: pole msgpool zwraca liczbę kolejek komunikatów istniejących obecnie w systemie; pole msgmap zwraca całkowitą liczbę komunikatów we wszystkich kolejkach w systemie, a pole msgtql zwraca całkowitą liczbę bajtów we wszystkich komunikatach z wszystkich kolejek w systemie.

MSG_STAT (specyficzne dla Linuksa)
    Zwraca strukturę msqid_ds, taką jak dla IPC_STAT. Jednakże parametr msqid nie jest identyfikatorem kolejki, ale indeksem wewnętrznej tablicy jądra przechowującej informacje o wszystkich kolejkach w systemie.

MSG_STAT_ANY (specyficzne dla Linuksa, od Linuks 4.17)
    Zwraca strukturę msqid_ds, jak dla MSG_STAT. Jednak msg_perm.mode nie jest sprawdzany pod kątem uprawnień odczytu do msqid co oznacza, że każdy użytkownik może wykonać tę operację (podobnie jak każdy użytkownik może odczytać /proc/sysvipc/msg, pozyskując te same informacje).

WARTOŚĆ ZWRACANA
W razie powodzenia IPC_STAT, IPC_SET i IPC_RMID zwracają 0. Pomyślnie zakończone operacje IPC_INFO i MSG_INFO zwracają indeks najwyższego używanego wpisu w wewnętrznej tablicy jądra przechowującej informacje o wszystkich kolejkach komunikatów. (Informacji tej można użyć w operacjach MSG_STAT lub MSG_STAT_ANY, aby otrzymać informacje o wszystkich kolejkach w systemie). Pomyślnie zakończona 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 wskazując rodzaj błędu.

BŁĘDY

EACCES
    Parametr op jest równy IPC_STAT lub MSG_STAT, ale proces wywołujący funkcję nie ma prawa do odczytu kolejki komunikatów wskazywanej przez msqid ani nie ma przywileju CAP_IPC_OWNER (ang. capability) w przestrzeni nazw użytkownika, która zarządza jego przestrzenią nazw IPC.

EFAULT
    Argument op ma wartość IPC_SET lub IPC_STAT, ale buf wskazuje na niedostępny obszar pamięci.

EIDRM
    Kolejka komunikatów została usunięta.

EINVAL
    Niepoprawna wartość parametru op lub msqid. Albo: w przypadku operacji MSG_STAT wartość indeksu podana w parametrze msqid odwoływała się do obecnie nieużywanego elementu tablicy.

EPERM
    Argument op jest równy IPC_SET lub IPC_RMID, ale proces wywołujący funkcję nie jest twórcą (określonym w msg_perm.cuid) ani właścicielem (określonym w msg_perm.uid) kolejki komunikatów, a wywołujący nie jest uprzywilejowany (Linux: nie ma przywileju CAP_SYS_ADMIN).

EPERM
    Podjęto próbę (IPC_SET) zwiększenia msg_qbytes ponad parametr systemowy MSGMNB, lecz wywołujący nie jest uprzywilejowany (Linux: nie ma przywileju CAP_SYS_RESOURCE).

STANDARDY
POSIX.1-2024.

HISTORIA
POSIX.1-2001, SVr4.

Niektóre pola struktury struct msqid_ds były w Linuksie 2.2 typu short, ale 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 wywołania od nowych za pomocą znacznika IPC_64 w op).

UWAGI
Operacje IPC_INFO, MSG_STAT oraz MSG_INFO są używane przez program ipcs(1) w celu dostarczenia informacji o zajmowanych zasobach. W przyszłości operacje te mogą zostać zmodyfikowane lub przeniesione do interfejsu systemu plików /proc.

ZOBACZ TAKŻE
msgget(2), msgrcv(2), msgsnd(2), capabilities(7), mq_overview(7), sysvipc(7)

TŁUMACZENIE
Tłumaczenie niniejszej strony podręcznika: Rafał Lewczuk <R.Lewczuk@elka.pw.edu.p>, Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>, Robert Luberda <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>

Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z GNU General Public License w wersji 3 (https://www.gnu.org/licenses/gpl-3.0.html) lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.

Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej manpages-pl-list@lists.sourceforge.net.