SKŁADNIA

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

OPIS

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

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)). Kolejka komunikatów jest uważana za pełną w jednym z następujących przypadków:

*

Dodanie nowego komunikatu do kolejki spowoduje, że suma bajtów w kolejki przekroczy maksymalny rozmiar kolejki (pole msg_qbytes).

*

Dodanie kolejnego komunikatu do kolejki spowoduje, że całkowita liczba komunikatów w kolejce przekroczy maksymalny rozmiar kolejki (pole msg_qbytes). 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.

Jeśli w kolejce obecna jest niewystarczająca ilość wolnego miejsca, to domyślne zachowaniem msgsnd() jest blokada do momentu uzyskania wolnej przestrzeni. Jeśli w msgflg określono IPC_NOWAIT, to zamiast tego wywołanie zwróci 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()

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.

Jeżeli podano MSG_COPY w msgflg (zob. poniżej), 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_COPY (od Linuksa 3.8)

Nieniszcząco pobiega kopię komunikatu w pozycję porządkową w kolejce określoną przez msgtyp (komunikaty są pomyślane do numerowania od 0).

Tę flagę należy podać w połączeniu z IPC_NOWAIT, co skutkuje tym, że jeśli w danej pozycji nie ma dostępnego komunikatu, to wywołanie natychmiast zwraca błąd ENOMSG. Ponieważ zmienia to znaczenie msgtyp w różny sposób, MSG_COPY i MSG_EXCEPT nie mogą być podane równocześnie w msgflg.

Flaga MSG_COPY 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ą CONFIG_CHECKPOINT_RESTORE.

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.

ZGODNE Z

Znaczniki MSG_EXCEPT i MSG_COPY są charakterystyczne dla Linuksa, ich definicje można pobrać przez zdefiniowane makra testującego funkcje _GNU_SOURCE.

UWAGI

Parametr msgp jest deklarowany jako struct msgbuf * w glibc 2.0 i 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). Proces uprzywilejowany (w Linuksie: proces ze możliwością CAP_SYS_RESOURCE) 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).

O STRONIE

TŁUMACZENIE

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.