AVR Named Address-Spaces
	__flash

	__flashx

	__memx

Functions from stdio.h, but with a format string in address-space __flash
int	vfprintf_F (FILE stream, const __flash char fmt, va_list ap)

int	printf_F (const __flash char *fmt,...)

int	sprintf_F (char s, const __flash char fmt,...)

int	snprintf_F (char s, size_t n, const __flash char fmt,...)

int	vsprintf_F (char s, const __flash char fmt, va_list ap)

int	vsnprintf_F (char s, size_t n, const __flash char fmt, va_list ap)

int	fprintf_F (FILE stream, const __flash char fmt,...)

int	fputs_F (const __flash char str, FILE stream)

int	puts_F (const __flash char *str)

int	vfscanf_F (FILE stream, const __flash char fmt, va_list ap)

int	fscanf_F (FILE stream, const __flash char fmt,...)

int	scanf_F (const __flash char *fmt,...)

int	sscanf_F (const char buf, const __flash char fmt,...)

Functions from string.h, but one argument is in address-space __flash
const __flash void *	memchr_F (const __flash void *, int, size_t)

int	memcmp_F (const void , const __flash void , size_t)

void *	memccpy_F (void , const __flash void , int val, size_t)

void *	memcpy_F (void , const __flash void , size_t)

void *	memmem_F (const void , size_t, const __flash void , size_t)

const __flash void *	memrchr_F (const __flash void *, int val, size_t len)

static size_t	strlen_F (const __flash char *src)

char *	strcat_F (char , const __flash char )

const __flash char *	strchr_F (const __flash char *, int val)

const __flash char *	strchrnul_F (const __flash char *, int val)

int	strcmp_F (const char , const __flash char )

char *	strcpy_F (char , const __flash char )

char *	stpcpy_F (char , const __flash char )

int	strcasecmp_F (const char , const __flash char )

char *	strcasestr_F (const char , const __flash char )

size_t	strcspn_F (const char s, const __flash char reject)

size_t	strlcat_F (char , const __flash char , size_t)

size_t	strlcpy_F (char , const __flash char , size_t)

size_t	strnlen_F (const __flash char *, size_t)

int	strncmp_F (const char , const __flash char , size_t)

int	strncasecmp_F (const char , const __flash char , size_t)

char *	strncat_F (char , const __flash char , size_t)

char *	strncpy_F (char , const __flash char , size_t)

char *	strpbrk_F (const char , const __flash char accept)

const __flash char *	strrchr_F (const __flash char *, int val)

char *	strsep_F (char *sp, const __flash char delim)

size_t	strspn_F (const char s, const __flash char accept)

char *	strstr_F (const char , const __flash char )

char *	strtok_F (char s, const __flash char delim)

char *	strtok_rF (char s, const __flash char delim, char **last)

Functions from string.h, but one argument is in 24-bit address-space __flashx
void *	memcpy_FX (void dest, const __flashx void src, size_t len)

int	memcmp_FX (const void s1, const __flashx void s2, size_t)

size_t	strlen_FX (const __flashx char *src)

size_t	strnlen_FX (const __flashx char *src, size_t len)

char *	strcpy_FX (char dest, const __flashx char src)

char *	stpcpy_FX (char dest, const __flashx char src)

char *	strncpy_FX (char dest, const __flashx char src, size_t len)

char *	strcat_FX (char dest, const __flashx char src)

size_t	strlcat_FX (char dst, const __flashx char src, size_t siz)

char *	strncat_FX (char dest, const __flashx char src, size_t len)

int	strcmp_FX (const char s1, const __flashx char s2)

int	strncmp_FX (const char s1, const __flashx char s2, size_t n)

int	strcasecmp_FX (const char s1, const __flashx char s2)

int	strncasecmp_FX (const char s1, const __flashx char s2, size_t n)

const __flashx char *	strchr_FX (const __flashx char *s, int val)

char *	strstr_FX (const char s1, const __flashx char s2)

size_t	strlcpy_FX (char , const __flashx char , size_t)

More efficient reading of 64-bit values from __flash and __flashx
static uint64_t	flash_read_u64 (const __flash uint64_t *addr)

static int64_t	flash_read_i64 (const __flash int64_t *addr)

static double	flash_read_double (const __flash double *addr)

static long double	flash_read_long_double (const __flash long double *addr)

static uint64_t	flashx_read_u64 (const __flashx uint64_t *addr)

static int64_t	flashx_read_i64 (const __flashx int64_t *addr)

static double	flashx_read_double (const __flashx double *addr)

static long double	flashx_read_long_double (const __flashx long double *addr)

Macros
#define	FSTR(str) ({ static const __flash char c[] = (str); &c[0]; })

#define	FXSTR(str) ({ static const __flashx char c[] = (str); &c[0]; })

#define	FLIT(str) ((const __flash char[]) { str })

#define	FXLIT(str) ((const __flashx char[]) { str })

Convenience macros for functions from stdio.h, that allocate the format string with FSTR
#define	vfprintf_FSTR(stream, fmt, ap) vfprintf_F(stream, FSTR(fmt), ap)

#define	printf_FSTR(fmt, ...) printf_F(FSTR(fmt), ##__VA_ARGS__)

#define	sprintf_FSTR(s, fmt, ...) sprintf_F(s, FSTR(fmt), ##__VA_ARGS__)

#define	snprintf_FSTR(s, n, fmt, ...) snprintf_F(s, n, FSTR(fmt), ##__VA_ARGS__)

#define	vsprintf_FSTR(s, fmt, ap) vsprintf_F(s, FSTR(fmt), ap)

#define	vsnprintf_FSTR(s, n, fmt, ap) vsnprintf_F(s, n, FSTR(fmt), ap);

