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

<stdlib.h>: 汎用ユーティリティ


Detailed Description

 #include <stdlib.h> 

このファイルはISO standardによって定められたいくつかの基本的なCのマクロや関数を宣言しています。AVR独特な拡張もいくつかあります。


構造体

struct  div_t
struct  ldiv_t

標準でない(ISO C 互換でない)関数類

#define RANDOM_MAX   0x7FFFFFFF
char * itoa (int __val, char *__s, int __radix)
char * ltoa (long int __val, char *__s, int __radix)
char * utoa (unsigned int __val, char *__s, int __radix)
char * ultoa (unsigned long int __val, char *__s, int __radix)
long random (void)
void srandom (unsigned long __seed)
long random_r (unsigned long *ctx)

倍精度実数用の変換関数

これらの関数はデフォルトで組み込まれるライブラリlibc.a,内には置かれていません。 数学的関数ライブラリlibm.a内にあります。アプリケーションをリンクする際は -lm オプションを付加する必要があります。
#define DTOSTR_ALWAYS_SIGN   0x01
#define DTOSTR_PLUS_SIGN   0x02
#define DTOSTR_UPPERCASE   0x04
char * dtostre (double __val, char *__s, unsigned char __prec, unsigned char __flags)
char * dtostrf (double __val, char __width, char __prec, char *__s)

定数定義

#define RAND_MAX   0x7FFF

型定義

typedef int(* __compar_fn_t )(const void *, const void *)

関数定義

__inline__ void abort (void) __ATTR_NORETURN__
int abs (int __i) __ATTR_CONST__
long labs (long __i) __ATTR_CONST__
void * bsearch (const void *__key, const void *__base, size_t __nmemb, size_t __size, int(*__compar)(const void *, const void *))
div_t div (int __num, int __denom) __asm__("__divmodhi4") __ATTR_CONST__
ldiv_t ldiv (long __num, long __denom) __asm__("__divmodsi4") __ATTR_CONST__
void qsort (void *__base, size_t __nmemb, size_t __size, __compar_fn_t __compar)
long strtol (const char *__nptr, char **__endptr, int __base)
unsigned long strtoul (const char *__nptr, char **__endptr, int __base)
__inline__ long atol (const char *__nptr) __ATTR_PURE__
__inline__ int atoi (const char *__nptr) __ATTR_PURE__
void exit (int __status) __ATTR_NORETURN__
void * malloc (size_t __size) __ATTR_MALLOC__
void free (void *__ptr)
void * calloc (size_t __nele, size_t __size) __ATTR_MALLOC__
void * realloc (void *__ptr, size_t __size) __ATTR_MALLOC__
double strtod (const char *__nptr, char **__endptr)
double atof (const char *__nptr)
int rand (void)
void srand (unsigned int __seed)
int rand_r (unsigned long *ctx)

変数

size_t __malloc_margin
char * __malloc_heap_start
char * __malloc_heap_end

詳細解説

#define DTOSTR_ALWAYS_SIGN   0x01
 

dtostre()flags に渡されるビット値

#define DTOSTR_PLUS_SIGN   0x02
 

dtostre()flags に渡されるビット値

#define DTOSTR_UPPERCASE   0x04
 

dtostre()flags に渡されるビット値

#define RAND_MAX   0x7FFF
 

rand() で生成される値の最大値

#define RANDOM_MAX   0x7FFFFFFF
 

random() で生成される値の最大値


型定義の解説

typedef int(* __compar_fn_t)(const void *, const void *)
 

qsort() のための比較関数。便宜のために定義されています。


関数の解説

__inline__ void abort void   ) 
 

The abort()

関数は異常プログラム終了を発生させます。制限のあるAVR環境では、この実行は無限ループによる実行停止をもたらします。

int abs int  __i  ) 
 

abs() 関数は整数 i の絶対値を返します。

Note:
abs() and labs() 関数はgccのビルドイン関数です。
double atof const char *  __nptr  ) 
 

atof() 関数はポインタで示される文字列の先頭部分を整数値に変換します。

これは、以下と同等です。

 strtod(nptr, (char **)NULL); 
int atoi const char *  string  ) 
 

文字列を整数値に変換します。

atoi() 関数はポインタで示される文字列の先頭部分を整数値に変換します。

