man3/strfromd.3

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