Provided by: manpages-pl-dev_0.7-2_all 
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 {
size_t cmsg_len; /* Liczba bajtów danych, włączając nagłówek
(typ to socklen_t w POSIX) */
int cmsg_level; /* Protokół źródłowy */
int cmsg_type; /* Typ zależny od protokołu */
/* followed by
unsigned char cmsg_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 odbierane poprzez wywołanie recvmsg(2). Więcej informacji znajduje się na
stronach podręcznika tych poleceń.
Dane pomocnicze są ciągiem struktur struct cmsghdr z dodanymi danymi. Dostęp do tego ciągu
powinien się odbywać wyłącznie przez opisane na tej stronie podręcznika makrodefinicje,
nigdy zaś bezpośrednio. Dostępne rodzaje komunikatów sterujących opisano na stronach
podręcznika poszczególnych protokołów. Maksymalny rozmiar bufora danych pomocniczych dla
gniazda można ustawić, używając /proc/sys/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() zwraca żądaną długość, 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 zainicjować 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_NXTHDR(), aby otrzymać wszystkie
następne. Dla każdego komunikatu sterującego należy zainicjować 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()
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.
ZGODNE Z
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_ALIGN() jest
rozszerzeniem Linuksa.
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.
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 == IPPROTO_IP
&& cmsg->cmsg_type == IP_TTL) {
ttlptr = (int *) CMSG_DATA(cmsg);
received_ttl = *ttlptr;
break;
}
}
if (cmsg == NULL) {
/* Błąd: IP_TTL nie jest włączone, za mały bufor
lub błąd wejścia/wyjścia */
}
Poniższy kod przekazuje tablicę deskryptorów plików przez gniazdo domeny UNIX SCM_RIGHTS:
struct msghdr msg = { 0 };
struct cmsghdr *cmsg;
int myfds[NUM_FD]; /* Zawiera przekazywane deskryptory plików */
int *fdptr;
union { /* Bufor danych pomocniczych, opakowany w unię,
aby zapewnić jego odpowiednie wyrównanie */
char buf[CMSG_SPACE(sizeof(myfds))];
struct cmsghdr align;
} u;
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(int) * NUM_FD);
fdptr = (int *) CMSG_DATA(cmsg); /* Inicjacja payloadu */
memcpy(fdptr, myfds, NUM_FD * sizeof(int));
ZOBACZ TAKŻE
recvmsg(2), sendmsg(2)
RFC 2292
O STRONIE
Angielska wersja tej strony pochodzi z wydania 4.07 projektu Linux man-pages. Opis
projektu, informacje dotyczące zgłaszania błędów, oraz najnowszą wersję oryginału można
znaleźć pod adresem https://www.kernel.org/doc/man-pages/.
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika man są: 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ą 4.07
oryginału.