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¶
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.
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 3.71 projektu Linux
man-pages. Opis projektu, informacje dotyczące zgłaszania
błędów, oraz najnowszą wersję
oryginału 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.71 oryginału.
