gethostname 函式 (winsock.h)

  • 發行項

gethostname 函式會擷取本機計算機的標準主機名。

語法

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

參數

[out] name

接收本機主機名之緩衝區的指標。

[in] namelen

name 參數所指向之緩衝區的長度，以位元組為單位。

傳回值

如果沒有發生錯誤， gethostname 會傳回零。 否則，它會傳回SOCKET_ERROR，而且可以藉由呼叫 WSAGetLastError 來擷取特定的錯誤碼。

錯誤碼 意義
WSAEFAULT
 name 參數是 NULL 指標，或不是使用者位址空間的有效部分。 如果 namelen 參數指定的緩衝區大小太小而無法保存完整主機名，也會傳回此錯誤。
WSANOTINITIALISED
 使用此函式之前，必須先進行成功的 WSAStartup 呼叫。
WSAENETDOWN
 網路子系統失敗。
WSAEINPROGRESS
 封鎖的 Windows Sockets 1.1 呼叫正在進行中，或者服務提供者仍在處理回呼函式。

備註

gethostname 函式會將本機主機的名稱傳回名稱參數所指定的緩衝區。 主機名會以 Null 終止字串的形式傳回。 主機名的格式取決於 Windows Sockets 提供者，它可以是簡單的主機名，也可以是完整功能變數名稱。 不過，保證傳回的名稱將會由 gethostbyname 和 WSAAsyncGetHostByName 成功剖析。

name 參數所指向之緩衝區中傳回的名稱長度上限取決於命名空間提供者。

如果在 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server 上的叢集資源上使用 gethostname 函式，且已定義 CLUSTER_NETWORK_NAME 環境變數，則此環境變數中的值會覆寫實際的主機名並傳回。 在叢集資源上， CLUSTER_NETWORK_NAME 環境變數包含叢集的名稱。

gethostname 函式會查詢命名空間提供者，以使用 Svgguid.h 頭檔中定義的SVCID_HOSTNAME GUID 來判斷本機主機名。 如果沒有命名空間提供者回應， gethostname 函式會傳回本機計算機的 NetBIOS 名稱。

name 參數所指向之緩衝區中傳回之字串的最大長度，以位元組為單位，取決於命名空間提供者，但此字元串必須是 256 個字節或更少。 因此，如果在 name 參數中傳遞 256 個字節的緩衝區， 且 namelen 參數設定為 256，則緩衝區大小一律會足夠。

注意 如果未設定本機主機名， gethostname 必須成功，並傳回 gethostbyname 或 WSAAsyncGetHostByName 可以解析的令牌主機名。
 

Windows Phone 8：Windows Phone 8 和更新版本 Windows Phone 市集應用程式支援此函式。

Windows 8.1和 Windows Server 2012 R2：Windows 市集應用程式支援 Windows 8.1、Windows Server 2012 R2 和更新版本。

規格需求

需求 值
最低支援的用戶端 Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 winsock.h (包含 Winsock2.h)
程式庫 Ws2_32.lib
Dll Ws2_32.dll

另請參閱

GetAddrInfoW

WSAAsyncGetHostByName

Winsock 函式

Winsock 參考

gethostbyname