cmsg

CMSG(3)                  Podręcznik programisty Linuksa                  CMSG(3)



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);

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()  returns a pointer to the data portion of a cmsghdr.  The
          pointer returned cannot be assumed to be suitably aligned for
          accessing arbitrary payload data types.  Applications should not cast
          it to a pointer type matching the payload, but should instead use
          memcpy(3)  to copy data to or from a suitably declared object.

       *  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).

ZGODNE Z
       This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
       the IPv6 advanced API described in RFC 2292 and SUSv2.  CMSG_FIRSTHDR(),
       CMSG_NXTHDR(), and CMSG_DATA()  are specified in POSIX.1-2008.
       CMSG_SPACE()  and CMSG_LEN()  will be included in the next POSIX release
       (Issue 8).

       CMSG_ALIGN()  is a Linux extension.

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), co oznacza, że te wartości
       można do zadeklarowania rozmiaru zmiennych globalnych. Jednakże, może się
       to okazać nieprzenośne.

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 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) {
                   memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl));
                   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 */
           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));

ZOBACZ TAKŻE
       recvmsg(2), sendmsg(2)

       RFC 2292

O STRONIE
       Angielska wersja tej strony pochodzi z wydania 5.11 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 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
       manpages-pl-list@lists.sourceforge.net ⟨⟩.



Linux                           22 marca 2021 r.                         CMSG(3)