man3/getpass.3

   1 '\" t
   2 .\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH getpass 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 getpass \- get a password
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <unistd.h>
  15 .PP
  16 .BI "[[deprecated]] char *getpass(const char *" prompt );
  17 .fi
  18 .PP
  19 .RS -4
  20 Feature Test Macro Requirements for glibc (see
  21 .BR feature_test_macros (7)):
  22 .RE
  23 .PP
  24 .BR getpass ():
  25 .nf
  26     Since glibc 2.2.2:
  27         _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
  28             || /* glibc >= 2.19: */ _DEFAULT_SOURCE
  29             || /* glibc <= 2.19: */ _BSD_SOURCE
  30     Before glibc 2.2.2:
  31         none
  32 .fi
  33 .SH DESCRIPTION
  34 This function is obsolete.
  35 Do not use it.
  36 See NOTES.
  37 If you want to read input without terminal echoing enabled,
  38 see the description of the
  39 .I ECHO
  40 flag in
  41 .BR termios (3).
  42 .PP
  43 The
  44 .BR getpass ()
  45 function opens
  46 .I /dev/tty
  47 (the controlling terminal of the process), outputs the string
  48 .IR prompt ,
  49 turns off echoing, reads one line (the "password"),
  50 restores the terminal state and closes
  51 .I /dev/tty
  52 again.
  53 .SH RETURN VALUE
  54 The function
  55 .BR getpass ()
  56 returns a pointer to a static buffer containing (the first
  57 .B PASS_MAX
  58 bytes of) the password without the trailing
  59 newline, terminated by a null byte (\[aq]\e0\[aq]).
  60 This buffer may be overwritten by a following call.
  61 On error, the terminal state is restored,
  62 .I errno
  63 is set to indicate the error, and NULL is returned.
  64 .SH ERRORS
  65 .TP
  66 .B ENXIO
  67 The process does not have a controlling terminal.
  68 .SH FILES
  69 .I /dev/tty
  70 .SH ATTRIBUTES
  71 For an explanation of the terms used in this section, see
  72 .BR attributes (7).
  73 .TS
  74 allbox;
  75 lbx lb lb
  76 l l l.
  77 Interface       Attribute       Value
  78 T{
  79 .na
  80 .nh
  81 .BR getpass ()
  82 T}      Thread safety   MT-Unsafe term
  83 .TE
  84 .sp 1
  85 .SH STANDARDS
  86 None.
  87 .SH HISTORY
  88 Version 7 AT&T UNIX.
  89 Present in SUSv2, but marked LEGACY.
  90 Removed in POSIX.1-2001.
  91 .SH NOTES
  92 .\" For libc4 and libc5, the prompt is not written to
  93 .\" .I /dev/tty
  94 .\" but to
  95 .\" .IR stderr .
  96 .\" Moreover, if
  97 .\" .I /dev/tty
  98 .\" cannot be opened, the password is read from
  99 .\" .IR stdin .
 100 .\" The static buffer has length 128 so that only the first 127
 101 .\" bytes of the password are returned.
 102 .\" While reading the password, signal generation
 103 .\" .RB ( SIGINT ,
 104 .\" .BR SIGQUIT ,
 105 .\" .BR SIGSTOP ,
 106 .\" .BR SIGTSTP )
 107 .\" is disabled and the corresponding characters
 108 .\" (usually control-C, control-\e, control-Z and control-Y)
 109 .\" are transmitted as part of the password.
 110 .\" Since libc 5.4.19 also line editing is disabled, so that also
 111 .\" backspace and the like will be seen as part of the password.
 112 You should use instead
 113 .BR readpassphrase (3bsd),
 114 provided by
 115 .IR libbsd .
 116 .PP
 117 In the GNU C library implementation, if
 118 .I /dev/tty
 119 cannot be opened, the prompt is written to
 120 .I stderr
 121 and the password is read from
 122 .IR stdin .
 123 There is no limit on the length of the password.
 124 Line editing is not disabled.
 125 .PP
 126 According to SUSv2, the value of
 127 .B PASS_MAX
 128 must be defined in
 129 .I <limits.h>
 130 in case it is smaller than 8, and can in any case be obtained using
 131 .IR sysconf(_SC_PASS_MAX) .
 132 However, POSIX.2 withdraws the constants
 133 .B PASS_MAX
 134 and
 135 .BR _SC_PASS_MAX ,
 136 and the function
 137 .BR getpass ().
 138 .\" Libc4 and libc5 have never supported
 139 .\" .B PASS_MAX
 140 .\" or
 141 .\" .BR _SC_PASS_MAX .
 142 The glibc version accepts
 143 .B _SC_PASS_MAX
 144 and returns
 145 .B BUFSIZ
 146 (e.g., 8192).
 147 .SH BUGS
 148 The calling process should zero the password as soon as possible to avoid
 149 leaving the cleartext password visible in the process's address space.
 150 .SH SEE ALSO
 151 .BR crypt (3)