From kido@vnet.IBM.COM Mon Mar 15 03:25:00 1993
Received: from vnet.IBM.COM ([192.239.48.4]) by dkuug.dk with SMTP id AA29460
  (5.65c8/IDA-1.4.4j); Mon, 15 Mar 1993 03:00:20 +0100
Message-Id: <199303150200.AA29460@dkuug.dk>
Received: from YMTVM8 by vnet.IBM.COM (IBM VM SMTP V2R2) with BSMTP id 4015;
   Sun, 14 Mar 93 20:59:39 EST
Date: Mon, 15 Mar 93 10:59:57 JST
From: "Akio    Kido" <kido@vnet.IBM.COM>
To: sc22wg15@dkuug.dk, sc22wg20@dkuug.dk, XoJIG@xopen.co.uk,
        sig-international@osf.org, uojlg-bse@uiap.ui.org,
        efischer@donald.aix.kingston.ibm.com
Subject: MSE 4.5.3.1.mm
X-Charset: ASCII
X-Char-Esc: 29

.SK
.H 3 Input/output
.eX 7.9.1
.P
The header
.Cf <wchar.h>
declares a number of functions useful
for wide character input and output.
.P
The wide character input/output functions described in this subclause
provide operations analogous to most of those described in \*(AC subclause 7.9,
except that the fundamental units internal to the program
are wide characters,
although the external representation
(in the file)
is multibyte characters.
.P
The input/output functions described here and in \*(AC
are given the following collective terms:
.DL
.LI
The
.I "wide character input functions"
\(em those functions described in this subclause
that perform input on wide characters and wide strings:
.Cf fgetwc ,
.Cf fgetws ,
.Cf getwc ,
.Cf getwchar ,
.Cf fwscanf ,
and
.Cf wscanf .
.LI
The
.I "wide character output functions"
\(em those functions described in this subclause
that perform output on wide characters and wide strings:
.Cf fputwc ,
.Cf fputws ,
.Cf putwc ,
.Cf putwchar ,
.Cf fwprintf ,
.Cf wprintf ,
.Cf vfwprintf ,
and
.Cf vwprintf .
.LI
The
.I "wide character input/output functions"
\(em the union of the
.Cf ungetwc
function,
the wide character input functions,
and the wide character output functions.
.LI
The
.I "byte input/output functions"
\(em the
.Cf ungetc
function and the input/output functions described in \*(AC subclause 7.9:
.Cf fgetc ,
.Cf fgets ,
.Cf fprintf ,
.Cf fputc ,
.Cf fputs ,
.Cf fread ,
.Cf fscanf ,
.Cf fwrite ,
.Cf getc ,
.Cf getchar ,
.Cf gets ,
.Cf printf ,
.Cf putc ,
.Cf putchar ,
.Cf puts ,
.Cf scanf ,
.Cf vfprintf ,
and
.Cf vprintf .
.LE
.H 4 Streams
.eX 7.9.2
.P
The definition of a stream is adjusted to include an
.I orientation
for both text and binary streams.
After a stream is associated with an external file,
but before any operations are performed on it,
the stream is without orientation.
Once a wide character input/output function has been applied
to a stream without orientation,
the stream becomes
.IR wide-oriented .
Similarly,
once a byte input/output function has been applied
to a stream without orientation,
the stream becomes
.IR byte-oriented .
Only a successful call to the
.Cf freopen
function can otherwise alter the orientation of a stream;
it removes any orientation.
.P
Byte input/output functions shall not be applied
to a wide-oriented stream;
and wide character input/output functions shall not be applied
to a byte-oriented stream.
The remaining stream operations
do not affect and are not affected by a stream's orientation,
except for the following additional restrictions:
.DL
.LI
Binary wide-oriented streams
have the file positioning restrictions
ascribed to both text and binary streams.
.LI
For wide-oriented streams,
after a successful call to a file positioning function
that leaves the file position indicator prior to the end-of-file,
a wide character output function can overwrite
a partial multibyte character;
any file contents beyond the byte(s) written
are henceforth undefined.
.LE
.H 4 Files
.eX 7.9.3
.P
Although both text and binary wide-oriented streams
are conceptually sequences of wide characters,
the external file associated with a wide-oriented stream
is a sequence of multibyte characters,
beginning in the initial shift state.
The shift state at end-of-file is unspecified.
.P
The wide character input functions read multibyte characters from the stream
and convert them to wide characters
as if they were read by successive calls to the
.Cf fgetwc
function.
Each conversion occurs as if by a call to the
.Cf mbrtowc
function,
with the conversion state described by the stream's own
.Cf mbstate_t
object.
.P
The wide character output functions convert wide characters
to multibyte characters and write them to the stream
as if they were written by successive calls to the
.Cf fputwc
function.
Each conversion occurs as if by a call to the
.Cf wcrtomb
function,
with the conversion state described by the stream's own
.Cf mbstate_t
object.
.P
An
.I "encoding error"
occurs if the character sequence presented to the underlying
.Cf mbrtowc
function does not form a valid multibyte character,
or if the code value passed to the underlying
.Cf wcrtomb
does not correspond to a valid multibyte character.
The wide character input/output functions
and the byte input/output functions
shall store the value of the macro
.Cf EILSEQ
in
.Cf errno
if and only if an encoding error occurs.
.rF
the
.Cf fgetwc
function (4.5.3.6.1),
the
.Cf fputwc
function (4.5.3.6.2),
the
.Cf mbrtowc
function (4.5.6.3.2),
the
.Cf wcrtomb
function (4.5.6.3.3).