Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
wcrtomb(3C)		 Standard C Library Functions		   wcrtomb(3C)

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 is 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 determines the  num-
       ber  of bytes needed to represent the character that corresponds	to the
       wide-character given by wc (including any shift sequences), and	stores
       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-charac-
       ter,  a	null  byte is stored, preceded by any shift sequence needed to
       restore the initial shift state.
	The resulting state described is the initial conversion	state.

       If ps is	a null pointer,	the wcrtomb() function uses its	 own  internal
       mbstate_t  object,  which is initialized	at program startup to the ini-
       tial conversion state.	Otherwise, the	mbstate_t object pointed to by
       ps  is  used to completely describe the current conversion state	of the
       associated character sequence. Solaris will behave as  if  no  function
       defined in the Solaris Reference	Manual calls wcrtomb().

       The  behavior  of this function is affected by the LC_CTYPE category of
       the current locale.  See	environ(5).

RETURN VALUES
       The wcrtomb() function returns the number of bytes stored in the	 array
       object  (including  any shift sequences).  When wc is not a valid wide-
       character, an encoding error occurs.  In	this case, the function	stores
       the  value  of  the  macros EILSEQ in errno and returns (size_t)-1; the
       conversion state	is undefined.

ERRORS
       The wcrtomb() function may fail if:

       EINVAL	       The ps argument points to an object  that  contains  an
		       invalid conversion state.

       EILSEQ	       Invalid wide-character code is detected.

USAGE
       If  ps  is  not	a  null	 pointer,  wcrtomb() uses the mbstate_t	object
       pointed to by ps	and the	function can be	used safely  in	 multithreaded
       applications,  as  long	as setlocale(3C) is not	being called to	change
       the locale. If ps is a null pointer, wcrtomb() uses  its	 internal  mb-
       state_t	object	and  the  function is Unsafe in	multithreaded applica-
       tions.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |See NOTES	below		   |
       +-----------------------------+-----------------------------+

SEE ALSO
       mbsinit(3C), setlocale(3C), attributes(5), standards(5),	environ(5)

SunOS 5.10			  1 Nov	2003			   wcrtomb(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=wcrtomb&sektion=3c&manpath=SunOS+5.10>

home | help