ICU 52.1  52.1
ustdio.h
Go to the documentation of this file.
1 /*
2 ******************************************************************************
3 *
4 * Copyright (C) 1998-2013, 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 #ifndef U_HIDE_DRAFT_API
443 
449  U_DRAFT const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f);
450 #endif /* U_HIDE_DRAFT_API */
451 
452 /* Output functions */
453 
461 U_STABLE int32_t U_EXPORT2
462 u_printf(const char *patternSpecification,
463  ... );
464 
473 U_STABLE int32_t U_EXPORT2
474 u_fprintf(UFILE *f,
475  const char *patternSpecification,
476  ... );
477 
490 U_STABLE int32_t U_EXPORT2
491 u_vfprintf(UFILE *f,
492  const char *patternSpecification,
493  va_list ap);
494 
502 U_STABLE int32_t U_EXPORT2
503 u_printf_u(const UChar *patternSpecification,
504  ... );
505 
511 U_STABLE UFILE * U_EXPORT2
512 u_get_stdout(void);
513 
522 U_STABLE int32_t U_EXPORT2
523 u_fprintf_u(UFILE *f,
524  const UChar *patternSpecification,
525  ... );
526 
539 U_STABLE int32_t U_EXPORT2
541  const UChar *patternSpecification,
542  va_list ap);
543 #endif
544 
554 U_STABLE int32_t U_EXPORT2
555 u_fputs(const UChar *s,
556  UFILE *f);
557 
565 U_STABLE UChar32 U_EXPORT2
566 u_fputc(UChar32 uc,
567  UFILE *f);
568 
580 U_STABLE int32_t U_EXPORT2
581 u_file_write(const UChar *ustring,
582  int32_t count,
583  UFILE *f);
584 
585 
586 /* Input functions */
587 #if !UCONFIG_NO_FORMATTING
588 
598 U_STABLE int32_t U_EXPORT2
599 u_fscanf(UFILE *f,
600  const char *patternSpecification,
601  ... );
602 
616 U_STABLE int32_t U_EXPORT2
617 u_vfscanf(UFILE *f,
618  const char *patternSpecification,
619  va_list ap);
620 
630 U_STABLE int32_t U_EXPORT2
631 u_fscanf_u(UFILE *f,
632  const UChar *patternSpecification,
633  ... );
634 
648 U_STABLE int32_t U_EXPORT2
649 u_vfscanf_u(UFILE *f,
650  const UChar *patternSpecification,
651  va_list ap);
652 #endif
653 
666 U_STABLE UChar* U_EXPORT2
667 u_fgets(UChar *s,
668  int32_t n,
669  UFILE *f);
670 
680 U_STABLE UChar U_EXPORT2
681 u_fgetc(UFILE *f);
682 
693 U_STABLE UChar32 U_EXPORT2
694 u_fgetcx(UFILE *f);
695 
707 U_STABLE UChar32 U_EXPORT2
709  UFILE *f);
710 
721 U_STABLE int32_t U_EXPORT2
722 u_file_read(UChar *chars,
723  int32_t count,
724  UFILE *f);
725 
726 #if !UCONFIG_NO_TRANSLITERATION
727 
745 U_STABLE UTransliterator* U_EXPORT2
746 u_fsettransliterator(UFILE *file, UFileDirection direction,
747  UTransliterator *adopt, UErrorCode *status);
748 
749 #endif
750 
751 
752 /* Output string functions */
753 #if !UCONFIG_NO_FORMATTING
754 
755 
766 U_STABLE int32_t U_EXPORT2
767 u_sprintf(UChar *buffer,
768  const char *patternSpecification,
769  ... );
770 
788 U_STABLE int32_t U_EXPORT2
789 u_snprintf(UChar *buffer,
790  int32_t count,
791  const char *patternSpecification,
792  ... );
793 
807 U_STABLE int32_t U_EXPORT2
808 u_vsprintf(UChar *buffer,
809  const char *patternSpecification,
810  va_list ap);
811 
832 U_STABLE int32_t U_EXPORT2
833 u_vsnprintf(UChar *buffer,
834  int32_t count,
835  const char *patternSpecification,
836  va_list ap);
837 
847 U_STABLE int32_t U_EXPORT2
848 u_sprintf_u(UChar *buffer,
849  const UChar *patternSpecification,
850  ... );
851 
868 U_STABLE int32_t U_EXPORT2
869 u_snprintf_u(UChar *buffer,
870  int32_t count,
871  const UChar *patternSpecification,
872  ... );
873 
887 U_STABLE int32_t U_EXPORT2
888 u_vsprintf_u(UChar *buffer,
889  const UChar *patternSpecification,
890  va_list ap);
891 
912 U_STABLE int32_t U_EXPORT2
913 u_vsnprintf_u(UChar *buffer,
914  int32_t count,
915  const UChar *patternSpecification,
916  va_list ap);
917 
918 /* Input string functions */
919 
930 U_STABLE int32_t U_EXPORT2
931 u_sscanf(const UChar *buffer,
932  const char *patternSpecification,
933  ... );
934 
949 U_STABLE int32_t U_EXPORT2
950 u_vsscanf(const UChar *buffer,
951  const char *patternSpecification,
952  va_list ap);
953 
964 U_STABLE int32_t U_EXPORT2
965 u_sscanf_u(const UChar *buffer,
966  const UChar *patternSpecification,
967  ... );
968 
983 U_STABLE int32_t U_EXPORT2
984 u_vsscanf_u(const UChar *buffer,
985  const UChar *patternSpecification,
986  va_list ap);
987 
988 #endif
989 #endif
990 
991