- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- Search for |

- File List
- Globals

# ustdio.h

Go to the documentation of this file.

    00001 /*
    00002 ******************************************************************************
    00003 *
    00004 *   Copyright (C) 1998-2009, 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
    00203 #define U_EOF 0xFFFF
    00204
    00206 typedef struct UFILE UFILE;
    00207
    00213 typedef enum {
    00214    U_READ = 1,
    00215    U_WRITE = 2,
    00216    U_READWRITE =3  /* == (U_READ | U_WRITE) */
    00217 } UFileDirection;
    00218
    00236 U_DRAFT UFILE* U_EXPORT2
    00237 u_fopen(const char    *filename,
    00238     const char    *perm,
    00239     const char    *locale,
    00240     const char    *codepage);
    00241
    00255 U_DRAFT UFILE* U_EXPORT2
    00256 u_finit(FILE        *f,
    00257     const char    *locale,
    00258     const char    *codepage);
    00259
    00274 U_DRAFT UFILE* U_EXPORT2
    00275 u_fstropen(UChar      *stringBuf,
    00276            int32_t     capacity,
    00277            const char *locale);
    00278
    00284 U_DRAFT void U_EXPORT2
    00285 u_fclose(UFILE *file);
    00286
    00295 U_DRAFT UBool U_EXPORT2
    00296 u_feof(UFILE  *f);
    00297
    00306 U_DRAFT void U_EXPORT2
    00307 u_fflush(UFILE *file);
    00308
    00314 U_DRAFT void
    00315 u_frewind(UFILE *file);
    00316
    00323 U_DRAFT FILE* U_EXPORT2
    00324 u_fgetfile(UFILE *f);
    00325
    00326 #if !UCONFIG_NO_FORMATTING
    00327
    00336 U_DRAFT const char* U_EXPORT2
    00337 u_fgetlocale(UFILE *file);
    00338
    00347 U_DRAFT int32_t U_EXPORT2
    00348 u_fsetlocale(UFILE      *file,
    00349              const char *locale);
    00350
    00351 #endif
    00352
    00362 U_DRAFT const char* U_EXPORT2
    00363 u_fgetcodepage(UFILE *file);
    00364
    00380 U_DRAFT int32_t U_EXPORT2
    00381 u_fsetcodepage(const char   *codepage,
    00382                UFILE        *file);
    00383
    00384
    00391 U_DRAFT UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
    00392
    00393 #if !UCONFIG_NO_FORMATTING
    00394
    00395 /* Output functions */
    00396
    00405 U_DRAFT int32_t U_EXPORT2
    00406 u_fprintf(UFILE         *f,
    00407           const char    *patternSpecification,
    00408           ... );
    00409
    00422 U_DRAFT int32_t U_EXPORT2
    00423 u_vfprintf(UFILE        *f,
    00424            const char   *patternSpecification,
    00425            va_list      ap);
    00426
    00435 U_DRAFT int32_t U_EXPORT2
    00436 u_fprintf_u(UFILE       *f,
    00437             const UChar *patternSpecification,
    00438             ... );
    00439
    00452 U_DRAFT int32_t U_EXPORT2
    00453 u_vfprintf_u(UFILE      *f,
    00454             const UChar *patternSpecification,
    00455             va_list     ap);
    00456 #endif
    00457
    00467 U_DRAFT int32_t U_EXPORT2
    00468 u_fputs(const UChar *s,
    00469         UFILE       *f);
    00470
    00478 U_DRAFT UChar32 U_EXPORT2
    00479 u_fputc(UChar32  uc,
    00480         UFILE  *f);
    00481
    00493 U_DRAFT int32_t U_EXPORT2
    00494 u_file_write(const UChar    *ustring,
    00495              int32_t        count,
    00496              UFILE          *f);
    00497
    00498
    00499 /* Input functions */
    00500 #if !UCONFIG_NO_FORMATTING
    00501
    00511 U_DRAFT int32_t U_EXPORT2
    00512 u_fscanf(UFILE      *f,
    00513          const char *patternSpecification,
    00514          ... );
    00515
    00529 U_DRAFT int32_t U_EXPORT2
    00530 u_vfscanf(UFILE         *f,
    00531           const char    *patternSpecification,
    00532           va_list        ap);
    00533
    00543 U_DRAFT int32_t U_EXPORT2
    00544 u_fscanf_u(UFILE        *f,
    00545            const UChar  *patternSpecification,
    00546            ... );
    00547
    00561 U_DRAFT int32_t U_EXPORT2
    00562 u_vfscanf_u(UFILE       *f,
    00563             const UChar *patternSpecification,
    00564             va_list      ap);
    00565 #endif
    00566
    00579 U_DRAFT UChar* U_EXPORT2
    00580 u_fgets(UChar  *s,
    00581         int32_t n,
    00582         UFILE  *f);
    00583
    00593 U_DRAFT UChar U_EXPORT2
    00594 u_fgetc(UFILE   *f);
    00595
    00606 U_DRAFT UChar32 U_EXPORT2
    00607 u_fgetcx(UFILE  *f);
    00608
    00620 U_DRAFT UChar32 U_EXPORT2
    00621 u_fungetc(UChar32   c,
    00622       UFILE        *f);
    00623
    00634 U_DRAFT int32_t U_EXPORT2
    00635 u_file_read(UChar        *chars,
    00636         int32_t        count,
    00637         UFILE         *f);
    00638
    00639 #if !UCONFIG_NO_TRANSLITERATION
    00640
    00658 U_DRAFT UTransliterator* U_EXPORT2
    00659 u_fsettransliterator(UFILE *file, UFileDirection direction,
    00660                      UTransliterator *adopt, UErrorCode *status);
    00661
    00662 #endif
    00663
    00664
    00665 /* Output string functions */
    00666 #if !UCONFIG_NO_FORMATTING
    00667
    00668
    00679 U_DRAFT int32_t U_EXPORT2
    00680 u_sprintf(UChar       *buffer,
    00681         const char    *patternSpecification,
    00682         ... );
    00683
    00701 U_DRAFT int32_t U_EXPORT2
    00702 u_snprintf(UChar      *buffer,
    00703         int32_t       count,
    00704         const char    *patternSpecification,
    00705         ... );
    00706
    00720 U_DRAFT int32_t U_EXPORT2
    00721 u_vsprintf(UChar      *buffer,
    00722         const char    *patternSpecification,
    00723         va_list        ap);
    00724
    00745 U_DRAFT int32_t U_EXPORT2
    00746 u_vsnprintf(UChar     *buffer,
    00747         int32_t       count,
    00748         const char    *patternSpecification,
    00749         va_list        ap);
    00750
    00760 U_DRAFT int32_t U_EXPORT2
    00761 u_sprintf_u(UChar      *buffer,
    00762         const UChar    *patternSpecification,
    00763         ... );
    00764
    00781 U_DRAFT int32_t U_EXPORT2
    00782 u_snprintf_u(UChar     *buffer,
    00783         int32_t        count,
    00784         const UChar    *patternSpecification,
    00785         ... );
    00786
    00800 U_DRAFT int32_t U_EXPORT2
    00801 u_vsprintf_u(UChar     *buffer,
    00802         const UChar    *patternSpecification,
    00803         va_list        ap);
    00804
    00825 U_DRAFT int32_t U_EXPORT2
    00826 u_vsnprintf_u(UChar *buffer,
    00827         int32_t         count,
    00828         const UChar     *patternSpecification,
    00829         va_list         ap);
    00830
    00831 /* Input string functions */
    00832
    00843 U_DRAFT int32_t U_EXPORT2
    00844 u_sscanf(const UChar   *buffer,
    00845         const char     *patternSpecification,
    00846         ... );
    00847
    00862 U_DRAFT int32_t U_EXPORT2
    00863 u_vsscanf(const UChar  *buffer,
    00864         const char     *patternSpecification,
    00865         va_list        ap);
    00866
    00877 U_DRAFT int32_t U_EXPORT2
    00878 u_sscanf_u(const UChar  *buffer,
    00879         const UChar     *patternSpecification,
    00880         ... );
    00881
    00896 U_DRAFT int32_t U_EXPORT2
    00897 u_vsscanf_u(const UChar *buffer,
    00898         const UChar     *patternSpecification,
    00899         va_list         ap);
    00900
    00901 #endif
    00902 #endif
    00903
    00904