#define	fprintf_FSTR(stream, fmt, ...) fprintf_F(stream, FSTR(fmt), ##__VA_ARGS__)

#define	fputs_FSTR(str, stream) fputs_F(FSTR(str), stream);

#define	puts_FSTR(str) puts_F(FSTR(str));

#define	vfscanf_FSTR(stream, fmt, ap) vfscanf_F(stream, FSTR(fmt), ap);

#define	fscanf_FSTR(stream, fmt, ...) fscanf_F(stream, FSTR(fmt), ##__VA_ARGS__)

#define	scanf_FSTR(fmt, ...) scanf_F(FSTR(fmt), ##__VA_ARGS__)

#define	sscanf_FSTR(buf, fmt, ...) sscanf_F(buf, FSTR(fmt), ##__VA_ARGS__)

Detailed Description

Since: AVR-LibC v2.3

#include <avr/flash.h>

flash.h

The functions and macros in this module provide interfaces for a program to use data stored in program space (flash memory) by means of the __flash and __flashx named address-spaces supported by avr-gcc.

Purpose

The prototypes and macros provided by this header allow to write C programs that are address-space correct, i.e. they will compile without diagnostics due to -Waddr-space-convert.

For example, you can call printf_P with a format string located in RAM resulting in non-functional code, and the compiler won't complain. This is different with printf_F which will trigger a diagnostic when -Waddr-space-convert is on, and you feed in a format string that does not carry the __flash named address-space qualifier.

Structure of this Header

This header provides:

Functions from stdio.h, string.h resp. avr/pgmspace.h, but where one input string resides in the 16-bit address-space __flash. For example, the strlen_F function works the same like the "progmem" function strlen_P but uses a prototype that describes the flash string as const __flash char*.
Functions from string.h resp. avr/pgmspace.h, but where one input string resides in 24-bit address-space __flashx. For example, the strlen_FX function works the same like the "far" function strlen_PF but uses a prototype that describes the flash string as const __flashx char*.
Some macros for convenience.

Examples

#include <stdbool.h>
#include <avr/flash.h>
 
// Array of string literals where the array
// and also the literals reside in __flash.
const __flash char* const __flash pets[] =
{
    FLIT("gnu"), FLIT("cat"), FLIT("bat"), FLIT("rat")
};
 
void test_pet (const char *pet, const __flash char *what)
{
    const __flash char *yesno;
    bool is_what = ! strcmp_F (pet, what);
    yesno = is_what ? FSTR("yes") : FSTR("no");
 
    // %S denotes a string in lower 64 KiB flash.
    printf_FSTR ("%s is a %S? %S!\n", pet, what, yesno);
}
 
int main (void)
{
    char pet[] = "cat";
    for (size_t i = 0; i < sizeof (pets) / sizeof (*pets); ++i)
    {
        pet[0] ^= 1;
        test_pet (pet, pets[i]);
    }
  return 0;
}

It will print

bat is a gnu? no!
cat is a cat? yes!
bat is a bat? yes!
cat is a rat? no!

provided stdout has been set up appropriately.

Efficiency

The internal handling of 64-bit values in avr-gcc is such that it splits them into single byte operations for the purpose of moving them around. This can lead to quite some overhead when reading such values from named address-spaces. To that end, avr/flash.h provides some inline functions like flash_read_u64 and flashx_read_double that work similar to the pgm_read_u64 and pgm_read_double_far functions, but are coming with proper address-space qualification.

Limitations

Named address-spaces are supported by avr-gcc as part of GNU-C (e.g. -std=gnu99). They are not available in Standard C, and are not supported in C++.
Address-spaces __flash and __memx are supported since avr-gcc v4.7 (Release 2012), whereas __flashx is available since avr-gcc v15 (Release 2025).
Named address-spaces are not supported for Reduced Tiny (core AVRrc, -mmcu=avrtiny), like ATtiny10, ATtiny102 or ATtiny40.

Macro Definition Documentation

◆ FLIT

#define FLIT ( str ) ((const __flash char[]) { str })

Turn string literal str into a compound literal in address-space __flash. This macro can be used to construct arrays of string pointers: Suppose the following 2-dimensional array of animal names:

// Each string occupies 13 bytes, hence
// animals[] occupies 9 * 13 = 117 bytes.
const __flash char animals[][13] =
{
    "hippopotamus",
    "cat", "pig", "gnu", "bat",
    "dog", "cow", "fox", "rat"
};

A more memory-friendly way to represent the strings is an array of string pointers, like in:

// Occupies 9*2 + 13 + 8*4 = 63 bytes
const char* const animals2[] =
{
    "hippopotamus",
    "cat", "pig", "gnu", "bat",
    "dog", "cow", "fox", "rat"
};

animals2[] occupies only 63 bytes (9 * 2 bytes for the string addresses plus the lengths of the very strings). However, all objects are located in the generic address-space. When all objects should be put in a non-generic address-space like __flash, then the type of the literals has to be forced to be const __flash char[]. This can be accomplished with FLIT:

// Occupies 9*2 + 13 + 8*4 = 63 bytes
const __flash char* const __flash animals3[] =
{
    FLIT("hippopotamus"),
    FLIT("cat"), FLIT("pig"), FLIT("gnu"), FLIT("bat"),
    FLIT("dog"), FLIT("cow"), FLIT("fox"), FLIT("rat")
};

Notice the two __flash's in the declarator: The left one says that the pointed-to strings are in __flash, whereas the right one says that the animals3[] array itself resides in __flash.

Unfortunately, to date (avr-gcc v15), FLIT can only be used at global scope. Though what works in a function is using constexpr as introduced in C23:

