ustdio.h

Go to the documentation of this file.

// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
******************************************************************************
*
*   Copyright (C) 1998-2015, International Business Machines
*   Corporation and others.  All Rights Reserved.
*
******************************************************************************
*
* File ustdio.h
*
* Modification History:
*
*   Date        Name        Description
*   10/16/98    stephen     Creation.
*   11/06/98    stephen     Modified per code review.
*   03/12/99    stephen     Modified for new C API.
*   07/19/99    stephen     Minor doc update.
*   02/01/01    george      Added sprintf & sscanf with all of its variants
******************************************************************************
*/

#ifndef USTDIO_H
#define USTDIO_H

#include <stdio.h>
#include <stdarg.h>

#include "unicode/utypes.h"
#include "unicode/ucnv.h"
#include "unicode/utrans.h"
#include "unicode/localpointer.h"
#include "unicode/unum.h"

#if !UCONFIG_NO_CONVERSION

/*
    TODO
 The following is a small list as to what is currently wrong/suggestions for
 ustdio.

 * Make sure that * in the scanf format specification works for all formats.
 * Each UFILE takes up at least 2KB.
    Look into adding setvbuf() for configurable buffers.
 * This library does buffering. The OS should do this for us already. Check on
    this, and remove it from this library, if this is the case. Double buffering
    wastes a lot of time and space.
 * Test stdin and stdout with the u_f* functions
 * Testing should be done for reading and writing multi-byte encodings,
    and make sure that a character that is contained across buffer boundries
    works even for incomplete characters.
 * Make sure that the last character is flushed when the file/string is closed.
 * snprintf should follow the C99 standard for the return value, which is
    return the number of characters (excluding the trailing '\0')
    which would have been written to the destination string regardless
    of available space. This is like pre-flighting.
 * Everything that uses %s should do what operator>> does for UnicodeString.
    It should convert one byte at a time, and once a character is
    converted then check to see if it's whitespace or in the scanset.
    If it's whitespace or in the scanset, put all the bytes back (do nothing
    for sprintf/sscanf).
 * If bad string data is encountered, make sure that the function fails
    without memory leaks and the unconvertable characters are valid
    substitution or are escaped characters.
 * u_fungetc() can't unget a character when it's at the beginning of the
    internal conversion buffer. For example, read the buffer size # of
    characters, and then ungetc to get the previous character that was
    at the end of the last buffer.
 * u_fflush() and u_fclose should return an int32_t like C99 functions.
    0 is returned if the operation was successful and EOF otherwise.
 * u_fsettransliterator does not support U_READ side of transliteration.
 * The format specifier should limit the size of a format or honor it in
    order to prevent buffer overruns.  (e.g. %256.256d).
 * u_fread and u_fwrite don't exist. They're needed for reading and writing
    data structures without any conversion.
 * u_file_read and u_file_write are used for writing strings. u_fgets and
    u_fputs or u_fread and u_fwrite should be used to do this.
 * The width parameter for all scanf formats, including scanset, needs
    better testing. This prevents buffer overflows.
 * Figure out what is suppose to happen when a codepage is changed midstream.
    Maybe a flush or a rewind are good enough.
 * Make sure that a UFile opened with "rw" can be used after using
    u_fflush with a u_frewind.
 * scanf(%i) should detect what type of number to use.
 * Add more testing of the alternate format, %#
 * Look at newline handling of fputs/puts
 * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
 * Complete the file documentation with proper doxygen formatting.
    See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
*/

#define U_EOF 0xFFFF

typedef struct UFILE UFILE;

typedef enum { 
   U_READ = 1,
   U_WRITE = 2, 
   U_READWRITE =3  /* == (U_READ | U_WRITE) */ 
} UFileDirection;

U_STABLE UFILE* U_EXPORT2
u_fopen(const char    *filename,
    const char    *perm,
    const char    *locale,
    const char    *codepage);

U_STABLE UFILE* U_EXPORT2
u_fopen_u(const UChar    *filename,
    const char    *perm,
    const char    *locale,
    const char    *codepage);

U_STABLE UFILE* U_EXPORT2
u_finit(FILE        *f,
    const char    *locale,
    const char    *codepage);

U_STABLE UFILE* U_EXPORT2
u_fadopt(FILE     *f,
    const char    *locale,
    const char    *codepage);

U_STABLE UFILE* U_EXPORT2
u_fstropen(UChar      *stringBuf,
           int32_t     capacity,
           const char *locale);

U_STABLE void U_EXPORT2
u_fclose(UFILE *file);

#if U_SHOW_CPLUSPLUS_API

U_NAMESPACE_BEGIN

U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose);

U_NAMESPACE_END

#endif

U_STABLE UBool U_EXPORT2
u_feof(UFILE  *f);

U_STABLE void U_EXPORT2
u_fflush(UFILE *file);

U_STABLE void
u_frewind(UFILE *file);

U_STABLE FILE* U_EXPORT2
u_fgetfile(UFILE *f);

#if !UCONFIG_NO_FORMATTING

U_STABLE const char* U_EXPORT2
u_fgetlocale(UFILE *file);

