Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
rlwrap(1)		    General Commands Manual		     rlwrap(1)

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  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, or when command manipulates its terminal	settings.

       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	termi-
	      nal  settings.   Use  this option	if you want to use rlwrap with
	      commands that already use	readline.  NB: With this  option,  rl-
	      wrap  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	inter-
	      vening space.

	      On a linux machine you can use the -N (--no-children) option  to
	      prevent  the wrapping of 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 (al-
	      though 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 be-
	      haved 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 preced-
	      ing!) 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-sensi-
	      tive, even with the -i option) This is not always	useful,	as rl-
	      wrap cannot keep track of	command's 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	> 0 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.

       -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  any-
	      thing) or	some other character.

       -f, --file file
	      Split  file into words 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/local/share/rlwrap/com-
	      pletions.

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

       -g, --forget-matching regexp
	      Forget  (i.e. drop from 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  ex-
	      ist).

       -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  di-
	      rect  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  rl-
	      wrap_call_editor	key  (CTRL-^  by  default) The argument	is op-
	      tional; 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	exten-
	      sion .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  up-
	      percase  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 automati-
	      cally set	the --always-readline option).

       -q, --quote-characters list_of_characters
	      Assume that the given characters act as quotes, e.g. when	match-
	      ing  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 users)

       -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  com-
	      mand 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 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, rl-
	      wrap waits timeout millisecs 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.  Be-
	      fore  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.  De-
	      fault 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  accord-
	      ingly,  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  special  perl module (cf.	RlwrapFilter(3pm)) for
	      easy filter writing. A number of example filters	are  installed
	      in  the  directory  /usr/local/share/rlwrap/filters.  "rlwrap -z
	      filter" displays information about a filter, "rlwrap -z listing"
	      lists  all  currently  installed filters.	 If filter needs argu-
	      ments, you should	quote the whole	filter command line:

		  rlwrap -z 'filter args' 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 con-
       sider single quotes as quotes (so that the parentheses in  e.g.	(print
       'q) match)
	  rlwrap -pBlue	-m -M .scm -q'"' gosh

       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_or-
	  ders -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 gen-
       erally  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,
       with its	own "pseudo-terminal" (pty),  and  monitor  this  pty  to  see
       whether	the  pty  is in	raw mode 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  "pa-
       tient" 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  dis-
       tinguish	 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 de-
       fault, 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 afer 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 num-
       ber  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
       Control + O
	      Accept the current line, but don't put it	in the	history	 list.
	      This   action   has   a	readline   command   name   rlwrap-ac-
	      cept-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 com-
	      mand name	 rlwrap-call-editor

       These 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 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
	  "\C-xe":   rlwrap-call-editor		   # CTRL-x e

       cf. the readline(3) manpage

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="vi +%L"
	   export RLWRAP_EDITOR="vim '+call cursor(%L,%C)'"

       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

       RLWRAP_FILTERDIR:
	      Any  executable  along your PATH can in theory be	used as	a fil-
	      ter, but because filters have to follow a	rather outlandish pro-
	      tocol (cf. RlwrapFilter (3)) it is a good	idea to	keep them sep-
	      arate. This is why rlwrap	adds a	special	 filter	 directory  to
	      $PATH  just  before  launching  a	 filter.  By  default, this is
	      /usr/local/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 rl-
       wrap 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  differ-
       ent commands.

       $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 sim-
	      ulate the	effect of a -r option that works across	invocations.

       /usr/local/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	behav-
	      iours  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 flter may	be used	to clean up the	prompt.

VERSION
       This manpage documents rlwrap version 0.42

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 prac-
       tically unchanged from rxvt-2.7.10 (currently maintained	 by  Geoff  C.
       Wing),  and  completion word lists are managed by Damian	Ivereigh's li-
       bredblack library. The few remaining lines of code were written by Hans
       Lub (hanslub42@gmail.com).

SEE ALSO
       readline(3), RlwrapFilter(3pm)

			       November	14, 2014		     rlwrap(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | DIRECT MODE AND READLINE MODE | PATIENT AND IMPATIENT MODE | COOKING PROMPTS | SPECIAL KEYS | ENVIRONMENT | SIGNALS | REDIRECTION | EXIT STATUS | FILES | BUGS and LIMITATIONS | VERSION | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rlwrap&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help