ICU 4.8.1.1  4.8.1.1
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_STABLE 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 
00310 U_STABLE void U_EXPORT2
00311 u_fclose(UFILE *file);
00312 
00313 #if U_SHOW_CPLUSPLUS_API
00314 
00315 U_NAMESPACE_BEGIN
00316 
00326 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose);
00327 
00328 U_NAMESPACE_END
00329 
00330 #endif
00331 
00340 U_STABLE UBool U_EXPORT2
00341 u_feof(UFILE  *f);
00342 
00353 U_STABLE void U_EXPORT2
00354 u_fflush(UFILE *file);
00355 
00361 U_STABLE void
00362 u_frewind(UFILE *file);
00363 
00370 U_STABLE FILE* U_EXPORT2
00371 u_fgetfile(UFILE *f);
00372 
00373 #if !UCONFIG_NO_FORMATTING
00374 
00383 U_STABLE const char* U_EXPORT2
00384 u_fgetlocale(UFILE *file);
00385 
00394 U_STABLE int32_t U_EXPORT2
00395 u_fsetlocale(UFILE      *file,
00396              const char *locale);
00397 
00398 #endif
00399 
00409 U_STABLE const char* U_EXPORT2
00410 u_fgetcodepage(UFILE *file);
00411 
00427 U_STABLE int32_t U_EXPORT2
00428 u_fsetcodepage(const char   *codepage,
00429                UFILE        *file);
00430 
00431 
00438 U_STABLE UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
00439 
00440 #if !UCONFIG_NO_FORMATTING
00441 
00442 /* Output functions */
00443 
00452 U_STABLE int32_t U_EXPORT2
00453 u_fprintf(UFILE         *f,
00454           const char    *patternSpecification,
00455           ... );
00456 
00469 U_STABLE int32_t U_EXPORT2
00470 u_vfprintf(UFILE        *f,
00471            const char   *patternSpecification,
00472            va_list      ap);
00473 
00482 U_STABLE int32_t U_EXPORT2
00483 u_fprintf_u(UFILE       *f,
00484             const UChar *patternSpecification,
00485             ... );
00486 
00499 U_STABLE int32_t U_EXPORT2
00500 u_vfprintf_u(UFILE      *f,
00501             const UChar *patternSpecification,
00502             va_list     ap);
00503 #endif
00504 
00514 U_STABLE int32_t U_EXPORT2
00515 u_fputs(const UChar *s,
00516         UFILE       *f);
00517 
00525 U_STABLE UChar32 U_EXPORT2
00526 u_fputc(UChar32  uc,
00527         UFILE  *f);
00528 
00540 U_STABLE int32_t U_EXPORT2
00541 u_file_write(const UChar    *ustring, 
00542              int32_t        count, 
00543              UFILE          *f);
00544 
00545 
00546 /* Input functions */
00547 #if !UCONFIG_NO_FORMATTING
00548 
00558 U_STABLE int32_t U_EXPORT2
00559 u_fscanf(UFILE      *f,
00560          const char *patternSpecification,
00561          ... );
00562 
00576 U_STABLE int32_t U_EXPORT2
00577 u_vfscanf(UFILE         *f,
00578           const char    *patternSpecification,
00579           va_list        ap);
00580 
00590 U_STABLE int32_t U_EXPORT2
00591 u_fscanf_u(UFILE        *f,
00592            const UChar  *patternSpecification,
00593            ... );
00594 
00608 U_STABLE int32_t U_EXPORT2
00609 u_vfscanf_u(UFILE       *f,
00610             const UChar *patternSpecification,
00611             va_list      ap);
00612 #endif
00613 
00626 U_STABLE UChar* U_EXPORT2
00627 u_fgets(UChar  *s,
00628         int32_t n,
00629         UFILE  *f);
00630 
00640 U_STABLE UChar U_EXPORT2
00641 u_fgetc(UFILE   *f);
00642 
00653 U_STABLE UChar32 U_EXPORT2
00654 u_fgetcx(UFILE  *f);
00655 
00667 U_STABLE UChar32 U_EXPORT2
00668 u_fungetc(UChar32   c,
00669       UFILE        *f);
00670 
00681 U_STABLE int32_t U_EXPORT2
00682 u_file_read(UChar        *chars, 
00683         int32_t        count, 
00684         UFILE         *f);
00685 
00686 #if !UCONFIG_NO_TRANSLITERATION
00687 
00705 U_STABLE UTransliterator* U_EXPORT2
00706 u_fsettransliterator(UFILE *file, UFileDirection direction,
00707                      UTransliterator *adopt, UErrorCode *status);
00708 
00709 #endif
00710 
00711 
00712 /* Output string functions */
00713 #if !UCONFIG_NO_FORMATTING
00714 
00715 
00726 U_STABLE int32_t U_EXPORT2
00727 u_sprintf(UChar       *buffer,
00728         const char    *patternSpecification,
00729         ... );
00730 
00748 U_STABLE int32_t U_EXPORT2
00749 u_snprintf(UChar      *buffer,
00750         int32_t       count,
00751         const char    *patternSpecification,
00752         ... );
00753 
00767 U_STABLE int32_t U_EXPORT2
00768 u_vsprintf(UChar      *buffer,
00769         const char    *patternSpecification,
00770         va_list        ap);
00771 
00792 U_STABLE int32_t U_EXPORT2
00793 u_vsnprintf(UChar     *buffer,
00794         int32_t       count,
00795         const char    *patternSpecification,
00796         va_list        ap);
00797 
00807 U_STABLE int32_t U_EXPORT2
00808 u_sprintf_u(UChar      *buffer,
00809         const UChar    *patternSpecification,
00810         ... );
00811 
00828 U_STABLE int32_t U_EXPORT2
00829 u_snprintf_u(UChar     *buffer,
00830         int32_t        count,
00831         const UChar    *patternSpecification,
00832         ... );
00833 
00847 U_STABLE int32_t U_EXPORT2
00848 u_vsprintf_u(UChar     *buffer,
00849         const UChar    *patternSpecification,
00850         va_list        ap);
00851 
00872 U_STABLE int32_t U_EXPORT2
00873 u_vsnprintf_u(UChar *buffer,
00874         int32_t         count,
00875         const UChar     *patternSpecification,
00876         va_list         ap);
00877 
00878 /* Input string functions */
00879 
00890 U_STABLE int32_t U_EXPORT2
00891 u_sscanf(const UChar   *buffer,
00892         const char     *patternSpecification,
00893         ... );
00894 
00909 U_STABLE int32_t U_EXPORT2
00910 u_vsscanf(const UChar  *buffer,
00911         const char     *patternSpecification,
00912         va_list        ap);
00913 
00924 U_STABLE int32_t U_EXPORT2
00925 u_sscanf_u(const UChar  *buffer,
00926         const UChar     *patternSpecification,
00927         ... );
00928 
00943 U_STABLE int32_t U_EXPORT2
00944 u_vsscanf_u(const UChar *buffer,
00945         const UChar     *patternSpecification,
00946         va_list         ap);
00947 
00948 #endif
00949 #endif
00950 
00951 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines