ICU 62.1  62.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/localpointer.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 
212 typedef struct UFILE UFILE;
213 
219 typedef enum {
220  U_READ = 1,
221  U_WRITE = 2,
222  U_READWRITE =3 /* == (U_READ | U_WRITE) */
224 
242 U_STABLE UFILE* U_EXPORT2
243 u_fopen(const char *filename,
244  const char *perm,
245  const char *locale,
246  const char *codepage);
247 
265 U_STABLE UFILE* U_EXPORT2
266 u_fopen_u(const UChar *filename,
267  const char *perm,
268  const char *locale,
269  const char *codepage);
270 
287 U_STABLE UFILE* U_EXPORT2
288 u_finit(FILE *f,
289  const char *locale,
290  const char *codepage);
291 
308 U_STABLE UFILE* U_EXPORT2
309 u_fadopt(FILE *f,
310  const char *locale,
311  const char *codepage);
312 
327 U_STABLE UFILE* U_EXPORT2
328 u_fstropen(UChar *stringBuf,
329  int32_t capacity,
330  const char *locale);
331 
338 U_STABLE void U_EXPORT2
339 u_fclose(UFILE *file);
340 
341 #if U_SHOW_CPLUSPLUS_API
342 
344 
355 
357 
358 #endif
359 
368 U_STABLE UBool U_EXPORT2
369 u_feof(UFILE *f);
370 
381 U_STABLE void U_EXPORT2
382 u_fflush(UFILE *file);
383 
389 U_STABLE void
390 u_frewind(UFILE *file);
391 
398 U_STABLE FILE* U_EXPORT2
399 u_fgetfile(UFILE *f);
400 
401 #if !UCONFIG_NO_FORMATTING
402 
411 U_STABLE const char* U_EXPORT2
412 u_fgetlocale(UFILE *file);
413 
422 U_STABLE int32_t U_EXPORT2
423 u_fsetlocale(UFILE *file,
424  const char *locale);
425 
426 #endif
427 
437 U_STABLE const char* U_EXPORT2
438 u_fgetcodepage(UFILE *file);
439 
455 U_STABLE int32_t U_EXPORT2
456 u_fsetcodepage(const char *codepage,
457  UFILE *file);
458 
459 
467 
468 #if !UCONFIG_NO_FORMATTING
469 
475  U_STABLE const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f);
476 
477 /* Output functions */
478 
486 U_STABLE int32_t U_EXPORT2
487 u_printf(const char *patternSpecification,
488  ... );
489 
498 U_STABLE int32_t U_EXPORT2
499 u_fprintf(UFILE *f,
500  const char *patternSpecification,
501  ... );
502 
515 U_STABLE int32_t U_EXPORT2
516 u_vfprintf(UFILE *f,
517  const char *patternSpecification,
518  va_list ap);
519 
527 U_STABLE int32_t U_EXPORT2
528 u_printf_u(const UChar *patternSpecification,
529  ... );
530 
536 U_STABLE UFILE * U_EXPORT2
537 u_get_stdout(void);
538 
547 U_STABLE int32_t U_EXPORT2
548 u_fprintf_u(UFILE *f,
549  const UChar *patternSpecification,
550  ... );
551 
564 U_STABLE int32_t U_EXPORT2
566  const UChar *patternSpecification,
567  va_list ap);
568 #endif
569 
579 U_STABLE int32_t U_EXPORT2
580 u_fputs(const UChar *s,
581  UFILE *f);
582 
590 U_STABLE UChar32 U_EXPORT2
591 u_fputc(UChar32 uc,
592  UFILE *f);
593 
605 U_STABLE int32_t U_EXPORT2
606 u_file_write(const UChar *ustring,
607  int32_t count,
608  UFILE *f);
609 
610 
611 /* Input functions */
612 #if !UCONFIG_NO_FORMATTING
613 
623 U_STABLE int32_t U_EXPORT2
624 u_fscanf(UFILE *f,
625  const char *patternSpecification,
626  ... );
627 
641 U_STABLE int32_t U_EXPORT2
642 u_vfscanf(UFILE *f,
643  const char *patternSpecification,
644  va_list ap);
645 
655 U_STABLE int32_t U_EXPORT2
656 u_fscanf_u(UFILE *f,
657  const UChar *patternSpecification,
658  ... );
659 
673 U_STABLE int32_t U_EXPORT2
674 u_vfscanf_u(UFILE *f,
675  const UChar *patternSpecification,
676  va_list ap);
677 #endif
678 
691 U_STABLE UChar* U_EXPORT2
692 u_fgets(UChar *s,
693  int32_t n,
694  UFILE *f);
695 
705 U_STABLE UChar U_EXPORT2
706 u_fgetc(UFILE *f);
707 
718 U_STABLE UChar32 U_EXPORT2
719 u_fgetcx(UFILE *f);
720 
732 U_STABLE UChar32 U_EXPORT2
734  UFILE *f);
735 
746 U_STABLE int32_t U_EXPORT2
747 u_file_read(UChar *chars,
748  int32_t count,
749  UFILE *f);
750 
751 #if !UCONFIG_NO_TRANSLITERATION
752 
770 U_STABLE UTransliterator* U_EXPORT2
771 u_fsettransliterator(UFILE *file, UFileDirection direction,
772  UTransliterator *adopt, UErrorCode *status);
773 
774 #endif
775 
776 
777 /* Output string functions */
778 #if !UCONFIG_NO_FORMATTING
779 
780 
791 U_STABLE int32_t U_EXPORT2
792 u_sprintf(UChar *buffer,
793  const char *patternSpecification,
794  ... );
795 
813 U_STABLE int32_t U_EXPORT2
814 u_snprintf(UChar *buffer,
815  int32_t count,
816  const char *patternSpecification,
817  ... );
818 
832 U_STABLE int32_t U_EXPORT2
833 u_vsprintf(UChar *buffer,
834  const char *patternSpecification,
835  va_list ap);
836 
857 U_STABLE int32_t U_EXPORT2
858 u_vsnprintf(UChar *buffer,
859  int32_t count,
860  const char *patternSpecification,
861  va_list ap);
862 
872 U_STABLE int32_t U_EXPORT2
873 u_sprintf_u(UChar *buffer,
874  const UChar *patternSpecification,
875  ... );
876 
893 U_STABLE int32_t U_EXPORT2
894 u_snprintf_u(UChar *buffer,
895  int32_t count,
896  const UChar *patternSpecification,
897  ... );
898 
912 U_STABLE int32_t U_EXPORT2
913 u_vsprintf_u(UChar *buffer,
914  const UChar *patternSpecification,
915  va_list ap);
916 
937 U_STABLE int32_t U_EXPORT2
938 u_vsnprintf_u(UChar *buffer,
939  int32_t count,
940  const UChar *patternSpecification,
941  va_list ap);
942 
943 /* Input string functions */
944 
955 U_STABLE int32_t U_EXPORT2
956 u_sscanf(const UChar *buffer,
957  const char *patternSpecification,
958  ... );
959 
974 U_STABLE int32_t U_EXPORT2
975 u_vsscanf(const UChar *buffer,
976  const char *patternSpecification,
977  va_list ap);
978 
989 U_STABLE int32_t U_EXPORT2
990 u_sscanf_u(const UChar *buffer,
991  const UChar *patternSpecification,
992  ... );
993 
1008 U_STABLE int32_t U_EXPORT2
1009 u_vsscanf_u(const UChar *buffer,
1010  const UChar *patternSpecification,
1011  va_list ap);
1012 
1013 
1014 #endif
1015 #endif
1016 #endif
1017 
1018 
u_fgetcodepage
const char * u_fgetcodepage(UFILE *file)
Get the codepage in which data is written to and read from the UFILE.
LocalUFILEPointer
u_feof
UBool u_feof(UFILE *f)
Tests if the UFILE is at the end of the file stream.
u_fsetcodepage
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_sprintf_u
int32_t u_sprintf_u(UChar *buffer, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
u_vsprintf
int32_t u_vsprintf(UChar *buffer, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
u_frewind
void u_frewind(UFILE *file)
Rewind the file pointer to the beginning of the file.
u_vsscanf_u
int32_t u_vsscanf_u(const UChar *buffer, const UChar *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
UBool
int8_t UBool
The ICU boolean type.
Definition: umachine.h:236
u_fstropen
UFILE * u_fstropen(UChar *stringBuf, int32_t capacity, const char *locale)
Create a UFILE that can be used for localized formatting or parsing.
u_snprintf
int32_t u_snprintf(UChar *buffer, int32_t count, const char *patternSpecification,...)
Write formatted data to a Unicode string.
u_fadopt
UFILE * u_fadopt(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
u_printf_u
int32_t u_printf_u(const UChar *patternSpecification,...)
Write formatted data to stdout.
u_vfprintf_u
int32_t u_vfprintf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Write formatted data to a UFILE.
u_vfscanf_u
int32_t u_vfscanf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Read formatted data from a UFILE.
u_printf
int32_t u_printf(const char *patternSpecification,...)
Write formatted data to stdout.
u_vfscanf
int32_t u_vfscanf(UFILE *f, const char *patternSpecification, va_list ap)
Read formatted data from a UFILE.
u_fputc
UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
u_fsettransliterator
UTransliterator * u_fsettransliterator(UFILE *file, UFileDirection direction, UTransliterator *adopt, UErrorCode *status)
Set a transliterator on the UFILE.
u_vsnprintf_u
int32_t u_vsnprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
ucnv.h
C API: Character conversion.
u_fgetConverter
UConverter * u_fgetConverter(UFILE *f)
Returns an alias to the converter being used for this file.
u_fgets
UChar * u_fgets(UChar *s, int32_t n, UFILE *f)
Read one line of text into a UChar* string from a UFILE.
u_fclose
void u_fclose(UFILE *file)
Close a UFILE.
u_fgetfile
FILE * u_fgetfile(UFILE *f)
Get the FILE* associated with a UFILE.
u_fscanf
int32_t u_fscanf(UFILE *f, const char *patternSpecification,...)
Read formatted data from a UFILE.
unum.h
C API: Compatibility APIs for number formatting.
UFILE
struct UFILE UFILE
Forward declaration of a Unicode-aware file.
Definition: ustdio.h:212
u_vsprintf_u
int32_t u_vsprintf_u(UChar *buffer, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
u_fprintf
int32_t u_fprintf(UFILE *f, const char *patternSpecification,...)
Write formatted data to a UFILE.
UChar32
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition: umachine.h:400
UErrorCode
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers,...
Definition: utypes.h:396
u_finit
UFILE * u_finit(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
u_fprintf_u
int32_t u_fprintf_u(UFILE *f, const UChar *patternSpecification,...)
Write formatted data to a UFILE.
u_sscanf_u
int32_t u_sscanf_u(const UChar *buffer, const UChar *patternSpecification,...)
Read formatted data from a Unicode string.
u_fgetcx
UChar32 u_fgetcx(UFILE *f)
Read a UChar32 from a UFILE.
u_vsscanf
int32_t u_vsscanf(const UChar *buffer, const char *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
u_fgetlocale
const char * u_fgetlocale(UFILE *file)
Get the locale whose conventions are used to format and parse output.
u_fgetNumberFormat
const UNumberFormat * u_fgetNumberFormat(UFILE *f)
Returns an alias to the number formatter being used for this file.
UFileDirection
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:219
u_sscanf
int32_t u_sscanf(const UChar *buffer, const char *patternSpecification,...)
Read formatted data from a Unicode string.
u_vfprintf
int32_t u_vfprintf(UFILE *f, const char *patternSpecification, va_list ap)
Write formatted data to a UFILE.
U_DEFINE_LOCAL_OPEN_POINTER
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
Definition: localpointer.h:487
u_fopen
UFILE * u_fopen(const char *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE.
u_fflush
void u_fflush(UFILE *file)
Flush output of a UFILE.
u_fscanf_u
int32_t u_fscanf_u(UFILE *f, const UChar *patternSpecification,...)
Read formatted data from a UFILE.
u_fgetc
UChar u_fgetc(UFILE *f)
Read a UChar from a UFILE.
localpointer.h
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
UTransliterator
void * UTransliterator
An opaque transliterator for use in C.
Definition: utrans.h:70
u_sprintf
int32_t u_sprintf(UChar *buffer, const char *patternSpecification,...)
Write formatted data to a Unicode string.
U_STABLE
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:111
UNumberFormat
void * UNumberFormat
A number formatter.
Definition: unum.h:141
UConverter
struct UConverter UConverter
Definition: ucnv_err.h:96
u_file_write
int32_t u_file_write(const UChar *ustring, int32_t count, UFILE *f)
Write Unicode to a UFILE.
u_fsetlocale
int32_t u_fsetlocale(UFILE *file, const char *locale)
Set the locale whose conventions will be used to format and parse output.
utrans.h
C API: Transliterator.
UChar
uint16_t UChar
Definition: umachine.h:353
u_file_read
int32_t u_file_read(UChar *chars, int32_t count, UFILE *f)
Read Unicode from a UFILE.
u_get_stdout
UFILE * u_get_stdout(void)
Get a UFILE for stdout.
u_fputs
int32_t u_fputs(const UChar *s, UFILE *f)
Write a Unicode to a UFILE.
U_NAMESPACE_END
#define U_NAMESPACE_END
Definition: uversion.h:138
U_NAMESPACE_BEGIN
#define U_NAMESPACE_BEGIN
Definition: uversion.h:137
u_fungetc
UChar32 u_fungetc(UChar32 c, UFILE *f)
Unget a UChar from a UFILE.
u_vsnprintf
int32_t u_vsnprintf(UChar *buffer, int32_t count, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
u_fopen_u
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_snprintf_u
int32_t u_snprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.