GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


NAME

       getc_unlocked,   getchar_unlocked,  putc_unlocked,  putchar_unlocked  -
       stdio with explicit client locking

SYNOPSIS

       #include <stdio.h>

       int getc_unlocked(FILE *stream);
       int getchar_unlocked(void);
       int putc_unlocked(int c, FILE *stream);
       int putchar_unlocked(int c);

DESCRIPTION

       Versions of the functions  getc(),  getchar(),  putc(),  and  putchar()
       respectively       named      getc_unlocked(),      getchar_unlocked(),
       putc_unlocked(), and putchar_unlocked() shall  be  provided  which  are
       functionally  equivalent  to  the original versions, with the exception
       that they are not required to be implemented in a  thread-safe  manner.
       They  may  only  safely be used within a scope protected by flockfile()
       (or ftrylockfile()) and funlockfile().  These functions may  safely  be
       used  in  a multi-threaded program if and only if they are called while
       the invoking thread owns the ( FILE *) object, as is the case  after  a
       successful call to the flockfile() or ftrylockfile() functions.

RETURN VALUE

       See getc() , getchar() , putc() , and putchar() .

ERRORS

       See getc() , getchar() , putc() , and putchar() .

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       Since   they   may   be  implemented  as  macros,  getc_unlocked()  and
       putc_unlocked() may treat  incorrectly  a  stream  argument  with  side
       effects.  In particular, getc_unlocked(*f++) and putc_unlocked(*f++) do
       not necessarily work as expected. Therefore, use of these functions  in
       such  situations  should  be  preceded  by  the  following statement as
       appropriate:

              #undef getc_unlocked
              #undef putc_unlocked

RATIONALE

       Some I/O functions are typically implemented as macros for  performance
       reasons  (for  example, putc() and getc()). For safety, they need to be
       synchronized, but it is often too expensive  to  synchronize  on  every
       character. Nevertheless, it was felt that the safety concerns were more
       important; consequently, the getc(), getchar(), putc(),  and  putchar()
       functions  are  required to be thread-safe.  However, unlocked versions
       are also provided with names that clearly indicate the unsafe nature of
       their  operation  but  can be used to exploit their higher performance.
       These unlocked versions can  be  safely  used  only  within  explicitly
       locked   program   regions,   using  exported  locking  primitives.  In
       particular, a sequence such as:

              flockfile(fileptr);
              putc_unlocked('1', fileptr);
              putc_unlocked('
', fileptr);
              fprintf(fileptr, "Line 2
");
              funlockfile(fileptr);

       is permissible, and results in the text sequence:

              1
              Line 2

       being  printed  without  being  interspersed  with  output  from  other
       threads.

       It  would  be  wrong to have the standard names such as getc(), putc(),
       and so on, map to the "faster, but unsafe" rather than the "slower, but
       safe''  versions.  In  either case, you would still want to inspect all
       uses of getc(), putc(), and so on, by  hand  when  converting  existing
       code.  Choosing  the safe bindings as the default, at least, results in
       correct code and maintains the "atomicity at the  function"  invariant.
       To  do otherwise would introduce gratuitous synchronization errors into
       converted code.  Other  routines  that  modify  the  stdio  (  FILE  *)
       structures or buffers are also safely synchronized.

       Note  that  there  is  no need for functions of the form getc_locked(),
       putc_locked(), and so on, since this is the  functionality  of  getc(),
       putc(), et al. It would be inappropriate to use a feature test macro to
       switch  a  macro  definition  of  getc()  between   getc_locked()   and
       getc_unlocked(),  since  the ISO C standard requires an actual function
       to exist, a function whose behavior could not be changed by the feature
       test  macro.  Also,  providing both the xxx_locked() and xxx_unlocked()
       forms leads to the  confusion  of  whether  the  suffix  describes  the
       behavior  of the function or the circumstances under which it should be
       used.

       Three   additional   routines,   flockfile(),    ftrylockfile(),    and
       funlockfile()  (which may be macros), are provided to allow the user to
       delineate a sequence of I/O statements that are executed synchronously.

       The ungetc() function is infrequently  called  relative  to  the  other
       functions/macros so no unlocked variation is needed.

FUTURE DIRECTIONS

       None.

SEE ALSO

       getc()  ,  getchar() , putc() , putchar() , the Base Definitions volume
       of IEEE Std 1003.1-2001, <stdio.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.php .



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.116 seconds. Last modified: November 04 2018 12:49:43.