Originální popis anglicky:
getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked - stdio with
explicit client locking
Návod, kniha: POSIX Programmer's Manual
#include <stdio.h>
int getc_unlocked(FILE *
stream);
int getchar_unlocked(void);
int putc_unlocked(int
c, FILE
*stream);
int putchar_unlocked(int
c);
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.
See
getc() ,
getchar() ,
putc() , and
putchar() .
See
getc() ,
getchar() ,
putc() , and
putchar() .
The following sections are informative.
None.
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
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('\n', fileptr);
fprintf(fileptr, "Line 2\n");
funlockfile(fileptr);
is permissible, and results in the text sequence:
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.
None.
getc() ,
getchar() ,
putc() ,
putchar() , the Base
Definitions volume of IEEE Std 1003.1-2001,
<stdio.h>
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
.
