Provided by: manpages-pl-dev_4.13-4_all 
NAZWA
getnameinfo - tłumaczenie adresu na nazwę w sposób niezależny od protokołu
SKŁADNIA
#include <sys/socket.h>
#include <netdb.h>
int getnameinfo(const struct sockaddr *addr, socklen_t addrlen,
char *host, socklen_t hostlen,
char *serv, socklen_t servlen, int flags);
Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):
getnameinfo():
Since glibc 2.22: _POSIX_C_SOURCE >= 200112L
Glibc 2.21 and earlier: _POSIX_C_SOURCE
OPIS
Funkcja getnameinfo() jest odwrotnością funkcji getaddrinfo(3): tłumaczy, w sposób
niezależny od protokołu, adres gniazda na odpowiadające mu nazwę komputera i usługi. Łączy
w sobie funkcjonalność funkcji gethostbyaddr(3) oraz getservbyport(3), ale w
przeciwieństwie do nich getnameinfo() jest bezpieczna dla wątków i pozwala programowi
wyeliminować zależności od IPv4-kontra-IPv6.
Argument addr jest wskaźnikiem do ogólnej struktury adresu gniazda (typu sockaddr_in lub
sockaddr_in6) o rozmiarze addrlen, która przechowuje wejściowy adres IP i numer portu.
Argumenty host i port są wskaźnikami do zaalokowanych przez program wywołujący tę funkcję
buforów (odpowiednio o rozmiarach hostlen i servlen), w których getnameinfo() umieści
zakończone NULL-em łańcuchy znaków zawierające odpowiednio nazwę komputera i nazwy usług.
Funkcja wywołująca może określić, że nazwa komputera (lub nazwa serwisu) nie jest
potrzebna, przez przekazanie wartości NULL w argumencie host (lub serv) albo przez podanie
0 w parametrze hostlen (lub servlen). Jednakże co najmniej jeden z podanych parametrów
(nazwa komputera lub nazwa serwisu) musi być ustawiony.
Argument flags zmienia zachowanie getnameinfo() w następujący sposób:
NI_NAMEREQD
Jeśli ustawiono, to w razie nieznalezienia nazwy komputera zwracany jest błąd.
NI_DGRAM
Jeżeli ustawiono, to serwis jest oparty raczej na datagramach (UDP) niż na
strumieniach (TCP). Jest to wymagane dla kilku portów (512\n514), które mają
przypisane inne serwisy dla UDP niż dla TCP.
NI_NOFQDN
Jeżeli ustawiono, to zwracana jest tylko lokalna część nazwy komputera, a nie jego
pełną domenowa nazwa sieciowa.
NI_NUMERICHOST
Jeśli ustawiono, to nazwa komputera jest zwracana w formie numerycznej. (Może się
to również zdarzyć wtedy, gdy nie ustawiono tej flagi i nie można znaleźć nazwy
komputera).
NI_NUMERICSERV
Jeśli ustawiono, to nazwa komputera jest zwracana w formie numerycznej. (Może się
to również zdarzyć wtedy, gdy nie ustawiono tej flagi i nie można znaleźć nazwy
komputera).
Rozszerzenia getnameinfo() dotyczące międzynarodowych nazw domen
Począwszy do wersji 2.3.4 biblioteki glibc, getnameinfo() został rozszerzony i pozwala na
przezroczystą konwersję nazw komputerów do i z formatu międzynarodowych nazw domenowych
(Internationalized Domain Name — IDN; patrz RFC 3490, Internationalizing Domain Names in
Applications (IDNA)). Zostały zdefiniowane trzy nowe flagi:
NI_IDN Jeśli użyto tego znacznika, to nazwa znaleziona przez proces wyszukiwania jest
konwertowana z formatu IDN na kodowanie zgodne z bieżącymi ustawieniami językowymi.
Nazwy składające się wyłącznie ze znaków ASCII nie są zmieniane, co pozwala na
bezproblemowe używanie tego znacznika w istniejących programach i środowiskach.
NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
Ustawienie tych znaczników włączy odpowiednio znaczniki IDNA_ALLOW_UNASSIGNED
(zezwala na używanie nieprzypisanych znaków Unikodu) i IDNA_USE_STD3_ASCII_RULES
(upewnia się, że zwracana nazwa komputera jest zgodna ze standardem STD3), które
będą używane podczas obsługi IDNA.
WARTOŚĆ ZWRACANA
W przypadku powodzenia zwracane jest 0, a nazwy komputera i usług, jeśli ich zażądano, są
wypełniane łańcuchami znaków zakończonymi NULL-em. Nazwy te mogą zostać obcięte, tak aby
zmieściły się w podanych długościach bufora. W razie błędu zwracany jest jeden z
poniższych niezerowych kodów błędu:
EAI_AGAIN
Obecnie nie można znaleźć nazwy. Proszę spróbować później.
EAI_BADFLAGS
Argument flags ma niepoprawną wartość.
EAI_FAIL
Wystąpił błąd krytyczny.
EAI_FAMILY
Nieznana rodzina adresów lub długość adresu nie jest odpowiednia dla podanej
rodziny.
EAI_MEMORY
Brak pamięci.
EAI_NONAME
Nie można rozwinąć nazwy dla podanych parametrów. Ustawiono NI_NAMEREQD, a nie
można znaleźć nazwy komputera albo nie zażądano ani nazwy komputera, ani nazwy
serwisu.
EAI_OVERFLOW
Bufor, na który wskazywał parametr host lub serv, był za mały.
EAI_SYSTEM
Wystąpił błąd systemowy. Numer błędu można znaleźć w zmiennej errno.
Funkcja gai_strerror(3) przekształca te kody błędów w komunikat zrozumiały dla człowieka,
więc jest odpowiednia do raportowania błędów.
PLIKI
/etc/hosts
/etc/nsswitch.conf
/etc/resolv.conf
WERSJE
getnameinfo() jest dostarczane przez glibc od wersji 2.1.
ATRYBUTY
Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku
attributes(7).
┌──────────────┬────────────────────────┬────────────────────┐
│Interfejs │ Atrybut │ Wartość │
├──────────────┼────────────────────────┼────────────────────┤
│getnameinfo() │ Bezpieczeństwo wątkowe │ MT-Safe env locale │
└──────────────┴────────────────────────┴────────────────────┘
ZGODNE Z
POSIX.1-2001, POSIX.1-2008, RFC 2553.
UWAGI
Aby pomóc programiście w wyborze odpowiedniego rozmiaru buforów, w <netdb.h> zdefiniowano
stałe
#define NI_MAXHOST 1025
#define NI_MAXSERV 32
Od glibc 2.8 powyższe definicje są dostępne, jeśli zdefiniowano odpowiednie makro,
mianowicie: _GNU_SOURCE, _DEFAULT_SOURCE (od glibc 2.19) lub (w wersjach glibc do 2.19
włącznie) _BSD_SOURCE lub _SVID_SOURCE.
Pierwsza z nich jest stałą MAXDNAME zdefiniowaną w pliku nagłówkowym <arpa/nameser.h> z
nowszych wersji BIND-a. Druga jest zgadywaniem opartym na liście serwisów w bieżącym RFC
dotyczącym przypisanych numerów (Assigned Numbers RFC).
Przed glibc w wersji 2.2 argumenty hostlen i servlen były wprowadzane jako size_t.
PRZYKŁADY
Następujący kod próbuje pobrać numeryczną nazwę komputera i nazwę usługi dla podanego
adresu gniazda. Proszę zauważyć, że nie ustawiono na sztywno żadnej rodziny adresów.
struct sockaddr *addr; /* wejście */
socklen_t addrlen; /* wejście */
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf,
sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
printf("host=%s, serv=%s\n", hbuf, sbuf);
Następująca wersja sprawdza, czy adres gniazda ma odwrotne mapowanie adresu.
struct sockaddr *addr; /* wejście */
socklen_t addrlen; /* wejście */
char hbuf[NI_MAXHOST];
if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf),
NULL, 0, NI_NAMEREQD))
printf("nie można znaleźć nazwy komputera");
else
printf("komputer=%s\n", hbuf);
Przykładowy program używający getnameinfo() można znaleźć w getaddrinfo(3).
ZOBACZ TAKŻE
accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2), getaddrinfo(3),
gethostbyaddr(3), getservbyname(3), getservbyport(3), inet_ntop(3), hosts(5), services(5),
hostname(7), named(8)
R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket Interface Extensions for
IPv6, RFC 2553, marzec 1999.
Tatsuya Jinmei i Atsushi Onoe, An Extension of Format for IPv6 Scoped Addresses, szkic
internetowy, prace trwają ⟨ftp://ftp.ietf.org/internet-drafts
/draft-ietf-ipngwg-scopedaddr-format-02.txt⟩.
Craig Metz, Protocol Independence Using the Sockets API, Proceedings of the freenix track:
Coroczna techniczna konferencja USENIX 2000, czerwiec 2000 ⟨http://www.usenix.org
/publications/library/proceedings/usenix2000/freenix/metzprotocol.html⟩.
O STRONIE
Angielska wersja tej strony pochodzi z wydania 5.10 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ą: 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⟩.