original/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  2014-08-19 "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 _BSD_SOURCE ||
  45     (_XOPEN_SOURCE\ >=\ 500 ||
  46         _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
  47     !(_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600)
  48 .fi
  49 .TP 4
  50 Before glibc 2.2.2:
  51 none
  52 .PD
  53 .RE
  54 .ad b
  55 .SH DESCRIPTION
  56 This function is obsolete.
  57 Do not use it.
  58 If you want to read input without terminal echoing enabled,
  59 see the description of the
  60 .I ECHO
  61 flag in
  62 .BR termios (3).
  63 .PP
  64 The
  65 .BR getpass ()
  66 function opens
  67 .I /dev/tty
  68 (the controlling terminal of the process), outputs the string
  69 .IR prompt ,
  70 turns off echoing, reads one line (the "password"),
  71 restores the terminal state and closes
  72 .I /dev/tty
  73 again.
  74 .SH RETURN VALUE
  75 The function
  76 .BR getpass ()
  77 returns a pointer to a static buffer containing (the first
  78 .B PASS_MAX
  79 bytes of) the password without the trailing
  80 newline, terminated by a null byte (\(aq\\0\(aq).
  81 This buffer may be overwritten by a following call.
  82 On error, the terminal state is restored,
  83 .I errno
  84 is set appropriately, and NULL is returned.
  85 .SH ERRORS
  86 The function may fail if
  87 .TP
  88 .B ENXIO
  89 The process does not have a controlling terminal.
  90 .SH FILES
  91 .I /dev/tty
  92 .\" .SH HISTORY
  93 .\" A
  94 .\" .BR getpass ()
  95 .\" function appeared in Version 7 AT&T UNIX.
  96 .SH ATTRIBUTES
  97 .SS Multithreading (see pthreads(7))
  98 The
  99 .BR getpass ()
 100 function is not thread-safe.
 101 .SH CONFORMING TO
 102 Present in SUSv2, but marked LEGACY.
 103 Removed in POSIX.1-2001.
 104 .SH NOTES
 105 .\" For libc4 and libc5, the prompt is not written to
 106 .\" .I /dev/tty
 107 .\" but to
 108 .\" .IR stderr .
 109 .\" Moreover, if
 110 .\" .I /dev/tty
 111 .\" cannot be opened, the password is read from
 112 .\" .IR stdin .
 113 .\" The static buffer has length 128 so that only the first 127
 114 .\" bytes of the password are returned.
 115 .\" While reading the password, signal generation
 116 .\" .RB ( SIGINT ,
 117 .\" .BR SIGQUIT ,
 118 .\" .BR SIGSTOP ,
 119 .\" .BR SIGTSTP )
 120 .\" is disabled and the corresponding characters
 121 .\" (usually control-C, control-\e, control-Z and control-Y)
 122 .\" are transmitted as part of the password.
 123 .\" Since libc 5.4.19 also line editing is disabled, so that also
 124 .\" backspace and the like will be seen as part of the password.
 125 .PP
 126 In the GNU C library implementation, if
 127 .I /dev/tty
 128 cannot be opened, the prompt is written to
 129 .I stderr
 130 and the password is read from
 131 .IR stdin .
 132 There is no limit on the length of the password.
 133 Line editing is not disabled.
 134 .PP
 135 According to SUSv2, the value of
 136 .B PASS_MAX
 137 must be defined in
 138 .I <limits.h>
 139 in case it is smaller than 8, and can in any case be obtained using
 140 .IR sysconf(_SC_PASS_MAX) .
 141 However, POSIX.2 withdraws the constants
 142 .B PASS_MAX
 143 and
 144 .BR _SC_PASS_MAX ,
 145 and the function
 146 .BR getpass ().
 147 .\" Libc4 and libc5 have never supported
 148 .\" .B PASS_MAX
 149 .\" or
 150 .\" .BR _SC_PASS_MAX .
 151 The glibc version accepts
 152 .B _SC_PASS_MAX
 153 and returns
 154 .B BUFSIZ
 155 (e.g., 8192).
 156 .SH BUGS
 157 The calling process should zero the password as soon as possible to avoid
 158 leaving the cleartext password visible in the process's address space.
 159 .SH SEE ALSO
 160 .BR crypt (3)
 161 .SH COLOPHON
 162 This page is part of release 3.79 of the Linux
 163 .I man-pages
 164 project.
 165 A description of the project,
 166 information about reporting bugs,
 167 and the latest version of this page,
 168 can be found at
 169 \%http://www.kernel.org/doc/man\-pages/.