Linux Certif

Toute la documentation sur la certification Linux LPI

cmsg

NAZWA

CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - dostêp do danych pomocniczych

SK£ADNIA

#include <sys/socket.h>

struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *msgh);
struct cmsghdr *CMSG_NXTHDR(struct msghdr *msgh, struct cmsghdr *cmsg);
size_t CMSG_ALIGN(size_t length);
size_t CMSG_SPACE(size_t length);
size_t CMSG_LEN(size_t length);
unsigned char *CMSG_DATA(struct cmsghdr *cmsg);

struct cmsghdr {

        socklen_t   cmsg_len;   /* liczba bajtów danych, w³±czaj±c nag³ówek */

        int         cmsg_level; /* protokó³ ¼ród³owy */

        int         cmsg_type;  /* zale¿ny od protoko³u typ */

/* nastêpuje po nim  unsigned charcmsg_data[]; */

};

OPIS

Makrodefinicje te s³u¿± do tworzenia i dostêpu do komunikatów steruj±cych (zwanych równie¿ danymi pomocniczymi), które nie s± czê¶ci± gniazda. Te informacje steruj±ce mog± zawieraæ: interfejs, przez który pakiet zosta³ odebrany, ró¿ne rzadko u¿ywane pola nag³ówka, rozszerzony opis b³êdu, zestaw deskryptorów plików lub uwierzytelnieñ uniksowych. Na przyk³ad, komunikaty steruj±ce mog± s³u¿yæ do ustawiania dodatkowych pól nag³ówka, takich jak opcje IP, dla wysy³anych pakietów. Dane pomocnicze s± wysy³ane poprzez wywo³anie sendmsg(2) a otrzymywane poprzez wywo³anie recvmsg(2). Wiêcej informacji znajduje siê na stronach podrêcznika man dla tych poleceñ.

Dane pomocnicze s± ci±giem struktur struct cmsghdr z dodanymi danymi. Dostêp do tego ci±gu powinien siê odbywaæ wy³±cznie poprzez opisane na tej stronie podrêcznika makrodefinicje, nigdy za¶ bezpo¶rednio. Dostêpne rodzaje komunikatów steruj±cych opisano na stronach podrêcznika dla poszczególnych protoko³ów. Maksymalny rozmiar bufora danych pomocniczych dla gniazda mo¿na ustawiæ za pomoc± sysctl-a net.core.optmem_max; patrz socket(7).

CMSG_FIRSTHDR zwraca wska¼nik do pierwszego cmsghdr w buforze danych pomocniczych zwi±zanym z przekazanym msghdr.

CMSG_NXTHDR zwraca nastêpny poprawny cmsghdr po przekazanym cmsghdr. Zwraca NULL, gdy brak dostatecznej ilo¶ci miejsca w buforze.

CMSG_ALIGN, zadana d³ugo¶æ, zwraca j± w³±czaj±c niezbêdne wyrównanie. Jest to wyra¿enie sta³e.

CMSG_SPACE zwraca liczbê bajtów elementu pomocniczego w³±czaj±c d³ugo¶æ, jak± zajmuj± przekazane dane. Jest to wyra¿enie sta³e.

CMSG_DATA zwraca wska¼nik do czê¶ci cmsghdr zawieraj±cej dane.

CMSG_LEN zwraca warto¶æ, która ma byæ przechowywana w elemencie cmsg_len struktury cmsghdr, bior±c pod uwagê wszelkie niezbêdne wyrównania. Jako argument pobiera d³ugo¶æ danych. Jest to wyra¿enie sta³e.

Aby utworzyæ dane pomocnicze, nale¿y najpierw zainicjalizowaæ element msg_controllen struktury msghdr d³ugo¶ci± bufora komunikatów steruj±cych. Nale¿y u¿yæ CMSG_FIRSTHDR dla msghdr, aby otrzymaæ pierwszy komunikat steruj±cy oraz CMSG_NEXTHDR, aby otrzymaæ wszystkie nastêpne. Dla ka¿dego komunikatu steruj±cego nale¿y zainicjalizowaæ cmsg_len (za pomoc± CMSG_LEN), inne pola nag³ówka cmsghdr oraz czê¶æ zawieraj±c± dane za pomoc± CMSG_DATA. Ostatecznie pole msg_controllen struktury msghdr powinno zawieraæ sumê CMSG_SPACE dla d³ugo¶ci wszystkich komunikatów steruj±cych w buforze. Wiêcej informacji dotycz±cych msghdr, znajduje siê w recvmsg(2).

Gdy bufor komunikatów steruj±cych jest za krótki, aby przechowaæ wszystkie komunikaty, ustawiany jest znacznik MSG_CTRUNC elementu msg_flags struktury msghdr.

PRZYK£AD

Nastêpuj±cy kod poszukuje opcji IP_TTL w otrzymanym buforze pomocniczym:

struct msghdr msgh;

struct cmsghdr *cmsg;

int *ttlptr;

int received_ttl;



/* Otrzymywanie danych z zewn±trz do msgh */

for (cmsg = CMSG_FIRSTHDR(&msgh);

     cmsg != NULL;

     cmsg = CMSG_NXTHDR(&msgh,cmsg) {

        if (cmsg->cmsg_level == SOL_IP

          && cmsg->cmsg_type == IP_TTL) {

                ttlptr = (int *) CMSG_DATA(cmsg);

                received_ttl = *ttlptr;

                break;

        }

}

if (cmsg == NULL) {

        /*

         * B³±d: IP_TTL not jest w³±czone, za ma³y bufor lub

         * b³±d I/O.

         */

}

Poni¿szy kod przekazuje tablicê deskryptorów plików poprzez gniazdo Uniksa SCM_RIGHTS:

struct msghdr msg = {0};

struct cmsghdr *cmsg;

int myfds[NUM_FD]; /* Zawiera przekazywane deskryptory plików. */

char buf[CMSG_SPACE(sizeof myfds)];  /* bufor danych pomocniczych */

int *fdptr;



msg.msg_control = buf;

msg.msg_controllen = sizeof buf;

cmsg = CMSG_FIRSTHDR(&msg);

cmsg->cmsg_level = SOL_SOCKET;

cmsg->cmsg_type = SCM_RIGHTS;

cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);

/* Inicjalizacja: */

fdptr = (int *)CMSG_DATA(cmsg);

memcpy(fdptr, myfds, NUM_FD * sizeof(int));

/* Suma d³ugo¶ci wszystkich komunikatów steruj±cych w buforze: */

msg.msg_controllen = cmsg->cmsg_len;

UWAGI

Dla przeno¶no¶ci, dostêp do danych pomocniczych powinien siê odbywaæ jedynie za pomoc± opisanych tu makrodefinicji. CMSG_ALIGN jest rozszerzeniem Linuksa i nie powinno byæ u¿ywane w przeno¶nych programach.

W Linuksie, CMSG_LEN, CMSG_DATA, i CMSG_ALIGN s± wyra¿eniami sta³ymi (zak³adaj±c, ¿e ich argument jest sta³y) - mo¿na to wykorzystaæ do zadeklarowania rozmiaru zmiennych globalnych. Jednak¿e, mo¿e siê to okazaæ nieprzeno¶nym.

ZGODNE Z

Ten model danych pomocniczych jest zgodny ze szkicem POSIX.1003.1g, z 4.4BSD-Lite, z zaawansowanym API dla IPv6 opisanym w RFC2292 oraz ze specyfikacj± Single Unix v2. CMSG_ALIGN jest rozszerzeniem Linuksa.

ZOBACZ TAK¯E

sendmsg(2), recvmsg(2)

RFC 2292