Provided by: manpages-pl-dev_4.21.0-2_all bug

NAZWA

       msgctl - sterowanie kolejkami komunikatów Systemu V

BIBLIOTEKA

       Standardowa biblioteka C (libc, -lc)

SKŁADNIA

       #include <sys/msg.h>

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

OPIS

       msgctl() wykonuje operację określoną przez parametr cmd 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;   /* 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 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 */
           };

       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 wartości parametru cmd 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  (przynajmniej  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:  atrybut  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 of entries in message
                                      map; 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)
              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).

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.

       On failure, -1 is returned and errno is set to indicate the error.

BŁĘDY

       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 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  cmd 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  Parametr  cmd  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 ustawionego atrybutu 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  posiada  możliwości
              CAP_SYS_RESOURCE).

STANDARDY

       POSIX.1-2001, POSIX.1-2008, SVr4.

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.

       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 cmd).

ZOBACZ TAKŻE

       msgget(2), msgrcv(2), msgsnd(2), capabilities(7), mq_overview(7), sysvipc(7)

TŁUMACZENIE

       Autorami  polskiego  tłumaczenia  niniejszej  strony   podręcznika   są:   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⟩.