getc_unlocked man page on Manjaro

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Manjaro 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.

       If getc_unlocked() or putc_unlocked() are implemented  as  macros  they
       may evaluate stream more than once, so the stream argument should never
       be an expression with side-effects.

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(c,*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  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
       Section	2.5,  Standard	I/O  Streams,  flockfile(), getc(), getchar(),
       putc(), putchar()

       The Base Definitions volume of POSIX.1‐2008, <stdio.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),	The  Open  Group  Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal and Electronics Engineers,  Inc  and	 The  Open  Group.   (This  is
       POSIX.1-2008  with  the	2013  Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any  typographical  or  formatting  errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files  to  man page format. To report such errors, see https://www.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

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

List of man pages available for Manjaro

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