Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Search  

ustdio.h

Go to the documentation of this file.
00001 /*
00002 ******************************************************************************
00003 *
00004 *   Copyright (C) 1998-2001, International Business Machines
00005 *   Corporation and others.  All Rights Reserved.
00006 *
00007 ******************************************************************************
00008 *
00009 * File ustdio.h
00010 *
00011 * Modification History:
00012 *
00013 *   Date        Name        Description
00014 *   10/16/98    stephen     Creation.
00015 *   11/06/98    stephen     Modified per code review.
00016 *   03/12/99    stephen     Modified for new C API.
00017 *   07/19/99    stephen     Minor doc update.
00018 *   02/01/01    george      Added sprintf & sscanf with all of its variants
00019 ******************************************************************************
00020 */
00021 
00022 #ifndef USTDIO_H
00023 #define USTDIO_H
00024 
00025 #include <stdio.h>
00026 #include <stdarg.h>
00027 
00028 #include "unicode/utypes.h"
00029 #include "unicode/ucnv.h"
00030 #include "unicode/utrans.h"
00031 
00032 /*
00033     TODO
00034  The following is a small list as to what is currently wrong/suggestions for
00035  ustdio.
00036 
00037  * %p should be deprecated. Pointers are 2-16 bytes big and scanf should
00038     really read them.
00039  * The format specification should use int32_t and ICU type variants instead of
00040     the compiler dependent int.
00041  * Make sure that #, blank and precision in the printf format specification
00042     works.
00043  * Make sure that * in the scanf format specification works.
00044  * Each UFILE takes up at least 2KB. This should be really reduced.
00045  * This library does buffering. The OS should do this for us already. Check on
00046     this, and remove it from this library, if this is the case. Double buffering
00047     wastes a lot of time and space.
00048  * Make sure that surrogates are supported. It doesn't look like %[], %s or %U
00049     properly handle surrogates in both scanf()'s.
00050  * Testing should be done for reading and writing multi-byte encodings,
00051     and make sure that a character that is contained across buffer boundries
00052     works even for incomplete characters.
00053  * Make sure that the last character is flushed when the file/string is closed.
00054  * snprintf should follow the C99 standard for the return value, which is
00055     return the number of characters (excluding the trailing '\0')
00056     which would have been written to the destination string regardless
00057     of available space. This is like pre-flighting.
00058  * Everything that uses %s should do what operator>> does for UnicodeString.
00059     It should convert one byte at a time, and once a character is
00060     converted then check to see if it's whitespace or in the scanset.
00061     If it's whitespace or in the scanset, put all the bytes back (do nothing
00062     for sprintf/sscanf).
00063  * If bad string data is encountered, make sure that the function fails
00064     without memory leaks and the unconvertable characters are valid
00065     substitution or are escaped characters.
00066  * u_fungetc() can't unget a character when it's at the beginning of the
00067     internal conversion buffer, and it shouldn't be writing new
00068     characters to this buffer because they might be different characters.
00069     This can be tested by writing a file, and reading it backwards by
00070     using u_fgetc and two u_fungetc() calls with incorrect data.
00071     FYI The behavior is undefined for ungetc() when an incorrect character
00072     is put back, when its called multiple times in a row, or when
00073     a its called without a read operation.
00074  * u_fflush() and u_fclose should return an int32_t like C99 functions.
00075     0 is returned if the operation was successful and EOF otherwise.
00076  * u_fsettransliterator does not support U_READ side of transliteration.
00077  * The format specifier should limit the size of a format or honor it in
00078     order to prevent buffer overruns.  (e.g. %256.256d).
00079  * u_fread and u_fwrite don't exist. They're needed for reading and writing
00080     data structures without any conversion.
00081  * u_file_read and u_file_write are used for writing strings. u_fgets and
00082     u_fputs or u_fread and u_fwrite should be used to do this.
00083  * u_fgetcx may not be needed anymore. Maybe u_fgetc should return a UChar32.
00084  * u_fgetc() should use UChar32 instead of UChar. Maybe u_fgetcx is good enough
00085     for now.
00086  * We should consider using a UnicodeSet for scanset.
00087  * scanset has a buffer overflow and underflow bug for both string and file
00088     APIs.
00089  * The width parameter for all scanf formats, including scanset, needs
00090     better testing. This prevents buffer overflows.
00091  * The skip '*' parameter for all scanf formats, including scanset, needs
00092     better testing. This prevents writing to bad memory.
00093  * Figure out what is suppose to happen when a codepage is changed midstream.
00094     Maybe a flush or a rewind are good enough.
00095  * More testing is needed.
00096 */
00097 
00098 
00104 #define U_EOF 0xFFFF
00105 
00107 typedef struct UFILE UFILE;
00108 
00114 typedef enum { 
00115    U_READ = 1,
00116    U_WRITE = 2, 
00117    U_READWRITE =3  /* == (U_READ | U_WRITE) */ 
00118 } UFileDirection;
00119 
00138 U_CAPI UFILE* U_EXPORT2
00139 u_fopen(const char    *filename,
00140     const char    *perm,
00141     const char    *locale,
00142     const char    *codepage);
00143 
00157 U_CAPI UFILE* U_EXPORT2
00158 u_finit(FILE        *f,
00159     const char    *locale,
00160     const char    *codepage);
00161 
00167 U_CAPI void U_EXPORT2
00168 u_fclose(UFILE *file);
00169 
00178 U_CAPI void U_EXPORT2
00179 u_fflush(UFILE *file);
00180 
00186 U_CAPI void
00187 u_frewind(UFILE *file);
00188 
00195 U_CAPI FILE* U_EXPORT2
00196 u_fgetfile(UFILE *f);
00197 
00198 #if !UCONFIG_NO_FORMATTING
00199 
00208 U_CAPI const char* U_EXPORT2
00209 u_fgetlocale(UFILE *file);
00210 
00219 U_CAPI int32_t U_EXPORT2
00220 u_fsetlocale(const char *locale,
00221              UFILE      *file);
00222 
00223 #endif
00224 
00234 U_CAPI const char* U_EXPORT2
00235 u_fgetcodepage(UFILE *file);
00236 
00252 U_CAPI int32_t U_EXPORT2
00253 u_fsetcodepage(const char   *codepage,
00254                UFILE        *file);
00255 
00256 
00263 U_CAPI UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
00264 
00265 /* Output functions */
00266 
00275 U_CAPI int32_t U_EXPORT2
00276 u_fprintf(UFILE         *f,
00277           const char    *patternSpecification,
00278           ... );
00279 
00292 U_CAPI int32_t U_EXPORT2
00293 u_vfprintf(UFILE        *f,
00294            const char   *patternSpecification,
00295            va_list      ap);
00296 
00305 U_CAPI int32_t U_EXPORT2
00306 u_fprintf_u(UFILE       *f,
00307             const UChar *patternSpecification,
00308             ... );
00309 
00322 U_CAPI int32_t U_EXPORT2
00323 u_vfprintf_u(UFILE      *f,
00324             const UChar *patternSpecification,
00325             va_list     ap);
00326 
00336 U_CAPI int32_t U_EXPORT2
00337 u_fputs(const UChar *s,
00338         UFILE       *f);
00339 
00347 U_CAPI int32_t U_EXPORT2
00348 u_fputc(UChar   uc,
00349         UFILE  *f);
00350 
00362 U_CAPI int32_t U_EXPORT2
00363 u_file_write(const UChar    *ustring, 
00364              int32_t        count, 
00365              UFILE          *f);
00366 
00367 
00368 /* Input functions */
00369 
00379 U_CAPI int32_t U_EXPORT2
00380 u_fscanf(UFILE      *f,
00381          const char *patternSpecification,
00382          ... );
00383 
00397 U_CAPI int32_t U_EXPORT2
00398 u_vfscanf(UFILE         *f,
00399           const char    *patternSpecification,
00400           va_list        ap);
00401 
00411 U_CAPI int32_t U_EXPORT2
00412 u_fscanf_u(UFILE        *f,
00413            const UChar  *patternSpecification,
00414            ... );
00415 
00429 U_CAPI int32_t U_EXPORT2
00430 u_vfscanf_u(UFILE       *f,
00431             const UChar *patternSpecification,
00432             va_list      ap);
00433 
00446 U_CAPI UChar* U_EXPORT2
00447 u_fgets(UChar  *s,
00448         int32_t n,
00449         UFILE  *f);
00450 
00457 U_CAPI UChar U_EXPORT2
00458 u_fgetc(UFILE   *f);
00459 
00470 U_CAPI UChar32 U_EXPORT2
00471 u_fgetcx(UFILE  *f);
00472 
00482 U_CAPI UChar32 U_EXPORT2
00483 u_fungetc(UChar32   c,
00484       UFILE        *f);
00485 
00496 U_CAPI int32_t U_EXPORT2
00497 u_file_read(UChar        *chars, 
00498         int32_t        count, 
00499         UFILE         *f);
00500 
00501 #if !UCONFIG_NO_TRANSLITERATION
00502 
00520 U_CAPI UTransliterator* U_EXPORT2
00521 u_fsettransliterator(UFILE *file, UFileDirection direction,
00522                      UTransliterator *adopt, UErrorCode *status);
00523 
00524 #endif
00525 
00526 
00527 /* Output string functions */
00528 
00529 
00542 U_CAPI int32_t U_EXPORT2
00543 u_sprintf(UChar       *buffer,
00544         const char    *locale,
00545         const char    *patternSpecification,
00546         ... );
00547 
00566 U_CAPI int32_t U_EXPORT2
00567 u_snprintf(UChar      *buffer,
00568         int32_t       count,
00569         const char    *locale,
00570         const char    *patternSpecification,
00571         ... );
00572 
00588 U_CAPI int32_t U_EXPORT2
00589 u_vsprintf(UChar      *buffer,
00590         const char    *locale,
00591         const char    *patternSpecification,
00592         va_list        ap);
00593 
00615 U_CAPI int32_t U_EXPORT2
00616 u_vsnprintf(UChar     *buffer,
00617         int32_t       count,
00618         const char    *locale,
00619         const char    *patternSpecification,
00620         va_list        ap);
00621 
00633 U_CAPI int32_t U_EXPORT2
00634 u_sprintf_u(UChar      *buffer,
00635         const char     *locale,
00636         const UChar    *patternSpecification,
00637         ... );
00638 
00656 U_CAPI int32_t U_EXPORT2
00657 u_snprintf_u(UChar     *buffer,
00658         int32_t        count,
00659         const char     *locale,
00660         const UChar    *patternSpecification,
00661         ... );
00662 
00679 U_CAPI int32_t U_EXPORT2
00680 u_vsprintf_u(UChar     *buffer,
00681         const char    *locale,
00682         const UChar    *patternSpecification,
00683         va_list        ap);
00684 
00705 U_CAPI int32_t U_EXPORT2
00706 u_vsnprintf_u(UChar *buffer,
00707         int32_t         count,
00708         const char     *locale,
00709         const UChar     *patternSpecification,
00710         va_list         ap);
00711 
00712 /* Input string functions */
00713 
00726 U_CAPI int32_t U_EXPORT2
00727 u_sscanf(const UChar   *buffer,
00728         const char     *locale,
00729         const char     *patternSpecification,
00730         ... );
00731 
00748 U_CAPI int32_t U_EXPORT2
00749 u_vsscanf(const UChar  *buffer,
00750         const char     *locale,
00751         const char     *patternSpecification,
00752         va_list        ap);
00753 
00766 U_CAPI int32_t U_EXPORT2
00767 u_sscanf_u(const UChar  *buffer,
00768         const char      *locale,
00769         const UChar     *patternSpecification,
00770         ... );
00771 
00788 U_CAPI int32_t U_EXPORT2
00789 u_vsscanf_u(const UChar *buffer,
00790         const char      *locale,
00791         const UChar     *patternSpecification,
00792         va_list         ap);
00793 
00794 
00795 #endif
00796 
00797 

Generated on Mon Nov 24 14:35:45 2003 for ICU 2.8 by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001