void func (int i)
{
    static constexpr __flash char s_hip[] = "hippopotamus";
    static constexpr __flash char s_cat[] = "cat";
    // ...
    static const __flash char* const __flash animals4[] =
    {
        s_hip, s_cat, // ...
    };
    printf_FSTR ("Animal %d = %S\n", i, animals4[i]);
}

◆ fprintf_FSTR

#define fprintf_FSTR	(	stream,
		fmt,
		...
	)	fprintf_F(stream, FSTR(fmt), ##__VA_ARGS__)

A convenience macro that wraps fprintf_F's format string with FSTR.

◆ fputs_FSTR

#define fputs_FSTR	(	str,
		stream
	)	fputs_F(FSTR(str), stream);

A convenience macro that wraps fputs_F's string with FSTR.

◆ fscanf_FSTR

#define fscanf_FSTR	(	stream,
		fmt,
		...
	)	fscanf_F(stream, FSTR(fmt), ##__VA_ARGS__)

A convenience macro that wraps fscanf_F's format string with FSTR.

◆ FSTR

#define FSTR ( str ) ({ static const __flash char c[] = (str); &c[0]; })

Used to get a pointer to a static string in address-space __flash. This macro can only be used in the context of a funcion, like in:

#include <avr/flash.h>
 
void say_hello (int x)
{
    printf_F (FSTR ("Hello number %d\n"), x);
 
    // Same effect, but more convenient.
    printf_FSTR ("Hello number %d\n", x);
}

FSTR works similar to the PSTR macro but returns a pointer to the 16-bit named address-space __flash, whereas PSTR returns a 16-bit address in the generic address-space (but isn't).

◆ FXLIT

#define FXLIT ( str ) ((const __flashx char[]) { str })

Turn string literal str into a compound literal in address-space __flashx. This macro can be used to construct arrays of string pointers.

For example code and usage, see the FLIT macro.

◆ FXSTR

#define FXSTR ( str ) ({ static const __flashx char c[] = (str); &c[0]; })

Used to get a pointer to a static string in the 24-bit address-space __flashx. This macro can only be used in the context of a funcion, like in:

#include <stdbool.h>
#include <avr/flash.h>
 
bool text_contains_dog (const char *text)
{
    return strstr_FX (text, FXSTR ("dog")) != NULL;
}

FXSTR works similar to the PSTR_FAR macro but returns a pointer to the 24-bit named address-space __flashx, whereas PSTR_FAR returns a 32-bit integer that represents an address in the generic address-space (but isn't).

◆ printf_FSTR

#define printf_FSTR	(	fmt,
		...
	)	printf_F(FSTR(fmt), ##__VA_ARGS__)

A convenience macro that wraps printf_F's format string with FSTR.

◆ puts_FSTR

#define puts_FSTR ( str ) puts_F(FSTR(str));

A convenience macro that wraps puts_F's string with FSTR.

◆ scanf_FSTR

#define scanf_FSTR	(	fmt,
		...
	)	scanf_F(FSTR(fmt), ##__VA_ARGS__)

A convenience macro that wraps scanf_F's format string with FSTR.

◆ snprintf_FSTR

#define snprintf_FSTR	(	s,
		n,
		fmt,
		...
	)	snprintf_F(s, n, FSTR(fmt), ##__VA_ARGS__)

A convenience macro that wraps snprintf_F's format string with FSTR.

◆ sprintf_FSTR

#define sprintf_FSTR	(	s,
		fmt,
		...
	)	sprintf_F(s, FSTR(fmt), ##__VA_ARGS__)

A convenience macro that wraps sprintf_F's format string with FSTR.

◆ sscanf_FSTR

#define sscanf_FSTR	(	buf,
		fmt,
		...
	)	sscanf_F(buf, FSTR(fmt), ##__VA_ARGS__)

A convenience macro that wraps sscanf_F's format string with FSTR.

◆ vfprintf_FSTR

#define vfprintf_FSTR	(	stream,
		fmt,
		ap
	)	vfprintf_F(stream, FSTR(fmt), ap)

A convenience macro that wraps vfprintf_F's format string with FSTR.

◆ vfscanf_FSTR

#define vfscanf_FSTR	(	stream,
		fmt,
		ap
	)	vfscanf_F(stream, FSTR(fmt), ap);

A convenience macro that wraps vfscanf_F's format string with FSTR.

◆ vsnprintf_FSTR

#define vsnprintf_FSTR	(	s,
		n,
		fmt,
		ap
	)	vsnprintf_F(s, n, FSTR(fmt), ap);

A convenience macro that wraps vsnprintf_F's format string with FSTR.

◆ vsprintf_FSTR

#define vsprintf_FSTR	(	s,
		fmt,
		ap
	)	vsprintf_F(s, FSTR(fmt), ap)

A convenience macro that wraps vsprintf_F's format string with FSTR.

Function Documentation

◆ flash_read_double()

double flash_read_double ( const __flash double * addr )

inlinestatic

Read a double from 16-bit __flash address addr.

◆ flash_read_i64()

int64_t flash_read_i64 ( const __flash int64_t * addr )

inlinestatic

Read an int64_t from 16-bit __flash address addr.

◆ flash_read_long_double()

long double flash_read_long_double ( const __flash long double * addr )

inlinestatic

Read a long double from 16-bit __flash address addr.

◆ flash_read_u64()

uint64_t flash_read_u64 ( const __flash uint64_t * addr )

inlinestatic

Read an uint64_t from 16-bit __flash address addr.

◆ flashx_read_double()

double flashx_read_double ( const __flashx double * addr )

inlinestatic

Read a double from 24-bit __flashx address addr.

◆ flashx_read_i64()

int64_t flashx_read_i64 ( const __flashx int64_t * addr )

inlinestatic

Read an int64_t from 24-bit __flashx address addr.

◆ flashx_read_long_double()

