c/string/multibyte/wcrtomb

Converts a wide character to its narrow multibyte representation.

@1@ If is not a null pointer, the function determines the number of bytes necessary to store the multibyte character representation of  (including any shift sequences, and taking into account the current multibyte conversion state ), and stores the multibyte character representation in the character array whose first element is pointed to by,  updating  as necessary. At most bytes can be written by this function. @@ If is a null pointer, the call is equivalent to  for some internal buffer. @@ If wc is the null wide character, a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter is updated to represent the initial shift state. @@If the environment macro is defined, the values of type  are the same as the short identifiers of the characters in the Unicode required set (typically UTF-32 encoding); otherwise, it is implementation-defined. In any case, the multibyte character encoding used by this function is specified by the currently active C locale. @2@ Same as, except that @@ if is a null pointer, the call is equivalent to  with internal variables  and  (whose size is greater than mb_cur_max) @@ the result is returned in the out-parameter @@ the following errors are detected at runtime and call the currently installed constraint handler function:
 * or is a null pointer.
 * is zero or greater than rsize_max (unless is null)
 * is less than the number of bytes that would be written (unless is null)
 * is a null pointer but is not zero

Return value
@1@ On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by. @@ On failure (if is not a valid wide character), returns, stores eilseq in errno, and leaves  in unspecified state. @2@ Returns zero on success and non-zero on failure, in which case, is set to  (unless  is null or  is zero or greater than rsize_max) and  is set to  (unless  is null)