NAME [Toc] [Back]
orientation - the orientation of a stream
DESCRIPTION [Toc] [Back]
The orientation of a stream is a property of a FILE object that is
handled as a input/output stream. It is useful when the input/output
model assumes that characters are handled as wide-characters within an
application and stored as multi-byte characters in files, and that all
the wide-character input/output functions begin executing with the
stream positioned at the boundary between two multi-byte characters.
After a stream is associated with a file, but before any operations
are performed on the stream, the stream is without orientation. If a
wide-character input or output function is applied to a stream without
orientation, the stream becomes wide-oriented implicitly. Likewise,
if a byte input or output operation is applied to a stream without
orientation, the stream becomes byte-oriented implicitly. Only the
fwide() function can alter the orientation of a stream explicitly when
the stream is without orientation.
Just after a stream is associated with a pipe by the popen() function,
the stream is byte-oriented.
After the stream becomes byte-oriented or wide-oriented, the
orientation of a stream will be fixed and can not be changed until the
stream is closed.
The following functions are wide-character input/output functions.
fgetwc(), fgetws(), fputwc(), fputws(), fwprintf(), fwscanf(),
getwc(), getwchar(), putwc(), putwchar(), putws(), ungetwc(),
vfwprintf(), wprintf(), wscanf().
The following functions are byte input/output functions.
fgetc(), fgets(), fprintf(), fputc(), fputs(), fread(), fscanf(),
fwrite(), getc(), getchar(), getc_unlocked(), getchar_unlocked(),
gets(), getw(), printf(), putc(), putchar(), putc_unlocked(),
putchar_unlocked(), puts(), putw(), scanf(), ungetc(),
EXAMPLES [Toc] [Back]
To read characters from a stream when the orientation of the stream is
so = fwide(stream, 0); /* Check the orientation */
if (so > 0) /* the stream is wide-oriented */
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
fgetws(ws, CHAR_NUM, stream);
else if (so < 0) / * stream is byte-oriented */
fgets(s, CHAR_NUM, stream);
else /* the stream is without orientation */
fprintf(stderr, "It is first time to access this file.");
WARNINGS [Toc] [Back]
If byte input/output functions are applied to a wide-oriented stream
or wide-character input/output functions are applied to a byteoriented
stream, the behavior is undefined.
AUTHOR [Toc] [Back]
The functionality of the orientation of a stream was developed by HP
and Mitsubishi Electric Corporation.
SEE ALSO [Toc] [Back]
fgetws(3C), fopen(3S), fread(3S), fwide(3C), fwprintf(3C),
fwscanf(3C), getc(3S), gets(3S), getwc(3C), popen(3S), printf(3S),
putc(3S), puts(3S), putwc(3C), putws(3C), scanf(3S), ungetc(3S),
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003 [ Back ]