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 2021-03-22 "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 .RS -4
  49 Feature Test Macro Requirements for glibc (see
  50 .BR feature_test_macros (7)):
  51 .RE
  52 .PP
  53 .BR strfromd (),
  54 .BR strfromf (),
  55 .BR strfroml ():
  56 .nf
  57     __STDC_WANT_IEC_60559_BFP_EXT__
  58 .fi
  59 .SH DESCRIPTION
  60 These functions convert a floating-point value,
  61 .IR fp ,
  62 into a string of characters,
  63 .IR str ,
  64 with a configurable
  65 .IR format
  66 string.
  67 At most
  68 .I n
  69 characters are stored into
  70 .IR str .
  71 .PP
  72 The terminating null byte ('\e0') is written if and only if
  73 .I n
  74 is sufficiently large, otherwise the written string is truncated at
  75 .I n
  76 characters.
  77 .PP
  78 The
  79 .BR strfromd (),
  80 .BR strfromf (),
  81 and
  82 .BR strfroml ()
  83 functions are equivalent to
  84 .PP
  85 .in +4n
  86 .EX
  87 snprintf(str, n, format, fp);
  88 .EE
  89 .in
  90 .PP
  91 except for the
  92 .I format
  93 string.
  94 .SS Format of the format string
  95 The
  96 .I format
  97 string must start with the character \(aq%\(aq.
  98 This is followed by an optional precision which starts with the period
  99 character (.), followed by an optional decimal integer.
 100 If no integer is specified after the period character,
 101 a precision of zero is used.
 102 Finally, the format string should have one of the conversion specifiers
 103 .BR a ,
 104 .BR A ,
 105 .BR e ,
 106 .BR E ,
 107 .BR f ,
 108 .BR F ,
 109 .BR g ,
 110 or
 111 .BR G .
 112 .PP
 113 The conversion specifier is applied based on the floating-point type
 114 indicated by the function suffix.
 115 Therefore, unlike
 116 .BR snprintf (),
 117 the format string does not have a length modifier character.
 118 See
 119 .BR snprintf (3)
 120 for a detailed description of these conversion specifiers.
 121 .PP
 122 The implementation conforms to the C99 standard on conversion of NaN and
 123 infinity values:
 124 .PP
 125 .RS
 126 If
 127 .I fp
 128 is a NaN, +NaN, or \-NaN, and
 129 .BR f
 130 (or
 131 .BR a ,
 132 .BR e ,
 133 .BR g )
 134 is the conversion specifier, the conversion is to "nan", "nan", or "\-nan",
 135 respectively.
 136 If
 137 .B F
 138 (or
 139 .BR A ,
 140 .BR E ,
 141 .BR G )
 142 is the conversion specifier, the conversion is to "NAN" or "\-NAN".
 143 .PP
 144 Likewise if
 145 .I fp
 146 is infinity, it is converted to [\-]inf or [\-]INF.
 147 .RE
 148 .PP
 149 A malformed
 150 .I format
 151 string results in undefined behavior.
 152 .SH RETURN VALUE
 153 The
 154 .BR strfromd (),
 155 .BR strfromf (),
 156 and
 157 .BR strfroml ()
 158 functions return the number of characters that would have been written in
 159 .I str
 160 if
 161 .I n
 162 had enough space,
 163 not counting the terminating null byte.
 164 Thus, a return value of
 165 .I n
 166 or greater means that the output was truncated.
 167 .SH VERSIONS
 168 The
 169 .BR strfromd (),
 170 .BR strfromf (),
 171 and
 172 .BR strfroml ()
 173 functions are available in glibc since version 2.25.
 174 .SH ATTRIBUTES
 175 For an explanation of the terms used in this section, see
 176 .BR attributes (7)
 177 and the
 178 .B POSIX Safety Concepts
 179 section in GNU C Library manual.
 180 .PP
 181 .ad l
 182 .nh
 183 .TS
 184 allbox;
 185 lbx 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 \^      Async-signal safety     AS-Unsafe heap
 194 \^      Async-cancel safety     AC-Unsafe mem
 195 .TE
 196 .hy
 197 .ad
 198 .sp 1
 199 Note: these attributes are preliminary.
 200 .SH CONFORMING TO
 201 C99, ISO/IEC TS 18661-1.
 202 .SH NOTES
 203 The
 204 .BR strfromd (),
 205 .BR strfromf (),
 206 and
 207 .BR strfroml ()
 208 functions take account of the
 209 .B LC_NUMERIC
 210 category of the current locale.
 211 .SH EXAMPLES
 212 To convert the value 12.1 as a float type to a string using decimal
 213 notation, resulting in "12.100000":
 214 .PP
 215 .in +4n
 216 .EX
 217 #define __STDC_WANT_IEC_60559_BFP_EXT__
 218 #include <stdlib.h>
 219 int ssize = 10;
 220 char s[ssize];
 221 strfromf(s, ssize, "%f", 12.1);
 222 .EE
 223 .in
 224 .PP
 225 To convert the value 12.3456 as a float type to a string using
 226 decimal notation with two digits of precision, resulting in "12.35":
 227 .PP
 228 .in +4n
 229 .EX
 230 #define __STDC_WANT_IEC_60559_BFP_EXT__
 231 #include <stdlib.h>
 232 int ssize = 10;
 233 char s[ssize];
 234 strfromf(s, ssize, "%.2f", 12.3456);
 235 .EE
 236 .in
 237 .PP
 238 To convert the value 12.345e19 as a double type to a string using
 239 scientific notation with zero digits of precision, resulting in "1E+20":
 240 .PP
 241 .in +4n
 242 .EX
 243 #define __STDC_WANT_IEC_60559_BFP_EXT__
 244 #include <stdlib.h>
 245 int ssize = 10;
 246 char s[ssize];
 247 strfromd(s, ssize, "%.E", 12.345e19);
 248 .EE
 249 .in
 250 .SH SEE ALSO
 251 .BR atof (3),
 252 .BR snprintf (3),
 253 .BR strtod (3)