Provided by: manpages-pl-dev_20060617-1_all bug

NAZWA

       msgop - przekazywanie komunikatów

SKŁADNIA

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/msg.h>

       int msgsnd(int msqid, struct msgbuf *msgp, size_t msgsz, int msgflg);

       ssize_t  msgrcv(int  msqid,  struct  msgbuf  *msgp,  size_t msgsz, long
       msgtyp, int msgflg);

OPIS

       W celu wysłania lub odebrania komunikatu,  proces  powinien  zaalokować
       strukturę danych o następującej postaci ogólnej:

            struct msgbuf {
                 long mtype;     /* rodzaj komunikatu, musi być > 0 */
                 char mtext[1];  /* przekazywane dane */
            };

       Pole  mtext  jest  tablicą  (lub inna strukturą) o rozmiarze określonym
       przez  msgsz,  będącym  nieujemną  liczbą  całkowitą.    Dozwolone   są
       komunikaty o zerowej długości (tzn. nie zawierające pola mtext) Wartość
       pola mtype musi być liczbą ściśle dodatnią, która może służyć procesowi
       odbierającemu   komunikaty   do  filtrowania  kolejki.   (zobacz  część
       dotyczącą msgrcv).

       Proces wywołujący funkcję musi mieć prawo zapisu do kolejki, aby wysłać
       komunikat,  natomiast  prawo  odczytu  jest  niezbędne,  aby  komunikat
       odebrać.

       Wywołanie systemowe msgsnd dołącza kopię komunikatu wskazywanego  przez
       msgp do kolejki o identyfikatorze określonym przez msqid.

       Gdy   w   kolejce  jest  dość  miejsca,  msgsnd  kończy  się  pomyślnie
       natychmiast  (Pojemność  kolejki  określona  jest  w   polu   msg_bytes
       struktury  danych  stowarzyszonej  z kolejką. Podczas tworzenia kolejki
       nadawana jest  mu  wartość  inicjalna  wynosząca  MSGMNB  bajtów,  lecz
       ograniczenie to może zostać zmienione za pomocą msgctl.)  Gdy w kolejce
       nie  ma  dość  miejsca,  to  domyślne  zachowanie  msgsnd   polega   na
       wstrzymaniu  wykonywania  funkcji  do  czasu,  gdy  miejsce  stanie się
       dostępne.  If Ustawienie w msgflg znacznika  IPC_NOWAIT  spowoduje,  że
       zamiast  tego wywołanie systemowe zakończy się niepomyślnie, zgłaszając
       błąd EAGAIN.

       Wstrzymane wywołanie msgsnd może również  zakończyć  się  niepomyślnie,
       gdy   kolejka   zostanie   usunięta  (i  wtedy  wywołanie  to  powoduje
       przypisanie  zmiennej  errno  wartości   EIDRM),   lub   gdy   zostanie
       przechwycony sygnał (i wtedy wywołanie to powoduje przypisanie zmiennej
       errno wartości EINTR).  (msgsnd i msgrcv po  przerwaniu  przez  obsługę
       sygnału  nie  są  nigdy  automatycznie  restartowane,  nie  zależnie od
       ustawienia znacznika SA_RESTART podczas ustanaiwiania  funkcji  obsługi
       sygnału.)

       W  wyniku  pomyślnego  wykonania  operacji,  struktura danych opisująca
       kolejkę komunikatów zostanie zmodyfikowana następująco:

              msg_lspid przypisany zostanie identyfikator procesu wykonującego
              tę operację.

              msg_qnum zostanie zwiększone o 1

              msg_stime zostanie przypisany aktualny czas.

       Wywołanie  systemowe msgrcv odczyta komunikat z kolejki wskazanej przez
       parametr msqid do struktury  msgbuf  wskazywanej  przez  parametr  msgp
       usuwając odczytany komunikat z kolejki.

       Parametr  msgsz  określa  maksymalny  rozmiar  (w  bajtach)  pola mtext
       struktury wskazywanej  przez  parametr  msgp.   Jeśli  dane  komunikatu
       zajmują  więcej  bajtów,  niż msgsz, a parametr msgflg zawiera znacznik
       MSG_NOERROR, wówczas dane komunikatu  zostaną  obcięte  (obcięta  część
       zostanie  utracona).  Jeśli  znacznik nie jest ustawiony a (a komunikat
       jest za długi), wówczas nie zostanie on usunięty z  kolejki,  natomiast
       system  zgłosi błąd a zmiennej errno zostanie przypisana wartość E2BIG.

       Parametr msgtyp określa rodzaj komunikatu w następujący sposób:

              Jeśli msgtyp jest równy 0, to  czytany  jest  pierwszy  dostępny
              komunikat w kolejce (czyli najdawniej wysłany).

              Jeśli  msgtyp ma wartość większą niż 0, to z kolejki odczytywany
              jest pierwszy komunikat tego typu, chyba że w parametrze  msgflg
              zostanie  ustawiony  znacznik  MSG_EXCEPT,  kiedy  to  z kolejki
              zostanie odczytany pierwszy komunikat o typie innym niż podany w
              msgtyp.

              Jeśli  msgtyp  ma  wartość mniejszą niż 0, to z kolejki zostanie
              odczytany pierwszy komunikat o najniższym numerze  typu,  o  ile
              jest on mniejszy lub równy wartości bezwzględnej msgtyp .

       Parametr  msgflg  zawiera  bitową alternatywę (OR) żadnego, jednego lub
       więcej spośród następujących znaczników:

              IPC_NOWAIT Wywołanie nie będzie wstrzymywać pracy procesu, jeśli
              w  kolejce  nie  ma  komunikatów  odpowiedniego  typu. Wywołanie
              systemowe  zgłosi  wówczas  błąd,  przypisując  zmiennej   errno
              wartość ENOMSG.

              MSG_EXCEPT Używane jest wtedy, gdy msgtyp ma wartość większą niż
              0, spowoduje odczytanie z kolejki pierwszego  komunikatu  innego
              typu, niż msgtyp.

              MSG_NOERROR  Spowoduje  obcięcie  komunikatu, jeśli jego dane są
              dłuższe niż msgsz bajtów.

       Jeśli w  kolejce  nie  ma  komunikatu  spełniającego  te  warunki,  zaś
       znacznik  IPC_NOWAIT nie został przekazany w msgflg, to proces zostanie
       wstrzymany, dopóki nie nastąpi jedno z poniższych zdarzeń:

              Komunikat odpowiedniego typu zostanie umieszczony w kolejce.

              Kolejka zostanie usunięta z systemu. W tym  przypadku  wywołanie
              systemowe zgłosi błąd, przypisując zmiennej errno wartość EIDRM.

              Proces wywołujący otrzyma sygnał wymagający przechwycenia. W tym
              przypadku  wywołanie systemowe zgłosi błąd, przypisując zmiennej
              errno wartość EINTR.

       Jeśli operacja zakończy się pomyślnie, to  struktura  danych  opisująca
       kolejkę zostanie następująco zmodyfikowana:

              msg_lrpid  przyjmie  wartość  równą  identyfikatorowi wołającego
              procesu

              msg_qnum zostanie zmniejszone o 1.

              msg_rtime zostanie przypisany aktualny czas.

