ustdio.h

Go to the documentation of this file.
00001 /*
00002 ******************************************************************************
00003 *
00004 *   Copyright (C) 1998-2010, 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 #include "unicode/localpointer.h"
00032 
00033 /*
00034     TODO
00035  The following is a small list as to what is currently wrong/suggestions for
00036  ustdio.
00037 
00038  * Make sure that * in the scanf format specification works for all formats.
00039  * Each UFILE takes up at least 2KB.
00040     Look into adding setvbuf() for configurable buffers.
00041  * This library does buffering. The OS should do this for us already. Check on
00042     this, and remove it from this library, if this is the case. Double buffering
00043     wastes a lot of time and space.
00044  * Test stdin and stdout with the u_f* functions
00045  * Testing should be done for reading and writing multi-byte encodings,
00046     and make sure that a character that is contained across buffer boundries
00047     works even for incomplete characters.
00048  * Make sure that the last character is flushed when the file/string is closed.
00049  * snprintf should follow the C99 standard for the return value, which is
00050     return the number of characters (excluding the trailing '\0')
00051     which would have been written to the destination string regardless
00052     of available space. This is like pre-flighting.
00053  * Everything that uses %s should do what operator>> does for UnicodeString.
00054     It should convert one byte at a time, and once a character is
00055     converted then check to see if it's whitespace or in the scanset.
00056     If it's whitespace or in the scanset, put all the bytes back (do nothing
00057     for sprintf/sscanf).
00058  * If bad string data is encountered, make sure that the function fails
00059     without memory leaks and the unconvertable characters are valid
00060     substitution or are escaped characters.
00061  * u_fungetc() can't unget a character when it's at the beginning of the
00062     internal conversion buffer. For example, read the buffer size # of
00063     characters, and then ungetc to get the previous character that was
00064     at the end of the last buffer.
00065  * u_fflush() and u_fclose should return an int32_t like C99 functions.
00066     0 is returned if the operation was successful and EOF otherwise.
00067  * u_fsettransliterator does not support U_READ side of transliteration.
00068  * The format specifier should limit the size of a format or honor it in
00069     order to prevent buffer overruns.  (e.g. %256.256d).
00070  * u_fread and u_fwrite don't exist. They're needed for reading and writing
00071     data structures without any conversion.
00072  * u_file_read and u_file_write are used for writing strings. u_fgets and
00073     u_fputs or u_fread and u_fwrite should be used to do this.
00074  * The width parameter for all scanf formats, including scanset, needs
00075     better testing. This prevents buffer overflows.
00076  * Figure out what is suppose to happen when a codepage is changed midstream.
00077     Maybe a flush or a rewind are good enough.
00078  * Make sure that a UFile opened with "rw" can be used after using
00079     u_fflush with a u_frewind.
00080  * scanf(%i) should detect what type of number to use.
00081  * Add more testing of the alternate format, %#
00082  * Look at newline handling of fputs/puts
00083  * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
00084  * Complete the file documentation with proper doxygen formatting.
00085     See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
00086 */
00087 
00204 #define U_EOF 0xFFFF
00205 
00207 typedef struct UFILE UFILE;
00208 
00214 typedef enum { 
00215    U_READ = 1,
00216    U_WRITE = 2, 
00217    U_READWRITE =3  /* == (U_READ | U_WRITE) */ 
00218 } UFileDirection;
00219 
00237 U_STABLE UFILE* U_EXPORT2
00238 u_fopen(const char    *filename,
00239     const char    *perm,
00240     const char    *locale,
00241     const char    *codepage);
00242 
00259 U_STABLE UFILE* U_EXPORT2
00260 u_finit(FILE        *f,
00261     const char    *locale,
00262     const char    *codepage);
00263 
00280 U_DRAFT UFILE* U_EXPORT2
00281 u_fadopt(FILE     *f,
00282     const char    *locale,
00283     const char    *codepage);
00284 
00299 U_STABLE UFILE* U_EXPORT2
00300 u_fstropen(UChar      *stringBuf,
00301            int32_t     capacity,
00302            const char *locale);
00303 
00309 U_STABLE void U_EXPORT2
00310 u_fclose(UFILE *file);
00311 
00312 #if U_SHOW_CPLUSPLUS_API
00313 
00314 U_NAMESPACE_BEGIN
00315 
00325 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose);
00326 
00327 U_NAMESPACE_END
00328 
00329 #endif
00330 
00339 U_STABLE UBool U_EXPORT2
00340 u_feof(UFILE  *f);
00341 
00350 U_STABLE void U_EXPORT2
00351 u_fflush(UFILE *file);
00352 
00358 U_STABLE void
00359 u_frewind(UFILE *file);
00360 
00367 U_STABLE FILE* U_EXPORT2
00368 u_fgetfile(UFILE *f);
00369 
00370 #if !UCONFIG_NO_FORMATTING
00371 
00380 U_STABLE const char* U_EXPORT2
00381 u_fgetlocale(UFILE *file);
00382 
00391 U_STABLE int32_t U_EXPORT2
00392 u_fsetlocale(UFILE      *file,
00393              const char *locale);
00394 
00395 #endif
00396 
00406 U_STABLE const char* U_EXPORT2
00407 u_fgetcodepage(UFILE *file);
00408 
00424 U_STABLE int32_t U_EXPORT2
00425 u_fsetcodepage(const char   *codepage,
00426                UFILE        *file);
00427 
00428 
00435 U_STABLE UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
00436 
00437 #if !UCONFIG_NO_FORMATTING
00438 
00439 /* Output functions */
00440 
00449 U_STABLE int32_t U_EXPORT2
00450 u_fprintf(UFILE         *f,
00451           const char    *patternSpecification,
00452           ... );
00453 
00466 U_STABLE int32_t U_EXPORT2
00467 u_vfprintf(UFILE        *f,
00468            const char   *patternSpecification,
00469            va_list      ap);
00470 
00479 U_STABLE int32_t U_EXPORT2
00480 u_fprintf_u(UFILE       *f,
00481             const UChar *patternSpecification,
00482             ... );
00483 
00496 U_STABLE int32_t U_EXPORT2
00497 u_vfprintf_u(UFILE      *f,
00498             const UChar *patternSpecification,
00499             va_list     ap);
00500 #endif
00501 
00511 U_STABLE int32_t U_EXPORT2
00512 u_fputs(const UChar *s,
00513         UFILE       *f);
00514 
00522 U_STABLE UChar32 U_EXPORT2
00523 u_fputc(UChar32  uc,
00524         UFILE  *f);
00525 
00537 U_STABLE int32_t U_EXPORT2
00538 u_file_write(const UChar    *ustring, 
00539              int32_t        count, 
00540              UFILE          *f);
00541 
00542 
00543 /* Input functions */
00544 #if !UCONFIG_NO_FORMATTING
00545 
00555 U_STABLE int32_t U_EXPORT2
00556 u_fscanf(UFILE      *f,
00557          const char *patternSpecification,
00558          ... );
00559 
00573 U_STABLE int32_t U_EXPORT2
00574 u_vfscanf(UFILE         *f,
00575           const char    *patternSpecification,
00576           va_list        ap);
00577 
00587 U_STABLE int32_t U_EXPORT2
00588 u_fscanf_u(UFILE        *f,
00589            const UChar  *patternSpecification,
00590            ... );
00591 
00605 U_STABLE int32_t U_EXPORT2
00606 u_vfscanf_u(UFILE       *f,
00607             const UChar *patternSpecification,
00608             va_list      ap);
00609 #endif
00610 
00623 U_STABLE UChar* U_EXPORT2
00624 u_fgets(UChar  *s,
00625         int32_t n,
00626         UFILE  *f);
00627 
00637 U_STABLE UChar U_EXPORT2
00638 u_fgetc(UFILE   *f);
00639 
00650 U_STABLE UChar32 U_EXPORT2
00651 u_fgetcx(UFILE  *f);
00652 
00664 U_STABLE UChar32 U_EXPORT2
00665 u_fungetc(UChar32   c,
00666       UFILE        *f);
00667 
00678 U_STABLE int32_t U_EXPORT2
00679 u_file_read(UChar        *chars, 
00680         int32_t        count, 
00681         UFILE         *f);
00682 
00683 #if !UCONFIG_NO_TRANSLITERATION
00684 
00702 U_STABLE UTransliterator* U_EXPORT2
00703 u_fsettransliterator(UFILE *file, UFileDirection direction,
00704                      UTransliterator *adopt, UErrorCode *status);
00705 
00706 #endif
00707 
00708 
00709 /* Output string functions */
00710 #if !UCONFIG_NO_FORMATTING
00711 
00712 
00723 U_STABLE int32_t U_EXPORT2
00724 u_sprintf(UChar       *buffer,
00725         const char    *patternSpecification,
00726         ... );
00727 
00745 U_STABLE int32_t U_EXPORT2
00746 u_snprintf(UChar      *buffer,
00747         int32_t       count,
00748         const char    *patternSpecification,
00749         ... );
00750 
00764 U_STABLE int32_t U_EXPORT2
00765 u_vsprintf(UChar      *buffer,
00766         const char    *patternSpecification,
00767         va_list        ap);
00768 
00789 U_STABLE int32_t U_EXPORT2
00790 u_vsnprintf(UChar     *buffer,
00791         int32_t       count,
00792         const char    *patternSpecification,
00793         va_list        ap);
00794 
00804 U_STABLE int32_t U_EXPORT2
00805 u_sprintf_u(UChar      *buffer,
00806         const UChar    *patternSpecification,
00807         ... );
00808 
00825 U_STABLE int32_t U_EXPORT2
00826 u_snprintf_u(UChar     *buffer,
00827         int32_t        count,
00828         const UChar    *patternSpecification,
00829         ... );
00830 
00844 U_STABLE int32_t U_EXPORT2
00845 u_vsprintf_u(UChar     *buffer,
00846         const UChar    *patternSpecification,
00847         va_list        ap);
00848 
00869 U_STABLE int32_t U_EXPORT2
00870 u_vsnprintf_u(UChar *buffer,
00871         int32_t         count,
00872         const UChar     *patternSpecification,
00873         va_list         ap);
00874 
00875 /* Input string functions */
00876 
00887 U_STABLE int32_t U_EXPORT2
00888 u_sscanf(const UChar   *buffer,
00889         const char     *patternSpecification,
00890         ... );
00891 
00906 U_STABLE int32_t U_EXPORT2
00907 u_vsscanf(const UChar  *buffer,
00908         const char     *patternSpecification,
00909         va_list        ap);
00910 
00921 U_STABLE int32_t U_EXPORT2
00922 u_sscanf_u(const UChar  *buffer,
00923         const UChar     *patternSpecification,
00924         ... );
00925 
00940 U_STABLE int32_t U_EXPORT2
00941 u_vsscanf_u(const UChar *buffer,
00942         const UChar     *patternSpecification,
00943         va_list         ap);
00944 
00945 #endif
00946 #endif
00947 
00948 

Generated on Tue Apr 27 15:10:35 2010 for ICU 4.4.1 by  doxygen 1.4.7