1 files changed, 235 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3p/getc_unlocked.3p b/upstream/mageia-cauldron/man3p/getc_unlocked.3p
new file mode 100644
index 00000000..271506ce
--- /dev/null
+++ b/upstream/mageia-cauldron/man3p/getc_unlocked.3p
@@ -0,0 +1,235 @@
+'\" et
+.TH GETC_UNLOCKED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH 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.
+.\"
+.SH NAME
+getc_unlocked,
+getchar_unlocked,
+putc_unlocked,
+putchar_unlocked
+\(em stdio with explicit client locking
+.SH SYNOPSIS
+.LP
+.nf
+#include <stdio.h>
+.P
+int getc_unlocked(FILE *\fIstream\fP);
+int getchar_unlocked(void);
+int putc_unlocked(int \fIc\fP, FILE *\fIstream\fP);
+int putchar_unlocked(int \fIc\fP);
+.fi
+.SH DESCRIPTION
+Versions of the functions
+\fIgetc\fR(),
+\fIgetchar\fR(),
+\fIputc\fR(),
+and
+\fIputchar\fR()
+respectively named
+\fIgetc_unlocked\fR(),
+\fIgetchar_unlocked\fR(),
+\fIputc_unlocked\fR(),
+and
+\fIputchar_unlocked\fR()
+shall be provided which are functionally equivalent to the original
+versions, with the exception that they are not required to be
+implemented in a fully thread-safe manner. They shall be thread-safe
+when used within a scope protected by
+\fIflockfile\fR()
+(or
+\fIftrylockfile\fR())
+and
+\fIfunlockfile\fR().
+These functions can safely be used in a multi-threaded program if and
+only if they are called while the invoking thread owns the (\c
+.BR "FILE *" )
+object, as is the case after a successful call to the
+\fIflockfile\fR()
+or
+\fIftrylockfile\fR()
+functions.
+.P
+If
+\fIgetc_unlocked\fR()
+or
+\fIputc_unlocked\fR()
+are implemented as macros they may evaluate
+.IR stream
+more than once, so the
+.IR stream
+argument should never be an expression with side-effects.
+.SH "RETURN VALUE"
+See
+.IR "\fIgetc\fR\^(\|)",
+.IR "\fIgetchar\fR\^(\|)",
+.IR "\fIputc\fR\^(\|)",
+and
+.IR "\fIputchar\fR\^(\|)".
+.SH ERRORS
+See
+.IR "\fIgetc\fR\^(\|)",
+.IR "\fIgetchar\fR\^(\|)",
+.IR "\fIputc\fR\^(\|)",
+and
+.IR "\fIputchar\fR\^(\|)".
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+Since they may be implemented as macros,
+\fIgetc_unlocked\fR()
+and
+\fIputc_unlocked\fR()
+may treat incorrectly a
+.IR stream
+argument with side-effects. In particular, \fIgetc_unlocked\fP(*f++)
+and \fIputc_unlocked\fP(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:
+.sp
+.RS 4
+.nf
+
+#undef getc_unlocked
+#undef putc_unlocked
+.fi
+.P
+.RE
+.SH RATIONALE
+Some I/O functions are typically implemented as macros for performance
+reasons (for example,
+\fIputc\fR()
+and
+\fIgetc\fR()).
+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
+\fIgetc\fR(),
+\fIgetchar\fR(),
+\fIputc\fR(),
+and
+\fIputchar\fR()
+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:
+.sp
+.RS 4
+.nf
+
+flockfile(fileptr);
+putc_unlocked(\(aq1\(aq, fileptr);
+putc_unlocked(\(aq\en\(aq, fileptr);
+fprintf(fileptr, "Line 2\en");
+funlockfile(fileptr);
+.fi
+.P
+.RE
+.br
+.P
+is permissible, and results in the text sequence:
+.sp
+.RS 4
+.nf
+
+1
+Line 2
+.fi
+.P
+.RE
+.P
+being printed without being interspersed with output from other
+threads.
+.P
+It would be wrong to have the standard names such as
+\fIgetc\fR(),
+\fIputc\fR(),
+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
+\fIgetc\fR(),
+\fIputc\fR(),
+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
+.IR stdio
+(\c
+.BR "FILE *" )
+structures or buffers are also safely synchronized.
+.P
+Note that there is no need for functions of the form
+\fIgetc_locked\fR(),
+\fIputc_locked\fR(),
+and so on, since this is the functionality of
+\fIgetc\fR(),
+\fIputc\fR(),
+.IR "et al" .
+It would be inappropriate to use a feature test macro to
+switch a macro definition of
+\fIgetc\fR()
+between
+\fIgetc_locked\fR()
+and
+\fIgetc_unlocked\fR(),
+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
+\fIxxx_locked\fR()
+and
+\fIxxx_unlocked\fR()
+forms leads to the confusion of whether the suffix describes the
+behavior of the function or the circumstances under which it should be
+used.
+.P
+Three additional routines,
+\fIflockfile\fR(),
+\fIftrylockfile\fR(),
+and
+\fIfunlockfile\fR()
+(which may be macros), are provided to allow the user to delineate a
+sequence of I/O statements that are executed synchronously.
+.P
+The
+\fIungetc\fR()
+function is infrequently called relative to the other functions/macros
+so no unlocked variation is needed.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "Section 2.5" ", " "Standard I/O Streams",
+.IR "\fIflockfile\fR\^(\|)",
+.IR "\fIgetc\fR\^(\|)",
+.IR "\fIgetchar\fR\^(\|)",
+.IR "\fIputc\fR\^(\|)",
+.IR "\fIputchar\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<stdio.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 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 .
+.PP
+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.kernel.org/doc/man-pages/reporting_bugs.html .