Linux Certif

Toute la documentation sur la certification Linux LPI

msgctl

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

};

Dozwolone warto¶ci 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: 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)