gethostname function (winsock.h)

Article
08/19/2022

The gethostname function retrieves the standard host name for the local computer.

Syntax

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

Parameters

[out] name

A pointer to a buffer that receives the local host name.

[in] namelen

The length, in bytes, of the buffer pointed to by the name parameter.

Return value

If no error occurs, gethostname returns zero. Otherwise, it returns SOCKET_ERROR and a specific error code can be retrieved by calling WSAGetLastError.

Error code	Meaning
WSAEFAULT	The name parameter is a NULL pointer or is not a valid part of the user address space. This error is also returned if the buffer size specified by namelen parameter is too small to hold the complete host name.
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.

Remarks

The gethostname function returns the name of the local host into the buffer specified by the name parameter. The host name is returned as a null-terminated string. The form of the host name is dependent on the Windows Sockets provider—it can be a simple host name, or it can be a fully qualified domain name. However, it is guaranteed that the name returned will be successfully parsed by gethostbyname and WSAAsyncGetHostByName.

The maximum length of the name returned in the buffer pointed to by the name parameter is dependent on the namespace provider.

If the gethostname function is used on a cluster resource on Windows Server 2008, Windows Server 2003, or Windows 2000 Server and the CLUSTER_NETWORK_NAME environment variable is defined, then the value in this environment variable overrides the actual hostname and is returned. On a cluster resource, the CLUSTER_NETWORK_NAME environment variable contains the name of the cluster.

The gethostname function queries namespace providers to determine the local host name using the SVCID_HOSTNAME GUID defined in the Svgguid.h header file. If no namespace provider responds, then the gethostname function returns the NetBIOS name of the local computer.

The maximum length, in bytes, of the string returned in the buffer pointed to by the name parameter is dependent on the namespace provider, but this string must be 256 bytes or less. So if a buffer of 256 bytes is passed in the name parameter and the namelen parameter is set to 256, the buffer size will always be adequate.

Note If no local host name has been configured, gethostname must succeed and return a token host name that gethostbyname or WSAAsyncGetHostByName can resolve.

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Requirements

Requirement	Value
Minimum supported client	Windows 8.1, Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2003 [desktop apps \| UWP apps]
Target Platform	Windows
Header	winsock.h (include Winsock2.h)
Library	Ws2_32.lib
DLL	Ws2_32.dll