ustdio.h

Go to the documentation of this file.
00001 /*
00002 ******************************************************************************
00003 *
00004 *   Copyright (C) 1998-2006, 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 
00196 #ifndef U_HIDE_DRAFT_API
00197 
00202 typedef enum { 
00203    U_READ = 1,
00204    U_WRITE = 2, 
00205    U_READWRITE =3  /* == (U_READ | U_WRITE) */ 
00206 } UFileDirection;
00207 
00208 #endif /* U_HIDE_DRAFT_API */
00209 
00227 U_DRAFT UFILE* U_EXPORT2
00228 u_fopen(const char    *filename,
00229     const char    *perm,
00230     const char    *locale,
00231     const char    *codepage);
00232 
00246 U_DRAFT UFILE* U_EXPORT2
00247 u_finit(FILE        *f,
00248     const char    *locale,
00249     const char    *codepage);
00250 
00265 U_DRAFT UFILE* U_EXPORT2
00266 u_fstropen(UChar      *stringBuf,
00267            int32_t     capacity,
00268            const char *locale);
00269 
00275 U_DRAFT void U_EXPORT2
00276 u_fclose(UFILE *file);
00277 
00286 U_DRAFT UBool U_EXPORT2
00287 u_feof(UFILE  *f);
00288 
00297 U_DRAFT void U_EXPORT2
00298 u_fflush(UFILE *file);
00299 
00305 U_DRAFT void
00306 u_frewind(UFILE *file);
00307 
00314 U_DRAFT FILE* U_EXPORT2
00315 u_fgetfile(UFILE *f);
00316 
00317 #if !UCONFIG_NO_FORMATTING
00318 
00327 U_DRAFT const char* U_EXPORT2
00328 u_fgetlocale(UFILE *file);
00329 
00338 U_DRAFT int32_t U_EXPORT2
00339 u_fsetlocale(UFILE      *file,
00340              const char *locale);
00341 
00342 #endif
00343 
00353 U_DRAFT const char* U_EXPORT2
00354 u_fgetcodepage(UFILE *file);
00355 
00371 U_DRAFT int32_t U_EXPORT2
00372 u_fsetcodepage(const char   *codepage,
00373                UFILE        *file);
00374 
00375 
00382 U_DRAFT UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
00383 
00384 #if !UCONFIG_NO_FORMATTING
00385 
00386 /* Output functions */
00387 
00396 U_DRAFT int32_t U_EXPORT2
00397 u_fprintf(UFILE         *f,
00398           const char    *patternSpecification,
00399           ... );
00400 
00413 U_DRAFT int32_t U_EXPORT2
00414 u_vfprintf(UFILE        *f,
00415            const char   *patternSpecification,
00416            va_list      ap);
00417 
00426 U_DRAFT int32_t U_EXPORT2
00427 u_fprintf_u(UFILE       *f,
00428             const UChar *patternSpecification,
00429             ... );
00430 
00443 U_DRAFT int32_t U_EXPORT2
00444 u_vfprintf_u(UFILE      *f,
00445             const UChar *patternSpecification,
00446             va_list     ap);
00447 #endif
00448 
00458 U_DRAFT int32_t U_EXPORT2
00459 u_fputs(const UChar *s,
00460         UFILE       *f);
00461 
00469 U_DRAFT UChar32 U_EXPORT2
00470 u_fputc(UChar32  uc,
00471         UFILE  *f);
00472 
00484 U_DRAFT int32_t U_EXPORT2
00485 u_file_write(const UChar    *ustring, 
00486              int32_t        count, 
00487              UFILE          *f);
00488 
00489 
00490 /* Input functions */
00491 #if !UCONFIG_NO_FORMATTING
00492 
00502 U_DRAFT int32_t U_EXPORT2
00503 u_fscanf(UFILE      *f,
00504          const char *patternSpecification,
00505          ... );
00506 
00520 U_DRAFT int32_t U_EXPORT2
00521 u_vfscanf(UFILE         *f,
00522           const char    *patternSpecification,
00523           va_list        ap);
00524 
00534 U_DRAFT int32_t U_EXPORT2
00535 u_fscanf_u(UFILE        *f,
00536            const UChar  *patternSpecification,
00537            ... );
00538 
00552 U_DRAFT int32_t U_EXPORT2
00553 u_vfscanf_u(UFILE       *f,
00554             const UChar *patternSpecification,
00555             va_list      ap);
00556 #endif
00557 
00570 U_DRAFT UChar* U_EXPORT2
00571 u_fgets(UChar  *s,
00572         int32_t n,
00573         UFILE  *f);
00574 
00584 U_DRAFT UChar U_EXPORT2
00585 u_fgetc(UFILE   *f);
00586 
00597 U_DRAFT UChar32 U_EXPORT2
00598 u_fgetcx(UFILE  *f);
00599 
00611 U_DRAFT UChar32 U_EXPORT2
00612 u_fungetc(UChar32   c,
00613       UFILE        *f);
00614 
00625 U_DRAFT int32_t U_EXPORT2
00626 u_file_read(UChar        *chars, 
00627         int32_t        count, 
00628         UFILE         *f);
00629 
00630 #if !UCONFIG_NO_TRANSLITERATION
00631 
00649 U_DRAFT UTransliterator* U_EXPORT2
00650 u_fsettransliterator(UFILE *file, UFileDirection direction,
00651                      UTransliterator *adopt, UErrorCode *status);
00652 
00653 #endif
00654 
00655 
00656 /* Output string functions */
00657 #if !UCONFIG_NO_FORMATTING
00658 
00659 
00670 U_DRAFT int32_t U_EXPORT2
00671 u_sprintf(UChar       *buffer,
00672         const char    *patternSpecification,
00673         ... );
00674 
00691 U_DRAFT int32_t U_EXPORT2
00692 u_snprintf(UChar      *buffer,
00693         int32_t       count,
00694         const char    *patternSpecification,
00695         ... );
00696 
00710 U_DRAFT int32_t U_EXPORT2
00711 u_vsprintf(UChar      *buffer,
00712         const char    *patternSpecification,
00713         va_list        ap);
00714 
00734 U_DRAFT int32_t U_EXPORT2
00735 u_vsnprintf(UChar     *buffer,
00736         int32_t       count,
00737         const char    *patternSpecification,
00738         va_list        ap);
00739 
00749 U_DRAFT int32_t U_EXPORT2
00750 u_sprintf_u(UChar      *buffer,
00751         const UChar    *patternSpecification,
00752         ... );
00753 
00769 U_DRAFT int32_t U_EXPORT2
00770 u_snprintf_u(UChar     *buffer,
00771         int32_t        count,
00772         const UChar    *patternSpecification,
00773         ... );
00774 
00788 U_DRAFT int32_t U_EXPORT2
00789 u_vsprintf_u(UChar     *buffer,
00790         const UChar    *patternSpecification,
00791         va_list        ap);
00792 
00812 U_DRAFT int32_t U_EXPORT2
00813 u_vsnprintf_u(UChar *buffer,
00814         int32_t         count,
00815         const UChar     *patternSpecification,
00816         va_list         ap);
00817 
00818 /* Input string functions */
00819 
00830 U_DRAFT int32_t U_EXPORT2
00831 u_sscanf(const UChar   *buffer,
00832         const char     *patternSpecification,
00833         ... );
00834 
00849 U_DRAFT int32_t U_EXPORT2
00850 u_vsscanf(const UChar  *buffer,
00851         const char     *patternSpecification,
00852         va_list        ap);
00853 
00864 U_DRAFT int32_t U_EXPORT2
00865 u_sscanf_u(const UChar  *buffer,
00866         const UChar     *patternSpecification,
00867         ... );
00868 
00883 U_DRAFT int32_t U_EXPORT2
00884 u_vsscanf_u(const UChar *buffer,
00885         const UChar     *patternSpecification,
00886         va_list         ap);
00887 
00888 #endif
00889 #endif
00890 
00891 

Generated on Mon Aug 13 07:17:24 2007 for ICU 3.6 by  doxygen 1.5.2