long double flashx_read_long_double ( const __flashx long double * addr )

inlinestatic

Read a long double from 24-bit __flashx address addr.

◆ flashx_read_u64()

uint64_t flashx_read_u64 ( const __flashx uint64_t * addr )

inlinestatic

Read an uint64_t from 24-bit __flashx address addr.

◆ fprintf_F()

int fprintf_F	(	FILE *	stream,
		const __flash char *	fmt,
			...
	)

Variant of fprintf that uses a fmt string that resides in address-space __flash. See also fprintf_FSTR.

◆ fputs_F()

int fputs_F	(	const __flash char *	str,
		FILE *	stream
	)

Variant of fputs where str resides in address-space __flash. See also fputs_FSTR.

◆ fscanf_F()

int fscanf_F	(	FILE *	stream,
		const __flash char *	fmt,
			...
	)

Variant of fscanf using a fmt string in address-space __flash. See also fscanf_FSTR.

◆ memccpy_F()

void * memccpy_F	(	void *	dest,
		const __flash void *	src,
		int	val,
		size_t	len
	)

This function is similar to memccpy except that src is pointer to a string in address-space __flash.

◆ memchr_F()

const __flash void * memchr_F	(	const __flash void *	s,
		int	val,
		size_t	len
	)

Scan flash memory for a character.

The memchr_F function scans the first len bytes of the flash memory area pointed to by s for the character val. The first byte to match val (interpreted as an unsigned character) stops the operation.

Returns: The memchr_F function returns a pointer to the matching byte or NULL if the character does not occur in the given memory area.

◆ memcmp_F()

int memcmp_F	(	const void *	s1,
		const __flash void *	s2,
		size_t	len
	)

Compare memory areas.

The memcmp_F function compares the first len bytes of the memory areas s1 and flash s2. The comparision is performed using unsigned char operations.

Returns: The memcmp_F function returns an integer less than, equal to, or greater than zero if the first len bytes of s1 is found, respectively, to be less than, to match, or be greater than the first len bytes of s2.

◆ memcmp_FX()

int memcmp_FX	(	const void *	s1,
		const __flashx void *	s2,
		size_t	len
	)

Compare memory areas.

The memcmp_FX function compares the first len bytes of the memory areas s1 and __flashx s2. The comparision is performed using unsigned char operations. It is an equivalent of memcmp_F function, except that it is capable working on all Flash including the extended area above 64 KiB.

Returns: The memcmp_FX function returns an integer less than, equal to, or greater than zero if the first len bytes of s1 is found, respectively, to be less than, to match, or be greater than the first len bytes of s2.

◆ memcpy_F()

void * memcpy_F	(	void *	dest,
		const __flash void *	src,
		size_t	n
	)

The memcpy_F function is similar to memcpy, except the src string resides in address-space __flash.

Returns: The memcpy_F function returns a pointer to dest.

◆ memcpy_FX()

void * memcpy_FX	(	void *	dest,
		const __flashx void *	src,
		size_t	n
	)

Copy a memory block from address-space __flashx to SRAM.

The memcpy_FX function is similar to memcpy, except the data is copied from address-space __flashx and is addressed using an according pointer.

Parameters

dest	A pointer to the destination buffer.
src	A pointer to the origin of data in __flashx.
n	The number of bytes to be copied.

Returns: The memcpy_FX function returns a pointer to dst.

◆ memmem_F()

void * memmem_F	(	const void *	s1,
		size_t	len1,
		const __flash void *	s2,
		size_t	len2
	)

The memmem_F function is similar to memmem except that s2 is pointer to a string in address-space __flash.

◆ memrchr_F()

const __flash void * memrchr_F	(	const __flash void *	src,
		int	val,
		size_t	len
	)

The memrchr_F function is like the memchr_F function, except that it searches backwards from the end of the len bytes pointed to by src instead of forwards from the front. (Glibc, GNU extension.)

Returns: The memrchr_F function returns a pointer to the matching byte or NULL if the character does not occur in the given memory area.

◆ printf_F()

int printf_F	(	const __flash char *	fmt,
			...
	)

Variant of printf that uses a fmt string that resides in address-space __flash. See also printf_FSTR.

◆ puts_F()

int puts_F ( const __flash char * str )

Variant of puts where str resides in address-space __flash. See also puts_FSTR.

◆ scanf_F()

int scanf_F	(	const __flash char *	fmt,
			...
	)

Variant of scanf where fmt resides in address-space __flash. See also scanf_FSTR.

◆ snprintf_F()

int snprintf_F	(	char *	s,
		size_t	n,
		const __flash char *	fmt,
			...
	)

Variant of snprintf that uses a fmt string that resides in address-space __flash. See also snprintf_FSTR.

◆ sprintf_F()

int sprintf_F	(	char *	s,
		const __flash char *	fmt,
			...
	)

Variant of sprintf that uses a fmt string that resides in address-space __flash. See also sprintf_FSTR.

◆ sscanf_F()

int sscanf_F	(	const char *	buf,
		const __flash char *	fmt,
			...
	)

Variant of sscanf using a fmt string in address-space __flash. See also sscanf_FSTR.

◆ stpcpy_F()

char * stpcpy_F	(	char *	dest,
		const __flash char *	src
	)

inline

The stpcpy_F function is similar to stpcpy except that src is a pointer to a string in address-space __flash.

Returns: stpcpy_F returns a pointer to the end of the string dest (that is, the address of the terminating null byte) rather than the beginning.

◆ stpcpy_FX()

char * stpcpy_FX	(	char *	dst,
		const __flashx char *	src
	)

Duplicate a string from address-space __flashx.

The stpcpy_FX function is similar to stpcpy except that src is a string located in address-space __flashx.

Parameters