これは、以下と同等です。

 (int)strtol(nptr, (char **)NULL, 10); 
ただ、atoi() はエラー検出をしない点が異なります。

long int atol const char *  string  ) 
 

文字列を Long 整数値に変換します。

atol() 関数はポインタで示される文字列の先頭部分を整数値に変換します。

これは、以下と同等です。

 strtol(nptr, (char **)NULL, 10); 
ただ、atol() はエラー検出をしない点が異なります。

void* bsearch const void *  __key,
const void *  __base,
size_t  __nmemb,
size_t  __size,
int(*)(const void *, const void *)  __compar
 

bsearch()関数は、ポインタbaseで示される要素を先頭とするnmemb 個の配列を検索する。配列要素のサイズは size で指定する。

配列の内容はあらかじめ比較関数による順序において昇順にソートされていなければなりません。比較ルーチンはキーオブジェクトと他の配列メンバの2つの引数を持ち、キーオブジェクトが一致/小さい/大きい と評価される場合に、0/負の値/正の値を返さねばなりません。

bsearch() 関数は配列内の合致したメンバへのポインタを返します。合致データがない場合はnull pointerを返します。合致するメンバが2つある場合は、どちらが合致するかは不定となります。

void* calloc size_t  __nele,
size_t  __size
 

大きさ sizenele 個のメモリを確保します。malloc() 関数に nele * size を与えても同等ですが、callocは割り当てられたメモリをゼロクリアする点がことなります。

div_t div int  __num,
int  __denom
 

div() 関数はnum/denom を計算し、商と余りを div_t 形式の構造体に返します。div_tは quot(商)とrem(余り)の2つの整数メンバを持ちます。

char* dtostre double  __val,
char *  __s,
unsigned char  __prec,
unsigned char  __flags
 

dtostre() 関数は倍精度実数値 val を、ASCII表現文字列に変換し、sが示す領域に保存します。呼び出し元はあらかじめsが示す領域に充分なメモリを確保する必要があります。

変換は  "[-]d.ddde±dd" (dは数字) の書式で行われます。小数点以上は1桁で、小数点以下は prec 桁表示されます。prec が0なら、小数点はつけられません。flags値のDTOSTRE_UPPERCASEのビットがセットされている場合、指数部を表すために文字"E" (eではない)が置かれます。指数部は常に2桁表示されます。(指数部)値が0なら、表示は"00"です。

flags値のDTOSTRE_ALWAYS_SIGN ビットがセットされている場合、正の数の頭にスペースが挿入されます。

flags値のDTOSTRE_PLUS_SIGN ビットがセットされている場合、正の数の頭にスペースではなく符号 (+)がつけられます。

dtostre() 関数は変換結果を保持する文字列 s の先頭アドレスを返します。

char* dtostrf double  __val,
char  __width,
char  __prec,
char *  __s
 

dtostrf() 関数は倍精度実数値 val を、ASCII表現文字列に変換し、sが示す領域に保存します。呼び出し元はあらかじめsが示す領域に充分なメモリを確保する必要があります。

変換は "[-]d.ddd" の書式で行われます。変換結果文字列の最小幅('.'や符号も含む)は width で指定します。 prec で小数点以下桁数を指定します。

dtostrf() 関数は変換結果を保持する文字列 s の先頭アドレスを返します。

void exit int  __status  ) 
 

exit() 関数はアプリケーションを終了します。戻っていくべきOS環境は存在しないので、引数 status は無視され、コード実行は無限ループによる実行停止となります。

C++ では、実行停止の前にグローバルデストラクタ関数が呼ばれます。

void free void *  __ptr  ) 
 

free() 関数は ptr で示された割り当てられたメモリを解放し、再度割り当て可能にします。ptr がNULLなら、何も起こりません。

char* itoa int  __val,
char *  __s,
int  __radix
 

整数値を (radix)進数の文字列に変換する。

itoa() は整数値 val をASCII表現文字列に変換し、sが示す領域に保存します。呼び出し元はあらかじめsが示す領域に充分なメモリを確保する必要があります。

