Linux Certif

Toute la documentation sur la certification Linux LPI

rlwrap

NAME

rlwrap - readline wrapper

SYNOPSIS

rlwrap [rlwrap-options] command ...

DESCRIPTION

rlwrap runs the specified command, intercepting user input in order to provide readline's line editing, persistent history and completion. rlwrap tries to be as transparent as possible, keeping track of command's terminal settings, so that it can do the right thing when command asks for single keypresses or for a password.

OPTIONS

-a, --always-readline [<password_prompt>]

Always use readline, regardless of command's terminal settings. Use this option you want to use rlwrap with commands that already use readline, e.g. to get rlwrap's history and completion. NB: With this option, rlwrap will echo (and save) passwords, unless you give command's password prompt as an argument. The argument is optional; if given, it has to directly follow the option without an intervening space.

-A, --ansi-colour-aware

Prompts that use colour will confuse rlwrap, especially at the end of long input lines. This option will make rlwrap behave in such cases. If the prompt contains anything fancier than ANSI color codes, this option may actually make things worse.

-b, --break-chars <list_of_characters>

Consider the specified characters word-breaking (whitespace is always word-breaking). This determines what is considered a "word", both when completing and when building a completion word list from files specified by -f options following (not preceding!) it. Default list (){}[],+-=&^%$#@"";|\ Unless -c is specified, / and . (period) are included in the default list.

-c, --complete-filenames

Complete filenames (filename completion is always case-sensitive, even with the -i option)
 When doing this, rlwrap keeps track of commands working directory.

-C, --command-name <command_name>|<N>

Use command_name instead of command to determine the names of history and completion files, and to initialise readline (as specified in ~/.inputrc). A numeric argument N means: use the Nth argument counting backwards from the end of the argument list

-D, --history-no-dupes n

How agressively to weed out duplicate entries from the input history. If n = 0, all inputs are kept in the history list, if n = 1 (this is the default) consecutive duplicates are dropped from the list, while n = 2 will make rlwrap drop all previous occurrences of the current input from the list.

-f, --file file

Split file into words and feed them into the completion word list. This option can be given more than once, and adds to the default completion list in $RLWRAP_HOME or /etc/rlwrap.

-F, --history-format format

Append format to each history entry, replacing the following printf-style conversion specifiers: %D by commands working directory, %P by the current prompt, %C by the command name, and all remaining format specifiers recognised by strftime (3)

format should start with one or more non-space characters, which will be used to recognise and strip off the appended format from recalled history items.

-h, --help

Print a short help message.

-H, --history-filename file

Read command history from file (and write it back there if --histsize >= 0)

-i, --case-insensitive

Ignore case when completing (filename completion remains case-sensitive). This option has to come before any -f options.

-l, --logfile file

