Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 150 insertions, 0 deletions

diff --git a/man/man3/getpass.3 b/man/man3/getpass.3
new file mode 100644
index 0000000..6986a83
--- /dev/null
+++ b/man/man3/getpass.3
@@ -0,0 +1,150 @@
+'\" t
+.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH getpass 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+getpass \- get a password
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "[[deprecated]] char *getpass(const char *" prompt );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR getpass ():
+.nf
+    Since glibc 2.2.2:
+        _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
+            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
+            || /* glibc <= 2.19: */ _BSD_SOURCE
+    Before glibc 2.2.2:
+        none
+.fi
+.SH DESCRIPTION
+This function is obsolete.
+Do not use it.
+See NOTES.
+If you want to read input without terminal echoing enabled,
+see the description of the
+.I ECHO
+flag in
+.BR termios (3).
+.P
+The
+.BR getpass ()
+function opens
+.I /dev/tty
+(the controlling terminal of the process), outputs the string
+.IR prompt ,
+turns off echoing, reads one line (the "password"),
+restores the terminal state and closes
+.I /dev/tty
+again.
+.SH RETURN VALUE
+The function
+.BR getpass ()
+returns a pointer to a static buffer containing (the first
+.B PASS_MAX
+bytes of) the password without the trailing
+newline, terminated by a null byte (\[aq]\e0\[aq]).
+This buffer may be overwritten by a following call.
+On error, the terminal state is restored,
+.I errno
+is set to indicate the error, and NULL is returned.
+.SH ERRORS
+.TP
+.B ENXIO
+The process does not have a controlling terminal.
+.SH FILES
+.I /dev/tty
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR getpass ()
+T}	Thread safety	MT-Unsafe term
+.TE
+.SH STANDARDS
+None.
+.SH HISTORY
+Version 7 AT&T UNIX.
+Present in SUSv2, but marked LEGACY.
+Removed in POSIX.1-2001.
+.SH NOTES
+.\" For libc4 and libc5, the prompt is not written to
+.\" .I /dev/tty
+.\" but to
+.\" .IR stderr .
+.\" Moreover, if
+.\" .I /dev/tty
+.\" cannot be opened, the password is read from
+.\" .IR stdin .
+.\" The static buffer has length 128 so that only the first 127
+.\" bytes of the password are returned.
+.\" While reading the password, signal generation
+.\" .RB ( SIGINT ,
+.\" .BR SIGQUIT ,
+.\" .BR SIGSTOP ,
+.\" .BR SIGTSTP )
+.\" is disabled and the corresponding characters
+.\" (usually control-C, control-\e, control-Z and control-Y)
+.\" are transmitted as part of the password.
+.\" Since libc 5.4.19 also line editing is disabled, so that also
+.\" backspace and the like will be seen as part of the password.
+You should use instead
+.BR readpassphrase (3bsd),
+provided by
+.IR libbsd .
+.P
+In the GNU C library implementation, if
+.I /dev/tty
+cannot be opened, the prompt is written to
+.I stderr
+and the password is read from
+.IR stdin .
+There is no limit on the length of the password.
+Line editing is not disabled.
+.P
+According to SUSv2, the value of
+.B PASS_MAX
+must be defined in
+.I <limits.h>
+in case it is smaller than 8, and can in any case be obtained using
+.IR sysconf(_SC_PASS_MAX) .
+However, POSIX.2 withdraws the constants
+.B PASS_MAX
+and
+.BR _SC_PASS_MAX ,
+and the function
+.BR getpass ().
+.\" Libc4 and libc5 have never supported
+.\" .B PASS_MAX
+.\" or
+.\" .BR _SC_PASS_MAX .
+The glibc version accepts
+.B _SC_PASS_MAX
+and returns
+.B BUFSIZ
+(e.g., 8192).
+.SH BUGS
+The calling process should zero the password as soon as possible to avoid
+leaving the cleartext password visible in the process's address space.
+.SH SEE ALSO
+.BR crypt (3)