[FreeRTOS Embedded IP Stack API]

uint32_t FreeRTOS_gethostbyname( const uint8_t *pcHostName );

Performs a Domain Name System (DNS) lookup on a host name, returning the hosts IP address. For example, assuming a DNS server replies to the lookup request, a call to FreeRTOS_gethostbyname( “” ) will return’s IP address.

ipconfigUSE_DNS must be set to 1 in FreeRTOSIPConfig.h for FreeRTOS_gethostbyname() to be available.

A DNS lookup can only be performed when FreeRTOS+UDP knows the IP address of a DNS server. If ipconfigUSE_DHCP is 0 in FreeRTOSIPConfig.h then the DNS server address is passed into FreeRTOS+UDP as a parameter of the FreeRTOS_IPInit() function. If ipconfigUSE_DHCP is 1 in FreeRTOSIPConfig.h then the DNS server address can be obtained from a DHCP server.

FreeRTOS_gethostbyname() will wait (in the Blocked state so other tasks can execute) for a reply for 200ms after each DNS request – with a maximum of 5 DNS requests being sent.


pcHostName   A standard NULL terminated string containing the name of the host being looked up.



If the lookup is successful then the IP address of the host is returned in network byte order.

If the lookup fails then 0 is returned.

Example usage:


/* FreeRTOS+UDP sockets include */
#include "FreeRTOS_sockets.h"

void aFunction( void )
uint32_t ulIPAddress;
int8_t cBuffer[ 16 ];

    /* Lookup the IP address of the website. */
    ulIPAddress = FreeRTOS_gethostbyname( "" );
    if( ulIPAddress != 0 )
        /* Convert the IP address to a string. */
        FreeRTOS_inet_ntoa( ulIPAddress, ( char * ) cBuffer );
        /* Print out the IP address. */
        printf( " is at IP address %s\r\n", cBuffer );
        printf( "DNS lookup failed. " );

Example use of the FreeRTOS_gethostbyname() API function
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.

Latest News

FreeRTOS v10.2.1 is available for immediate download. MIT licensed, includes 64-bit RISC-V, NXP Cortex-M33 demo & Nuvoton Cortex-M23 demo & STM32H745 dual core (AMP) demo.

New Updates to MIT licensed IoT MQTT and POSIX libraries are now available. New library IoT HTTPS is available.  Includes demo projects.

View a recording of the “OTA Update Security and Reliability” webinar, presented by TI and AWS.


FreeRTOS and other embedded software careers at AWS.

FreeRTOS Partners
ARM Connected RTOS partner for all ARM microcontroller cores
Espressif ESP32
IAR Partner
Microchip Premier RTOS Partner
STMicro RTOS partner supporting ARM7, ARM Cortex-M3, ARM Cortex-M4 and ARM Cortex-M0
Texas Instruments MCU Developer Network RTOS partner for ARM and MSP430 microcontrollers
OpenRTOS and SafeRTOS
Xilinx Microblaze and Zynq partner