ICU 50.1.2  50.1.2
ustdio.h
Go to the documentation of this file.
1 /*
2 ******************************************************************************
3 *
4 * Copyright (C) 1998-2012, International Business Machines
5 * Corporation and others. All Rights Reserved.
6 *
7 ******************************************************************************
8 *
9 * File ustdio.h
10 *
11 * Modification History:
12 *
13 * Date Name Description
14 * 10/16/98 stephen Creation.
15 * 11/06/98 stephen Modified per code review.
16 * 03/12/99 stephen Modified for new C API.
17 * 07/19/99 stephen Minor doc update.
18 * 02/01/01 george Added sprintf & sscanf with all of its variants
19 ******************************************************************************
20 */
21 
22 #ifndef USTDIO_H
23 #define USTDIO_H
24 
25 #include <stdio.h>
26 #include <stdarg.h>
27 
28 #include "unicode/utypes.h"
29 #include "unicode/ucnv.h"
30 #include "unicode/utrans.h"
31 #include "unicode/localpointer.h"
32 
33 /*
34  TODO
35  The following is a small list as to what is currently wrong/suggestions for
36  ustdio.
37 
38  * Make sure that * in the scanf format specification works for all formats.
39  * Each UFILE takes up at least 2KB.
40  Look into adding setvbuf() for configurable buffers.
41  * This library does buffering. The OS should do this for us already. Check on
42  this, and remove it from this library, if this is the case. Double buffering
43  wastes a lot of time and space.
44  * Test stdin and stdout with the u_f* functions
45  * Testing should be done for reading and writing multi-byte encodings,
46  and make sure that a character that is contained across buffer boundries
47  works even for incomplete characters.
48  * Make sure that the last character is flushed when the file/string is closed.
49  * snprintf should follow the C99 standard for the return value, which is
50  return the number of characters (excluding the trailing '\0')
51  which would have been written to the destination string regardless
52  of available space. This is like pre-flighting.
53  * Everything that uses %s should do what operator>> does for UnicodeString.
54  It should convert one byte at a time, and once a character is
55  converted then check to see if it's whitespace or in the scanset.
56  If it's whitespace or in the scanset, put all the bytes back (do nothing
57  for sprintf/sscanf).
58  * If bad string data is encountered, make sure that the function fails
59  without memory leaks and the unconvertable characters are valid
60  substitution or are escaped characters.
61  * u_fungetc() can't unget a character when it's at the beginning of the
62  internal conversion buffer. For example, read the buffer size # of
63  characters, and then ungetc to get the previous character that was
64  at the end of the last buffer.
65  * u_fflush() and u_fclose should return an int32_t like C99 functions.
66  0 is returned if the operation was successful and EOF otherwise.
67  * u_fsettransliterator does not support U_READ side of transliteration.
68  * The format specifier should limit the size of a format or honor it in
69  order to prevent buffer overruns. (e.g. %256.256d).
70  * u_fread and u_fwrite don't exist. They're needed for reading and writing
71  data structures without any conversion.
72  * u_file_read and u_file_write are used for writing strings. u_fgets and
73  u_fputs or u_fread and u_fwrite should be used to do this.
74  * The width parameter for all scanf formats, including scanset, needs
75  better testing. This prevents buffer overflows.
76  * Figure out what is suppose to happen when a codepage is changed midstream.
77  Maybe a flush or a rewind are good enough.
78  * Make sure that a UFile opened with "rw" can be used after using
79  u_fflush with a u_frewind.
80  * scanf(%i) should detect what type of number to use.
81  * Add more testing of the alternate format, %#
82  * Look at newline handling of fputs/puts
83  * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
84  * Complete the file documentation with proper doxygen formatting.
85  See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
86 */
87 
204 #define U_EOF 0xFFFF
205 
207 typedef struct UFILE UFILE;
208 
214 typedef enum {
215  U_READ = 1,
216  U_WRITE = 2,
217  U_READWRITE =3 /* == (U_READ | U_WRITE) */
219 
237 U_STABLE UFILE* U_EXPORT2
238 u_fopen(const char *filename,
239  const char *perm,
240  const char *locale,
241  const char *codepage);
242 
259 U_STABLE UFILE* U_EXPORT2
260 u_finit(FILE *f,
261  const char *locale,
262  const char *codepage);
263 
280 U_STABLE UFILE* U_EXPORT2
281 u_fadopt(FILE *f,
282  const char *locale,
283  const char *codepage);
284 
299 U_STABLE UFILE* U_EXPORT2
300 u_fstropen(UChar *stringBuf,
301  int32_t capacity,
302  const char *locale);
303 
310 U_STABLE void U_EXPORT2
311 u_fclose(UFILE *file);
312 
313 #if U_SHOW_CPLUSPLUS_API
314 
316 
327 
329 
330 #endif
331 
340 U_STABLE UBool U_EXPORT2
341 u_feof(UFILE *f);
342 
353 U_STABLE void U_EXPORT2
354 u_fflush(UFILE *file);
355 
361 U_STABLE void
362 u_frewind(UFILE *file);
363 
370 U_STABLE FILE* U_EXPORT2
371 u_fgetfile(UFILE *f);
372 
373 #if !UCONFIG_NO_FORMATTING
374 
383 U_STABLE const char* U_EXPORT2
384 u_fgetlocale(UFILE *file);
385 
394 U_STABLE int32_t U_EXPORT2
395 u_fsetlocale(UFILE *file,
396  const char *locale);
397 
398 #endif
399 
409 U_STABLE const char* U_EXPORT2
410 u_fgetcodepage(UFILE *file);
411 
427 U_STABLE int32_t U_EXPORT2
428 u_fsetcodepage(const char *codepage,
429  UFILE *file);
430 
431 
439 
440 #if !UCONFIG_NO_FORMATTING
441 
442 /* Output functions */
443 
451 U_DRAFT int32_t U_EXPORT2
452 u_printf(const char *patternSpecification,
453  ... );
454 
463 U_STABLE int32_t U_EXPORT2
464 u_fprintf(UFILE *f,
465  const char *patternSpecification,
466  ... );
467 
480 U_STABLE int32_t U_EXPORT2
481 u_vfprintf(UFILE *f,
482  const char *patternSpecification,
483  va_list ap);
484 
492 U_DRAFT int32_t U_EXPORT2
493 u_printf_u(const UChar *patternSpecification,
494  ... );
495 
501 U_DRAFT UFILE * U_EXPORT2
502 u_get_stdout(void);
503 
512 U_STABLE int32_t U_EXPORT2
513 u_fprintf_u(UFILE *f,
514  const UChar *patternSpecification,
515  ... );
516 
529 U_STABLE int32_t U_EXPORT2
531  const UChar *patternSpecification,
532  va_list ap);
533 #endif
534 
544 U_STABLE int32_t U_EXPORT2
545 u_fputs(const UChar *s,
546  UFILE *f);
547 
555 U_STABLE UChar32 U_EXPORT2
556 u_fputc(UChar32 uc,
557  UFILE *f);
558 
570 U_STABLE int32_t U_EXPORT2
571 u_file_write(const UChar *ustring,
572  int32_t count,
573  UFILE *f);
574 
575 
576 /* Input functions */
577 #if !UCONFIG_NO_FORMATTING
578 
588 U_STABLE int32_t U_EXPORT2
589 u_fscanf(UFILE *f,
590  const char *patternSpecification,
591  ... );
592 
606 U_STABLE int32_t U_EXPORT2
607 u_vfscanf(UFILE *f,
608  const char *patternSpecification,
609  va_list ap);
610 
620 U_STABLE int32_t U_EXPORT2
621 u_fscanf_u(UFILE *f,
622  const UChar *patternSpecification,
623  ... );
624 
638 U_STABLE int32_t U_EXPORT2
639 u_vfscanf_u(UFILE *f,
640  const UChar *patternSpecification,
641  va_list ap);
642 #endif
643 
656 U_STABLE UChar* U_EXPORT2
657 u_fgets(UChar *s,
658  int32_t n,
659  UFILE *f);
660 
670 U_STABLE UChar U_EXPORT2
671 u_fgetc(UFILE *f);
672 
683 U_STABLE UChar32 U_EXPORT2
684 u_fgetcx(UFILE *f);
685 
697 U_STABLE UChar32 U_EXPORT2
699  UFILE *f);
700 
711 U_STABLE int32_t U_EXPORT2
712 u_file_read(UChar *chars,
713  int32_t count,
714  UFILE *f);
715 
716 #if !UCONFIG_NO_TRANSLITERATION
717 
735 U_STABLE UTransliterator* U_EXPORT2
736 u_fsettransliterator(UFILE *file, UFileDirection direction,
737  UTransliterator *adopt, UErrorCode *status);
738 
739 #endif
740 
741 
742 /* Output string functions */
743 #if !UCONFIG_NO_FORMATTING
744 
745 
756 U_STABLE int32_t U_EXPORT2
757 u_sprintf(UChar *buffer,
758  const char *patternSpecification,
759  ... );
760 
778 U_STABLE int32_t U_EXPORT2
779 u_snprintf(UChar *buffer,
780  int32_t count,
781  const char *patternSpecification,
782  ... );
783 
797 U_STABLE int32_t U_EXPORT2
798 u_vsprintf(UChar *buffer,
799  const char *patternSpecification,
800  va_list ap);
801 
822 U_STABLE int32_t U_EXPORT2
823 u_vsnprintf(UChar *buffer,
824  int32_t count,
825  const char *patternSpecification,
826  va_list ap);
827 
837 U_STABLE int32_t U_EXPORT2
838 u_sprintf_u(UChar *buffer,
839  const UChar *patternSpecification,
840  ... );
841 
858 U_STABLE int32_t U_EXPORT2
859 u_snprintf_u(UChar *buffer,
860  int32_t count,
861  const UChar *patternSpecification,
862  ... );
863 
877 U_STABLE int32_t U_EXPORT2
878 u_vsprintf_u(UChar *buffer,
879  const UChar *patternSpecification,
880  va_list ap);
881 
902 U_STABLE int32_t U_EXPORT2
903 u_vsnprintf_u(UChar *buffer,
904  int32_t count,
905  const UChar *patternSpecification,
906  va_list ap);
907 
908 /* Input string functions */
909 
920 U_STABLE int32_t U_EXPORT2
921 u_sscanf(const UChar *buffer,
922  const char *patternSpecification,
923  ... );
924 
939 U_STABLE int32_t U_EXPORT2
940 u_vsscanf(const UChar *buffer,
941  const char *patternSpecification,
942  va_list ap);
943 
954 U_STABLE int32_t U_EXPORT2
955 u_sscanf_u(const UChar *buffer,
956  const UChar *patternSpecification,
957  ... );
958 
973 U_STABLE int32_t U_EXPORT2
974 u_vsscanf_u(const UChar *buffer,
975  const UChar *patternSpecification,
976  va_list ap);
977 
978 #endif
979 #endif
980 
981 
UFILE * u_fopen(const char *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE.
int32_t u_fputs(const UChar *s, UFILE *f)
Write a Unicode to a UFILE.
UChar u_fgetc(UFILE *f)
Read a UChar from a UFILE.
void * UTransliterator
An opaque transliterator for use in C.
Definition: utrans.h:67
int32_t u_vsscanf(const UChar *buffer, const char *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
int32_t u_fscanf_u(UFILE *f, const UChar *patternSpecification,...)
Read formatted data from a UFILE.
int32_t u_printf(const char *patternSpecification,...)
Write formatted data to stdout.
UTransliterator * u_fsettransliterator(UFILE *file, UFileDirection direction, UTransliterator *adopt, UErrorCode *status)
Set a transliterator on the 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.
struct UFILE UFILE
Forward declaration of a Unicode-aware file.
Definition: ustdio.h:207
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:214
int32_t u_fscanf(UFILE *f, const char *patternSpecification,...)
Read formatted data from a UFILE.
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.
void u_frewind(UFILE *file)
Rewind the file pointer to the beginning of the file.
UFILE * u_get_stdout(void)
Get a UFILE for stdout.
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:129
UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
&quot;Smart pointer&quot; definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:290
int32_t u_vfprintf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Write formatted data to a UFILE.
int32_t u_sprintf(UChar *buffer, const char *patternSpecification,...)
Write formatted data to a Unicode string.
C++ API: &quot;Smart pointers&quot; for use with and in ICU4C C++ code.
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_vsnprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition: umachine.h:298
int32_t u_vsprintf_u(UChar *buffer, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
UConverter * u_fgetConverter(UFILE *f)
Returns an alias to the converter being used for this file.
UBool u_feof(UFILE *f)
Tests if the UFILE is at the end of the file stream.
C API: Transliterator.
int32_t u_fsetlocale(UFILE *file, const char *locale)
Set the locale whose conventions will be used to format and parse output.
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_vsnprintf(UChar *buffer, int32_t count, const char *patternSpecification, va_list ap)
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_sprintf_u(UChar *buffer, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
int32_t u_vfscanf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Read formatted data from a UFILE.
uint16_t UChar
Define UChar to be UCHAR_TYPE, if that is #defined (for example, to char16_t), or wchar_t if that is ...
Definition: umachine.h:278
int32_t u_sscanf(const UChar *buffer, const char *patternSpecification,...)
Read formatted data from a Unicode string.
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:130
const char * u_fgetcodepage(UFILE *file)
Get the codepage in which data is written to and read from the UFILE.
FILE * u_fgetfile(UFILE *f)
Get the FILE* associated with a UFILE.
int32_t u_vfscanf(UFILE *f, const char *patternSpecification, va_list ap)
Read formatted data from a UFILE.
int32_t u_fprintf_u(UFILE *f, const UChar *patternSpecification,...)
Write formatted data to a UFILE.
UChar32 u_fungetc(UChar32 c, UFILE *f)
Unget a UChar from a UFILE.
UChar32 u_fgetcx(UFILE *f)
Read a UChar32 from a UFILE.
struct UConverter UConverter
Definition: ucnv_err.h:94
&quot;Smart pointer&quot; class, closes a UFILE via u_fclose().
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:476
int32_t u_printf_u(const UChar *patternSpecification,...)
Write formatted data to stdout.
UFILE * u_finit(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
int32_t u_fprintf(UFILE *f, const char *patternSpecification,...)
Write formatted data to a UFILE.
Basic definitions for ICU, for both C and C++ APIs.
int32_t u_snprintf(UChar *buffer, int32_t count, const char *patternSpecification,...)
Write formatted data to a Unicode string.
int32_t u_snprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
void u_fclose(UFILE *file)
Close a UFILE.
int32_t u_vsscanf_u(const UChar *buffer, const UChar *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
const char * u_fgetlocale(UFILE *file)
Get the locale whose conventions are used to format and parse output.
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_sscanf_u(const UChar *buffer, const UChar *patternSpecification,...)
Read formatted data from a Unicode string.
#define U_DRAFT
This is used to declare a function as a draft public ICU C API.
Definition: umachine.h:111
C API: Character conversion.
UFILE * u_fadopt(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:109
int8_t UBool
The ICU boolean type.
Definition: umachine.h:200