man3/strfromd.3

   1 .\" Copyright (c) 2016, IBM Corporation.
   2 .\" Written by Wainer dos Santos Moschetta <wainersm@linux.vnet.ibm.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of
  10 .\" this manual under the conditions for verbatim copying, provided that
  11 .\" the entire resulting derived work is distributed under the terms of
  12 .\" a permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume.
  16 .\" no responsibility for errors or omissions, or for damages resulting.
  17 .\" from the use of the information contained herein.  The author(s) may.
  18 .\" not have taken the same level of care in the production of this.
  19 .\" manual, which is licensed free of charge, as they might when working.
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" References consulted:
  27 .\"   Glibc 2.25 source code and manual.
  28 .\"   C99 standard document.
  29 .\"   ISO/IEC TS 18661-1 technical specification.
  30 .\"   snprintf and other man.3 pages.
  31 .\"
  32 .TH STRFROMD 3 2019-03-06 "GNU" "Linux Programmer's Manual"
  33 .SH NAME
  34 strfromd, strfromf, strfroml \- convert a floating-point value into
  35 a string
  36 .SH SYNOPSIS
  37 .nf
  38 .B #include <stdlib.h>
  39 .PP
  40 .BI "int strfromd(char *restrict " str ", size_t " n ",
  41 .BI "             const char *restrict " format ", double " fp ");"
  42 .BI "int strfromf(char *restrict " str ", size_t " n ",
  43 .BI "             const char *restrict " format ", float "fp ");"
  44 .BI "int strfroml(char *restrict " str ", size_t " n ",
  45 .BI "             const char *restrict " format ", long double " fp ");"
  46 .fi
  47 .PP
  48 .in -4
  49 Feature Test Macro Requirements for glibc (see
  50 .BR feature_test_macros (7)):
  51 .in
  52 .PP
  53 .ad l
  54 .BR strfromd (),
  55 .BR strfromf (),
  56 .BR strfroml ():
  57 .RS 4
  58 __STDC_WANT_IEC_60559_BFP_EXT__
  59 .RE
  60 .ad b
  61 .SH DESCRIPTION
  62 These functions convert a floating-point value,
  63 .IR fp ,
  64 into a string of characters,
  65 .IR str ,
  66 with a configurable
  67 .IR format
  68 string.
  69 At most
  70 .I n
  71 characters are stored into
  72 .IR str .
  73 .PP
  74 The terminating null character ('\e0') is written if and only if
  75 .I n
  76 is sufficiently large, otherwise the written string is truncated at
  77 .I n
  78 characters.
  79 .PP
  80 The
  81 .BR strfromd (),
  82 .BR strfromf (),
  83 and
  84 .BR strfroml ()
  85 functions are equivalent to
  86 .PP
  87 .in +4n
  88 .EX
  89 snprintf(str, n, format, fp);
  90 .EE
  91 .in
  92 .PP
  93 except for the
  94 .I format
  95 string.
  96 .SS Format of the format string
  97 The
  98 .I format
  99 string must start with the character \(aq%\(aq.
 100 This is followed by an optional precision which starts with the period
 101 character (.), followed by an optional decimal integer.
 102 If no integer is specified after the period character,
 103 a precision of zero is used.
 104 Finally, the format string should have one of the conversion specifiers
 105 .BR a ,
 106 .BR A ,
 107 .BR e ,
 108 .BR E ,
 109 .BR f ,
 110 .BR F ,
 111 .BR g ,
 112 or
 113 .BR G .
 114 .PP
 115 The conversion specifier is applied based on the floating-point type
 116 indicated by the function suffix.
 117 Therefore, unlike
 118 .BR snprintf (),
 119 the format string does not have a length modifier character.
 120 See
 121 .BR snprintf (3)
 122 for a detailed description of these conversion specifiers.
 123 .PP
 124 The implementation conforms to the C99 standard on conversion of NaN and
 125 infinity values:
 126 .PP
 127 .RS
 128 If
 129 .I fp
 130 is a NaN, +NaN, or -NaN, and
 131 .BR f
 132 (or
 133 .BR a ,
 134 .BR e ,
 135 .BR g )
 136 is the conversion specifier, the conversion is to "nan", "nan", or "-nan",
 137 respectively.
 138 If
 139 .B F
 140 (or
 141 .BR A ,
 142 .BR E ,
 143 .BR G )
 144 is the conversion specifier, the conversion is to "NAN" or "-NAN".
 145 .PP
 146 Likewise if
 147 .I fp
 148 is infinity, it is converted to [-]inf or [-]INF.
 149 .RE
 150 .PP
 151 A malformed
 152 .I format
 153 string results in undefined behavior.
 154 .SH RETURN VALUE
 155 The
 156 .BR strfromd (),
 157 .BR strfromf (),
 158 and
 159 .BR strfroml ()
 160 functions return the number of characters that would have been written in
 161 .I str
 162 if
 163 .I n
 164 had enough space,
 165 not counting the terminating null character.
 166 Thus, a return value of
 167 .I n
 168 or greater means that the output was truncated.
 169 .SH VERSIONS
 170 The
 171 .BR strfromd (),
 172 .BR strfromf (),
 173 and
 174 .BR strfroml ()
 175 functions are available in glibc since version 2.25.
 176 .SH ATTRIBUTES
 177 For an explanation of the terms used in this section, see
 178 .BR attributes (7)
 179 and the
 180 .B POSIX Safety Concepts
 181 section in GNU C Library manual.
 182 .PP
 183 .TS
 184 allbox;
 185 lbw11 lb lb
 186 l l l.
 187 Interface       Attribute       Value
 188 T{
 189 .BR strfromd (),
 190 .BR strfromf (),
 191 .BR strfroml ()
 192 T}      Thread safety   MT-Safe locale
 193 \^      Asynchronous signal safety      AS-Unsafe heap
 194 \^      Asynchronous cancellation safety        AC-Unsafe mem
 195 .TE
 196 .sp 1
 197 Note: these attributes are preliminary.
 198 .SH CONFORMING TO
 199 C99, ISO/IEC TS 18661-1.
 200 .SH NOTES
 201 The
 202 .BR strfromd (),
 203 .BR strfromf (),
 204 and
 205 .BR strfroml ()
 206 functions take account of the
 207 .B LC_NUMERIC
 208 category of the current locale.
 209 .SH EXAMPLES
 210 To convert the value 12.1 as a float type to a string using decimal
 211 notation, resulting in "12.100000":
 212 .PP
 213 .in +4
 214 .EX
 215 #define __STDC_WANT_IEC_60559_BFP_EXT__
 216 #include <stdlib.h>
 217 int ssize = 10;
 218 char s[ssize];
 219 strfromf(s, ssize, "%f", 12.1);
 220 .EE
 221 .in
 222 .PP
 223 To convert the value 12.3456 as a float type to a string using
 224 decimal notation with two digits of precision, resulting in "12.35":
 225 .PP
 226 .in +4
 227 .EX
 228 #define __STDC_WANT_IEC_60559_BFP_EXT__
 229 #include <stdlib.h>
 230 int ssize = 10;
 231 char s[ssize];
 232 strfromf(s, ssize, "%.2f", 12.3456);
 233 .EE
 234 .in
 235 .PP
 236 To convert the value 12.345e19 as a double type to a string using
 237 scientific notation with zero digits of precision, resulting in "1E+20":
 238 .PP
 239 .in +4
 240 .EX
 241 #define __STDC_WANT_IEC_60559_BFP_EXT__
 242 #include <stdlib.h>
 243 int ssize = 10;
 244 char s[ssize];
 245 strfromd(s, ssize, "%.E", 12.345e19);
 246 .EE
 247 .in
 248 .SH SEE ALSO
 249 .BR atof (3),
 250 .BR snprintf (3),
 251 .BR strtod (3)