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

- File List
- Globals

# 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

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines