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

   1 '\" te
   2 .\"  Copyright (c) 1992, X/Open Company Limited  All Rights Reserved  Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   4 .\" http://www.opengroup.org/bookstore/.
   5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   6 .\"  This notice shall appear on any product containing this material.
   7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  10 .TH WCSTOD 3C "Mar 31, 2003"
  11 .SH NAME
  12 wcstod, wcstof, wcstold, wstod, watof \- convert wide character string to
  13 floating-point number
  14 .SH SYNOPSIS
  15 .LP
  16 .nf
  17 #include <wchar.h>
  18
  19 \fBdouble\fR \fBwcstod\fR(\fBconst wchar_t *restrict\fR \fInptr\fR,
  20      \fBwchar_t **restrict\fR \fIendptr\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBfloat\fR \fBwcstof\fR(\fBconst wchar_t *restrict\fR \fInptr\fR,
  26      \fBwchar_t **restrict\fR \fIendptr\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBlong double\fR \fBwcstold\fR(\fBconst wchar_t *restrict\fR \fInptr\fR,
  32      \fBwchar_t **restrict\fR \fIendptr\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBdouble\fR \fBwstod\fR(\fBconst wchar_t *\fR\fInptr\fR, \fBwchar_t **\fR\fIendptr\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBdouble\fR \fBwatof\fR(\fBwchar_t *\fR\fInptr\fR);
  43 .fi
  44
  45 .SH DESCRIPTION
  46 .sp
  47 .LP
  48 The \fBwcstod()\fR, \fBwcstof()\fR, and \fBwcstold()\fR functions convert the
  49 initial portion of the wide-character string pointed to by \fInptr\fR to
  50 \fBdouble\fR, \fBfloat\fR, and \fBlong double\fR representation, respectively.
  51 They first decompose the input wide-character string into three parts:
  52 .RS +4
  53 .TP
  54 1.
  55 An initial, possibly empty, sequence of white-space wide-character codes (as
  56 specified by \fBiswspace\fR(3C))
  57 .RE
  58 .RS +4
  59 .TP
  60 2.
  61 A subject sequence interpreted as a floating-point constant or representing
  62 infinity or NaN
  63 .RE
  64 .RS +4
  65 .TP
  66 3.
  67 A final wide-character string of one or more unrecognized wide-character
  68 codes, including the terminating null wide-character code of the input
  69 wide-character string.
  70 .RE
  71 .sp
  72 .LP
  73 Then they attempt to convert the subject sequence to a floating-point number,
  74 and return the result.
  75 .sp
  76 .LP
  77 The expected form of the subject sequence is an optional plus or minus sign,
  78 then one of the following:
  79 .RS +4
  80 .TP
  81 .ie t \(bu
  82 .el o
  83 A non-empty sequence of decimal digits optionally containing a radix character,
  84 then an optional exponent part
  85 .RE
  86 .RS +4
  87 .TP
  88 .ie t \(bu
  89 .el o
  90 A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally
  91 containing a radix character, then an optional binary exponent part
  92 .RE
  93 .RS +4
  94 .TP
  95 .ie t \(bu
  96 .el o
  97 One of INF or INFINITY, or any other wide string equivalent except for case
  98 .RE
  99 .RS +4
 100 .TP
 101 .ie t \(bu
 102 .el o
 103 One of NAN or NAN(\fIn-wchar-sequence\fR(\fIopt\fR)), or any other wide string
 104 ignoring case in the NAN part, where:
 105 .sp
 106 .in +2
 107 .nf
 108 n-wchar-sequence:
 109     digit
 110     nondigit
 111     n-wchar-sequence digit
 112     n-wchar-sequence nondigit
 113 .fi
 114 .in -2
 115
 116 .RE
 117 .sp
 118 .LP
 119 In default mode for \fBwcstod()\fR, only decimal, INF/INFINITY, and
 120 NAN/NAN(\fIn-char-sequence\fR) forms are recognized. In C99/SUSv3 mode,
 121 hexadecimal strings are also recognized.
 122 .sp
 123 .LP
 124 In default mode for \fBwcstod()\fR, the \fIn-char-sequence\fR in the
 125 NAN(\fIn-char-equence\fR) form can contain any character except ')' (right
 126 parenthesis) or '\e0' (null).  In C99/SUSv3 mode, the \fIn-char-sequence\fR can
 127 contain only upper and lower case letters, digits, and '_' (underscore).
 128 .sp
 129 .LP
 130 The \fBwcstof()\fR and \fBwcstold()\fR functions always function in
 131 C99/SUSv3-conformant mode.
 132 .sp
 133 .LP
 134 The subject sequence is defined as the longest initial subsequence of the input
 135 wide string, starting with the first non-white-space wide character, that is of
 136 the expected form. The subject sequence contains no wide characters if the
 137 input wide string is not of the expected form.
 138 .sp
 139 .LP
 140 If the subject sequence has the expected form for a floating-point number, the
 141 sequence of wide characters starting with the first digit or the radix
 142 character (whichever occurs first) is interpreted as a floating constant
 143 according to the rules of the C language, except that the radix character is
 144 used in place of a period, and that if neither an exponent part nor a radix
 145 character appears in a decimal floating-point number, or if a binary exponent
 146 part does not appear in a hexadecimal floating-point number, an exponent part
 147 of the appropriate type with value zero is assumed to follow the last digit in
 148 the string. If the subject sequence begins with a minus sign, the sequence is
 149 interpreted as negated. A wide-character sequence INF or INFINITY is
 150 interpreted as an infinity. A wide-character sequence NAN or
 151 NAN(\fIn-wchar-sequence\fR(\fIopt\fR)) is interpreted as a quiet NaN. A pointer
 152 to the final wide string is stored in the object pointed to by \fIendptr\fR,
 153 provided that \fIendptr\fR is not a null pointer.
 154 .sp
 155 .LP
 156 If the subject sequence has either the decimal or hexadecimal form, the value
 157 resulting from the conversion is rounded correctly according to the prevailing
 158 floating point rounding direction mode. The conversion also raises floating
 159 point inexact, underflow, or overflow exceptions as appropriate.
 160 .sp
 161 .LP
 162 The radix character is defined in the program's locale (category
 163 \fBLC_NUMERIC\fR). In the POSIX locale, or in a locale where the radix
 164 character is not defined, the radix character defaults to a period ('.').
 165 .sp
 166 .LP
 167 If the subject sequence is empty or does not have the expected form, no
 168 conversion is performed; the value of  \fInptr\fR is stored in the object
 169 pointed to by \fIendptr\fR, provided that  \fIendptr\fR is not a null pointer.
 170 .sp
 171 .LP
 172 The \fBwcstod()\fR function does not change the setting of \fBerrno\fR if
 173 successful.
 174 .sp
 175 .LP
 176 The \fBwstod()\fR function is identical to \fBwcstod()\fR.
 177 .sp
 178 .LP
 179 The \fBwatof\fR(\fIstr\fR) function is equivalent to \fBwstod(\fR\fInptr\fR\fB,
 180 (wchar_t **)NULL)\fR.
 181 .SH RETURN VALUES
 182 .sp
 183 .LP
 184 Upon successful completion, these functions return the converted value. If no
 185 conversion could be performed, \fB0\fR is returned.
 186 .sp
 187 .LP
 188 If the correct value is outside the range of representable values,
 189 \fB\(+-HUGE_VAL\fR, \fB\(+-HUGE_VALF\fR, or \fB\(+-HUGE_VALL\fR is returned
 190 (according to the sign of the value), a floating point overflow exception is
 191 raised, and \fBerrno\fR is set to \fBERANGE\fR.
 192 .sp
 193 .LP
 194 If the correct value would cause an underflow, the correctly rounded result
 195 (which may be normal, subnormal, or zero) is returned, a floating point
 196 underflow exception is raised, and \fBerrno\fR is set to \fBERANGE\fR.
 197 .SH ERRORS
 198 .sp
 199 .LP
 200 The \fBwcstod()\fR and \fBwstod()\fR functions will fail if:
 201 .sp
 202 .ne 2
 203 .na
 204 \fB\fBERANGE\fR\fR
 205 .ad
 206 .RS 10n
 207 The value to be returned would cause overflow or underflow.
 208 .RE
 209
 210 .sp
 211 .LP
 212 The \fBwcstod()\fR and \fBwcstod()\fR functions may fail if:
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBEINVAL\fR\fR
 217 .ad
 218 .RS 10n
 219 No conversion could be performed.
 220 .RE
 221
 222 .SH USAGE
 223 .sp
 224 .LP
 225 Because 0 is returned on error and is also a valid return on success, an
 226 application wishing to check for error situations should set \fBerrno\fR to 0
 227 call \fBwcstod()\fR, \fBwcstof()\fR, \fBwcstold()\fR, or \fBwstod()\fR, then
 228 check  \fBerrno\fR and if it is non-zero, assume an error has occurred.
 229 .SH ATTRIBUTES
 230 .sp
 231 .LP
 232 See \fBattributes\fR(5) for descriptions of the following attributes:
 233 .sp
 234
 235 .sp
 236 .TS
 237 box;
 238 l | l
 239 l | l .
 240 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 241 _
 242 Interface Stability     T{
 243 \fBwcstod()\fR, \fBwcstof()\fR, and \fBwcstold()\fR are Standard.
 244 T}
 245 _
 246 MT-Level        MT-Safe
 247 .TE
 248
 249 .SH SEE ALSO
 250 .sp
 251 .LP
 252 \fBiswspace\fR(3C), \fBlocaleconv\fR(3C), \fBscanf\fR(3C), \fBsetlocale\fR(3C),
 253 \fBwcstol\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)