GETNAMEINFO(3) | Podręcznik programisty Linuksa | GETNAMEINFO(3) |
getnameinfo - tłumaczenie adresu na nazwę w sposób niezależny od protokołu
#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():
Od glibc 2.22: _POSIX_C_SOURCE >= 201112L
Glibc 2.21 i wcześniejsze: _POSIX_C_SOURCE
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 sa 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:
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:
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:
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.
/etc/hosts
/etc/nsswitch.conf
/etc/resolv.conf
getnameinfo() jest dostarczane przez glibc od wersji 2.1.
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 |
POSIX.1-2001, POSIX.1-2008, RFC 2553.
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.
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).
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 i 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.
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/.
Autorami polskiego tłumaczenia niniejszej strony podręcznika man są: 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.
2016-03-15 | GNU |