NAZWA¶

msgctl - sterowanie kolejkami komunikatów

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¶

Funkcja ta wykonuje operację określoną przez parametr cmd na kolejce komunikatów 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() */


    time_t          msg_rtime;    /* Czas ostatniego msgrcv() */


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


    pid_t           msg_lrpid;    /* PID ostatniego msgrcv() */
};

Struktura ipc_perm jest zdefiniowana w <sys/ipc.h> następująco (wyróżnione pola można ustawić za pomocą IPC_SET):

struct ipc_perm {


    key_t key;            /* Klucz podany w msgget() */


    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 */
};

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: zdolność CAP_IPC_RESOURCE) są również wymagane, aby nadać polu msg_qbytes wartość większą niż parametr systemowy MSGMNB.

IPC_RMID

Natychmiastowe usunięcie kolejki komunikatów i skojarzonej z nią struktury danych. Wszystkie procesy oczekujące na zapis lub odczyt z kolejki zostaną wznowione i wywołania, które wykonywały zasygnalizują błąd (przypisując zmiennej errno wartość EIDRM). Proces wywołujący tę funkcję musi mieć odpowiednie uprawnienia (prawdopodobnie uprawnienia użytkownika root), ewentualnie jego efektywny identyfikator użytkownika musi wskazywać na twórcę lub na właściciela kolejki komunikatów.

WARTOŚĆ ZWRACANA¶

Po pomyślnym zakończeniu, funkcja zwróci wartość 0, w przeciwnym przypadku -1, a zmiennej errno zostanie nadana wartość określająca rodzaj błędu.

BŁĘDY¶

W przypadku niepomyślnego zakończenia funkcji, zmiennej errno zostanie nadana 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 wskazywanej przez msqid kolejki komunikatów ani nie ma zdolności 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

Niewłaściwa wartość parametru cmd lub msqid.

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 proces nie jest uprzywilejowany (Linux: nie ma zdolności CAP_SYS_ADMIN). Niektóre pola struktury struct msqid_ds były w Linuksie 2.2 typu short a 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 i nowe wywołania za pomocą znacznika IPC_64 w cmd).

ZGODNE Z¶

SVr4, SVID. Kod błędu EIDRM nie został udokumentowany w SVID.

ZOBACZ TAKŻE¶

msgget(2), msgrcv(2), msgsnd(2), ipc(5), capabilities(7)