mbrtowc man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

mbtowc(3)							     mbtowc(3)

NAME
       mbtowc, mbrtowc - Convert a multibyte character to a wide character

SYNOPSIS
       #include <stdlib.h>

       int mbtowc(
	       wchar_t *pwc,
	       const char *s,
	       size_t n ); #include <wchar.h>

       size_t mbrtowc(
	       wchar_t *pwc,
	       const char *s,
	       size_t n,
	       mbstate_t *ps );

LIBRARY
       Standard C Library (libc)

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       mbtowc(): ISO C, XPG4

       mbrtowc(): ISO C

       Refer to the standards(5) reference page	 for  more  information	 about
       industry standards and associated tags.

PARAMETERS
       Points  to  the	location  of  a variable containing the wide-character
       value.  Points to a byte array containing the multibyte character to be
       converted.   Specifies the maximum number of bytes to evaluate.	Points
       to the mbstate_t structure that contains the conversion	state  of  the
       multibyte character in s (for mbrtowc() only).

DESCRIPTION
       The  mbtowc() function converts a multibyte character to a wide charac‐
       ter and returns the number of bytes of the multibyte  character,	 which
       is stored as an output variable.

       In locales with shift-state character encoding, a call to mbtowc() with
       a null pointer as the s parameter places the function  in  the  initial
       shift  state. A call to mbtowc() with an s parameter that is not a null
       pointer may change the shift state for subsequent  calls	 to  mbtowc(),
       depending  on the character examined. Changing the LC_CTYPE category of
       the locale causes the shift state of the function to be	indeterminate.
       The  implementation  behaves  as	 though	 no  other  function calls the
       mbtowc() function.

       In the case of nonrestartable functions, such as	 mbtowc(),  conversion
       of  shift-state	encoding must first be enabled by calling the function
       with a null pointer parameter and then calling the function again  with
       the multibyte value to be converted. The status of the conversion oper‐
       ation after the call is not available to subsequent calls.

       The mbrtowc() function is a  restartable	 version  of  mbtowc(),	 which
       means  that the shift state for the character in s is maintained in the
       mbstate_t structure and is therefore available to subsequent  calls  by
       mbrtowc() and other restartable conversion functions.

RESTRICTIONS
       The  mbrtowc() and other restartable conversion routines are functional
       only when used with locales that support	 shift-state  encoding.	  Cur‐
       rently, the Tru64 UNIX product does not provide locales that use shift-
       state encoding. Therefore, the run-time behavior of mbrtowc() is equiv‐
       alent  to  mbtowc(),  and  neither  function  returns values listed for
       state-dependent conditions.

RETURN VALUES
       If *s is not a null pointer, the mbtowc() function returns the  follow‐
       ing  values:  A	positive  value	 indicating the number of bytes in the
       multibyte character, if the next n or fewer bytes in  s	constitutes  a
       valid multibyte character other than the null character Zero, if s con‐
       tains a null character -1, if s does  not  contain  a  valid  multibyte
       character  or contains a character having more than the number of bytes
       expressed by the n parameter. In this  case,  mbtowc()  sets  errno  to
       indicate the error.

       If  s  is  not a null pointer, the mbrtowc() function returns the first
       value that applies in the following list: Zero, if the next n or	 fewer
       bytes  are  converted to a null wide character, which is then stored in
       pwc A positive value indicating the number of bytes  in	the  converted
       multibyte  character,  if  the next n or fewer bytes constitute a valid
       multibyte character.  The  counterpart  wide-character  value  is  then
       stored in pwc.  (size_t)-2, if the next n bytes contribute to an incom‐
       plete (but potentially valid) multibyte character.  In  this  case,  no
       value  is  stored  in pwc.  (size_t)-1, if an encoding error occurs, in
       which case the next n or fewer bytes do not contribute  to  a  complete
       and valid multibyte character. In this case, no value is stored in pwc,
       the function sets errno to EILSEQ, and the conversion  state  is	 unde‐
       fined.

       If  *s  is  a  null  pointer, both the mbtowc() and mbrtowc() functions
       return one of the following values, depending on whether the  character
       encoding	 in  the  current  locale  is shift-state dependent: A nonzero
       value, if the character encoding is shift-state dependent Zero, if  the
       character encoding is not shift-state dependent

       The  return  values for these functions is never greater than the value
       specified by the n parameter or the value of MB_CUR_MAX.

ERRORS
       If the following condition occurs, the mbtowc() and mbrtowc() functions
       set  errno  to  the  corresponding value.  The s parameter points to an
       invalid multibyte character.

SEE ALSO
       Functions: btowc(3),  mblen(3),	wctomb(3),  mbstowcs(3),  wcstombs(3),
       wctob(3)

       Files: locale(4)

								     mbtowc(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net