#include <sys.socket.h>
#include <netdb.h>
Kernighan-Ritchie-C:
int getaddrinfo(nodename, servname, hints, res);
const char *nodename;
const char *servname;
const struct addrinfo *hints;
const struct addrinfo **res;
ANSI-C:
int getaddrinfo(const char* nodename, const char* servname, const struct
addrinfo* hints, const struct addrinfo** res);
Beschreibung
Die Funktion getaddrinfo() ermöglicht die protokollunabhängige Abfrage von Rechnerinformationen für die Adressfamilien AF_INET und AF_INET6.
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 kann optional eine addrinfo-Struktur übergeben werden. 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,AI_NUMERICHOST*/
/* AI_NUMERICSERV,AI_V4MAPPED,AI_ALL */
/* AI_NUMERICHOST*/
int ai_family; /* PF_INET,PF_INET6 */
int ai_socktype; /* SOCK_STREAM,SOCK_DGRAM*/
int ai_protocol; /* 0 (in SOCKETS nicht unterstützt) */
size_t ai_addrlen; /* Länge der Adresse */
char* ai_canonname; /* Kanonischer Name des Knotens */
struct sockaddr *ai_addr; /* Socket-Adress-Struktur der Adress-*/
/* familie AF_INET oder AF_INET6 */
struct addrinfo *ai_next; /* Zeiger auf das nächste Objekt der
verketteten Liste */};
In dem mit hints übergebenen Objekt vom Typ struct addrinfo müssen alle Elemente außer ai_flags, ai_family, 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 wird eine Auswahl festgelegt:
ai_family = PF_UNSPEC bedeutet, dass jede Protokollfamilie gewünscht wird.
ai_socktype = 0 bedeutet, dass für jeden Socket-Typ eine addrinfo-Struktur mit dem gewünschten Service angelegt werden soll.
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 gesetzt.
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()-, 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 in den ai_flags der hints-Struktur das Bit AI_CANONNAME gesetzt ist, enthält bei erfolgreicher Ausführung von getaddrinfo() mindestens die erste zurückgegebene addrinfo-Struktur im Element ai_canonname den Zeiger auf den mit einem Null-Byte abgeschlossenen kanonischen Namen des ausgewählten Rechners.
Der ai_canonname wird durch einen Reverse Lookup ermittelt. Falls dieser Reverse Lookup nicht erfolgreich ist, also zur mitgegebenen Adresse kein Name gefunden wurde, wird kein Fehler gemeldet, sondern im Element ai_canonname wird der Inhalt des Parameters nodename hineinkopiert, wenn er ungleich dem Null-Zeiger ist. Ist nodename ein Null-Zeiger, wird im Element ai_canonname ein Null-Zeiger eingetragen.
Bitte beachten Sie, dass der Inhalt von nodename auch eine Adresse sein kann! Auch diese wird dann kopiert.Wenn in den ai_flags der hints-Struktur das Bit AI_NUMERICHOST gesetzt ist, muss ein vom Null-Zeiger verschiedener nodename 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.
Wenn in den ai_flags der hints-Struktur das Bit AI_V4MAPPED in Verbindung mit ai_family = PF_INET6 gesetzt ist und keine IPv6-Adressen für den Namen geliefert werden, dann werden in der Ausgabeliste vorhandene IPv4-Adressen in Form einer IPv4-mapped IPv6-Adresse eingetragen.
Ist auch das Bit AI_ALL gesetzt, werden sowohl IPv6- als auch die IPv4-mapped IPv6-Adressen eingetragen.Wenn in den ai_flags der hints-Struktur das Bit AI_ADDRCONFIG gesetzt ist, dann werden zum Namen gehörige IPv4- oder IPv6-Adressen nur ausgegeben, wenn eine entsprechende Interface-Adresse auf dem lokalen Rechner definiert ist. Die Loopback-Adresse zählt hier nicht als konfigurierte Interface-Adresse.
Wenn in den ai_flags der hints-Struktur das Bit AI_NUMERICSERV gesetzt ist, dann muss der von Null verschiedene Zeiger von servname auf eine numerische Portnummern-Zeichenkette verweisen. Ist das nicht der Fall, wird eine Fehlermeldung (EAI_NONAME) zurückgegeben.
hints = NULL bewirkt das Gleiche wie eine mit 0 initialisierte addrinfo-Struktur und 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, wobei das Element ai_next = NULL das letzte Kettenelement kennzeichnet. 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.
Fehlercode in <netdb.h> definiert:
EAI_ADDRFAMILY
Die Internet-Adressfamilien werden 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 Rechnernamen-Information
EAI_FAMILY
Die Protokoll-Familie wird nicht unterstützt.
EAI_MEMORY
Fehler bei Speicheranforderung
EAI_NODATA
Keine zum Rechnernamen korrespondierende Adressen 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.
In SOCKETS(BS2000) ist PF_UNSPEC = AF_UNSPEC.
Wenn DNS nicht genutzt wird, geben Sie keinen full-qualified-domain-name an, sondern nur den Rechnernamen, um die BCAM-Prozessor-Tabelle zu nutzen (z.B. host statt host.mydomain.net).
Für den Zugang zum DNS wird der für SOCKETS(BS2000), BCAM und POSIX-Sockets gemeinsame Resolver LWRESD genutzt. Näheres siehe Handbuch „BCAM Band 1/2“.