usr/src/man/man3c/mbrtowc.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
  44 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
  45 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  46 .\"
  47 .TH MBRTOWC 3C "Jun 23, 2014"
  48 .SH NAME
  49 mbrtowc, mbrtowc_l \- convert a character to a wide-character code (restartable)
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 #include <wchar.h>
  54
  55 \fBsize_t\fR \fBmbrtowc\fR(\fBwchar_t *restrict\fR \fIpwc\fR, \fBconst char *restrict\fR \fIs\fR, \fBsize_t\fR \fIn\fR,
  56      \fBmbstate_t *restrict\fR \fIps\fR);
  57 .fi
  58 .LP
  59 .nf
  60 #include <wchar.h>
  61 #include <xlocale.h>
  62
  63 \fBsize_t\fR \fBmbrtowc_l\fR(\fBwchar_t *restrict\fR \fIpwc\fR, \fBconst char *restrict\fR \fIs\fR, \fBsize_t\fR \fIn\fR,
  64      \fBmbstate_t *restrict\fR \fIps\fR, \fBlocale_t\fR \fIloc\fR);
  65 .fi
  66 .SH DESCRIPTION
  67 .LP
  68 If
  69 .I s
  70 is a null pointer, the
  71 .B mbrtowc()
  72 function is equivalent to the call:
  73 .sp
  74 .in +2
  75 .nf
  76 \fBmbrtowc\fR(NULL, "", 1, \fIps\fR)
  77 .fi
  78 .in -2
  79 .LP
  80 Likewise, if
  81 .I s
  82 is a null pointer, the
  83 .B mbrtowc_l()
  84 function is equivalent to the call:
  85 .sp
  86 .in +2
  87 .nf
  88 \fBmbrtowc_l\fR(NULL, "", 1, \fIps\fR, \fIloc\fR);
  89 .fi
  90 .in -2
  91 .LP
  92 In these cases, the values of the arguments
  93 .I pwc
  94 and
  95 .I n
  96 are ignored.
  97 .LP
  98 If
  99 .I s
 100 is not a null pointer, these functions inspect at most
 101 .I n
 102 bytes beginning at the byte pointed to by
 103 .I s
 104 to determine the number of bytes needed to complete the next character
 105 (including any shift sequences).  If the functions determine that the next
 106 character is completed,
 107 they determine the value of the corresponding wide-character and then, if
 108 .I pwc
 109 is not a null pointer, stores that value in the object pointed to by
 110 .IR pwc .
 111 If the corresponding wide-character is the null wide-character, the
 112 resulting state described is the initial conversion state.
 113 .LP
 114 If
 115 .I ps
 116 is a null pointer, these functions use their own
 117 internal
 118 .B mbstate_t
 119 object, which is initialized at program startup to the
 120 initial conversion state. Otherwise, the
 121 .B mbstate_t
 122 object pointed to by
 123 .I ps
 124 is used to completely describe the current conversion state of the
 125 associated character sequence. The system will behave as if no function defined
 126 in the Reference Manual calls
 127 .B mbrtowc()
 128 or
 129 .BR Bmbrtowc_l() .
 130 .LP
 131 The behavior of
 132 .B mbrtowc()
 133 is affected by the
 134 .B LC_CTYPE
 135 category of the current locale.  The
 136 .B mbrtowc_l()
 137 function is affected by the
 138 .B LC_CTYPE
 139 category of the specified
 140 .I loc
 141 locale object.  See
 142 .B environ (5).
 143 .SH RETURN VALUES
 144 .LP
 145 The
 146 .B mbrtowc()
 147 and
 148 .B mbrtowc_l()
 149 functions return the first of the following that applies:
 150 .IP \fB0\fR
 151 If the next
 152 .I n
 153 or fewer bytes complete the character that corresponds to
 154 the null wide-character (which is the value stored).
 155 .IP \fBpositive\fR
 156 If the next
 157 .I n
 158 or fewer bytes complete a valid character (which is the
 159 value stored); the value returned is the number of bytes that complete the
 160 character.
 161 .IP \fB(size_t)\(mi2\fR
 162 If the next
 163 .I n
 164 bytes contribute to an incomplete but potentially valid
 165 character, and all
 166 .I n
 167 bytes have been processed (no value is stored).
 168 When
 169 .I n
 170 has at least the value of the
 171 .B MB_CUR_MAX
 172 macro, this case can only occur if
 173 .I s
 174 points at a sequence of redundant shift sequences
 175 (for implementations with state-dependent encodings).
 176 .IP \fB(size_t)\(mi1\fR
 177 If an encoding error occurs, in which case the next \fIn\fR or fewer bytes do
 178 not contribute to a complete and valid  character (no value is stored).  In
 179 this case,
 180 .B EILSEQ
 181 is stored in
 182 .B errno
 183 and the conversion state is undefined.
 184 .SH ERRORS
 185 .LP
 186 The
 187 .B mbrtowc()
 188 and
 189 .B mbrtowc_l()
 190 functions may fail if:
 191 .IP \fBEINVAL\fR
 192 The
 193 .I ps
 194 argument points to an object that contains an invalid conversion
 195 state.
 196 .IP \fBEILSEQ\fR
 197 Invalid character sequence is detected.
 198 .SH ATTRIBUTES
 199 .LP
 200 See \fBattributes\fR(5) for descriptions of the following attributes:
 201 .TS
 202 box;
 203 c | c
 204 l | l .
 205 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 206 _
 207 Interface Stability     See below.
 208 _
 209 MT-Level        See below.
 210 .TE
 211
 212 .LP
 213 The
 214 .B mbrtowc()
 215 function is Standard.  The
 216 .B mbrtowc_l()
 217 function is Uncommitted.
 218 .LP
 219 If
 220 .I ps
 221 is a null pointer, these functions are Unsafe for use in
 222 multithreaded applications.  Otherwise they are MT-Safe.
 223 .SH SEE ALSO
 224 .LP
 225 .BR mbsinit (3C),
 226 .BR newlocale (3C),
 227 .BR setlocale (3C),
 228 .BR uselocale (3C),
 229 .BR attributes (5),
 230 .BR environ (5),
 231 .BR standards (5)