AVR Libc Home Page AVRs AVR Libc Development Pages
Main Page FAQ Library Reference Additional Documentation Example Projects

<avr/pgmspace.h>: Program Space String Utilities


Detailed Description

    #include <avr/io.h>
    #include <avr/pgmspace.h>
このモジュール内の関数はプログラムスペース(フラッシュメモリ)内のデータへのアクセスを提供します。これらの関数を使うためには、ターゲットデバイスはLPM命令又はELPM命令をサポートしている必要があります。
Note:
 これらの関数はIAR Cのヘッダファイルといくらかの互換性をとり、異なるコンパイラへの移植を容易にするよう試みています。100%ではありませんが。(GCCはまだ複数のアドレス空間をフルサポートしていません。)

 完全にRAM上にある文字列の扱いについては 文字列(Strings)で解説している文字列関数をご利用ください。

 可能な限り定数テーブルは下位64KBytes空間に置き、 pgm_read_byte_near() or pgm_read_word_near() を利用してください。 pgm_read_byte_far()pgm_read_word_far() よりも効率的です。上位64KBytes空間は(*_near()関数ではアクセスできませんが、)実行コードに使用することが出来ます。

 全ての "_P"がついた関数は、下位64KBytesを対象にしなければなりません。これらの関数はELPM命令を使っていませんので。通常、プログラムスペース文字列はリンカのセットアップにより割り込みベクタの後、プログラムコードの前に置かれるので、これが問題になることはまずありません。しかし、あまりにたくさんの定数を用意したり、64KBを越えるROMを持つデバイスでブートローダーを使い、この中でプログラムスペース文字列を使う場合には問題になり得ます。このような場合にはこれらの関数は動作しません。


Defines

#define PROGMEM   __ATTR_PROGMEM__
#define PSTR(s)   ((const PROGMEM char *)(s))
#define pgm_read_byte_near(address_short)   __LPM((uint16_t)(address_short))
#define pgm_read_word_near(address_short)   __LPM_word((uint16_t)(address_short))
#define pgm_read_dword_near(address_short)   __LPM_dword((uint16_t)(address_short))
#define pgm_read_byte_far(address_long)   __ELPM((uint32_t)(address_long))
#define pgm_read_word_far(address_long)   __ELPM_word((uint32_t)(address_long))
#define pgm_read_dword_far(address_long)   __ELPM_dword((uint32_t)(address_long))
#define pgm_read_byte(address_short)   pgm_read_byte_near(address_short)
#define pgm_read_word(address_short)   pgm_read_word_near(address_short)
#define pgm_read_dword(address_short)   pgm_read_dword_near(address_short)
#define PGM_P   const prog_char *
#define PGM_VOID_P   const prog_void *

Typedefs

typedef void PROGMEM prog_void
typedef char PROGMEM prog_char
typedef unsigned char PROGMEM prog_uchar
typedef int8_t PROGMEM prog_int8_t
typedef uint8_t PROGMEM prog_uint8_t
typedef int16_t PROGMEM prog_int16_t
typedef uint16_t PROGMEM prog_uint16_t
typedef int32_t PROGMEM prog_int32_t
typedef uint32_t PROGMEM prog_uint32_t
typedef int64_t PROGMEM prog_int64_t
typedef uint64_t PROGMEM prog_uint64_t

Functions

void * memcpy_P (void *, PGM_VOID_P, size_t)
int strcasecmp_P (const char *, PGM_P) __ATTR_PURE__
char * strcat_P (char *, PGM_P)
int strcmp_P (const char *, PGM_P) __ATTR_PURE__
char * strcpy_P (char *, PGM_P)
size_t strlcat_P (char *, PGM_P, size_t)
size_t strlcpy_P (char *, PGM_P, size_t)
size_t strlen_P (PGM_P) __ATTR_CONST__
int strncasecmp_P (const char *, PGM_P, size_t) __ATTR_PURE__
char * strncat_P (char *, PGM_P, size_t)
int strncmp_P (const char *, PGM_P, size_t) __ATTR_PURE__
char * strncpy_P (char *, PGM_P, size_t)
size_t strnlen_P (PGM_P, size_t) __ATTR_CONST__
char * strstr_P (const char *, PGM_P) __ATTR_PURE__

