man3/getpass.3

   1 .\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, see
  20 .\" <http://www.gnu.org/licenses/>.
  21 .\"
  22 .TH GETPASS 3  2010-09-20 "Linux" "Linux Programmer's Manual"
  23 .SH NAME
  24 getpass \- get a password
  25 .SH SYNOPSIS
  26 .B #include <unistd.h>
  27 .sp
  28 .BI "char *getpass( const char *" prompt );
  29 .sp
  30 .in -4n
  31 Feature Test Macro Requirements for glibc (see
  32 .BR feature_test_macros (7)):
  33 .in
  34 .sp
  35 .BR getpass ():
  36 .ad l
  37 .RS 4
  38 .PD 0
  39 .TP 4
  40 Since glibc 2.2.2:
  41 .nf
  42 _BSD_SOURCE ||
  43     (_XOPEN_SOURCE\ >=\ 500 ||
  44         _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
  45     !(_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600)
  46 .TP 4
  47 .fi
  48 Before glibc 2.2.2: none
  49 .PD
  50 .RE
  51 .ad b
  52 .SH DESCRIPTION
  53 This function is obsolete.
  54 Do not use it.
  55 .PP
  56 The
  57 .BR getpass ()
  58 function opens
  59 .I /dev/tty
  60 (the controlling terminal of the process), outputs the string
  61 .IR prompt ,
  62 turns off echoing, reads one line (the "password"),
  63 restores the terminal state and closes
  64 .I /dev/tty
  65 again.
  66 .SH RETURN VALUE
  67 The function
  68 .BR getpass ()
  69 returns a pointer to a static buffer containing (the first
  70 .B PASS_MAX
  71 bytes of) the password without the trailing
  72 newline, terminated by a null byte (\(aq\\0\(aq).
  73 This buffer may be overwritten by a following call.
  74 On error, the terminal state is restored,
  75 .I errno
  76 is set appropriately, and NULL is returned.
  77 .SH ERRORS
  78 The function may fail if
  79 .TP
  80 .B ENXIO
  81 The process does not have a controlling terminal.
  82 .SH FILES
  83 .I /dev/tty
  84 .\" .SH HISTORY
  85 .\" A
  86 .\" .BR getpass ()
  87 .\" function appeared in Version 7 AT&T UNIX.
  88 .SH CONFORMING TO
  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 .PP
 113 For glibc2, if
 114 .I /dev/tty
 115 cannot be opened, the prompt is written to
 116 .I stderr
 117 and the password is read from
 118 .IR stdin .
 119 There is no limit on the length of the password.
 120 Line editing is not disabled.
 121 .PP
 122 According to the SUSv2, the value of
 123 .B PASS_MAX
 124 must be defined in
 125 .I <limits.h>
 126 in case it is smaller than 8, and can in any case be obtained using
 127 .IR sysconf(_SC_PASS_MAX) .
 128 However, POSIX.2 withdraws the constants
 129 .B PASS_MAX
 130 and
 131 .BR _SC_PASS_MAX ,
 132 and the function
 133 .BR getpass ().
 134 Libc4 and libc5 have never supported
 135 .B PASS_MAX
 136 or
 137 .BR _SC_PASS_MAX .
 138 Glibc2 accepts
 139 .B _SC_PASS_MAX
 140 and returns
 141 .B BUFSIZ
 142 (e.g., 8192).
 143 .SH BUGS
 144 The calling process should zero the password as soon as possible to avoid
 145 leaving the cleartext password visible in the process's address space.
 146 .SH SEE ALSO
 147 .BR crypt (3)