Append command's output (including echo'ed user input) to file (creating file when it doesn't exist).

-n, --no-warnings

Don't print warnings.

-m, --multi-line [<newline_substitute>]

Enable multi-line input using a "newline substitute" character sequence (" \ ", [space-backslash-space] by default). Newline substitutes are translated to newlines before sending the input to command. With this option, you can call an external editor $RLWRAP_EDITOR on the (expanded) current input with the rlwrap_call_editor key (CTRL-^ by default) The argument is optional; if given, it has to directly follow the option without an intervening space.

-p, --prompt-colour [<colour_spec>]

Use ANSI-conformant <colour_spec> to colour any prompt displayed by command. All output that doesn't end in a newline is considered a "prompt" by rlwrap (but only if commands terminal is in cooked mode) - this may not be what you want. Prompts that are too long, or contain (colour) escape sequences, are not coloured. This option implies --ansi-colour-aware.

<colour spec> has the form <attr>;<fg>[;<bg>] Example: -p'0;31' will give a red prompt on the current background (this is the default when no argument is given). Google for 'ANSI color' to learn more about colour codes. The argument is optional; if given, it has to directly follow the option without an intervening space.

-P, --pre-given text

Start rlwrap with text in edit buffer (this will automatically set the --always-readline option). Use this for default user input in "one-shot" situations like the following replacement for the read shell command:

 
     rlwrap -H past_dinners -f toppings -P "pizza"\
       sh -c 'echo -n "please order: "; head -n 1 > dinner'
     prepare $(dinner)
 

-q, --quote-characters <list_of_characters>

Assume that the given characters act as quotes, e.g. when matching parentheses. Take care to escape the list properly, or else your shell will become confused (for example: -q "\"'", which happens to be the default)

-r, --remember

Put all words seen on in- and output on the completion list.

-s, --histsize <N>

Limit the history list to N entries, truncating the history file (default: 300). A negative size -N means the same as N, but treats the history file as read-only.

-v, --version

Print rlwrap version.

SPECIAL KEYS

Control + O

Accept the current line, but don't put it in the history list. This action has a readline command name rlwrap_accept_line_and_forget

Control + ^

Use an external editor to edit the current input (this will only work if the -m option is set). This action has a readline command name rlwrap_call_editor

If you don't like these keybindings, rlwraps special keys (all keys, in fact) kan be re-bound by including a line like the following in ~/.inputrc:

"\M-\C-m":rlwrap_accept_line_and_forget # ESC-ENTER

c.f. the readline(3) manpage for more about re-binding keys

ENVIRONMENT

RLWRAP_HOME: directory in which the history and completion files

are kept.

RLWRAP_EDITOR (or else EDITOR, or else VISUAL): editor to use for multi-line input. Example:

     export RLWRAP_EDITOR="emacs -nw"
     export RLWRAP_EDITOR="vi +%L"
 

The last example is the default; %L and %C are replaced by line and column numbers corresponding to the cursor position in rlwraps edit buffer

SIGNALS

A number of signals are forwarded to command: HUP INT QUIT USR1 USR2 TERM and (by way of resizing commands terminal) WINCH. Some care is taken to handle TSTP (usually a result of a CTRL-Z from the terminal) sensibly.

If command changes the keystrokes that send a particular signal from the keyboard (like emacs, which uses CTRL-G instead of CTRL-C) rlwrap will do the same.

When command is killed by a signal, rlwrap will clean up, reset its signal handlers an then commit suicide by sending the same signal to itself. This means that your shell will see the same exit status as it would have seen without rlwrap.

REDIRECTION

When the standard input is not a terminal, editing input doesn't make sense, so rlwrap will ignore all options and simply execute command. When stdout (or stderr) is not a terminal, rlwrap will re-open it to /dev/tty (the users terminal) after it has started command, so that commands output is redirected as expected, but keyboard input and rlwrap error messages are still visible.

The upshot of this is that rlwrap command behaves more or less like command when redirecting.

EXIT STATUS

non-zero after a rlwrap error, or else command's exit status. rlwrap will always leave the terminal in a tidy state, even after a crash.

FILES

rlwrap expects its history and completion files in $RLWRAP_HOME, but uses .dotfiles in the users home directory if this variable is not set. This will quickly become messy if you use rlwrap a lot.

$RLWRAP_HOME/command_history, ~/.command_history

History for command

$RLWRAP_HOME/command_completions, ~/.command_completions

Per-user completion word list for command. rlwrap never writes into this list, but one can combine -l and -f options to to simulate the effect of a -r option that works across invocations.

/etc/rlwrap/command

System-wide completion word list for command. This file is only consulted if the per-user completion word list is not found.

$INPUTRC, ~/.inputrc

Individual readline initialisation file (See readline (3) for its format). rlwrap sets its application name to command (unless you use the -C option), enabling different behaviours for different commands. One could e.g. put the following lines in ~/.inputrc:

 
    $if coqtop
        set show-all-if-ambiguous On
    $endif
 
 

making rlwrap show all completions whenever it runs coqtop

BUGS

rlwrap can try, but often fails to, handle prompts that contain control characters. A client that uses anything more than simple ANSI color codes will confuse rlwrap. The first thing you will notice in such cases is the cursor wrapping back on the same line before it has reached the right margin.

Prompt colouring (using the -p option) is not very robust. This is why long prompts are never colourised.

vi mode doesn't work well with terminals that cannot move the cursor up (A warning will be printed at startup)

Pasting large amounts of text into rlwrap will mess up the screen. However, command should receive the pasted text correctly.

VERSION

This manpage documents rlwrap version 0.30

AUTHORS

The readline library (written by Chet Ramey) does all the hard work behind the scenes, the pty-handling code has been taken practically unchanged from rxvt-2.7.10 (currently maintained by Geoff C. Wing), and completion word lists are managed by Damian Ivereighs libredblack library. The few remaining lines of code were written by Hans Lub (hlub@knoware.nl).

SEE ALSO

readline(3)