WARTOŚĆ ZWRACANA

       W przypadku niepowodzenia,  obydwa  wywołania  zwrócą  -1  i  przypiszą
       zmiennej   errno   wartość  określającą  rodzaj  błędu.   W  przeciwnym
       przypadku,  msgsnd  zwróci  0,  zaś   msgrvc   zwróci   liczbę   bajtów
       skopiowanych z kolejki do tablicy mtext.

BŁĘDY

       Jeśli  wywołanie  msgsnd  nie  powiedzie się, to zmienna errno przyjmie
       jedną z poniższych wartości:

       EAGAIN     Komunikat nie może  zostać  wysłany  do  kolejki,  z  powodu
                  ograniczenia   msg_qbytes,   a  znacznik  IPC_NOWAIT  został
                  przekazany w parametrze mgsflg.

       EACCES     Proces nie ma prawa zapisu do kolejki komunikatów.

       EFAULT     dres wskazywany przez msgp jest niedostępny.

       EIDRM      Kolejka została w międzyczasie usunięta.

       EINTR      Podczas oczekiwania na zwolnienie miejsca w kolejce,  proces
                  przechwycił sygnał.

       EINVAL     Niewłaściwa  wartość msqid, mtype (powinna być dodatnia) lub
                  msgsz (powinna być większa lub równa 0 i mniejsza lub  równa
                  MSGMAX).

       ENOMEM     Brak w systemie pamięci na skopiowanie podanego msgbuf.

       Jeśli  wywołanie  msgrcv  nie powiedzie się, to zmiennej errno zostanie
       przypisana jedna z poniższych wartości:

       E2BIG      Tekst komunikatu jest  dłuższy  niż  msgsz  ,  zaś  znacznik
                  MSG_NOERROR nie został w parametrze msgflg ustawiony.

       EACCES     Proces nie ma prawa do odczytu danej kolejki komunikatów.

       EFAULT     Adres wskazywany przez msgp jest niedostępny.

       EIDRM      Proces  oczekiwał  na  komunikat, ale w międzyczasie kolejka
                  została usunięta.

       EINTR      Proces oczekiwał na komunikat, ale  dotarł  do  niego  jakiś
                  wymagający obsłużenia sygnał.

       EINVAL     Niewłaściwa  wartość  msgqid  lub msgsz (powinna być większa
                  lub równa 0).

       ENOMSG     Znacznik IPC_NOWAIT został  przekazany  w  msgflg  ,  ale  w
                  kolejce nie ma komunikatu żądanego typu.

UWAGI

       Wywołanie msgsnd obowiązują następujące ograniczenia systemowe:

       MSGMAX     Maksymalny   rozmiar  danych  komunikatu:  ta  implementacja
                  ogranicza wielkość do 8192 bajty.

       MSGMNB     Domyślny maksymalny łączny rozmiar  (w  bajtach)  wszystkich
                  komunikatów  w  kolejce: 16384 bajty.  Administrator systemu
                  może przekroczyć  to  ograniczenie,  przy  pomocy  wywołania
                  msgctl.

       W  tej  implementacji  nie  ma  jawnego systemowego ograniczenia liczby
       komunikatów przechowywanych w kolejce (MSGTQL) i na rozmiar obszaru  (w
       bajtach) przeznaczonego na komunikaty (MSGPOOL).

ZGODNE Z

       SVr4, SVID.

UWAGA

       Parametr  będący  wskaźnikiem jest w ibc4, libc5, glibc 2.0 i glibc 2.1
       zadeclarowany jako struct msgbuf *. W glibc 2.2 jest zadeklarowany jako
       void * (const void * dla msgsnd()), zgodnie z SUSv2.

ZOBACZ TAKŻE

       ipc(5), msgctl(2), msgget(2), msgrcv(2), msgsnd(2)