mirror of https://github.com/mkerrisk/man-pages
252 lines
5.8 KiB
Groff
252 lines
5.8 KiB
Groff
.\" Copyright (c) 2016, IBM Corporation.
|
|
.\" Written by Wainer dos Santos Moschetta <wainersm@linux.vnet.ibm.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of
|
|
.\" this manual under the conditions for verbatim copying, provided that
|
|
.\" the entire resulting derived work is distributed under the terms of
|
|
.\" a permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume.
|
|
.\" no responsibility for errors or omissions, or for damages resulting.
|
|
.\" from the use of the information contained herein. The author(s) may.
|
|
.\" not have taken the same level of care in the production of this.
|
|
.\" manual, which is licensed free of charge, as they might when working.
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" References consulted:
|
|
.\" Glibc 2.25 source code and manual.
|
|
.\" C99 standard document.
|
|
.\" ISO/IEC TS 18661-1 technical specification.
|
|
.\" snprintf and other man.3 pages.
|
|
.\"
|
|
.TH STRFROMD 3 2019-03-06 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
strfromd, strfromf, strfroml \- convert a floating-point value into
|
|
a string
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <stdlib.h>
|
|
.PP
|
|
.BI "int strfromd(char *restrict " str ", size_t " n ",
|
|
.BI " const char *restrict " format ", double " fp ");"
|
|
.BI "int strfromf(char *restrict " str ", size_t " n ",
|
|
.BI " const char *restrict " format ", float "fp ");"
|
|
.BI "int strfroml(char *restrict " str ", size_t " n ",
|
|
.BI " const char *restrict " format ", long double " fp ");"
|
|
.fi
|
|
.PP
|
|
.in -4
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.PP
|
|
.ad l
|
|
.BR strfromd (),
|
|
.BR strfromf (),
|
|
.BR strfroml ():
|
|
.RS 4
|
|
__STDC_WANT_IEC_60559_BFP_EXT__
|
|
.RE
|
|
.ad b
|
|
.SH DESCRIPTION
|
|
These functions convert a floating-point value,
|
|
.IR fp ,
|
|
into a string of characters,
|
|
.IR str ,
|
|
with a configurable
|
|
.IR format
|
|
string.
|
|
At most
|
|
.I n
|
|
characters are stored into
|
|
.IR str .
|
|
.PP
|
|
The terminating null character ('\e0') is written if and only if
|
|
.I n
|
|
is sufficiently large, otherwise the written string is truncated at
|
|
.I n
|
|
characters.
|
|
.PP
|
|
The
|
|
.BR strfromd (),
|
|
.BR strfromf (),
|
|
and
|
|
.BR strfroml ()
|
|
functions are equivalent to
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
snprintf(str, n, format, fp);
|
|
.EE
|
|
.in
|
|
.PP
|
|
except for the
|
|
.I format
|
|
string.
|
|
.SS Format of the format string
|
|
The
|
|
.I format
|
|
string must start with the character \(aq%\(aq.
|
|
This is followed by an optional precision which starts with the period
|
|
character (.), followed by an optional decimal integer.
|
|
If no integer is specified after the period character,
|
|
a precision of zero is used.
|
|
Finally, the format string should have one of the conversion specifiers
|
|
.BR a ,
|
|
.BR A ,
|
|
.BR e ,
|
|
.BR E ,
|
|
.BR f ,
|
|
.BR F ,
|
|
.BR g ,
|
|
or
|
|
.BR G .
|
|
.PP
|
|
The conversion specifier is applied based on the floating-point type
|
|
indicated by the function suffix.
|
|
Therefore, unlike
|
|
.BR snprintf (),
|
|
the format string does not have a length modifier character.
|
|
See
|
|
.BR snprintf (3)
|
|
for a detailed description of these conversion specifiers.
|
|
.PP
|
|
The implementation conforms to the C99 standard on conversion of NaN and
|
|
infinity values:
|
|
.PP
|
|
.RS
|
|
If
|
|
.I fp
|
|
is a NaN, +NaN, or -NaN, and
|
|
.BR f
|
|
(or
|
|
.BR a ,
|
|
.BR e ,
|
|
.BR g )
|
|
is the conversion specifier, the conversion is to "nan", "nan", or "-nan",
|
|
respectively.
|
|
If
|
|
.B F
|
|
(or
|
|
.BR A ,
|
|
.BR E ,
|
|
.BR G )
|
|
is the conversion specifier, the conversion is to "NAN" or "-NAN".
|
|
.PP
|
|
Likewise if
|
|
.I fp
|
|
is infinity, it is converted to [-]inf or [-]INF.
|
|
.RE
|
|
.PP
|
|
A malformed
|
|
.I format
|
|
string results in undefined behavior.
|
|
.SH RETURN VALUE
|
|
The
|
|
.BR strfromd (),
|
|
.BR strfromf (),
|
|
and
|
|
.BR strfroml ()
|
|
functions return the number of characters that would have been written in
|
|
.I str
|
|
if
|
|
.I n
|
|
had enough space,
|
|
not counting the terminating null character.
|
|
Thus, a return value of
|
|
.I n
|
|
or greater means that the output was truncated.
|
|
.SH VERSIONS
|
|
The
|
|
.BR strfromd (),
|
|
.BR strfromf (),
|
|
and
|
|
.BR strfroml ()
|
|
functions are available in glibc since version 2.25.
|
|
.SH ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7)
|
|
and the
|
|
.B POSIX Safety Concepts
|
|
section in GNU C Library manual.
|
|
.PP
|
|
.TS
|
|
allbox;
|
|
lbw11 lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR strfromd (),
|
|
.BR strfromf (),
|
|
.BR strfroml ()
|
|
T} Thread safety MT-Safe locale
|
|
\^ Asynchronous signal safety AS-Unsafe heap
|
|
\^ Asynchronous cancellation safety AC-Unsafe mem
|
|
.TE
|
|
.sp 1
|
|
Note: these attributes are preliminary.
|
|
.SH CONFORMING TO
|
|
C99, ISO/IEC TS 18661-1.
|
|
.SH NOTES
|
|
The
|
|
.BR strfromd (),
|
|
.BR strfromf (),
|
|
and
|
|
.BR strfroml ()
|
|
functions take account of the
|
|
.B LC_NUMERIC
|
|
category of the current locale.
|
|
.SH EXAMPLES
|
|
To convert the value 12.1 as a float type to a string using decimal
|
|
notation, resulting in "12.100000":
|
|
.PP
|
|
.in +4
|
|
.EX
|
|
#define __STDC_WANT_IEC_60559_BFP_EXT__
|
|
#include <stdlib.h>
|
|
int ssize = 10;
|
|
char s[ssize];
|
|
strfromf(s, ssize, "%f", 12.1);
|
|
.EE
|
|
.in
|
|
.PP
|
|
To convert the value 12.3456 as a float type to a string using
|
|
decimal notation with two digits of precision, resulting in "12.35":
|
|
.PP
|
|
.in +4
|
|
.EX
|
|
#define __STDC_WANT_IEC_60559_BFP_EXT__
|
|
#include <stdlib.h>
|
|
int ssize = 10;
|
|
char s[ssize];
|
|
strfromf(s, ssize, "%.2f", 12.3456);
|
|
.EE
|
|
.in
|
|
.PP
|
|
To convert the value 12.345e19 as a double type to a string using
|
|
scientific notation with zero digits of precision, resulting in "1E+20":
|
|
.PP
|
|
.in +4
|
|
.EX
|
|
#define __STDC_WANT_IEC_60559_BFP_EXT__
|
|
#include <stdlib.h>
|
|
int ssize = 10;
|
|
char s[ssize];
|
|
strfromd(s, ssize, "%.E", 12.345e19);
|
|
.EE
|
|
.in
|
|
.SH SEE ALSO
|
|
.BR atof (3),
|
|
.BR snprintf (3),
|
|
.BR strtod (3)
|