ICU 4.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ustdio.h
Go to the documentation of this file.
1 /*
2 ******************************************************************************
3 *
4 * Copyright (C) 1998-2009, 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 
32 /*
33  TODO
34  The following is a small list as to what is currently wrong/suggestions for
35  ustdio.
36 
37  * Make sure that * in the scanf format specification works for all formats.
38  * Each UFILE takes up at least 2KB.
39  Look into adding setvbuf() for configurable buffers.
40  * This library does buffering. The OS should do this for us already. Check on
41  this, and remove it from this library, if this is the case. Double buffering
42  wastes a lot of time and space.
43  * Test stdin and stdout with the u_f* functions
44  * Testing should be done for reading and writing multi-byte encodings,
45  and make sure that a character that is contained across buffer boundries
46  works even for incomplete characters.
47  * Make sure that the last character is flushed when the file/string is closed.
48  * snprintf should follow the C99 standard for the return value, which is
49  return the number of characters (excluding the trailing '\0')
50  which would have been written to the destination string regardless
51  of available space. This is like pre-flighting.
52  * Everything that uses %s should do what operator>> does for UnicodeString.
53  It should convert one byte at a time, and once a character is
54  converted then check to see if it's whitespace or in the scanset.
55  If it's whitespace or in the scanset, put all the bytes back (do nothing
56  for sprintf/sscanf).
57  * If bad string data is encountered, make sure that the function fails
58  without memory leaks and the unconvertable characters are valid
59  substitution or are escaped characters.
60  * u_fungetc() can't unget a character when it's at the beginning of the
61  internal conversion buffer. For example, read the buffer size # of
62  characters, and then ungetc to get the previous character that was
63  at the end of the last buffer.
64  * u_fflush() and u_fclose should return an int32_t like C99 functions.
65  0 is returned if the operation was successful and EOF otherwise.
66  * u_fsettransliterator does not support U_READ side of transliteration.
67  * The format specifier should limit the size of a format or honor it in
68  order to prevent buffer overruns. (e.g. %256.256d).
69  * u_fread and u_fwrite don't exist. They're needed for reading and writing
70  data structures without any conversion.
71  * u_file_read and u_file_write are used for writing strings. u_fgets and
72  u_fputs or u_fread and u_fwrite should be used to do this.
73  * The width parameter for all scanf formats, including scanset, needs
74  better testing. This prevents buffer overflows.
75  * Figure out what is suppose to happen when a codepage is changed midstream.
76  Maybe a flush or a rewind are good enough.
77  * Make sure that a UFile opened with "rw" can be used after using
78  u_fflush with a u_frewind.
79  * scanf(%i) should detect what type of number to use.
80  * Add more testing of the alternate format, %#
81  * Look at newline handling of fputs/puts
82  * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
83  * Complete the file documentation with proper doxygen formatting.
84  See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
85 */
86 
203 #define U_EOF 0xFFFF
204 
206 typedef struct UFILE UFILE;
207 
213 typedef enum {
214  U_READ = 1,
215  U_WRITE = 2,
216  U_READWRITE =3 /* == (U_READ | U_WRITE) */
218 
237 u_fopen(const char *filename,
238  const char *perm,
239  const char *locale,
240  const char *codepage);
241 
256 u_finit(FILE *f,
257  const char *locale,
258  const char *codepage);
259 
275 u_fstropen(UChar *stringBuf,
276  int32_t capacity,
277  const char *locale);
278 
284 U_DRAFT void U_EXPORT2
285 u_fclose(UFILE *file);
286 
296 u_feof(UFILE *f);
297 
306 U_DRAFT void U_EXPORT2
307 u_fflush(UFILE *file);
308 
314 U_DRAFT void
315 u_frewind(UFILE *file);
316 
323 U_DRAFT FILE* U_EXPORT2
324 u_fgetfile(UFILE *f);
325 
326 #if !UCONFIG_NO_FORMATTING
327 
336 U_DRAFT const char* U_EXPORT2
337 u_fgetlocale(UFILE *file);
338 
348 u_fsetlocale(UFILE *file,
349  const char *locale);
350 
351 #endif
352 
362 U_DRAFT const char* U_EXPORT2
363 u_fgetcodepage(UFILE *file);
364 
381 u_fsetcodepage(const char *codepage,
382  UFILE *file);
383 
384 
392 
393 #if !UCONFIG_NO_FORMATTING
394 
395 /* Output functions */
396 
406 u_fprintf(UFILE *f,
407  const char *patternSpecification,
408  ... );
409 
423 u_vfprintf(UFILE *f,
424  const char *patternSpecification,
425  va_list ap);
426 
436 u_fprintf_u(UFILE *f,
437  const UChar *patternSpecification,
438  ... );
439 
454  const UChar *patternSpecification,
455  va_list ap);
456 #endif
457 
468 u_fputs(const UChar *s,
469  UFILE *f);
470 
479 u_fputc(UChar32 uc,
480  UFILE *f);
481 
494 u_file_write(const UChar *ustring,
495  int32_t count,
496  UFILE *f);
497 
498 
499 /* Input functions */
500 #if !UCONFIG_NO_FORMATTING
501 
512 u_fscanf(UFILE *f,
513  const char *patternSpecification,
514  ... );
515 
530 u_vfscanf(UFILE *f,
531  const char *patternSpecification,
532  va_list ap);
533 
544 u_fscanf_u(UFILE *f,
545  const UChar *patternSpecification,
546  ... );
547 
562 u_vfscanf_u(UFILE *f,
563  const UChar *patternSpecification,
564  va_list ap);
565 #endif
566 
580 u_fgets(UChar *s,
581  int32_t n,
582  UFILE *f);
583 
594 u_fgetc(UFILE *f);
595 
607 u_fgetcx(UFILE *f);
608 
622  UFILE *f);
623 
635 u_file_read(UChar *chars,
636  int32_t count,
637  UFILE *f);
638 
639 #if !UCONFIG_NO_TRANSLITERATION
640 
659 u_fsettransliterator(UFILE *file, UFileDirection direction,
660  UTransliterator *adopt, UErrorCode *status);
661 
662 #endif
663 
664 
665 /* Output string functions */
666 #if !UCONFIG_NO_FORMATTING
667 
668 
680 u_sprintf(UChar *buffer,
681  const char *patternSpecification,
682  ... );
683 
702 u_snprintf(UChar *buffer,
703  int32_t count,
704  const char *patternSpecification,
705  ... );
706 
721 u_vsprintf(UChar *buffer,
722  const char *patternSpecification,
723  va_list ap);
724 
746 u_vsnprintf(UChar *buffer,
747  int32_t count,
748  const char *patternSpecification,
749  va_list ap);
750 
761 u_sprintf_u(UChar *buffer,
762  const UChar *patternSpecification,
763  ... );
764 
782 u_snprintf_u(UChar *buffer,
783  int32_t count,
784  const UChar *patternSpecification,
785  ... );
786 
801 u_vsprintf_u(UChar *buffer,
802  const UChar *patternSpecification,
803  va_list ap);
804 
826 u_vsnprintf_u(UChar *buffer,
827  int32_t count,
828  const UChar *patternSpecification,
829  va_list ap);
830 
831 /* Input string functions */
832 
844 u_sscanf(const UChar *buffer,
845  const char *patternSpecification,
846  ... );
847 
863 u_vsscanf(const UChar *buffer,
864  const char *patternSpecification,
865  va_list ap);
866 
878 u_sscanf_u(const UChar *buffer,
879  const UChar *patternSpecification,
880  ... );
881 
897 u_vsscanf_u(const UChar *buffer,
898  const UChar *patternSpecification,
899  va_list ap);
900 
901 #endif
902 #endif
903 
904 
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:66
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.
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:206
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:213
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.
UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
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.
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:319
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.
#define U_EXPORT2
Definition: platform.h:338
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 wchar_t if that is 16 bits wide; always assumed to be unsigned.
Definition: umachine.h:299
int32_t u_sscanf(const UChar *buffer, const char *patternSpecification,...)
Read formatted data from a Unicode string.
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
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:593
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:119
C API: Character conversion.
signed int int32_t
Define 64 bit limits.
Definition: pwin32.h:143
int8_t UBool
The ICU boolean type.
Definition: umachine.h:208