locale/FreeBSD/mbrtowc.3

   1 .\" Copyright (c) 2002-2004 Tim J. Robbins
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libc/locale/mbrtowc.3,v 1.5 2004/06/30 19:32:41 ru Exp $
  26 .\"
  27 .Dd April 8, 2004
  28 .Dt MBRTOWC 3
  29 .Os
  30 .Sh NAME
  31 .Nm mbrtowc
  32 .Nd "convert a character to a wide-character code (restartable)"
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In wchar.h
  37 .Ft size_t
  38 .Fo mbrtowc
  39 .Fa "wchar_t * restrict pwc" "const char * restrict s" "size_t n"
  40 .Fa "mbstate_t * restrict ps"
  41 .Fc
  42 .Sh DESCRIPTION
  43 The
  44 .Fn mbrtowc
  45 function inspects at most
  46 .Fa n
  47 bytes pointed to by
  48 .Fa s
  49 to determine the number of bytes needed to complete the next multibyte
  50 character.
  51 If a character can be completed, and
  52 .Fa pwc
  53 is not
  54 .Dv NULL ,
  55 the wide character which is represented by
  56 .Fa s
  57 is stored in the
  58 .Vt wchar_t
  59 it points to.
  60 .Pp
  61 If
  62 .Fa s
  63 is
  64 .Dv NULL ,
  65 .Fn mbrtowc
  66 behaves as if
  67 .Fa pwc
  68 was
  69 .Dv NULL ,
  70 .Fa s
  71 was an empty string
  72 .Pq Qq
  73 and
  74 .Fa n
  75 was 1.
  76 .Pp
  77 The
  78 .Vt mbstate_t
  79 argument,
  80 .Fa ps ,
  81 is used to keep track of the shift state.
  82 If it is
  83 .Dv NULL ,
  84 .Fn mbrtowc
  85 uses an internal, static
  86 .Vt mbstate_t
  87 object, which is initialized to the initial conversion state
  88 at program startup.
  89 .Sh RETURN VALUES
  90 The
  91 .Fn mbrtowc
  92 functions returns:
  93 .Bl -tag -width indent
  94 .It 0
  95 The next
  96 .Fa n
  97 or fewer bytes
  98 represent the null wide character
  99 .Pq Li "L'\e0'" .
 100 .It >0
 101 The next
 102 .Fa n
 103 or fewer bytes
 104 represent a valid character,
 105 .Fn mbrtowc
 106 returns the number of bytes used to complete the multibyte character.
 107 .It Po Vt size_t Pc Ns \-2
 108 The next
 109 .Fa n
 110 contribute to, but do not complete, a valid multibyte character sequence,
 111 and all
 112 .Fa n
 113 bytes have been processed.
 114 .It Po Vt size_t Pc Ns \-1
 115 An encoding error has occurred.
 116 The next
 117 .Fa n
 118 or fewer bytes do not contribute to a valid multibyte character.
 119 .El
 120 .Sh ERRORS
 121 The
 122 .Fn mbrtowc
 123 function will fail if:
 124 .Bl -tag -width Er
 125 .It Bq Er EILSEQ
 126 An invalid multibyte sequence was detected.
 127 .It Bq Er EINVAL
 128 The conversion state is invalid.
 129 .El
 130 .Sh SEE ALSO
 131 .Xr mbtowc 3 ,
 132 .Xr multibyte 3 ,
 133 .Xr setlocale 3 ,
 134 .Xr wcrtomb 3
 135 .Sh STANDARDS
 136 The
 137 .Fn mbrtowc
 138 function conforms to
 139 .St -isoC-99 .