Note:
バッファ s に要求されるサイズは radix の値次第で変わります。たとえば、radix=2(二進数)だと、bit毎1文字+ターミネート文字で、8 * sizeof (int) + 1 文字を必要とします。radix 値が大きいときは要求バッファサイズは小さくなります。※ 16bit値を2/10/16進数にするなら要求バッファサイズは17/7(負の数表示分)/5文字。
Warning:
バッファが小さすぎた場合は、バッファオーバーフローが引き起こされます。
変換は radix 値(2〜36)を基数(何進数で表現するか)として行なわれます。radix が10より大きい場合は、'9'の次の文字として'a'が使われます。
※以後'b','c',・・・36進数では'z'まで使われる。

radix が10で、値が負の数の場合は、負の数として表示され、マイナス符号が付けられます。

itoa()関数は結果が置かれるポインタ s がそのまま返されます。

long labs long  __i  ) 
 

The labs() 関数は long整数の絶対値を返します。

Note:
abs() ,labs() 関数はgccのビルドイン関数です。.
ldiv_t ldiv long  __num,
long  __denom
 

ldiv() 関数はnum/denom を計算し、商と余りを ldiv_t 形式の構造体に返します。ldiv_t は quot(商)とrem(余り)の2つの整数メンバを持ちます。

char* ltoa long int  __val,
char *  __s,
int  __radix
 

long 整数を文字列に変換します。

関数 ltoa() は、long整数値 val をASCII表現文字列に変換し、sが示す領域に保存します。呼び出し元はあらかじめsが示す領域に充分なメモリを確保する必要があります。

Note:
バッファ s に要求されるサイズは radix の値次第で変わります。たとえば、radix=2(二進数)だと、bit毎1文字+ターミネート文字で、8 * sizeof (long int) + 1 文字を必要とします。radix 値が大きいときは要求バッファサイズは小さくなります。※ 32bit値を2/10/16進数にするなら要求バッファサイズは33/12(負の数表示分)/9文字。
Warning:
バッファが小さすぎた場合は、バッファオーバーフローが引き起こされます。
変換は radix 値(2〜36)を基数(何進数で表現するか)として行なわれます。radix が10より大きい場合は、'9'の次の文字として'a'が使われます。
※以後'b','c',・・・36進数では'z'まで使われる。

radix が10で、値が負の数の場合は、負の数として表示され、マイナス符号が付けられます。

ltoa() 関数は結果が置かれるポインタ s がそのまま返されます。

void* malloc size_t  __size  ) 
 

The malloc() 関数は size バイトのメモリを割り当てます。 malloc() がメモリ確保に失敗した場合は、NULLポインタが返されます。

malloc() は確保したメモリを 0 で初期化しない点にご注意ください。 ※calloc() はゼロフィルを行います。

malloc() の使い方の章も参照ください。

void qsort void *  __base,
size_t  __nmemb,
size_t  __size,
__compar_fn_t  __compar
 

qsort()関数は単純ソート(partition-exchange sort) または クイックソートを行います。

qsort() 関数は、ポインタbaseで示される要素を先頭とするnmemb 個の配列をソートする。配列要素のサイズは size で指定する。配列 base の内容は比較関数による順序において昇順にソートされます。比較ルーチンはキーオブジェクトと他の配列メンバの2つの引数を持ち、キーオブジェクトが一致/小さい/大きい と評価される場合に、0/負の値/正の値を返さねばなりません。

int rand void   ) 
 

rand() 関数は0〜RAND_MAX( <stdlib.h>で定義) の範囲の疑似乱数を返します。

srand() 関数は引数 seed を新しい疑似乱数のseed値として設定します。同じ seed 値で srand() をコールした場合、同じ乱数系列が繰り返し出現します。

seed 値を指定しない場合、関数は自動的にseed値を1で設定します。

標準C言語に従って、これらの関数は int 引数で計算しています。しかし使用しているアルゴリズムは32bit計算のものを用いています。これは精密さに欠けます。フル32bit精度の random() 関数もご検討ください。

int rand_r unsigned long *  ctx  ) 
 

rand() のバリエーション。スタティックなライブラリの変数ではなく、ユーザーが供給する ctx に置かれた変数に値を返す。そのため関数はリエントラント(スレッドセーフ)になります。

long random void   ) 
 

random() 関数は0〜RAMDOM_MAX(<stdlib.h>で定義) の範囲の整数疑似乱数列を返します。

