-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathwith-readline.1
141 lines (141 loc) · 4.33 KB
/
with-readline.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
.\" This file is part of with-readline.
.\" Copyright (C) 2005 Richard Kettlewell
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
.\" USA
.TH with-readline 1
.SH NAME
with-readline \- readline front-end for arbitrary programs
.SH SYNOPSIS
.B with-readline
.RI [OPTIONS]
.I COMMAND
.IR ARGS ...
.SH DESCRIPTION
.B with-readline
executes
.I COMMAND
with Readline applied to its standard input. This allows Readline's
editing features to be applied even to programs not linked against it.
.PP
For example, one might make
.BR sftp (1)
use Readline by aliasing it with the following Bash command:
.PP
.nf
alias sftp="with-readline sftp"
.fi
.SH OPTIONS
The following options are supported:
.TP
.B --application \fIAPP\fR, \fB-a \fIAPP\fR
Set the application name to
.IR APP .
This can be used in
.IR ~/.inputrc .
See the section
.I "Conditional Init Constructs"
in the GNU Readline manual for more details.
.IP
The default application name is the basename of the command. For
instance if the command is either "sftp" or "/usr/bin/sftp" then the
application name will be "sftp".
.TP
.B --history \fIENTRIES\fR, \fB-H \fIENTRIES\fR
Set the maximum number of history entries to record. \fIENTRIES\fR
must be a non-negative decimal integer.
.IP
If this option is not used then the environment variable
\fBHISTFILESIZE\fR is consulted instead.
.IP
If that is not set then the default size is 500 entries.
.TP
.B --help\fR, \fB-h
Display a usage message.
.TP
.B --version\fR, \fB-V
Display the version string.
.SH PROMPTS
.B with-readline
has to deduce the application's prompt, if it has one, by monitoring
the application's output. The way it does this is to record the
latest incomplete line (which might be a blank line) when the first
keypress of each line is detected, and assume that that is the
prompt. When the user always waits for a prompt before typing this
works well.
.PP
However if the user "types ahead" then it may guess incorrectly what
the prompt is. The result may be visually confusing, though not
necessarily any more so than it would have been anyway.
.SH "EXIT STATUS"
If the command exits normally then
.B with-readline
will exit with the same status. However if it is terminated by a
signal then
.B with-readline
will report this to standard error and exit with a status of
.RI 128+ signal .
.SH DIAGNOSTICS
Most error messages just indicate some library function failed. A few
deserve more detailed explanation. They usually mean either that
.B with-readline
has been installed incorrectly or not fully ported to the host
platform.
.TP
.B "real and effective group IDs do not match"
.TP
.B "failed to surrender privileged group ID"
.TP
.B "real and effective user IDs do not match"
.TP
.B "failed to surrender privileged user ID"
These messages only appear if
.B with-readline
is setuid or setgid, and indicate that something went wrong trying to
surrender privilege. This should "never happen".
.TP
.B "cannot parse wait status 0xNNNN"
This indicates that the command reported a wait status that
.B with-readline
did not know how to interpret.
.TP
.B "/dev/XYZ has insecure mode 0NNNNN"
.TP
.B "/dev/XYZ has owner NNN, but we are running as UID NNN"
These messages can appear if the pseudo-terminal created by
.B with-readline
has unsuitable permissions for secure operation. For instance, on
some platforms it needs to be installed setuid to root to properly
acquire a pty and if it is not then this problem can arise.
.SH FILES
.TP
.I ~/.inputrc
Readline configuration file
.TP
.I ~/APP_history
History file for APP.
.SH ENVIRONMENT
.TP
.B HOME
Home directory (contains history file).
.TP
.B HISTFILESIZE
Maximum history file size. See
.B --history
above.
.SH "SEE ALSO"
.BR readline (3)
.PP
The GNU Readline Library documentation.