Protocol-Independent Functions

The following functions are protocol-independent and can be used with any Winsock protocol provider.

gethostname

Retrieves the standard host name for the local computer.

int gethostname(
  _Out_writes_bytes_to_(nameLength, (_String_length_(buffer) + 1)) char *nameBuffer,
  _In_ int nameLength
);

Parameters

• nameBuffer: A pointer to a buffer that receives the null-terminated host name.
• nameLength: The size of the buffer pointed to by nameBuffer, in bytes.

Return Value

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

gethostbyaddr

Retrieves the name of a host from its address.

struct hostent *gethostbyaddr(
  _In_reads_bytes_(len) const char *addr,
  _In_ int                      len,
  _In_ int                      type
);

Parameters

• addr: A pointer to a buffer containing the network address.
• len: The length, in bytes, of the network address.
• type: The address family of the network address (e.g., AF_INET or AF_INET6).

Return Value

If successful, gethostbyaddr returns a pointer to a hostent structure. Otherwise, it returns NULL. The returned structure is allocated by Winsock and may be overwritten by subsequent calls to the same function in the same thread. An application should not free this resource. If a temporary buffer is required, the application should allocate and manage its own buffer.

gethostbyname

Retrieves the address of a host from its name.

struct hostent *gethostbyname(
  _In_ const char *name
);

Parameters

• name: A pointer to a null-terminated character string that specifies the name of the host.

Return Value

If successful, gethostbyname returns a pointer to a hostent structure. Otherwise, it returns NULL. The returned structure is allocated by Winsock and may be overwritten by subsequent calls to the same function in the same thread. An application should not free this resource. If a temporary buffer is required, the application should allocate and manage its own buffer.

getservbyname

Retrieves the port number for a specified service and protocol.

struct servent *getservbyname(
  _In_ const char *name,
  _In_ const char *proto
);

Parameters

• name: A pointer to a null-terminated string specifying the name of the service.
• proto: A pointer to a null-terminated string specifying the protocol (e.g., "tcp" or "udp"). If this parameter is NULL, getservbyname looks for a service that is available for any protocol.

Return Value

If successful, getservbyname returns a pointer to a servent structure. Otherwise, it returns NULL. The returned structure is allocated by Winsock and may be overwritten by subsequent calls to the same function in the same thread.

getservbyport

Retrieves the name of a service associated with a specified port and protocol.

struct servent *getservbyport(
  _In_ int    port,
  _In_ const char *proto
);

Parameters

• port: The port number in network byte order.
• proto: A pointer to a null-terminated string specifying the protocol (e.g., "tcp" or "udp"). If this parameter is NULL, getservbyport looks for a service that is available for any protocol.

Return Value

If successful, getservbyport returns a pointer to a servent structure. Otherwise, it returns NULL. The returned structure is allocated by Winsock and may be overwritten by subsequent calls to the same function in the same thread.