ICU 50.1.2  50.1.2
ustdio.h
Go to the documentation of this file.
1 /*
2 ******************************************************************************
3 *
4 * Copyright (C) 1998-2012, 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 
33 /*
34  TODO
35  The following is a small list as to what is currently wrong/suggestions for
36  ustdio.
37 
38  * Make sure that * in the scanf format specification works for all formats.
39  * Each UFILE takes up at least 2KB.
40  Look into adding setvbuf() for configurable buffers.
41  * This library does buffering. The OS should do this for us already. Check on
42  this, and remove it from this library, if this is the case. Double buffering
43  wastes a lot of time and space.
44  * Test stdin and stdout with the u_f* functions
45  * Testing should be done for reading and writing multi-byte encodings,
46  and make sure that a character that is contained across buffer boundries
47  works even for incomplete characters.
48  * Make sure that the last character is flushed when the file/string is closed.
49  * snprintf should follow the C99 standard for the return value, which is
50  return the number of characters (excluding the trailing '\0')
51  which would have been written to the destination string regardless
52  of available space. This is like pre-flighting.
53  * Everything that uses %s should do what operator>> does for UnicodeString.
54  It should convert one byte at a time, and once a character is
55  converted then check to see if it's whitespace or in the scanset.
56  If it's whitespace or in the scanset, put all the bytes back (do nothing
57  for sprintf/sscanf).
58  * If bad string data is encountered, make sure that the function fails
59  without memory leaks and the unconvertable characters are valid
60  substitution or are escaped characters.
61  * u_fungetc() can't unget a character when it's at the beginning of the
62  internal conversion buffer. For example, read the buffer size # of
63  characters, and then ungetc to get the previous character that was
64  at the end of the last buffer.
65  * u_fflush() and u_fclose should return an int32_t like C99 functions.
66  0 is returned if the operation was successful and EOF otherwise.
67  * u_fsettransliterator does not support U_READ side of transliteration.
68  * The format specifier should limit the size of a format or honor it in
69  order to prevent buffer overruns. (e.g. %256.256d).
70  * u_fread and u_fwrite don't exist. They're needed for reading and writing
71  data structures without any conversion.
72  * u_file_read and u_file_write are used for writing strings. u_fgets and
73  u_fputs or u_fread and u_fwrite should be used to do this.
74  * The width parameter for all scanf formats, including scanset, needs
75  better testing. This prevents buffer overflows.
76  * Figure out what is suppose to happen when a codepage is changed midstream.
77  Maybe a flush or a rewind are good enough.
78  * Make sure that a UFile opened with "rw" can be used after using
79  u_fflush with a u_frewind.
80  * scanf(%i) should detect what type of number to use.
81  * Add more testing of the alternate format, %#
82  * Look at newline handling of fputs/puts
83  * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
84  * Complete the file documentation with proper doxygen formatting.
85  See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
86 */
87 
204 #define U_EOF 0xFFFF
205 
207 typedef struct UFILE UFILE;
208 
214 typedef enum {
215  U_READ = 1,
216  U_WRITE = 2,
217  U_READWRITE =3 /* == (U_READ | U_WRITE) */
219 
237 U_STABLE UFILE* U_EXPORT2
238 u_fopen(const char *filename,
239  const char *perm,
240  const char *locale,
241  const char *codepage);
242 
259 U_STABLE UFILE* U_EXPORT2
260 u_finit(FILE *f,
261  const char *locale,
262  const char *codepage);
263 
280 U_STABLE UFILE* U_EXPORT2
281 u_fadopt(FILE *f,
282  const char *locale,
283  const char *codepage);
284 
299 U_STABLE UFILE* U_EXPORT2
300 u_fstropen(UChar *stringBuf,
301  int32_t capacity,
302  const char *locale);
303 
310 U_STABLE void U_EXPORT2
311 u_fclose(UFILE *file);
312 
313 #if U_SHOW_CPLUSPLUS_API
314 
316 
327 
329 
330 #endif
331 
340 U_STABLE UBool U_EXPORT2
341 u_feof(UFILE *f);
342 
353 U_STABLE void U_EXPORT2
354 u_fflush(UFILE *file);
355 
361 U_STABLE void
362 u_frewind(UFILE *file);
363 
370 U_STABLE FILE* U_EXPORT2
371 u_fgetfile(UFILE *f);
372 
373 #if !UCONFIG_NO_FORMATTING
374 
383 U_STABLE const char* U_EXPORT2
384 u_fgetlocale(UFILE *file);
385 
394 U_STABLE int32_t U_EXPORT2
395 u_fsetlocale(UFILE *file,
396  const char *locale);
397 
398 #endif
399 
409 U_STABLE const char* U_EXPORT2
410 u_fgetcodepage(UFILE *file);
411 
427 U_STABLE int32_t U_EXPORT2
428 u_fsetcodepage(const char *codepage,
429  UFILE *file);
430 
431 
439 
440 #if !UCONFIG_NO_FORMATTING
441 
442 /* Output functions */
443 
451 U_DRAFT int32_t U_EXPORT2
452 u_printf(const char *patternSpecification,
453  ... );
454 
463 U_STABLE int32_t U_EXPORT2
464 u_fprintf(UFILE *f,
465  const char *patternSpecification,
466  ... );
467 
480 U_STABLE int32_t U_EXPORT2
481 u_vfprintf(UFILE *f,
482  const char *patternSpecification,
483  va_list ap);
484 
492 U_DRAFT int32_t U_EXPORT2
493 u_printf_u(const UChar *patternSpecification,
494  ... );
495 
501 U_DRAFT UFILE * U_EXPORT2
502 u_get_stdout(void);
503 
512 U_STABLE int32_t U_EXPORT2
513 u_fprintf_u(UFILE *f,
514  const UChar *patternSpecification,
515  ... );
516 
529 U_STABLE int32_t U_EXPORT2
531  const UChar *patternSpecification,
532  va_list ap);
533 #endif
534 
544 U_STABLE int32_t U_EXPORT2
545 u_fputs(const UChar *s,
546  UFILE *f);
547 
555 U_STABLE UChar32 U_EXPORT2
556 u_fputc(UChar32 uc,
557  UFILE *f);
558 
570 U_STABLE int32_t U_EXPORT2
571 u_file_write(const UChar *ustring,
572  int32_t count,
573  UFILE *f);
574 
575 
576 /* Input functions */
577 #if !UCONFIG_NO_FORMATTING
578 
588 U_STABLE int32_t U_EXPORT2
589 u_fscanf(UFILE *f,
590  const char *patternSpecification,
591  ... );
592 
606 U_STABLE int32_t U_EXPORT2
607 u_vfscanf(UFILE *f,
608  const char *patternSpecification,
609  va_list ap);
610 
620 U_STABLE int32_t U_EXPORT2
621 u_fscanf_u(UFILE *f,
622  const UChar *patternSpecification,
623  ... );
624 
638 U_STABLE int32_t U_EXPORT2
639 u_vfscanf_u(UFILE *f,
640  const UChar *patternSpecification,
641  va_list ap);
642 #endif
643 
656 U_STABLE UChar* U_EXPORT2
657 u_fgets(UChar *s,
658  int32_t n,
659  UFILE *f);
660 
670 U_STABLE UChar U_EXPORT2
671 u_fgetc(UFILE *f);
672 
683 U_STABLE UChar32 U_EXPORT2
684 u_fgetcx(UFILE *f);
685 
697 U_STABLE UChar32 U_EXPORT2
699  UFILE *f);
700 
711 U_STABLE int32_t U_EXPORT2
712 u_file_read(UChar *chars,
713  int32_t count,
714  UFILE *f);
715 
716 #if !UCONFIG_NO_TRANSLITERATION
717 
735 U_STABLE UTransliterator* U_EXPORT2
736 u_fsettransliterator(UFILE *file, UFileDirection direction,
737  UTransliterator *adopt, UErrorCode *status);
738 
739 #endif
740 
741 
742 /* Output string functions */
743 #if !UCONFIG_NO_FORMATTING
744 
745 
756 U_STABLE int32_t U_EXPORT2
757 u_sprintf(UChar *buffer,
758  const char *patternSpecification,
759  ... );
760 
778 U_STABLE int32_t U_EXPORT2
779 u_snprintf(UChar *buffer,
780  int32_t count,
781  const char *patternSpecification,
782  ... );
783 
797 U_STABLE int32_t U_EXPORT2
798 u_vsprintf(UChar *buffer,
799  const char *patternSpecification,
800  va_list ap);
801 
822 U_STABLE int32_t U_EXPORT2
823 u_vsnprintf(UChar *buffer,
824  int32_t count,
825  const char *patternSpecification,
826  va_list ap);
827 
837 U_STABLE int32_t U_EXPORT2
838 u_sprintf_u(UChar *buffer,
839  const UChar *patternSpecification,
840  ... );
841 
858 U_STABLE int32_t U_EXPORT2
859 u_snprintf_u(UChar *buffer,
860  int32_t count,
861  const UChar *patternSpecification,
862  ... );
863 
877 U_STABLE int32_t U_EXPORT2
878 u_vsprintf_u(UChar *buffer,
879  const UChar *patternSpecification,
880  va_list ap);
881 
902 U_STABLE int32_t U_EXPORT2
903 u_vsnprintf_u(UChar *buffer,
904  int32_t count,
905  const UChar *patternSpecification,
906  va_list ap);
907 
908 /* Input string functions */
909 
920 U_STABLE int32_t U_EXPORT2
921 u_sscanf(const UChar *buffer,
922  const char *patternSpecification,
923  ... );
924 
939 U_STABLE int32_t U_EXPORT2
940 u_vsscanf(const UChar *buffer,
941  const char *patternSpecification,
942  va_list ap);
943 
954 U_STABLE int32_t U_EXPORT2
955 u_sscanf_u(const UChar *buffer,
956  const UChar *patternSpecification,
957  ... );
958 
973 U_STABLE int32_t U_EXPORT2
974 u_vsscanf_u(const UChar *buffer,
975  const UChar *patternSpecification,
976  va_list ap);
977 
978 #endif
979 #endif
980 
981