• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 ******************************************************************************
5 *
6 *   Copyright (C) 1998-2015, International Business Machines
7 *   Corporation and others.  All Rights Reserved.
8 *
9 ******************************************************************************
10 *
11 * File ustdio.h
12 *
13 * Modification History:
14 *
15 *   Date        Name        Description
16 *   10/16/98    stephen     Creation.
17 *   11/06/98    stephen     Modified per code review.
18 *   03/12/99    stephen     Modified for new C API.
19 *   07/19/99    stephen     Minor doc update.
20 *   02/01/01    george      Added sprintf & sscanf with all of its variants
21 ******************************************************************************
22 */
23 
24 #ifndef USTDIO_H
25 #define USTDIO_H
26 
27 #include <stdio.h>
28 #include <stdarg.h>
29 
30 #include "unicode/utypes.h"
31 #include "unicode/ucnv.h"
32 #include "unicode/utrans.h"
33 #include "unicode/unum.h"
34 
35 #if U_SHOW_CPLUSPLUS_API
36 #include "unicode/localpointer.h"
37 #endif   // U_SHOW_CPLUSPLUS_API
38 
39 #if !UCONFIG_NO_CONVERSION
40 
41 /*
42     TODO
43  The following is a small list as to what is currently wrong/suggestions for
44  ustdio.
45 
46  * Make sure that * in the scanf format specification works for all formats.
47  * Each UFILE takes up at least 2KB.
48     Look into adding setvbuf() for configurable buffers.
49  * This library does buffering. The OS should do this for us already. Check on
50     this, and remove it from this library, if this is the case. Double buffering
51     wastes a lot of time and space.
52  * Test stdin and stdout with the u_f* functions
53  * Testing should be done for reading and writing multi-byte encodings,
54     and make sure that a character that is contained across buffer boundries
55     works even for incomplete characters.
56  * Make sure that the last character is flushed when the file/string is closed.
57  * snprintf should follow the C99 standard for the return value, which is
58     return the number of characters (excluding the trailing '\0')
59     which would have been written to the destination string regardless
60     of available space. This is like pre-flighting.
61  * Everything that uses %s should do what operator>> does for UnicodeString.
62     It should convert one byte at a time, and once a character is
63     converted then check to see if it's whitespace or in the scanset.
64     If it's whitespace or in the scanset, put all the bytes back (do nothing
65     for sprintf/sscanf).
66  * If bad string data is encountered, make sure that the function fails
67     without memory leaks and the unconvertable characters are valid
68     substitution or are escaped characters.
69  * u_fungetc() can't unget a character when it's at the beginning of the
70     internal conversion buffer. For example, read the buffer size # of
71     characters, and then ungetc to get the previous character that was
72     at the end of the last buffer.
73  * u_fflush() and u_fclose should return an int32_t like C99 functions.
74     0 is returned if the operation was successful and EOF otherwise.
75  * u_fsettransliterator does not support U_READ side of transliteration.
76  * The format specifier should limit the size of a format or honor it in
77     order to prevent buffer overruns.  (e.g. %256.256d).
78  * u_fread and u_fwrite don't exist. They're needed for reading and writing
79     data structures without any conversion.
80  * u_file_read and u_file_write are used for writing strings. u_fgets and
81     u_fputs or u_fread and u_fwrite should be used to do this.
82  * The width parameter for all scanf formats, including scanset, needs
83     better testing. This prevents buffer overflows.
84  * Figure out what is suppose to happen when a codepage is changed midstream.
85     Maybe a flush or a rewind are good enough.
86  * Make sure that a UFile opened with "rw" can be used after using
87     u_fflush with a u_frewind.
88  * scanf(%i) should detect what type of number to use.
89  * Add more testing of the alternate format, %#
90  * Look at newline handling of fputs/puts
91  * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
92  * Complete the file documentation with proper doxygen formatting.
93     See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
94 */
95 
96 /**
97  * \file
98  * \brief C API: Unicode stdio-like API
99  *
100  * <h2>Unicode stdio-like C API</h2>
101  *
102  * <p>This API provides an stdio-like API wrapper around ICU's other
103  * formatting and parsing APIs. It is meant to ease the transition of adding
104  * Unicode support to a preexisting applications using stdio. The following
105  * is a small list of noticable differences between stdio and ICU I/O's
106  * ustdio implementation.</p>
107  *
108  * <ul>
109  * <li>Locale specific formatting and parsing is only done with file IO.</li>
110  * <li>u_fstropen can be used to simulate file IO with strings.
111  * This is similar to the iostream API, and it allows locale specific
112  * formatting and parsing to be used.</li>
113  * <li>This API provides uniform formatting and parsing behavior between
114  * platforms (unlike the standard stdio implementations found on various
115  * platforms).</li>
116  * <li>This API is better suited for text data handling than binary data
117  * handling when compared to the typical stdio implementation.</li>
118  * <li>You can specify a Transliterator while using the file IO.</li>
119  * <li>You can specify a file's codepage separately from the default
120  * system codepage.</li>
121  * </ul>
122  *
123  * <h2>Formatting and Parsing Specification</h2>
124  *
125  * General printf format:<br>
126  * %[format modifier][width][.precision][type modifier][format]
127  *
128  * General scanf format:<br>
129  * %[*][format modifier][width][type modifier][format]
130  *
131 <table cellspacing="3">
132 <tr><td>format</td><td>default<br>printf<br>type</td><td>default<br>scanf<br>type</td><td>description</td></tr>
133 <tr><td>%E</td><td>double</td><td>float</td><td>Scientific with an uppercase exponent</td></tr>
134 <tr><td>%e</td><td>double</td><td>float</td><td>Scientific with a lowercase exponent</td></tr>
135 <tr><td>%G</td><td>double</td><td>float</td><td>Use %E or %f for best format</td></tr>
136 <tr><td>%g</td><td>double</td><td>float</td><td>Use %e or %f for best format</td></tr>
137 <tr><td>%f</td><td>double</td><td>float</td><td>Simple floating point without the exponent</td></tr>
138 <tr><td>%X</td><td>int32_t</td><td>int32_t</td><td>ustdio special uppercase hex radix formatting</td></tr>
139 <tr><td>%x</td><td>int32_t</td><td>int32_t</td><td>ustdio special lowercase hex radix formatting</td></tr>
140 <tr><td>%d</td><td>int32_t</td><td>int32_t</td><td>Decimal format</td></tr>
141 <tr><td>%i</td><td>int32_t</td><td>int32_t</td><td>Same as %d</td></tr>
142 <tr><td>%n</td><td>int32_t</td><td>int32_t</td><td>count (write the number of UTF-16 codeunits read/written)</td></tr>
143 <tr><td>%o</td><td>int32_t</td><td>int32_t</td><td>ustdio special octal radix formatting</td></tr>
144 <tr><td>%u</td><td>uint32_t</td><td>uint32_t</td><td>Decimal format</td></tr>
145 <tr><td>%p</td><td>void *</td><td>void *</td><td>Prints the pointer value</td></tr>
146 <tr><td>%s</td><td>char *</td><td>char *</td><td>Use default converter or specified converter from fopen</td></tr>
147 <tr><td>%c</td><td>char</td><td>char</td><td>Use default converter or specified converter from fopen<br>
148 When width is specified for scanf, this acts like a non-NULL-terminated char * string.<br>
149 By default, only one char is written.</td></tr>
150 <tr><td>%S</td><td>UChar *</td><td>UChar *</td><td>Null terminated UTF-16 string</td></tr>
151 <tr><td>%C</td><td>UChar</td><td>UChar</td><td>16-bit Unicode code unit<br>
152 When width is specified for scanf, this acts like a non-NULL-terminated UChar * string<br>
153 By default, only one codepoint is written.</td></tr>
154 <tr><td>%[]</td><td>&nbsp;</td><td>UChar *</td><td>Null terminated UTF-16 string which contains the filtered set of characters specified by the UnicodeSet</td></tr>
155 <tr><td>%%</td><td>&nbsp;</td><td>&nbsp;</td><td>Show a percent sign</td></tr>
156 </table>
157 
158 Format modifiers
159 <table>
160 <tr><td>modifier</td><td>formats</td><td>type</td><td>comments</td></tr>
161 <tr><td>%h</td><td>%d, %i, %o, %x</td><td>int16_t</td><td>short format</td></tr>
162 <tr><td>%h</td><td>%u</td><td>uint16_t</td><td>short format</td></tr>
163 <tr><td>%h</td><td>c</td><td>char</td><td><b>(Unimplemented)</b> Use invariant converter</td></tr>
164 <tr><td>%h</td><td>s</td><td>char *</td><td><b>(Unimplemented)</b> Use invariant converter</td></tr>
165 <tr><td>%h</td><td>C</td><td>char</td><td><b>(Unimplemented)</b> 8-bit Unicode code unit</td></tr>
166 <tr><td>%h</td><td>S</td><td>char *</td><td><b>(Unimplemented)</b> Null terminated UTF-8 string</td></tr>
167 <tr><td>%l</td><td>%d, %i, %o, %x</td><td>int32_t</td><td>long format (no effect)</td></tr>
168 <tr><td>%l</td><td>%u</td><td>uint32_t</td><td>long format (no effect)</td></tr>
169 <tr><td>%l</td><td>c</td><td>N/A</td><td><b>(Unimplemented)</b> Reserved for future implementation</td></tr>
170 <tr><td>%l</td><td>s</td><td>N/A</td><td><b>(Unimplemented)</b> Reserved for future implementation</td></tr>
171 <tr><td>%l</td><td>C</td><td>UChar32</td><td><b>(Unimplemented)</b> 32-bit Unicode code unit</td></tr>
172 <tr><td>%l</td><td>S</td><td>UChar32 *</td><td><b>(Unimplemented)</b> Null terminated UTF-32 string</td></tr>
173 <tr><td>%ll</td><td>%d, %i, %o, %x</td><td>int64_t</td><td>long long format</td></tr>
174 <tr><td>%ll</td><td>%u</td><td>uint64_t</td><td><b>(Unimplemented)</b> long long format</td></tr>
175 <tr><td>%-</td><td><i>all</i></td><td>N/A</td><td>Left justify</td></tr>
176 <tr><td>%+</td><td>%d, %i, %o, %x, %e, %f, %g, %E, %G</td><td>N/A</td><td>Always show the plus or minus sign. Needs data for plus sign.</td></tr>
177 <tr><td>% </td><td>%d, %i, %o, %x, %e, %f, %g, %E, %G</td><td>N/A</td><td>Instead of a "+" output a blank character for positive numbers.</td></tr>
178 <tr><td>%#</td><td>%d, %i, %o, %x, %e, %f, %g, %E, %G</td><td>N/A</td><td>Precede octal value with 0, hex with 0x and show the
179                 decimal point for floats.</td></tr>
180 <tr><td>%<i>n</i></td><td><i>all</i></td><td>N/A</td><td>Width of input/output. num is an actual number from 0 to
181                 some large number.</td></tr>
182 <tr><td>%.<i>n</i></td><td>%e, %f, %g, %E, %F, %G</td><td>N/A</td><td>Significant digits precision. num is an actual number from
183                 0 to some large number.<br>If * is used in printf, then the precision is passed in as an argument before the number to be formatted.</td></tr>
184 </table>
185 
186 printf modifier
187 %*  int32_t     Next argument after this one specifies the width
188 
189 scanf modifier
190 %*  N/A         This field is scanned, but not stored
191 
192 <p>If you are using this C API instead of the ustream.h API for C++,
193 you can use one of the following u_fprintf examples to display a UnicodeString.</p>
194 
195 <pre><code>
196     UFILE *out = u_finit(stdout, NULL, NULL);
197     UnicodeString string1("string 1");
198     UnicodeString string2("string 2");
199     u_fprintf(out, "%S\n", string1.getTerminatedBuffer());
200     u_fprintf(out, "%.*S\n", string2.length(), string2.getBuffer());
201     u_fclose(out);
202 </code></pre>
203 
204  */
205 
206 
207 /**
208  * When an end of file is encountered, this value can be returned.
209  * @see u_fgetc
210  * @stable 3.0
211  */
212 #define U_EOF 0xFFFF
213 
214 /** Forward declaration of a Unicode-aware file @stable 3.0 */
215 typedef struct UFILE UFILE;
216 
217 /**
218  * Enum for which direction of stream a transliterator applies to.
219  * @see u_fsettransliterator
220  * @stable ICU 3.0
221  */
222 typedef enum {
223    U_READ = 1,
224    U_WRITE = 2,
225    U_READWRITE =3  /* == (U_READ | U_WRITE) */
226 } UFileDirection;
227 
228 /**
229  * Open a UFILE.
230  * A UFILE is a wrapper around a FILE* that is locale and codepage aware.
231  * That is, data written to a UFILE will be formatted using the conventions
232  * specified by that UFILE's Locale; this data will be in the character set
233  * specified by that UFILE's codepage.
234  * @param filename The name of the file to open. Must be 0-terminated.
235  * @param perm The read/write permission for the UFILE; one of "r", "w", "rw"
236  * @param locale The locale whose conventions will be used to format
237  * and parse output. If this parameter is NULL, the default locale will
238  * be used.
239  * @param codepage The codepage in which data will be written to and
240  * read from the file. If this paramter is NULL the system default codepage
241  * will be used.
242  * @return A new UFILE, or NULL if an error occurred.
243  * @stable ICU 3.0
244  */
245 U_CAPI UFILE* U_EXPORT2
246 u_fopen(const char    *filename,
247     const char    *perm,
248     const char    *locale,
249     const char    *codepage);
250 
251 /**
252  * Open a UFILE with a UChar* filename
253  * A UFILE is a wrapper around a FILE* that is locale and codepage aware.
254  * That is, data written to a UFILE will be formatted using the conventions
255  * specified by that UFILE's Locale; this data will be in the character set
256  * specified by that UFILE's codepage.
257  * @param filename The name of the file to open. Must be 0-terminated.
258  * @param perm The read/write permission for the UFILE; one of "r", "w", "rw"
259  * @param locale The locale whose conventions will be used to format
260  * and parse output. If this parameter is NULL, the default locale will
261  * be used.
262  * @param codepage The codepage in which data will be written to and
263  * read from the file. If this paramter is NULL the system default codepage
264  * will be used.
265  * @return A new UFILE, or NULL if an error occurred.
266  * @stable ICU 54
267  */
268 U_CAPI UFILE* U_EXPORT2
269 u_fopen_u(const UChar    *filename,
270     const char    *perm,
271     const char    *locale,
272     const char    *codepage);
273 
274 /**
275  * Open a UFILE on top of an existing FILE* stream. The FILE* stream
276  * ownership remains with the caller. To have the UFILE take over
277  * ownership and responsibility for the FILE* stream, use the
278  * function u_fadopt.
279  * @param f The FILE* to which this UFILE will attach and use.
280  * @param locale The locale whose conventions will be used to format
281  * and parse output. If this parameter is NULL, the default locale will
282  * be used.
283  * @param codepage The codepage in which data will be written to and
284  * read from the file. If this paramter is NULL, data will be written and
285  * read using the default codepage for <TT>locale</TT>, unless <TT>locale</TT>
286  * is NULL, in which case the system default codepage will be used.
287  * @return A new UFILE, or NULL if an error occurred.
288  * @stable ICU 3.0
289  */
290 U_CAPI UFILE* U_EXPORT2
291 u_finit(FILE        *f,
292     const char    *locale,
293     const char    *codepage);
294 
295 /**
296  * Open a UFILE on top of an existing FILE* stream. The FILE* stream
297  * ownership is transferred to the new UFILE. It will be closed when the
298  * UFILE is closed.
299  * @param f The FILE* which this UFILE will take ownership of.
300  * @param locale The locale whose conventions will be used to format
301  * and parse output. If this parameter is NULL, the default locale will
302  * be used.
303  * @param codepage The codepage in which data will be written to and
304  * read from the file. If this paramter is NULL, data will be written and
305  * read using the default codepage for <TT>locale</TT>, unless <TT>locale</TT>
306  * is NULL, in which case the system default codepage will be used.
307  * @return A new UFILE, or NULL if an error occurred. If an error occurs
308  * the ownership of the FILE* stream remains with the caller.
309  * @stable ICU 4.4
310  */
311 U_CAPI UFILE* U_EXPORT2
312 u_fadopt(FILE     *f,
313     const char    *locale,
314     const char    *codepage);
315 
316 /**
317  * Create a UFILE that can be used for localized formatting or parsing.
318  * The u_sprintf and u_sscanf functions do not read or write numbers for a
319  * specific locale. The ustdio.h file functions can be used on this UFILE.
320  * The string is usable once u_fclose or u_fflush has been called on the
321  * returned UFILE.
322  * @param stringBuf The string used for reading or writing.
323  * @param capacity The number of code units available for use in stringBuf
324  * @param locale The locale whose conventions will be used to format
325  * and parse output. If this parameter is NULL, the default locale will
326  * be used.
327  * @return A new UFILE, or NULL if an error occurred.
328  * @stable ICU 3.0
329  */
330 U_CAPI UFILE* U_EXPORT2
331 u_fstropen(UChar      *stringBuf,
332            int32_t     capacity,
333            const char *locale);
334 
335 /**
336  * Close a UFILE. Implies u_fflush first.
337  * @param file The UFILE to close.
338  * @stable ICU 3.0
339  * @see u_fflush
340  */
341 U_CAPI void U_EXPORT2
342 u_fclose(UFILE *file);
343 
344 #if U_SHOW_CPLUSPLUS_API
345 
346 U_NAMESPACE_BEGIN
347 
348 /**
349  * \class LocalUFILEPointer
350  * "Smart pointer" class, closes a UFILE via u_fclose().
351  * For most methods see the LocalPointerBase base class.
352  *
353  * @see LocalPointerBase
354  * @see LocalPointer
355  * @stable ICU 4.4
356  */
357 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose);
358 
359 U_NAMESPACE_END
360 
361 #endif
362 
363 /**
364  * Tests if the UFILE is at the end of the file stream.
365  * @param f The UFILE from which to read.
366  * @return Returns true after the first read operation that attempts to
367  * read past the end of the file. It returns false if the current position is
368  * not end of file.
369  * @stable ICU 3.0
370 */
371 U_CAPI UBool U_EXPORT2
372 u_feof(UFILE  *f);
373 
374 /**
375  * Flush output of a UFILE. Implies a flush of
376  * converter/transliterator state. (That is, a logical break is
377  * made in the output stream - for example if a different type of
378  * output is desired.)  The underlying OS level file is also flushed.
379  * Note that for a stateful encoding, the converter may write additional
380  * bytes to return the stream to default state.
381  * @param file The UFILE to flush.
382  * @stable ICU 3.0
383  */
384 U_CAPI void U_EXPORT2
385 u_fflush(UFILE *file);
386 
387 /**
388  * Rewind the file pointer to the beginning of the file.
389  * @param file The UFILE to rewind.
390  * @stable ICU 3.0
391  */
392 U_CAPI void
393 u_frewind(UFILE *file);
394 
395 /**
396  * Get the FILE* associated with a UFILE.
397  * @param f The UFILE
398  * @return A FILE*, owned by the UFILE. (The FILE <EM>must not</EM> be modified or closed)
399  * @stable ICU 3.0
400  */
401 U_CAPI FILE* U_EXPORT2
402 u_fgetfile(UFILE *f);
403 
404 #if !UCONFIG_NO_FORMATTING
405 
406 /**
407  * Get the locale whose conventions are used to format and parse output.
408  * This is the same locale passed in the preceding call to<TT>u_fsetlocale</TT>
409  * or <TT>u_fopen</TT>.
410  * @param file The UFILE to set.
411  * @return The locale whose conventions are used to format and parse output.
412  * @stable ICU 3.0
413  */
414 U_CAPI const char* U_EXPORT2
415 u_fgetlocale(UFILE *file);
416 
417 /**
418  * Set the locale whose conventions will be used to format and parse output.
419  * @param locale The locale whose conventions will be used to format
420  * and parse output.
421  * @param file The UFILE to query.
422  * @return NULL if successful, otherwise a negative number.
423  * @stable ICU 3.0
424  */
425 U_CAPI int32_t U_EXPORT2
426 u_fsetlocale(UFILE      *file,
427              const char *locale);
428 
429 #endif
430 
431 /**
432  * Get the codepage in which data is written to and read from the UFILE.
433  * This is the same codepage passed in the preceding call to
434  * <TT>u_fsetcodepage</TT> or <TT>u_fopen</TT>.
435  * @param file The UFILE to query.
436  * @return The codepage in which data is written to and read from the UFILE,
437  * or NULL if an error occurred.
438  * @stable ICU 3.0
439  */
440 U_CAPI const char* U_EXPORT2
441 u_fgetcodepage(UFILE *file);
442 
443 /**
444  * Set the codepage in which data will be written to and read from the UFILE.
445  * All Unicode data written to the UFILE will be converted to this codepage
446  * before it is written to the underlying FILE*. It it generally a bad idea to
447  * mix codepages within a file. This should only be called right
448  * after opening the <TT>UFile</TT>, or after calling <TT>u_frewind</TT>.
449  * @param codepage The codepage in which data will be written to
450  * and read from the file. For example <TT>"latin-1"</TT> or <TT>"ibm-943"</TT>.
451  * A value of NULL means the default codepage for the UFILE's current
452  * locale will be used.
453  * @param file The UFILE to set.
454  * @return 0 if successful, otherwise a negative number.
455  * @see u_frewind
456  * @stable ICU 3.0
457  */
458 U_CAPI int32_t U_EXPORT2
459 u_fsetcodepage(const char   *codepage,
460                UFILE        *file);
461 
462 
463 /**
464  * Returns an alias to the converter being used for this file.
465  * @param f The UFILE to get the value from
466  * @return alias to the converter (The converter <EM>must not</EM> be modified or closed)
467  * @stable ICU 3.0
468  */
469 U_CAPI UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
470 
471 #if !UCONFIG_NO_FORMATTING
472 /**
473  * Returns an alias to the number formatter being used for this file.
474  * @param f The UFILE to get the value from
475  * @return alias to the number formatter (The formatter <EM>must not</EM> be modified or closed)
476  * @stable ICU 51
477 */
478  U_CAPI const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f);
479 
480 /* Output functions */
481 
482 /**
483  * Write formatted data to <TT>stdout</TT>.
484  * @param patternSpecification A pattern specifying how <TT>u_printf</TT> will
485  * interpret the variable arguments received and format the data.
486  * @return The number of Unicode characters written to <TT>stdout</TT>
487  * @stable ICU 49
488  */
489 U_CAPI int32_t U_EXPORT2
490 u_printf(const char *patternSpecification,
491          ... );
492 
493 /**
494  * Write formatted data to a UFILE.
495  * @param f The UFILE to which to write.
496  * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
497  * interpret the variable arguments received and format the data.
498  * @return The number of Unicode characters written to <TT>f</TT>.
499  * @stable ICU 3.0
500  */
501 U_CAPI int32_t U_EXPORT2
502 u_fprintf(UFILE         *f,
503           const char    *patternSpecification,
504           ... );
505 
506 /**
507  * Write formatted data to a UFILE.
508  * This is identical to <TT>u_fprintf</TT>, except that it will
509  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
510  * @param f The UFILE to which to write.
511  * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
512  * interpret the variable arguments received and format the data.
513  * @param ap The argument list to use.
514  * @return The number of Unicode characters written to <TT>f</TT>.
515  * @see u_fprintf
516  * @stable ICU 3.0
517  */
518 U_CAPI int32_t U_EXPORT2
519 u_vfprintf(UFILE        *f,
520            const char   *patternSpecification,
521            va_list      ap);
522 
523 /**
524  * Write formatted data to <TT>stdout</TT>.
525  * @param patternSpecification A pattern specifying how <TT>u_printf_u</TT> will
526  * interpret the variable arguments received and format the data.
527  * @return The number of Unicode characters written to <TT>stdout</TT>
528  * @stable ICU 49
529  */
530 U_CAPI int32_t U_EXPORT2
531 u_printf_u(const UChar *patternSpecification,
532            ... );
533 
534 /**
535  * Get a UFILE for <TT>stdout</TT>.
536  * @return UFILE that writes to <TT>stdout</TT>
537  * @stable ICU 49
538  */
539 U_CAPI UFILE * U_EXPORT2
540 u_get_stdout(void);
541 
542 /**
543  * Write formatted data to a UFILE.
544  * @param f The UFILE to which to write.
545  * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
546  * interpret the variable arguments received and format the data.
547  * @return The number of Unicode characters written to <TT>f</TT>.
548  * @stable ICU 3.0
549  */
550 U_CAPI int32_t U_EXPORT2
551 u_fprintf_u(UFILE       *f,
552             const UChar *patternSpecification,
553             ... );
554 
555 /**
556  * Write formatted data to a UFILE.
557  * This is identical to <TT>u_fprintf_u</TT>, except that it will
558  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
559  * @param f The UFILE to which to write.
560  * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
561  * interpret the variable arguments received and format the data.
562  * @param ap The argument list to use.
563  * @return The number of Unicode characters written to <TT>f</TT>.
564  * @see u_fprintf_u
565  * @stable ICU 3.0
566  */
567 U_CAPI int32_t U_EXPORT2
568 u_vfprintf_u(UFILE      *f,
569             const UChar *patternSpecification,
570             va_list     ap);
571 #endif
572 /**
573  * Write a Unicode to a UFILE.  The null (U+0000) terminated UChar*
574  * <TT>s</TT> will be written to <TT>f</TT>, excluding the NULL terminator.
575  * A newline will be added to <TT>f</TT>.
576  * @param s The UChar* to write.
577  * @param f The UFILE to which to write.
578  * @return A non-negative number if successful, EOF otherwise.
579  * @see u_file_write
580  * @stable ICU 3.0
581  */
582 U_CAPI int32_t U_EXPORT2
583 u_fputs(const UChar *s,
584         UFILE       *f);
585 
586 /**
587  * Write a UChar to a UFILE.
588  * @param uc The UChar to write.
589  * @param f The UFILE to which to write.
590  * @return The character written if successful, EOF otherwise.
591  * @stable ICU 3.0
592  */
593 U_CAPI UChar32 U_EXPORT2
594 u_fputc(UChar32  uc,
595         UFILE  *f);
596 
597 /**
598  * Write Unicode to a UFILE.
599  * The ustring passed in will be converted to the UFILE's underlying
600  * codepage before it is written.
601  * @param ustring A pointer to the Unicode data to write.
602  * @param count The number of Unicode characters to write
603  * @param f The UFILE to which to write.
604  * @return The number of Unicode characters written.
605  * @see u_fputs
606  * @stable ICU 3.0
607  */
608 U_CAPI int32_t U_EXPORT2
609 u_file_write(const UChar    *ustring,
610              int32_t        count,
611              UFILE          *f);
612 
613 
614 /* Input functions */
615 #if !UCONFIG_NO_FORMATTING
616 
617 /**
618  * Read formatted data from a UFILE.
619  * @param f The UFILE from which to read.
620  * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
621  * interpret the variable arguments received and parse the data.
622  * @return The number of items successfully converted and assigned, or EOF
623  * if an error occurred.
624  * @stable ICU 3.0
625  */
626 U_CAPI int32_t U_EXPORT2
627 u_fscanf(UFILE      *f,
628          const char *patternSpecification,
629          ... );
630 
631 /**
632  * Read formatted data from a UFILE.
633  * This is identical to <TT>u_fscanf</TT>, except that it will
634  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
635  * @param f The UFILE from which to read.
636  * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
637  * interpret the variable arguments received and parse the data.
638  * @param ap The argument list to use.
639  * @return The number of items successfully converted and assigned, or EOF
640  * if an error occurred.
641  * @see u_fscanf
642  * @stable ICU 3.0
643  */
644 U_CAPI int32_t U_EXPORT2
645 u_vfscanf(UFILE         *f,
646           const char    *patternSpecification,
647           va_list        ap);
648 
649 /**
650  * Read formatted data from a UFILE.
651  * @param f The UFILE from which to read.
652  * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
653  * interpret the variable arguments received and parse the data.
654  * @return The number of items successfully converted and assigned, or EOF
655  * if an error occurred.
656  * @stable ICU 3.0
657  */
658 U_CAPI int32_t U_EXPORT2
659 u_fscanf_u(UFILE        *f,
660            const UChar  *patternSpecification,
661            ... );
662 
663 /**
664  * Read formatted data from a UFILE.
665  * This is identical to <TT>u_fscanf_u</TT>, except that it will
666  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
667  * @param f The UFILE from which to read.
668  * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
669  * interpret the variable arguments received and parse the data.
670  * @param ap The argument list to use.
671  * @return The number of items successfully converted and assigned, or EOF
672  * if an error occurred.
673  * @see u_fscanf_u
674  * @stable ICU 3.0
675  */
676 U_CAPI int32_t U_EXPORT2
677 u_vfscanf_u(UFILE       *f,
678             const UChar *patternSpecification,
679             va_list      ap);
680 #endif
681 
682 /**
683  * Read one line of text into a UChar* string from a UFILE. The newline
684  * at the end of the line is read into the string. The string is always
685  * null terminated
686  * @param f The UFILE from which to read.
687  * @param n The maximum number of characters - 1 to read.
688  * @param s The UChar* to receive the read data.  Characters will be
689  * stored successively in <TT>s</TT> until a newline or EOF is
690  * reached. A null character (U+0000) will be appended to <TT>s</TT>.
691  * @return A pointer to <TT>s</TT>, or NULL if no characters were available.
692  * @stable ICU 3.0
693  */
694 U_CAPI UChar* U_EXPORT2
695 u_fgets(UChar  *s,
696         int32_t n,
697         UFILE  *f);
698 
699 /**
700  * Read a UChar from a UFILE. It is recommended that <TT>u_fgetcx</TT>
701  * used instead for proper parsing functions, but sometimes reading
702  * code units is needed instead of codepoints.
703  *
704  * @param f The UFILE from which to read.
705  * @return The UChar value read, or U+FFFF if no character was available.
706  * @stable ICU 3.0
707  */
708 U_CAPI UChar U_EXPORT2
709 u_fgetc(UFILE   *f);
710 
711 /**
712  * Read a UChar32 from a UFILE.
713  *
714  * @param f The UFILE from which to read.
715  * @return The UChar32 value read, or U_EOF if no character was
716  * available, or U+FFFFFFFF if an ill-formed character was
717  * encountered.
718  * @see u_unescape()
719  * @stable ICU 3.0
720  */
721 U_CAPI UChar32 U_EXPORT2
722 u_fgetcx(UFILE  *f);
723 
724 /**
725  * Unget a UChar from a UFILE.
726  * If this function is not the first to operate on <TT>f</TT> after a call
727  * to <TT>u_fgetc</TT>, the results are undefined.
728  * If this function is passed a character that was not recieved from the
729  * previous <TT>u_fgetc</TT> or <TT>u_fgetcx</TT> call, the results are undefined.
730  * @param c The UChar to put back on the stream.
731  * @param f The UFILE to receive <TT>c</TT>.
732  * @return The UChar32 value put back if successful, U_EOF otherwise.
733  * @stable ICU 3.0
734  */
735 U_CAPI UChar32 U_EXPORT2
736 u_fungetc(UChar32   c,
737       UFILE        *f);
738 
739 /**
740  * Read Unicode from a UFILE.
741  * Bytes will be converted from the UFILE's underlying codepage, with
742  * subsequent conversion to Unicode. The data will not be NULL terminated.
743  * @param chars A pointer to receive the Unicode data.
744  * @param count The number of Unicode characters to read.
745  * @param f The UFILE from which to read.
746  * @return The number of Unicode characters read.
747  * @stable ICU 3.0
748  */
749 U_CAPI int32_t U_EXPORT2
750 u_file_read(UChar        *chars,
751         int32_t        count,
752         UFILE         *f);
753 
754 #if !UCONFIG_NO_TRANSLITERATION
755 
756 /**
757  * Set a transliterator on the UFILE. The transliterator will be owned by the
758  * UFILE.
759  * @param file The UFILE to set transliteration on
760  * @param adopt The UTransliterator to set. Can be NULL, which will
761  * mean that no transliteration is used.
762  * @param direction either U_READ, U_WRITE, or U_READWRITE - sets
763  *  which direction the transliterator is to be applied to. If
764  * U_READWRITE, the "Read" transliteration will be in the inverse
765  * direction.
766  * @param status ICU error code.
767  * @return The previously set transliterator, owned by the
768  * caller. If U_READWRITE is specified, only the WRITE transliterator
769  * is returned. In most cases, the caller should call utrans_close()
770  * on the result of this function.
771  * @stable ICU 3.0
772  */
773 U_CAPI UTransliterator* U_EXPORT2
774 u_fsettransliterator(UFILE *file, UFileDirection direction,
775                      UTransliterator *adopt, UErrorCode *status);
776 
777 #endif
778 
779 
780 /* Output string functions */
781 #if !UCONFIG_NO_FORMATTING
782 
783 
784 /**
785  * Write formatted data to a Unicode string.
786  *
787  * @param buffer The Unicode String to which to write.
788  * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
789  * interpret the variable arguments received and format the data.
790  * @return The number of Unicode code units written to <TT>buffer</TT>. This
791  * does not include the terminating null character.
792  * @stable ICU 3.0
793  */
794 U_CAPI int32_t U_EXPORT2
795 u_sprintf(UChar       *buffer,
796         const char    *patternSpecification,
797         ... );
798 
799 /**
800  * Write formatted data to a Unicode string. When the number of code units
801  * required to store the data exceeds <TT>count</TT>, then <TT>count</TT> code
802  * units of data are stored in <TT>buffer</TT> and a negative value is
803  * returned. When the number of code units required to store the data equals
804  * <TT>count</TT>, the string is not null terminated and <TT>count</TT> is
805  * returned.
806  *
807  * @param buffer The Unicode String to which to write.
808  * @param count The number of code units to read.
809  * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
810  * interpret the variable arguments received and format the data.
811  * @return The number of Unicode characters that would have been written to
812  * <TT>buffer</TT> had count been sufficiently large. This does not include
813  * the terminating null character.
814  * @stable ICU 3.0
815  */
816 U_CAPI int32_t U_EXPORT2
817 u_snprintf(UChar      *buffer,
818         int32_t       count,
819         const char    *patternSpecification,
820         ... );
821 
822 /**
823  * Write formatted data to a Unicode string.
824  * This is identical to <TT>u_sprintf</TT>, except that it will
825  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
826  *
827  * @param buffer The Unicode string to which to write.
828  * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
829  * interpret the variable arguments received and format the data.
830  * @param ap The argument list to use.
831  * @return The number of Unicode characters written to <TT>buffer</TT>.
832  * @see u_sprintf
833  * @stable ICU 3.0
834  */
835 U_CAPI int32_t U_EXPORT2
836 u_vsprintf(UChar      *buffer,
837         const char    *patternSpecification,
838         va_list        ap);
839 
840 /**
841  * Write formatted data to a Unicode string.
842  * This is identical to <TT>u_snprintf</TT>, except that it will
843  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.<br><br>
844  * When the number of code units required to store the data exceeds
845  * <TT>count</TT>, then <TT>count</TT> code units of data are stored in
846  * <TT>buffer</TT> and a negative value is returned. When the number of code
847  * units required to store the data equals <TT>count</TT>, the string is not
848  * null terminated and <TT>count</TT> is returned.
849  *
850  * @param buffer The Unicode string to which to write.
851  * @param count The number of code units to read.
852  * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
853  * interpret the variable arguments received and format the data.
854  * @param ap The argument list to use.
855  * @return The number of Unicode characters that would have been written to
856  * <TT>buffer</TT> had count been sufficiently large.
857  * @see u_sprintf
858  * @stable ICU 3.0
859  */
860 U_CAPI int32_t U_EXPORT2
861 u_vsnprintf(UChar     *buffer,
862         int32_t       count,
863         const char    *patternSpecification,
864         va_list        ap);
865 
866 /**
867  * Write formatted data to a Unicode string.
868  *
869  * @param buffer The Unicode string to which to write.
870  * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
871  * interpret the variable arguments received and format the data.
872  * @return The number of Unicode characters written to <TT>buffer</TT>.
873  * @stable ICU 3.0
874  */
875 U_CAPI int32_t U_EXPORT2
876 u_sprintf_u(UChar      *buffer,
877         const UChar    *patternSpecification,
878         ... );
879 
880 /**
881  * Write formatted data to a Unicode string. When the number of code units
882  * required to store the data exceeds <TT>count</TT>, then <TT>count</TT> code
883  * units of data are stored in <TT>buffer</TT> and a negative value is
884  * returned. When the number of code units required to store the data equals
885  * <TT>count</TT>, the string is not null terminated and <TT>count</TT> is
886  * returned.
887  *
888  * @param buffer The Unicode string to which to write.
889  * @param count The number of code units to read.
890  * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
891  * interpret the variable arguments received and format the data.
892  * @return The number of Unicode characters that would have been written to
893  * <TT>buffer</TT> had count been sufficiently large.
894  * @stable ICU 3.0
895  */
896 U_CAPI int32_t U_EXPORT2
897 u_snprintf_u(UChar     *buffer,
898         int32_t        count,
899         const UChar    *patternSpecification,
900         ... );
901 
902 /**
903  * Write formatted data to a Unicode string.
904  * This is identical to <TT>u_sprintf_u</TT>, except that it will
905  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
906  *
907  * @param buffer The Unicode string to which to write.
908  * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
909  * interpret the variable arguments received and format the data.
910  * @param ap The argument list to use.
911  * @return The number of Unicode characters written to <TT>f</TT>.
912  * @see u_sprintf_u
913  * @stable ICU 3.0
914  */
915 U_CAPI int32_t U_EXPORT2
916 u_vsprintf_u(UChar     *buffer,
917         const UChar    *patternSpecification,
918         va_list        ap);
919 
920 /**
921  * Write formatted data to a Unicode string.
922  * This is identical to <TT>u_snprintf_u</TT>, except that it will
923  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
924  * When the number of code units required to store the data exceeds
925  * <TT>count</TT>, then <TT>count</TT> code units of data are stored in
926  * <TT>buffer</TT> and a negative value is returned. When the number of code
927  * units required to store the data equals <TT>count</TT>, the string is not
928  * null terminated and <TT>count</TT> is returned.
929  *
930  * @param buffer The Unicode string to which to write.
931  * @param count The number of code units to read.
932  * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
933  * interpret the variable arguments received and format the data.
934  * @param ap The argument list to use.
935  * @return The number of Unicode characters that would have been written to
936  * <TT>f</TT> had count been sufficiently large.
937  * @see u_sprintf_u
938  * @stable ICU 3.0
939  */
940 U_CAPI int32_t U_EXPORT2
941 u_vsnprintf_u(UChar *buffer,
942         int32_t         count,
943         const UChar     *patternSpecification,
944         va_list         ap);
945 
946 /* Input string functions */
947 
948 /**
949  * Read formatted data from a Unicode string.
950  *
951  * @param buffer The Unicode string from which to read.
952  * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will
953  * interpret the variable arguments received and parse the data.
954  * @return The number of items successfully converted and assigned, or EOF
955  * if an error occurred.
956  * @stable ICU 3.0
957  */
958 U_CAPI int32_t U_EXPORT2
959 u_sscanf(const UChar   *buffer,
960         const char     *patternSpecification,
961         ... );
962 
963 /**
964  * Read formatted data from a Unicode string.
965  * This is identical to <TT>u_sscanf</TT>, except that it will
966  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
967  *
968  * @param buffer The Unicode string from which to read.
969  * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will
970  * interpret the variable arguments received and parse the data.
971  * @param ap The argument list to use.
972  * @return The number of items successfully converted and assigned, or EOF
973  * if an error occurred.
974  * @see u_sscanf
975  * @stable ICU 3.0
976  */
977 U_CAPI int32_t U_EXPORT2
978 u_vsscanf(const UChar  *buffer,
979         const char     *patternSpecification,
980         va_list        ap);
981 
982 /**
983  * Read formatted data from a Unicode string.
984  *
985  * @param buffer The Unicode string from which to read.
986  * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will
987  * interpret the variable arguments received and parse the data.
988  * @return The number of items successfully converted and assigned, or EOF
989  * if an error occurred.
990  * @stable ICU 3.0
991  */
992 U_CAPI int32_t U_EXPORT2
993 u_sscanf_u(const UChar  *buffer,
994         const UChar     *patternSpecification,
995         ... );
996 
997 /**
998  * Read formatted data from a Unicode string.
999  * This is identical to <TT>u_sscanf_u</TT>, except that it will
1000  * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
1001  *
1002  * @param buffer The Unicode string from which to read.
1003  * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will
1004  * interpret the variable arguments received and parse the data.
1005  * @param ap The argument list to use.
1006  * @return The number of items successfully converted and assigned, or EOF
1007  * if an error occurred.
1008  * @see u_sscanf_u
1009  * @stable ICU 3.0
1010  */
1011 U_CAPI int32_t U_EXPORT2
1012 u_vsscanf_u(const UChar *buffer,
1013         const UChar     *patternSpecification,
1014         va_list         ap);
1015 
1016 
1017 #endif
1018 #endif
1019 #endif
1020 
1021 
1022