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

- Search for |

- File List
- Globals

# ustdio.h

Go to the documentation of this file.

    00001 /*
    00002 ******************************************************************************
    00003 *
    00004 *   Copyright (C) 1998-2007, 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
    00208 #ifndef U_HIDE_DRAFT_API
    00209
    00214 typedef enum {
    00215    U_READ = 1,
    00216    U_WRITE = 2,
    00217    U_READWRITE =3  /* == (U_READ | U_WRITE) */
    00218 } UFileDirection;
    00219
    00220 #endif /* U_HIDE_DRAFT_API */
    00221
    00239 U_DRAFT UFILE* U_EXPORT2
    00240 u_fopen(const char    *filename,
    00241     const char    *perm,
    00242     const char    *locale,
    00243     const char    *codepage);
    00244
    00258 U_DRAFT UFILE* U_EXPORT2
    00259 u_finit(FILE        *f,
    00260     const char    *locale,
    00261     const char    *codepage);
    00262
    00277 U_DRAFT UFILE* U_EXPORT2
    00278 u_fstropen(UChar      *stringBuf,
    00279            int32_t     capacity,
    00280            const char *locale);
    00281
    00287 U_DRAFT void U_EXPORT2
    00288 u_fclose(UFILE *file);
    00289
    00298 U_DRAFT UBool U_EXPORT2
    00299 u_feof(UFILE  *f);
    00300
    00309 U_DRAFT void U_EXPORT2
    00310 u_fflush(UFILE *file);
    00311
    00317 U_DRAFT void
    00318 u_frewind(UFILE *file);
    00319
    00326 U_DRAFT FILE* U_EXPORT2
    00327 u_fgetfile(UFILE *f);
    00328
    00329 #if !UCONFIG_NO_FORMATTING
    00330
    00339 U_DRAFT const char* U_EXPORT2
    00340 u_fgetlocale(UFILE *file);
    00341
    00350 U_DRAFT int32_t U_EXPORT2
    00351 u_fsetlocale(UFILE      *file,
    00352              const char *locale);
    00353
    00354 #endif
    00355
    00365 U_DRAFT const char* U_EXPORT2
    00366 u_fgetcodepage(UFILE *file);
    00367
    00383 U_DRAFT int32_t U_EXPORT2
    00384 u_fsetcodepage(const char   *codepage,
    00385                UFILE        *file);
    00386
    00387
    00394 U_DRAFT UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
    00395
    00396 #if !UCONFIG_NO_FORMATTING
    00397
    00398 /* Output functions */
    00399
    00408 U_DRAFT int32_t U_EXPORT2
    00409 u_fprintf(UFILE         *f,
    00410           const char    *patternSpecification,
    00411           ... );
    00412
    00425 U_DRAFT int32_t U_EXPORT2
    00426 u_vfprintf(UFILE        *f,
    00427            const char   *patternSpecification,
    00428            va_list      ap);
    00429
    00438 U_DRAFT int32_t U_EXPORT2
    00439 u_fprintf_u(UFILE       *f,
    00440             const UChar *patternSpecification,
    00441             ... );
    00442
    00455 U_DRAFT int32_t U_EXPORT2
    00456 u_vfprintf_u(UFILE      *f,
    00457             const UChar *patternSpecification,
    00458             va_list     ap);
    00459 #endif
    00460
    00470 U_DRAFT int32_t U_EXPORT2
    00471 u_fputs(const UChar *s,
    00472         UFILE       *f);
    00473
    00481 U_DRAFT UChar32 U_EXPORT2
    00482 u_fputc(UChar32  uc,
    00483         UFILE  *f);
    00484
    00496 U_DRAFT int32_t U_EXPORT2
    00497 u_file_write(const UChar    *ustring,
    00498              int32_t        count,
    00499              UFILE          *f);
    00500
    00501
    00502 /* Input functions */
    00503 #if !UCONFIG_NO_FORMATTING
    00504
    00514 U_DRAFT int32_t U_EXPORT2
    00515 u_fscanf(UFILE      *f,
    00516          const char *patternSpecification,
    00517          ... );
    00518
    00532 U_DRAFT int32_t U_EXPORT2
    00533 u_vfscanf(UFILE         *f,
    00534           const char    *patternSpecification,
    00535           va_list        ap);
    00536
    00546 U_DRAFT int32_t U_EXPORT2
    00547 u_fscanf_u(UFILE        *f,
    00548            const UChar  *patternSpecification,
    00549            ... );
    00550
    00564 U_DRAFT int32_t U_EXPORT2
    00565 u_vfscanf_u(UFILE       *f,
    00566             const UChar *patternSpecification,
    00567             va_list      ap);
    00568 #endif
    00569
    00582 U_DRAFT UChar* U_EXPORT2
    00583 u_fgets(UChar  *s,
    00584         int32_t n,
    00585         UFILE  *f);
    00586
    00596 U_DRAFT UChar U_EXPORT2
    00597 u_fgetc(UFILE   *f);
    00598
    00609 U_DRAFT UChar32 U_EXPORT2
    00610 u_fgetcx(UFILE  *f);
    00611
    00623 U_DRAFT UChar32 U_EXPORT2
    00624 u_fungetc(UChar32   c,
    00625       UFILE        *f);
    00626
    00637 U_DRAFT int32_t U_EXPORT2
    00638 u_file_read(UChar        *chars,
    00639         int32_t        count,
    00640         UFILE         *f);
    00641
    00642 #if !UCONFIG_NO_TRANSLITERATION
    00643
    00661 U_DRAFT UTransliterator* U_EXPORT2
    00662 u_fsettransliterator(UFILE *file, UFileDirection direction,
    00663                      UTransliterator *adopt, UErrorCode *status);
    00664
    00665 #endif
    00666
    00667
    00668 /* Output string functions */
    00669 #if !UCONFIG_NO_FORMATTING
    00670
    00671
    00682 U_DRAFT int32_t U_EXPORT2
    00683 u_sprintf(UChar       *buffer,
    00684         const char    *patternSpecification,
    00685         ... );
    00686
    00703 U_DRAFT int32_t U_EXPORT2
    00704 u_snprintf(UChar      *buffer,
    00705         int32_t       count,
    00706         const char    *patternSpecification,
    00707         ... );
    00708
    00722 U_DRAFT int32_t U_EXPORT2
    00723 u_vsprintf(UChar      *buffer,
    00724         const char    *patternSpecification,
    00725         va_list        ap);
    00726
    00746 U_DRAFT int32_t U_EXPORT2
    00747 u_vsnprintf(UChar     *buffer,
    00748         int32_t       count,
    00749         const char    *patternSpecification,
    00750         va_list        ap);
    00751
    00761 U_DRAFT int32_t U_EXPORT2
    00762 u_sprintf_u(UChar      *buffer,
    00763         const UChar    *patternSpecification,
    00764         ... );
    00765
    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
    00824 U_DRAFT int32_t U_EXPORT2
    00825 u_vsnprintf_u(UChar *buffer,
    00826         int32_t         count,
    00827         const UChar     *patternSpecification,
    00828         va_list         ap);
    00829
    00830 /* Input string functions */
    00831
    00842 U_DRAFT int32_t U_EXPORT2
    00843 u_sscanf(const UChar   *buffer,
    00844         const char     *patternSpecification,
    00845         ... );
    00846
    00861 U_DRAFT int32_t U_EXPORT2
    00862 u_vsscanf(const UChar  *buffer,
    00863         const char     *patternSpecification,
    00864         va_list        ap);
    00865
    00876 U_DRAFT int32_t U_EXPORT2
    00877 u_sscanf_u(const UChar  *buffer,
    00878         const UChar     *patternSpecification,
    00879         ... );
    00880
    00895 U_DRAFT int32_t U_EXPORT2
    00896 u_vsscanf_u(const UChar *buffer,
    00897         const UChar     *patternSpecification,
    00898         va_list         ap);
    00899
    00900 #endif
    00901 #endif
    00902
    00903