gethostname-Funktion (winsock.h)

  • Artikel

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

Syntax

int 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 kein gültiger Teil des Benutzeradressraums. Dieser Fehler wird auch zurückgegeben, wenn die durch den namelen-Parameter angegebene Puffergröße zu klein ist, um den vollständigen Hostnamen zu enthalten.
WSANOTINITIALISIERT
 Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSAENETDOWN
 Fehler beim Netzwerksubsystem.
WSAEINPROGRESS
 Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet noch 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-endende Zeichenfolge zurückgegeben. Die Form des Hostnamens hängt vom Windows Sockets-Anbieter ab. Dabei kann es 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 Namens, der im Puffer zurückgegeben wird, 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 umgebungsvariable CLUSTER_NETWORK_NAME definiert ist, überschreibt der Wert in dieser Umgebungsvariable den tatsächlichen Hostnamen und wird zurückgegeben. In 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 bestimmen. Wenn kein Namespaceanbieter antwortet, gibt die gethostname-Funktion den NetBIOS-Namen des lokalen Computers zurück.

Die maximale Länge der im Puffer zurückgegebenen Zeichenfolge in Bytes, auf die der Name-Parameter verweist, hängt vom Namespaceanbieter ab, aber diese Zeichenfolge muss maximal 256 Bytes betragen. Wenn also im name-Parameter ein Puffer von 256 Bytes übergeben wird und der namelen-Parameter auf 256 festgelegt ist, ist die Puffergröße immer ausreichend.

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

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps ab Windows Phone 8 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 winsock.h (Winsock2.h einschließen)
Bibliothek Ws2_32.lib
DLL Ws2_32.dll

Weitere Informationen

GetAddrInfoW

WSAAsyncGetHostByName

Winsock-Funktionen

Winsock-Referenz

Gethostbyname