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 correspond-
       ing 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  ftrylock-
       file())	and funlockfile().  These functions may safely be used in a multi-threaded program if and only if they are called while the invok-
       ing 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 sit-
       uations 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  exist-
       ing  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 fea-
       ture 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 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 Technol-
       ogy -- 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)