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 <stdio.h>
       size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);

DESCRIPTION
       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 IEEE Std 1003.1-2001
       calls wcrtomb().
       If the application uses  any  of  the  _POSIX_THREAD_SAFE_FUNCTIONS  or
       _POSIX_THREADS  functions,  the  application shall ensure that the wcr-
       tomb() function is called with a non-NULL ps argument.
       The behavior of this function shall be affected by the  LC_CTYPE  cate-
       gory of the current locale.
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 may fail if:
       EINVAL ps  points  to  an  object  that  contains an invalid conversion
              state.
       EILSEQ Invalid wide-character code is detected.

       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       None.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       mbsinit(),  the  Base  Definitions  volume   of   IEEE Std 1003.1-2001,
       <wchar.h>
COPYRIGHT
       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                          WCRTOMB(3P)