U_STABLE int32_t U_EXPORT2
u_fsetlocale(UFILE      *file,
             const char *locale);

#endif

U_STABLE const char* U_EXPORT2
u_fgetcodepage(UFILE *file);

U_STABLE int32_t U_EXPORT2
u_fsetcodepage(const char   *codepage,
               UFILE        *file);


U_STABLE UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);

#if !UCONFIG_NO_FORMATTING

 U_STABLE const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f);

/* Output functions */

U_STABLE int32_t U_EXPORT2
u_printf(const char *patternSpecification,
         ... );

U_STABLE int32_t U_EXPORT2
u_fprintf(UFILE         *f,
          const char    *patternSpecification,
          ... );

U_STABLE int32_t U_EXPORT2
u_vfprintf(UFILE        *f,
           const char   *patternSpecification,
           va_list      ap);

U_STABLE int32_t U_EXPORT2
u_printf_u(const UChar *patternSpecification,
           ... );

U_STABLE UFILE * U_EXPORT2
u_get_stdout(void);

U_STABLE int32_t U_EXPORT2
u_fprintf_u(UFILE       *f,
            const UChar *patternSpecification,
            ... );

U_STABLE int32_t U_EXPORT2
u_vfprintf_u(UFILE      *f,
            const UChar *patternSpecification,
            va_list     ap);
#endif

U_STABLE int32_t U_EXPORT2
u_fputs(const UChar *s,
        UFILE       *f);

U_STABLE UChar32 U_EXPORT2
u_fputc(UChar32  uc,
        UFILE  *f);

U_STABLE int32_t U_EXPORT2
u_file_write(const UChar    *ustring, 
             int32_t        count, 
             UFILE          *f);


/* Input functions */
#if !UCONFIG_NO_FORMATTING

U_STABLE int32_t U_EXPORT2
u_fscanf(UFILE      *f,
         const char *patternSpecification,
         ... );

U_STABLE int32_t U_EXPORT2
u_vfscanf(UFILE         *f,
          const char    *patternSpecification,
          va_list        ap);

U_STABLE int32_t U_EXPORT2
u_fscanf_u(UFILE        *f,
           const UChar  *patternSpecification,
           ... );

U_STABLE int32_t U_EXPORT2
u_vfscanf_u(UFILE       *f,
            const UChar *patternSpecification,
            va_list      ap);
#endif

U_STABLE UChar* U_EXPORT2
u_fgets(UChar  *s,
        int32_t n,
        UFILE  *f);

U_STABLE UChar U_EXPORT2
u_fgetc(UFILE   *f);

U_STABLE UChar32 U_EXPORT2
u_fgetcx(UFILE  *f);

U_STABLE UChar32 U_EXPORT2
u_fungetc(UChar32   c,
      UFILE        *f);

U_STABLE int32_t U_EXPORT2
u_file_read(UChar        *chars, 
        int32_t        count, 
        UFILE         *f);

#if !UCONFIG_NO_TRANSLITERATION

U_STABLE UTransliterator* U_EXPORT2
u_fsettransliterator(UFILE *file, UFileDirection direction,
                     UTransliterator *adopt, UErrorCode *status);

#endif


/* Output string functions */
#if !UCONFIG_NO_FORMATTING


U_STABLE int32_t U_EXPORT2
u_sprintf(UChar       *buffer,
        const char    *patternSpecification,
        ... );

U_STABLE int32_t U_EXPORT2
u_snprintf(UChar      *buffer,
        int32_t       count,
        const char    *patternSpecification,
        ... );

U_STABLE int32_t U_EXPORT2
u_vsprintf(UChar      *buffer,
        const char    *patternSpecification,
        va_list        ap);

U_STABLE int32_t U_EXPORT2
u_vsnprintf(UChar     *buffer,
        int32_t       count,
        const char    *patternSpecification,
        va_list        ap);

U_STABLE int32_t U_EXPORT2
u_sprintf_u(UChar      *buffer,
        const UChar    *patternSpecification,
        ... );

U_STABLE int32_t U_EXPORT2
u_snprintf_u(UChar     *buffer,
        int32_t        count,
        const UChar    *patternSpecification,
        ... );

U_STABLE int32_t U_EXPORT2
u_vsprintf_u(UChar     *buffer,
        const UChar    *patternSpecification,
        va_list        ap);

U_STABLE int32_t U_EXPORT2
u_vsnprintf_u(UChar *buffer,
        int32_t         count,
        const UChar     *patternSpecification,
        va_list         ap);

/* Input string functions */

U_STABLE int32_t U_EXPORT2
u_sscanf(const UChar   *buffer,
        const char     *patternSpecification,
        ... );

U_STABLE int32_t U_EXPORT2
u_vsscanf(const UChar  *buffer,
        const char     *patternSpecification,
        va_list        ap);

U_STABLE int32_t U_EXPORT2
u_sscanf_u(const UChar  *buffer,
        const UChar     *patternSpecification,
        ... );

U_STABLE int32_t U_EXPORT2
u_vsscanf_u(const UChar *buffer,
        const UChar     *patternSpecification,
        va_list         ap);


#endif
#endif
#endif