getnameinfo(3) Library Functions Manual getnameinfo(3) NAZWA getnameinfo - tlumaczenie adresu na nazwe w sposob niezalezny od protokolu BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include #include int getnameinfo(const struct sockaddr *restrict addr, socklen_t addrlen, char host[_Nullable restrict .hostlen], socklen_t hostlen, char serv[_Nullable restrict .servlen], 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 odwrotnoscia funkcji getaddrinfo(3): tlumaczy, w sposob niezalezny od protokolu, adres gniazda na odpowiadajace mu nazwe komputera i uslugi. Laczy w sobie funkcjonalnosc funkcji gethostbyaddr(3) oraz getservbyport(3), ale w przeciwienstwie do nich getnameinfo() jest bezpieczna dla watkow i pozwala programowi wyeliminowac zaleznosci od IPv4-kontra-IPv6. Argument addr jest wskaznikiem do ogolnej struktury adresu gniazda (typu sockaddr_in lub sockaddr_in6) o rozmiarze addrlen, ktora przechowuje wejsciowy adres IP i numer portu. Argumenty host i port sa wskaznikami do zaalokowanych przez program wywolujacy te funkcje buforow (odpowiednio o rozmiarach hostlen i servlen), w ktorych getnameinfo() umiesci zakonczone NULL-em lancuchy znakow zawierajace odpowiednio nazwe komputera i nazwy uslug. Funkcja wywolujaca moze okreslic, ze nazwa komputera (lub nazwa serwisu) nie jest potrzebna, przez przekazanie wartosci NULL w argumencie host (lub serv) albo przez podanie 0 w parametrze hostlen (lub servlen). Jednakze co najmniej jeden z podanych parametrow (nazwa komputera lub nazwa serwisu) musi byc ustawiony. Argument flags zmienia zachowanie getnameinfo() w nastepujacy sposob: NI_NAMEREQD Jesli ustawiono, to w razie nieznalezienia nazwy komputera zwracany jest blad. NI_DGRAM If set, then the service is datagram (UDP) based rather than stream (TCP) based. This is required for the few ports (512-514) that have different services for UDP and TCP. NI_NOFQDN Jezeli ustawiono, to zwracana jest tylko lokalna czesc nazwy komputera, a nie jego pelna domenowa nazwa sieciowa. NI_NUMERICHOST Jesli ustawiono, to nazwa komputera jest zwracana w formie numerycznej. (Moze sie to rowniez zdarzyc wtedy, gdy nie ustawiono tej flagi i nie mozna znalezc nazwy komputera). NI_NUMERICSERV Jesli ustawiono, to nazwa komputera jest zwracana w formie numerycznej. (Moze sie to rowniez zdarzyc wtedy, gdy nie ustawiono tej flagi i nie mozna znalezc nazwy komputera). Rozszerzenia getnameinfo() dotyczace miedzynarodowych nazw domen Poczawszy do wersji 2.3.4 biblioteki glibc, getnameinfo() zostal rozszerzony i pozwala na przezroczysta konwersje nazw komputerow do i z formatu miedzynarodowych nazw domenowych (Internationalized Domain Name -- IDN; patrz RFC 3490, Internationalizing Domain Names in Applications (IDNA)). Zostaly zdefiniowane trzy nowe flagi: NI_IDN Jesli uzyto tego znacznika, to nazwa znaleziona przez proces wyszukiwania jest konwertowana z formatu IDN na kodowanie zgodne z biezacymi ustawieniami jezykowymi. Nazwy skladajace sie wylacznie ze znakow ASCII nie sa zmieniane, co pozwala na bezproblemowe uzywanie tego znacznika w istniejacych programach i srodowiskach. NI_IDN_ALLOW_UNASSIGNED NI_IDN_USE_STD3_ASCII_RULES Ustawienie tych znacznikow wlaczy odpowiednio znaczniki IDNA_ALLOW_UNASSIGNED (zezwala na uzywanie nieprzypisanych znakow Unikodu) i IDNA_USE_STD3_ASCII_RULES (upewnia sie, ze zwracana nazwa komputera jest zgodna ze standardem STD3), ktore beda uzywane podczas obslugi IDNA. WARTOSC ZWRACANA W przypadku powodzenia zwracane jest 0, a nazwy komputera i uslug, jesli ich zazadano, sa wypelniane lancuchami znakow zakonczonymi NULL-em. Nazwy te moga zostac obciete, tak aby zmiescily sie w podanych dlugosciach bufora. W razie bledu zwracany jest jeden z ponizszych niezerowych kodow bledu: EAI_AGAIN Obecnie nie mozna znalezc nazwy. Prosze sprobowac pozniej. EAI_BADFLAGS Argument flags ma niepoprawna wartosc. EAI_FAIL Wystapil blad krytyczny. EAI_FAMILY Nieznana rodzina adresow lub dlugosc adresu nie jest odpowiednia dla podanej rodziny. EAI_MEMORY Brak pamieci. EAI_NONAME Nie mozna rozwinac nazwy dla podanych parametrow. Ustawiono NI_NAMEREQD, a nie mozna znalezc nazwy komputera albo nie zazadano ani nazwy komputera, ani nazwy serwisu. EAI_OVERFLOW Bufor, na ktory wskazywal parametr host lub serv, byl za maly. EAI_SYSTEM Wystapil blad systemowy. Numer bledu mozna znalezc w zmiennej errno. Funkcja gai_strerror(3) przeksztalca te kody bledow w komunikat zrozumialy dla czlowieka, wiec jest odpowiednia do raportowania bledow. PLIKI /etc/hosts /etc/nsswitch.conf /etc/resolv.conf ATRYBUTY Informacje o pojeciach uzywanych w tym rozdziale mozna znalezc w podreczniku attributes(7). +----------------+--------------------------+--------------------------+ |Interfejs | Atrybut | Wartosc | +----------------+--------------------------+--------------------------+ |getnameinfo() | Bezpieczenstwo watkowe | MT-bezpieczne env locale | +----------------+--------------------------+--------------------------+ STANDARDY POSIX.1-2008. RFC 2553. HISTORIA glibc 2.1. POSIX.1-2001. Before glibc 2.2, the hostlen and servlen arguments were typed as size_t. UWAGI Aby pomoc programiscie w wyborze odpowiedniego rozmiaru buforow, w zdefiniowano stale #define NI_MAXHOST 1025 #define NI_MAXSERV 32 Od glibc 2.8 powyzsze definicje sa dostepne, jesli zdefiniowano odpowiednie makro, mianowicie: _GNU_SOURCE, _DEFAULT_SOURCE (od glibc 2.19) lub (w wersjach glibc do 2.19 wlacznie) _BSD_SOURCE lub _SVID_SOURCE. Pierwsza z nich jest stala MAXDNAME zdefiniowana w pliku naglowkowym z nowszych wersji BIND-a. Druga jest zgadywaniem opartym na liscie serwisow w biezacym RFC dotyczacym przypisanych numerow (Assigned Numbers RFC). PRZYKLADY Nastepujacy kod probuje pobrac numeryczna nazwe komputera i nazwe uslugi dla podanego adresu gniazda. Prosze zauwazyc, ze nie ustawiono na sztywno zadnej rodziny adresow. struct sockaddr *addr; /* input */ socklen_t addrlen; /* input */ 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); Nastepujaca wersja sprawdza, czy adres gniazda ma odwrotne mapowanie adresu. struct sockaddr *addr; /* input */ socklen_t addrlen; /* input */ char hbuf[NI_MAXHOST]; if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), NULL, 0, NI_NAMEREQD)) printf("could not resolve hostname"); else printf("host=%s\n", hbuf); Przykladowy program uzywajacy getnameinfo() mozna znalezc w getaddrinfo(3). ZOBACZ TAKZE 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 trwaja . Craig Metz, Protocol Independence Using the Sockets API, Proceedings of the freenix track: Coroczna techniczna konferencja USENIX 2000, czerwiec 2000 . TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Robert Luberda i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.06 31 pazdziernika 2023 r. getnameinfo(3)