ICU 69.1  69.1
ustdio.h
Go to the documentation of this file.
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 boundaries
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 
212 #define U_EOF 0xFFFF
213 
215 typedef struct UFILE UFILE;
216 
222 typedef enum {
223  U_READ = 1,
224  U_WRITE = 2,
225  U_READWRITE =3 /* == (U_READ | U_WRITE) */
227 
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 
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 
290 U_CAPI UFILE* U_EXPORT2
291 u_finit(FILE *f,
292  const char *locale,
293  const char *codepage);
294 
311 U_CAPI UFILE* U_EXPORT2
312 u_fadopt(FILE *f,
313  const char *locale,
314  const char *codepage);
315 
330 U_CAPI UFILE* U_EXPORT2
331 u_fstropen(UChar *stringBuf,
332  int32_t capacity,
333  const char *locale);
334 
341 U_CAPI void U_EXPORT2
342 u_fclose(UFILE *file);
343 
344 #if U_SHOW_CPLUSPLUS_API
345 
346 U_NAMESPACE_BEGIN
347 
358 
359 U_NAMESPACE_END
360 
361 #endif
362 
371 U_CAPI UBool U_EXPORT2
372 u_feof(UFILE *f);
373 
384 U_CAPI void U_EXPORT2
385 u_fflush(UFILE *file);
386 
392 U_CAPI void
393 u_frewind(UFILE *file);
394 
401 U_CAPI FILE* U_EXPORT2
402 u_fgetfile(UFILE *f);
403 
404 #if !UCONFIG_NO_FORMATTING
405 
414 U_CAPI const char* U_EXPORT2
415 u_fgetlocale(UFILE *file);
416 
425 U_CAPI int32_t U_EXPORT2
426 u_fsetlocale(UFILE *file,
427  const char *locale);
428 
429 #endif
430 
440 U_CAPI const char* U_EXPORT2
441 u_fgetcodepage(UFILE *file);
442 
458 U_CAPI int32_t U_EXPORT2
459 u_fsetcodepage(const char *codepage,
460  UFILE *file);
461 
462 
469 U_CAPI UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
470 
471 #if !UCONFIG_NO_FORMATTING
472 
478  U_CAPI const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f);
479 
480 /* Output functions */
481 
489 U_CAPI int32_t U_EXPORT2
490 u_printf(const char *patternSpecification,
491  ... );
492 
501 U_CAPI int32_t U_EXPORT2
502 u_fprintf(UFILE *f,
503  const char *patternSpecification,
504  ... );
505 
518 U_CAPI int32_t U_EXPORT2
519 u_vfprintf(UFILE *f,
520  const char *patternSpecification,
521  va_list ap);
522 
530 U_CAPI int32_t U_EXPORT2
531 u_printf_u(const UChar *patternSpecification,
532  ... );
533 
539 U_CAPI UFILE * U_EXPORT2
540 u_get_stdout(void);
541 
550 U_CAPI int32_t U_EXPORT2
551 u_fprintf_u(UFILE *f,
552  const UChar *patternSpecification,
553  ... );
554 
567 U_CAPI int32_t U_EXPORT2
569  const UChar *patternSpecification,
570  va_list ap);
571 #endif
572 
582 U_CAPI int32_t U_EXPORT2
583 u_fputs(const UChar *s,
584  UFILE *f);
585 
593 U_CAPI UChar32 U_EXPORT2
594 u_fputc(UChar32 uc,
595  UFILE *f);
596 
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 
626 U_CAPI int32_t U_EXPORT2
627 u_fscanf(UFILE *f,
628  const char *patternSpecification,
629  ... );
630 
644 U_CAPI int32_t U_EXPORT2
645 u_vfscanf(UFILE *f,
646  const char *patternSpecification,
647  va_list ap);
648 
658 U_CAPI int32_t U_EXPORT2
659 u_fscanf_u(UFILE *f,
660  const UChar *patternSpecification,
661  ... );
662 
676 U_CAPI int32_t U_EXPORT2
677 u_vfscanf_u(UFILE *f,
678  const UChar *patternSpecification,
679  va_list ap);
680 #endif
681 
694 U_CAPI UChar* U_EXPORT2
695 u_fgets(UChar *s,
696  int32_t n,
697  UFILE *f);
698 
708 U_CAPI UChar U_EXPORT2
709 u_fgetc(UFILE *f);
710 
721 U_CAPI UChar32 U_EXPORT2
722 u_fgetcx(UFILE *f);
723 
735 U_CAPI UChar32 U_EXPORT2
737  UFILE *f);
738 
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 
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 
794 U_CAPI int32_t U_EXPORT2
795 u_sprintf(UChar *buffer,
796  const char *patternSpecification,
797  ... );
798 
816 U_CAPI int32_t U_EXPORT2
817 u_snprintf(UChar *buffer,
818  int32_t count,
819  const char *patternSpecification,
820  ... );
821 
835 U_CAPI int32_t U_EXPORT2
836 u_vsprintf(UChar *buffer,
837  const char *patternSpecification,
838  va_list ap);
839 
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 
875 U_CAPI int32_t U_EXPORT2
876 u_sprintf_u(UChar *buffer,
877  const UChar *patternSpecification,
878  ... );
879 
896 U_CAPI int32_t U_EXPORT2
897 u_snprintf_u(UChar *buffer,
898  int32_t count,
899  const UChar *patternSpecification,
900  ... );
901 
915 U_CAPI int32_t U_EXPORT2
916 u_vsprintf_u(UChar *buffer,
917  const UChar *patternSpecification,
918  va_list ap);
919 
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 
958 U_CAPI int32_t U_EXPORT2
959 u_sscanf(const UChar *buffer,
960  const char *patternSpecification,
961  ... );
962 
977 U_CAPI int32_t U_EXPORT2
978 u_vsscanf(const UChar *buffer,
979  const char *patternSpecification,
980  va_list ap);
981 
992 U_CAPI int32_t U_EXPORT2
993 u_sscanf_u(const UChar *buffer,
994  const UChar *patternSpecification,
995  ... );
996 
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 
U_CAPI const UNumberFormat * u_fgetNumberFormat(UFILE *f)
Returns an alias to the number formatter being used for this file.
U_CAPI int32_t u_sprintf(UChar *buffer, const char *patternSpecification,...)
Write formatted data to a Unicode string.
void * UTransliterator
An opaque transliterator for use in C.
Definition: utrans.h:73
U_CAPI int32_t u_fputs(const UChar *s, UFILE *f)
Write a Unicode to a UFILE.
#define U_CAPI
This is used to declare a function as a public ICU C API.
Definition: umachine.h:110
U_CAPI UFILE * u_fopen(const char *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE.
struct UFILE UFILE
Forward declaration of a Unicode-aware file.
Definition: ustdio.h:215
U_CAPI UTransliterator * u_fsettransliterator(UFILE *file, UFileDirection direction, UTransliterator *adopt, UErrorCode *status)
Set a transliterator on the UFILE.
U_CAPI UFILE * u_get_stdout(void)
Get a UFILE for stdout.
U_CAPI UFILE * u_fopen_u(const UChar *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE with a UChar* filename A UFILE is a wrapper around a FILE* that is locale and codepage a...
U_CAPI const char * u_fgetlocale(UFILE *file)
Get the locale whose conventions are used to format and parse output.
U_CAPI UFILE * u_finit(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
U_CAPI FILE * u_fgetfile(UFILE *f)
Get the FILE* associated with a UFILE.
U_CAPI int32_t u_fscanf(UFILE *f, const char *patternSpecification,...)
Read formatted data from a UFILE.
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:222
U_CAPI int32_t u_vsscanf(const UChar *buffer, const char *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
U_CAPI int32_t u_vfprintf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Write formatted data to a UFILE.
U_CAPI UConverter * u_fgetConverter(UFILE *f)
Returns an alias to the converter being used for this file.
U_CAPI UChar u_fgetc(UFILE *f)
Read a UChar from a UFILE.
U_CAPI UChar32 u_fgetcx(UFILE *f)
Read a UChar32 from a UFILE.
U_CAPI int32_t u_file_read(UChar *chars, int32_t count, UFILE *f)
Read Unicode from a UFILE.
U_CAPI int32_t u_vsprintf(UChar *buffer, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
U_CAPI int32_t u_snprintf(UChar *buffer, int32_t count, const char *patternSpecification,...)
Write formatted data to a Unicode string.
U_CAPI int32_t u_snprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
U_CAPI UBool u_feof(UFILE *f)
Tests if the UFILE is at the end of the file stream.
U_CAPI const char * u_fgetcodepage(UFILE *file)
Get the codepage in which data is written to and read from the UFILE.
U_CAPI UChar * u_fgets(UChar *s, int32_t n, UFILE *f)
Read one line of text into a UChar* string from a UFILE.
U_CAPI UChar32 u_fungetc(UChar32 c, UFILE *f)
Unget a UChar from a UFILE.
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
&quot;Smart pointer&quot; definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:550
void * UNumberFormat
A number formatter.
Definition: unum.h:144
U_CAPI int32_t u_sprintf_u(UChar *buffer, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
C++ API: &quot;Smart pointers&quot; for use with and in ICU4C C++ code.
U_CAPI int32_t u_printf_u(const UChar *patternSpecification,...)
Write formatted data to stdout.
U_CAPI int32_t u_vfscanf(UFILE *f, const char *patternSpecification, va_list ap)
Read formatted data from a UFILE.
U_CAPI int32_t u_vsprintf_u(UChar *buffer, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition: umachine.h:467
U_CAPI int32_t u_vfprintf(UFILE *f, const char *patternSpecification, va_list ap)
Write formatted data to a UFILE.
C API: Transliterator.
U_CAPI int32_t u_vfscanf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Read formatted data from a UFILE.
U_CAPI int32_t u_fprintf(UFILE *f, const char *patternSpecification,...)
Write formatted data to a UFILE.
U_CAPI int32_t u_fsetcodepage(const char *codepage, UFILE *file)
Set the codepage in which data will be written to and read from the UFILE.
U_CAPI UFILE * u_fadopt(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:418
struct UConverter UConverter
Definition: ucnv_err.h:96
&quot;Smart pointer&quot; class, closes a UFILE via u_fclose().
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
U_CAPI int32_t u_vsscanf_u(const UChar *buffer, const UChar *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
U_CAPI void u_frewind(UFILE *file)
Rewind the file pointer to the beginning of the file.
U_CAPI void u_fclose(UFILE *file)
Close a UFILE.
U_CAPI int32_t u_printf(const char *patternSpecification,...)
Write formatted data to stdout.
Basic definitions for ICU, for both C and C++ APIs.
U_CAPI int32_t u_fprintf_u(UFILE *f, const UChar *patternSpecification,...)
Write formatted data to a UFILE.
U_CAPI int32_t u_fscanf_u(UFILE *f, const UChar *patternSpecification,...)
Read formatted data from a UFILE.
U_CAPI UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
U_CAPI int32_t u_sscanf_u(const UChar *buffer, const UChar *patternSpecification,...)
Read formatted data from a Unicode string.
U_CAPI void u_fflush(UFILE *file)
Flush output of a UFILE.
U_CAPI int32_t u_vsnprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
U_CAPI int32_t u_sscanf(const UChar *buffer, const char *patternSpecification,...)
Read formatted data from a Unicode string.
U_CAPI UFILE * u_fstropen(UChar *stringBuf, int32_t capacity, const char *locale)
Create a UFILE that can be used for localized formatting or parsing.
C API: Character conversion.
U_CAPI int32_t u_vsnprintf(UChar *buffer, int32_t count, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
U_CAPI int32_t u_fsetlocale(UFILE *file, const char *locale)
Set the locale whose conventions will be used to format and parse output.
U_CAPI int32_t u_file_write(const UChar *ustring, int32_t count, UFILE *f)
Write Unicode to a UFILE.
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
C API: Compatibility APIs for number formatting.