ICU 74.1 74.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"
33#include "unicode/unum.h"
34
35#if U_SHOW_CPLUSPLUS_API
37#endif // U_SHOW_CPLUSPLUS_API
38
39#if !UCONFIG_NO_CONVERSION
40
41/*
42 TODO
43 The following is a small list as to what is currently wrong/suggestions for
44 ustdio.
45
46 * Make sure that * in the scanf format specification works for all formats.
47 * Each UFILE takes up at least 2KB.
48 Look into adding setvbuf() for configurable buffers.
49 * This library does buffering. The OS should do this for us already. Check on
50 this, and remove it from this library, if this is the case. Double buffering
51 wastes a lot of time and space.
52 * Test stdin and stdout with the u_f* functions
53 * Testing should be done for reading and writing multi-byte encodings,
54 and make sure that a character that is contained across buffer boundaries
55 works even for incomplete characters.
56 * Make sure that the last character is flushed when the file/string is closed.
57 * snprintf should follow the C99 standard for the return value, which is
58 return the number of characters (excluding the trailing '\0')
59 which would have been written to the destination string regardless
60 of available space. This is like pre-flighting.
61 * Everything that uses %s should do what operator>> does for UnicodeString.
62 It should convert one byte at a time, and once a character is
63 converted then check to see if it's whitespace or in the scanset.
64 If it's whitespace or in the scanset, put all the bytes back (do nothing
65 for sprintf/sscanf).
66 * If bad string data is encountered, make sure that the function fails
67 without memory leaks and the unconvertable characters are valid
68 substitution or are escaped characters.
69 * u_fungetc() can't unget a character when it's at the beginning of the
70 internal conversion buffer. For example, read the buffer size # of
71 characters, and then ungetc to get the previous character that was
72 at the end of the last buffer.
73 * u_fflush() and u_fclose should return an int32_t like C99 functions.
74 0 is returned if the operation was successful and EOF otherwise.
75 * u_fsettransliterator does not support U_READ side of transliteration.
76 * The format specifier should limit the size of a format or honor it in
77 order to prevent buffer overruns. (e.g. %256.256d).
78 * u_fread and u_fwrite don't exist. They're needed for reading and writing
79 data structures without any conversion.
80 * u_file_read and u_file_write are used for writing strings. u_fgets and
81 u_fputs or u_fread and u_fwrite should be used to do this.
82 * The width parameter for all scanf formats, including scanset, needs
83 better testing. This prevents buffer overflows.
84 * Figure out what is suppose to happen when a codepage is changed midstream.
85 Maybe a flush or a rewind are good enough.
86 * Make sure that a UFile opened with "rw" can be used after using
87 u_fflush with a u_frewind.
88 * scanf(%i) should detect what type of number to use.
89 * Add more testing of the alternate format, %#
90 * Look at newline handling of fputs/puts
91 * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
92 * Complete the file documentation with proper doxygen formatting.
93 See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
94*/
95
212#define U_EOF 0xFFFF
213
215typedef struct UFILE UFILE;
216
222typedef enum {
223 U_READ = 1,
224 U_WRITE = 2,
225 U_READWRITE =3 /* == (U_READ | U_WRITE) */
227
245U_CAPI UFILE* U_EXPORT2
246u_fopen(const char *filename,
247 const char *perm,
248 const char *locale,
249 const char *codepage);
250
268U_CAPI UFILE* U_EXPORT2
269u_fopen_u(const UChar *filename,
270 const char *perm,
271 const char *locale,
272 const char *codepage);
273
290U_CAPI UFILE* U_EXPORT2
291u_finit(FILE *f,
292 const char *locale,
293 const char *codepage);
294
311U_CAPI UFILE* U_EXPORT2
312u_fadopt(FILE *f,
313 const char *locale,
314 const char *codepage);
315
330U_CAPI UFILE* U_EXPORT2
331u_fstropen(UChar *stringBuf,
332 int32_t capacity,
333 const char *locale);
334
341U_CAPI void U_EXPORT2
343
344#if U_SHOW_CPLUSPLUS_API
345
346U_NAMESPACE_BEGIN
347
358
359U_NAMESPACE_END
360
361#endif
362
371U_CAPI UBool U_EXPORT2
373
384U_CAPI void U_EXPORT2
386
392U_CAPI void
394
401U_CAPI FILE* U_EXPORT2
403
404#if !UCONFIG_NO_FORMATTING
405
414U_CAPI const char* U_EXPORT2
416
425U_CAPI int32_t U_EXPORT2
427 const char *locale);
428
429#endif
430
440U_CAPI const char* U_EXPORT2
442
458U_CAPI int32_t U_EXPORT2
459u_fsetcodepage(const char *codepage,
460 UFILE *file);
461
462
470
471#if !UCONFIG_NO_FORMATTING
479
480/* Output functions */
481
489U_CAPI int32_t U_EXPORT2
490u_printf(const char *patternSpecification,
491 ... );
492
501U_CAPI int32_t U_EXPORT2
503 const char *patternSpecification,
504 ... );
505
518U_CAPI int32_t U_EXPORT2
520 const char *patternSpecification,
521 va_list ap);
522
530U_CAPI int32_t U_EXPORT2
531u_printf_u(const UChar *patternSpecification,
532 ... );
533
539U_CAPI UFILE * U_EXPORT2
541
550U_CAPI int32_t U_EXPORT2
552 const UChar *patternSpecification,
553 ... );
554
567U_CAPI int32_t U_EXPORT2
569 const UChar *patternSpecification,
570 va_list ap);
571#endif
582U_CAPI int32_t U_EXPORT2
583u_fputs(const UChar *s,
584 UFILE *f);
585
593U_CAPI UChar32 U_EXPORT2
595 UFILE *f);
596
608U_CAPI int32_t U_EXPORT2
609u_file_write(const UChar *ustring,
610 int32_t count,
611 UFILE *f);
612
613
614/* Input functions */
615#if !UCONFIG_NO_FORMATTING
616
626U_CAPI int32_t U_EXPORT2
628 const char *patternSpecification,
629 ... );
630
644U_CAPI int32_t U_EXPORT2
646 const char *patternSpecification,
647 va_list ap);
648
658U_CAPI int32_t U_EXPORT2
660 const UChar *patternSpecification,
661 ... );
662
676U_CAPI int32_t U_EXPORT2
678 const UChar *patternSpecification,
679 va_list ap);
680#endif
681
694U_CAPI UChar* U_EXPORT2
696 int32_t n,
697 UFILE *f);
698
708U_CAPI UChar U_EXPORT2
710
721U_CAPI UChar32 U_EXPORT2
723
735U_CAPI UChar32 U_EXPORT2
737 UFILE *f);
738
749U_CAPI int32_t U_EXPORT2
751 int32_t count,
752 UFILE *f);
753
754#if !UCONFIG_NO_TRANSLITERATION
755
773U_CAPI UTransliterator* U_EXPORT2
775 UTransliterator *adopt, UErrorCode *status);
776
777#endif
778
779
780/* Output string functions */
781#if !UCONFIG_NO_FORMATTING
782
783
794U_CAPI int32_t U_EXPORT2
796 const char *patternSpecification,
797 ... );
798
816U_CAPI int32_t U_EXPORT2
818 int32_t count,
819 const char *patternSpecification,
820 ... );
821
835U_CAPI int32_t U_EXPORT2
837 const char *patternSpecification,
838 va_list ap);
839
860U_CAPI int32_t U_EXPORT2
862 int32_t count,
863 const char *patternSpecification,
864 va_list ap);
865
875U_CAPI int32_t U_EXPORT2
877 const UChar *patternSpecification,
878 ... );
879
896U_CAPI int32_t U_EXPORT2
898 int32_t count,
899 const UChar *patternSpecification,
900 ... );
901
915U_CAPI int32_t U_EXPORT2
917 const UChar *patternSpecification,
918 va_list ap);
919
940U_CAPI int32_t U_EXPORT2
942 int32_t count,
943 const UChar *patternSpecification,
944 va_list ap);
945
946/* Input string functions */
947
958U_CAPI int32_t U_EXPORT2
959u_sscanf(const UChar *buffer,
960 const char *patternSpecification,
961 ... );
962
977U_CAPI int32_t U_EXPORT2
978u_vsscanf(const UChar *buffer,
979 const char *patternSpecification,
980 va_list ap);
981
992U_CAPI int32_t U_EXPORT2
993u_sscanf_u(const UChar *buffer,
994 const UChar *patternSpecification,
995 ... );
996
1011U_CAPI int32_t U_EXPORT2
1012u_vsscanf_u(const UChar *buffer,
1013 const UChar *patternSpecification,
1014 va_list ap);
1015
1016
1017#endif
1018#endif
1019#endif
1020
1021
"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:550
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:435
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:247
#define U_CAPI
This is used to declare a function as a public ICU C API.
Definition: umachine.h:110
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:386
C API: Compatibility APIs for number formatting.
void * UNumberFormat
A number formatter.
Definition: unum.h:145
U_CAPI int32_t u_vfprintf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Write formatted data to a UFILE.
U_CAPI const UNumberFormat * u_fgetNumberFormat(UFILE *f)
Returns an alias to the number formatter being used for this file.
U_CAPI const char * u_fgetcodepage(UFILE *file)
Get the codepage in which data is written to and read from the UFILE.
U_CAPI UBool u_feof(UFILE *f)
Tests if the UFILE is at the end of the file stream.
U_CAPI const char * u_fgetlocale(UFILE *file)
Get the locale whose conventions are used to format and parse output.
U_CAPI int32_t u_fscanf_u(UFILE *f, const UChar *patternSpecification,...)
Read formatted data from a UFILE.
U_CAPI int32_t u_vfprintf(UFILE *f, const char *patternSpecification, va_list ap)
Write formatted data to a UFILE.
U_CAPI UChar u_fgetc(UFILE *f)
Read a UChar from a UFILE.
U_CAPI int32_t u_file_write(const UChar *ustring, int32_t count, UFILE *f)
Write Unicode to a UFILE.
U_CAPI void u_fflush(UFILE *file)
Flush output of a UFILE.
U_CAPI int32_t u_vfscanf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Read formatted data from a UFILE.
U_CAPI int32_t u_vsnprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
U_CAPI int32_t u_fprintf_u(UFILE *f, const UChar *patternSpecification,...)
Write formatted data to a UFILE.
U_CAPI void u_frewind(UFILE *file)
Rewind the file pointer to the beginning of the file.
U_CAPI void u_fclose(UFILE *file)
Close a UFILE.
U_CAPI int32_t u_fsetcodepage(const char *codepage, UFILE *file)
Set the codepage in which data will be written to and read from the UFILE.
U_CAPI UChar * u_fgets(UChar *s, int32_t n, UFILE *f)
Read one line of text into a UChar* string from a UFILE.
U_CAPI int32_t u_fsetlocale(UFILE *file, const char *locale)
Set the locale whose conventions will be used to format and parse output.
U_CAPI int32_t u_printf_u(const UChar *patternSpecification,...)
Write formatted data to stdout.
U_CAPI 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...
U_CAPI int32_t u_printf(const char *patternSpecification,...)
Write formatted data to stdout.
U_CAPI int32_t u_sprintf(UChar *buffer, const char *patternSpecification,...)
Write formatted data to a Unicode string.
U_CAPI int32_t u_fscanf(UFILE *f, const char *patternSpecification,...)
Read formatted data from a UFILE.
U_CAPI UFILE * u_get_stdout(void)
Get a UFILE for stdout.
U_CAPI int32_t u_sscanf(const UChar *buffer, const char *patternSpecification,...)
Read formatted data from a Unicode string.
U_CAPI UFILE * u_fadopt(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
U_CAPI FILE * u_fgetfile(UFILE *f)
Get the FILE* associated with a UFILE.
U_CAPI int32_t u_fputs(const UChar *s, UFILE *f)
Write a Unicode to a UFILE.
U_CAPI int32_t u_file_read(UChar *chars, int32_t count, UFILE *f)
Read Unicode from a UFILE.
U_CAPI UTransliterator * u_fsettransliterator(UFILE *file, UFileDirection direction, UTransliterator *adopt, UErrorCode *status)
Set a transliterator on the UFILE.
U_CAPI int32_t u_vsprintf_u(UChar *buffer, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
U_CAPI int32_t u_snprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
U_CAPI UChar32 u_fungetc(UChar32 c, UFILE *f)
Unget a UChar from a UFILE.
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:222
U_CAPI int32_t u_vsscanf(const UChar *buffer, const char *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
U_CAPI UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
U_CAPI UFILE * u_fstropen(UChar *stringBuf, int32_t capacity, const char *locale)
Create a UFILE that can be used for localized formatting or parsing.
U_CAPI int32_t u_snprintf(UChar *buffer, int32_t count, const char *patternSpecification,...)
Write formatted data to a Unicode string.
U_CAPI UFILE * u_fopen(const char *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE.
U_CAPI int32_t u_sscanf_u(const UChar *buffer, const UChar *patternSpecification,...)
Read formatted data from a Unicode string.
U_CAPI int32_t u_sprintf_u(UChar *buffer, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
U_CAPI int32_t u_fprintf(UFILE *f, const char *patternSpecification,...)
Write formatted data to a UFILE.
U_CAPI UChar32 u_fgetcx(UFILE *f)
Read a UChar32 from a UFILE.
U_CAPI UConverter * u_fgetConverter(UFILE *f)
Returns an alias to the converter being used for this file.
U_CAPI int32_t u_vsnprintf(UChar *buffer, int32_t count, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
struct UFILE UFILE
Forward declaration of a Unicode-aware file.
Definition: ustdio.h:215
U_CAPI UFILE * u_finit(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
U_CAPI int32_t u_vsprintf(UChar *buffer, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
U_CAPI int32_t u_vsscanf_u(const UChar *buffer, const UChar *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
U_CAPI int32_t u_vfscanf(UFILE *f, const char *patternSpecification, va_list ap)
Read formatted data from a UFILE.
C API: Transliterator.
void * UTransliterator
An opaque transliterator for use in C.
Definition: utrans.h:73
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415