dst	A pointer to the destination string in SRAM.
src	A pointer to the source string in __flashx.

Returns: The stpcpy_PF() function returns a pointer to the terminating '\0' character of the destination string dst.

◆ strcasecmp_F()

int strcasecmp_F	(	const char *	s1,
		const __flash char *	s2
	)

Compare two strings ignoring case.

The strcasecmp_F function compares the two strings s1 and s2, ignoring the case of the characters.

Parameters

s1	A pointer to a string in SRAM.
s2	A pointer to a string in address-space __flash.

Returns: The strcasecmp_F function returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2. A consequence of the ordering used by strcasecmp_F is that if s1 is an initial substring of s2, then s1 is considered to be "less than" s2.

◆ strcasecmp_FX()

int strcasecmp_FX	(	const char *	s1,
		const __flashx char *	s2
	)

Compare two strings ignoring case.

The strcasecmp_FX function compares the two strings s1 and s2, ignoring the case of the characters.

Parameters

s1	A pointer to the first string in SRAM.
s2	A pointer to the second string in address-space __flashx.

Returns: The strcasecmp_FX function returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

◆ strcasestr_F()

char * strcasestr_F	(	const char *	s1,
		const __flash char *	s2
	)

This function is similar to strcasestr except that s2 is pointer to a string in address-space __flash.

◆ strcat_F()

char * strcat_F	(	char *	dest,
		const __flash char *	src
	)

The strcat_F function is similar to strcat except that the src string must be located in address-space __flash.

Returns: The strcat function returns a pointer to the resulting string dest.

◆ strcat_FX()

char * strcat_FX	(	char *	dst,
		const __flashx char *	src
	)

Concatenates two strings.

The strcat_FX function is similar to strcat except that the src string must be located in address-space __flashx.

Parameters

dst	A pointer to the destination string in SRAM.
src	A pointer to the string located in __flashx to be appended.

Returns: The strcat_FX function returns a pointer to the resulting string dst.

◆ strchr_F()

const __flash char * strchr_F	(	const __flash char *	s,
		int	val
	)

Locate character in a string in address-space __flash.

The strchr_F function locates the first occurrence of val (converted to a char) in the string pointed to by s in address-space __flash. The terminating NULL character is considered to be part of the string.

The strchr_F function is similar to strchr except that s is pointer to a string in address-space __flash.

Returns: The strchr_F function returns a pointer to the matched character or NULL if the character is not found.

◆ strchr_FX()

const __flashx char * strchr_FX	(	const __flashx char *	s,
		int	val
	)

Locate a character in a string located in address-space __flashx.

The strchr_FX function locates the first occurrence of val (converted to a char) in the string pointed to by s in address-space __flashx. The terminating null character is considered to be part of the string.

The strchr_FX function is similar to strchr except that s is a pointer to a string in address-space __flashx that's not required to be located in the lower 64 KiB block like it is the case for strchr_F.

Returns: The strchr_FX function returns a far pointer to the matched character or 0 if the character is not found.

◆ strchrnul_F()

const __flash char * strchrnul_F	(	const __flash char *	s,
		int	c
	)

The strchrnul_F function is like strchr_F except that if c is not found in s, then it returns a pointer to the NULL byte at the end of s, rather than NULL. (Glibc, GNU extension.)

Returns: The strchrnul_F function returns a pointer to the matched character, or a pointer to the NULL byte at the end of s (i.e., s+strlen(s)) if the character is not found.

◆ strcmp_F()

int strcmp_F	(	const char *	s1,
		const __flash char *	s2
	)

inline

The strcmp_F function is similar to strcmp except that s2 is pointer to a string in address-space __flash.

Returns: The strcmp_F function returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2. A consequence of the ordering used by strcmp_F is that if s1 is an initial substring of s2, then s1 is considered to be "less than" s2.

◆ strcmp_FX()

int strcmp_FX	(	const char *	s1,
		const __flashx char *	s2
	)

Compares two strings.

The strcmp_FX function is similar to strcmp except that s2 is a pointer to a string in address-space __flashx.

Parameters

s1	A pointer to the first string in SRAM.
s2	A pointer to the second string in __flashx.

Returns: The strcmp_FX function returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

◆ strcpy_F()

char * strcpy_F	(	char *	dest,
		const __flash char *	src
	)

inline

The strcpy_F function is similar to strcpy except that src is a pointer to a string in address-space __flash.

Returns: The strcpy_F function returns a pointer to the destination string dest.

◆ strcpy_FX()

char * strcpy_FX	(	char *	dst,
		const __flashx char *	src
	)

Duplicate a string from address-space __flashx.

The strcpy_FX function is similar to strcpy except that src is a string located in address-space __flashx.

Parameters

dst	A pointer to the destination string in SRAM.
src	A pointer to the source string in __flashx.

Returns: The strcpy_FX function returns a pointer to the destination string dst.

◆ strcspn_F()

size_t strcspn_F	(	const char *	s,
		const __flash char *	reject
	)

The strcspn_F function calculates the length of the initial segment of s which consists entirely of characters not in reject. This function is similar to strcspn except that reject is a pointer to a string in address-space __flash.

Returns: The strcspn_F function returns the number of characters in the initial segment of s which are not in the string reject. The terminating zero is not considered as a part of string.

◆ strlcat_F()

size_t strlcat_F	(	char *	dst,
		const __flash char *	src,
		size_t	siz
	)

Concatenate two strings.

The strlcat_F function is similar to strlcat, except that the src string must be located in address-space __flash.

Appends src to string dst of size siz (unlike strncat, siz is the full size of dst, not space left). At most siz-1 characters will be copied. Always NULL terminates (unless siz <= strlen(dst)).

Returns: The strlcat_F function returns strlen(src) + MIN(siz, strlen(initial dst)). If retval >= siz, truncation occurred.

