man3/getpass.3

   1 .\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .TH GETPASS 3  2016-03-15 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 getpass \- get a password
  27 .SH SYNOPSIS
  28 .B #include <unistd.h>
  29 .sp
  30 .BI "char *getpass(const char *" prompt );
  31 .sp
  32 .in -4n
  33 Feature Test Macro Requirements for glibc (see
  34 .BR feature_test_macros (7)):
  35 .in
  36 .sp
  37 .BR getpass ():
  38 .ad l
  39 .RS 4
  40 .PD 0
  41 .TP 4
  42 Since glibc 2.2.2:
  43 .nf
  44 _XOPEN_SOURCE && ! (_POSIX_C_SOURCE\ >=\ 200112L)
  45     || /* Glibc since 2.19: */ _DEFAULT_SOURCE
  46     || /* Glibc versions <= 2.19: */ _BSD_SOURCE
  47 .fi
  48 .TP 4
  49 Before glibc 2.2.2:
  50 none
  51 .PD
  52 .RE
  53 .ad b
  54 .SH DESCRIPTION
  55 This function is obsolete.
  56 Do not use it.
  57 If you want to read input without terminal echoing enabled,
  58 see the description of the
  59 .I ECHO
  60 flag in
  61 .BR termios (3).
  62 .PP
  63 The
  64 .BR getpass ()
  65 function opens
  66 .I /dev/tty
  67 (the controlling terminal of the process), outputs the string
  68 .IR prompt ,
  69 turns off echoing, reads one line (the "password"),
  70 restores the terminal state and closes
  71 .I /dev/tty
  72 again.
  73 .SH RETURN VALUE
  74 The function
  75 .BR getpass ()
  76 returns a pointer to a static buffer containing (the first
  77 .B PASS_MAX
  78 bytes of) the password without the trailing
  79 newline, terminated by a null byte (\(aq\\0\(aq).
  80 This buffer may be overwritten by a following call.
  81 On error, the terminal state is restored,
  82 .I errno
  83 is set appropriately, and NULL is returned.
  84 .SH ERRORS
  85 The function may fail if
  86 .TP
  87 .B ENXIO
  88 The process does not have a controlling terminal.
  89 .SH FILES
  90 .I /dev/tty
  91 .\" .SH HISTORY
  92 .\" A
  93 .\" .BR getpass ()
  94 .\" function appeared in Version 7 AT&T UNIX.
  95 .SH ATTRIBUTES
  96 For an explanation of the terms used in this section, see
  97 .BR attributes (7).
  98 .TS
  99 allbox;
 100 lb lb lb
 101 l l l.
 102 Interface       Attribute       Value
 103 T{
 104 .BR getpass ()
 105 T}      Thread safety   MT-Unsafe term
 106 .TE
 107 .SH CONFORMING TO
 108 Present in SUSv2, but marked LEGACY.
 109 Removed in POSIX.1-2001.
 110 .SH NOTES
 111 .\" For libc4 and libc5, the prompt is not written to
 112 .\" .I /dev/tty
 113 .\" but to
 114 .\" .IR stderr .
 115 .\" Moreover, if
 116 .\" .I /dev/tty
 117 .\" cannot be opened, the password is read from
 118 .\" .IR stdin .
 119 .\" The static buffer has length 128 so that only the first 127
 120 .\" bytes of the password are returned.
 121 .\" While reading the password, signal generation
 122 .\" .RB ( SIGINT ,
 123 .\" .BR SIGQUIT ,
 124 .\" .BR SIGSTOP ,
 125 .\" .BR SIGTSTP )
 126 .\" is disabled and the corresponding characters
 127 .\" (usually control-C, control-\e, control-Z and control-Y)
 128 .\" are transmitted as part of the password.
 129 .\" Since libc 5.4.19 also line editing is disabled, so that also
 130 .\" backspace and the like will be seen as part of the password.
 131 .PP
 132 In the GNU C library implementation, if
 133 .I /dev/tty
 134 cannot be opened, the prompt is written to
 135 .I stderr
 136 and the password is read from
 137 .IR stdin .
 138 There is no limit on the length of the password.
 139 Line editing is not disabled.
 140 .PP
 141 According to SUSv2, the value of
 142 .B PASS_MAX
 143 must be defined in
 144 .I <limits.h>
 145 in case it is smaller than 8, and can in any case be obtained using
 146 .IR sysconf(_SC_PASS_MAX) .
 147 However, POSIX.2 withdraws the constants
 148 .B PASS_MAX
 149 and
 150 .BR _SC_PASS_MAX ,
 151 and the function
 152 .BR getpass ().
 153 .\" Libc4 and libc5 have never supported
 154 .\" .B PASS_MAX
 155 .\" or
 156 .\" .BR _SC_PASS_MAX .
 157 The glibc version accepts
 158 .B _SC_PASS_MAX
 159 and returns
 160 .B BUFSIZ
 161 (e.g., 8192).
 162 .SH BUGS
 163 The calling process should zero the password as soon as possible to avoid
 164 leaving the cleartext password visible in the process's address space.
 165 .SH SEE ALSO
 166 .BR crypt (3)