mbstowcs_s、_mbstowcs_s_l
更新 : 2007 年 11 月
マルチバイト文字列を対応するワイド文字列に変換します。これらの関数は、「CRT のセキュリティ強化」に説明されているように、mbstowcs、_mbstowcs_l のセキュリティが強化されたバージョンです。
errno_t mbstowcs_s(
size_t *pReturnValue,
wchar_t *wcstr,
size_t sizeInWords,
const char *mbstr,
size_t count
);
errno_t _mbstowcs_s_l(
size_t *pReturnValue,
wchar_t *wcstr,
size_t sizeInWords,
const char *mbstr,
size_t count,
_locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
size_t *pReturnValue,
wchar_t (&wcstr)[size],
const char *mbstr,
size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
size_t *pReturnValue,
wchar_t (&wcstr)[size],
const char *mbstr,
size_t count,
_locale_t locale
); // C++ only
パラメータ
[出力] pReturnValue
変換された文字数。[出力] wcstr
変換されたワイド文字列を格納するバッファのアドレス。[入力] sizeInWords
wcstr バッファのサイズ (ワード単位)。[入力] mbstr
null で終わるマルチバイト文字列のアドレス。[入力] count
wcstr に格納するワイド文字の最大数 (終端の null は含まない)、または _TRUNCATE。[入力] locale
使用するロケール。
戻り値
正常終了した場合は 0 を返します。失敗した場合はエラー コードを返します。
エラー条件 |
戻り値と errno |
---|---|
wcstr が NULL でsizeInWords > 0 |
EINVAL |
mbstr がNULL |
EINVAL |
変換先バッファが小さいため変換後の文字列が収まらない (count が _TRUNCATE の場合は例外。下記の「解説」を参照) |
ERANGE |
上記のいずれかの条件が発生すると、「パラメータの検証」に説明されているように、無効なパラメータの例外が呼び出されます。実行の続行が許可された場合、関数はエラー コードを返し、errno を表で示されている値に設定します。
解説
mbstowcs_s 関数は、mbstr が指すマルチバイト文字列を、ワイド文字列に変換して wcstr が指すバッファに格納します。変換は各文字列に対して行われ、次の条件の 1 つが満たされるまで続行されます。
null マルチバイト文字が検出された
無効なマルチバイト文字が検出された
wcstr バッファに格納されたワイド文字の数が count と等しい。
変換後の文字列は、常に null で終わります (エラーの場合も同様)。
count が特殊な値の _TRUNCATE である場合、mbstowcs_s は、null 終端文字 1 つ分を残して、変換先バッファに収まるだけの文字列まで変換を行います。
mbstowcs_s は、変換元の文字列の変換に成功すると、null 終端文字を含む変換した文字列のサイズ (ワイド文字単位) を *pReturnValue に設定します (pReturnValue が NULL でない場合)。これは、wcstr 引数が NULL の場合でも発生するので、これを使用して必要なバッファ サイズを確認できます。wcstr が NULL の場合、count は無視され、sizeInWords は 0 である必要があります。
mbstowcs_s は、無効なマルチバイト文字を検出すると、0 を *pReturnValue に設定し、変換先バッファに空の文字列を設定し、さらに、errno を EILSEQ に設定して、EILSEQ を返します。
mbstr と wcstr が指す文字列が重なり合う場合、mbstowcs_s 関数の動作は未定義です。
セキュリティに関するメモ : |
---|
wcstr と mbstr が重なり合っていないこと、count が変換対象のマルチバイト文字数を正しく反映していることを確認してください。 |
mbstowcs_s は、すべてのロケールに依存する動作に現在のロケールを使用します。_mbstowcs_s_l は、渡されたロケールを代わりに使用することを除いて同じです。詳細については、「ロケール」を参照してください。
C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファ長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。詳細については、「セキュリティ保護されたテンプレート オーバーロード」を参照してください。
必要条件
ルーチン |
必須ヘッダー |
---|---|
mbstowcs_s |
<stdlib.h> |
_mbstowcs_s_l |
<stdlib.h> |
互換性の詳細については、「C ランタイム ライブラリ」の「互換性」を参照してください。
.NET Framework の相当するアイテム
適用できません。標準 C 関数を呼び出すには、PInvoke を使用します。詳細については、「プラットフォーム呼び出しの例」を参照してください。