HP-UX Reference (11i v2 07/12) - 5 Miscellaneous (vol 9)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

281

282

283

284

285

286

287

288

289

290

orientation(5) orientation(5)

NAME

orientation - the orientation of a stream

DESCRIPTION

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 ﬁles, and that all the wide-character input/output func-

tions begin executing with the stream positioned at the boundary between two multi-byte characters.

After a stream is associated with a ﬁle, 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 orienta-

tion, 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 ﬁxed 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(), vfprintf() , vprintf().

EXAMPLES

To read characters from a stream when the orientation of the stream is unknown :

int so;

wchar_t ws[CHAR_NUM];

char s[CHAR_NUM];

so = fwide(stream, 0); /* Check the orientation */

if (so > 0) /* the stream is wide-oriented */

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

If byte input/output functions are applied to a wide-oriented stream or wide-character input/output func-

tions are applied to a byte-oriented stream, the behavior is undeﬁned.

AUTHOR

The functionality of the orientation of a stream was developed by HP and Mitsubishi Electric Corporation.