Provided by: manpages-pl-dev_0.5-1_all 
NAZWA
msgrcv, msgsnd - przekazywanie komunikatów kolejki Systemu V
SKŁADNIA
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg);
ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp,
int msgflg);
OPIS
Wywołań systemowych msgsnd() i msgrcv() używa się do - odpowiednio - wysyłania komunikatów do kolejki
komunikatów i odbierania komunikatów z kolejki Systemu V. Aby wysłać komunikat, proces wywołujący musi
mieć uprawnienie do zapisu na kolejce komunikatów, a aby odebrać komunikat - uprawnienie do odczytu
kolejki.
Parametr msgp jest wskaźnikiem do zdefiniowanej przez proces wywołujący struktury, której ogólna postać
wygląda tak:
struct msgbuf {
long mtype; /* typ wiadomości, musi być > 0 */
char mtext[1]; /* dane wiadomości */
};
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. niezawierają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 opis msgrcv() poniżej).
msgsnd()
Wywołanie systemowe msgsnd() dołącza kopię komunikatu wskazywanego przez msgp do kolejki o
identyfikatorze określonym przez msqid.
Gdy w kolejce jest wystarczająco dużo miejsca, to msgsnd() natychmiast kończy się pomyślnie. (Pojemność
kolejki określona jest w polu msg_qbytes struktury danych stowarzyszonej z kolejką. Podczas tworzenia
kolejki polu temu jest przypisywana wartość początkowa wynosząca MSGMNB bajtów, lecz ograniczenie to może
zostać zmienione za pomocą msgctl(2)). Gdy w kolejce nie ma miejsca, to domyślne zachowanie msgsnd()
polega na wstrzymaniu wykonywania funkcji do czasu, gdy miejsce stanie się dostępne. 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 się także nie powieść, jeżeli:
* kolejka zostanie usunięta z systemu - w tym przypadku wywołanie systemowe zgłosi błąd, przypisując
zmiennej errno wartość EIDRM;
* zostanie przechwycony sygnał - wtedy wywołanie to powoduje przypisanie zmiennej errno wartości EINTR;
patrz signal(7) (msgsnd() po przerwaniu przez obsługę sygnału nie jest nigdy automatycznie
restartowane, niezależnie od ustawienia znacznika SA_RESTART podanego podczas ustanawiania funkcji
obsługi sygnału).
Jeśli operacja zakończy się pomyślnie, to struktura danych opisująca kolejkę zostanie zmodyfikowana w
następujący sposób:
msg_lspid przypisany zostanie identyfikator procesu wykonującego tę operację.
msg_qnum zostanie zwiększone o 1.
msg_stime zostanie przypisany bieżący czas.
msgrcv()
Wywołanie systemowe msgrcv usuwa komunikat z kolejki określonej przez msqid i umieszcza go w buforze
wskazywanym przez parametr msgp.
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, to wynik zależy od tego, czy w msgflg przekazano
znacznik MSG_NOERROR. Jeżeli podano MSG_NOERROR, to tekst komunikatu zostanie obcięty (obcięta część
zostanie utracona); jeżeli MSG_NOERROR nie występuje, to komunikat nie jest usuwany z kolejki, a
wywołanie systemowe kończy się błędem, zwracając wartość -1 i ustawiając errno na E2BIG.
Parametr msgtyp określa rodzaj komunikatu w następujący sposób:
* Jeśli msgtyp jest równy 0, to czytany jest pierwszy komunikat z kolejki.
* Jeśli msgtyp ma wartość większą niż 0, to z kolejki odczytywany jest pierwszy komunikat o typie msgtyp,
chyba że w parametrze msgflg zostanie ustawiony znacznik MSG_EXCEPT, co spowoduje, że z kolejki
zostanie odczytany pierwszy komunikat o typie różnym od msgtyp.
* Jeśli msgtyp ma wartość mniejszą niż 0, to z kolejki zostanie odczytany pierwszy komunikat o najniższym
numerze typu, mniejszym lub równym wartości bezwzględnej msgtyp.
Parametr msgflg jest maską bitową, utworzoną jako alternatywa (OR) zera lub więcej następujących
znaczników:
IPC_NOWAIT
Nie wstrzymuje pracy procesu, jeśli w kolejce nie ma komunikatów odpowiedniego typu. Wywołanie
systemowe zwróci wówczas błąd, przypisując zmiennej errno wartość ENOMSG.
MSG_EXCEPT
Użyte z parametrem msgtyp większym od 0, spowoduje odczytanie z kolejki pierwszego komunikatu o
typie różnym od 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, a znacznik IPC_NOWAIT nie został ustawiony 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 przechwytuje sygnał. W takim przypadku wywołanie systemowe kończy się niepowodzeniem,
ustawiając errno na EINTR. (msgrcv() po przerwaniu przez obsługę sygnału nie jest nigdy automatycznie
restartowane, niezależnie od ustawienia znacznika SA_RESTART podczas ustanawiania funkcji obsługi
sygnału).
Jeśli operacja zakończy się pomyślnie, to struktura danych opisująca kolejkę zostanie zmodyfikowana w
następujący sposób:
msg_lrpid przyjmie wartość równą identyfikatorowi wołającego procesu
msg_qnum zostanie zmniejszone o 1.
msg_rtime zostanie przypisany bieżący 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, a msgrvc() zwróci liczbę bajtów skopiowanych z
kolejki do tablicy mtext.
BŁĘDY
Jeśli wywołanie msgsnd() się nie powiedzie, to zmienna errno przyjmie jedną z poniższych wartości:
EACCES Proces wywołujący nie ma prawa do zapisu danej kolejki komunikatów, ani nie ma ustawionego
atrybutu CAP_IPC_OWNER.
EAGAIN Komunikat nie może zostać wysłany z powodu ograniczenia msg_qbytes dotyczącego kolejki, a nie
przekazano znacznika IPC_NOWAIT w parametrze mgsflg.
EFAULT Adres wskazywany przez msgp jest niedostępny.
EIDRM Kolejka komunikatów została 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 komunikatu wskazywanego przez msgp.
Jeśli wywołanie msgrcv() się nie powiedzie, to zmiennej errno zostanie przypisana jedna z poniższych
wartości:
E2BIG Tekst komunikatu jest dłuższy niż msgsz i nie ustawiono znacznika MSG_NOERROR w parametrze msgflg.
EACCES Proces wywołujący nie ma prawa do odczytu danej kolejki komunikatów, ani nie ma ustawionego
atrybutu CAP_IPC_OWNER.
EAGAIN Brak dostępnych komunikatów w kolejce, a podano IPC_NOWAIT w msgflg.
EFAULT Adres wskazywany przez msgp jest niedostępny.
EIDRM Proces oczekiwał na komunikat, ale w międzyczasie kolejka została usunięta.
EINTR Proces przechwycił sygnał podczas oczekiwania na odebranie komunikatu; patrz signal(7).
EINVAL msgqid był niepoprawny lub msgsz był mniejszy od 0.
ENOMSG Znacznik IPC_NOWAIT został przekazany w msgflg, ale w kolejce nie ma komunikatu żądanego typu.
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.
Parametr msgp jest deklarowany jako struct msgbuf * w libc4, libc5, glibc 2.0, glibc 2.1. W glibc 2.2 i
późniejszych jest deklarowany jako void *, zgodnie z wymaganiami SUSv2 i SUSv3.
Wywołania msgsnd() dotyczą następujące ograniczenia systemowe:
MSGMAX Maksymalny rozmiar tekstu komunikatu: 8192 bajty (pod Linuksem ten limit można odczytać i
modyfikować, używając pliku /proc/sys/kernel/msgmax).
MSGMNB Domyślny maksymalny łączny rozmiar wszystkich komunikatów w kolejce: 16384 bajty (pod Linuksem
można ten limit odczytać i zmienić, używając pliku /proc/sys/kernel/msgmnb). Administrator systemu
może za pomocą wywołania msgctl() ustawić rozmiar kolejki komunikatów na wartość większą niż
MSGMNB.
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).
ZOBACZ TAKŻE
msgctl(2), msgget(2), capabilities(7), mq_overview(7), svipc(7)
O STRONIE
Angielska wersja tej strony pochodzi z wydania 3.52 projektu Linux man-pages. Opis projektu oraz
informacje dotyczące zgłaszania błędów 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.52 oryginału.
Linux 2012-05-31 MSGOP(2)