5.2. Function Reference

5.2.1. __ATTR_CONST__, __ATTR_PROGMEM__, __ATTR_PURE__

#include <pgmspace.h>

__ATTR_CONST__, __ATTR_PROGMEM__, __ATTR_PURE__
	    

description. These macros are used to notify the compiler that it is to handle a function or variable specially.

If a function is marked with the __ATTR_CONST__ macro, the compiler will assume the function produces no side effects and produces an identical result when rpesented with identical inputs. (i.e. the function takes the parameters and produces a result, but doesn't change any memory locations.) If a function marked with this attribute is in a loop and its parameters don't change, the compiler can call it once and use the return value in the loop.

The __ATTR_PROGMEM__ macro is used in variable definitions. If a variable has this attribute, it is allocated in program memory. Since program memory can't be changed when the processor is running, a variable with this attribute is always defined with an initial value.

The __ATTR_PURE__ macro, when used on a function, tells the compiler not to generate any prologue or epilogue code (the function's ret instruction is even suppressed!)

5.2.2. __elpm_inline

#include <pgmspace.h>
	    

uint8_t __elpm_inline(uint32_t addr);

description. This macro gets converted into in-line assembly instructions to pull a byte from program ROM. The elpm instruction is used, so this macro can only be used with AVR devices that support it. The argument is the 32-bit address of the cell. The maximum address depends upon the device being used.

5.2.3. __lpm_inline

#include <pgmspace.h>
	    

uint8_t __lpm_inline(uint16_t addr);

description. This function gets converted into in-line assembly instructions to pull a byte from program ROM. The argument is the 16-bit address of the cell. The maximum address depends upon the device being used.

Only one byte is returned by this function. When pulling wider values from the program memory, the memcpy_P() and strcpy_P() functions should be used.

see also. memcpy_P(), strcpy_P()

5.2.4. memcpy_P

#include <pgmspace.h>
	    

void* memcpy_P(void* dst, PGM_VOID_P src, size_t n);

description. This is a special version of the memcpy function that copies data from program memory to RAM.

5.2.5. PRG_RDB

#include <pgmspace.h>
	    

uint8_t PRG_RDB(uint16_t addr);

description. This macro simply invokes the __lpm_inline() function.

5.2.6. PSTR

#include <pgmspace.h>
	    

PSTR(s);

description. This macro takes a literal string as an argument. It places the string into the program address space and returns its address. The string can be accessed using the macros and functions in this section.

5.2.7. strcat_P

#include <pgmspace.h>
	    

char* strcat_P(char* s1, PGM_P s2);

description. This function operates similarly to the strcat() function. Its second argument, however, refers to a string in program memory.

5.2.8. strcmp_P

#include <pgmspace.h>
	    

int strcmp_P(char const* s1, PGM_P s2);

description. This function operates similarly to the strcmp() function. Its second argument, however, refers to a string in program memory. Make sure you don't get the arguments reversed.

5.2.9. strcpy_P

#include <pgmspace.h>
	    

char* strcpy_P(char* s1, PGM_P s2);

description. This function operates similarly to the strcpy() function. Its second argument, however, refers to a string in program memory.

5.2.10. strcasecmp_P

#include <pgmspace.h>
	    

int strcasecmp_P(char const* s1, PGM_P s2);

description. This function operates similarly to the strcasecmp() function. Its second argument, however, refers to a string in program memory.

5.2.11. strlen_P

#include <pgmspace.h>
	    

size_t strlen_P(PGM_P s);

description. This function operates similarly to the strlen() function. Its argument, however, refers to a string in program memory.

5.2.12. strncasecmp_P

#include <pgmspace.h>
	    

int strncasecmp_P(char const* s1, PGM_P s2, size_t n);

description. This function operates similarly to the strncasecmp() function. Its second argument, however, refers to a string in program memory.

5.2.13. strncmp_P

#include <pgmspace.h>
	    

int strncmp_P(char const* s1, PGM_P s2, size_t n);

description. This function operates similarly to the strncmp() function. Its second argument, however, refers to a string in program memory. Make sure you don't get the arguments reversed.

5.2.14. strncpy_P

#include <pgmspace.h>
	    

char* strncpy_P(char* s1, PGM_P s2, size_t n);

description. This function operates similarly to the strncpy() function. Its second argument, however, refers to a string in program memory.