Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

mbstowcs_s(3C)

Name

mbstowcs - convert a character string to a wide-character string

mbstowcs_s - convert a character string to a wide-character string with additional safety checks

Synopsis

#include <stdlib.h>

size_t mbstowcs(wchar_t *restrict pwcs, const char *restrict s, size_t n);
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>

errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrict dst,
	rsize_t dstmax, const char *restrict src, rsize_t len);

Description

The mbstowcs() function converts a sequence of characters from the array pointed to by s into a sequence of corresponding wide-character codes and stores not more than n wide-character codes into the array pointed to by pwcs. No characters that follow a null byte (which is converted into a wide-character code with value 0) will be examined or converted. Each character is converted as if by a call to mbtowc(3C).

No more than n elements will be modified in the array pointed to by pwcs. If copying takes place between objects that overlap, the behavior is undefined.

The behavior of this function is affected by the LC_CTYPE category of the current locale. If pwcs is a null pointer, mbstowcs() returns the length required to convert the entire array regardless of the value of n, but no values are stored.

The mbstowcs_s() function is part of the bounds checking interfaces specified in the C11 standard, Annex K. It is similar to the mbstowcs() function, but with differing parameters and explicit runtime-constraints as defined in the C11 standard. See runtime_constraint_handler(3C) and INCITS/ISO/IEC 9899:2011.

Return Values

If an invalid character is encountered, mbstowcs() returns (size_t)−1 and may set errno to indicate the error. Otherwise, mbstowcs() returns the number of the array elements modified (or required if pwcs is NULL), not including a terminating 0 code, if any. The array will not be zero-terminated if the value returned is n.

If no runtime-constraint violation and no encoding error occurred, mbstowcs_s() returns zero. Otherwise, mbstowcs_s() returns a nonzero value.

Errors

The mbstowcs() function will fail if:

EILSEQ

Invalid byte sequence is detected.

The mbstowcs_s() function will fail if:

EINVAL

Null pointer is passed.

ERANGE

size argument is not a valid value.

EILSEQ

Invalid byte sequence is detected.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
CSI
Enabled
Interface Stability
Committed
MT-Level
See below
Standard

The mbstowcs() function can be used safely in multithreaded applications.

The mbstowcs_s() function cannot be used safely in a multithreaded application due to the runtime constraint handler. For more information, see the runtime_constraint_handler(3C) man page.

See Also

setlocale(3C), mblen(3C), mbtowc(3C), wcstombs(3C), wctomb(3C), attributes(7), standards(7), wcstombs_s(3C), wctomb_s(3C), runtime_constraint_handler(3C)