👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for putc_unlocked (linux section 3posix)

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

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 pro-
       vided 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  exam-
       ple,  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:

	      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 intro-
       duce 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				 GETC_UNLOCKED(P)


All times are GMT -4. The time now is 11:40 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password