Define Documentation

※ 以下に共通: address はプログラムスペース内のバイトアドレスです。ワードアドレスではありません。

#define PGM_P   const prog_char *
  プログラムスペース内に定義された文字列へのポインタを宣言する時に用いる型宣言。
#define pgm_read_byte address_short   )     pgm_read_byte_near(address_short)
  プログラムスペース内の1バイトデータを16-bitアドレスで読み込みます。
#define pgm_read_byte_far address_long   )     __ELPM((uint32_t)(address_long))
 

プログラムスペース内の1バイトデータを 32-bitアドレスで 読み込みます。

#define pgm_read_byte_near address_short   )     __LPM((uint16_t)(address_short))
 

プログラムスペース内の1バイトデータを16-bitアドレスで読み込みます。pgm_read_byte と同じ

#define pgm_read_dword address_short   )     pgm_read_dword_near(address_short)
 

プログラムスペース内の4バイトデータを16-bitアドレスで読み込みます。

#define pgm_read_dword_far address_long   )     __ELPM_dword((uint32_t)(address_long))
 

プログラムスペース内の4バイトデータを 32-bitアドレスで読み込みます。

#define pgm_read_dword_near address_short   )     __LPM_dword((uint16_t)(address_short))
 

プログラムスペース内の4バイトデータを16-bitアドレスで読み込みます。

#define pgm_read_word address_short   )     pgm_read_word_near(address_short)
 

プログラムスペース内の 2バイトデータを 16-bitアドレスで読み込みます。

#define pgm_read_word_far address_long   )     __ELPM_word((uint32_t)(address_long))
  プログラムスペース内の 2バイトデータを 32-bitアドレスで読み込みます。
#define pgm_read_word_near address_short   )     __LPM_word((uint16_t)(address_short))
 

プログラムスペース内の 2バイトデータを 16-bitアドレスで読み込みます。

#define PGM_VOID_P   const prog_void *
  プログラムスペース内への汎用ポインタを宣言するのに使う型です。
#define PROGMEM   __ATTR_PROGMEM__
  オブジェクト(変数その他)をフラッシュROMに置く属性指定です。
#define PSTR  )     ((const PROGMEM char *)(s))
 

プログラムスペース内の文字列への静的ポインタを宣言するのに使う型です。

使用例:PGM_P("hogehoge")
   → この文字列はSRAMには置かれず、FLASHのみに置かれます。マクロはFLASH上の文字列先頭アドレスを返します。


Typedef Documentation

prog_char
prog_uchar
prog_int8_t
prog_uint8_t
prog_int16_t
prog_uint16_t
prog_int32_t
prog_uint32_t
prog_int64_t
prog_uint64_t

それぞれ先頭の "prog_" を除去した型に対応する、flash ROMに置かれるオブジェクトの型

prog_void
 

flash ROMに置かれる "void" オブジェクトの型。
それ自体は意味を持ちませんが、flash ROM内に (void *) オブジェクトを宣言するのに使われます。


Function Documentation

文字列長

size_t strlen_P PGM_P  src  ) 
  FLASH上にある文字列の長さを返します。
size_t strnlen_P PGM_P  src,
size_t  len
 

strlen_P() と同様だが、先頭からlenバイト以内だけをチェックする。
もしこの範囲に終端0がなければ、 len が返される。


文字比較

int strcasecmp_P const char *  s1,
PGM_P  s2
 

SRAM上文字列 s1と、FLASH上文字列s2を、大小文字を無視して比較します。

Parameters:
s1 SRAM上文字列へのポインタ.
s2 フラッシュ上文字列へのポインタ
Returns:
文字列 s1 が、文字列s2に対して、辞書順で
  より大きい→正の数
  等しい  → 0
  より小さい→負の数
を返します。
int strcmp_P const char *  s1,
PGM_P  s2
 

