wcstombs(3)

1WCSTOMBS(3)                Linux Programmer's Manual               WCSTOMBS(3)
2
3
4

NAME

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

SYNOPSIS

9       #include <stdlib.h>
10
11       size_t wcstombs(char *dest, const wchar_t *src, size_t n);
12

DESCRIPTION

14       If  dest is not NULL, the wcstombs() function converts the wide-charac‐
15       ter string src to a multibyte string starting at dest.  At most n bytes
16       are  written to dest.  The sequence of characters placed in dest begins
17       in the initial shift state.  The conversion can stop for three reasons:
18
19       1. A wide character has been encountered that can not be represented as
20          a  multibyte  sequence  (according  to the current locale).  In this
21          case, (size_t) -1 is returned.
22
23       2. The length limit forces a stop.  In this case, the number  of  bytes
24          written  to  dest  is returned, but the shift state at this point is
25          lost.
26
27       3. The wide-character string has been completely  converted,  including
28          the terminating null wide character (L'\0').  In this case, the con‐
29          version ends in the initial shift state.  The number of bytes  writ‐
30          ten  to  dest,  excluding  the  terminating  null  byte  ('\0'),  is
31          returned.
32
33       The programmer must ensure that there is room for at least n  bytes  at
34       dest.
35
36       If  dest  is  NULL, n is ignored, and the conversion proceeds as above,
37       except that the converted bytes are not written out to memory,  and  no
38       length limit exists.
39
40       In  order  to avoid the case 2 above, the programmer should make sure n
41       is greater than or equal to wcstombs(NULL,src,0)+1.
42

RETURN VALUE

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

ATTRIBUTES

50       For   an   explanation   of   the  terms  used  in  this  section,  see
51       attributes(7).
52
53       ┌───────────┬───────────────┬─────────┐
54       │Interface  │ Attribute     │ Value   │
55       ├───────────┼───────────────┼─────────┤
56       │wcstombs() │ Thread safety │ MT-Safe │
57       └───────────┴───────────────┴─────────┘
58

CONFORMING TO

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

NOTES

63       The behavior of wcstombs() depends on the LC_CTYPE category of the cur‐
64       rent locale.
65
66       The function wcsrtombs(3) provides a better interface to the same func‐
67       tionality.
68

COLOPHON

73       This page is part of release 4.16 of the Linux  man-pages  project.   A
74       description  of  the project, information about reporting bugs, and the
75       latest    version    of    this    page,    can     be     found     at
76       https://www.kernel.org/doc/man-pages/.
77
78
79
80GNU                               2017-09-15                       WCSTOMBS(3)