plucky (2) msgctl.2.gz

Provided by: manpages-pl-dev_4.25.1-1_all bug

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

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

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