C言語編 標準ライブラリのリファレンス「M」

「M」で始まる標準ライブラリ関数及び、その他の定義です。

malloc関数

概要 メモリ領域を割り当てる(アロケートする)。
ヘッダ stdlib.h
形式 void* malloc(size_t size);
引数 size アロケートする領域の大きさをバイト単位で指定する。
0 を指定した場合の動作は環境依存。
戻り値 アロケートされた領域の先頭を指すポインタ。 メモリ不足などの要因で失敗した場合には、NULL が返される。
詳細 アロケートされた領域が不要になったら、free関数で解放(システムへ返却)することができる。
システムがメモリ領域を管理するための追加の領域が必要なため、実際に割り当てられる大きさは、size を超える可能性がある。
注意 割り当てられた領域の状態は不定であり、クリアされるかどうかも、以前の状態が残っているかどうかも保証できない。
calloc関数を使えば、確実にゼロクリアされた領域を得られる。
使用例
#include <stdio.h>
#include <stdlib.h>

#define ALLOCATE_SIZE	(10)

int main(void)
{
	int* values;
	int i;
	
	values = malloc( sizeof(int) * ALLOCATE_SIZE );
	if( values == NULL ){
		exit( EXIT_FAILURE );
	}

	for( i = 0; i < ALLOCATE_SIZE; ++i ){
		values[i] = i;
	}

	for( i = 0; i < ALLOCATE_SIZE; ++i ){
		printf( "%d\n", values[i] );
	}

	free( values );

	return 0;
}

実行結果:

0
1
2
3
4
5
6
7
8
9
関連 ゼロクリアされた領域は calloc関数で得ることができる。 また、realloc関数は領域の再割り当てを行う。
解説章 第34章

MB_CUR_MAX

概要 現在のロケール設定において、マルチバイト文字1文字の最大バイト数。
ヘッダ stdlib.h
形式 #define MB_CUR_MAX 2
置換結果 現在の LC_CTYPE によって指定されるロケールにおいての、 マルチバイト文字1文字を表すのに必要な最大バイト数。
詳細
注意 現在のロケールに依存するので、考え得る最大サイズを表してはいないし、定数では無い可能性が高い。 全てのロケールを含めたときの最大サイズは、MB_LEN_MAX で得られる。
使用例
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>

int main(int argc, char* argv[])
{
	setlocale( LC_CTYPE, "jpn" );
	printf( "%d\n", MB_CUR_MAX );

	setlocale( LC_CTYPE, "usa" );
	printf( "%d\n", MB_CUR_MAX );

	return 0;
}

実行結果:

2
1
関連 全てのロケールを合わせた場合の最大サイズは、MB_LEN_MAX が表現する。
解説章 第46章

mblen関数

概要 マルチバイト文字列の長さを調べる。
ヘッダ stdlib.h
形式 int mblen(const char* s, size_t n);
引数 s 対象の文字列。
n 調べるバイト数。
戻り値 引数s が NULL でない場合は、引数n のバイト数までを調べる。 文字列がマルチバイト文字として有効であれば、その長さを返し、有効でなければ -1 を返す。
引数s が NULL であれば、現在のロケールのマルチバイト文字の表現形式がシフト状態に依存する場合は 0以外の値を返し、 依存しない場合は 0 を返す。
詳細 調べる範囲は、引数n で指定したバイト数までである。
引数s に NULL を指定した場合、内部のシフト状態が初期状態に戻される。
注意
使用例
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>

int main(void)
{
	const char str[] = "日本語を使うテスト";
	int char_count;
	int i;

	setlocale( LC_CTYPE, "" );

	i = 0;
	char_count = 0;
	while( str[i] != '\0' ){
		i += mblen( &str[i], MB_CUR_MAX );
		char_count++;
	}

	printf( "length: %d\n", char_count );

	return 0;
}

実行結果 (VisualC++):

length: 9

実行結果 (clang (Xcode)):

length: 27
関連 1文字が1バイトの文字列の長さは strlen関数で調べることができる。
C95 で、再開可能な形でマルチバイト文字列の長さを調べる mbrlen関数が追加されている。
ワイド文字列の長さは、C95 で追加された wcslen関数で調べることができる。
解説章 第46章

