ICU 57.1  57.1
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) */
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 
342 
353 
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 
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
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
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 
UFILE * u_fopen(const char *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE.
int32_t u_fputs(const UChar *s, UFILE *f)
Write a Unicode to a UFILE.
UChar u_fgetc(UFILE *f)
Read a UChar from a UFILE.
void * UTransliterator
An opaque transliterator for use in C.
Definition: utrans.h:68
int32_t u_vsscanf(const UChar *buffer, const char *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
int32_t u_fscanf_u(UFILE *f, const UChar *patternSpecification,...)
Read formatted data from a UFILE.
int32_t u_printf(const char *patternSpecification,...)
Write formatted data to stdout.
UTransliterator * u_fsettransliterator(UFILE *file, UFileDirection direction, UTransliterator *adopt, UErrorCode *status)
Set a transliterator on the UFILE.
void u_fflush(UFILE *file)
Flush output of a UFILE.
int32_t u_file_write(const UChar *ustring, int32_t count, UFILE *f)
Write Unicode to a UFILE.
struct UFILE UFILE
Forward declaration of a Unicode-aware file.
Definition: ustdio.h:210
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:217
int32_t u_fscanf(UFILE *f, const char *patternSpecification,...)
Read formatted data from a UFILE.
int32_t u_vfprintf(UFILE *f, const char *patternSpecification, va_list ap)
Write formatted data to a UFILE.
int32_t u_file_read(UChar *chars, int32_t count, UFILE *f)
Read Unicode from a UFILE.
void u_frewind(UFILE *file)
Rewind the file pointer to the beginning of the file.
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...
UFILE * u_get_stdout(void)
Get a UFILE for stdout.
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:129
UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
"Smart pointer" definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:536
void * UNumberFormat
A number formatter.
Definition: unum.h:134
int32_t u_vfprintf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Write formatted data to a UFILE.
int32_t u_sprintf(UChar *buffer, const char *patternSpecification,...)
Write formatted data to a Unicode string.
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
int32_t u_fsetcodepage(const char *codepage, UFILE *file)
Set the codepage in which data will be written to and read from the UFILE.
int32_t u_vsnprintf_u(UChar *buffer, int32_t count, 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:332
int32_t u_vsprintf_u(UChar *buffer, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
UConverter * u_fgetConverter(UFILE *f)
Returns an alias to the converter being used for this file.
UBool u_feof(UFILE *f)
Tests if the UFILE is at the end of the file stream.
C API: Transliterator.
int32_t u_fsetlocale(UFILE *file, const char *locale)
Set the locale whose conventions will be used to format and parse output.
UFILE * u_fstropen(UChar *stringBuf, int32_t capacity, const char *locale)
Create a UFILE that can be used for localized formatting or parsing.
int32_t u_vsnprintf(UChar *buffer, int32_t count, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
int32_t u_vsprintf(UChar *buffer, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
int32_t u_sprintf_u(UChar *buffer, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
int32_t u_vfscanf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Read formatted data from a UFILE.
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
int32_t u_sscanf(const UChar *buffer, const char *patternSpecification,...)
Read formatted data from a Unicode string.
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:130
const char * u_fgetcodepage(UFILE *file)
Get the codepage in which data is written to and read from the UFILE.
FILE * u_fgetfile(UFILE *f)
Get the FILE* associated with a UFILE.
int32_t u_vfscanf(UFILE *f, const char *patternSpecification, va_list ap)
Read formatted data from a UFILE.
int32_t u_fprintf_u(UFILE *f, const UChar *patternSpecification,...)
Write formatted data to a UFILE.
UChar32 u_fungetc(UChar32 c, UFILE *f)
Unget a UChar from a UFILE.
UChar32 u_fgetcx(UFILE *f)
Read a UChar32 from a UFILE.
struct UConverter UConverter
Definition: ucnv_err.h:94
"Smart pointer" class, closes a UFILE via u_fclose().
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:476
int32_t u_printf_u(const UChar *patternSpecification,...)
Write formatted data to stdout.
UFILE * u_finit(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
int32_t u_fprintf(UFILE *f, const char *patternSpecification,...)
Write formatted data to a UFILE.
Basic definitions for ICU, for both C and C++ APIs.
int32_t u_snprintf(UChar *buffer, int32_t count, const char *patternSpecification,...)
Write formatted data to a Unicode string.
int32_t u_snprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
const UNumberFormat * u_fgetNumberFormat(UFILE *f)
Returns an alias to the number formatter being used for this file.
void u_fclose(UFILE *file)
Close a UFILE.
int32_t u_vsscanf_u(const UChar *buffer, const UChar *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
const char * u_fgetlocale(UFILE *file)
Get the locale whose conventions are used to format and parse output.
UChar * u_fgets(UChar *s, int32_t n, UFILE *f)
Read one line of text into a UChar* string from a UFILE.
int32_t u_sscanf_u(const UChar *buffer, const UChar *patternSpecification,...)
Read formatted data from a Unicode string.
C API: Character conversion.
UFILE * u_fadopt(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:109
int8_t UBool
The ICU boolean type.
Definition: umachine.h:234
C API: NumberFormat.