.\" -*- coding: UTF-8 -*- .\" Copyright 1993 Giorgio Ciucci .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond .\" Modified Mon Jul 10 21:09:59 2000 by aeb .\" Modified 1 Jun 2002, Michael Kerrisk .\" Language clean-ups. .\" Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX .\" Added note on restart behavior of msgsnd() and msgrcv() .\" Formatting clean-ups (argument and field names marked as .I .\" instead of .B) .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" Modified, 11 Nov 2004, Michael Kerrisk .\" Language and formatting clean-ups .\" Added notes on /proc files .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH MSGOP 2 "2 sierpnia 2019 r." Linux "Podręcznik programisty Linuksa" .SH NAZWA msgrcv, msgsnd \- przekazywanie komunikatów kolejki Systemu V .SH SKŁADNIA .nf \fB#include \fP \fB#include \fP \fB#include \fP .PP \fBint msgsnd(int \fP\fImsqid\fP\fB, const void *\fP\fImsgp\fP\fB, size_t \fP\fImsgsz\fP\fB, int \fP\fImsgflg\fP\fB);\fP .PP \fBssize_t msgrcv(int \fP\fImsqid\fP\fB, void *\fP\fImsgp\fP\fB, size_t \fP\fImsgsz\fP\fB, long \fP\fImsgtyp\fP\fB,\fP \fB int \fP\fImsgflg\fP\fB);\fP .fi .SH OPIS The \fBmsgsnd\fP() and \fBmsgrcv\fP() system calls are used to send messages to, and receive messages from, a System\ V message queue. The calling process must have write permission on the message queue in order to send a message, and read permission to receive a message. .PP Parametr \fImsgp\fP jest wskaźnikiem do zdefiniowanej przez proces wywołujący struktury, której ogólna postać wygląda tak: .PP .in +4n .EX struct msgbuf { long mtype; /* typ wiadomości, musi być > 0 */ char mtext[1]; /* dane wiadomości */ }; .EE .in .PP Pole \fImtext\fP jest tablicą (lub inna strukturą) o rozmiarze określonym przez \fImsgsz\fP, będącym nieujemną liczbą całkowitą. Dozwolone są komunikaty o zerowej długości (tzn. niezawierające pola \fImtext\fP). Wartość pola \fImtype\fP musi być liczbą ściśle dodatnią, która może służyć procesowi odbierającemu komunikaty do filtrowania kolejki (zobacz opis \fBmsgrcv\fP() poniżej). .SS msgsnd() Wywołanie systemowe \fBmsgsnd\fP() dołącza kopię komunikatu wskazywanego przez \fImsgp\fP do kolejki o identyfikatorze określonym przez \fImsqid\fP. .PP Gdy w kolejce jest wystarczająco dużo miejsca, to \fBmsgsnd\fP() natychmiast kończy się pomyślnie. (Pojemność kolejki określona jest w polu \fImsg_qbytes\fP struktury danych stowarzyszonej z kolejką. Podczas tworzenia kolejki polu temu jest przypisywana wartość początkowa wynosząca \fBMSGMNB\fP bajtów, lecz ograniczenie to może zostać zmienione za pomocą \fBmsgctl\fP(2)). Kolejka komunikatów jest uważana za pełną w jednym z następujących przypadków: .IP * 2 Dodanie nowego komunikatu do kolejki spowoduje, że suma bajtów w kolejki przekroczy maksymalny rozmiar kolejki (pole \fImsg_qbytes\fP). .IP * Dodanie kolejnego komunikatu do kolejki spowoduje, że całkowita liczba komunikatów w kolejce przekroczy maksymalny rozmiar kolejki (pole \fImsg_qbytes\fP). To sprawdzenie jest konieczne aby zapobiec umieszczaniu w kolejce nieograniczonej liczby komunikatów o zerowej długości. Choć takie komunikaty nie zawierają danych, to wciąż zajmują (zablokowaną) pamięć jądra. .PP Jeśli w kolejce obecna jest niewystarczająca ilość wolnego miejsca, to domyślne zachowaniem \fBmsgsnd\fP() jest blokada do momentu uzyskania wolnej przestrzeni. Jeśli w \fImsgflg\fP określono \fBIPC_NOWAIT\fP, to zamiast tego wywołanie zwróci błąd \fBEAGAIN\fP. .PP Wstrzymane wywołanie \fBmsgsnd\fP() może się także nie powieść, jeżeli: .IP * 2 kolejka zostanie usunięta z systemu \- w tym przypadku wywołanie systemowe zgłosi błąd, przypisując zmiennej \fIerrno\fP wartość \fBEIDRM\fP; .IP * zostanie przechwycony sygnał \- wtedy wywołanie to powoduje przypisanie zmiennej \fIerrno\fP wartości \fBEINTR\fP; patrz \fBsignal\fP(7) (\fBmsgsnd\fP() po przerwaniu przez obsługę sygnału nie jest nigdy automatycznie restartowane, niezależnie od ustawienia znacznika \fBSA_RESTART\fP podanego podczas ustanawiania funkcji obsługi sygnału). .PP Jeśli operacja zakończy się pomyślnie, to struktura danych opisująca kolejkę zostanie zmodyfikowana w następujący sposób: .IP \fImsg_lspid\fP przypisany zostanie identyfikator procesu wykonującego tę operację. .IP \fImsg_qnum\fP zostanie zwiększone o 1. .IP \fImsg_stime\fP zostanie przypisany bieżący czas. .SS msgrcv() Wywołanie systemowe \fBmsgrcv\fP usuwa komunikat z kolejki określonej przez \fImsqid\fP i umieszcza go w buforze wskazywanym przez parametr \fImsgp\fP. .PP Parametr \fImsgsz\fP określa maksymalny rozmiar w bajtach pola \fImtext\fP struktury wskazywanej przez parametr \fImsgp\fP. Jeśli dane komunikatu zajmują więcej bajtów niż \fImsgsz\fP, to wynik zależy od tego, czy w \fImsgflg\fP przekazano znacznik \fBMSG_NOERROR\fP. Jeżeli podano \fBMSG_NOERROR\fP, to tekst komunikatu zostanie obcięty (obcięta część zostanie utracona); jeżeli \fBMSG_NOERROR\fP 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 \fIerrno\fP na \fBE2BIG\fP. .PP Jeżeli podano \fBMSG_COPY\fP w \fImsgflg\fP (zob. poniżej), parametr \fImsgtyp\fP określa rodzaj komunikatu w następujący sposób: .IP * 2 Jeśli \fImsgtyp\fP jest równy 0, to czytany jest pierwszy komunikat z kolejki. .IP * Jeśli \fImsgtyp\fP ma wartość większą niż 0, to z kolejki odczytywany jest pierwszy komunikat o typie \fImsgtyp\fP, chyba że w parametrze \fImsgflg\fP zostanie ustawiony znacznik \fBMSG_EXCEPT\fP, co spowoduje, że z kolejki zostanie odczytany pierwszy komunikat o typie różnym od \fImsgtyp\fP. .IP * Jeśli \fImsgtyp\fP 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 \fImsgtyp\fP. .PP Parametr \fImsgflg\fP jest maską bitową, utworzoną jako alternatywa (OR) zera lub więcej następujących znaczników: .TP \fBIPC_NOWAIT\fP 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 \fIerrno\fP wartość \fBENOMSG\fP. .TP \fBMSG_COPY\fP (od Linuksa 3.8) .\" commit 4a674f34ba04a002244edaf891b5da7fc1473ae8 Nieniszcząco pobiega kopię komunikatu w pozycję porządkową w kolejce określoną przez \fImsgtyp\fP (komunikaty są pomyślane do numerowania od 0). .IP Tę flagę należy podać w połączeniu z \fBIPC_NOWAIT\fP, co skutkuje tym, że jeśli w danej pozycji nie ma dostępnego komunikatu, to wywołanie natychmiast zwraca błąd \fBENOMSG\fP. Ponieważ zmienia to znaczenie \fImsgtyp\fP w różny sposób, \fBMSG_COPY\fP i \fBMSG_EXCEPT\fP nie mogą\ być\ podane równocześnie w \fImsgflg\fP. .IP Flaga \fBMSG_COPY\fP została dodana dla zaimplementowania w jądrze funkcji przywracania do punktu kontrolnego (checkpoint\-restore) i jest dostępna wyłącznie wtedy, jeśli jądro zbudowano z opcją \fBCONFIG_CHECKPOINT_RESTORE\fP. .TP \fBMSG_EXCEPT\fP Użyte z parametrem \fImsgtyp\fP większym od 0, spowoduje odczytanie z kolejki pierwszego komunikatu o typie różnym od \fImsgtyp\fP. .TP \fBMSG_NOERROR\fP Spowoduje obcięcie komunikatu, jeśli jego dane są dłuższe niż \fImsgsz\fP bajtów. .PP Jeśli w kolejce nie ma komunikatu spełniającego te warunki, a znacznik \fBIPC_NOWAIT\fP nie został ustawiony w \fImsgflg\fP, to proces zostanie wstrzymany, dopóki nie nastąpi jedno z poniższych zdarzeń: .IP * 2 Komunikat odpowiedniego typu zostanie umieszczony w kolejce. .IP * Kolejka zostanie usunięta z systemu. W tym przypadku wywołanie systemowe zgłosi błąd, przypisując zmiennej \fIerrno\fP wartość \fBEIDRM\fP. .IP * Proces wywołujący przechwytuje sygnał. W takim przypadku wywołanie systemowe kończy się niepowodzeniem, ustawiając \fIerrno\fP na \fBEINTR\fP. (\fBmsgrcv\fP() po przerwaniu przez obsługę sygnału nie jest nigdy automatycznie restartowane, niezależnie od ustawienia znacznika \fBSA_RESTART\fP podczas ustanawiania funkcji obsługi sygnału). .PP Jeśli operacja zakończy się pomyślnie, to struktura danych opisująca kolejkę zostanie zmodyfikowana w następujący sposób: .IP \fImsg_lrpid\fP przyjmie wartość równą identyfikatorowi wołającego procesu .IP \fImsg_qnum\fP zostanie zmniejszone o 1. .IP \fImsg_rtime\fP zostanie przypisany bieżący czas. .SH "WARTOŚĆ ZWRACANA" W przypadku niepowodzenia obydwa wywołania zwrócą \-1 i przypiszą zmiennej \fIerrno\fP wartość określającą rodzaj błędu. W przeciwnym przypadku, \fBmsgsnd\fP() zwróci 0, a \fBmsgrvc\fP() zwróci liczbę bajtów skopiowanych z kolejki do tablicy \fImtext\fP. .SH BŁĘDY Jeśli wywołanie \fBmsgsnd\fP() się nie powiedzie, to zmienna \fIerrno\fP przyjmie jedną z poniższych wartości: .TP \fBEACCES\fP The calling process does not have write permission on the message queue, and does not have the \fBCAP_IPC_OWNER\fP capability in the user namespace that governs its IPC namespace. .TP \fBEAGAIN\fP Komunikat nie może zostać wysłany z powodu ograniczenia \fImsg_qbytes\fP dotyczącego kolejki, a nie przekazano znacznika \fBIPC_NOWAIT\fP w parametrze \fImgsflg\fP. .TP \fBEFAULT\fP Adres wskazywany przez \fImsgp\fP jest niedostępny. .TP \fBEIDRM\fP Kolejka komunikatów została usunięta. .TP \fBEINTR\fP Podczas oczekiwania na zwolnienie miejsca w kolejce, proces przechwycił sygnał. .TP \fBEINVAL\fP Niewłaściwa wartość \fImsqid\fP, \fImtype\fP (powinna być dodatnia) lub \fImsgsz\fP (powinna być większa lub równa \fB0\fP i mniejsza lub równa \fBMSGMAX\fP). .TP \fBENOMEM\fP Brak w systemie pamięci na skopiowanie komunikatu wskazywanego przez \fImsgp\fP. .PP Jeśli wywołanie \fBmsgrcv\fP() się nie powiedzie, to zmiennej \fIerrno\fP zostanie przypisana jedna z poniższych wartości: .TP \fBE2BIG\fP Tekst komunikatu jest dłuższy niż \fImsgsz\fP i nie ustawiono znacznika \fBMSG_NOERROR\fP w parametrze \fImsgflg\fP. .TP \fBEACCES\fP The calling process does not have read permission on the message queue, and does not have the \fBCAP_IPC_OWNER\fP capability in the user namespace that governs its IPC namespace. .TP \fBEFAULT\fP Adres wskazywany przez \fImsgp\fP jest niedostępny. .TP \fBEIDRM\fP Proces oczekiwał na komunikat, ale w międzyczasie kolejka została usunięta. .TP \fBEINTR\fP Proces przechwycił sygnał podczas oczekiwania na odebranie komunikatu; patrz \fBsignal\fP(7). .TP \fBEINVAL\fP \fImsqid\fP był niepoprawny lub \fImsgsz\fP był mniejszy od 0. .TP \fBEINVAL\fP (od Linuksa 3.14) \fImsgflg\fP określono jako \fBMSG_COPY\fP, ale nie \fBIPC_NOWAIT\fP. .TP \fBEINVAL\fP (od Linuksa 3.14) \fImsgflg\fP określono jako \fBMSG_COPY\fP i \fBMSG_EXCEPT\fP. .TP \fBENOMSG\fP Znacznik \fBIPC_NOWAIT\fP został przekazany w \fImsgflg\fP, ale w kolejce nie ma komunikatu żądanego typu. .TP \fBENOMSG\fP \fBIPC_NOWAIT\fP i \fBMSG_COPY\fP zostały określone w \fImsgflg\fP, a kolejka zawiera mniej niż \fImsgtyp\fP komunikatów. .TP \fBENOSYS\fP (od Linuksa 3.8) \fIMSG_COPY\fP zostało określone w \fImsgflg\fP, a jądro zostało skonfigurowane bez opcji \fBCONFIG_CHECKPOINT_RESTORE\fP. .SH "ZGODNE Z" POSIX.1\-2001, POSIX.1\-2008, SVr4. .PP .\" MSG_COPY since glibc 2.18 Znaczniki \fBMSG_EXCEPT\fP i \fBMSG_COPY\fP są charakterystyczne dla Linuksa, ich definicje można pobrać przez zdefiniowane makra testującego funkcje \fB_GNU_SOURCE\fP. .SH UWAGI .\" Like Linux, the FreeBSD man pages still document .\" the inclusion of these header files. Dołączenie \fI\fP i \fI\fP 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. .PP Parametr \fImsgp\fP jest deklarowany jako \fIstruct msgbuf\ *\fP w glibc 2.0 i glibc 2.1. W glibc 2.2 i późniejszych jest deklarowany jako \fIvoid\ *\fP, zgodnie z wymaganiami SUSv2 i SUSv3. .PP Wywołania \fBmsgsnd\fP() dotyczą następujące ograniczenia systemowe: .TP \fBMSGMAX\fP Maksymalny rozmiar tekstu komunikatu, w bajtach: (domyślna wartość: 8192 bajty). Pod Linuksem ten limit można odczytać i modyfikować, używając pliku \fI/proc/sys/kernel/msgmax\fP. .TP \fBMSGMNB\fP Maksymalna liczba bajtów która może być\ przechowywana w kolejce komunikatów (domyślna wartość: 16384 bajtów). Pod Linuksem można ten limit odczytać i zmienić, używając pliku \fI/proc/sys/kernel/msgmnb\fP. Proces uprzywilejowany (w Linuksie: proces z przywilejem \fBCAP_SYS_RESOURCE\fP) może zwiększyć rozmiar kolejki komunikatów poza \fBMSGMNB\fP za pomocą\ operacji \fBIPC_SET\fP \fBmsgctl\fP(2). .PP W tej implementacji nie ma jawnego systemowego ograniczenia liczby komunikatów przechowywanych w kolejce (\fBMSGTQL\fP) i na rozmiar obszaru (w bajtach) przeznaczonego na komunikaty (\fBMSGPOOL\fP). .SH BŁĘDY .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c W Linuksie 3.13 i wcześniejszych, jeśli \fBmsgrcv\fP() było wywołane ze znacznikiem \fBMSG_COPY\fP, lecz bez \fBIPC_NOWAIT\fP, a kolejka komunikatów zawierała mniej niż \fImsgtyp\fP komunikatów, to wywołanie było zablokowane aż do zapisania kolejnego komunikatu do kolejki. W tym momencie wywołanie zwracało kopię komunikatu \fIbez względu\fP na to czy komunikat był w pozycji \fImsgtyp\fP. Błąd ten został naprawiony w jądrze Linux 3.14. .PP .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c Podanie zarówno w \fImsgflg\fP zarówno \fBMSG_COPY\fP jak i \fBMSC_EXCEPT\fP jest błędem logicznym (ponieważ oba te znaczniki wymagają innej interpretacji \fImsgtyp\fP). W Linuksie 3.13 błąd ten nie był diagnozowany przez \fImsgsrv\fP(). Zostało to naprawione w jądrze Linux 3.14. .SH PRZYKŁAD Program poniżej demonstruje użycie \fBmsgsnd\fP() i \fBmsgrcv\fP(). .PP Przykładowy program jest początkowo uruchomiony z opcją \fB\-s\fP, aby wysłać komunikat, a następnie ponownie z opcją \fB\-r\fP, aby otrzymać\ komunikat. .PP Poniższa sesja powłoki pokazuje przykładowy przebieg programu: .PP .in +4n .EX $\fB ./a.out \-s\fP sent: a message at Wed Mar 4 16:25:45 2015 $\fB ./a.out \-r\fP message received: a message at Wed Mar 4 16:25:45 2015 .EE .in .SS "Kod źródłowy programu" \& .EX #include #include #include #include #include #include #include #include #include struct msgbuf { long mtype; char mtext[80]; }; static void usage(char *prog_name, char *msg) { if (msg != NULL) fputs(msg, stderr); fprintf(stderr, "Uzycie: %s [opcje]\en", nazwa_prog); fprintf(stderr, "Opcje:\en"); fprintf(stderr, "\-s wysyła komunikat przez msgsnd()\en"); fprintf(stderr, "\-r odczytuje komunikat przez msgrcv()\en"); fprintf(stderr, "\-t typ komunikatu (domyślnie: 1)\en"); fprintf(stderr, "\-k klucz kolejki komunikatu (domyślnie: 1234)\en"); exit(EXIT_FAILURE); } static void send_msg(int qid, int msgtype) { struct msgbuf msg; time_t t; msg.mtype = msgtype; time(&t); snprintf(msg.mtext, sizeof(msg.mtext), "wiadomość o %s", ctime(&t)); if (msgsnd(qid, (void *) &msg, sizeof(msg.mtext), IPC_NOWAIT) == \-1) { perror("błąd msgsnd"); exit(EXIT_FAILURE); } printf("wysłano: %s\en", msg.mtext); } static void get_msg(int qid, int msgtype) { struct msgbuf msg; if (msgrcv(qid, (void *) &msg, sizeof(msg.mtext), msgtype, MSG_NOERROR | IPC_NOWAIT) == \-1) { if (errno != ENOMSG) { perror("msgrcv"); exit(EXIT_FAILURE); } printf("Brak komunikatu dostępnego dla msgrcv()\en"); } else printf("komunikat otrzymano: %s\en", msg.mtext); } int main(int argc, char *argv[]) { int qid, opt; int mode = 0; /* 1 = wysłanie, 2 = otrzymanie */ int msgtype = 1; int msgkey = 1234; while ((opt = getopt(argc, argv, "srt:k:")) != \-1) { switch (opt) { case \(aqs\(aq: mode = 1; break; case \(aqr\(aq: mode = 2; break; case \(aqt\(aq: msgtype = atoi(optarg); if (msgtype <= 0) usage(argv[0], "opcja \-t musi być\ większa od 0\en"); break; case \(aqk\(aq: msgkey = atoi(optarg); break; default: usage(argv[0], "Nierozpoznana opcja\en"); } } if (mode == 0) usage(argv[0], "musi być opcją \-s albo \-r\en"); qid = msgget(msgkey, IPC_CREAT | 0666); if (qid == \-1) { perror("msgget"); exit(EXIT_FAILURE); } if (mode == 2) get_msg(qid, msgtype); else send_msg(qid, msgtype); exit(EXIT_SUCCESS); } .EE .SH "ZOBACZ TAKŻE" \fBmsgctl\fP(2), \fBmsgget\fP(2), \fBcapabilities\fP(7), \fBmq_overview\fP(7), \fBsysvipc\fP(7) .SH "O STRONIE" Angielska wersja tej strony pochodzi z wydania 5.04 projektu Linux \fIman\-pages\fP. 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/. .SH TŁUMACZENIE Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Rafał Lewczuk , Andrzej Krzysztofowicz , Robert Luberda i Michał Kułach . Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License w wersji 3 .UE lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI. Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres .MT manpages-pl-list@lists.sourceforge.net .ME .