Provided by: manpages-pl-dev_4.23.1-1_all 
NAZWA
CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - uzyskuje dostęp do danych pomocniczych
BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)
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);
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 cmsghdr z dodanymi danymi. 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).
Struktura cmsghdr jest zdefiniowana następująco:
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 */
/* po których następuje
unsigned char cmsg_data[]; */
};
Dostęp do ciągu struktur cmsghdr nidy nie powinien się odbywać bezpośrednio. Należy używać następujących
makrodefinicji:
CMSG_FIRSTHDR()
zwraca wskaźnik do pierwszego cmsghdr w buforze danych pomocniczych związanym z przekazanym
msghdr. Zwraca NULL, jeśli bufor jest za mały, by pomieścić cmsghdr.
CMSG_NXTHDR()
zwraca następny poprawny cmsghdr po przekazanym cmsghdr. Zwraca NULL, gdy brak dostatecznej ilości
miejsca w buforze.
Podczas inicjowania bufora, który ma zawierać ciąg struktur cmsghdr (na przykład w celu
przesłania za pomocą sendmsg(2)), bufor ten powinien być najpierw inicjowany zerami, tak aby
zapewnić poprawne działanie CMSG_NXTHDR().
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 z danymi cmsghdr. Nie można zakładać, że zwracany wskaźnik zostanie
wystarczająco wyrównany, do dostępu do dowolnych typów zawartości danych. Aplikacje nie powinny
rzutować go na typ wskaźnika pasujący do zawartości, lecz korzystać z memcpy(3), aby kopiować dane
z, lub do, odpowiednio zadeklarowanego obiektu.
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).
WERSJE
Dla przenośności, dostęp do danych pomocniczych powinien się odbywać jedynie za pomocą opisanych tu
makrodefinicji.
W Linuksie, CMSG_LEN(), CMSG_DATA() i CMSG_ALIGN() są wyrażeniami stałymi (zakładając, że ich argument
jest stały), co oznacza, że te wartości można do zadeklarowania rozmiaru zmiennych globalnych. Jednakże,
może się to okazać nieprzenośne.
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() będą objęte następnym wydaniem POSIX (Issue 8).
PRZYKŁADY
Następujący 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) {
/* Błąd: nie włączono IP_TTL lub mały bufor lub błąd we/wy */
}
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 */
char iobuf[1];
struct iovec io = {
.iov_base = iobuf,
.iov_len = sizeof(iobuf)
};
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_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));
Pełny kod, pokazujący także przekazywanie deskryptorów pliku przez gniazdo domeny Uniksa, znajduje się w
podręczniku seccomp_unotify(2).
ZOBACZ TAKŻE
recvmsg(2), sendmsg(2) RFC 2292
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Andrzej Krzysztofowicz
<ankry@green.mf.pg.gda.pl>, Robert Luberda <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać
zapoznając się z GNU General Public License w wersji 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ lub
nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej ⟨manpages-pl-
list@lists.sourceforge.net⟩.