table of contents
- bookworm 1:4.18.1-1
- bookworm-backports 1:4.24.0-2~bpo12+1
- testing 1:4.24.0-2
- unstable 1:4.24.0-2
getnameinfo(3) | Library Functions Manual | getnameinfo(3) |
NAZWA¶
getnameinfo - tłumaczy adres na nazwę w sposób niezależny od protokołu
BIBLIOTEKA¶
Standardowa biblioteka C (libc, -lc)
SKŁADNIA¶
#include <sys/socket.h> #include <netdb.h>
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);
getnameinfo():
Od glibc 2.22:
_POSIX_C_SOURCE >= 200112L
glibc 2.21 i wcześniejsze:
_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 usługi) 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 usługi) 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 usługa jest oparta raczej na datagramach (UDP) niż na strumieniach (TCP). Jest to wymagane dla kilku portów (512–514), które mają przypisane inne usługi dla UDP niż dla TCP.
- NI_NOFQDN
- Jeżeli ustawiono, to zwracana jest tylko lokalna część nazwy komputera, a nie jego pełna 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 tego znacznika i nie można znaleźć nazwy komputera).
- NI_NUMERICSERV
- Jeśli ustawiono, to nazwa usługi jest zwracana w formie numerycznej (może się to również zdarzyć wtedy, gdy nie ustawiono tego znacznika 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 znaczniki:
- 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 znaczniki, odpowiednio, IDNA_ALLOW_UNASSIGNED (zezwala na nieprzypisane kody Unikodu) i IDNA_USE_STD3_ASCII_RULES (sprawdza wyjście, aby upewnić się że jest to nazwa stacji zgodna z STD3) do użycia w obsłudze 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 usługi.
- 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
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-bezpieczne env locale |
STANDARDY¶
POSIX.1-2008. RFC 2553.
HISTORIA¶
glibc 2.1. POSIX.1-2001.
Przed glibc 2.2, argumenty hostlen i servlen były wprowadzane jako size_t.
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 usług w bieżącym RFC dotyczącym przypisanych numerów (Assigned Numbers RFC).
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("stacja=%s, usługa=%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 udało się rozwiązać nazwy stacji"); else
printf("stacja=%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.
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 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.
2 maja 2024 r. | Linux man-pages 6.8 |