.\" -*- coding: UTF-8 -*-
.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
.\"
.\" %%%LICENSE_START(VERBATIM_ONE_PARA)
.\" Permission is granted to distribute possibly modified copies
.\" of this page provided the header is included verbatim,
.\" and in case of nontrivial modification author and date
.\" of the modification is added to the header.
.\" %%%LICENSE_END
.\"
.\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH CMSG 3 "1 listopada 2020 r." Linux "Podręcznik programisty Linuksa"
.SH NAZWA
CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- dostęp do danych
pomocniczych
.SH SKŁADNIA
.nf
\fB#include <sys/socket.h>\fP
\fBstruct cmsghdr *CMSG_FIRSTHDR(struct msghdr *\fP\fImsgh\fP\fB);\fP
\fBstruct cmsghdr *CMSG_NXTHDR(struct msghdr *\fP\fImsgh\fP\fB,\fP
\fB                            struct cmsghdr *\fPcmsg\fB);\fP
\fBsize_t CMSG_ALIGN(size_t \fP\fIlength\fP\fB);\fP
\fBsize_t CMSG_SPACE(size_t \fP\fIlength\fP\fB);\fP
\fBsize_t CMSG_LEN(size_t \fP\fIlength\fP\fB);\fP
\fBunsigned char *CMSG_DATA(struct cmsghdr *\fP\fIcmsg\fP\fB);\fP
.fi
.SH 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 \fBsendmsg\fP(2), a odbierane poprzez wywołanie \fBrecvmsg\fP(2).
Więcej informacji znajduje się na stronach podręcznika tych poleceń.
.PP
Dane pomocnicze są ciągiem struktur \fIcmsghdr\fP 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 \fI/proc/sys/net/core/optmem_max\fP; patrz
\fBsocket\fP(7).
.PP
Struktura \fIcmsghdr\fP jest zdefiniowana następująco:
.PP
.in +4n
.EX
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[]; */
};
.EE
.in
.PP
Dostęp do ciągu struktur \fIcmsghdr\fP nidy nie powinien się odbywać
bezpośrednio. Należy używać następujących makrodefinicji:
.IP * 3
\fBCMSG_FIRSTHDR\fP() zwraca wskaźnik do pierwszego \fIcmsghdr\fP w buforze danych
pomocniczych związanym z przekazanym \fImsghdr\fP. Zwraca NULL, jeśli bufor
jest za mały, by pomieścić \fIcmsghdr\fP.
.IP *
\fBCMSG_NXTHDR\fP() zwraca następny poprawny \fIcmsghdr\fP po przekazanym
\fIcmsghdr\fP. Zwraca NULL, gdy brak dostatecznej ilości miejsca w buforze.
.IP
Podczas inicjowania bufora, który ma zawierać ciąg struktur \fIcmsghdr\fP (na
przykład  w celu przesłania za pomocą \fBsendmsg\fP(2)), bufor ten powinien być
najpierw inicjowany zerami, tak aby zapewnić poprawne działanie
\fBCMSG_NXTHDR\fP().
.IP *
\fBCMSG_ALIGN\fP() zwraca żądaną długość, włączając niezbędne wyrównanie. Jest
to wyrażenie stałe.
.IP *
\fBCMSG_SPACE\fP() zwraca liczbę bajtów elementu pomocniczego włączając
długość, jaką zajmują przekazane dane. Jest to wyrażenie stałe.
.IP *
\fBCMSG_DATA\fP()  returns a pointer to the data portion of a \fIcmsghdr\fP.  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 \fBmemcpy\fP(3)  to copy data
to or from a suitably declared object.
.IP *
\fBCMSG_LEN\fP() zwraca wartość, która ma być przechowywana w elemencie
\fIcmsg_len\fP struktury \fIcmsghdr\fP, biorąc pod uwagę wszelkie niezbędne
wyrównania. Jako argument pobiera długość danych. Jest to wyrażenie stałe.
.PP
Aby utworzyć dane pomocnicze, należy najpierw zainicjować element
\fImsg_controllen\fP struktury \fImsghdr\fP długością bufora komunikatów
sterujących. Należy użyć \fBCMSG_FIRSTHDR\fP() dla \fImsghdr\fP, aby otrzymać
pierwszy komunikat sterujący, oraz \fBCMSG_NXTHDR\fP(), aby otrzymać wszystkie
następne. Dla każdego komunikatu sterującego należy zainicjować \fIcmsg_len\fP
(za pomocą \fBCMSG_LEN\fP()), inne pola nagłówka \fIcmsghdr\fP oraz część
zawierającą dane za pomocą \fBCMSG_DATA\fP(). Ostatecznie pole
\fImsg_controllen\fP struktury \fImsghdr\fP powinno zawierać sumę \fBCMSG_SPACE\fP()
długości wszystkich komunikatów sterujących w buforze. Więcej informacji
dotyczących \fImsghdr\fP znajduje się w \fBrecvmsg\fP(2).
.SH "ZGODNE Z"
.\" https://www.austingroupbugs.net/view.php?id=978#c3242
This ancillary data model conforms to the POSIX.1g draft, 4.4BSD\-Lite, the
IPv6 advanced API described in RFC\ 2292 and SUSv2.  \fBCMSG_FIRSTHDR\fP(),
\fBCMSG_NXTHDR\fP(), and \fBCMSG_DATA\fP()  are specified in POSIX.1\-2008.
\fBCMSG_SPACE\fP()  and \fBCMSG_LEN\fP()  will be included in the next POSIX
release (Issue 8).
.PP
\fBCMSG_ALIGN\fP()  is a Linux extension.
.SH UWAGI
Dla przenośności, dostęp do danych pomocniczych powinien się odbywać jedynie
za pomocą opisanych tu makrodefinicji. \fBCMSG_ALIGN\fP() jest rozszerzeniem
Linuksa i nie powinno być używane w przenośnych programach.
.PP
W Linuksie, \fBCMSG_LEN\fP(), \fBCMSG_DATA\fP() i \fBCMSG_ALIGN\fP() 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.
.SH PRZYKŁADY
Następujący kod poszukuje opcji \fBIP_TTL\fP w otrzymanym buforze pomocniczym:
.PP
.in +4n
.EX
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 */
}
.EE
.in
.PP
Poniższy kod przekazuje tablicę deskryptorów plików przez gniazdo domeny
UNIX \fBSCM_RIGHTS\fP:
.PP
.in +4n
.EX
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));
.EE
.in
.SH "ZOBACZ TAKŻE"
\fBrecvmsg\fP(2), \fBsendmsg\fP(2)
.PP
RFC\ 2292
.SH "O STRONIE"
Angielska wersja tej strony pochodzi z wydania 5.10 projektu Linux
\fIman\-pages\fP. 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/.

.SH 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
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License w wersji 3
.UE
lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.

Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres
.MT
manpages-pl-list@lists.sourceforge.net
.ME .
