The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### NAME

> wcsnrtombs, wcsrtombs - convert a wide-character string to a character string (restartable)

#### SYNOPSIS

> ``#include <wchar.h>
> ``

> ``[CX] size_t wcsnrtombs(char *restrict` dst`, const wchar_t **restrict` src`,
> size_t` nwc`, size_t` len`, mbstate_t *restrict` ps`);``
> `
> size_t wcsrtombs(char *restrict` dst`, const wchar_t **restrict` src`,
> size_t` len`, mbstate_t *restrict` ps`);
> `

#### DESCRIPTION

> For wcsrtombs(): [CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2008 defers to the ISO C standard.

> The wcsrtombs() function shall convert a sequence of wide characters from the array indirectly pointed to by src into a sequence of corresponding characters, beginning in the conversion state described by the object pointed to by ps. If dst is not a null pointer, the converted characters shall then be stored into the array pointed to by dst. Conversion continues up to and including a terminating null wide character, which shall also be stored. Conversion shall stop earlier in the following cases:

> - When a code is reached that does not correspond to a valid character

> - When the next character would exceed the limit of len total bytes to be stored in the array pointed to by dst (and dst is not a null pointer)

> Each conversion shall take place as if by a call to the wcrtomb() function.

> If dst is not a null pointer, the pointer object pointed to by src shall be assigned either a null pointer (if conversion stopped due to reaching a terminating null wide character) or the address just past the last wide character converted (if any). If conversion stopped due to reaching a terminating null wide character, the resulting state described shall be the initial conversion state.

> If ps is a null pointer, the wcsrtombs() function shall use its own internal mbstate_t object, which is initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object pointed to by ps shall be used to completely describe the current conversion state of the associated character sequence.

> [CX] The wcsnrtombs() and wcsrtombs() functions need not be thread-safe if called with a NULL ps argument.

> The wcsnrtombs() function shall be equivalent to the wcsrtombs() function, except that the conversion is limited to the first nwc wide characters.

> The wcsrtombs() function shall not change the setting of errno if successful.

> The behavior of these functions shall be affected by the LC_CTYPE category of the current locale.

> The implementation shall behave as if no function defined in System Interfaces volume of POSIX.1-2008 calls these functions.

#### RETURN VALUE

> If conversion stops because a code is reached that does not correspond to a valid character, an encoding error occurs. In this case, these functions shall store the value of the macro [EILSEQ] in errno and return (size_t)-1; the conversion state is undefined. Otherwise, these functions shall return the number of bytes in the resulting character sequence, not including the terminating null (if any).

#### ERRORS

> These functions shall fail if:

> [EILSEQ]
>   A wide-character code does not correspond to a valid character.

> These functions may fail if:

> [EINVAL]
>   [CX] ps points to an object that contains an invalid conversion state.

The following sections are informative.

#### EXAMPLES

> None.

#### APPLICATION USAGE

> None.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> mbsinit, wcrtomb

> XBD <wchar.h>

#### CHANGE HISTORY

> First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 (E).

#### Issue 6

> In the DESCRIPTION, a note on using this function in a threaded application is added.

> Extensions beyond the ISO C standard are marked.

> The normative text is updated to avoid use of the term "must" for application requirements.

> The wcsrtombs() prototype is updated for alignment with the ISO/IEC 9899:1999 standard.

#### Issue 7

> Austin Group Interpretation 1003.1-2001 #148 is applied, clarifying that the wcsrtombs() function need not be thread-safe if called with a NULL ps argument.

> Austin Group Interpretation 1003.1-2001 #170 is applied.

> The wcsnrtombs() function is added from The Open Group Technical Standard, 2006, Extended API Set Part 1.

> POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0722 [109,105] is applied.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]