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 
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:67
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.
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:207
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:214
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.
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:131
UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
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: &quot;Smart pointers&quot; 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:345
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.
#define U_EXPORT2
Definition: platform.h:314
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 wchar_t if that is 16 bits wide; always assumed to be unsigned.
Definition: umachine.h:325
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:132
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
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:639
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.
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:137
int8_t UBool
The ICU boolean type.
Definition: umachine.h:228