Provided by: manpages-pl-dev_0.7-2_all 
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
POSIX.1-2001, POSIX.1-2008, SVr4.
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 4.07 projektu Linux man-pages. 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/.
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ą 4.07
oryginału.