◆ strlcat_FX()

size_t strlcat_FX	(	char *	dst,
		const __flashx char *	src,
		size_t	n
	)

Concatenate two strings.

The strlcat_FX function is similar to strlcat, except that the src string must be located in address-space __flashx.

Appends src to string dst of size n (unlike strncat, n is the full size of dst, not space left). At most n-1 characters will be copied. Always NULL terminates (unless n <= strlen(dst)).

Parameters

dst	A pointer to the destination string in SRAM.
src	A pointer to the source string in __flashx.
n	The total number of bytes allocated to the destination string.

Returns: The strlcat_FX function returns strlen(src) + MIN(n, strlen(initial dst)). If retval >= n, truncation occurred.

◆ strlcpy_F()

size_t strlcpy_F	(	char *	dst,
		const __flash char *	src,
		size_t	siz
	)

Copy a string from address-space __flash to RAM.

Copy src to string dst of size siz. At most siz-1 characters will be copied. Always NULL terminates (unless siz == 0). The strlcpy_F function is similar to strlcpy except that the src is pointer to a string in address-space __flash.

Returns: The strlcpy_F function returns strlen(src). If retval >= siz, truncation occurred.

◆ strlcpy_FX()

size_t strlcpy_FX	(	char *	dst,
		const __flashx char *	src,
		size_t	len
	)

Copy a string from address-space __flashx to RAM.

Copy src to string dst of length len. At most len-1 characters will be copied. Always NULL terminates (unless len == 0).

Returns: The strlcpy_FX function returns strlen_FX(src). If retval >= len, truncation occurred.

◆ strlen_F()

size_t strlen_F ( const __flash char * src )

inlinestatic

The strlen_F function is similar to strlen, except that src is a pointer to a string in address-space __flash.

Returns: The strlen_F function returns the number of characters in src.

Note: strlen_F is implemented as an inline function in the avr/flash.h header file, which will check if the length of the string is a constant and known at compile time. If it is not known at compile time, the macro will issue a call to a libc function which will then calculate the length of the string as usual.

◆ strlen_FX()

size_t strlen_FX ( const __flashx char * s )

Obtain the length of a string located in address-space __flashx.

The strlen_FX function is similar to strlen, except that s is a pointer to a string in address-space __flashx.

Returns: The strlen_FX function returns the number of characters in s.

◆ strncasecmp_F()

int strncasecmp_F	(	const char *	s1,
		const __flash char *	s2,
		size_t	n
	)

Compare two strings ignoring case.

The strncasecmp_F function is similar to strcasecmp_F, except it only compares the first n characters of s1.

Parameters

s1	A pointer to a string in SRAM.
s2	A pointer to a string in address-space __flash.
n	The maximum number of bytes to compare.

Returns: The strncasecmp_F function returns an integer less than, equal to, or greater than zero if s1 (or the first n bytes thereof) is found, respectively, to be less than, to match, or be greater than s2. A consequence of the ordering used by strncasecmp_F is that if s1 is an initial substring of s2, then s1 is considered to be "less than" s2.

◆ strncasecmp_FX()

int strncasecmp_FX	(	const char *	s1,
		const __flashx char *	s2,
		size_t	n
	)

Compare two strings ignoring case.

The strncasecmp_FX function is similar to strcasecmp_FX, except it only compares the first n characters of s1, and the string s2 is located in address-space __flashx.

Parameters

s1	A pointer to a string in SRAM.
s2	A pointer to a string in __flashx.
n	The maximum number of bytes to compare.

Returns: The strncasecmp_FX function returns an integer less than, equal to, or greater than zero if s1 (or the first n bytes thereof) is found, respectively, to be less than, to match, or be greater than s2.

◆ strncat_F()

char * strncat_F	(	char *	dest,
		const __flash char *	src,
		size_t	len
	)

Concatenate two strings.

The strncat_F function is similar to strncat, except that the src string must be located in address-space __flash.

Returns: The strncat_F function returns a pointer to the resulting string dest.

◆ strncat_FX()

char * strncat_FX	(	char *	dst,
		const __flashx char *	src,
		size_t	n
	)

Concatenate two strings.

The strncat_FX function is similar to strncat, except that the src string must be located in address-space __flashx.

Parameters

dst	A pointer to the destination string in SRAM.
src	A pointer to the source string in __flashx.
n	The maximum number of bytes to append.

Returns: The strncat_FX function returns a pointer to the resulting string dst.

◆ strncmp_F()

int strncmp_F	(	const char *	s1,
		const __flash char *	s2,
		size_t	n
	)

The strncmp_F function is similar to strcmp_F except it only compares the first (at most) n characters of s1 and s2.

Returns: The strncmp_F function returns an integer less than, equal to, or greater than zero if s1 (or the first n bytes thereof) is found, respectively, to be less than, to match, or be greater than s2.

◆ strncmp_FX()

int strncmp_FX	(	const char *	s1,
		const __flashx char *	s2,
		size_t	n
	)

Compare two strings with limited length.

The strncmp_FX function is similar to strcmp_FX except it only compares the first (at most) n characters of s1 and s2.

Parameters

s1	A pointer to the first string in SRAM.
s2	A pointer to the second string in address-space __flashx.
n	The maximum number of bytes to compare.

Returns: The strncmp_FX function returns an integer less than, equal to, or greater than zero if s1 (or the first n bytes thereof) is found, respectively, to be less than, to match, or be greater than s2.

◆ strncpy_F()

char * strncpy_F	(	char *	dest,
		const __flash char *	src,
		size_t	n
	)

The strncpy_F function is similar to strcpy_F except that not more than n bytes of src are copied. Thus, if there is no null byte among the first n bytes of src, the result will not be null-terminated.

