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  * %D and %T printf uses the current timezone, but the scanf version uses GMT.
00038  * %p should be deprecated. Pointers are 2-16 bytes big and scanf should
00039     really read them.
00040  * The format specification should use int32_t and ICU type variants instead of
00041     the compiler dependent int.
00042  * We should consider using Microsoft's wprintf and wscanf format
00043     specification.
00044  * %C and %S are aliases of %lc and %ls, which are used for wchar_t.
00045     We should consider using this for UChar and replace %K and %U,
00046     or we should make them use wchar_t.
00047  * + in printf format specification is incomplete.
00048  * Make sure that #, blank and precision in the printf format specification
00049     works.
00050  * Make sure that * in the scanf format specification works.
00051  * Each UFILE takes up at least 2KB. This should be really reduced.
00052  * This library does buffering. The OS should do this for us already. Check on
00053     this, and remove it from this library, if this is the case. Double buffering
00054     wastes a lot of time and space.
00055  * Make sure that surrogates are supported. It doesn't look like %[], %s or %U
00056     properly handle surrogates in both scanf()'s.
00057  * The ustream header should also include operator<< and
00058     operator>> for UDate (not double). This may not work on some compilers
00059     that use these operators on a double.
00060  * Testing should be done for reading and writing multi-byte encodings,
00061     and make sure that a character that is contained across buffer boundries
00062     works even for incomplete characters.
00063  * Make sure that the last character is flushed when the file/string is closed.
00064  * snprintf should follow the C99 standard for the return value, which is
00065     return the number of characters (excluding the trailing '\0')
00066     which would have been written to the destination string regardless
00067     of available space. This is like pre-flighting.
00068  * Everything that uses %s should do what operator>> does for UnicodeString.
00069     It should convert one byte at a time, and once a character is
00070     converted then check to see if it's whitespace or in the scanset.
00071     If it's whitespace or in the scanset, put all the bytes back (do nothing
00072     for sprintf/sscanf).
00073  * If bad string data is encountered, make sure that the function fails
00074     without memory leaks and the unconvertable characters are valid
00075     substitution or are escaped characters.
00076  * u_fungetc() can't unget a character when it's at the beginning of the
00077     internal conversion buffer, and it shouldn't be writing new
00078     characters to this buffer because they might be different characters.
00079     This can be tested by writing a file, and reading it backwards by
00080     using u_fgetc and two u_fungetc() calls with incorrect data.
00081     FYI The behavior is undefined for ungetc() when an incorrect character
00082     is put back, when its called multiple times in a row, or when
00083     a its called without a read operation.
00084  * u_fflush() and u_fclose should return an int32_t like C99 functions.
00085     0 is returned if the operation was successful and EOF otherwise.
00086  * u_fsettransliterator does not support U_READ side of transliteration.
00087  * The format specifier should limit the size of a format or honor it in
00088     order to prevent buffer overruns.  (e.g. %1000.1000d).
00089  * u_fgets is different from stdio. The UChar and UFile arguments are swapped.
00090  * u_fread and u_fwrite don't exist. They're needed for reading and writing
00091     data structures without any conversion.
00092  * u_file_read and u_file_write are used for writing strings. u_fgets and
00093     u_fputs or u_fread and u_fwrite should be used to do this.
00094  * u_fgetcx isn't really needed anymore because the transliterator is a
00095     part of the file API. It allows multiple kinds of escape sequences
00096     to be unescaped.
00097  * We should consider using a UnicodeSet for scanset.
00098  * scanset has a buffer overflow and underflow bug for both string and file
00099     APIs.
00100  * The width '*' parameter for all scanf formats, including scanset, needs
00101     better testing. This prevents buffer overflows.
00102  * u_fgetc() and u_fungetc() should use UChar32 instead of UChar, or at
00103     least 32-bit versions should be available.
00104  * More testing is needed.
00105 */
00106 
00107 
00113 #define U_EOF 0xFFFF
00114 
00116 typedef struct UFILE UFILE;
00117 
00123 typedef enum { 
00124    U_READ = 1,
00125    U_WRITE = 2, 
00126    U_READWRITE =3  /* == (U_READ | U_WRITE) */ 
00127 } UFileDirection;
00128 
00147 U_CAPI UFILE* U_EXPORT2
00148 u_fopen(const char    *filename,
00149     const char    *perm,
00150     const char    *locale,
00151     const char    *codepage);
00152 
00166 U_CAPI UFILE* U_EXPORT2
00167 u_finit(FILE        *f,
00168     const char    *locale,
00169     const char    *codepage);
00170 
00176 U_CAPI void U_EXPORT2
00177 u_fclose(UFILE *file);
00178 
00187 U_CAPI void U_EXPORT2
00188 u_fflush(UFILE *file);
00189 
00196 U_CAPI FILE* U_EXPORT2
00197 u_fgetfile(UFILE *f);
00198 
00199 #if !UCONFIG_NO_FORMATTING
00200 
00209 U_CAPI const char* U_EXPORT2
00210 u_fgetlocale(UFILE *file);
00211 
00220 U_CAPI int32_t U_EXPORT2
00221 u_fsetlocale(const char        *locale,
00222          UFILE        *file);
00223 
00224 #endif
00225 
00235 U_CAPI const char* U_EXPORT2
00236 u_fgetcodepage(UFILE *file);
00237 
00250 U_CAPI int32_t U_EXPORT2
00251 u_fsetcodepage(const char    *codepage,
00252            UFILE        *file);
00253 
00254 
00261 U_CAPI UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
00262 
00263 /* Output functions */
00264 
00273 U_CAPI int32_t U_EXPORT2
00274 u_fprintf(    UFILE        *f,
00275         const char    *patternSpecification,
00276         ... );
00277 
00290 U_CAPI int32_t U_EXPORT2
00291 u_vfprintf(    UFILE        *f,
00292         const char    *patternSpecification,
00293         va_list        ap);
00294 
00303 U_CAPI int32_t U_EXPORT2
00304 u_fprintf_u(    UFILE        *f,
00305         const UChar    *patternSpecification,
00306         ... );
00307 
00320 U_CAPI int32_t U_EXPORT2
00321 u_vfprintf_u(    UFILE        *f,
00322         const UChar    *patternSpecification,
00323         va_list        ap);
00324 
00334 U_CAPI int32_t U_EXPORT2
00335 u_fputs(const UChar    *s,
00336     UFILE        *f);
00337 
00345 U_CAPI int32_t U_EXPORT2
00346 u_fputc(UChar        uc,
00347     UFILE        *f);
00348 
00359 U_CAPI int32_t U_EXPORT2
00360 u_file_write(const UChar     *chars, 
00361          int32_t        count, 
00362          UFILE         *f);
00363 
00364 
00365 /* Input functions */
00366 
00376 U_CAPI int32_t U_EXPORT2
00377 u_fscanf(    UFILE        *f,
00378         const char     *patternSpecification,
00379         ... );
00380 
00394 U_CAPI int32_t U_EXPORT2
00395 u_vfscanf(    UFILE        *f,
00396         const char     *patternSpecification,
00397         va_list        ap);
00398 
00408 U_CAPI int32_t U_EXPORT2
00409 u_fscanf_u(    UFILE        *f,
00410         const UChar     *patternSpecification,
00411         ... );
00412 
00426 U_CAPI int32_t U_EXPORT2
00427 u_vfscanf_u(    UFILE        *f,
00428         const UChar     *patternSpecification,
00429         va_list        ap);
00430 
00443 U_CAPI UChar* U_EXPORT2
00444 u_fgets(UFILE        *f,
00445     int32_t        n,
00446     UChar        *s);
00447 
00454 U_CAPI UChar U_EXPORT2
00455 u_fgetc(UFILE        *f);
00456 
00471 U_CAPI UChar32 U_EXPORT2
00472 u_fgetcx(UFILE        *f);
00473 
00483 U_CAPI UChar U_EXPORT2
00484 u_fungetc(UChar        c,
00485       UFILE        *f);
00486 
00497 U_CAPI int32_t U_EXPORT2
00498 u_file_read(UChar        *chars, 
00499         int32_t        count, 
00500         UFILE         *f);
00501 
00502 #if !UCONFIG_NO_TRANSLITERATION
00503 
00521 U_CAPI UTransliterator* U_EXPORT2
00522 u_fsettransliterator(UFILE *file, UFileDirection direction,
00523                      UTransliterator *adopt, UErrorCode *status);
00524 
00525 #endif
00526 
00527 
00528 /* Output string functions */
00529 
00530 
00543 U_CAPI int32_t U_EXPORT2
00544 u_sprintf(UChar       *buffer,
00545         const char    *locale,
00546         const char    *patternSpecification,
00547         ... );
00548 
00567 U_CAPI int32_t U_EXPORT2
00568 u_snprintf(UChar      *buffer,
00569         int32_t       count,
00570         const char    *locale,
00571         const char    *patternSpecification,
00572         ... );
00573 
00589 U_CAPI int32_t U_EXPORT2
00590 u_vsprintf(UChar      *buffer,
00591         const char    *locale,
00592         const char    *patternSpecification,
00593         va_list        ap);
00594 
00616 U_CAPI int32_t U_EXPORT2
00617 u_vsnprintf(UChar     *buffer,
00618         int32_t       count,
00619         const char    *locale,
00620         const char    *patternSpecification,
00621         va_list        ap);
00622 
00634 U_CAPI int32_t U_EXPORT2
00635 u_sprintf_u(UChar      *buffer,
00636         const char     *locale,
00637         const UChar    *patternSpecification,
00638         ... );
00639 
00657 U_CAPI int32_t U_EXPORT2
00658 u_snprintf_u(UChar     *buffer,
00659         int32_t        count,
00660         const char     *locale,
00661         const UChar    *patternSpecification,
00662         ... );
00663 
00680 U_CAPI int32_t U_EXPORT2
00681 u_vsprintf_u(UChar     *buffer,
00682         const char    *locale,
00683         const UChar    *patternSpecification,
00684         va_list        ap);
00685 
00706 U_CAPI int32_t U_EXPORT2
00707 u_vsnprintf_u(UChar *buffer,
00708         int32_t         count,
00709         const char     *locale,
00710         const UChar     *patternSpecification,
00711         va_list         ap);
00712 
00713 /* Input string functions */
00714 
00727 U_CAPI int32_t U_EXPORT2
00728 u_sscanf(const UChar   *buffer,
00729         const char     *locale,
00730         const char     *patternSpecification,
00731         ... );
00732 
00749 U_CAPI int32_t U_EXPORT2
00750 u_vsscanf(const UChar  *buffer,
00751         const char     *locale,
00752         const char     *patternSpecification,
00753         va_list        ap);
00754 
00767 U_CAPI int32_t U_EXPORT2
00768 u_sscanf_u(const UChar  *buffer,
00769         const char      *locale,
00770         const UChar     *patternSpecification,
00771         ... );
00772 
00789 U_CAPI int32_t U_EXPORT2
00790 u_vsscanf_u(const UChar *buffer,
00791         const char      *locale,
00792         const UChar     *patternSpecification,
00793         va_list         ap);
00794 
00795 
00796 #endif
00797 
00798 
00799 

Generated on Thu Jun 12 13:09:29 2003 for ICU 2.6 by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001