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 函数将本地主机的名称返回到 name 参数指定的缓冲区中。 主机名以 null 结尾的字符串的形式返回。 主机名的形式取决于 Windows 套接字提供程序，它可以是简单的主机名，也可以是完全限定的域名。 但是，可以保证 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 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持此函数。

要求

要求 值
最低受支持的客户端 Windows 8.1、Windows Vista [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2003 [桌面应用 | UWP 应用]
目标平台 Windows
标头 winsock.h (包括 Winsock2.h)
Library Ws2_32.lib
DLL Ws2_32.dll

另请参阅

GetAddrInfoW

WSAAsyncGetHostByName

Winsock 函数

Winsock 参考

gethostbyname