ワイド文字列をマルチバイト文字列に変換する

wcstombs_s関数は、ワイド文セットの文字列をマルチバイト文字セットの文字列に変換します。

※mbstowcs_s関数の逆の変換を行う関数です。

マルチバイト文字セット、ワイド文字セットについては、mbstowcs_s関数を参照してください。

#include <stdlib.h>
errno_t wcstombs_s( size_t *pReturnValue，

char *mbs，

size_t sizeInBytes，

const wchar_t *wcs，

size_t count

);

pReturnValueは、変換された文字数です。[出力]

mbsは、マルチバイト文字セットの文字列(変換先)が格納される領域の先頭ポインタを指定します。[出力]

sizeInBytesは、mbsバッファのサイズ(バイト数)です。[入力]

wcsは、ワイド文字セットの文字列(変換元)が格納される領域の先頭ポインタを指定します。[入力]

型wchar_tは、ワイド文字列を扱うための型で、C言語ではunsigned short型と同義です。

countは、mbsに格納する最大バイト数、または _TRUNCATEです。[入力]

_TRUNCATEを指定した場合、本関数は、終端文字1つ分を残して、変換先バッファに収まるだけの文字列まで変換を行います。

戻り値として、

正常終了した場合は0を、失敗した場合はエラーコードを返します。

以下はエラーコードと引数の対応です。

EINVAL	mbsがNULLでsizeInBytes > 0 もしくは、wcsがNULL
ERANGE	mbsの指す領域サイズが小さいため、変換後の文字列が収まらない (countが_TRUNCATE の場合は、mbsの指す領域サイズに収まる範囲で処理されるため、失敗しません)

変換元の文字列の変換に成功すると、終端文字を含む変換した文字列のサイズ(バイト単位)をpReturnValueに設定します(ただし、pReturnValueがNULLでない場合)。

※この動作は、mbsがNULLの場合でも実行されますので、これを使用して必要なバッファサイズを確認できます。

mbsがNULLの場合、countは無視されます。

また、マルチバイト文字に変換できないワイド文字を検出すると、pReturnValueに0を、mbsに空の文字列を設定し、さらに、戻り値にEILSEQを返します。

なお、mbsとwcsの指す領域が重なる場合、本関数の動作は未定義(環境により動作が違う)です。

プログラム　例

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <locale.h>

int main(void)
{
  wchar_t *wcs = 'aあbいcう';
  char wcs[100];
  size_t ret;

  setlocale( LC_CTYPE， 'jpn' );

  mbstowcs_s(&ret， mbs， 100， wcs， _TRUNCATE);

  printf('ワイド文字列n');
  printf(' 文字列 = %wsn'， wcs);
  printf(' バイト数 = %dn'， wcslen(wcs) * sizeof(wchar_t));

  printf('マルチバイト文字列n');
  printf(' 文字列 = %sn'， mbs);
  printf(' バイト数 = %dn'， (int)strlen(mbs));
  printf('n');

  return 0;
}

例の実行結果

> mbstowcs_s.exe
ワイド文字列
 文字列 = aあbいcう
 バイト数 = 12

マルチバイト文字列
 文字列 = aあbいcう
 バイト数 = 9

※Windows環境でのみ動作確認しております。LINUX環境などでは動作が異なる場合がありますので、その場合は環境に合わせてカスタマイズしてください。

なお、本関数と同等の処理を行う関数に、wcstombs()があります。

しかし、wcstombs()はバッファオーバーフローを検知できないことがあるため、本関数の使用が推奨されています。