funzione gethostname (winsock.h)

Articolo
03/04/2024

La funzione gethostname recupera il nome host standard per il computer locale.

Sintassi

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

Parametri

[out] name

Puntatore a un buffer che riceve il nome host locale.

[in] namelen

Lunghezza, in byte, del buffer a cui punta il parametro name .

Valore restituito

Se non si verifica alcun errore, gethostname restituisce zero. In caso contrario, restituisce SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

Codice di errore	Significato
WSAEFAULT	Il parametro name è un puntatore NULL o non è una parte valida dello spazio degli indirizzi utente. Questo errore viene restituito anche se la dimensione del buffer specificata dal parametro namelen è troppo piccola per contenere il nome host completo.
WSANOTINITIALISED	Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEINPROGRESS	Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback.

Commenti

La funzione gethostname restituisce il nome dell'host locale nel buffer specificato dal parametro name . Il nome host viene restituito come stringa con terminazione Null. Il formato del nome host dipende dal provider Di Windows Sockets, che può essere un nome host semplice oppure può essere un nome di dominio completo. Tuttavia, è garantito che il nome restituito verrà analizzato correttamente da gethostbyname e WSAAsyncGetHostByName.

La lunghezza massima del nome restituito nel buffer a cui fa riferimento il parametro name dipende dal provider dello spazio dei nomi.

Se la funzione gethostname viene usata in una risorsa cluster in Windows Server 2008, Windows Server 2003 o Windows 2000 Server e la variabile di ambiente CLUSTER_NETWORK_NAME viene definita, il valore in questa variabile di ambiente esegue l'override del nome host effettivo e viene restituito. In una risorsa cluster, la variabile di ambiente CLUSTER_NETWORK_NAME contiene il nome del cluster.

La funzione gethostname esegue query sui provider di spazi dei nomi per determinare il nome host locale usando il GUID SVCID_HOSTNAME definito nel file di intestazione Svgguid.h . Se nessun provider di spazi dei nomi risponde, la funzione gethostname restituisce il nome NetBIOS del computer locale.

La lunghezza massima, espressa in byte, della stringa restituita nel buffer a cui punta il parametro name dipende dal provider dello spazio dei nomi, ma questa stringa deve essere di 256 byte o meno. Quindi, se un buffer di 256 byte viene passato nel parametro nome e il parametro namelen è impostato su 256, le dimensioni del buffer saranno sempre adeguate.

Nota Se non è stato configurato alcun nome host locale, gethostname deve avere esito positivo e restituire un nome host token che gethostbyname o WSAAsyncGetHostByName può risolvere.

Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock.h (include Winsock2.h)
Libreria	Ws2_32.lib
DLL	Ws2_32.dll