orientation(5)                                               orientation(5)




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

 EXAMPLES    [Toc]    [Back]
      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 */



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 orientation(5)                                               orientation(5)




               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),
      ungetwc(3C).


 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003