srandom() 関数は引数 seed を、rand() で生成される新しい疑似乱数列の種として設定します。この疑似乱数列は同じseed値を入れて srandom() をコールすると、同じ疑似乱数列を繰り返すことになります。

seed値が提供されなかった場合は、この関数は自動的にseedを1とします。

long random_r unsigned long *  ctx  ) 
 

random() のバリエーション。スタティックなライブラリの変数ではなく、ユーザーが供給する ctx に置かれた変数に値を返す。そのため関数はリエントラント(スレッドセーフ)になります。

void* realloc void *  __ptr,
size_t  __size
 

realloc() 関数はptr に割り当てられた領域の大きさを size に変更するよう試みます。返されるポインタは古いものと同じかも知れないし、全く異なる領域を返すかも知れません。

返された領域のうち、新旧サイズのうち小さい方までの内容はrealloc()適用前のものと全く同一になります。これは新しい領域が割り付けられたときでも成立します(その場合はrealloc()がデータをコピーする)

ptr にNULLを入れて渡すことも出来ます。この場合は realloc()malloc() と同じ動作をします。

新しいメモリが割り当てられなかった場合は、 realloc() はNULLを返し、ptr が指す領域は変更されません。

void srand unsigned int  __seed  ) 
 

疑似乱数列生成の種を設定する。 rand() 参照。

void srandom unsigned long  __seed  ) 
 

疑似乱数列生成の種を設定する。 random() の項参照。

double strtod const char *  __nptr,
char **  __endptr
 

strtod() 関数はnptrが指し示す文字列の最初の部分を倍精度実数表現として変換します。

文字列の期待される書式は、オプションとしての正符号 ( '+' ) 又は負符号 ( '-' ) に、小数点文字をオプションとして含む十進数値が続き、オプションとして指数部が続きます・指数部は 'E' 又は 'e' に十進数値が続きます。

文字列内の先行するホワイトスペース文字はスキップされます。

strtod()関数は成功すれば変換された値を返します。

endptr がNULLでなければ、このポインタの位置には、変換の最後に使った文字の次の文字を指すポインタが納められます。
※例:nptr上の文字列が"12.345E07/__"なら、アドレスendptrには、'/'を指すポインタ値が納められる。

変換に失敗した場合は、値 0 が返され、endptrが指す位置にはnptr値(変換文字列の先頭アドレス)が保存されます。

正しい書式だが値がオーバーフローした場合は、+HUGE_VAL または -HUGE_VAL(値の正負による) が返されます。errnoには値ERANGEが保存されます。アンダーフロー時は、値 0 が返され、errnoには値ERANGEが保存されます。

FIXME: HUGE_VAL をどこかに定義して使わなければなりません。ビットパターンは0x7fffffffなんですけど、これはどんな値になるんでしょう?

long strtol const char *  __nptr,
char **  __endptr,
int  __base
 

strtol() 関数はnptrが指し示す文字列の最初の部分をlong 整数表現として変換します。変換は与えられた基数(2〜36、特殊な値として0もとれる)に従って行われます。

文字列は(0個を含む)任意の数のホワイトスペース( isspace() で判定される文字)で始まり、オプションとしての正符号 ( '+' ) 又は負符号 ( '-' ) が続きます。基数が0の場合、先頭に"0x"を含んでいれば数字列は基数=16として(16進数として)読まれます。また基数が0で先頭文字が'0'なら、8進数として読まれます。それ以外の場合は10進数で読まれます。基数が2〜36の場合はその基数に従った数値表現として読まれます。(※このへん原文のママだと意味取りづらかったので修正)

そこから後の部分は基数指定に従いlong値に変換されます。基数に応じた桁文字以外の文字に出会った場合は変換を停止します。基数が10を越える場合は10の表記には大文字又は小文字の文字'A'が使われます。同様に11に対して'B'・・・・35に対して'Z'が使われます。

endptr がNULLでなければ、このポインタの位置には、変換の最後に使った文字の次の文字を指すポインタが納められます。変換に失敗した場合は、値 0 が返され、endptrが指す位置にはnptr値(変換文字列の先頭アドレス)が保存されます。(*nptr != '\0'で、**endptr == '\0' の場合、文字列全体がチェックされたことを意味します。)

