1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
4 <meta http-equiv=
"Content-Type" content=
"text/html; charset=utf-8">
5 <meta http-equiv=
"Content-Style-Type" content=
"text/css">
6 <link rel=
"up" title=
"FatFs" href=
"../00index_e.html">
7 <link rel=
"alternate" hreflang=
"ja" title=
"Japanese" href=
"../ja/printf.html">
8 <link rel=
"stylesheet" href=
"../css_e.css" type=
"text/css" media=
"screen" title=
"ELM Default">
9 <title>FatFs - f_printf
</title>
14 <div class=
"para func">
16 <p>The f_printf function writes formatted string to the file.
</p>
19 FIL*
<span class=
"arg">fp
</span>,
<span class=
"c">/* [IN] File object */
</span>
20 const TCHAR*
<span class=
"arg">fmt
</span>,
<span class=
"c">/* [IN] Format stirng */
</span>
26 <div class=
"para arg">
30 <dd>Pointer to the open file object structure.
</dd>
32 <dd>Pointer to the null
<tt>'\
0'
</tt> terminated format string. The terminator character will not be output.
</dd>
34 <dd>Optional arguments...
</dd>
40 <div class=
"para ret">
41 <h4>Return Values
</h4>
42 <p>When the string was written successfuly, it returns number of character encoding units written to the file. When the function failed due to disk full or an error, a negative value will be returned.
</p>
46 <div class=
"para desc">
48 <p>The format control directive is a sub-set of standard library shown as follows:
</p>
50 %[flag][width][precision][size]type
53 <dt>flag
</dt><dd>Padding option. A
<tt>-
</tt> specifies left-aligned. A
<tt>0</tt> specifies zero padded. The default setting is in right-aligned and space padded.
</dd>
54 <dt>width
</dt><dd>Minimum width of the field,
<tt>1-
99</tt> or
<tt>*
</tt>. If the width of generated string is less than the minimum width, rest field is padded with spaces or zeros. An
<tt>*
</tt> specifies the value comes from an argument in int type. The default setting is zero.
</dd>
55 <dt>precision
</dt><dd>Specifies number of fractional digits or maximum width of string,
<tt>.0-
.99</tt> or
<tt>.*
</tt>. If the number is omitted, it is same as
<tt>.0</tt>. Default setting is
6 for number and no limit for string.
</dd>
56 <dt>size
</dt><dd>Specifies size of integer argument,
<tt>l
</tt>(long) and
<tt>ll
</tt>(long long). If
<tt>sizeof (long) == sizeof (int)
</tt> is true (this is typical of
32-bit systems), prefix
<tt>l
</tt> can be omitted for long integer argument. The default size is int for integer argument and floating point argument is always assumed double as the default argument promotion.
</dd>
57 <dt>type
</dt><dd>Specifies type of the output format and the argument as shown below. The length of generated string is in assumtion of int is
32-bit.
59 <tr><th>Type
</th><th>Format
</th><th>Argument
</th><th>Length
</th></tr>
60 <tr><td><tt>c
</tt></td><td>Character
</td><td rowspan=
"6"><tt>int
</tt>,
<br><tt>long
</tt>,
<br><tt>long long
</tt></td><td>1 character.
</td></tr>
61 <tr><td><tt>d
</tt></td><td>Signed
decimal
</td><td>1 to
11 (
20 for ll) characters.
</td></tr>
62 <tr><td><tt>u
</tt></td><td>Unsigned
decimal
</td><td>1 to
10 (
20 for ll) characters.
</td></tr>
63 <tr><td><tt>o
</tt></td><td>Unsigned
octal
</td><td>1 to
11 (
22 for ll) characters.
</td></tr>
64 <tr><td><tt>x X
</tt></td><td>Unsigned
hexdecimal
</td><td>1 to
8 (
16 for ll) characters.
</td></tr>
65 <tr><td><tt>b
</tt></td><td>Unsigned
binary
</td><td>1 to
32 characters. Limited to lower
32 digits when ll is specified.
</td></tr>
66 <tr><td><tt>s
</tt></td><td>String
</td><td><tt>TCHAR*
</tt></td><td>As input string. Null pointer generates a null string.
</td></tr>
67 <tr><td><tt>f
</tt></td><td>Floating point
<br>(decimal)
</td><td rowspan=
"2"><tt>double
</tt></td><td>1 to
31 characters. If the number of characters exceeds
31, it writes
<tt>"±OV"</tt>. Not a number and infinite write
<tt>"NaN"</tt> and
<tt>"±INF"</tt>.
</td></tr>
68 <tr><td><tt>e E
</tt></td><td>Floating point
<br>(e notation)
</td><td>4 to
31 characters. If the number of characters exceeds
31 or exponent exceeds +
99, it writes
<tt>"±OV"</tt>.
</td></tr>
72 <p>When FatFs is configured for Unicode API (
<tt><a href=
"config.html#lfn_unicode">FF_LFN_UNICODE
</a> >=
1</tt>), character encoding on the string fuctions,
<tt>f_putc
</tt>,
<tt>f_puts
</tt>,
<tt>f_printf
</tt> and
<tt>f_gets
</tt> function, is also switched to Unicode. The Unicode characters in multiple encoding unit, such as surrogate pair and multi-byte sequence, should not be divided into two function calls, or the character will be lost. The character encoding
<em>on the file
</em> to be written via this function is selected by
<tt><a href=
"config.html#strf_encode">FF_STRF_ENCODE
</a></tt>. The characters with wrong encoding or invalid for the output encoding will be lost.
</p>
73 <p>If
<tt>sprintf
</tt> is used in the project and code conversion is not needed,
<tt>f_write
</tt> with
<tt>sprintf
</tt> will be efficient in code size and performance rather than
<tt>f_printf
</tt>.
</p>
77 <div class=
"para comp">
79 <p>This is a wrapper function of
<a href=
"write.html"><tt>f_write
</tt></a> function. Available when
<tt><a href=
"config.html#fs_readonly">FF_FS_READONLY
</a> ==
0</tt> and
<tt><a href=
"config.html#use_strfunc">FF_USE_STRFUNC
</a> >=
1</tt>. When
<tt>FF_USE_STRFUNC ==
2</tt>,
<tt>'\n'
</tt>s in the generated string are written as
<tt>'\r'+'\n'
</tt> each.
</p>
83 <div class=
"para use">
86 <em>f_printf
</em>(fp,
"%d",
1234);
<span class=
"c">/*
"1234" */
</span>
87 <em>f_printf
</em>(fp,
"%6d,%3d%%", -
200,
5);
<span class=
"c">/*
" -200, 5%" */
</span>
88 <em>f_printf
</em>(fp,
"%-6u",
100);
<span class=
"c">/*
"100 " */
</span>
89 <em>f_printf
</em>(fp,
"%ld",
12345678);
<span class=
"c">/*
"12345678" */
</span>
90 <em>f_printf
</em>(fp,
"%llu",
0x100000000);
<span class=
"c">/*
"4294967296" (
<a href=
"config.html#print_lli">FF_PRINT_LLI
</a>) */
</span>
91 <em>f_printf
</em>(fp,
"%lld", -
1LL);
<span class=
"c">/*
"-1" (FF_PRINT_LLI) */
</span>
92 <em>f_printf
</em>(fp,
"%04x",
0xA3);
<span class=
"c">/*
"00a3" */
</span>
93 <em>f_printf
</em>(fp,
"%08lX",
0x123ABC);
<span class=
"c">/*
"00123ABC" */
</span>
94 <em>f_printf
</em>(fp,
"%016b",
0x550F);
<span class=
"c">/*
"0101010100001111" */
</span>
95 <em>f_printf
</em>(fp,
"%*d",
6,
100);
<span class=
"c">/*
" 100" */
</span>
96 <em>f_printf
</em>(fp,
"%s",
"abcdefg");
<span class=
"c">/*
"abcdefg" */
</span>
97 <em>f_printf
</em>(fp,
"%5s",
"abc");
<span class=
"c">/*
" abc" */
</span>
98 <em>f_printf
</em>(fp,
"%-5s",
"abc");
<span class=
"c">/*
"abc " */
</span>
99 <em>f_printf
</em>(fp,
"%.5s",
"abcdefg");
<span class=
"c">/*
"abcde" */
</span>
100 <em>f_printf
</em>(fp,
"%-5.2s",
"abcdefg");
<span class=
"c">/*
"ab " */
</span>
101 <em>f_printf
</em>(fp,
"%c", 'a');
<span class=
"c">/*
"a" */
</span>
102 <em>f_printf
</em>(fp,
"%12f",
10.0);
<span class=
"c">/*
" 10.000000" (
<a href=
"config.html#print_fp">FF_PRINT_FLOAT
</a>) */
</span>
103 <em>f_printf
</em>(fp,
"%.4E",
123.45678);
<span class=
"c">/*
"1.2346E+02" (FF_PRINT_FLOAT) */
</span>
108 <div class=
"para ref">
110 <p><tt><a href=
"open.html">f_open
</a>,
<a href=
"putc.html">f_putc
</a>,
<a href=
"puts.html">f_puts
</a>,
<a href=
"gets.html">f_gets
</a>,
<a href=
"close.html">f_close
</a>,
<a href=
"sfile.html">FIL
</a></tt></p>
113 <p class=
"foot"><a href=
"../00index_e.html">Return
</a></p>