|
Beschreibung
Mit der Funktion getaddrinfo() liefert protokollunabhängig Rechnerinformationen für die Adressfamilien AF_INET und AF_INET6. Die Werte werden entweder über den Domain Name Service (DNS) oder über systemspezifische Tabellen ermittelt.
Parameter nodename und servname
Beim Aufruf von getaddrinfo() muss mindestens einer der Parameter nodename oder servname vom Null-Zeiger verschieden sein. nodename und servname sind entweder ein Null-Zeiger oder ein mit dem Null-Byte abgeschlossener String. Der Parameter nodename kann sowohl ein Name sein, als auch eine IPv4-Adresse in dezimaler Punkt-Notation oder eine IPv6-Adresse in sedezimaler Doppelpunkt-Notation. Der Parameter servname kann entweder ein Service-Name oder eine dezimale Portnummer sein.
Parameter hints
Mit dem Parameter hints wird optional eine addrinfo-Struktur übergeben. Andernfalls muss der Parameter hints der Null-Zeiger sein.
Die Struktur addrinfo ist wie folgt deklariert:
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
int ai_family; /* AF_INET, AF_INET6 */
int ai_socktype; /* SOCK_STREAM, SOCK_DGRAM */
int ai_protocol; /* 0 oder IPPROTO_xxx für IP */
size_t ai_addrlen; /* Länge von ai_addr */
char*ai_canonname; /* kanonischer Name */
struct sockaddr *ai_addr; /* Socket-Adress-Struktur */
struct addrinfo *ai_next; /* nächste Struktur der Liste */
};
In dem mit hints übergebenen Objekt vom Typ struct addrinfo müssen alle Elemente außer ai_flags, ai_family und ai_socktype den Wert 0 haben bzw. der Null-Zeiger sein.
Mit den Werten für die addrinfo-Komponenten ai_flags, ai_family und ai_socktype legen Sie eine Auswahl fest:
ai_family = PF_UNSPEC bedeutet, dass jede Protokollfamilie gewünscht ist.
ai_socktype = 0 bedeutet, dass jeder Socket-Typ akzeptiert ist.
ai_flags = AI_PASSIVE bedeutet, dass die zurückgelieferte Sockets-Adress-Struktur für einen bind()-Aufruf verwendet werden soll. Wenn nodename = NULL ist (siehe oben), wird das IP-Adresselement bei einer IPv4-Adresse mit INADDR_ANY und bei einer IPv6-Adresse mit IN6ADDR_ANY versorgt.
Wenn das AI_PASSIVE-Bit nicht gesetzt ist, wird die zurückgelieferte Socket-Adress-Struktur wie folgt verwendet:
für einen connect()-Aufruf bei ai_socktype = SOCK_STREAM
für einen connect()-, sendto()- oder sendmsg()-Aufruf bei ai_socktype = SOCK_DGRAM
Wenn in diesen Fällen nodename der Null-Zeiger ist, wird die IP-Adresse von sockaddr mit dem Wert der loopback-Adresse versorgt.
Wenn das Bit ai_flags = AI_CANONNAME gesetzt ist, enthält bei erfolgreicher Ausführung von getaddrinfo() die erste zurückgegebene addrinfo-Struktur im Element ai_canonname den Socket-Hostnamen des ausgewählten Rechners. Dieser Socket-Hostname ist mit dem Null-Byte abgeschlossen.
Wenn das Bit ai_flags = AI_NUMERICHOST gesetzt ist, muss ein vom Null-Zeiger verschiedener nodename entweder ein IPv4-Adress-String in dezimaler Punkt-Notation oder ein IPv6-Adress-String in sedezimaler Doppelpunkt-Notation sein. Andernfalls wird der Returnwert EAI_NONAME geliefert. Das Flag verhindert einen Aufruf zur Namensauflösung durch einen DNS-Service oder interne Rechnertabellen.
hints = NULL bewirkt das Gleiche wie eine mit 0 initialisierte addrinfo-Struktur mit ai_family = PF_UNSPEC.
Parameter res
Bei erfolgreicher Ausführung von getaddrinfo() wird in res ein Zeiger auf eine oder mehrere miteinander verkettete addrinfo-Strukturen übergeben. Das Element ai_next = NULL kennzeichnet das letzte Kettenelement. Jede der zurückgelieferten addrinfo-Strukturen enthält in den Elementen ai_family und ai_socktype einen zum socket()-Aufruf korrespondierenden Wert. ai_addr zeigt immer auf eine Socket-Adress-Struktur, deren Länge in ai_addrlen spezifiziert ist.
Returnwert
0:
Bei Erfolg.
>0:
Fehler, Returnwert ist ein in <netdb.h> definierter Fehlercode EAI_xxx.
-1:
Fehler, errno wird gesetzt, um den Fehler anzuzeigen
Fehler
EAFNOSUPPORT
Die Funktion wird an diesem System nicht unterstützt. Vergleichen Sie dazu auch "Abhängigkeiten vom BS2000-Transportsystem BCAM".
In <netdb.h> definierte Fehlercodes:
EAI_ADDRFAMILY
Die Adressfamilie wird für den angegebenen Rechner nicht unterstützt.
EAI_AGAIN
Temporärer Fehler beim Zugriff auf die Rechnernamen-Information (z.B. DNS-Fehler).
Der Aufruf der Funktion sollte wiederholt werden.
EAI_BADFLAGS
Ungültiger Wert für den Operanden ai_flags.
EAI_FAIL
Fehler beim Zugriff auf die Rechnernameninformation.
EAI_FAMILY
Die Protokoll-Familie wird nicht unterstützt.
EAI_MEMORY
Fehler bei Speicheranforderung.
EAI_NODATA
Keine zum Rechnernamen korrespondierende Adresse gefunden.
EAI_NONAME
Rechner- oder Service-Name werden nicht unterstützt, oder sind unbekannt.
EAI_SERVICE
Service wird für den Socket-Typ nicht unterstützt.
EAI_SOCKTYPE
Der Socket-Typ wird nicht unterstützt.
EAI_SYSTEM
System-Fehler, wird in errno näher spezifiziert.
Hinweis
Der Speicher für die von getaddrinfo() gelieferten addrinfo-Strukturen wird dynamisch angefordert und muss mit der Funktion freeaddrinfo() wieder freigegeben werden.