locale/FreeBSD/mbrtowc.3

   1 .\" Copyright (c) 2002 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.3 2002/11/29 17:35:09 ru Exp $
  26 .\"
  27 .Dd August 15, 2002
  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 and interprets them as a multibyte character sequence
  50 according to the current setting of
  51 .Ev LC_CTYPE .
  52 If
  53 .Fa pwc
  54 is not
  55 .Dv NULL ,
  56 the multibyte character which
  57 .Fa s
  58 represents is stored in the
  59 .Vt wchar_t
  60 it points to.
  61 .Pp
  62 If
  63 .Fa s
  64 is
  65 .Dv NULL ,
  66 .Fn mbrtowc
  67 behaves as if
  68 .Fa pwc
  69 was
  70 .Dv NULL ,
  71 .Fa s
  72 was an empty string
  73 .Pq Qq
  74 and
  75 .Fa n
  76 was 1.
  77 .Pp
  78 The
  79 .Vt mbstate_t
  80 argument,
  81 .Fa ps ,
  82 is used to keep track of the shift state.
  83 If it is
  84 .Dv NULL ,
  85 .Fn mbrtowc
  86 uses an internal, static
  87 .Vt mbstate_t
  88 object.
  89 .Sh RETURN VALUES
  90 The
  91 .Fn mbrtowc
  92 functions returns:
  93 .Bl -tag -width indent
  94 .It 0
  95 The first
  96 .Fa n
  97 or fewer bytes of
  98 .Fa s
  99 represent the null wide character
 100 .Pq Li "L'\e0'" .
 101 .It >0
 102 The first
 103 .Fa n
 104 or fewer bytes of
 105 .Fa s
 106 represent a valid character,
 107 .Fn mbrtowc
 108 returns the length (in bytes) of the multibyte sequence.
 109 .It Po Vt size_t Pc Ns \-2
 110 The first
 111 .Fa n
 112 bytes of
 113 .Fa s
 114 are an incomplete multibyte sequence.
 115 .It Po Vt size_t Pc Ns \-1
 116 The byte sequence pointed to by
 117 .Fa s
 118 is an invalid multibyte sequence.
 119 .El
 120 .Sh ERRORS
 121 The
 122 .Fn mbrtowc
 123 function will fail if:
 124 .Bl -tag -width Er
 125 .\".It Bq Er EINVAL
 126 .\"Invalid argument.
 127 .It Bq Er EILSEQ
 128 An invalid multibyte sequence was detected.
 129 .El
 130 .Sh SEE ALSO
 131 .Xr mbtowc 3 ,
 132 .Xr setlocale 3 ,
 133 .Xr wcrtomb 3
 134 .Sh STANDARDS
 135 The
 136 .Fn mbrtowc
 137 function conforms to
 138 .St -isoC-99 .
 139 .Sh BUGS
 140 The current implementation does not support shift states.