In the case where the length of src is less than that of n, the remainder of dest will be padded with nulls.

Returns: The strncpy_F function returns a pointer to the destination string dest.

◆ strncpy_FX()

char * strncpy_FX	(	char *	dst,
		const __flashx char *	src,
		size_t	n
	)

Duplicate a string from address-space __flashx until a limited length.

The strncpy_FX function is similar to strcpy_FX except that not more than n bytes of src are copied. Thus, if there is no null byte among the first n bytes of src, the result will not be null-terminated.

In the case where the length of src is less than that of n, the remainder of dst will be padded with nulls.

Parameters

dst	A pointer to the destination string in SRAM.
src	A far pointer to the source string in address-space __flashx.
n	The maximum number of bytes to copy.

Returns: The strncpy_FX function returns a pointer to the destination string dst.

◆ strnlen_F()

size_t strnlen_F	(	const __flash char *	src,
		size_t	len
	)

Determine the length of a fixed-size string.

The strnlen_F function is similar to strnlen, except that src is a pointer to a string in address-space __flash.

Returns: The strnlen_F function returns strlen_F(src), if that is less than len, or len if there is no '\0' character among the first len characters pointed to by src.

◆ strnlen_FX()

size_t strnlen_FX	(	const __flashx char *	s,
		size_t	len
	)

Determine the length of a fixed-size string in address-space __flashx.

The strnlen_FX function is similar to strnlen, except that s is a pointer to a string in address-space __flashx.

Parameters

s	The address of a string in __flashx.
len	The maximum number of length to return.

Returns: The strnlen_FX function returns strlen_FX(s), if that is less than len, or len if there is no '\0' character among the first len characters pointed to by s.

◆ strpbrk_F()

char * strpbrk_F	(	const char *	s,
		const __flash char *	accept
	)

The strpbrk_F function locates the first occurrence in the string s of any of the characters in the __flash string accept. This function is similar to strpbrk except that accept is a pointer to a string in address-space __flash.

Returns: The strpbrk_F function returns a pointer to the character in s that matches one of the characters in accept, or NULL if no such character is found. The terminating zero is not considered as a part of string: If one or both args are empty, the result will NULL.

◆ strrchr_F()

const __flash char * strrchr_F	(	const __flash char *	s,
		int	val
	)

Locate character in string.

The strrchr_F function returns a pointer to the last occurrence of the character val in the __flash string s.

Returns: The strrchr_F function returns a pointer to the matched character or NULL if the character is not found.

◆ strsep_F()

char * strsep_F	(	char **	sp,
		const __flash char *	delim
	)

Parse a string into tokens.

The strsep_F function locates, in the string referenced by *sp, the first occurrence of any character in the string delim (or the terminating '\0' character) and replaces it with a '\0'. The location of the next character after the delimiter character (or NULL, if the end of the string was reached) is stored in *sp. An ``empty'' field, i.e. one caused by two adjacent delimiter characters, can be detected by comparing the location referenced by the pointer returned in *sp to '\0'. This function is similar to strsep except that delim is a pointer to a string in address-space __flash.

Returns: The strsep_F function returns a pointer to the original value of *sp. If *sp is initially NULL, strsep_F returns NULL.

◆ strspn_F()

size_t strspn_F	(	const char *	s,
		const __flash char *	accept
	)

The strspn_F function calculates the length of the initial segment of s which consists entirely of characters in accept. This function is similar to strspn except that accept is a pointer to a string in address-space __flash.

Returns: The strspn_F function returns the number of characters in the initial segment of s which consist only of characters from accept. The terminating zero is not considered as a part of string.

◆ strstr_F()

char * strstr_F	(	const char *	s1,
		const __flash char *	s2
	)

Locate a substring.

The strstr_F function finds the first occurrence of the substring s2 in the string s1. The terminating '\0' characters are not compared. The strstr_F function is similar to strstr except that s2 is pointer to a string in address-space __flash.

Returns: The strstr_F function returns a pointer to the beginning of the substring, or NULL if the substring is not found. If s2 points to a string of zero length, the function returns s1.

◆ strstr_FX()

char * strstr_FX	(	const char *	s1,
		const __flashx char *	s2
	)

Locate a substring.

The strstr_FX function finds the first occurrence of the substring s2 in the string s1. The terminating '\0' characters are not compared. The strstr_FX function is similar to strstr except that s2 points to a string located in address-space __flashx.

Returns: The strstr_FX function returns a pointer to the beginning of the substring, or NULL if the substring is not found. If s2 points to a string of zero length, the function returns s1.

◆ strtok_F()

char * strtok_F	(	char *	s,
		const __flash char *	delim
	)

Parses the string into tokens.

strtok_F parses the string s into tokens. The first call to strtok_F should have s as its first argument. Subsequent calls should have the first argument set to NULL. If a token ends with a delimiter, this delimiting character is overwritten with a '\0' and a pointer to the next character is saved for the next call to strtok_F. The delimiter string delim may be different for each call.

The strtok_F function is similar to strtok except that delim is pointer to a string in address-space __flash.

Returns: The strtok_F function returns a pointer to the next token or NULL when no more tokens are found.

Note: strtok_F is NOT reentrant. For a reentrant version of this function see strtok_rF.

◆ strtok_rF()

char * strtok_rF	(	char *	string,
		const __flash char *	delim,
		char **	last
	)

Parses string into tokens.

The strtok_rF function parses string into tokens. The first call to strtok_rF should have string as its first argument. Subsequent calls should have the first argument set to NULL. If a token ends with a delimiter, this delimiting character is overwritten with a '\0' and a pointer to the next character is saved for the next call to strtok_rF. The delimiter string delim may be different for each call. last is a user allocated char* pointer. It must be the same while parsing the same string. strtok_rF is a reentrant version of strtok_F.

