WCTOMB(3P)                                          POSIX Programmer's Manual                                         WCTOMB(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       wctomb - convert a wide-character code to a character

SYNOPSIS
       #include <stdlib.h>

       int wctomb(char *s, wchar_t wchar);


DESCRIPTION
       The  wctomb()  function  shall determine the number of bytes needed to represent the character corresponding to the wide-
       character code whose value is wchar (including any change in the shift state). It shall store the  character  representa-
       tion  (possibly  multiple bytes and any special bytes to change shift state) in the array object pointed to by s (if s is
       not a null pointer). At most {MB_CUR_MAX} bytes shall be stored. If wchar is 0, a null byte shall be stored, preceded  by
       any shift sequence needed to restore the initial shift state, and wctomb() shall be left in the initial shift state.

       The behavior of this function is affected by the LC_CTYPE category of the current locale. For a state-dependent encoding,
       this function shall be placed into its initial state by a call for which its character pointer argument,  s,  is  a  null
       pointer.   Subsequent  calls  with  s  as  other than a null pointer shall cause the internal state of the function to be
       altered as necessary. A call with s as a null pointer shall cause this function to return a non-zero value  if  encodings
       have  state  dependency,  and  0  otherwise. Changing the LC_CTYPE category causes the shift state of this function to be
       unspecified.

       The wctomb() function need not be reentrant. A function that is not required to  be  reentrant  is  not  required  to  be
       thread-safe.

       The implementation shall behave as if no function defined in this volume of IEEE Std 1003.1-2001 calls wctomb().

RETURN VALUE
       If  s  is a null pointer, wctomb() shall return a non-zero or 0 value, if character encodings, respectively, do or do not
       have state-dependent encodings. If s is not a null pointer, wctomb() shall return -1 if the value of wchar does not  cor-
       respond  to  a valid character, or return the number of bytes that constitute the character corresponding to the value of
       wchar.

       In no case shall the value returned be greater than the value of the {MB_CUR_MAX} macro.

ERRORS
       No errors are defined.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       mblen(), mbtowc(), mbstowcs(), wcstombs(), the Base Definitions volume of IEEE Std 1003.1-2001, <stdlib.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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                    WCTOMB(3P)