ICU 4.8.1.1  4.8.1.1
 All Data Structures 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-2010, 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 
238 u_fopen(const char *filename,
239  const char *perm,
240  const char *locale,
241  const char *codepage);
242 
260 u_finit(FILE *f,
261  const char *locale,
262  const char *codepage);
263 
281 u_fadopt(FILE *f,
282  const char *locale,
283  const char *codepage);
284 
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 
326 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose);
327 
329 
330 #endif
331 
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 
452 U_STABLE int32_t U_EXPORT2
453 u_fprintf(UFILE *f,
454  const char *patternSpecification,
455  ... );
456 
469 U_STABLE int32_t U_EXPORT2
470 u_vfprintf(UFILE *f,
471  const char *patternSpecification,
472  va_list ap);
473 
482 U_STABLE int32_t U_EXPORT2
483 u_fprintf_u(UFILE *f,
484  const UChar *patternSpecification,
485  ... );
486 
499 U_STABLE int32_t U_EXPORT2
501  const UChar *patternSpecification,
502  va_list ap);
503 #endif
504 
514 U_STABLE int32_t U_EXPORT2
515 u_fputs(const UChar *s,
516  UFILE *f);
517 
526 u_fputc(UChar32 uc,
527  UFILE *f);
528 
540 U_STABLE int32_t U_EXPORT2
541 u_file_write(const UChar *ustring,
542  int32_t count,
543  UFILE *f);
544 
545 
546 /* Input functions */
547 #if !UCONFIG_NO_FORMATTING
548 
558 U_STABLE int32_t U_EXPORT2
559 u_fscanf(UFILE *f,
560  const char *patternSpecification,
561  ... );
562 
576 U_STABLE int32_t U_EXPORT2
577 u_vfscanf(UFILE *f,
578  const char *patternSpecification,
579  va_list ap);
580 
590 U_STABLE int32_t U_EXPORT2
591 u_fscanf_u(UFILE *f,
592  const UChar *patternSpecification,
593  ... );
594 
608 U_STABLE int32_t U_EXPORT2
609 u_vfscanf_u(UFILE *f,
610  const UChar *patternSpecification,
611  va_list ap);
612 #endif
613 
627 u_fgets(UChar *s,
628  int32_t n,
629  UFILE *f);
630 
641 u_fgetc(UFILE *f);
642 
654 u_fgetcx(UFILE *f);
655 
669  UFILE *f);
670 
681 U_STABLE int32_t U_EXPORT2
682 u_file_read(UChar *chars,
683  int32_t count,
684  UFILE *f);
685 
686 #if !UCONFIG_NO_TRANSLITERATION
687 
706 u_fsettransliterator(UFILE *file, UFileDirection direction,
707  UTransliterator *adopt, UErrorCode *status);
708 
709 #endif
710 
711 
712 /* Output string functions */
713 #if !UCONFIG_NO_FORMATTING
714 
715 
726 U_STABLE int32_t U_EXPORT2
727 u_sprintf(UChar *buffer,
728  const char *patternSpecification,
729  ... );
730 
748 U_STABLE int32_t U_EXPORT2
749 u_snprintf(UChar *buffer,
750  int32_t count,
751  const char *patternSpecification,
752  ... );
753 
767 U_STABLE int32_t U_EXPORT2
768 u_vsprintf(UChar *buffer,
769  const char *patternSpecification,
770  va_list ap);
771 
792 U_STABLE int32_t U_EXPORT2
793 u_vsnprintf(UChar *buffer,
794  int32_t count,
795  const char *patternSpecification,
796  va_list ap);
797 
807 U_STABLE int32_t U_EXPORT2
808 u_sprintf_u(UChar *buffer,
809  const UChar *patternSpecification,
810  ... );
811 
828 U_STABLE int32_t U_EXPORT2
829 u_snprintf_u(UChar *buffer,
830  int32_t count,
831  const UChar *patternSpecification,
832  ... );
833 
847 U_STABLE int32_t U_EXPORT2
848 u_vsprintf_u(UChar *buffer,
849  const UChar *patternSpecification,
850  va_list ap);
851 
872 U_STABLE int32_t U_EXPORT2
873 u_vsnprintf_u(UChar *buffer,
874  int32_t count,
875  const UChar *patternSpecification,
876  va_list ap);
877 
878 /* Input string functions */
879 
890 U_STABLE int32_t U_EXPORT2
891 u_sscanf(const UChar *buffer,
892  const char *patternSpecification,
893  ... );
894 
909 U_STABLE int32_t U_EXPORT2
910 u_vsscanf(const UChar *buffer,
911  const char *patternSpecification,
912  va_list ap);
913 
924 U_STABLE int32_t U_EXPORT2
925 u_sscanf_u(const UChar *buffer,
926  const UChar *patternSpecification,
927  ... );
928 
943 U_STABLE int32_t U_EXPORT2
944 u_vsscanf_u(const UChar *buffer,
945  const UChar *patternSpecification,
946  va_list ap);
947 
948 #endif
949 #endif
950 
951