huschi.net

WCSRTOMBS(3P)              POSIX Programmer's Manual             WCSRTOMBS(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
       wcsrtombs - convert a  wide-character  string  to  a  character  string
       (restartable)
SYNOPSIS
       #include <wchar.h>
       size_t wcsrtombs(char *restrict dst, const wchar_t **restrict src,
              size_t len, mbstate_t *restrict ps);

DESCRIPTION
       The  wcsrtombs()  function  shall convert a sequence of wide characters
       from the array indirectly pointed to by src into a sequence  of  corre-
       sponding characters, beginning in the conversion state described by the
       object pointed to by ps. If dst is not a null  pointer,  the  converted
       characters  shall then be stored into the array pointed to by dst. Con-
       version continues up to and including a terminating null  wide  charac-
       ter,  which  shall also be stored. Conversion shall stop earlier in the
       following cases:
        * When a code is reached that does not correspond to a valid character
        * When the next character would exceed the limit of len total bytes to
          be  stored  in  the  array  pointed to by dst (and dst is not a null
          pointer)
       Each conversion shall take place as if by a call to the wcrtomb() func-
       tion.
       If  dst  is  not  a  null pointer, the pointer object pointed to by src
       shall be assigned either a null pointer (if conversion stopped  due  to
       reaching  a  terminating  null wide character) or the address just past
       the last wide character converted (if any). If conversion  stopped  due
       to  reaching  a  terminating  null  wide character, the resulting state
       described shall be the initial conversion state.
       If ps is a null pointer, the wcsrtombs() 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 wcsrtombs().
       If the application uses  any  of  the  _POSIX_THREAD_SAFE_FUNCTIONS  or
       _POSIX_THREADS  functions,  the application shall ensure that the wcsr-
       tombs() 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
       If  conversion stops because a code is reached that does not correspond
       to a valid character, an encoding error occurs. In this case, the wcsr-
       tombs()  function  shall store the value of the macro [EILSEQ] in errno
       and return (size_t)-1; the conversion state is undefined. Otherwise, it
       shall  return  the number of bytes in the resulting character sequence,
       not including the terminating null (if any).
ERRORS
       The wcsrtombs() function may fail if:
       EINVAL ps points to an  object  that  contains  an  invalid  conversion
              state.
       EILSEQ A wide-character code does not correspond to a valid character.

       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       None.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       mbsinit(),     wcrtomb(),    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                        WCSRTOMBS(3P)