huschi.net

WCRTOMB(3P)                POSIX Programmer's Manual               WCRTOMB(3P)
PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       wcrtomb -- convert a wide-character code to a character (restartable)
SYNOPSIS
       #include <wchar.h>
       size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);
DESCRIPTION
       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.
       If  s  is a null pointer, the wcrtomb() function shall be equivalent to
       the call:
           wcrtomb(buf, L'\0', ps)
       where buf is an internal buffer.
       If s is not a null pointer, the wcrtomb() function shall determine  the
       number  of  bytes needed to represent the character that corresponds to
       the wide character given by wc (including  any  shift  sequences),  and
       store  the  resulting bytes in the array whose first element is pointed
       to by s.  At most {MB_CUR_MAX} bytes are stored. If wc is a  null  wide
       character,  a null byte shall be stored, preceded by any shift sequence
       needed  to  restore  the  initial  shift  state.  The  resulting  state
       described shall be the initial conversion state.
       If  ps  is  a  null  pointer,  the wcrtomb() 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. The implementation shall
       behave as if no function defined in this volume of  POSIX.1-2008  calls
       wcrtomb().
       The wcrtomb() function need not be thread-safe if called with a NULL ps
       argument.
       The behavior of this function shall be affected by the  LC_CTYPE  cate-
       gory of the current locale.
       The  wcrtomb()  function  shall not change the setting of errno if suc-
       cessful.
RETURN VALUE
       The wcrtomb() function shall return the number of bytes stored  in  the
       array  object  (including  any shift sequences). When wc is not a valid
       wide character, an encoding error shall occur. In this case, the  func-
       tion  shall  store  the  value of the macro [EILSEQ] in errno and shall
       return (size_t)-1; the conversion state shall be undefined.
ERRORS
       The wcrtomb() function shall fail if:
       EILSEQ An invalid wide-character code is detected.
       The wcrtomb() function may fail if:
       EINVAL 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(), wcsrtombs()
       The Base Definitions volume of POSIX.1-2008, <wchar.h>
COPYRIGHT
       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri-
       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .
       Any typographical or formatting errors that appear  in  this  page  are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors,  see  https://www.ker-
       nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group                  2013                          WCRTOMB(3P)