Provided by: manpages-pl-dev_0.6-2_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;     /* 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 ostatniej zmiany */
               unsigned long   __msg_cbytes; /* Bieżąca liczba bajtów w
                                                kolejce (niestandardowy) */
               msgqnum_t       msg_qnum;     /* Bieżąca liczba komunikatów
                                                w kolejce */
               msglen_t        msg_qbytes;   /* Maksymalna liczba dostępnych
                                                bajtów w kolejce */
               pid_t           msg_lspid;    /* PID ostatniego msgsnd(2) */
               pid_t           msg_lrpid;    /* PID ostatniego 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 */
           };

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

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, aby otrzymać informacje o wszystkich kolejkach w systemie).
       Pomyślnie zakończona operacja MSG_STAT zwraca identyfikator kolejki o indeksie przekazanym
       w 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 Parametr cmd 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 ustawionego
              atrybutu CAP_IPC_OWNER.

       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

       SVr4, POSIX.1-2001.

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), svipc(7)

O STRONIE

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

TŁUMACZENIE

       Autorami polskiego tłumaczenia niniejszej strony podręcznika man są: Rafał  Lewczuk  (PTM)
       <R.Lewczuk@elka.pw.edu.p>,  Andrzej  Krzysztofowicz  (PTM)  <ankry@mif.pg.gda.pl>,  Robert
       Luberda <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>.

       Polskie tłumaczenie jest częścią projektu manpages-pl; uwagi, pomoc, zgłaszanie błędów  na
       stronie   http://sourceforge.net/projects/manpages-pl/.   Jest   zgodne   z  wersją   3.71
       oryginału.