ICU 66.1 66.1
ustdio.h
Go to the documentation of this file.
1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4******************************************************************************
5*
6* Copyright (C) 1998-2015, International Business Machines
7* Corporation and others. All Rights Reserved.
8*
9******************************************************************************
10*
11* File ustdio.h
12*
13* Modification History:
14*
15* Date Name Description
16* 10/16/98 stephen Creation.
17* 11/06/98 stephen Modified per code review.
18* 03/12/99 stephen Modified for new C API.
19* 07/19/99 stephen Minor doc update.
20* 02/01/01 george Added sprintf & sscanf with all of its variants
21******************************************************************************
22*/
23
24#ifndef USTDIO_H
25#define USTDIO_H
26
27#include <stdio.h>
28#include <stdarg.h>
29
30#include "unicode/utypes.h"
31#include "unicode/ucnv.h"
32#include "unicode/utrans.h"
34#include "unicode/unum.h"
35
36#if !UCONFIG_NO_CONVERSION
37
38/*
39 TODO
40 The following is a small list as to what is currently wrong/suggestions for
41 ustdio.
42
43 * Make sure that * in the scanf format specification works for all formats.
44 * Each UFILE takes up at least 2KB.
45 Look into adding setvbuf() for configurable buffers.
46 * This library does buffering. The OS should do this for us already. Check on
47 this, and remove it from this library, if this is the case. Double buffering
48 wastes a lot of time and space.
49 * Test stdin and stdout with the u_f* functions
50 * Testing should be done for reading and writing multi-byte encodings,
51 and make sure that a character that is contained across buffer boundries
52 works even for incomplete characters.
53 * Make sure that the last character is flushed when the file/string is closed.
54 * snprintf should follow the C99 standard for the return value, which is
55 return the number of characters (excluding the trailing '\0')
56 which would have been written to the destination string regardless
57 of available space. This is like pre-flighting.
58 * Everything that uses %s should do what operator>> does for UnicodeString.
59 It should convert one byte at a time, and once a character is
60 converted then check to see if it's whitespace or in the scanset.
61 If it's whitespace or in the scanset, put all the bytes back (do nothing
62 for sprintf/sscanf).
63 * If bad string data is encountered, make sure that the function fails
64 without memory leaks and the unconvertable characters are valid
65 substitution or are escaped characters.
66 * u_fungetc() can't unget a character when it's at the beginning of the
67 internal conversion buffer. For example, read the buffer size # of
68 characters, and then ungetc to get the previous character that was
69 at the end of the last buffer.
70 * u_fflush() and u_fclose should return an int32_t like C99 functions.
71 0 is returned if the operation was successful and EOF otherwise.
72 * u_fsettransliterator does not support U_READ side of transliteration.
73 * The format specifier should limit the size of a format or honor it in
74 order to prevent buffer overruns. (e.g. %256.256d).
75 * u_fread and u_fwrite don't exist. They're needed for reading and writing
76 data structures without any conversion.
77 * u_file_read and u_file_write are used for writing strings. u_fgets and
78 u_fputs or u_fread and u_fwrite should be used to do this.
79 * The width parameter for all scanf formats, including scanset, needs
80 better testing. This prevents buffer overflows.
81 * Figure out what is suppose to happen when a codepage is changed midstream.
82 Maybe a flush or a rewind are good enough.
83 * Make sure that a UFile opened with "rw" can be used after using
84 u_fflush with a u_frewind.
85 * scanf(%i) should detect what type of number to use.
86 * Add more testing of the alternate format, %#
87 * Look at newline handling of fputs/puts
88 * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
89 * Complete the file documentation with proper doxygen formatting.
90 See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
91*/
92
209#define U_EOF 0xFFFF
210
212typedef struct UFILE UFILE;
213
219typedef enum {
220 U_READ = 1,
221 U_WRITE = 2,
222 U_READWRITE =3 /* == (U_READ | U_WRITE) */
224
242U_STABLE UFILE* U_EXPORT2
243u_fopen(const char *filename,
244 const char *perm,
245 const char *locale,
246 const char *codepage);
247
265U_STABLE UFILE* U_EXPORT2
266u_fopen_u(const UChar *filename,
267 const char *perm,
268 const char *locale,
269 const char *codepage);
270
287U_STABLE UFILE* U_EXPORT2
288u_finit(FILE *f,
289 const char *locale,
290 const char *codepage);
291
308U_STABLE UFILE* U_EXPORT2
309u_fadopt(FILE *f,
310 const char *locale,
311 const char *codepage);
312
327U_STABLE UFILE* U_EXPORT2
328u_fstropen(UChar *stringBuf,
329 int32_t capacity,
330 const char *locale);
331
338U_STABLE void U_EXPORT2
340
341#if U_SHOW_CPLUSPLUS_API
342
343U_NAMESPACE_BEGIN
344
355
356U_NAMESPACE_END
357
358#endif
359
368U_STABLE UBool U_EXPORT2
370
381U_STABLE void U_EXPORT2
383
389U_STABLE void
391
398U_STABLE FILE* U_EXPORT2
400
401#if !UCONFIG_NO_FORMATTING
402
411U_STABLE const char* U_EXPORT2
413
422U_STABLE int32_t U_EXPORT2
424 const char *locale);
425
426#endif
427
437U_STABLE const char* U_EXPORT2
439
455U_STABLE int32_t U_EXPORT2
456u_fsetcodepage(const char *codepage,
457 UFILE *file);
458
459
467
468#if !UCONFIG_NO_FORMATTING
476
477/* Output functions */
478
486U_STABLE int32_t U_EXPORT2
487u_printf(const char *patternSpecification,
488 ... );
489
498U_STABLE int32_t U_EXPORT2
500 const char *patternSpecification,
501 ... );
502
515U_STABLE int32_t U_EXPORT2
517 const char *patternSpecification,
518 va_list ap);
519
527U_STABLE int32_t U_EXPORT2
528u_printf_u(const UChar *patternSpecification,
529 ... );
530
536U_STABLE UFILE * U_EXPORT2
538
547U_STABLE int32_t U_EXPORT2
549 const UChar *patternSpecification,
550 ... );
551
564U_STABLE int32_t U_EXPORT2
566 const UChar *patternSpecification,
567 va_list ap);
568#endif
579U_STABLE int32_t U_EXPORT2
580u_fputs(const UChar *s,
581 UFILE *f);
582
590U_STABLE UChar32 U_EXPORT2
592 UFILE *f);
593
605U_STABLE int32_t U_EXPORT2
606u_file_write(const UChar *ustring,
607 int32_t count,
608 UFILE *f);
609
610
611/* Input functions */
612#if !UCONFIG_NO_FORMATTING
613
623U_STABLE int32_t U_EXPORT2
625 const char *patternSpecification,
626 ... );
627
641U_STABLE int32_t U_EXPORT2
643 const char *patternSpecification,
644 va_list ap);
645
655U_STABLE int32_t U_EXPORT2
657 const UChar *patternSpecification,
658 ... );
659
673U_STABLE int32_t U_EXPORT2
675 const UChar *patternSpecification,
676 va_list ap);
677#endif
678
691U_STABLE UChar* U_EXPORT2
693 int32_t n,
694 UFILE *f);
695
705U_STABLE UChar U_EXPORT2
707
718U_STABLE UChar32 U_EXPORT2
720
732U_STABLE UChar32 U_EXPORT2
734 UFILE *f);
735
746U_STABLE int32_t U_EXPORT2
748 int32_t count,
749 UFILE *f);
750
751#if !UCONFIG_NO_TRANSLITERATION
752
770U_STABLE UTransliterator* U_EXPORT2
772 UTransliterator *adopt, UErrorCode *status);
773
774#endif
775
776
777/* Output string functions */
778#if !UCONFIG_NO_FORMATTING
779
780
791U_STABLE int32_t U_EXPORT2
793 const char *patternSpecification,
794 ... );
795
813U_STABLE int32_t U_EXPORT2
815 int32_t count,
816 const char *patternSpecification,
817 ... );
818
832U_STABLE int32_t U_EXPORT2
834 const char *patternSpecification,
835 va_list ap);
836
857U_STABLE int32_t U_EXPORT2
859 int32_t count,
860 const char *patternSpecification,
861 va_list ap);
862
872U_STABLE int32_t U_EXPORT2
874 const UChar *patternSpecification,
875 ... );
876
893U_STABLE int32_t U_EXPORT2
895 int32_t count,
896 const UChar *patternSpecification,
897 ... );
898
912U_STABLE int32_t U_EXPORT2
914 const UChar *patternSpecification,
915 va_list ap);
916
937U_STABLE int32_t U_EXPORT2
939 int32_t count,
940 const UChar *patternSpecification,
941 va_list ap);
942
943/* Input string functions */
944
955U_STABLE int32_t U_EXPORT2
956u_sscanf(const UChar *buffer,
957 const char *patternSpecification,
958 ... );
959
974U_STABLE int32_t U_EXPORT2
975u_vsscanf(const UChar *buffer,
976 const char *patternSpecification,
977 va_list ap);
978
989U_STABLE int32_t U_EXPORT2
990u_sscanf_u(const UChar *buffer,
991 const UChar *patternSpecification,
992 ... );
993
1008U_STABLE int32_t U_EXPORT2
1009u_vsscanf_u(const UChar *buffer,
1010 const UChar *patternSpecification,
1011 va_list ap);
1012
1013
1014#endif
1015#endif
1016#endif
1017
1018
"Smart pointer" class, closes a UFILE via u_fclose().
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
"Smart pointer" definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:562
C API: Character conversion.
struct UConverter UConverter
Definition: ucnv_err.h:96
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition: umachine.h:425
int8_t UBool
The ICU boolean type.
Definition: umachine.h:261
uint16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:378
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:111
C API: Compatibility APIs for number formatting.
void * UNumberFormat
A number formatter.
Definition: unum.h:141
UConverter * u_fgetConverter(UFILE *f)
Returns an alias to the converter being used for this file.
FILE * u_fgetfile(UFILE *f)
Get the FILE* associated with a UFILE.
int32_t u_printf_u(const UChar *patternSpecification,...)
Write formatted data to stdout.
int32_t u_vsscanf_u(const UChar *buffer, const UChar *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
UTransliterator * u_fsettransliterator(UFILE *file, UFileDirection direction, UTransliterator *adopt, UErrorCode *status)
Set a transliterator on the UFILE.
int32_t u_fscanf(UFILE *f, const char *patternSpecification,...)
Read formatted data from a UFILE.
UChar * u_fgets(UChar *s, int32_t n, UFILE *f)
Read one line of text into a UChar* string from a UFILE.
int32_t u_vsnprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
int32_t u_fputs(const UChar *s, UFILE *f)
Write a Unicode to a UFILE.
int32_t u_fprintf_u(UFILE *f, const UChar *patternSpecification,...)
Write formatted data to a UFILE.
UFILE * u_fopen(const char *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE.
int32_t u_vfscanf(UFILE *f, const char *patternSpecification, va_list ap)
Read formatted data from a UFILE.
UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
int32_t u_sprintf_u(UChar *buffer, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
UChar32 u_fgetcx(UFILE *f)
Read a UChar32 from a UFILE.
const char * u_fgetcodepage(UFILE *file)
Get the codepage in which data is written to and read from the UFILE.
int32_t u_snprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
int32_t u_sscanf(const UChar *buffer, const char *patternSpecification,...)
Read formatted data from a Unicode string.
int32_t u_vsscanf(const UChar *buffer, const char *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
UChar32 u_fungetc(UChar32 c, UFILE *f)
Unget a UChar from a UFILE.
int32_t u_vfprintf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Write formatted data to a UFILE.
UFILE * u_fstropen(UChar *stringBuf, int32_t capacity, const char *locale)
Create a UFILE that can be used for localized formatting or parsing.
int32_t u_printf(const char *patternSpecification,...)
Write formatted data to stdout.
UFILE * u_fadopt(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
int32_t u_fsetcodepage(const char *codepage, UFILE *file)
Set the codepage in which data will be written to and read from the UFILE.
int32_t u_sprintf(UChar *buffer, const char *patternSpecification,...)
Write formatted data to a Unicode string.
int32_t u_snprintf(UChar *buffer, int32_t count, const char *patternSpecification,...)
Write formatted data to a Unicode string.
int32_t u_vsprintf(UChar *buffer, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
int32_t u_vfprintf(UFILE *f, const char *patternSpecification, va_list ap)
Write formatted data to a UFILE.
int32_t u_file_read(UChar *chars, int32_t count, UFILE *f)
Read Unicode from a UFILE.
const char * u_fgetlocale(UFILE *file)
Get the locale whose conventions are used to format and parse output.
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:219
int32_t u_vfscanf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Read formatted data from a UFILE.
int32_t u_sscanf_u(const UChar *buffer, const UChar *patternSpecification,...)
Read formatted data from a Unicode string.
int32_t u_vsprintf_u(UChar *buffer, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
int32_t u_fprintf(UFILE *f, const char *patternSpecification,...)
Write formatted data to a UFILE.
int32_t u_vsnprintf(UChar *buffer, int32_t count, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
void u_fclose(UFILE *file)
Close a UFILE.
void u_fflush(UFILE *file)
Flush output of a UFILE.
int32_t u_file_write(const UChar *ustring, int32_t count, UFILE *f)
Write Unicode to a UFILE.
int32_t u_fscanf_u(UFILE *f, const UChar *patternSpecification,...)
Read formatted data from a UFILE.
int32_t u_fsetlocale(UFILE *file, const char *locale)
Set the locale whose conventions will be used to format and parse output.
UFILE * u_finit(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
UFILE * u_get_stdout(void)
Get a UFILE for stdout.
struct UFILE UFILE
Forward declaration of a Unicode-aware file.
Definition: ustdio.h:212
UBool u_feof(UFILE *f)
Tests if the UFILE is at the end of the file stream.
const UNumberFormat * u_fgetNumberFormat(UFILE *f)
Returns an alias to the number formatter being used for this file.
void u_frewind(UFILE *file)
Rewind the file pointer to the beginning of the file.
UChar u_fgetc(UFILE *f)
Read a UChar from a UFILE.
UFILE * u_fopen_u(const UChar *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE with a UChar* filename A UFILE is a wrapper around a FILE* that is locale and codepage a...
C API: Transliterator.
void * UTransliterator
An opaque transliterator for use in C.
Definition: utrans.h:70
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415