__fbufsize(3C)

NAME

     __fbufsize,  __flbf,  __fpending,   __fpurge,   __freadable,
     __freading,    __fsetlocking,    __fwritable,    __fwriting,
     _flushlbf - interfaces to stdio FILE structure

SYNOPSIS

     #include <stdio.h>
     #include <stdio_ext.h>

     size_t __fbufsize(FILE *stream);

     int __flbf(FILE *stream);

     size_t __fpending(FILE *stream);

     void __fpurge(FILE *stream);

     int __freadable(FILE *stream);

     int __freading(FILE *stream);

     int __fsetlocking(FILE *stream, int type);

     int __fwritable(FILE *stream);

     int __fwriting(FILE *stream);

     void _flushlbf(void);

DESCRIPTION

     These functions provide portable access to  the  members  of
     the stdio(3C) FILE structure.

     The __fbufsize() function returns in bytes the size  of  the
     buffer currently in use by the given stream.

     The __flbf() function returns  non-zero  if  the  stream  is
     line-buffered.

     The __fpending function returns in bytes the amount of  out-
     put pending on a stream.

     The __fpurge() function discards any pending buffered I/O on
     the stream.

     The __freadable() function returns non-zero if it is  possi-
     ble to read from a stream.

     The __freading() function returns non-zero if  the  file  is
     open  readonly, or if the last operation on the stream was a
     read operation such as fread(3C) or fgetc(3C). Otherwise  it
     returns 0.
     The __fsetlocking() function allows the type of locking per-
     formed  by  stdio  on a given stream to be controlled by the
     programmer.

     If type is  FSETLOCKING_INTERNAL,  stdio  performs  implicit
     locking around every operation on the given stream.  This is
     the default system behavior on that stream.

     If type is  FSETLOCKING_BYCALLER,  stdio  assumes  that  the
     caller  is  responsible for maintaining the integrity of the
     stream in the face of access by multiple threads.  If  there
     is  only  one  thread  accessing the stream, nothing further
     needs to be done.  If multiple  threads  are  accessing  the
     stream,  then  the  caller can use the flockfile(), funlock-
     file(),  and  ftrylockfile()  functions  described  on   the
     flockfile(3C)  manual  page to provide the appropriate lock-
     ing.  In  both   this   and   the   case   where   type   is
     FSETLOCKING_INTERNAL,  __fsetlocking()  returns the previous
     state of the stream.

     If type is FSETLOCKING_QUERY,  __fsetlocking()  returns  the
     current state of the stream without changing it.

     The __fwritable() function returns non-zero if it is  possi-
     ble to write on a stream.

     The __fwriting() function returns non-zero if  the  file  is
     open  write-only or append-only, or if the last operation on
     the stream was a  write  operation  such  as  fwrite(3C)  or
     fputc(3C). Otherwise it returns 0.

     The _flushlbf() function flushes  all  line-buffered  files.
     It is used when reading from a line-buffered file.

USAGE

     Although the contents  of  the  stdio  FILE  structure  have
     always been private to the stdio implementation, some appli-
     cations have needed to  obtain  information  about  a  stdio
     stream  that  was  not accessible through a supported inter-
     face. These applications have resorted to  accessing  fields
     of  the  FILE  structure  directly,  rendering them possibly
     non-portable  to  new  implementations  of  stdio,  or  more
     likely,  preventing  enhancements  to stdio that would cause
     those applications to break.

     In the 64-bit environment, the  FILE  structure  is  opaque.
     The  functions  described  here  are  provided as a means of
     obtaining the information that up to now has been  retrieved
     directly from the FILE structure.  Because they are based on
     the needs of existing applications (such as mh  and  emacs),
     they may be extended as other programs are ported.  Although
     they may still be non-portable to other  operating  systems,
     they  will  be  compatible  from each Solaris release to the
     next.  Interfaces that are more portable are under  develop-
     ment.

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  MT-Level                   |  __fsetlocking() is  Unsafe;|
   |                             |  all others are MT-Safe     |
   |_____________________________|_____________________________|
   | Interface Stability         | Evolving                    |
   |_____________________________|_____________________________|

SEE ALSO

     fgetc(3C), flockfile(3C), fputc(3C), fread(3C),  fwrite(3C),
     stdio(3C), attributes(5)