Overview of the Azure Sphere Base APIs

  • Article

The Azure Sphere Application Runtime includes a set of common libraries that define the base APIs that are available for high-level application development: a POSIX-based C standard library, a curl-based HTTP client library, and an Azure IoT C SDK library.

This topic describes how to determine which base APIs are included in Azure Sphere, and where to find reference documentation for the base APIs. For information about device-specific APIs, see Applibs APIs.

Unsupported functions

It is important to use only base API functions that are explicitly included in the API surface of the Azure Sphere Application Runtime. Applications that call unsupported functions may not be compatible with future releases of the Azure Sphere OS and can cause device instability. If you want to request support for additional functions, you can use the Azure Sphere Community forum to make the request.

Verify functions

To determine whether a function call is supported, use auto-complete with IntelliSense in Visual Studio or verify that it is included in the Azure Sphere SDK header files. The locations of the header files for each library are listed in the sections below. If we add or modify functions in these libraries, we will list them in this topic.

musl C standard library

Azure Sphere ships with the musl C standard library (musl libc). Like glibc, musl libc is a POSIX-compliant standard C library. Functional differences between musl libc and glibc are listed in the musl libc wiki.

Consistent with Azure Sphere security policy and architecture, not all POSIX functions are exposed. For example, Azure Sphere does not support the functions open() or fopen(). The entire supported API surface of the library is defined in the Azure Sphere SDK header files. The current implementation may change in a future release.

API reference: POSIX specification

Header file location: Sysroots\API set\usr\include (Windows OS) or Sysroots/API set/usr/include (Linux OS) folders of your Azure Sphere SDK installation directory.

Tip

The Sysroots\API set\usr\include\sys folder contains headers for low-level, system-dependent APIs whereas the Sysroots\API set\usr\include parent folder contains headers for general APIs. This is likewise true for Linux. We recommend that you use the general APIs.

You can download the latest SDK here.

C standard library features

Significant portions of the following C standard library features are excluded:

  • File system paths
  • Terminal support
  • Authentication and authorization
  • Syscall functions
  • System V (SysV)

fcntl

The fcntl(int fd, int cmd, .../* arg */) function CMDs exposed and available for use are the following:

  • F_GETFL - Retrieves the file access mode and the related file status flags.
  • F_SETFL - Sets file status flags, as set by the arg, for a file descriptor.
  • O_NONBLOCK - Argument that is exposed specifically for F_SETFL.

For standard usage of the fcntl() function, see the MUSL library.

C type time_t

In preparation for the UNIX epoch rollover in 2038, musl libc version 1.2 included an update, from 32 bits to 64 bits, of C type time_t and all of its derivatives. For more information about this update, see musl time64 Release Notes.

Applications compiled against the 20.10 target API set (sysroot 7) and later use the 64-bit version of time_t. Applications that were built using earlier versions of the Azure Sphere SDK or target API set 20.04 (sysroot 5) or earlier can continue to use a 32-bit definition of time_t. New versions of the Azure Sphere OS will continue to provide the same Application Binary Interface (ABI) to these applications.

Application code that makes no assumptions about the size of a time_t value are not be affected. However, application code that explicitly or implicitly assumes that time_t values are 32-bit (for example, by casting a time_t value to a uint32_t) must be rewritten to reflect the 64-bit version.

The following snippet assumes that time_t is a 32-bit value and will cause a buffer overrun if recompiled with the 20.10 SDK (sysroot 7) or later:

// Incorrect code that assumes a 32-bit time_t value
time_t t = time(NULL);
char buffer[4];
memcpy(buffer, &t, sizeof(t)); // <-- buffer overrun when time_t is 64 bits

The following corrected code defines the buffer to be the same size as the time_t value, thus removing any assumptions about the size of time_t:

// Corrected version of the code. It does not hard-code the size of time_t

time_t t; // time_t represents the 64-bit struct.
char buffer[sizeof(time_t)]; // Buffer size is based on the actual size of time_t
memcpy(buffer, &t, sizeof(t));

If you need to continue using a 32-bit time value, use the time32_t type in the new version of musl. The following code snippet shows how:

// Corrected version of the code for cases where 32-bit time_t is needed
time32_t t = /* ... initialize 32-bit value ... */;
char buffer[sizeof(time32_t)];
memcpy(buffer, &t, sizeof(t));

curl library

The Azure Sphere SDK includes a subset of the libcurl multi protocol transfer library. You can use this API to transfer data over HTTP/HTTPS. The other transfer protocols are not supported. The entire supported API surface of the library is defined in the Azure Sphere SDK header files.

API reference: libcurl website

Header file location: Sysroots\API set\usr\include\curl (Windows OS) folder or Sysroots/API set/usr/include/curl (Linux OS) folder of the Azure Sphere SDK installation directory.

See also