mbrlen関数

概要 マルチバイト文字列の長さを調べる。
ヘッダ wchar.h
形式 size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
引数 s 対象の文字列。
n 調べるバイト数。
ps 変換状態を管理する変数へのポインタ。または NULL
戻り値 引数s が NULL でない場合は、引数n のバイト数までを調べる。 文字列がマルチバイト文字として有効であれば、その長さを返す。
引数s の先頭部分がナル文字('\0') だった場合は、0 を返す。
文字列がマルチバイト文字として有効でなければ、 -1 を size_t型にキャストした値を返す。
文字列が有効であるが、引数n のバイト数までを調べた時点では、 マルチバイト文字列が完結しない場合には、-2 を size_t型にキャストした値を返す。
詳細 mblen関数と違い、mbstate_t型によって表現される変換状態を用いることで、 マルチバイト文字を構成する途中の段階で処理を止めてしまっても、続きから再開することが可能になっている。
引数s の文字列を、引数n で指定したバイト数まで調べる。 このとき、引数ps の変換状態と照らし合わせて、正しいマルチバイト文字になっているかどうか判定する。 引数ps が NULL の場合は、関数自身が持っている内部情報を使う。 引数ps が指す変換状態は、戻り値が 0以上の場合にだけ更新される。
引数s が NULL の場合は、引数s として "" が、 引数n として 1 が指定されたかのように動作する。
(size_t)-1 が返される場合には、 errnoEILSEQ が設定される。
注意
使用例
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
#include <wchar.h>

int main(void)
{
	const char str[] = "日本語を使うテスト";
	mbstate_t mbstate = {0};
	int char_count;
	int i;
	size_t len;

	setlocale( LC_CTYPE, "" );

	char_count = 0;
	for( i = 0; str[i] != '\0'; ++i ){
		len = mbrlen( &str[i], 1, &mbstate );

		if( len == (size_t)-1 ){
			/* 有効な文字列ではない */
			perror( "" );
			exit( EXIT_FAILURE );
		}
		if( len != (size_t)-2 ){
			/* マルチバイト文字を構成するバイト列の途中でないなら、
			   1文字としてカウント */
			char_count++;
		}	
	}

	printf( "length: %d\n", char_count );

	return 0;
}

実行結果 (VisualC++):

length: 9

実行結果 (clang (Xcode)):

length: 27
関連 C89 の時点では、再開可能な形ではないが、同じ役割を果たす mblen関数があった。
解説章

mbrtowc関数

MB_LEN_MAX

概要 全てのロケール設定で、マルチバイト文字1文字を表すために必要なバイト数。
ヘッダ stdlib.h
形式 #define MB_LEN_MAX 5
置換結果 どのロケール設定においても、マルチバイト文字1文字を表現するために必要十分なバイト数。
詳細
注意
使用例
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>

int main(int argc, char* argv[])
{
	setlocale( LC_CTYPE, "jpn" );
	printf( "%d\n", MB_LEN_MAX );

	setlocale( LC_CTYPE, "usa" );
	printf( "%d\n", MB_LEN_MAX );

	return 0;
}

実行結果:

5
5
関連 現在のロケールだけを考慮した値が必要ならば、MB_CUR_MAX を使う。
解説章 第47章

mbtowc関数

概要 マルチバイト文字をワイド文字に変換する。
ヘッダ stdlib.h
形式 int mbtowc(wchar_t* ws, const char* s, size_t n);
引数 ws 変換結果を受け取るアドレス。
s 変換対象のマルチバイト文字列。
n 変換するバイト数。
戻り値 引数s が NULL でない場合は、引数n のバイト数までを調べる。 文字列がマルチバイト文字として有効であれば、マルチバイト文字列を構成する文字数を返し、 有効でなければ -1 を返す。
引数s が NULL であれば、現在のロケールのマルチバイト文字の表現形式がシフト状態に依存する場合は 0以外の値を返し、 依存しない場合は 0 を返す。
詳細 調べる範囲は、引数n で指定したバイト数までである。
引数s に NULL を指定した場合、内部のシフト状態が初期状態に戻される。
注意 変換結果の末尾に、終端文字(L'\0') は付加されない。
使用例
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <locale.h>

