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

NAME

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

SYNOPSIS

9       #include <wchar.h>
10
11       size_t wcsnrtombs(char *dest, const wchar_t **src, size_t nwc,
12                          size_t len, mbstate_t *ps);
13

DESCRIPTION

15       The wcsnrtombs() function is like the wcsrtombs() function, except that
16       the number of wide characters to be converted,  starting  at  *src,  is
17       limited to nwc.
18
19       If  dest  is  not a NULL pointer, the wcsnrtombs() function converts at
20       most nwc wide characters from  the  wide-character  string  *src  to  a
21       multibyte  string  starting  at  dest. At most len bytes are written to
22       dest. The shift state *ps is updated.  The  conversion  is  effectively
23       performed  by repeatedly calling wcrtomb(dest,*src,ps), as long as this
24       call succeeds, and then incrementing dest by the number of bytes  writ‐
25       ten and *src by one. The conversion can stop for three reasons:
26
27       1. A wide character has been encountered that can not be represented as
28       a multibyte sequence (according to the current locale).  In  this  case
29       *src  is  left  pointing to the invalid wide character, (size_t)(-1) is
30       returned, and errno is set to EILSEQ.
31
32       2. nwc wide characters  have  been  converted  without  encountering  a
33       L'\0',  or  the  length  limit forces a stop. In this case *src is left
34       pointing to the next wide character to be converted, and the number  of
35       bytes written to dest is returned.
36
37       3.  The  wide-character string has been completely converted, including
38       the terminating L'\0' (which has the side effect of bringing  back  *ps
39       to the initial state). In this case *src is set to NULL, and the number
40       of bytes written to dest,  excluding  the  terminating  '\0'  byte,  is
41       returned.
42
43       If  dest is NULL, len is ignored, and the conversion proceeds as above,
44       except that the converted bytes are not written out to memory, and that
45       no destination length limit exists.
46
47       In both of the above cases, if ps is a NULL pointer, a static anonymous
48       state only known to the wcsnrtombs function is used instead.
49
50       The programmer must ensure that there is room for at least len bytes at
51       dest.
52

RETURN VALUE

54       The  wcsnrtombs() function returns the number of bytes that make up the
55       converted part of multibyte sequence,  not  including  the  terminating
56       null byte.  If a wide character was encountered which could not be con‐
57       verted, (size_t)(-1) is returned, and errno set to EILSEQ.
58

CONFORMING TO

60       This function is a GNU extension.
61

SEE ALSO

63       iconv(3), wcsrtombs(3)
64

NOTES

66       The behaviour of wcsnrtombs() depends on the LC_CTYPE category  of  the
67       current locale.
68
69       Passing NULL as ps is not multi-thread safe.
70
71
72
73GNU                               1999-07-25                     WCSNRTOMBS(3)