SRAM上文字列 s1と、FLASH上文字列 s2を、大小文字を考慮して比較します。

Parameters:
s1  SRAM上文字列へのポインタ.
s2  フラッシュ上文字列へのポインタ
Returns:
文字列 s1 が、文字列s2に対して、辞書順で
  より大きい→正の数
  等しい  → 0
  より小さい→負の数
を返します。
int strncasecmp_P const char *  s1,
PGM_P  s2,
size_t  n
 

strcasecmp_Pと同様だが、第三引数 n があること、s1の頭から n 文字だけをサーチ対象にする点が異なる。

int strncmp_P const char *  s1,
PGM_P  s2,
size_t  n
 

strcmp_P と同様だが、第三引数 n があること、s1の頭から n 文字だけをサーチ対象にする点が異なる。

文字・領域コピー

void * memcpy_P void *  dest,
PGM_VOID_P  src,
size_t  n
 

memcpy()と同様、srcからnバイトをdestにコピーします。
ただし、コピー元の src 文字列はflash ROM内に置かれます。

Returns:
結果文字列 dest を返す。
char * strcat_P char *  dest,
PGM_P  src
 

SRAM上文字列 dest の末尾に、FLASH上文字列 src を結合します。
新しい文字列 dest の末尾にはNULがつきます。

Returns:
結果文字列 dest を返します。
char * strcpy_P char *  dest,
PGM_P  src
 

FLASH上文字列 src を、 dest で始まるSRAM上領域へ、終端NULを含めてコピーします。

Returns:
結果文字列 dest を指すポインタを返す。
size_t strlcat_P char *  dst,
PGM_P  ,
size_t  siz
 

SRAM上文字列 dest の末尾に、FLASH上文字列 src を結合します。
新しい文字列 dest の末尾にはNULがつきます。

destの最大サイズは文字列終端の 0 を含めて siz までに制限されます。
strncat_P() と異なり、siz はdst のフルサイズです。空きスペースサイズではありません。
dst には最大 siz-1 文字が収められます。strlen(dst)がsiz-1以下である限りは dst はNULLで終わる文字列となります。

Returns:
strlen(dest)siz の場合、strcat_P()はdestに対しては何もせず、siz + strlen(src) を返します。
strlen(dest)siz の場合、追加コピー処理後strlen(dest) + strlen(src) を返します。
どちらのケースでも、返される値≧siz となる場合は、src文字列の一部が切り捨てられています。
size_t strlcpy_P char *  dst,
PGM_P  ,
size_t  siz
 

FLASH上文字列 src を、 dest で始まるSRAM上領域へ、終端NULを含めてコピーします。
コピーされる文字数は (siz-1) に制限され、結果は必ず '\0' で終わる文字列となります。
(例外:siz==0の場合)

Returns:
strlen(src) が返されます。返される値≧siz なら、src文字列の一部が切り捨てられています
char * strncat_P char *  dest,
PGM_P  src,
size_t  len
 

SRAM上文字列 dest の末尾に、FLASH上文字列 src を、最大 n 文字結合します。
新しい文字列 dest の末尾にはNULがつきます。

Returns:
結果文字列 dest を返す。
char * strncpy_P char *  dest,
PGM_P  src,
size_t  n
  FLASH上文字列 src を、 dest で始まるSRAM上領域へ、最大 n 文字コピーします。
注意点として、strlen(src)≧n の場合、終端のNUL文字が付加されません。
Returns:
結果文字列 dest を返す。
char * strstr_P const char *  s1,
PGM_P  s2
 

SRAM上文字列s1の中で、先頭から探して最初にサブストリングs2 (FLASH上)に一致した場所を返します。文字列末端の '\0' は比較対象に含まれません。

Returns:
文字列 s1 内の、s2に一致する部分の先頭を指すポインタを返します。
一致部分がない場合にはNULLを返します。
s2にヌル文字列( '\0'のみ)を指定すると、関数は s1をそのまま返します。

Automatically generated by Doxygen 1.4.1 on 23 Jan 2006.