ustdio.h

Go to the documentation of this file.
00001 /*
00002 ******************************************************************************
00003 *
00004 *   Copyright (C) 1998-2012, 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 
00451 U_DRAFT int32_t U_EXPORT2
00452 u_printf(const char *patternSpecification,
00453          ... );
00454 
00463 U_STABLE int32_t U_EXPORT2
00464 u_fprintf(UFILE         *f,
00465           const char    *patternSpecification,
00466           ... );
00467 
00480 U_STABLE int32_t U_EXPORT2
00481 u_vfprintf(UFILE        *f,
00482            const char   *patternSpecification,
00483            va_list      ap);
00484 
00492 U_DRAFT int32_t U_EXPORT2
00493 u_printf_u(const UChar *patternSpecification,
00494            ... );
00495 
00501 U_DRAFT UFILE * U_EXPORT2
00502 u_get_stdout(void);
00503 
00512 U_STABLE int32_t U_EXPORT2
00513 u_fprintf_u(UFILE       *f,
00514             const UChar *patternSpecification,
00515             ... );
00516 
00529 U_STABLE int32_t U_EXPORT2
00530 u_vfprintf_u(UFILE      *f,
00531             const UChar *patternSpecification,
00532             va_list     ap);
00533 #endif
00534 
00544 U_STABLE int32_t U_EXPORT2
00545 u_fputs(const UChar *s,
00546         UFILE       *f);
00547 
00555 U_STABLE UChar32 U_EXPORT2
00556 u_fputc(UChar32  uc,
00557         UFILE  *f);
00558 
00570 U_STABLE int32_t U_EXPORT2
00571 u_file_write(const UChar    *ustring, 
00572              int32_t        count, 
00573              UFILE          *f);
00574 
00575 
00576 /* Input functions */
00577 #if !UCONFIG_NO_FORMATTING
00578 
00588 U_STABLE int32_t U_EXPORT2
00589 u_fscanf(UFILE      *f,
00590          const char *patternSpecification,
00591          ... );
00592 
00606 U_STABLE int32_t U_EXPORT2
00607 u_vfscanf(UFILE         *f,
00608           const char    *patternSpecification,
00609           va_list        ap);
00610 
00620 U_STABLE int32_t U_EXPORT2
00621 u_fscanf_u(UFILE        *f,
00622            const UChar  *patternSpecification,
00623            ... );
00624 
00638 U_STABLE int32_t U_EXPORT2
00639 u_vfscanf_u(UFILE       *f,
00640             const UChar *patternSpecification,
00641             va_list      ap);
00642 #endif
00643 
00656 U_STABLE UChar* U_EXPORT2
00657 u_fgets(UChar  *s,
00658         int32_t n,
00659         UFILE  *f);
00660 
00670 U_STABLE UChar U_EXPORT2
00671 u_fgetc(UFILE   *f);
00672 
00683 U_STABLE UChar32 U_EXPORT2
00684 u_fgetcx(UFILE  *f);
00685 
00697 U_STABLE UChar32 U_EXPORT2
00698 u_fungetc(UChar32   c,
00699       UFILE        *f);
00700 
00711 U_STABLE int32_t U_EXPORT2
00712 u_file_read(UChar        *chars, 
00713         int32_t        count, 
00714         UFILE         *f);
00715 
00716 #if !UCONFIG_NO_TRANSLITERATION
00717 
00735 U_STABLE UTransliterator* U_EXPORT2
00736 u_fsettransliterator(UFILE *file, UFileDirection direction,
00737                      UTransliterator *adopt, UErrorCode *status);
00738 
00739 #endif
00740 
00741 
00742 /* Output string functions */
00743 #if !UCONFIG_NO_FORMATTING
00744 
00745 
00756 U_STABLE int32_t U_EXPORT2
00757 u_sprintf(UChar       *buffer,
00758         const char    *patternSpecification,
00759         ... );
00760 
00778 U_STABLE int32_t U_EXPORT2
00779 u_snprintf(UChar      *buffer,
00780         int32_t       count,
00781         const char    *patternSpecification,
00782         ... );
00783 
00797 U_STABLE int32_t U_EXPORT2
00798 u_vsprintf(UChar      *buffer,
00799         const char    *patternSpecification,
00800         va_list        ap);
00801 
00822 U_STABLE int32_t U_EXPORT2
00823 u_vsnprintf(UChar     *buffer,
00824         int32_t       count,
00825         const char    *patternSpecification,
00826         va_list        ap);
00827 
00837 U_STABLE int32_t U_EXPORT2
00838 u_sprintf_u(UChar      *buffer,
00839         const UChar    *patternSpecification,
00840         ... );
00841 
00858 U_STABLE int32_t U_EXPORT2
00859 u_snprintf_u(UChar     *buffer,
00860         int32_t        count,
00861         const UChar    *patternSpecification,
00862         ... );
00863 
00877 U_STABLE int32_t U_EXPORT2
00878 u_vsprintf_u(UChar     *buffer,
00879         const UChar    *patternSpecification,
00880         va_list        ap);
00881 
00902 U_STABLE int32_t U_EXPORT2
00903 u_vsnprintf_u(UChar *buffer,
00904         int32_t         count,
00905         const UChar     *patternSpecification,
00906         va_list         ap);
00907 
00908 /* Input string functions */
00909 
00920 U_STABLE int32_t U_EXPORT2
00921 u_sscanf(const UChar   *buffer,
00922         const char     *patternSpecification,
00923         ... );
00924 
00939 U_STABLE int32_t U_EXPORT2
00940 u_vsscanf(const UChar  *buffer,
00941         const char     *patternSpecification,
00942         va_list        ap);
00943 
00954 U_STABLE int32_t U_EXPORT2
00955 u_sscanf_u(const UChar  *buffer,
00956         const UChar     *patternSpecification,
00957         ... );
00958 
00973 U_STABLE int32_t U_EXPORT2
00974 u_vsscanf_u(const UChar *buffer,
00975         const UChar     *patternSpecification,
00976         va_list         ap);
00977 
00978 #endif
00979 #endif
00980 
00981 

Generated on 25 Nov 2014 for ICU 50.1.2 by  doxygen 1.4.7