int main(void)
{
	const char mb[] = "あいうえお";
	wchar_t wc;
	int i = 0;

	setlocale( LC_CTYPE, "" );

	for( ;; ){
		const int result = mbtowc( &wc, &mb[i], MB_CUR_MAX );
		if( result > 0 ){
			wprintf( L"%lc", wc );
			i += result;
		}
		else {
			break;
		}
	}
	wprintf( L"\n" );

	return 0;
}

実行結果:

あいうえお
関連 逆方向の変換であるワイド文字からマルチバイト文字列への変換は、wctomb関数で行える。
C95 で、再開可能な形でマルチバイト文字からワイド文字への変換を行う mbrtowc関数が追加されている。
なお、終端文字のあるマルチバイト文字列からワイド文字列への変換は、mbstowcs関数で行える。
解説章 第47章

mbstate_t

概要 マルチバイト文字列、ワイド文字列間での変換状態を表す型。
ヘッダ wchar.h
形式 typedef int mbstate_t;
詳細 マルチバイト文字列からワイド文字列、またはその反対の変換を行う際に用いる。 例えば、mbrtowc関数wcrtomb関数で使用されている。
形式は環境によって異なるが、配列では無い何らかの型である。
値の内容は、現在のロケールの LC_CTYPEカテゴリに従うが、 値が 0 のときは、常に初期変換状態であることを示し、 任意のマルチバイト文字列・ワイド文字列間の変換を開始するために使用できる。 ただし、値が 0 でなくても、初期変換状態を示している可能性はある。
注意
使用例
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
#include <wchar.h>

int main(void)
{
	const char str[] = "日本語を使うテスト";
	mbstate_t mbstate = {0};
	int char_count;
	int i;
	size_t len;

	setlocale( LC_CTYPE, "" );

	char_count = 0;
	for( i = 0; str[i] != '\0'; ++i ){
		len = mbrlen( &str[i], 1, &mbstate );

		if( len == (size_t)-1 ){
			/* 有効な文字列ではない */
			perror( "" );
			exit( EXIT_FAILURE );
		}
		if( len != (size_t)-2 ){
			/* マルチバイト文字を構成するバイト列の途中でないなら、
			   1文字としてカウント */
			char_count++;
		}	
	}

	printf( "length: %d\n", char_count );

	return 0;
}

実行結果 (VisualC++):

length: 9

実行結果 (clang (Xcode)):

length: 27
関連
解説章

mbstowcs関数

概要 マルチバイト文字列をワイド文字列に変換する。
ヘッダ stdlib.h
形式 size_t mbstowcs(wchar_t* ws, const char* s, size_t n);
引数 ws 変換結果を受け取るアドレス。
s 変換対象のマルチバイト文字列。
n 変換する最大文字数。変換後のワイド文字列の文字数で指定する。
戻り値 変換後のワイド文字列の文字数。終端文字の分はカウントしない。
失敗した場合には、-1 を size_t型にキャストした値が返される。
詳細 引数s の各文字を、mbtowc関数で変換することと同等。 引数s の末尾に達するか、引数ws に書き込まれた文字数が、引数n で指定した値に達したときに正常終了する。
注意
使用例
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <locale.h>

#define SIZE_OF_ARRAY(array) (sizeof(array)/sizeof(array[0]))

int main(void)
{
	const char mbs[] = "あいうえお";
	wchar_t ws[16];
	size_t len;

	setlocale( LC_CTYPE, "" );

	len = mbstowcs( ws, mbs, SIZE_OF_ARRAY(ws) );
	if( len == (size_t)-1 ){
		fputs( "error\n", stderr );
		exit( EXIT_FAILURE );
	}

	wprintf( L"%ls\n", ws );

	return 0;
}

実行結果:

あいうえお
関連 逆方向の変換であるワイド文字列からマルチバイト文字列への変換は、wcstombs関数で行える。
解説章

memchr関数

概要 メモリ上から、特定の文字を探す。
ヘッダ string.h
形式 void* memchr(const void* s, int c, size_t n);
引数 s 対象のメモリアドレス。
c 探す文字。
n 検索するバイト数。
戻り値 発見された場合は、メモリ上の文字c のアドレス。
発見できなかった場合は NULL
詳細 アドレスs のから検索を行い、引数c を unsigned char型にキャストしたものと一致する文字を探す。
注意 検索対象のアドレスs は const であるのにも関わらず、戻り値は非const のポインタである。 そのため、const指定されている領域を対象にした場合、返されたポインタを経由して書き換えを行うことは未定義の動作である。
(C++ では、const指定の扱いが厳しくなっているため、この関数は const版と非const版にオーバーロードされていることがある)。
使用例
#include <stdio.h>
#include <string.h>

int main(void)
{
	const char str[] = "abc\0def";
	char* p;

	p = memchr( str, 'd', sizeof(str) );
	if( p == NULL ){
		puts( "見つからない。" );
	}
	else{
		puts( p );
	}

	return 0;
}

実行結果:

def
関連 文字列からの検索に特化した strchr関数がある。
C95以降では、メモリ上からワイド文字を検索する wmemchr関数がある。
解説章

memcmp関数

概要 2つのアドレスを起点に、それぞれ指定サイズ分のデータを比較する。
ヘッダ string.h
形式 void* memcmp(const void* s1, const void* s2, size_t size);
引数 s1 比較対象の先頭アドレス。
s2 比較対象の先頭アドレス。
size 比較するバイト数。
戻り値 辞書順で s1 の方が小さければ(前に来れば) 0 より小さい値が、
s1 の方が大きければ(後に来れば) 0 より大きい値が、
s1 と s2 が同じであれば 0 が返される。
詳細 2つの起点アドレスを元に、一定のバイト数の範囲を比較する。
この比較は、メモリ上のデータを 1バイト単位で文字とみなして調べることで行われる。 従って、終端文字('\0') で終了しない点を除けば、処理内容は strcmp関数と変わらない。
注意 構造体のメンバ間には、コンパイラによって、パディング(詰め物)が挿入される可能性があるので、 構造体変数同士を比較するような目的で、この関数を使用することは間違いである。 構造体変数同士の比較は、各メンバを個別に ==演算子で調べるのが正しい。
使用例
#include <stdio.h>
#include <string.h>

int main(void)
{
	char s1[] = "abc\0de";
	char s2[] = "ab\0c";
	char s3[] = "abcdef";

	printf( "%d\n", memcmp(s1, s1, sizeof(s1)) );
	printf( "%d\n", memcmp(s1, s2, sizeof(s1)) );
	printf( "%d\n", memcmp(s1, s3, sizeof(s1)) );

	return 0;
}

実行結果:

0
1
-1
関連 適切に終端文字('\0') が存在し、途中に登場することも無い、ごく普通の文字列同士の比較であれば、 strcmp関数を使えば良い。
また、C95以降では、ワイド文字とみなして同様の処理を行う wmemcmp関数が存在する。
解説章

memcpy関数

概要 あるアドレスを起点に、一定のサイズのデータを、別のアドレスへコピーする。
ヘッダ string.h
形式 void* memcpy(void* s1, const void* s2, size_t size);
引数 s1 コピー先の先頭アドレス。
s2 コピー元の先頭アドレス。
size コピーするバイト数。
戻り値 s1 と同じアドレスが返される。
詳細 strcpy関数とは異なり、'\0' の影響を受けない。
注意 コピー先の範囲と、コピー元の範囲が重なり合っている場合の結果は未定義である。 重なり合う場合には、memmove関数を使えば良い。
使用例
#include <stdio.h>
#include <string.h>

int main(void)
{
	char s1[] = "abcdefg";
	char s2[] = "xyz";

	printf( "%s\n", memcpy( s1, s2, sizeof(s2)-1 ) );

	return 0;
}

実行結果:

xyzdefg
関連 コピー先範囲とコピー元範囲が重なり合う場合は、memmove関数を使う。 文字列のコピーならば、strcpy関数strncpy関数が使える。
また、C95以降では、ワイド文字とみなして同様の処理を行う wmemcpy関数が存在する。
解説章

memmove関数

