CMSG(3) Library Functions Manual CMSG(3) NAZWA CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - uzyskuje dostep do danych pomocniczych BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include 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); OPIS Makrodefinicje te sluza do tworzenia i dostepu do komunikatow sterujacych (zwanych rowniez danymi pomocniczymi), ktore nie sa czescia gniazda. Te informacje sterujace moga zawierac: interfejs, przez ktory pakiet zostal odebrany, rozne rzadko uzywane pola naglowka, rozszerzony opis bledu, zestaw deskryptorow plikow lub uwierzytelnien uniksowych. Na przyklad, komunikaty sterujace moga sluzyc do ustawiania dodatkowych pol naglowka, takich jak opcje IP, dla wysylanych pakietow. Dane pomocnicze sa wysylane poprzez wywolanie sendmsg(2), a odbierane poprzez wywolanie recvmsg(2). Wiecej informacji znajduje sie na stronach podrecznika tych polecen. Dane pomocnicze sa ciagiem struktur cmsghdr z dodanymi danymi. Dostepne rodzaje komunikatow sterujacych opisano na stronach podrecznika poszczegolnych protokolow. Maksymalny rozmiar bufora danych pomocniczych dla gniazda mozna ustawic, uzywajac /proc/sys/net/core/optmem_max; patrz socket(7). Struktura cmsghdr jest zdefiniowana nastepujaco: struct cmsghdr { size_t cmsg_len; /* Liczba bajtow danych, wlaczajac naglowek (typ to socklen_t w POSIX) */ int cmsg_level; /* Protokol zrodlowy */ int cmsg_type; /* Typ zalezny od protokolu */ /* po ktorych nastepuje unsigned char cmsg_data[]; */ }; Dostep do ciagu struktur cmsghdr nidy nie powinien sie odbywac bezposrednio. Nalezy uzywac nastepujacych makrodefinicji: CMSG_FIRSTHDR() zwraca wskaznik do pierwszego cmsghdr w buforze danych pomocniczych zwiazanym z przekazanym msghdr. Zwraca NULL, jesli bufor jest za maly, by pomiescic cmsghdr. CMSG_NXTHDR() zwraca nastepny poprawny cmsghdr po przekazanym cmsghdr. Zwraca NULL, gdy brak dostatecznej ilosci miejsca w buforze. Podczas inicjowania bufora, ktory ma zawierac ciag struktur cmsghdr (na przyklad w celu przeslania za pomoca sendmsg(2)), bufor ten powinien byc najpierw inicjowany zerami, tak aby zapewnic poprawne dzialanie CMSG_NXTHDR(). CMSG_ALIGN(), zwraca zadana dlugosc, wlaczajac niezbedne wyrownanie. Jest to wyrazenie stale. CMSG_SPACE() zwraca liczbe bajtow elementu pomocniczego wlaczajac dlugosc, jaka zajmuja przekazane dane. Jest to wyrazenie stale. CMSG_DATA() zwraca wskaznik do czesci z danymi cmsghdr. Nie mozna zakladac, ze zwracany wskaznik zostanie wystarczajaco wyrownany, do dostepu do dowolnych typow zawartosci danych. Aplikacje nie powinny rzutowac go na typ wskaznika pasujacy do zawartosci, lecz korzystac z memcpy(3), aby kopiowac dane z, lub do, odpowiednio zadeklarowanego obiektu. CMSG_LEN() zwraca wartosc, ktora ma byc przechowywana w elemencie cmsg_len struktury cmsghdr, biorac pod uwage wszelkie niezbedne wyrownania. Jako argument pobiera dlugosc danych. Jest to wyrazenie stale. Aby utworzyc dane pomocnicze, nalezy najpierw zainicjowac element msg_controllen struktury msghdr dlugoscia bufora komunikatow sterujacych. Nalezy uzyc CMSG_FIRSTHDR() dla msghdr, aby otrzymac pierwszy komunikat sterujacy, oraz CMSG_NXTHDR(), aby otrzymac wszystkie nastepne. Dla kazdego komunikatu sterujacego nalezy zainicjowac cmsg_len (za pomoca CMSG_LEN()), inne pola naglowka cmsghdr oraz czesc zawierajaca dane za pomoca CMSG_DATA(). Ostatecznie pole msg_controllen struktury msghdr powinno zawierac sume CMSG_SPACE() dlugosci wszystkich komunikatow sterujacych w buforze. Wiecej informacji dotyczacych msghdr znajduje sie w recvmsg(2). WERSJE Dla przenosnosci, dostep do danych pomocniczych powinien sie odbywac jedynie za pomoca opisanych tu makrodefinicji. W Linuksie, CMSG_LEN(), CMSG_DATA() i CMSG_ALIGN() sa wyrazeniami stalymi (zakladajac, ze ich argument jest staly), co oznacza, ze te wartosci mozna do zadeklarowania rozmiaru zmiennych globalnych. Jednakze, moze sie to okazac nieprzenosne. STANDARDY CMSG_FIRSTHDR() CMSG_NXTHDR() CMSG_DATA() POSIX.1-2008. CMSG_SPACE() CMSG_LEN() CMSG_ALIGN() Linux. HISTORIA Ten model danych pomocniczych jest zgodny ze szkicem POSIX.1g, z 4.4BSD-Lite, z zaawansowanym API dla IPv6 opisanym w RFC 2292 oraz z SUSv2. CMSG_SPACE() i CMSG_LEN() beda objete nastepnym wydaniem POSIX (Issue 8). PRZYKLADY Nastepujacy kod poszukuje opcji IP_TTL w otrzymanym buforze pomocniczym: struct msghdr msgh; struct cmsghdr *cmsg; int received_ttl; /* Otrzymywanie danych pomocniczych w msgh */ for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL; cmsg = CMSG_NXTHDR(&msgh, cmsg)) { if (cmsg->cmsg_level == IPPROTO_IP && cmsg->cmsg_type == IP_TTL) { memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl)); break; } } if (cmsg == NULL) { /* Blad: nie wlaczono IP_TTL lub maly bufor lub blad we/wy */ } Ponizszy kod przekazuje tablice deskryptorow plikow przez gniazdo domeny UNIX SCM_RIGHTS: struct msghdr msg = { 0 }; struct cmsghdr *cmsg; int myfds[NUM_FD]; /* Zawiera przekazywane deskryptory plikow */ char iobuf[1]; struct iovec io = { .iov_base = iobuf, .iov_len = sizeof(iobuf) }; union { /* Bufor danych pomocniczych, opakowany w unie, aby zapewnic jego odpowiednie wyrownanie */ char buf[CMSG_SPACE(sizeof(myfds))]; struct cmsghdr align; } u; msg.msg_iov = &io; msg.msg_iovlen = 1; msg.msg_control = u.buf; msg.msg_controllen = sizeof(u.buf); cmsg = CMSG_FIRSTHDR(&msg); cmsg->cmsg_level = SOL_SOCKET; cmsg->cmsg_type = SCM_RIGHTS; cmsg->cmsg_len = CMSG_LEN(sizeof(myfds)); memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds)); Pelny kod, pokazujacy takze przekazywanie deskryptorow pliku przez gniazdo domeny Uniksa, znajduje sie w podreczniku seccomp_unotify(2). ZOBACZ TAKZE recvmsg(2), sendmsg(2) RFC 2292 TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Andrzej Krzysztofowicz , Robert Luberda i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.9.1 2 maja 2024 r. CMSG(3)