The strtok_rF function is similar to strtok_r except that delim is pointer to a string in address-space __flash.

Returns: The strtok_rF function returns a pointer to the next token or NULL when no more tokens are found.

◆ vfprintf_F()

int vfprintf_F	(	FILE *	stream,
		const __flash char *	fmt,
		va_list	ap
	)

Variant of vfprintf that uses a fmt string that resides in address-space __flash. See also vfprintf_FSTR.

◆ vfscanf_F()

int vfscanf_F	(	FILE *	stream,
		const __flash char *	fmt,
		va_list	ap
	)

Variant of vfscanf using a fmt string in address-space __flash. See also vfscanf_FSTR.

◆ vsnprintf_F()

int vsnprintf_F	(	char *	s,
		size_t	n,
		const __flash char *	fmt,
		va_list	ap
	)

Variant of vsnprintf that uses a fmt string that resides in address-space __flash. See also vsnprintf_FSTR.

◆ vsprintf_F()

int vsprintf_F	(	char *	s,
		const __flash char *	fmt,
		va_list	ap
	)

Variant of vsprintf that uses a fmt string that resides in address-space __flash. See also vsprintf_FSTR.

Variable Documentation

◆ __flash

__flash

A named address-space for data in the lower 64 KiB of program memory

Pointers to __flash are 16 bits wide.

Objects in __flash are located in section .progmem.data, which is located prior to the code sections by the default linker description files. Similar to PROGMEM, the assertion is that all objects in that section will fit in the lower 64 KiB flash segment (flash byte addresses 0x0 ... 0xffff).

The compiler defines the built-in macro __FLASH when this address-space is available. It is supported as part of GNU-C (-std=gnu99 etc.), and is not available on Reduced Tiny (core AVRrc).

Since: avr-gcc v4.7 (Release 2012)

See also: avr-gcc: __flash.

◆ __flashx

__flashx

A named address-space for data in program memory

Pointers to __flashx are 24 bits wide.

Objects in __flashx are located in section .progmemx.data, which is located after the code sections by the default linker description files. There is no restriction on the address range occupied by objects in that section, and __flashx supports reading across the 64 KiB segment boundaries.

The compiler defines the built-in macro __FLASHX when this address-space is available. It is supported as part of GNU-C (-std=gnu99 etc.), and is not available on Reduced Tiny (core AVRrc).

Since: avr-gcc v15 (Release 2025)

See also: avr-gcc: __flashx.

◆ __memx

__memx

A named address-space for data in program memory or RAM

Pointers to __memx are 24 bits wide.

Objects in __memx are located in section .progmemx.data, which is located after the code sections by the default linker description files. There is no restriction on the address range occupied by objects in that section, and __memx supports reading across the 64 KiB flash segment boundaries.

__memx pointers can also hold RAM addresses, and reading from __memx reads from RAM or from program memory depending on the most significant bit of the address.

The compiler defines the built-in macro __MEMX when this address-space is available. It is supported as part of GNU-C (-std=gnu99 etc.), and is not available on Reduced Tiny (core AVRrc). To date, AVR-LibC does not have support for functions operating on __memx.

Since: avr-gcc v4.7 (Release 2012)

See also: avr-gcc: __memx.

AVR-LibC Documentation					AVR-LibC Development Pages
Main Page	User Manual	Library Reference	FAQ	Example Projects	File List	Index

AVR-LibC Documen­tation

AVR-LibC Development Pages

Main Page

User Manual

Library Refe­rence

FAQ

Example Projects

File List

Index

AVR Named Address-Spaces

Functions from stdio.h, but with a format string in address-space __flash

Functions from string.h, but one argument is in address-space __flash

Functions from string.h, but one argument is in 24-bit address-space __flashx

More efficient reading of 64-bit values from __flash and __flashx

Macros

Convenience macros for functions from stdio.h, that allocate the format string with FSTR

Detailed Description

Purpose

Structure of this Header

Examples

Efficiency

Limitations

Further Reading

Macro Definition Documentation

◆ FLIT

◆ fprintf_FSTR

◆ fputs_FSTR

◆ fscanf_FSTR

◆ FSTR

◆ FXLIT

◆ FXSTR

◆ printf_FSTR

◆ puts_FSTR

◆ scanf_FSTR

◆ snprintf_FSTR

◆ sprintf_FSTR

◆ sscanf_FSTR

◆ vfprintf_FSTR

◆ vfscanf_FSTR

◆ vsnprintf_FSTR

◆ vsprintf_FSTR

Function Documentation

◆ flash_read_double()

◆ flash_read_i64()

◆ flash_read_long_double()

◆ flash_read_u64()

◆ flashx_read_double()

◆ flashx_read_i64()

◆ flashx_read_long_double()

◆ flashx_read_u64()

◆ fprintf_F()

◆ fputs_F()

◆ fscanf_F()

◆ memccpy_F()

◆ memchr_F()

◆ memcmp_F()

◆ memcmp_FX()

◆ memcpy_F()

◆ memcpy_FX()

◆ memmem_F()

◆ memrchr_F()

◆ printf_F()

◆ puts_F()

◆ scanf_F()

◆ snprintf_F()

◆ sprintf_F()

◆ sscanf_F()

◆ stpcpy_F()

◆ stpcpy_FX()

◆ strcasecmp_F()

◆ strcasecmp_FX()

◆ strcasestr_F()

◆ strcat_F()

◆ strcat_FX()

◆ strchr_F()

◆ strchr_FX()

◆ strchrnul_F()

◆ strcmp_F()

◆ strcmp_FX()

◆ strcpy_F()

AVR-LibC Documentation

Library Reference

More efficient reading of 64-bit values from flash and flashx