original/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, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .TH GETPASS 3  2000-12-05 "Linux" "Linux Programmer's Manual"
  24 .SH NAME
  25 getpass \- get a password
  26 .SH SYNOPSIS
  27 .B #include <unistd.h>
  28 .sp
  29 .BI "char *getpass( const char *" prompt );
  30 .SH DESCRIPTION
  31 This function is obsolete.
  32 Do not use it.
  33 .PP
  34 The
  35 .BR getpass ()
  36 function opens
  37 .I /dev/tty
  38 (the controlling terminal of the process), outputs the string
  39 .IR prompt ,
  40 turns off echoing, reads one line (the "password"),
  41 restores the terminal state and closes
  42 .I /dev/tty
  43 again.
  44 .SH "RETURN VALUE"
  45 The function
  46 .BR getpass ()
  47 returns a pointer to a static buffer containing (the first
  48 .B PASS_MAX
  49 bytes of) the password without the trailing
  50 newline, terminated by a null byte (\(aq\\0\(aq).
  51 This buffer may be overwritten by a following call.
  52 On error, the terminal state is restored,
  53 .I errno
  54 is set appropriately, and NULL is returned.
  55 .SH ERRORS
  56 The function may fail if
  57 .TP
  58 .B ENXIO
  59 The process does not have a controlling terminal.
  60 .SH FILES
  61 .I /dev/tty
  62 .\" .SH HISTORY
  63 .\" A
  64 .\" .BR getpass ()
  65 .\" function appeared in Version 7 AT&T UNIX.
  66 .SH "CONFORMING TO"
  67 Present in SUSv2, but marked LEGACY.
  68 Removed in POSIX.1-2001.
  69 .SH NOTES
  70 For libc4 and libc5, the prompt is not written to
  71 .I /dev/tty
  72 but to
  73 .IR stderr .
  74 Moreover, if
  75 .I /dev/tty
  76 cannot be opened, the password is read from
  77 .IR stdin .
  78 The static buffer has length 128 so that only the first 127
  79 bytes of the password are returned.
  80 While reading the password, signal generation
  81 .RB ( SIGINT ,
  82 .BR SIGQUIT ,
  83 .BR SIGSTOP ,
  84 .BR SIGTSTOP )
  85 is disabled and the corresponding characters
  86 (usually control-C, control-\e, control-Z and control-Y)
  87 are transmitted as part of the password.
  88 Since libc 5.4.19 also line editing is disabled, so that also
  89 backspace and the like will be seen as part of the password.
  90 .PP
  91 For glibc2, if
  92 .I /dev/tty
  93 cannot be opened, the prompt is written to
  94 .I stderr
  95 and the password is read from
  96 .IR stdin .
  97 There is no limit on the length of the password.
  98 Line editing is not disabled.
  99 .PP
 100 According to the SUSv2, the value of
 101 .B PASS_MAX
 102 must be defined in
 103 .I <limits.h>
 104 in case it is smaller than 8, and can in any case be obtained using
 105 .IR sysconf(_SC_PASS_MAX) .
 106 However, POSIX.2 withdraws the constants
 107 .B PASS_MAX
 108 and
 109 .BR _SC_PASS_MAX ,
 110 and the function
 111 .BR getpass ().
 112 Libc4 and libc5 have never supported
 113 .B PASS_MAX
 114 or
 115 .BR _SC_PASS_MAX .
 116 Glibc2 accepts
 117 .B _SC_PASS_MAX
 118 and returns
 119 .B BUFSIZ
 120 (e.g., 8192).
 121 .SH BUGS
 122 The calling process should zero the password as soon as possible to avoid
 123 leaving the cleartext password visible in the process's address space.
 124 .SH "SEE ALSO"
 125 .BR crypt (3)