getchar_unlocked man page on SuSE

Man page or keyword search:  
man Server   14857 pages
apropos Keyword Search (all sections)
Output format
SuSE logo
[printable version]

GETC_UNLOCKED(3P)	   POSIX Programmer's Manual	     GETC_UNLOCKED(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

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 appro‐
       priate:

	      #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  particu‐
       lar, a sequence such as:

	      flockfile(fileptr);
	      putc_unlocked('1', fileptr);
	      putc_unlocked('\n', fileptr);
	      fprintf(fileptr, "Line 2\n");
	      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 *) struc‐
       tures 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 behav‐
       ior of the function or the circumstances under which it should be used.

       Three additional routines, flockfile(),	ftrylockfile(),	 and  funlock‐
       file()  (which may be macros), are provided to allow the user to delin‐
       eate 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.html .

IEEE/The Open Group		     2003		     GETC_UNLOCKED(3P)
[top]

List of man pages available for SuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net