ustdio.h

Go to the documentation of this file.
00001 /*
00002 ******************************************************************************
00003 *
00004 *   Copyright (C) 1998-2005, 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  * Make sure that * in the scanf format specification works for all formats.
00038  * Each UFILE takes up at least 2KB.
00039     Look into adding setvbuf() for configurable buffers.
00040  * This library does buffering. The OS should do this for us already. Check on
00041     this, and remove it from this library, if this is the case. Double buffering
00042     wastes a lot of time and space.
00043  * Test stdin and stdout with the u_f* functions
00044  * Testing should be done for reading and writing multi-byte encodings,
00045     and make sure that a character that is contained across buffer boundries
00046     works even for incomplete characters.
00047  * Make sure that the last character is flushed when the file/string is closed.
00048  * snprintf should follow the C99 standard for the return value, which is
00049     return the number of characters (excluding the trailing '\0')
00050     which would have been written to the destination string regardless
00051     of available space. This is like pre-flighting.
00052  * Everything that uses %s should do what operator>> does for UnicodeString.
00053     It should convert one byte at a time, and once a character is
00054     converted then check to see if it's whitespace or in the scanset.
00055     If it's whitespace or in the scanset, put all the bytes back (do nothing
00056     for sprintf/sscanf).
00057  * If bad string data is encountered, make sure that the function fails
00058     without memory leaks and the unconvertable characters are valid
00059     substitution or are escaped characters.
00060  * u_fungetc() can't unget a character when it's at the beginning of the
00061     internal conversion buffer. For example, read the buffer size # of
00062     characters, and then ungetc to get the previous character that was
00063     at the end of the last buffer.
00064  * u_fflush() and u_fclose should return an int32_t like C99 functions.
00065     0 is returned if the operation was successful and EOF otherwise.
00066  * u_fsettransliterator does not support U_READ side of transliteration.
00067  * The format specifier should limit the size of a format or honor it in
00068     order to prevent buffer overruns.  (e.g. %256.256d).
00069  * u_fread and u_fwrite don't exist. They're needed for reading and writing
00070     data structures without any conversion.
00071  * u_file_read and u_file_write are used for writing strings. u_fgets and
00072     u_fputs or u_fread and u_fwrite should be used to do this.
00073  * The width parameter for all scanf formats, including scanset, needs
00074     better testing. This prevents buffer overflows.
00075  * Figure out what is suppose to happen when a codepage is changed midstream.
00076     Maybe a flush or a rewind are good enough.
00077  * Make sure that a UFile opened with "rw" can be used after using
00078     u_fflush with a u_frewind.
00079  * scanf(%i) should detect what type of number to use.
00080  * Add more testing of the alternate format, %#
00081  * Look at newline handling of fputs/puts
00082  * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
00083  * Complete the file documentation with proper doxygen formatting.
00084     See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
00085 */
00086 
00191 #define U_EOF 0xFFFF
00192 
00194 typedef struct UFILE UFILE;
00195 
00201 typedef enum { 
00202    U_READ = 1,
00203    U_WRITE = 2, 
00204    U_READWRITE =3  /* == (U_READ | U_WRITE) */ 
00205 } UFileDirection;
00206 
00224 U_CAPI UFILE* U_EXPORT2
00225 u_fopen(const char    *filename,
00226     const char    *perm,
00227     const char    *locale,
00228     const char    *codepage);
00229 
00243 U_CAPI UFILE* U_EXPORT2
00244 u_finit(FILE        *f,
00245     const char    *locale,
00246     const char    *codepage);
00247 
00262 U_CAPI UFILE* U_EXPORT2
00263 u_fstropen(UChar      *stringBuf,
00264            int32_t     capacity,
00265            const char *locale);
00266 
00272 U_CAPI void U_EXPORT2
00273 u_fclose(UFILE *file);
00274 
00283 U_CAPI UBool U_EXPORT2
00284 u_feof(UFILE  *f);
00285 
00294 U_CAPI void U_EXPORT2
00295 u_fflush(UFILE *file);
00296 
00302 U_CAPI void
00303 u_frewind(UFILE *file);
00304 
00311 U_CAPI FILE* U_EXPORT2
00312 u_fgetfile(UFILE *f);
00313 
00314 #if !UCONFIG_NO_FORMATTING
00315 
00324 U_CAPI const char* U_EXPORT2
00325 u_fgetlocale(UFILE *file);
00326 
00335 U_CAPI int32_t U_EXPORT2
00336 u_fsetlocale(UFILE      *file,
00337              const char *locale);
00338 
00339 #endif
00340 
00350 U_CAPI const char* U_EXPORT2
00351 u_fgetcodepage(UFILE *file);
00352 
00368 U_CAPI int32_t U_EXPORT2
00369 u_fsetcodepage(const char   *codepage,
00370                UFILE        *file);
00371 
00372 
00379 U_CAPI UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
00380 
00381 #if !UCONFIG_NO_FORMATTING
00382 
00383 /* Output functions */
00384 
00393 U_CAPI int32_t U_EXPORT2
00394 u_fprintf(UFILE         *f,
00395           const char    *patternSpecification,
00396           ... );
00397 
00410 U_CAPI int32_t U_EXPORT2
00411 u_vfprintf(UFILE        *f,
00412            const char   *patternSpecification,
00413            va_list      ap);
00414 
00423 U_CAPI int32_t U_EXPORT2
00424 u_fprintf_u(UFILE       *f,
00425             const UChar *patternSpecification,
00426             ... );
00427 
00440 U_CAPI int32_t U_EXPORT2
00441 u_vfprintf_u(UFILE      *f,
00442             const UChar *patternSpecification,
00443             va_list     ap);
00444 #endif
00445 
00455 U_CAPI int32_t U_EXPORT2
00456 u_fputs(const UChar *s,
00457         UFILE       *f);
00458 
00466 U_CAPI UChar32 U_EXPORT2
00467 u_fputc(UChar32  uc,
00468         UFILE  *f);
00469 
00481 U_CAPI int32_t U_EXPORT2
00482 u_file_write(const UChar    *ustring, 
00483              int32_t        count, 
00484              UFILE          *f);
00485 
00486 
00487 /* Input functions */
00488 #if !UCONFIG_NO_FORMATTING
00489 
00499 U_CAPI int32_t U_EXPORT2
00500 u_fscanf(UFILE      *f,
00501          const char *patternSpecification,
00502          ... );
00503 
00517 U_CAPI int32_t U_EXPORT2
00518 u_vfscanf(UFILE         *f,
00519           const char    *patternSpecification,
00520           va_list        ap);
00521 
00531 U_CAPI int32_t U_EXPORT2
00532 u_fscanf_u(UFILE        *f,
00533            const UChar  *patternSpecification,
00534            ... );
00535 
00549 U_CAPI int32_t U_EXPORT2
00550 u_vfscanf_u(UFILE       *f,
00551             const UChar *patternSpecification,
00552             va_list      ap);
00553 #endif
00554 
00567 U_CAPI UChar* U_EXPORT2
00568 u_fgets(UChar  *s,
00569         int32_t n,
00570         UFILE  *f);
00571 
00581 U_CAPI UChar U_EXPORT2
00582 u_fgetc(UFILE   *f);
00583 
00594 U_CAPI UChar32 U_EXPORT2
00595 u_fgetcx(UFILE  *f);
00596 
00608 U_CAPI UChar32 U_EXPORT2
00609 u_fungetc(UChar32   c,
00610       UFILE        *f);
00611 
00622 U_CAPI int32_t U_EXPORT2
00623 u_file_read(UChar        *chars, 
00624         int32_t        count, 
00625         UFILE         *f);
00626 
00627 #if !UCONFIG_NO_TRANSLITERATION
00628 
00646 U_CAPI UTransliterator* U_EXPORT2
00647 u_fsettransliterator(UFILE *file, UFileDirection direction,
00648                      UTransliterator *adopt, UErrorCode *status);
00649 
00650 #endif
00651 
00652 
00653 /* Output string functions */
00654 #if !UCONFIG_NO_FORMATTING
00655 
00656 
00667 U_CAPI int32_t U_EXPORT2
00668 u_sprintf(UChar       *buffer,
00669         const char    *patternSpecification,
00670         ... );
00671 
00688 U_CAPI int32_t U_EXPORT2
00689 u_snprintf(UChar      *buffer,
00690         int32_t       count,
00691         const char    *patternSpecification,
00692         ... );
00693 
00707 U_CAPI int32_t U_EXPORT2
00708 u_vsprintf(UChar      *buffer,
00709         const char    *patternSpecification,
00710         va_list        ap);
00711 
00731 U_CAPI int32_t U_EXPORT2
00732 u_vsnprintf(UChar     *buffer,
00733         int32_t       count,
00734         const char    *patternSpecification,
00735         va_list        ap);
00736 
00746 U_CAPI int32_t U_EXPORT2
00747 u_sprintf_u(UChar      *buffer,
00748         const UChar    *patternSpecification,
00749         ... );
00750 
00766 U_CAPI int32_t U_EXPORT2
00767 u_snprintf_u(UChar     *buffer,
00768         int32_t        count,
00769         const UChar    *patternSpecification,
00770         ... );
00771 
00785 U_CAPI int32_t U_EXPORT2
00786 u_vsprintf_u(UChar     *buffer,
00787         const UChar    *patternSpecification,
00788         va_list        ap);
00789 
00809 U_CAPI int32_t U_EXPORT2
00810 u_vsnprintf_u(UChar *buffer,
00811         int32_t         count,
00812         const UChar     *patternSpecification,
00813         va_list         ap);
00814 
00815 /* Input string functions */
00816 
00827 U_CAPI int32_t U_EXPORT2
00828 u_sscanf(const UChar   *buffer,
00829         const char     *patternSpecification,
00830         ... );
00831 
00846 U_CAPI int32_t U_EXPORT2
00847 u_vsscanf(const UChar  *buffer,
00848         const char     *patternSpecification,
00849         va_list        ap);
00850 
00861 U_CAPI int32_t U_EXPORT2
00862 u_sscanf_u(const UChar  *buffer,
00863         const UChar     *patternSpecification,
00864         ... );
00865 
00880 U_CAPI int32_t U_EXPORT2
00881 u_vsscanf_u(const UChar *buffer,
00882         const UChar     *patternSpecification,
00883         va_list         ap);
00884 
00885 #endif
00886 #endif
00887 
00888 

Generated on Tue Feb 28 01:37:40 2006 for ICU 3.4 by  doxygen 1.4.4