ICU 56.1: ustdio.h Source File

ICU 56.1 56.1

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files

- File List
- Globals

ustdio.h
Go to the documentation of this file.
1 /*
2 ******************************************************************************
3 *
4 * Copyright (C) 1998-2015, International Business Machines
5 * Corporation and others. All Rights Reserved.
6 *
7 ******************************************************************************
8 *
9 * File ustdio.h
10 *
11 * Modification History:
12 *
13 * Date Name Description
14 * 10/16/98 stephen Creation.
15 * 11/06/98 stephen Modified per code review.
16 * 03/12/99 stephen Modified for new C API.
17 * 07/19/99 stephen Minor doc update.
18 * 02/01/01 george Added sprintf & sscanf with all of its variants
19 ******************************************************************************
20 */
21
22 #ifndef USTDIO_H
23 #define USTDIO_H
24
25 #include <stdio.h>
26 #include <stdarg.h>
27
28 #include "unicode/utypes.h"
29 #include "unicode/ucnv.h"
30 #include "unicode/utrans.h"
31 #include "unicode/localpointer.h"
32 #include "unicode/unum.h"
33
34 #if !UCONFIG_NO_CONVERSION
35
36 /*
37 TODO
38 The following is a small list as to what is currently wrong/suggestions for
39 ustdio.
40
41 * Make sure that * in the scanf format specification works for all formats.
42 * Each UFILE takes up at least 2KB.
43 Look into adding setvbuf() for configurable buffers.
44 * This library does buffering. The OS should do this for us already. Check on
45 this, and remove it from this library, if this is the case. Double buffering
46 wastes a lot of time and space.
47 * Test stdin and stdout with the u_f* functions
48 * Testing should be done for reading and writing multi-byte encodings,
49 and make sure that a character that is contained across buffer boundries
50 works even for incomplete characters.
51 * Make sure that the last character is flushed when the file/string is closed.
52 * snprintf should follow the C99 standard for the return value, which is
53 return the number of characters (excluding the trailing '\0')
54 which would have been written to the destination string regardless
55 of available space. This is like pre-flighting.
56 * Everything that uses %s should do what operator>> does for UnicodeString.
57 It should convert one byte at a time, and once a character is
58 converted then check to see if it's whitespace or in the scanset.
59 If it's whitespace or in the scanset, put all the bytes back (do nothing
60 for sprintf/sscanf).
61 * If bad string data is encountered, make sure that the function fails
62 without memory leaks and the unconvertable characters are valid
63 substitution or are escaped characters.
64 * u_fungetc() can't unget a character when it's at the beginning of the
65 internal conversion buffer. For example, read the buffer size # of
66 characters, and then ungetc to get the previous character that was
67 at the end of the last buffer.
68 * u_fflush() and u_fclose should return an int32_t like C99 functions.
69 0 is returned if the operation was successful and EOF otherwise.
70 * u_fsettransliterator does not support U_READ side of transliteration.
71 * The format specifier should limit the size of a format or honor it in
72 order to prevent buffer overruns. (e.g. %256.256d).
73 * u_fread and u_fwrite don't exist. They're needed for reading and writing
74 data structures without any conversion.
75 * u_file_read and u_file_write are used for writing strings. u_fgets and
76 u_fputs or u_fread and u_fwrite should be used to do this.
77 * The width parameter for all scanf formats, including scanset, needs
78 better testing. This prevents buffer overflows.
79 * Figure out what is suppose to happen when a codepage is changed midstream.
80 Maybe a flush or a rewind are good enough.
81 * Make sure that a UFile opened with "rw" can be used after using
82 u_fflush with a u_frewind.
83 * scanf(%i) should detect what type of number to use.
84 * Add more testing of the alternate format, %#
85 * Look at newline handling of fputs/puts
86 * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
87 * Complete the file documentation with proper doxygen formatting.
88 See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
89 */
90
207 #define U_EOF 0xFFFF
208
210 typedef struct UFILE UFILE;
211
217 typedef enum {
218 U_READ = 1,
219 U_WRITE = 2,
220 U_READWRITE =3 /* == (U_READ | U_WRITE) */
221 } UFileDirection;
222
240 U_STABLE UFILE* U_EXPORT2
241 u_fopen(const char *filename,
242 const char *perm,
243 const char *locale,
244 const char *codepage);
245
263 U_STABLE UFILE* U_EXPORT2
264 u_fopen_u(const UChar *filename,
265 const char *perm,
266 const char *locale,
267 const char *codepage);
268
285 U_STABLE UFILE* U_EXPORT2
286 u_finit(FILE *f,
287 const char *locale,
288 const char *codepage);
289
306 U_STABLE UFILE* U_EXPORT2
307 u_fadopt(FILE *f,
308 const char *locale,
309 const char *codepage);
310
325 U_STABLE UFILE* U_EXPORT2
326 u_fstropen(UChar *stringBuf,
327 int32_t capacity,
328 const char *locale);
329
336 U_STABLE void U_EXPORT2
337 u_fclose(UFILE *file);
338
339 #if U_SHOW_CPLUSPLUS_API
340
341 U_NAMESPACE_BEGIN
342
352 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose);
353
354 U_NAMESPACE_END
355
356 #endif
357
366 U_STABLE UBool U_EXPORT2
367 u_feof(UFILE *f);
368
379 U_STABLE void U_EXPORT2
380 u_fflush(UFILE *file);
381
387 U_STABLE void
388 u_frewind(UFILE *file);
389
396 U_STABLE FILE* U_EXPORT2
397 u_fgetfile(UFILE *f);
398
399 #if !UCONFIG_NO_FORMATTING
400
409 U_STABLE const char* U_EXPORT2
410 u_fgetlocale(UFILE *file);
411
420 U_STABLE int32_t U_EXPORT2
421 u_fsetlocale(UFILE *file,
422 const char *locale);
423
424 #endif
425
435 U_STABLE const char* U_EXPORT2
436 u_fgetcodepage(UFILE *file);
437
453 U_STABLE int32_t U_EXPORT2
454 u_fsetcodepage(const char *codepage,
455 UFILE *file);
456
457
464 U_STABLE UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
465
466 #if !UCONFIG_NO_FORMATTING
467
473 U_STABLE const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f);
474
475 /* Output functions */
476
484 U_STABLE int32_t U_EXPORT2
485 u_printf(const char *patternSpecification,
486 ... );
487
496 U_STABLE int32_t U_EXPORT2
497 u_fprintf(UFILE *f,
498 const char *patternSpecification,
499 ... );
500
513 U_STABLE int32_t U_EXPORT2
514 u_vfprintf(UFILE *f,
515 const char *patternSpecification,
516 va_list ap);
517
525 U_STABLE int32_t U_EXPORT2
526 u_printf_u(const UChar *patternSpecification,
527 ... );
528
534 U_STABLE UFILE * U_EXPORT2
535 u_get_stdout(void);
536
545 U_STABLE int32_t U_EXPORT2
546 u_fprintf_u(UFILE *f,
547 const UChar *patternSpecification,
548 ... );
549
562 U_STABLE int32_t U_EXPORT2
563 u_vfprintf_u(UFILE *f,
564 const UChar *patternSpecification,
565 va_list ap);
566 #endif
567
577 U_STABLE int32_t U_EXPORT2
578 u_fputs(const UChar *s,
579 UFILE *f);
580
588 U_STABLE UChar32 U_EXPORT2
589 u_fputc(UChar32 uc,
590 UFILE *f);
591
603 U_STABLE int32_t U_EXPORT2
604 u_file_write(const UChar *ustring,
605 int32_t count,
606 UFILE *f);
607
608
609 /* Input functions */
610 #if !UCONFIG_NO_FORMATTING
611
621 U_STABLE int32_t U_EXPORT2
622 u_fscanf(UFILE *f,
623 const char *patternSpecification,
624 ... );
625
639 U_STABLE int32_t U_EXPORT2
640 u_vfscanf(UFILE *f,
641 const char *patternSpecification,
642 va_list ap);
643
653 U_STABLE int32_t U_EXPORT2
654 u_fscanf_u(UFILE *f,
655 const UChar *patternSpecification,
656 ... );
657
671 U_STABLE int32_t U_EXPORT2
672 u_vfscanf_u(UFILE *f,
673 const UChar *patternSpecification,
674 va_list ap);
675 #endif
676
689 U_STABLE UChar* U_EXPORT2
690 u_fgets(UChar *s,
691 int32_t n,
692 UFILE *f);
693
703 U_STABLE UChar U_EXPORT2
704 u_fgetc(UFILE *f);
705
716 U_STABLE UChar32 U_EXPORT2
717 u_fgetcx(UFILE *f);
718
730 U_STABLE UChar32 U_EXPORT2
731 u_fungetc(UChar32 c,
732 UFILE *f);
733
744 U_STABLE int32_t U_EXPORT2
745 u_file_read(UChar *chars,
746 int32_t count,
747 UFILE *f);
748
749 #if !UCONFIG_NO_TRANSLITERATION
750
768 U_STABLE UTransliterator* U_EXPORT2
769 u_fsettransliterator(UFILE *file, UFileDirection direction,
770 UTransliterator *adopt, UErrorCode *status);
771
772 #endif
773
774
775 /* Output string functions */
776 #if !UCONFIG_NO_FORMATTING
777
778
789 U_STABLE int32_t U_EXPORT2
790 u_sprintf(UChar *buffer,
791 const char *patternSpecification,
792 ... );
793
811 U_STABLE int32_t U_EXPORT2
812 u_snprintf(UChar *buffer,
813 int32_t count,
814 const char *patternSpecification,
815 ... );
816
830 U_STABLE int32_t U_EXPORT2
831 u_vsprintf(UChar *buffer,
832 const char *patternSpecification,
833 va_list ap);
834
855 U_STABLE int32_t U_EXPORT2
856 u_vsnprintf(UChar *buffer,
857 int32_t count,
858 const char *patternSpecification,
859 va_list ap);
860
870 U_STABLE int32_t U_EXPORT2
871 u_sprintf_u(UChar *buffer,
872 const UChar *patternSpecification,
873 ... );
874
891 U_STABLE int32_t U_EXPORT2
892 u_snprintf_u(UChar *buffer,
893 int32_t count,
894 const UChar *patternSpecification,
895 ... );
896
910 U_STABLE int32_t U_EXPORT2
911 u_vsprintf_u(UChar *buffer,
912 const UChar *patternSpecification,
913 va_list ap);
914
935 U_STABLE int32_t U_EXPORT2
936 u_vsnprintf_u(UChar *buffer,
937 int32_t count,
938 const UChar *patternSpecification,
939 va_list ap);
940
941 /* Input string functions */
942
953 U_STABLE int32_t U_EXPORT2
954 u_sscanf(const UChar *buffer,
955 const char *patternSpecification,
956 ... );
957
972 U_STABLE int32_t U_EXPORT2
973 u_vsscanf(const UChar *buffer,
974 const char *patternSpecification,
975 va_list ap);
976
987 U_STABLE int32_t U_EXPORT2
988 u_sscanf_u(const UChar *buffer,
989 const UChar *patternSpecification,
990 ... );
991
1006 U_STABLE int32_t U_EXPORT2
1007 u_vsscanf_u(const UChar *buffer,
1008 const UChar *patternSpecification,
1009 va_list ap);
1010
1011
1012 #endif
1013 #endif
1014 #endif
1015
1016
u_fopen
UFILE * u_fopen(const char *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE.
u_fputs
int32_t u_fputs(const UChar *s, UFILE *f)
Write a Unicode to a UFILE.
u_fgetc
UChar u_fgetc(UFILE *f)
Read a UChar from a UFILE.
UTransliterator
void * UTransliterator
An opaque transliterator for use in C.
Definition: utrans.h:68
u_vsscanf
int32_t u_vsscanf(const UChar *buffer, const char *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
u_fscanf_u
int32_t u_fscanf_u(UFILE *f, const UChar *patternSpecification,...)
Read formatted data from a UFILE.
u_printf
int32_t u_printf(const char *patternSpecification,...)
Write formatted data to stdout.
u_fsettransliterator
UTransliterator * u_fsettransliterator(UFILE *file, UFileDirection direction, UTransliterator *adopt, UErrorCode *status)
Set a transliterator on the UFILE.
u_fflush
void u_fflush(UFILE *file)
Flush output of a UFILE.
u_file_write
int32_t u_file_write(const UChar *ustring, int32_t count, UFILE *f)
Write Unicode to a UFILE.
UFILE
struct UFILE UFILE
Forward declaration of a Unicode-aware file.
Definition: ustdio.h:210
UFileDirection
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:217
u_fscanf
int32_t u_fscanf(UFILE *f, const char *patternSpecification,...)
Read formatted data from a UFILE.
u_vfprintf
int32_t u_vfprintf(UFILE *f, const char *patternSpecification, va_list ap)
Write formatted data to a UFILE.
u_file_read
int32_t u_file_read(UChar *chars, int32_t count, UFILE *f)
Read Unicode from a UFILE.
u_frewind
void u_frewind(UFILE *file)
Rewind the file pointer to the beginning of the file.
u_fopen_u
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_get_stdout
UFILE * u_get_stdout(void)
Get a UFILE for stdout.
U_NAMESPACE_BEGIN
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:129
u_fputc
UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
U_DEFINE_LOCAL_OPEN_POINTER
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
"Smart pointer" definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:535
UNumberFormat
void * UNumberFormat
A number formatter.
Definition: unum.h:134
u_vfprintf_u
int32_t u_vfprintf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Write formatted data to a UFILE.
u_sprintf
int32_t u_sprintf(UChar *buffer, const char *patternSpecification,...)
Write formatted data to a Unicode string.
localpointer.h
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
u_fsetcodepage
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_vsnprintf_u
int32_t u_vsnprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
UChar32
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition: umachine.h:332
u_vsprintf_u
int32_t u_vsprintf_u(UChar *buffer, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
u_fgetConverter
UConverter * u_fgetConverter(UFILE *f)
Returns an alias to the converter being used for this file.
u_feof
UBool u_feof(UFILE *f)
Tests if the UFILE is at the end of the file stream.
utrans.h
C API: Transliterator.
u_fsetlocale
int32_t u_fsetlocale(UFILE *file, const char *locale)
Set the locale whose conventions will be used to format and parse output.
u_fstropen
UFILE * u_fstropen(UChar *stringBuf, int32_t capacity, const char *locale)
Create a UFILE that can be used for localized formatting or parsing.
u_vsnprintf
int32_t u_vsnprintf(UChar *buffer, int32_t count, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
u_vsprintf
int32_t u_vsprintf(UChar *buffer, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
u_sprintf_u
int32_t u_sprintf_u(UChar *buffer, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
u_vfscanf_u
int32_t u_vfscanf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Read formatted data from a UFILE.
UChar
uint16_t UChar
Define UChar to be UCHAR_TYPE, if that is #defined (for example, to char16_t), or wchar_t if that is ...
Definition: umachine.h:312
u_sscanf
int32_t u_sscanf(const UChar *buffer, const char *patternSpecification,...)
Read formatted data from a Unicode string.
U_NAMESPACE_END
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:130
u_fgetcodepage
const char * u_fgetcodepage(UFILE *file)
Get the codepage in which data is written to and read from the UFILE.
u_fgetfile
FILE * u_fgetfile(UFILE *f)
Get the FILE* associated with a UFILE.
u_vfscanf
int32_t u_vfscanf(UFILE *f, const char *patternSpecification, va_list ap)
Read formatted data from a UFILE.
u_fprintf_u
int32_t u_fprintf_u(UFILE *f, const UChar *patternSpecification,...)
Write formatted data to a UFILE.
u_fungetc
UChar32 u_fungetc(UChar32 c, UFILE *f)
Unget a UChar from a UFILE.
u_fgetcx
UChar32 u_fgetcx(UFILE *f)
Read a UChar32 from a UFILE.
UConverter
struct UConverter UConverter
Definition: ucnv_err.h:94
LocalUFILEPointer
"Smart pointer" class, closes a UFILE via u_fclose().
UErrorCode
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:476
u_printf_u
int32_t u_printf_u(const UChar *patternSpecification,...)
Write formatted data to stdout.
u_finit
UFILE * u_finit(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
u_fprintf
int32_t u_fprintf(UFILE *f, const char *patternSpecification,...)
Write formatted data to a UFILE.
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
u_snprintf
int32_t u_snprintf(UChar *buffer, int32_t count, const char *patternSpecification,...)
Write formatted data to a Unicode string.
u_snprintf_u
int32_t u_snprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
u_fgetNumberFormat
const UNumberFormat * u_fgetNumberFormat(UFILE *f)
Returns an alias to the number formatter being used for this file.
u_fclose
void u_fclose(UFILE *file)
Close a UFILE.
u_vsscanf_u
int32_t u_vsscanf_u(const UChar *buffer, const UChar *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
u_fgetlocale
const char * u_fgetlocale(UFILE *file)
Get the locale whose conventions are used to format and parse output.
u_fgets
UChar * u_fgets(UChar *s, int32_t n, UFILE *f)
Read one line of text into a UChar* string from a UFILE.
u_sscanf_u
int32_t u_sscanf_u(const UChar *buffer, const UChar *patternSpecification,...)
Read formatted data from a Unicode string.
ucnv.h
C API: Character conversion.
u_fadopt
UFILE * u_fadopt(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
U_STABLE
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:109
UBool
int8_t UBool
The ICU boolean type.
Definition: umachine.h:234
unum.h
C API: NumberFormat.