strtol() 関数は変換がアンダーフロー又はオーバーフローしない場合は変換結果を返します。変換が行われなかった場合は0を返します。 アンダーフロー又はオーバーフローが起こった場合はerrnoに値 ERANGE がセットされ、関数は値 LONG_MIN 又はLONG_MAXを返します。

unsigned long strtoul const char *  __nptr,
char **  __endptr,
int  __base
 

strtoul() 関数はnptrが指し示す文字列の最初の部分をunsigned long 整数表現として変換します。変換は与えられた基数(2〜36、特殊な値として0もとれる)に従って行われます。

文字列は(0個を含む)任意の数のホワイトスペース(isspace()で判定される文字)で始まり、オプションとしての正符号 ( '+' ) 又は負符号 ( '-' ) が続きます。基数が0の場合、先頭に"0x"を含んでいれば数字列は基数=16として(16進数として)読まれます。また基数が0で先頭文字が'0'なら、8進数として読まれます。それ以外の場合は10進数で読まれます。基数が2〜36の場合はその基数に従った数値表現として読まれます。(※このへん原文のママだと意味取りづらかったので修正)

そこから後の部分は基数指定に従いlong値に変換されます。基数に応じた桁文字以外の文字に出会った場合は変換を停止します。基数が10を越える場合は10の表記には大文字又は小文字の文字'A'が使われます。同様に11に対して'B'・・・・35に対して'Z'が使われます。

endptr がNULLでなければ、このポインタの位置には、変換の最後に使った文字の次の文字を指すポインタが納められます。変換に失敗した場合は、値 0 が返され、endptrが指す位置にはnptr値(変換文字列の先頭アドレス)が保存されます。(*nptr != '\0'で、**endptr == '\0' の場合、文字列全体がチェックされたことを意味します。)

strtoul() 関数は変換で得られた値を返します。結果が負の数の場合は結果がオーバーフローしない限りその負数(=絶対値)を返します。変換が行われなかった場合は0を返します。 オーバーフローが起こった場合はerrnoに値ERANGE がセットされ、strtoul() 関数は値 ULONG_MAXを返します。

char* ultoa unsigned long int  __val,
char *  __s,
int  __radix
 

unsigned long整数を文字列に変換します。

関数 ultoa() は、 unsigned long 整数値 val を、ASCII表示形式に変換して s が指す領域に保存します。呼び出し元は充分な領域を s に確保する必要があります。

Note:
バッファ s の最低限サイズは基数 radix の値次第で変わります。たとえば基数が2(バイナリ)の場合、最低限バッファサイズはビット毎に1文字+文字列終端文字に1つで、 8*sizeof(unsigned long ) + 1文字(標準状態のavrgccの場合は33)です。基数が大きい場合は要求される最低限バッファサイズは小さくなります。
Warning:
バッファが小さすぎる場合はバッファオーバーフローを引き押す危険があります。
変換は radix を基数として行われます。基数 radix は2(バイナリ)から36(36進数)までとれます。radix が10を越える場合は、数字'9'の次は'a'が使われます。

ultoa() 関数は ポインタ s をそのまま返します。

char* utoa unsigned int  __val,
char *  __s,
int  __radix
 

unsigned int型整数を文字列に変換します。

関数 utoa() はunsigned int 整数値 val を ASCII形式にして s が示す領域に保存します。呼び出し元は充分な領域を s に確保する必要があります。

Note:
バッファ s の最低限サイズは基数 radix の値次第で変わります。たとえば基数が2(バイナリ)の場合、最低限バッファサイズはビット毎に1文字+文字列終端文字に1つで、 8*sizeof(unsigned int) + 1文字(標準状態のavrgccの場合は17)です。基数が大きい場合は要求される最低限バッファサイズは小さくなります。
Warning:
バッファが小さすぎる場合はバッファオーバーフローを引き押す危険があります。
変換は radix を基数として行われます。基数 radix は2(バイナリ)から36(36進数)までとれます。radix が10を越える場合は、数字'9'の次は'a'が使われます。

utoa() 関数は ポインタ s をそのまま返します。


Variable Documentation

char* __malloc_heap_end
 

malloc() tunable.

char* __malloc_heap_start
 

malloc() tunable.

size_t __malloc_margin
 

malloc() tunable.


Automatically generated by Doxygen 1.4.1 on 23 Jan 2006.