概要 あるアドレスを起点に、一定のサイズのデータを、別のアドレスへコピーする。
ヘッダ string.h
形式 void* memmove(void* s1, const void* s2, size_t size);
引数 s1 コピー先の先頭アドレス。
s2 コピー元の先頭アドレス。
size コピーするバイト数。
戻り値 s1 と同じアドレスが返される。
詳細 strcpy関数とは異なり、'\0' の影響を受けない。
memcpy関数とは異なり、コピー先範囲とコピー元範囲が重複していても動作する。 memmove関数の方が安全だが、通常、memcpy関数の方が高速なはずである。
注意
使用例
#include <stdio.h>
#include <string.h>

int main(void)
{
	char s1[] = "abcdefg";

	printf( "%s\n", memmove( &s1[0], &s1[3], 4 ) );

	return 0;
}

実行結果:

defgefg
関連 コピー先範囲とコピー元範囲が重なり合わない場合は、memcpy関数が使える。 文字列のコピーならば、strcpy関数strncpy関数が使える。
また、C95以降では、ワイド文字とみなして同様の処理を行う wmemmove関数が存在する。
解説章

memset関数

概要 あるアドレスを起点に、一定の範囲の各バイトに、特定の値を設定する。
ヘッダ string.h
形式 void* memset(void* s, int c, size_t size);
引数 s 設定先の先頭アドレス。
c 設定する値(文字)
size 設定するバイト数。
戻り値 s と同じアドレスが返される。
詳細 設定する値を指定する引数c は、int型であるが、実際には 1バイトの値でなければならない。 その値が、指定範囲内のすべての領域に設定される。
注意
使用例
#include <stdio.h>
#include <string.h>

int main(void)
{
	char s1[] = "abcdefg";

	printf( "%s\n", memset( s1, 'x', 5 ) );

	return 0;
}

実行結果:

xxxxxfg
関連 calloc関数は、malloc関数と memset関数の組み合わせであると考えられる。
また、C95以降では、ワイド文字とみなして同様の処理を行う wmemset関数が存在する。
解説章

mktime関数

概要 tm構造体から time_t型の値を作る。
ヘッダ time.h
形式 time_t mktime(struct tm* t);
引数 t ローカル時間が格納された tm構造体を指すポインタ。
戻り値 成功した場合は、time_t型の適切な値が返される。 失敗した場合は、-1 を time_t型にキャストした値が返される。
詳細 引数t が指し示す tm構造体に格納されたローカル時間から、time_t型の値を作る。
tm構造体の tm_wday、tm_yday の各メンバの値は無視される。 これらのメンバには、mktime関数が成功したときに、適切な値が格納される。 また、他のメンバについても、mktime関数が成功した際に、適切な範囲内の値が強制的に設定される (例えば、tm_sec の値が表現範囲を超えていたら、その値を減らして、tm_min の値を増やす等)。
注意
使用例
#include <stdio.h>
#include <time.h>

int main(void)
{
	struct tm* jst;
	time_t t;
	
	t = time( NULL );
	printf( "%ld\n", (long int)t );

	jst = localtime( &t );
	printf( "%ld\n", (long int)mktime( jst ) );

	return 0;
}

実行結果:

1301809706
1301809706
関連
解説章 第51章

参考リンク

S・P・ハービソン3世とG・L・スティール・ジュニアのCリファレンスマニュアル 第5版
 -- C99 まで網羅した最も詳細なリファレンス。
新ANSI C言語辞典
 -- 標準ライブラリについて詳しい。C99 には非対応。

更新履歴

'2017/5/16 mbstowcs関数の説明を追加。

'2017/5/15 mbrlen関数、mbstate_t の説明を追加。

'2017/5/12 mbtowc関数の説明を追加。

'2017/5/10 mblen関数の説明を追加。

'2017/5/1 mktime関数の説明を追加。

'2010/9/19 MB_CUR_MAXマクロ、MB_LEN_MAXマクロの説明を追加。

'2010/5/19 memchr関数の説明を追加。

'2009/12/24 memcmp関数、memcpy関数、memmove関数、memset関数の説明を追加。

'2009/12/17 malloc関数の説明を追加。

'2009/8/20 新規作成。



標準ライブラリのリファレンスのトップページへ

C言語編のトップページへ

Programming Place Plus のトップページへ