Provided by: rlwrap_0.43-1build2_amd64 bug

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 (and almost succeeds) to be completely transparent  -  you  (or  your  shell)
       shouldn't  notice  any  difference  between  command and rlwrap command - except the added
       readline functionality, of course.  This should even hold true when you are  re-directing,
       piping  and sending signals from and to command, and when command manipulates its terminal
       settings or working directory.

       There are many options to add (programmable) completion, handle multi-line  input,  colour
       and  re-write  prompts.  If you don't need them (and you probably don't), you can skip the
       rest of this manpage.

OPTIONS

       -a, --always-readline [password_prompt]
              Always remain in "readline mode", regardless of command's terminal  settings.   Use
              this  option  if  you  want  to  use rlwrap with commands that already do some line
              editing.  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.

              On a linux machine you can use the -N  (--no-children)  option  to  avoid  wrapping
              pagers and editors called from command; this should make them much more usable

              Many commands that need --always-readline may also need -t dumb to prevent terminal
              control  sequences  from  confusing  rlwrap   (although   this   will   annoy   the
              above-mentioned pagers and editors)

       -A, --ansi-colour-aware
              Prompts  that  use  colour will confuse rlwrap, especially at the end of long input
              lines. This option will make rlwrap better behaved in such cases.   If  the  prompt
              contains  anything  fancier  than  ANSI colour 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).  On  Linux,  OS X, FreeBSD and Solaris rlwrap will keep track of command's
              working directory, so that relative  filenames  will  be  completed  as  one  would
              expect.

       -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 > 0 means: use the Nth argument counting backwards from the end
              of the argument list

       -D, --history-no-dupes n
              How aggressively 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.

       -e, --extra-char-after-completion char
              By  default,  rlwrap  appends  a space after any inserted completion text. Use this
              option to change this to '' (don't insert anything) or some other character.

       -f, --file file
              Split file into  words  (using  the  default  word-breaking  characters,  or  those
              specified  by --break-chars), and add them to the completion word list. This option
              can be  given  more  than  once,  and  adds  to  the  default  completion  list  in
              $RLWRAP_HOME or /usr/share/rlwrap/completions.

              Specifying  -f . will make rlwrap use the current history file as a completion word
              list.

       -g, --forget-matching regexp
              Forget (i.e. never put into the history list) all input lines that match the  POSIX
              1003.2 regular expression regexp.  The match is always case-insensitive. regexp may
              be an ordinary string. For more about regular expressions, see  regex (7)

       -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.

       -I, --pass-sigint-as-sigterm
              Send a TERM signal to command when an INT is received (e.g. when you press CTRL-C).

       -l, --logfile file
              When  in  readline  mode, 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.

       -N, --no-children
              Don't rlwrap command's children: whenever rlwrap notices that  command  is  waiting
              for  one  of  its children, it switches to direct mode, handing down all keypresses
              immediately.  With this  option  commands  that  need  --always-readline  can  call
              editors and pagers and still be usable.

              This  option  needs  /proc/command_pid/wchan,  so  it only works with linux kernels
              configured with CONFIG_KALLSYMS.

       -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.

       -M, --multi-line-ext .ext
              Call  multi-line-editor on temporary files with filename extension .ext (useful for
              e.g. automatic syntax colouring)

       -o, --one-shot
              Send an EOF to command after accepting the first line of input

       -O, --only-cook regexp
              Only ever "cook" prompts that match regexp

       -p, --prompt-colour [colour_name|Colour_name|colour_spec]
              Use one of  the  colour  names  black,  red,  green,  yellow,  blue,  cyan,  purple
              (=magenta)  or  white,  or  an  ANSI-conformant  <colour_spec> to colour any prompt
              displayed by command. An uppercase colour name (Yellow or YELLOW  )  gives  a  bold
              prompt.   Prompts  that  already  contain  (colour)  escape sequences or one of the
              readline "ignore markers" (ASCII 0x01 and  0x02)  are  not  coloured.  This  option
              implies  --ansi-colour-aware.  colour spec has the form <attr>;<fg>[;<bg>] Example:
              -p'1;31' will give a bold 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  its  edit  buffer  (this will automatically set the
              --always-readline option).

       -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 for your shell (example: -q "\"'", which
              happens to be the default, or -q "\"" which will be better for lisp-like input)

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

       -R, --renice
              Make rlwrap nicer than  command  (cf  nice  (1)).  This  may  prevent  rlwrap  from
              interrupting  command  to  display  a prompt when command is still "thinking" about
              what to output next.

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

       -S, --substitute-prompt prompt
              Substitute the specified prompt for   command's  own  prompt.  Mainly  useful  when
              command doesn't have a prompt.

       -t, --set-term-name name
              Set  command's TERM to name. Programs that confuse rlwrap with fancy screen control
              codes can sometimes be tamed by specifying -t dumb

       -U, --mirror-arguments
              (linux only) Keep track of command's arguments as seen by the ps (1)  command,  and
              mirror  them  in  rlwrap's  own  arguments  This is mainly useful for commands that
              overwrite command-line password arguments that would be exposed by  rlwrap  without
              this option.

       -v, --version
              Print rlwrap version.

       -w, --wait-before-prompt timeout
              In  order  to determine if  command's last output is a prompt, rlwrap waits timeout
              milliseconds after receiving it.  Only when no  more  output  has  arrived,  it  is
              cooked (coloured, filtered and/or replaced by a substitute prompt) and displayed as
              a prompt.  Before this the prompt is displayed "uncooked". Most users won't notice,
              but  heavy  cookers  can  prepend the timeout with a minus sign, making rlwrap hold
              back the prompt until it has  been  cooked  ("patient  mode").  This  will  prevent
              flashing  of the prompt, but it will also interfere with long output lines and make
              switches from direct to readline mode less reliable. Default timeout: 40 ms

       -W, --polling
              EXPERIMENTAL: Wake up every timeout millisecs, where timeout is the same as for the
              -w  (--wait-before-prompt)  option,  40  ms  by  default. This is used to sense the
              slave's interrupt character and ISIG flag and to adjust stdin's  terminal  settings
              accordingly,  even  before  you  press a key. Try this option e.g. when CTRL-C acts
              differently on  command  with, and without, rlwrap.

       -z, --filter filter
              Use a filter to change rlwrap's behaviour. A filter can be  used  to  keep  certain
              input  out  of  the  history,  to  change the prompt, to implement simple macros or
              programmable completion.. rlwrap comes with a perl and a Python 3  module  to  make
              filter  writing easy. (cf. RlwrapFilter(3pm) for the perl module, the python one is
              very  similar)  A  number  of  example  filters  are  installed  in  the  directory
              /usr/share/rlwrap/filters.  "rlwrap -z filter" displays information about a filter,
              "rlwrap -z listing"  lists  all  currently  installed  filters.   If  filter  needs
              arguments, you should quote the whole filter command line:

                  rlwrap -z 'filter args' command ...
                  rlwrap -z 'pipeline filter1 ... : filter2 ... : ...' command ...

              If  this command line contains shell metacharacters, rlwrap passes it to the system
              shell for parsing.

EXAMPLES

       Run nc (netcat) with command-line editing and history
          rlwrap nc

       Wrap smbclient (which uses readline itself), keep passwords out of the history  and  don't
       wrap commands launched from smbclient (like more)
          rlwrap -aPassword: -N smbclient //PEANUT/C

       Wrap  gauche  (a  Scheme  interpreter)  with a bold blue prompt, enable multi-line editing
       (using .scm as filename extension) and don't consider single quotes as quotes (so that the
       parentheses in e.g. (print 'q) match)
          rlwrap -pBlue -m -M .scm -q'

       Get a list of all currently installed filters
          rlwrap -z listing

       Get help for the filter pipeto
          rlwrap -z pipeto

       Wrap  sqlite3, use the pipeto filter to be able to pipe the output of SQL commands through
       grep and/or less, complete (case-insensitively) on the SQL keywords in 'sql_words'
          rlwrap -a -z pipeto -i -f sql_words sqlite3 contacts.db

       In a shell script, use rlwrap in 'one-shot' mode as a replacement for read
          order=$(rlwrap -pYellow -S 'Your pizza? ' -H past_orders -P Margherita -o cat)

DIRECT MODE AND READLINE MODE

       Most simple console commands put your terminal either in "cooked" or  in  "raw"  mode.  In
       cooked mode the terminal will wait until you press the ENTER key before handing the entire
       line to the program, in raw mode every key you press is handed down immediately. In cooked
       mode  you generally can use the backspace key, but not the arrow keys, to edit your input.
       Most simple console commands use cooked mode whenever they want whole input lines, and raw
       mode  when  they  want single keypresses. More sophisticated commands tend to use raw mode
       all the time; they may sometimes be rlwrappable with the -a (and -N) options.

       When you rlwrap command, rlwrap will run it  a  in  a  separate  session,  under  its  own
       (controlling)  "pseudo-terminal"  (pty), and monitor this pty to see whether it is in raw,
       or in cooked mode. In the first case, rlwrap will  copy  all  input  and  output  directly
       between  command  and  your  terminal ("direct mode"). In the second case, rlwrap will use
       readline to edit your input ("readline mode"), and monitor command's output -  every  last
       line  that  doesn't  end  with  a  newline  is  a  potential prompt. How it handles such a
       candidate prompt depends on its being in "patient" or "impatient" mode:

PATIENT AND IMPATIENT MODE

       If command writes a lot of output, it tends to be written (and read) in "chunks". Not  all
       chunks  will  end  with  a  newline, and we need to distinguish their last lines from real
       prompts, especially if we want to re-write ("cook") prompts. rlwrap solves  this  (almost)
       by  waiting  a  little, to see if there is more to come. "A little" is 40 msec by default,
       but this can be changed with the -w option.  Normally rlwrap writes the  suspected  prompt
       as  soon as it is received, replacing it with a "cooked" version after the wait time. This
       is called "impatient" mode. If you don't  like  the  flashing  effect  (which  can  become
       annoying  when  you  "cook"  the  prompt  heavily) you can put rlwrap in "patient mode" by
       specifying a negative value with -w (e.g. -w -40). Rlwrap will then hold back  the  prompt
       and only print if after cooking.

COOKING PROMPTS

       If  and  when  rlwrap decides that it has a prompt, it will perform a number of actions on
       it, depending on the given options: filtering (-z), substituting (-S) and colouring  (-p),
       in  this  order.  The  resulting  "cooked" prompt is then printed (after erasing the "raw"
       prompt, if necessary)

SPECIAL KEYS AND BINDABLE COMMANDS

       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 (see RLWRAP_EDITOR below) 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

       (Not currently bound)
              Any  key can be bound to the readline command rlwrap-direct-keypress. This key will
              then always be sent directly to command,  even when rlwrap is not in direct mode.

       (Not currently bound)
              Any key can be bound to the readline command  rlwrap-hotkey.  This  key  will  then
              cause  the  current  input  line  and  the  current  history  to  be  filtered (cf.
              RlwrapFilter(3pm)) through the current filter (hence be a no-op when  there  is  no
              filter),  which  then  can  re-write the input line, move the cursor and update the
              history. After that, the user can still edit the resulting input.

       (Not currently bound)
              rlwrap-hotkey-without-history acts like  rlwrap-hotkey, but the history (which  can
              be  quite  large) is not passed to the filter. This is more efficient if the filter
              wouldn't do anything useful with the history anyway.

       The special keys were chosen for no other reason than that they  are not  currently  bound
       to  any  readline  action.  If you don't like them, (or your window manager swallows them)
       they (and the other 3 commands) can be re-bound more sensibly by including lines like  the
       following in your ~/.inputrc:

          "\M-\C-m": rlwrap-accept-line-and-forget         # ESC-ENTER to accept but keep out of history
          "\C-xe":   rlwrap-call-editor                    # CTRL-x e to edit (multi-line) input in editor of your choice
           $if erl                                         # (only) for the Erlang shell:
              "\C-g": rlwrap-direct-keypress               # pass CTRL-g directly to enter 'user switch' command
           $endif
           "\C-y": rlwrap-hotkey-without-history            # CTRL-y to filter input line (and e.g. insert X selection)

       cf. the readline(3) manpage. (NB: take care to not use keys that are already caught by the
       terminal driver, like CTRL+S, as rlwrap will never see those)

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 (and rlwrap-edit-history). Example:

           export RLWRAP_EDITOR="vi +%L"
           export RLWRAP_EDITOR="vim '+call cursor(%L,%C)'"
           export RLWRAP_EDITOR="emacs +%L:%C %F"

       The first example above is the default; %L and %C are replaced by line and column  numbers
       corresponding  to  the  cursor position in rlwrap's edit buffer, %F is replaced by name of
       the (temporary) file.  If  %F  is  not  used,  this  name  is  put  after  the  (expanded)
       $RLWAP_EDITOR

       RLWRAP_FILTERDIR:
              Any  executable  along  your  PATH  can  in theory be used as a filter, but because
              filters have to follow a rather outlandish protocol (cf. RlwrapFilter (3)) it is  a
              good idea to keep them separate. This is why rlwrap adds a special filter directory
              in  front  of  $PATH  just  before  launching  a  filter.  By  default,   this   is
              /usr/share/rlwrap/filters, but $RLWRAP_FILTERDIR is used if set.

SIGNALS

       A  number  of signals are forwarded to command: HUP INT QUIT USR1 USR2 TERM and (by way of
       resizing command's terminal) WINCH. Some care is taken to handle TSTP (usually a result of
       a  CTRL-Z from the terminal) sensibly - for example, after suspending rlwrap in the middle
       of a line edit, continuing (by typing 'fg') will land you at  the  exact  spot  where  you
       suspended it.

       Filters  that  take  more than 1 second to respond can be interrupted by a CTRL-C from the
       terminal (although rlwrap will not survive this)

       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 (but only after the
       next keystroke - use the --polling option to make rlwrap more transparent in this respect)

       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 sees
       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  command's  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
       user's  home  directory if this variable is not set. This will quickly become messy if you
       use rlwrap for many different commands.

       $RLWRAP_HOME/command_history, ~/.command_history
              History for command (remember that command may be overridden by the  --command-name
              (or -C) option)

       $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.

       /usr/share/rlwrap/completions/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 (this can be overridden by 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 and LIMITATIONS

       Though  it  is  flexible,  delivers the goods (readline functionality), and adheres to the
       Unix "many small tools" paradigm, rlwrap  is a  kludge.  It  cannot  know  anything  about
       command's  internal  state, which makes context-sensitive completion impossible. Using the
       readline library from within command is still the best option.

       Also, because "it takes two to tango" there is  no  way  for  rlwrap  to  synchronise  its
       internal  state  with command, resulting in a number of subtle race conditions, where e.g.
       command may have changed the state of its terminal before rlwrap has read  command  output
       that was written before the state change. You will notice these races especially on a busy
       machine and with heavy "cooking" and filtering, when suddenly (and unpredictably)  promtps
       or command output are garbled or incorrectly coloured.

       rlwrap  can  try,  but  often fails to, handle prompts that contain control characters.  A
       filter may be used to clean up the prompt.

VERSION

       This manpage documents rlwrap version 0.43

AUTHORS

       The readline library (written by Brian Fox and 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
       Ivereigh's  libredblack  library. The few remaining lines of code were written by Hans Lub
       (hanslub42@gmail.com).

SEE ALSO

       readline(3), RlwrapFilter(3pm)

                                          July 19, 2016                                 rlwrap(1)