The Open Group Base Specifications Issue 8
IEEE Std 1003.1-2024
Copyright © 2001-2024 The IEEE and The Open Group

NAME

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

SYNOPSIS

#include <stdlib.h>

size_t wcstombs(char *restrict
s, const wchar_t *restrict pwcs,
       size_t
n);

DESCRIPTION

[CX] [Option Start] 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-2024 defers to the ISO C standard. [Option End]

The wcstombs() function shall convert the sequence of wide-character codes that are in the array pointed to by pwcs into a sequence of characters that begins in the initial shift state and store these characters into the array pointed to by s, stopping if a character would exceed the limit of n total bytes or if a null byte is stored. Each wide-character code shall be converted as if by a call to wctomb(), except that the shift state of wctomb() shall not be affected.

The behavior of this function shall be affected by the LC_CTYPE category of the current locale.

No more than n bytes shall be modified in the array pointed to by s. If copying takes place between objects that overlap, the behavior is undefined. [CX] [Option Start]  If s is a null pointer, wcstombs() shall return the length required to convert the entire array regardless of the value of n, but no values are stored. [Option End]

RETURN VALUE

If a wide-character code is encountered that does not correspond to a valid character (of one or more bytes each), wcstombs() shall return (size_t)-1. Otherwise, wcstombs() shall return the number of bytes stored in the character array, not including any terminating null byte. The array shall not be null-terminated if the value returned is n.

ERRORS

The wcstombs() function shall fail if:

[EILSEQ]
[CX] [Option Start] A wide-character code does not correspond to a valid character. [Option End]

The following sections are informative.

EXAMPLES

None.

APPLICATION USAGE

None.

RATIONALE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

mblen , mbtowc , mbstowcs , wctomb

XBD <stdlib.h>

CHANGE HISTORY

First released in Issue 4. Derived from the ISO C standard.

Issue 6

The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

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

Issue 7

Austin Group Interpretations 1003.1-2001 #156 and #170 are applied.

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

End of informative text.

 

return to top of page

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