gethostname-Funktion (winsock2.h)

Artikel
03/04/2024

Die gethostname-Funktion ruft den Standardhostnamen für den lokalen Computer ab.

Syntax

int WSAAPI gethostname(
  [out] char *name,
  [in]  int  namelen
);

Parameter

[out] name

Ein Zeiger auf einen Puffer, der den lokalen Hostnamen empfängt.

[in] namelen

Die Länge des Puffers in Bytes, auf den der name-Parameter verweist.

Rückgabewert

Wenn kein Fehler auftritt, gibt gethostname null zurück. Andernfalls wird SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSAEFAULT	Der name-Parameter ist ein NULL-Zeiger oder ist kein gültiger Teil des Benutzeradressraums. Dieser Fehler wird auch zurückgegeben, wenn die vom parameter namelen angegebene Puffergröße zu klein ist, um den vollständigen Hostnamen aufzunehmen.
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSAENETDOWN	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAEINPROGRESS	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion.

Hinweise

Die gethostname-Funktion gibt den Namen des lokalen Hosts in den puffer zurück, der durch den name-Parameter angegeben wird. Der Hostname wird als NULL-beendete Zeichenfolge zurückgegeben. Die Form des Hostnamens ist vom Windows Sockets-Anbieter abhängig– es kann sich um einen einfachen Hostnamen oder um einen vollqualifizierten Domänennamen handeln. Es ist jedoch garantiert, dass der zurückgegebene Name von gethostbyname und WSAAsyncGetHostByName erfolgreich analysiert wird.

Die maximale Länge des im Puffer zurückgegebenen Namens, auf den der name-Parameter verweist, hängt vom Namespaceanbieter ab.

Wenn die gethostname-Funktion für eine Clusterressource unter Windows Server 2008, Windows Server 2003 oder Windows 2000 Server verwendet wird und die CLUSTER_NETWORK_NAME Umgebungsvariable definiert ist, überschreibt der Wert in dieser Umgebungsvariable den tatsächlichen Hostnamen und wird zurückgegeben. Bei einer Clusterressource enthält die umgebungsvariable CLUSTER_NETWORK_NAME den Namen des Clusters.

Die gethostname-Funktion fragt Namespaceanbieter ab, um den lokalen Hostnamen mithilfe der in der Headerdatei Svgguid.h definierten SVCID_HOSTNAME GUID zu ermitteln. Wenn kein Namespaceanbieter antwortet, gibt die Gethostname-Funktion den NetBIOS-Namen des lokalen Computers zurück.

Die maximale Länge der Zeichenfolge in Bytes, die im Puffer zurückgegeben wird, auf den der name-Parameter verweist, ist vom Namespaceanbieter abhängig, aber diese Zeichenfolge muss 256 Bytes oder weniger sein. Wenn also ein Puffer von 256 Bytes im name-Parameter übergeben und der namelen-Parameter auf 256 festgelegt ist, ist die Puffergröße immer angemessen.

Hinweis Wenn kein lokaler Hostname konfiguriert wurde, muss gethostname erfolgreich sein und einen Tokenhostnamen zurückgeben, den gethostbyname oder WSAAsyncGetHostByName auflösen kann.

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps auf Windows Phone 8 und höher unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock2.h (einschließlich Winsock2.h)
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll