jammy (2) msgctl.2.gz

Provided by: manpages-pl-dev_4.13-4_all bug

NAZWA

       msgctl - sterowanie kolejkami komunikatów Systemu V

SKŁADNIA

       #include <sys/types.h>
       #include <sys/ipc.h>
       #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 msgid_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 (Linux-specific, since Linux 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

       On  success,  IPC_STAT,  IPC_SET,  and  IPC_RMID  return  0.  A successful IPC_INFO or MSG_INFO operation
       returns the index of the highest used entry in the kernel's internal array  recording  information  about
       all  message  queues.  (This information can be used with repeated MSG_STAT or MSG_STAT_ANY operations to
       obtain information about all queues on the system.)  A  successful  MSG_STAT  or  MSG_STAT_ANY  operation
       returns the identifier of the queue whose index was given in msqid.

       W razie błędu zwracane jest -1, a zmiennej errno zostanie nadana wartość określająca rodzaj błędu.

BŁĘDY

       W przypadku wystąpienia błędu, zmiennej errno przypisywana jest jedna z następujących wartości:

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

ZGODNE Z

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

UWAGI

       Dołączenie  <sys/types.h>  i  <sys/ipc.h>  nie  jest wymagane na Linuksie ani przez żadną z wersji POSIX.
       Jednak  niektóre  stare  implementacje  wymagają  dołączenia  tych  plików  nagłówkowych,  SVID   również
       dokumentuje  ich  dołączenie.  Aplikacje które mają być przenośne na tego typu stare systemy mogą wymagać
       dołączenia omawianych plików nagłówkowych.

       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)

O STRONIE

       Angielska wersja tej strony pochodzi z wydania 5.10 projektu Linux man-pages. Opis  projektu,  informacje
       dotyczące   zgłaszania   błędów   oraz   najnowszą   wersję   oryginału   można   znaleźć   pod   adresem
       https://www.kernel.org/doc/man-pages/.

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⟩.