Open Source Software

wcstombs(3)



NAME

   wcstombs - convert a wide-character string to a multibyte string

SYNOPSIS

   #include <stdlib.h>

   size_t wcstombs(char *dest, const wchar_t *src, size_t n);

DESCRIPTION

   If  dest  is  not  NULL,  the  wcstombs()  function  converts the wide-
   character string src to a multibyte string starting at dest.  At most n
   bytes  are  written to dest.  The sequence of characters placed in dest
   begins in the initial shift state.  The conversion can stop  for  three
   reasons:

   1. A wide character has been encountered that can not be represented as
      a multibyte sequence (according to the  current  locale).   In  this
      case, (size_t) -1 is returned.

   2. The  length  limit forces a stop.  In this case, the number of bytes
      written to dest is returned, but the shift state at  this  point  is
      lost.

   3. The  wide-character  string has been completely converted, including
      the terminating null wide character  (L'\0').   In  this  case,  the
      conversion  ends  in  the  initial shift state.  The number of bytes
      written to dest, excluding the  terminating  null  byte  ('\0'),  is
      returned.

   The  programmer  must ensure that there is room for at least n bytes at
   dest.

   If dest is NULL, n is ignored, and the conversion  proceeds  as  above,
   except  that  the converted bytes are not written out to memory, and no
   length limit exists.

   In order to avoid the case 2 above, the programmer should make  sure  n
   is greater than or equal to wcstombs(NULL,src,0)+1.

RETURN VALUE

   The  wcstombs()  function  returns the number of bytes that make up the
   converted part of a multibyte sequence, not including  the  terminating
   null  byte.   If  a  wide  character was encountered which could not be
   converted, (size_t) -1 is returned.

ATTRIBUTES

   For  an  explanation  of  the  terms  used   in   this   section,   see
   attributes(7).

   
   Interface   Attribute      Value   
   
   wcstombs()  Thread safety  MT-Safe

CONFORMING TO

   POSIX.1-2001, POSIX.1-2008, C99.

NOTES

   The  behavior  of  wcstombs()  depends  on the LC_CTYPE category of the
   current locale.

   The function wcsrtombs(3) provides  a  better  interface  to  the  same
   functionality.

SEE ALSO

   mblen(3), mbstowcs(3), mbtowc(3), wcsrtombs(3) wctomb(3)

COLOPHON

   This  page  is  part of release 4.09 of the Linux man-pages project.  A
   description of the project, information about reporting bugs,  and  the
   latest     version     of     this    page,    can    be    found    at
   https://www.kernel.org/doc/man-pages/.



Free and Open Source Software


Free Software Video

Useful Programs

Free Online Courses

Open Opportunity

Open Business