Main Page | Class Hierarchy | Alphabetical List | Data Structures | File List | Data Fields | Globals

ustdio.h

Go to the documentation of this file.
00001 /*
00002 ******************************************************************************
00003 *
00004 *   Copyright (C) 1998-2004, 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 
00167 #define U_EOF 0xFFFF
00168 
00170 typedef struct UFILE UFILE;
00171 
00177 typedef enum { 
00178    U_READ = 1,
00179    U_WRITE = 2, 
00180    U_READWRITE =3  /* == (U_READ | U_WRITE) */ 
00181 } UFileDirection;
00182 
00200 U_CAPI UFILE* U_EXPORT2
00201 u_fopen(const char    *filename,
00202     const char    *perm,
00203     const char    *locale,
00204     const char    *codepage);
00205 
00219 U_CAPI UFILE* U_EXPORT2
00220 u_finit(FILE        *f,
00221     const char    *locale,
00222     const char    *codepage);
00223 
00238 U_CAPI UFILE* U_EXPORT2
00239 u_fstropen(UChar      *stringBuf,
00240            int32_t     capacity,
00241            const char *locale);
00242 
00248 U_CAPI void U_EXPORT2
00249 u_fclose(UFILE *file);
00250 
00259 U_CAPI UBool U_EXPORT2
00260 u_feof(UFILE  *f);
00261 
00270 U_CAPI void U_EXPORT2
00271 u_fflush(UFILE *file);
00272 
00278 U_CAPI void
00279 u_frewind(UFILE *file);
00280 
00287 U_CAPI FILE* U_EXPORT2
00288 u_fgetfile(UFILE *f);
00289 
00290 #if !UCONFIG_NO_FORMATTING
00291 
00300 U_CAPI const char* U_EXPORT2
00301 u_fgetlocale(UFILE *file);
00302 
00311 U_CAPI int32_t U_EXPORT2
00312 u_fsetlocale(UFILE      *file,
00313              const char *locale);
00314 
00315 #endif
00316 
00326 U_CAPI const char* U_EXPORT2
00327 u_fgetcodepage(UFILE *file);
00328 
00344 U_CAPI int32_t U_EXPORT2
00345 u_fsetcodepage(const char   *codepage,
00346                UFILE        *file);
00347 
00348 
00355 U_CAPI UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
00356 
00357 #if !UCONFIG_NO_FORMATTING
00358 
00359 /* Output functions */
00360 
00369 U_CAPI int32_t U_EXPORT2
00370 u_fprintf(UFILE         *f,
00371           const char    *patternSpecification,
00372           ... );
00373 
00386 U_CAPI int32_t U_EXPORT2
00387 u_vfprintf(UFILE        *f,
00388            const char   *patternSpecification,
00389            va_list      ap);
00390 
00399 U_CAPI int32_t U_EXPORT2
00400 u_fprintf_u(UFILE       *f,
00401             const UChar *patternSpecification,
00402             ... );
00403 
00416 U_CAPI int32_t U_EXPORT2
00417 u_vfprintf_u(UFILE      *f,
00418             const UChar *patternSpecification,
00419             va_list     ap);
00420 #endif
00421 
00431 U_CAPI int32_t U_EXPORT2
00432 u_fputs(const UChar *s,
00433         UFILE       *f);
00434 
00442 U_CAPI UChar32 U_EXPORT2
00443 u_fputc(UChar32  uc,
00444         UFILE  *f);
00445 
00457 U_CAPI int32_t U_EXPORT2
00458 u_file_write(const UChar    *ustring, 
00459              int32_t        count, 
00460              UFILE          *f);
00461 
00462 
00463 /* Input functions */
00464 #if !UCONFIG_NO_FORMATTING
00465 
00475 U_CAPI int32_t U_EXPORT2
00476 u_fscanf(UFILE      *f,
00477          const char *patternSpecification,
00478          ... );
00479 
00493 U_CAPI int32_t U_EXPORT2
00494 u_vfscanf(UFILE         *f,
00495           const char    *patternSpecification,
00496           va_list        ap);
00497 
00507 U_CAPI int32_t U_EXPORT2
00508 u_fscanf_u(UFILE        *f,
00509            const UChar  *patternSpecification,
00510            ... );
00511 
00525 U_CAPI int32_t U_EXPORT2
00526 u_vfscanf_u(UFILE       *f,
00527             const UChar *patternSpecification,
00528             va_list      ap);
00529 #endif
00530 
00543 U_CAPI UChar* U_EXPORT2
00544 u_fgets(UChar  *s,
00545         int32_t n,
00546         UFILE  *f);
00547 
00557 U_CAPI UChar U_EXPORT2
00558 u_fgetc(UFILE   *f);
00559 
00570 U_CAPI UChar32 U_EXPORT2
00571 u_fgetcx(UFILE  *f);
00572 
00584 U_CAPI UChar32 U_EXPORT2
00585 u_fungetc(UChar32   c,
00586       UFILE        *f);
00587 
00598 U_CAPI int32_t U_EXPORT2
00599 u_file_read(UChar        *chars, 
00600         int32_t        count, 
00601         UFILE         *f);
00602 
00603 #if !UCONFIG_NO_TRANSLITERATION
00604 
00622 U_CAPI UTransliterator* U_EXPORT2
00623 u_fsettransliterator(UFILE *file, UFileDirection direction,
00624                      UTransliterator *adopt, UErrorCode *status);
00625 
00626 #endif
00627 
00628 
00629 /* Output string functions */
00630 #if !UCONFIG_NO_FORMATTING
00631 
00632 
00643 U_CAPI int32_t U_EXPORT2
00644 u_sprintf(UChar       *buffer,
00645         const char    *patternSpecification,
00646         ... );
00647 
00664 U_CAPI int32_t U_EXPORT2
00665 u_snprintf(UChar      *buffer,
00666         int32_t       count,
00667         const char    *patternSpecification,
00668         ... );
00669 
00683 U_CAPI int32_t U_EXPORT2
00684 u_vsprintf(UChar      *buffer,
00685         const char    *patternSpecification,
00686         va_list        ap);
00687 
00707 U_CAPI int32_t U_EXPORT2
00708 u_vsnprintf(UChar     *buffer,
00709         int32_t       count,
00710         const char    *patternSpecification,
00711         va_list        ap);
00712 
00722 U_CAPI int32_t U_EXPORT2
00723 u_sprintf_u(UChar      *buffer,
00724         const UChar    *patternSpecification,
00725         ... );
00726 
00742 U_CAPI int32_t U_EXPORT2
00743 u_snprintf_u(UChar     *buffer,
00744         int32_t        count,
00745         const UChar    *patternSpecification,
00746         ... );
00747 
00761 U_CAPI int32_t U_EXPORT2
00762 u_vsprintf_u(UChar     *buffer,
00763         const UChar    *patternSpecification,
00764         va_list        ap);
00765 
00785 U_CAPI int32_t U_EXPORT2
00786 u_vsnprintf_u(UChar *buffer,
00787         int32_t         count,
00788         const UChar     *patternSpecification,
00789         va_list         ap);
00790 
00791 /* Input string functions */
00792 
00803 U_CAPI int32_t U_EXPORT2
00804 u_sscanf(const UChar   *buffer,
00805         const char     *patternSpecification,
00806         ... );
00807 
00822 U_CAPI int32_t U_EXPORT2
00823 u_vsscanf(const UChar  *buffer,
00824         const char     *patternSpecification,
00825         va_list        ap);
00826 
00837 U_CAPI int32_t U_EXPORT2
00838 u_sscanf_u(const UChar  *buffer,
00839         const UChar     *patternSpecification,
00840         ... );
00841 
00856 U_CAPI int32_t U_EXPORT2
00857 u_vsscanf_u(const UChar *buffer,
00858         const UChar     *patternSpecification,
00859         va_list         ap);
00860 
00861 #endif
00862 #endif
00863 
00864 

Generated on Tue Jul 26 00:40:02 2005 for ICU 3.2 by  doxygen 1.3.9.1