ICU 53.1  53.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ustdio.h
Go to the documentation of this file.
1 /*
2 ******************************************************************************
3 *
4 * Copyright (C) 1998-2014, 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 /*
35  TODO
36  The following is a small list as to what is currently wrong/suggestions for
37  ustdio.
38 
39  * Make sure that * in the scanf format specification works for all formats.
40  * Each UFILE takes up at least 2KB.
41  Look into adding setvbuf() for configurable buffers.
42  * This library does buffering. The OS should do this for us already. Check on
43  this, and remove it from this library, if this is the case. Double buffering
44  wastes a lot of time and space.
45  * Test stdin and stdout with the u_f* functions
46  * Testing should be done for reading and writing multi-byte encodings,
47  and make sure that a character that is contained across buffer boundries
48  works even for incomplete characters.
49  * Make sure that the last character is flushed when the file/string is closed.
50  * snprintf should follow the C99 standard for the return value, which is
51  return the number of characters (excluding the trailing '\0')
52  which would have been written to the destination string regardless
53  of available space. This is like pre-flighting.
54  * Everything that uses %s should do what operator>> does for UnicodeString.
55  It should convert one byte at a time, and once a character is
56  converted then check to see if it's whitespace or in the scanset.
57  If it's whitespace or in the scanset, put all the bytes back (do nothing
58  for sprintf/sscanf).
59  * If bad string data is encountered, make sure that the function fails
60  without memory leaks and the unconvertable characters are valid
61  substitution or are escaped characters.
62  * u_fungetc() can't unget a character when it's at the beginning of the
63  internal conversion buffer. For example, read the buffer size # of
64  characters, and then ungetc to get the previous character that was
65  at the end of the last buffer.
66  * u_fflush() and u_fclose should return an int32_t like C99 functions.
67  0 is returned if the operation was successful and EOF otherwise.
68  * u_fsettransliterator does not support U_READ side of transliteration.
69  * The format specifier should limit the size of a format or honor it in
70  order to prevent buffer overruns. (e.g. %256.256d).
71  * u_fread and u_fwrite don't exist. They're needed for reading and writing
72  data structures without any conversion.
73  * u_file_read and u_file_write are used for writing strings. u_fgets and
74  u_fputs or u_fread and u_fwrite should be used to do this.
75  * The width parameter for all scanf formats, including scanset, needs
76  better testing. This prevents buffer overflows.
77  * Figure out what is suppose to happen when a codepage is changed midstream.
78  Maybe a flush or a rewind are good enough.
79  * Make sure that a UFile opened with "rw" can be used after using
80  u_fflush with a u_frewind.
81  * scanf(%i) should detect what type of number to use.
82  * Add more testing of the alternate format, %#
83  * Look at newline handling of fputs/puts
84  * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
85  * Complete the file documentation with proper doxygen formatting.
86  See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
87 */
88 
205 #define U_EOF 0xFFFF
206 
208 typedef struct UFILE UFILE;
209 
215 typedef enum {
216  U_READ = 1,
217  U_WRITE = 2,
218  U_READWRITE =3 /* == (U_READ | U_WRITE) */
220 
238 U_STABLE UFILE* U_EXPORT2
239 u_fopen(const char *filename,
240  const char *perm,
241  const char *locale,
242  const char *codepage);
243 
260 U_STABLE UFILE* U_EXPORT2
261 u_finit(FILE *f,
262  const char *locale,
263  const char *codepage);
264 
281 U_STABLE UFILE* U_EXPORT2
282 u_fadopt(FILE *f,
283  const char *locale,
284  const char *codepage);
285 
300 U_STABLE UFILE* U_EXPORT2
301 u_fstropen(UChar *stringBuf,
302  int32_t capacity,
303  const char *locale);
304 
311 U_STABLE void U_EXPORT2
312 u_fclose(UFILE *file);
313 
314 #if U_SHOW_CPLUSPLUS_API
315 
317 
328 
330 
331 #endif
332 
341 U_STABLE UBool U_EXPORT2
342 u_feof(UFILE *f);
343 
354 U_STABLE void U_EXPORT2
355 u_fflush(UFILE *file);
356 
362 U_STABLE void
363 u_frewind(UFILE *file);
364 
371 U_STABLE FILE* U_EXPORT2
372 u_fgetfile(UFILE *f);
373 
374 #if !UCONFIG_NO_FORMATTING
375 
384 U_STABLE const char* U_EXPORT2
385 u_fgetlocale(UFILE *file);
386 
395 U_STABLE int32_t U_EXPORT2
396 u_fsetlocale(UFILE *file,
397  const char *locale);
398 
399 #endif
400 
410 U_STABLE const char* U_EXPORT2
411 u_fgetcodepage(UFILE *file);
412 
428 U_STABLE int32_t U_EXPORT2
429 u_fsetcodepage(const char *codepage,
430  UFILE *file);
431 
432 
440 
441 #if !UCONFIG_NO_FORMATTING
442 
448  U_STABLE const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f);
449 
450 /* Output functions */
451 
459 U_STABLE int32_t U_EXPORT2
460 u_printf(const char *patternSpecification,
461  ... );
462 
471 U_STABLE int32_t U_EXPORT2
472 u_fprintf(UFILE *f,
473  const char *patternSpecification,
474  ... );
475 
488 U_STABLE int32_t U_EXPORT2
489 u_vfprintf(UFILE *f,
490  const char *patternSpecification,
491  va_list ap);
492 
500 U_STABLE int32_t U_EXPORT2
501 u_printf_u(const UChar *patternSpecification,
502  ... );
503 
509 U_STABLE UFILE * U_EXPORT2
510 u_get_stdout(void);
511 
520 U_STABLE int32_t U_EXPORT2
521 u_fprintf_u(UFILE *f,
522  const UChar *patternSpecification,
523  ... );
524 
537 U_STABLE int32_t U_EXPORT2
539  const UChar *patternSpecification,
540  va_list ap);
541 #endif
542 
552 U_STABLE int32_t U_EXPORT2
553 u_fputs(const UChar *s,
554  UFILE *f);
555 
563 U_STABLE UChar32 U_EXPORT2
564 u_fputc(UChar32 uc,
565  UFILE *f);
566 
578 U_STABLE int32_t U_EXPORT2
579 u_file_write(const UChar *ustring,
580  int32_t count,
581  UFILE *f);
582 
583 
584 /* Input functions */
585 #if !UCONFIG_NO_FORMATTING
586 
596 U_STABLE int32_t U_EXPORT2
597 u_fscanf(UFILE *f,
598  const char *patternSpecification,
599  ... );
600 
614 U_STABLE int32_t U_EXPORT2
615 u_vfscanf(UFILE *f,
616  const char *patternSpecification,
617  va_list ap);
618 
628 U_STABLE int32_t U_EXPORT2
629 u_fscanf_u(UFILE *f,
630  const UChar *patternSpecification,
631  ... );
632 
646 U_STABLE int32_t U_EXPORT2
647 u_vfscanf_u(UFILE *f,
648  const UChar *patternSpecification,
649  va_list ap);
650 #endif
651 
664 U_STABLE UChar* U_EXPORT2
665 u_fgets(UChar *s,
666  int32_t n,
667  UFILE *f);
668 
678 U_STABLE UChar U_EXPORT2
679 u_fgetc(UFILE *f);
680 
691 U_STABLE UChar32 U_EXPORT2
692 u_fgetcx(UFILE *f);
693 
705 U_STABLE UChar32 U_EXPORT2
707  UFILE *f);
708 
719 U_STABLE int32_t U_EXPORT2
720 u_file_read(UChar *chars,
721  int32_t count,
722  UFILE *f);
723 
724 #if !UCONFIG_NO_TRANSLITERATION
725 
743 U_STABLE UTransliterator* U_EXPORT2
744 u_fsettransliterator(UFILE *file, UFileDirection direction,
745  UTransliterator *adopt, UErrorCode *status);
746 
747 #endif
748 
749 
750 /* Output string functions */
751 #if !UCONFIG_NO_FORMATTING
752 
753 
764 U_STABLE int32_t U_EXPORT2
765 u_sprintf(UChar *buffer,
766  const char *patternSpecification,
767  ... );
768 
786 U_STABLE int32_t U_EXPORT2
787 u_snprintf(UChar *buffer,
788  int32_t count,
789  const char *patternSpecification,
790  ... );
791 
805 U_STABLE int32_t U_EXPORT2
806 u_vsprintf(UChar *buffer,
807  const char *patternSpecification,
808  va_list ap);
809 
830 U_STABLE int32_t U_EXPORT2
831 u_vsnprintf(UChar *buffer,
832  int32_t count,
833  const char *patternSpecification,
834  va_list ap);
835 
845 U_STABLE int32_t U_EXPORT2
846 u_sprintf_u(UChar *buffer,
847  const UChar *patternSpecification,
848  ... );
849 
866 U_STABLE int32_t U_EXPORT2
867 u_snprintf_u(UChar *buffer,
868  int32_t count,
869  const UChar *patternSpecification,
870  ... );
871 
885 U_STABLE int32_t U_EXPORT2
886 u_vsprintf_u(UChar *buffer,
887  const UChar *patternSpecification,
888  va_list ap);
889 
910 U_STABLE int32_t U_EXPORT2
911 u_vsnprintf_u(UChar *buffer,
912  int32_t count,
913  const UChar *patternSpecification,
914  va_list ap);
915 
916 /* Input string functions */
917 
928 U_STABLE int32_t U_EXPORT2
929 u_sscanf(const UChar *buffer,
930  const char *patternSpecification,
931  ... );
932 
947 U_STABLE int32_t U_EXPORT2
948 u_vsscanf(const UChar *buffer,
949  const char *patternSpecification,
950  va_list ap);
951 
962 U_STABLE int32_t U_EXPORT2
963 u_sscanf_u(const UChar *buffer,
964  const UChar *patternSpecification,
965  ... );
966 
981 U_STABLE int32_t U_EXPORT2
982 u_vsscanf_u(const UChar *buffer,
983  const UChar *patternSpecification,
984  va_list ap);
985 
986 #endif
987 #endif
988 
989 
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:208
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:215
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_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:290
void * UNumberFormat
A number formatter.
Definition: unum.h:133
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:298
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:278
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:200
C API: NumberFormat.