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 .P
  16 .BI "[[deprecated]] char *getpass(const char *" prompt );
  17 .fi
  18 .P
  19 .RS -4
  20 Feature Test Macro Requirements for glibc (see
  21 .BR feature_test_macros (7)):
  22 .RE
  23 .P
  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 .P
  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 .SH STANDARDS
  85 None.
  86 .SH HISTORY
  87 Version 7 AT&T UNIX.
  88 Present in SUSv2, but marked LEGACY.
  89 Removed in POSIX.1-2001.
  90 .SH NOTES
  91 .\" For libc4 and libc5, the prompt is not written to
  92 .\" .I /dev/tty
  93 .\" but to
  94 .\" .IR stderr .
  95 .\" Moreover, if
  96 .\" .I /dev/tty
  97 .\" cannot be opened, the password is read from
  98 .\" .IR stdin .
  99 .\" The static buffer has length 128 so that only the first 127
 100 .\" bytes of the password are returned.
 101 .\" While reading the password, signal generation
 102 .\" .RB ( SIGINT ,
 103 .\" .BR SIGQUIT ,
 104 .\" .BR SIGSTOP ,
 105 .\" .BR SIGTSTP )
 106 .\" is disabled and the corresponding characters
 107 .\" (usually control-C, control-\e, control-Z and control-Y)
 108 .\" are transmitted as part of the password.
 109 .\" Since libc 5.4.19 also line editing is disabled, so that also
 110 .\" backspace and the like will be seen as part of the password.
 111 You should use instead
 112 .BR readpassphrase (3bsd),
 113 provided by
 114 .IR libbsd .
 115 .P
 116 In the GNU C library implementation, if
 117 .I /dev/tty
 118 cannot be opened, the prompt is written to
 119 .I stderr
 120 and the password is read from
 121 .IR stdin .
 122 There is no limit on the length of the password.
 123 Line editing is not disabled.
 124 .P
 125 According to SUSv2, the value of
 126 .B PASS_MAX
 127 must be defined in
 128 .I <limits.h>
 129 in case it is smaller than 8, and can in any case be obtained using
 130 .IR sysconf(_SC_PASS_MAX) .
 131 However, POSIX.2 withdraws the constants
 132 .B PASS_MAX
 133 and
 134 .BR _SC_PASS_MAX ,
 135 and the function
 136 .BR getpass ().
 137 .\" Libc4 and libc5 have never supported
 138 .\" .B PASS_MAX
 139 .\" or
 140 .\" .BR _SC_PASS_MAX .
 141 The glibc version accepts
 142 .B _SC_PASS_MAX
 143 and returns
 144 .B BUFSIZ
 145 (e.g., 8192).
 146 .SH BUGS
 147 The calling process should zero the password as soon as possible to avoid
 148 leaving the cleartext password visible in the process's address space.
 149 .SH SEE ALSO
 150 .BR crypt (3)