# PaCkAgE DaTaStReAm
readline 1 3217
# end of header
0707010002ca41000081a40000000000000000000000015424e06e00000110000001120001001bffffffffffffffff0000001100000000readline/pkginfo RSTATES=S s 1 2 3
ISTATES=S s 1 2 3
BASEDIR=/
CLASSES=none
CATEGORY=utility
ARCH=i386
DESC=GNU readline library
EMAIL=http://tiswww.case.edu/php/chet/readline/rltop.html
VENDOR=GNU
PSTAMP=26th September 2014
VERSION=6.3
NAME=GNU readline 6.3 i86pc Solaris 11
PKG=readline
0707010002ca40000081a40000000000000000000000015424e06e00000e05000001120001001bffffffffffffffff0000001000000000readline/pkgmap : 1 3217
1 d none /usr/local/bin 0755 root root
1 d none /usr/local/include 0755 root root
1 d none /usr/local/include/readline 0755 root root
1 f none /usr/local/include/readline/chardefs.h 0644 root root 4577 22400 1411702775
1 f none /usr/local/include/readline/history.h 0644 root root 10079 13481 1411702775
1 f none /usr/local/include/readline/keymaps.h 0644 root root 3163 5083 1411702775
1 f none /usr/local/include/readline/readline.h 0644 root root 37802 3874 1411702775
1 f none /usr/local/include/readline/rlconf.h 0644 root root 2438 7747 1411702775
1 f none /usr/local/include/readline/rlstdc.h 0644 root root 1835 18143 1411702775
1 f none /usr/local/include/readline/rltypedefs.h 0644 root root 2633 25525 1411702775
1 f none /usr/local/include/readline/tilde.h 0644 root root 3046 63660 1411702775
1 d none /usr/local/lib 0755 root root
1 f none /usr/local/lib/libhistory.a 0644 root root 52628 44494 1411702775
1 s none /usr/local/lib/libhistory.so=libhistory.so.6
1 f none /usr/local/lib/libhistory.so.6 0555 root root 45864 13083 1411702775
1 f none /usr/local/lib/libreadline.a 0644 root root 432864 6143 1411702775
1 s none /usr/local/lib/libreadline.so=libreadline.so.6
1 f none /usr/local/lib/libreadline.so.6 0555 root root 355900 16558 1411702775
1 d none /usr/local/share 0755 root root
1 d none /usr/local/share/doc 0755 root root
1 d none /usr/local/share/doc/readline 0755 root root
1 f none /usr/local/share/doc/readline/CHANGES 0644 root root 57525 17916 1411702775
1 f none /usr/local/share/doc/readline/INSTALL 0644 root root 12304 40684 1411702775
1 f none /usr/local/share/doc/readline/README 0644 root root 8028 58111 1411702775
1 d none /usr/local/share/info 0755 root root
1 f none /usr/local/share/info/dir 0644 root root 16778 3112 1411702775
1 f none /usr/local/share/info/history.info 0644 root root 60979 32594 1411702775
1 f none /usr/local/share/info/readline.info 0644 root root 217260 56989 1411702775
1 f none /usr/local/share/info/rluserman.info 0644 root root 82095 51367 1411702775
1 d none /usr/local/share/man 0755 root root
1 d none /usr/local/share/man/man3 0755 root root
1 f none /usr/local/share/man/man3/history.3 0644 root root 22290 16560 1411702775
1 f none /usr/local/share/man/man3/readline.3 0644 root root 44308 32514 1411702775
1 d none /usr/local/share/readline 0755 root root
1 f none /usr/local/share/readline/excallback.c 0644 root root 5808 28650 1411702775
1 f none /usr/local/share/readline/fileman.c 0644 root root 11426 11069 1411702775
1 f none /usr/local/share/readline/hist_erasedups.c 0644 root root 2767 15825 1411702775
1 f none /usr/local/share/readline/hist_purgecmd.c 0644 root root 3362 60355 1411702775
1 f none /usr/local/share/readline/histexamp.c 0644 root root 2889 24105 1411702775
1 f none /usr/local/share/readline/manexamp.c 0644 root root 3300 43704 1411702775
1 f none /usr/local/share/readline/rl-callbacktest.c 0644 root root 2038 31472 1411702775
1 f none /usr/local/share/readline/rl-fgets.c 0644 root root 11147 3436 1411702775
1 f none /usr/local/share/readline/rl.c 0644 root root 3179 50733 1411702775
1 f none /usr/local/share/readline/rlcat.c 0644 root root 3299 55901 1411702775
1 f none /usr/local/share/readline/rlevent.c 0644 root root 3295 60133 1411702775
1 f none /usr/local/share/readline/rlptytest.c 0644 root root 6531 38870 1411702775
1 f none /usr/local/share/readline/rltest.c 0644 root root 2146 29759 1411702775
1 f none /usr/local/share/readline/rlversion.c 0644 root root 1287 42286 1411702775
1 i checkinstall 790 2505 1411702894
1 i pkginfo 272 21269 1411702894
07070100000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000b00000000TRAILER!!! 0707010002ca41000081a40000000000000000000000015424e06e00000110000001120001001bffffffffffffffff0000000800000000pkginfo RSTATES=S s 1 2 3
ISTATES=S s 1 2 3
BASEDIR=/
CLASSES=none
CATEGORY=utility
ARCH=i386
DESC=GNU readline library
EMAIL=http://tiswww.case.edu/php/chet/readline/rltop.html
VENDOR=GNU
PSTAMP=26th September 2014
VERSION=6.3
NAME=GNU readline 6.3 i86pc Solaris 11
PKG=readline
0707010002ca40000081a40000000000000000000000015424e06e00000e05000001120001001bffffffffffffffff0000000700000000pkgmap : 1 3217
1 d none /usr/local/bin 0755 root root
1 d none /usr/local/include 0755 root root
1 d none /usr/local/include/readline 0755 root root
1 f none /usr/local/include/readline/chardefs.h 0644 root root 4577 22400 1411702775
1 f none /usr/local/include/readline/history.h 0644 root root 10079 13481 1411702775
1 f none /usr/local/include/readline/keymaps.h 0644 root root 3163 5083 1411702775
1 f none /usr/local/include/readline/readline.h 0644 root root 37802 3874 1411702775
1 f none /usr/local/include/readline/rlconf.h 0644 root root 2438 7747 1411702775
1 f none /usr/local/include/readline/rlstdc.h 0644 root root 1835 18143 1411702775
1 f none /usr/local/include/readline/rltypedefs.h 0644 root root 2633 25525 1411702775
1 f none /usr/local/include/readline/tilde.h 0644 root root 3046 63660 1411702775
1 d none /usr/local/lib 0755 root root
1 f none /usr/local/lib/libhistory.a 0644 root root 52628 44494 1411702775
1 s none /usr/local/lib/libhistory.so=libhistory.so.6
1 f none /usr/local/lib/libhistory.so.6 0555 root root 45864 13083 1411702775
1 f none /usr/local/lib/libreadline.a 0644 root root 432864 6143 1411702775
1 s none /usr/local/lib/libreadline.so=libreadline.so.6
1 f none /usr/local/lib/libreadline.so.6 0555 root root 355900 16558 1411702775
1 d none /usr/local/share 0755 root root
1 d none /usr/local/share/doc 0755 root root
1 d none /usr/local/share/doc/readline 0755 root root
1 f none /usr/local/share/doc/readline/CHANGES 0644 root root 57525 17916 1411702775
1 f none /usr/local/share/doc/readline/INSTALL 0644 root root 12304 40684 1411702775
1 f none /usr/local/share/doc/readline/README 0644 root root 8028 58111 1411702775
1 d none /usr/local/share/info 0755 root root
1 f none /usr/local/share/info/dir 0644 root root 16778 3112 1411702775
1 f none /usr/local/share/info/history.info 0644 root root 60979 32594 1411702775
1 f none /usr/local/share/info/readline.info 0644 root root 217260 56989 1411702775
1 f none /usr/local/share/info/rluserman.info 0644 root root 82095 51367 1411702775
1 d none /usr/local/share/man 0755 root root
1 d none /usr/local/share/man/man3 0755 root root
1 f none /usr/local/share/man/man3/history.3 0644 root root 22290 16560 1411702775
1 f none /usr/local/share/man/man3/readline.3 0644 root root 44308 32514 1411702775
1 d none /usr/local/share/readline 0755 root root
1 f none /usr/local/share/readline/excallback.c 0644 root root 5808 28650 1411702775
1 f none /usr/local/share/readline/fileman.c 0644 root root 11426 11069 1411702775
1 f none /usr/local/share/readline/hist_erasedups.c 0644 root root 2767 15825 1411702775
1 f none /usr/local/share/readline/hist_purgecmd.c 0644 root root 3362 60355 1411702775
1 f none /usr/local/share/readline/histexamp.c 0644 root root 2889 24105 1411702775
1 f none /usr/local/share/readline/manexamp.c 0644 root root 3300 43704 1411702775
1 f none /usr/local/share/readline/rl-callbacktest.c 0644 root root 2038 31472 1411702775
1 f none /usr/local/share/readline/rl-fgets.c 0644 root root 11147 3436 1411702775
1 f none /usr/local/share/readline/rl.c 0644 root root 3179 50733 1411702775
1 f none /usr/local/share/readline/rlcat.c 0644 root root 3299 55901 1411702775
1 f none /usr/local/share/readline/rlevent.c 0644 root root 3295 60133 1411702775
1 f none /usr/local/share/readline/rlptytest.c 0644 root root 6531 38870 1411702775
1 f none /usr/local/share/readline/rltest.c 0644 root root 2146 29759 1411702775
1 f none /usr/local/share/readline/rlversion.c 0644 root root 1287 42286 1411702775
1 i checkinstall 790 2505 1411702894
1 i pkginfo 272 21269 1411702894
0707010002ca72000041ed0000000000000000000000025424e06e00000000000001120001001bffffffffffffffff0000000800000000install 0707010002ca73000081ed0000000000000000000000015424e06e00000316000001120001001bffffffffffffffff0000001500000000install/checkinstall #!/bin/sh
#
expected_bits="64"
expected_release="5.11"
expected_platform="i386"
#
release=`uname -r`
platform=`uname -p`
bits=`isainfo -b`
#
if [ ${platform} != ${expected_platform} ]; then
echo "\n\n\n\tThis package must be installed on a ${expected_platform} architecture\n"
echo "\tAborting installation.\n\n\n"
exit 1
fi
if [ ${release} != ${expected_release} ]; then
echo "\n\n\n\tThis package must be installed on a ${expected_release} machine\n"
echo "\tAborting installation.\n\n\n"
exit 1
fi
#if [ ${bits} != ${expected_bits} ]; then
# echo "\n\n\n\tThis package must be installed on a ${expected_bits} bit machine\n"
# echo "\tYour machine is running a ${bits} bit O.S. currently\n"
# echo "\tAborting installation.\n\n\n"
# exit 1
#fi
exit 0
0707010002ca42000041ed0000000000000000000000035424e06e00000000000001120001001bffffffffffffffff0000000500000000root 0707010002ca43000041ed0000000000000000000000035424e06e00000000000001120001001bffffffffffffffff0000000900000000root/usr 0707010002ca44000041ed0000000000000000000000055424e06e00000000000001120001001bffffffffffffffff0000000f00000000root/usr/local 0707010002ca45000041ed0000000000000000000000035424e06e00000000000001120001001bffffffffffffffff0000001700000000root/usr/local/include 0707010002ca46000041ed0000000000000000000000025424e06e00000000000001120001001bffffffffffffffff0000002000000000root/usr/local/include/readline 0707010002ca4d000081a40000000000000000000000015424dff700000a49000001120001001bffffffffffffffff0000002d00000000root/usr/local/include/readline/rltypedefs.h /* rltypedefs.h -- Type declarations for readline functions. */
/* Copyright (C) 2000-2011 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library
for reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#ifndef _RL_TYPEDEFS_H_
#define _RL_TYPEDEFS_H_
#ifdef __cplusplus
extern "C" {
#endif
/* New style. */
#if !defined (_RL_FUNCTION_TYPEDEF)
# define _RL_FUNCTION_TYPEDEF
/* Bindable functions */
typedef int rl_command_func_t PARAMS((int, int));
/* Typedefs for the completion system */
typedef char *rl_compentry_func_t PARAMS((const char *, int));
typedef char **rl_completion_func_t PARAMS((const char *, int, int));
typedef char *rl_quote_func_t PARAMS((char *, int, char *));
typedef char *rl_dequote_func_t PARAMS((char *, int));
typedef int rl_compignore_func_t PARAMS((char **));
typedef void rl_compdisp_func_t PARAMS((char **, int, int));
/* Type for input and pre-read hook functions like rl_event_hook */
typedef int rl_hook_func_t PARAMS((void));
/* Input function type */
typedef int rl_getc_func_t PARAMS((FILE *));
/* Generic function that takes a character buffer (which could be the readline
line buffer) and an index into it (which could be rl_point) and returns
an int. */
typedef int rl_linebuf_func_t PARAMS((char *, int));
/* `Generic' function pointer typedefs */
typedef int rl_intfunc_t PARAMS((int));
#define rl_ivoidfunc_t rl_hook_func_t
typedef int rl_icpfunc_t PARAMS((char *));
typedef int rl_icppfunc_t PARAMS((char **));
typedef void rl_voidfunc_t PARAMS((void));
typedef void rl_vintfunc_t PARAMS((int));
typedef void rl_vcpfunc_t PARAMS((char *));
typedef void rl_vcppfunc_t PARAMS((char **));
typedef char *rl_cpvfunc_t PARAMS((void));
typedef char *rl_cpifunc_t PARAMS((int));
typedef char *rl_cpcpfunc_t PARAMS((char *));
typedef char *rl_cpcppfunc_t PARAMS((char **));
#endif /* _RL_FUNCTION_TYPEDEF */
#ifdef __cplusplus
}
#endif
#endif /* _RL_TYPEDEFS_H_ */
0707010002ca48000081a40000000000000000000000015424dff70000275f000001120001001bffffffffffffffff0000002a00000000root/usr/local/include/readline/history.h /* history.h -- the names of functions that you can call in history. */
/* Copyright (C) 1989-2009 Free Software Foundation, Inc.
This file contains the GNU History Library (History), a set of
routines for managing the text of previously typed lines.
History 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 3 of the License, or
(at your option) any later version.
History 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 History. If not, see .
*/
#ifndef _HISTORY_H_
#define _HISTORY_H_
#ifdef __cplusplus
extern "C" {
#endif
#include /* XXX - for history timestamp code */
#if defined READLINE_LIBRARY
# include "rlstdc.h"
# include "rltypedefs.h"
#else
# include
# include
#endif
#ifdef __STDC__
typedef void *histdata_t;
#else
typedef char *histdata_t;
#endif
/* The structure used to store a history entry. */
typedef struct _hist_entry {
char *line;
char *timestamp; /* char * rather than time_t for read/write */
histdata_t data;
} HIST_ENTRY;
/* Size of the history-library-managed space in history entry HS. */
#define HISTENT_BYTES(hs) (strlen ((hs)->line) + strlen ((hs)->timestamp))
/* A structure used to pass the current state of the history stuff around. */
typedef struct _hist_state {
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
int offset; /* The location pointer within this array. */
int length; /* Number of elements within this array. */
int size; /* Number of slots allocated to this array. */
int flags;
} HISTORY_STATE;
/* Flag values for the `flags' member of HISTORY_STATE. */
#define HS_STIFLED 0x01
/* Initialization and state management. */
/* Begin a session in which the history functions might be used. This
just initializes the interactive variables. */
extern void using_history PARAMS((void));
/* Return the current HISTORY_STATE of the history. */
extern HISTORY_STATE *history_get_history_state PARAMS((void));
/* Set the state of the current history array to STATE. */
extern void history_set_history_state PARAMS((HISTORY_STATE *));
/* Manage the history list. */
/* Place STRING at the end of the history list.
The associated data field (if any) is set to NULL. */
extern void add_history PARAMS((const char *));
/* Change the timestamp associated with the most recent history entry to
STRING. */
extern void add_history_time PARAMS((const char *));
/* A reasonably useless function, only here for completeness. WHICH
is the magic number that tells us which element to delete. The
elements are numbered from 0. */
extern HIST_ENTRY *remove_history PARAMS((int));
/* Free the history entry H and return any application-specific data
associated with it. */
extern histdata_t free_history_entry PARAMS((HIST_ENTRY *));
/* Make the history entry at WHICH have LINE and DATA. This returns
the old entry so you can dispose of the data. In the case of an
invalid WHICH, a NULL pointer is returned. */
extern HIST_ENTRY *replace_history_entry PARAMS((int, const char *, histdata_t));
/* Clear the history list and start over. */
extern void clear_history PARAMS((void));
/* Stifle the history list, remembering only MAX number of entries. */
extern void stifle_history PARAMS((int));
/* Stop stifling the history. This returns the previous amount the
history was stifled by. The value is positive if the history was
stifled, negative if it wasn't. */
extern int unstifle_history PARAMS((void));
/* Return 1 if the history is stifled, 0 if it is not. */
extern int history_is_stifled PARAMS((void));
/* Information about the history list. */
/* Return a NULL terminated array of HIST_ENTRY which is the current input
history. Element 0 of this list is the beginning of time. If there
is no history, return NULL. */
extern HIST_ENTRY **history_list PARAMS((void));
/* Returns the number which says what history element we are now
looking at. */
extern int where_history PARAMS((void));
/* Return the history entry at the current position, as determined by
history_offset. If there is no entry there, return a NULL pointer. */
extern HIST_ENTRY *current_history PARAMS((void));
/* Return the history entry which is logically at OFFSET in the history
array. OFFSET is relative to history_base. */
extern HIST_ENTRY *history_get PARAMS((int));
/* Return the timestamp associated with the HIST_ENTRY * passed as an
argument */
extern time_t history_get_time PARAMS((HIST_ENTRY *));
/* Return the number of bytes that the primary history entries are using.
This just adds up the lengths of the_history->lines. */
extern int history_total_bytes PARAMS((void));
/* Moving around the history list. */
/* Set the position in the history list to POS. */
extern int history_set_pos PARAMS((int));
/* Back up history_offset to the previous history entry, and return
a pointer to that entry. If there is no previous entry, return
a NULL pointer. */
extern HIST_ENTRY *previous_history PARAMS((void));
/* Move history_offset forward to the next item in the input_history,
and return the a pointer to that entry. If there is no next entry,
return a NULL pointer. */
extern HIST_ENTRY *next_history PARAMS((void));
/* Searching the history list. */
/* Search the history for STRING, starting at history_offset.
If DIRECTION < 0, then the search is through previous entries,
else through subsequent. If the string is found, then
current_history () is the history entry, and the value of this function
is the offset in the line of that history entry that the string was
found in. Otherwise, nothing is changed, and a -1 is returned. */
extern int history_search PARAMS((const char *, int));
/* Search the history for STRING, starting at history_offset.
The search is anchored: matching lines must begin with string.
DIRECTION is as in history_search(). */
extern int history_search_prefix PARAMS((const char *, int));
/* Search for STRING in the history list, starting at POS, an
absolute index into the list. DIR, if negative, says to search
backwards from POS, else forwards.
Returns the absolute index of the history element where STRING
was found, or -1 otherwise. */
extern int history_search_pos PARAMS((const char *, int, int));
/* Managing the history file. */
/* Add the contents of FILENAME to the history list, a line at a time.
If FILENAME is NULL, then read from ~/.history. Returns 0 if
successful, or errno if not. */
extern int read_history PARAMS((const char *));
/* Read a range of lines from FILENAME, adding them to the history list.
Start reading at the FROM'th line and end at the TO'th. If FROM
is zero, start at the beginning. If TO is less than FROM, read
until the end of the file. If FILENAME is NULL, then read from
~/.history. Returns 0 if successful, or errno if not. */
extern int read_history_range PARAMS((const char *, int, int));
/* Write the current history to FILENAME. If FILENAME is NULL,
then write the history list to ~/.history. Values returned
are as in read_history (). */
extern int write_history PARAMS((const char *));
/* Append NELEMENT entries to FILENAME. The entries appended are from
the end of the list minus NELEMENTs up to the end of the list. */
extern int append_history PARAMS((int, const char *));
/* Truncate the history file, leaving only the last NLINES lines. */
extern int history_truncate_file PARAMS((const char *, int));
/* History expansion. */
/* Expand the string STRING, placing the result into OUTPUT, a pointer
to a string. Returns:
0) If no expansions took place (or, if the only change in
the text was the de-slashifying of the history expansion
character)
1) If expansions did take place
-1) If there was an error in expansion.
2) If the returned line should just be printed.
If an error occurred in expansion, then OUTPUT contains a descriptive
error message. */
extern int history_expand PARAMS((char *, char **));
/* Extract a string segment consisting of the FIRST through LAST
arguments present in STRING. Arguments are broken up as in
the shell. */
extern char *history_arg_extract PARAMS((int, int, const char *));
/* Return the text of the history event beginning at the current
offset into STRING. Pass STRING with *INDEX equal to the
history_expansion_char that begins this specification.
DELIMITING_QUOTE is a character that is allowed to end the string
specification for what to search for in addition to the normal
characters `:', ` ', `\t', `\n', and sometimes `?'. */
extern char *get_history_event PARAMS((const char *, int *, int));
/* Return an array of tokens, much as the shell might. The tokens are
parsed out of STRING. */
extern char **history_tokenize PARAMS((const char *));
/* Exported history variables. */
extern int history_base;
extern int history_length;
extern int history_max_entries;
extern char history_expansion_char;
extern char history_subst_char;
extern char *history_word_delimiters;
extern char history_comment_char;
extern char *history_no_expand_chars;
extern char *history_search_delimiter_chars;
extern int history_quotes_inhibit_expansion;
extern int history_write_timestamps;
/* Backwards compatibility */
extern int max_input_history;
/* If set, this function is called to decide whether or not a particular
history expansion should be treated as a special case for the calling
application and not expanded. */
extern rl_linebuf_func_t *history_inhibit_expansion_function;
#ifdef __cplusplus
}
#endif
#endif /* !_HISTORY_H_ */
0707010002ca4a000081a40000000000000000000000015424dff7000093aa000001120001001bffffffffffffffff0000002b00000000root/usr/local/include/readline/readline.h /* Readline.h -- the names of functions callable from within readline. */
/* Copyright (C) 1987-2013 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library
for reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#if !defined (_READLINE_H_)
#define _READLINE_H_
#ifdef __cplusplus
extern "C" {
#endif
#if defined (READLINE_LIBRARY)
# include "rlstdc.h"
# include "rltypedefs.h"
# include "keymaps.h"
# include "tilde.h"
#else
# include
# include
# include
# include
#endif
/* Hex-encoded Readline version number. */
#define RL_READLINE_VERSION 0x0603 /* Readline 6.3 */
#define RL_VERSION_MAJOR 6
#define RL_VERSION_MINOR 3
/* Readline data structures. */
/* Maintaining the state of undo. We remember individual deletes and inserts
on a chain of things to do. */
/* The actions that undo knows how to undo. Notice that UNDO_DELETE means
to insert some text, and UNDO_INSERT means to delete some text. I.e.,
the code tells undo what to undo, not how to undo it. */
enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END };
/* What an element of THE_UNDO_LIST looks like. */
typedef struct undo_list {
struct undo_list *next;
int start, end; /* Where the change took place. */
char *text; /* The text to insert, if undoing a delete. */
enum undo_code what; /* Delete, Insert, Begin, End. */
} UNDO_LIST;
/* The current undo list for RL_LINE_BUFFER. */
extern UNDO_LIST *rl_undo_list;
/* The data structure for mapping textual names to code addresses. */
typedef struct _funmap {
const char *name;
rl_command_func_t *function;
} FUNMAP;
extern FUNMAP **funmap;
/* **************************************************************** */
/* */
/* Functions available to bind to key sequences */
/* */
/* **************************************************************** */
/* Bindable commands for numeric arguments. */
extern int rl_digit_argument PARAMS((int, int));
extern int rl_universal_argument PARAMS((int, int));
/* Bindable commands for moving the cursor. */
extern int rl_forward_byte PARAMS((int, int));
extern int rl_forward_char PARAMS((int, int));
extern int rl_forward PARAMS((int, int));
extern int rl_backward_byte PARAMS((int, int));
extern int rl_backward_char PARAMS((int, int));
extern int rl_backward PARAMS((int, int));
extern int rl_beg_of_line PARAMS((int, int));
extern int rl_end_of_line PARAMS((int, int));
extern int rl_forward_word PARAMS((int, int));
extern int rl_backward_word PARAMS((int, int));
extern int rl_refresh_line PARAMS((int, int));
extern int rl_clear_screen PARAMS((int, int));
extern int rl_skip_csi_sequence PARAMS((int, int));
extern int rl_arrow_keys PARAMS((int, int));
/* Bindable commands for inserting and deleting text. */
extern int rl_insert PARAMS((int, int));
extern int rl_quoted_insert PARAMS((int, int));
extern int rl_tab_insert PARAMS((int, int));
extern int rl_newline PARAMS((int, int));
extern int rl_do_lowercase_version PARAMS((int, int));
extern int rl_rubout PARAMS((int, int));
extern int rl_delete PARAMS((int, int));
extern int rl_rubout_or_delete PARAMS((int, int));
extern int rl_delete_horizontal_space PARAMS((int, int));
extern int rl_delete_or_show_completions PARAMS((int, int));
extern int rl_insert_comment PARAMS((int, int));
/* Bindable commands for changing case. */
extern int rl_upcase_word PARAMS((int, int));
extern int rl_downcase_word PARAMS((int, int));
extern int rl_capitalize_word PARAMS((int, int));
/* Bindable commands for transposing characters and words. */
extern int rl_transpose_words PARAMS((int, int));
extern int rl_transpose_chars PARAMS((int, int));
/* Bindable commands for searching within a line. */
extern int rl_char_search PARAMS((int, int));
extern int rl_backward_char_search PARAMS((int, int));
/* Bindable commands for readline's interface to the command history. */
extern int rl_beginning_of_history PARAMS((int, int));
extern int rl_end_of_history PARAMS((int, int));
extern int rl_get_next_history PARAMS((int, int));
extern int rl_get_previous_history PARAMS((int, int));
/* Bindable commands for managing the mark and region. */
extern int rl_set_mark PARAMS((int, int));
extern int rl_exchange_point_and_mark PARAMS((int, int));
/* Bindable commands to set the editing mode (emacs or vi). */
extern int rl_vi_editing_mode PARAMS((int, int));
extern int rl_emacs_editing_mode PARAMS((int, int));
/* Bindable commands to change the insert mode (insert or overwrite) */
extern int rl_overwrite_mode PARAMS((int, int));
/* Bindable commands for managing key bindings. */
extern int rl_re_read_init_file PARAMS((int, int));
extern int rl_dump_functions PARAMS((int, int));
extern int rl_dump_macros PARAMS((int, int));
extern int rl_dump_variables PARAMS((int, int));
/* Bindable commands for word completion. */
extern int rl_complete PARAMS((int, int));
extern int rl_possible_completions PARAMS((int, int));
extern int rl_insert_completions PARAMS((int, int));
extern int rl_old_menu_complete PARAMS((int, int));
extern int rl_menu_complete PARAMS((int, int));
extern int rl_backward_menu_complete PARAMS((int, int));
/* Bindable commands for killing and yanking text, and managing the kill ring. */
extern int rl_kill_word PARAMS((int, int));
extern int rl_backward_kill_word PARAMS((int, int));
extern int rl_kill_line PARAMS((int, int));
extern int rl_backward_kill_line PARAMS((int, int));
extern int rl_kill_full_line PARAMS((int, int));
extern int rl_unix_word_rubout PARAMS((int, int));
extern int rl_unix_filename_rubout PARAMS((int, int));
extern int rl_unix_line_discard PARAMS((int, int));
extern int rl_copy_region_to_kill PARAMS((int, int));
extern int rl_kill_region PARAMS((int, int));
extern int rl_copy_forward_word PARAMS((int, int));
extern int rl_copy_backward_word PARAMS((int, int));
extern int rl_yank PARAMS((int, int));
extern int rl_yank_pop PARAMS((int, int));
extern int rl_yank_nth_arg PARAMS((int, int));
extern int rl_yank_last_arg PARAMS((int, int));
/* Not available unless __CYGWIN__ is defined. */
#ifdef __CYGWIN__
extern int rl_paste_from_clipboard PARAMS((int, int));
#endif
/* Bindable commands for incremental searching. */
extern int rl_reverse_search_history PARAMS((int, int));
extern int rl_forward_search_history PARAMS((int, int));
/* Bindable keyboard macro commands. */
extern int rl_start_kbd_macro PARAMS((int, int));
extern int rl_end_kbd_macro PARAMS((int, int));
extern int rl_call_last_kbd_macro PARAMS((int, int));
extern int rl_print_last_kbd_macro PARAMS((int, int));
/* Bindable undo commands. */
extern int rl_revert_line PARAMS((int, int));
extern int rl_undo_command PARAMS((int, int));
/* Bindable tilde expansion commands. */
extern int rl_tilde_expand PARAMS((int, int));
/* Bindable terminal control commands. */
extern int rl_restart_output PARAMS((int, int));
extern int rl_stop_output PARAMS((int, int));
/* Miscellaneous bindable commands. */
extern int rl_abort PARAMS((int, int));
extern int rl_tty_status PARAMS((int, int));
/* Bindable commands for incremental and non-incremental history searching. */
extern int rl_history_search_forward PARAMS((int, int));
extern int rl_history_search_backward PARAMS((int, int));
extern int rl_history_substr_search_forward PARAMS((int, int));
extern int rl_history_substr_search_backward PARAMS((int, int));
extern int rl_noninc_forward_search PARAMS((int, int));
extern int rl_noninc_reverse_search PARAMS((int, int));
extern int rl_noninc_forward_search_again PARAMS((int, int));
extern int rl_noninc_reverse_search_again PARAMS((int, int));
/* Bindable command used when inserting a matching close character. */
extern int rl_insert_close PARAMS((int, int));
/* Not available unless READLINE_CALLBACKS is defined. */
extern void rl_callback_handler_install PARAMS((const char *, rl_vcpfunc_t *));
extern void rl_callback_read_char PARAMS((void));
extern void rl_callback_handler_remove PARAMS((void));
/* Things for vi mode. Not available unless readline is compiled -DVI_MODE. */
/* VI-mode bindable commands. */
extern int rl_vi_redo PARAMS((int, int));
extern int rl_vi_undo PARAMS((int, int));
extern int rl_vi_yank_arg PARAMS((int, int));
extern int rl_vi_fetch_history PARAMS((int, int));
extern int rl_vi_search_again PARAMS((int, int));
extern int rl_vi_search PARAMS((int, int));
extern int rl_vi_complete PARAMS((int, int));
extern int rl_vi_tilde_expand PARAMS((int, int));
extern int rl_vi_prev_word PARAMS((int, int));
extern int rl_vi_next_word PARAMS((int, int));
extern int rl_vi_end_word PARAMS((int, int));
extern int rl_vi_insert_beg PARAMS((int, int));
extern int rl_vi_append_mode PARAMS((int, int));
extern int rl_vi_append_eol PARAMS((int, int));
extern int rl_vi_eof_maybe PARAMS((int, int));
extern int rl_vi_insertion_mode PARAMS((int, int));
extern int rl_vi_insert_mode PARAMS((int, int));
extern int rl_vi_movement_mode PARAMS((int, int));
extern int rl_vi_arg_digit PARAMS((int, int));
extern int rl_vi_change_case PARAMS((int, int));
extern int rl_vi_put PARAMS((int, int));
extern int rl_vi_column PARAMS((int, int));
extern int rl_vi_delete_to PARAMS((int, int));
extern int rl_vi_change_to PARAMS((int, int));
extern int rl_vi_yank_to PARAMS((int, int));
extern int rl_vi_rubout PARAMS((int, int));
extern int rl_vi_delete PARAMS((int, int));
extern int rl_vi_back_to_indent PARAMS((int, int));
extern int rl_vi_first_print PARAMS((int, int));
extern int rl_vi_char_search PARAMS((int, int));
extern int rl_vi_match PARAMS((int, int));
extern int rl_vi_change_char PARAMS((int, int));
extern int rl_vi_subst PARAMS((int, int));
extern int rl_vi_overstrike PARAMS((int, int));
extern int rl_vi_overstrike_delete PARAMS((int, int));
extern int rl_vi_replace PARAMS((int, int));
extern int rl_vi_set_mark PARAMS((int, int));
extern int rl_vi_goto_mark PARAMS((int, int));
/* VI-mode utility functions. */
extern int rl_vi_check PARAMS((void));
extern int rl_vi_domove PARAMS((int, int *));
extern int rl_vi_bracktype PARAMS((int));
extern void rl_vi_start_inserting PARAMS((int, int, int));
/* VI-mode pseudo-bindable commands, used as utility functions. */
extern int rl_vi_fWord PARAMS((int, int));
extern int rl_vi_bWord PARAMS((int, int));
extern int rl_vi_eWord PARAMS((int, int));
extern int rl_vi_fword PARAMS((int, int));
extern int rl_vi_bword PARAMS((int, int));
extern int rl_vi_eword PARAMS((int, int));
/* **************************************************************** */
/* */
/* Well Published Functions */
/* */
/* **************************************************************** */
/* Readline functions. */
/* Read a line of input. Prompt with PROMPT. A NULL PROMPT means none. */
extern char *readline PARAMS((const char *));
extern int rl_set_prompt PARAMS((const char *));
extern int rl_expand_prompt PARAMS((char *));
extern int rl_initialize PARAMS((void));
/* Undocumented; unused by readline */
extern int rl_discard_argument PARAMS((void));
/* Utility functions to bind keys to readline commands. */
extern int rl_add_defun PARAMS((const char *, rl_command_func_t *, int));
extern int rl_bind_key PARAMS((int, rl_command_func_t *));
extern int rl_bind_key_in_map PARAMS((int, rl_command_func_t *, Keymap));
extern int rl_unbind_key PARAMS((int));
extern int rl_unbind_key_in_map PARAMS((int, Keymap));
extern int rl_bind_key_if_unbound PARAMS((int, rl_command_func_t *));
extern int rl_bind_key_if_unbound_in_map PARAMS((int, rl_command_func_t *, Keymap));
extern int rl_unbind_function_in_map PARAMS((rl_command_func_t *, Keymap));
extern int rl_unbind_command_in_map PARAMS((const char *, Keymap));
extern int rl_bind_keyseq PARAMS((const char *, rl_command_func_t *));
extern int rl_bind_keyseq_in_map PARAMS((const char *, rl_command_func_t *, Keymap));
extern int rl_bind_keyseq_if_unbound PARAMS((const char *, rl_command_func_t *));
extern int rl_bind_keyseq_if_unbound_in_map PARAMS((const char *, rl_command_func_t *, Keymap));
extern int rl_generic_bind PARAMS((int, const char *, char *, Keymap));
extern char *rl_variable_value PARAMS((const char *));
extern int rl_variable_bind PARAMS((const char *, const char *));
/* Backwards compatibility, use rl_bind_keyseq_in_map instead. */
extern int rl_set_key PARAMS((const char *, rl_command_func_t *, Keymap));
/* Backwards compatibility, use rl_generic_bind instead. */
extern int rl_macro_bind PARAMS((const char *, const char *, Keymap));
/* Undocumented in the texinfo manual; not really useful to programs. */
extern int rl_translate_keyseq PARAMS((const char *, char *, int *));
extern char *rl_untranslate_keyseq PARAMS((int));
extern rl_command_func_t *rl_named_function PARAMS((const char *));
extern rl_command_func_t *rl_function_of_keyseq PARAMS((const char *, Keymap, int *));
extern void rl_list_funmap_names PARAMS((void));
extern char **rl_invoking_keyseqs_in_map PARAMS((rl_command_func_t *, Keymap));
extern char **rl_invoking_keyseqs PARAMS((rl_command_func_t *));
extern void rl_function_dumper PARAMS((int));
extern void rl_macro_dumper PARAMS((int));
extern void rl_variable_dumper PARAMS((int));
extern int rl_read_init_file PARAMS((const char *));
extern int rl_parse_and_bind PARAMS((char *));
/* Functions for manipulating keymaps. */
extern Keymap rl_make_bare_keymap PARAMS((void));
extern Keymap rl_copy_keymap PARAMS((Keymap));
extern Keymap rl_make_keymap PARAMS((void));
extern void rl_discard_keymap PARAMS((Keymap));
extern void rl_free_keymap PARAMS((Keymap));
extern Keymap rl_get_keymap_by_name PARAMS((const char *));
extern char *rl_get_keymap_name PARAMS((Keymap));
extern void rl_set_keymap PARAMS((Keymap));
extern Keymap rl_get_keymap PARAMS((void));
/* Undocumented; used internally only. */
extern void rl_set_keymap_from_edit_mode PARAMS((void));
extern char *rl_get_keymap_name_from_edit_mode PARAMS((void));
/* Functions for manipulating the funmap, which maps command names to functions. */
extern int rl_add_funmap_entry PARAMS((const char *, rl_command_func_t *));
extern const char **rl_funmap_names PARAMS((void));
/* Undocumented, only used internally -- there is only one funmap, and this
function may be called only once. */
extern void rl_initialize_funmap PARAMS((void));
/* Utility functions for managing keyboard macros. */
extern void rl_push_macro_input PARAMS((char *));
/* Functions for undoing, from undo.c */
extern void rl_add_undo PARAMS((enum undo_code, int, int, char *));
extern void rl_free_undo_list PARAMS((void));
extern int rl_do_undo PARAMS((void));
extern int rl_begin_undo_group PARAMS((void));
extern int rl_end_undo_group PARAMS((void));
extern int rl_modifying PARAMS((int, int));
/* Functions for redisplay. */
extern void rl_redisplay PARAMS((void));
extern int rl_on_new_line PARAMS((void));
extern int rl_on_new_line_with_prompt PARAMS((void));
extern int rl_forced_update_display PARAMS((void));
extern int rl_clear_message PARAMS((void));
extern int rl_reset_line_state PARAMS((void));
extern int rl_crlf PARAMS((void));
#if defined (USE_VARARGS) && defined (PREFER_STDARG)
extern int rl_message (const char *, ...) __attribute__((__format__ (printf, 1, 2)));
#else
extern int rl_message ();
#endif
extern int rl_show_char PARAMS((int));
/* Undocumented in texinfo manual. */
extern int rl_character_len PARAMS((int, int));
/* Save and restore internal prompt redisplay information. */
extern void rl_save_prompt PARAMS((void));
extern void rl_restore_prompt PARAMS((void));
/* Modifying text. */
extern void rl_replace_line PARAMS((const char *, int));
extern int rl_insert_text PARAMS((const char *));
extern int rl_delete_text PARAMS((int, int));
extern int rl_kill_text PARAMS((int, int));
extern char *rl_copy_text PARAMS((int, int));
/* Terminal and tty mode management. */
extern void rl_prep_terminal PARAMS((int));
extern void rl_deprep_terminal PARAMS((void));
extern void rl_tty_set_default_bindings PARAMS((Keymap));
extern void rl_tty_unset_default_bindings PARAMS((Keymap));
extern int rl_reset_terminal PARAMS((const char *));
extern void rl_resize_terminal PARAMS((void));
extern void rl_set_screen_size PARAMS((int, int));
extern void rl_get_screen_size PARAMS((int *, int *));
extern void rl_reset_screen_size PARAMS((void));
extern char *rl_get_termcap PARAMS((const char *));
/* Functions for character input. */
extern int rl_stuff_char PARAMS((int));
extern int rl_execute_next PARAMS((int));
extern int rl_clear_pending_input PARAMS((void));
extern int rl_read_key PARAMS((void));
extern int rl_getc PARAMS((FILE *));
extern int rl_set_keyboard_input_timeout PARAMS((int));
/* `Public' utility functions . */
extern void rl_extend_line_buffer PARAMS((int));
extern int rl_ding PARAMS((void));
extern int rl_alphabetic PARAMS((int));
extern void rl_free PARAMS((void *));
/* Readline signal handling, from signals.c */
extern int rl_set_signals PARAMS((void));
extern int rl_clear_signals PARAMS((void));
extern void rl_cleanup_after_signal PARAMS((void));
extern void rl_reset_after_signal PARAMS((void));
extern void rl_free_line_state PARAMS((void));
extern void rl_echo_signal_char PARAMS((int));
extern int rl_set_paren_blink_timeout PARAMS((int));
/* History management functions. */
extern void rl_clear_history PARAMS((void));
/* Undocumented. */
extern int rl_maybe_save_line PARAMS((void));
extern int rl_maybe_unsave_line PARAMS((void));
extern int rl_maybe_replace_line PARAMS((void));
/* Completion functions. */
extern int rl_complete_internal PARAMS((int));
extern void rl_display_match_list PARAMS((char **, int, int));
extern char **rl_completion_matches PARAMS((const char *, rl_compentry_func_t *));
extern char *rl_username_completion_function PARAMS((const char *, int));
extern char *rl_filename_completion_function PARAMS((const char *, int));
extern int rl_completion_mode PARAMS((rl_command_func_t *));
#if 0
/* Backwards compatibility (compat.c). These will go away sometime. */
extern void free_undo_list PARAMS((void));
extern int maybe_save_line PARAMS((void));
extern int maybe_unsave_line PARAMS((void));
extern int maybe_replace_line PARAMS((void));
extern int ding PARAMS((void));
extern int alphabetic PARAMS((int));
extern int crlf PARAMS((void));
extern char **completion_matches PARAMS((char *, rl_compentry_func_t *));
extern char *username_completion_function PARAMS((const char *, int));
extern char *filename_completion_function PARAMS((const char *, int));
#endif
/* **************************************************************** */
/* */
/* Well Published Variables */
/* */
/* **************************************************************** */
/* The version of this incarnation of the readline library. */
extern const char *rl_library_version; /* e.g., "4.2" */
extern int rl_readline_version; /* e.g., 0x0402 */
/* True if this is real GNU readline. */
extern int rl_gnu_readline_p;
/* Flags word encapsulating the current readline state. */
extern int rl_readline_state;
/* Says which editing mode readline is currently using. 1 means emacs mode;
0 means vi mode. */
extern int rl_editing_mode;
/* Insert or overwrite mode for emacs mode. 1 means insert mode; 0 means
overwrite mode. Reset to insert mode on each input line. */
extern int rl_insert_mode;
/* The name of the calling program. You should initialize this to
whatever was in argv[0]. It is used when parsing conditionals. */
extern const char *rl_readline_name;
/* The prompt readline uses. This is set from the argument to
readline (), and should not be assigned to directly. */
extern char *rl_prompt;
/* The prompt string that is actually displayed by rl_redisplay. Public so
applications can more easily supply their own redisplay functions. */
extern char *rl_display_prompt;
/* The line buffer that is in use. */
extern char *rl_line_buffer;
/* The location of point, and end. */
extern int rl_point;
extern int rl_end;
/* The mark, or saved cursor position. */
extern int rl_mark;
/* Flag to indicate that readline has finished with the current input
line and should return it. */
extern int rl_done;
/* If set to a character value, that will be the next keystroke read. */
extern int rl_pending_input;
/* Non-zero if we called this function from _rl_dispatch(). It's present
so functions can find out whether they were called from a key binding
or directly from an application. */
extern int rl_dispatching;
/* Non-zero if the user typed a numeric argument before executing the
current function. */
extern int rl_explicit_arg;
/* The current value of the numeric argument specified by the user. */
extern int rl_numeric_arg;
/* The address of the last command function Readline executed. */
extern rl_command_func_t *rl_last_func;
/* The name of the terminal to use. */
extern const char *rl_terminal_name;
/* The input and output streams. */
extern FILE *rl_instream;
extern FILE *rl_outstream;
/* If non-zero, Readline gives values of LINES and COLUMNS from the environment
greater precedence than values fetched from the kernel when computing the
screen dimensions. */
extern int rl_prefer_env_winsize;
/* If non-zero, then this is the address of a function to call just
before readline_internal () prints the first prompt. */
extern rl_hook_func_t *rl_startup_hook;
/* If non-zero, this is the address of a function to call just before
readline_internal_setup () returns and readline_internal starts
reading input characters. */
extern rl_hook_func_t *rl_pre_input_hook;
/* The address of a function to call periodically while Readline is
awaiting character input, or NULL, for no event handling. */
extern rl_hook_func_t *rl_event_hook;
/* The address of a function to call if a read is interrupted by a signal. */
extern rl_hook_func_t *rl_signal_event_hook;
/* The address of a function to call if Readline needs to know whether or not
there is data available from the current input source. */
extern rl_hook_func_t *rl_input_available_hook;
/* The address of the function to call to fetch a character from the current
Readline input stream */
extern rl_getc_func_t *rl_getc_function;
extern rl_voidfunc_t *rl_redisplay_function;
extern rl_vintfunc_t *rl_prep_term_function;
extern rl_voidfunc_t *rl_deprep_term_function;
/* Dispatch variables. */
extern Keymap rl_executing_keymap;
extern Keymap rl_binding_keymap;
extern int rl_executing_key;
extern char *rl_executing_keyseq;
extern int rl_key_sequence_length;
/* Display variables. */
/* If non-zero, readline will erase the entire line, including any prompt,
if the only thing typed on an otherwise-blank line is something bound to
rl_newline. */
extern int rl_erase_empty_line;
/* If non-zero, the application has already printed the prompt (rl_prompt)
before calling readline, so readline should not output it the first time
redisplay is done. */
extern int rl_already_prompted;
/* A non-zero value means to read only this many characters rather than
up to a character bound to accept-line. */
extern int rl_num_chars_to_read;
/* The text of a currently-executing keyboard macro. */
extern char *rl_executing_macro;
/* Variables to control readline signal handling. */
/* If non-zero, readline will install its own signal handlers for
SIGINT, SIGTERM, SIGQUIT, SIGALRM, SIGTSTP, SIGTTIN, and SIGTTOU. */
extern int rl_catch_signals;
/* If non-zero, readline will install a signal handler for SIGWINCH
that also attempts to call any calling application's SIGWINCH signal
handler. Note that the terminal is not cleaned up before the
application's signal handler is called; use rl_cleanup_after_signal()
to do that. */
extern int rl_catch_sigwinch;
/* If non-zero, the readline SIGWINCH handler will modify LINES and
COLUMNS in the environment. */
extern int rl_change_environment;
/* Completion variables. */
/* Pointer to the generator function for completion_matches ().
NULL means to use rl_filename_completion_function (), the default
filename completer. */
extern rl_compentry_func_t *rl_completion_entry_function;
/* Optional generator for menu completion. Default is
rl_completion_entry_function (rl_filename_completion_function). */
extern rl_compentry_func_t *rl_menu_completion_entry_function;
/* If rl_ignore_some_completions_function is non-NULL it is the address
of a function to call after all of the possible matches have been
generated, but before the actual completion is done to the input line.
The function is called with one argument; a NULL terminated array
of (char *). If your function removes any of the elements, they
must be free()'ed. */
extern rl_compignore_func_t *rl_ignore_some_completions_function;
/* Pointer to alternative function to create matches.
Function is called with TEXT, START, and END.
START and END are indices in RL_LINE_BUFFER saying what the boundaries
of TEXT are.
If this function exists and returns NULL then call the value of
rl_completion_entry_function to try to match, otherwise use the
array of strings returned. */
extern rl_completion_func_t *rl_attempted_completion_function;
/* The basic list of characters that signal a break between words for the
completer routine. The initial contents of this variable is what
breaks words in the shell, i.e. "n\"\\'`@$>". */
extern const char *rl_basic_word_break_characters;
/* The list of characters that signal a break between words for
rl_complete_internal. The default list is the contents of
rl_basic_word_break_characters. */
extern /*const*/ char *rl_completer_word_break_characters;
/* Hook function to allow an application to set the completion word
break characters before readline breaks up the line. Allows
position-dependent word break characters. */
extern rl_cpvfunc_t *rl_completion_word_break_hook;
/* List of characters which can be used to quote a substring of the line.
Completion occurs on the entire substring, and within the substring
rl_completer_word_break_characters are treated as any other character,
unless they also appear within this list. */
extern const char *rl_completer_quote_characters;
/* List of quote characters which cause a word break. */
extern const char *rl_basic_quote_characters;
/* List of characters that need to be quoted in filenames by the completer. */
extern const char *rl_filename_quote_characters;
/* List of characters that are word break characters, but should be left
in TEXT when it is passed to the completion function. The shell uses
this to help determine what kind of completing to do. */
extern const char *rl_special_prefixes;
/* If non-zero, then this is the address of a function to call when
completing on a directory name. The function is called with
the address of a string (the current directory name) as an arg. It
changes what is displayed when the possible completions are printed
or inserted. The directory completion hook should perform
any necessary dequoting. This function should return 1 if it modifies
the directory name pointer passed as an argument. If the directory
completion hook returns 0, it should not modify the directory name
pointer passed as an argument. */
extern rl_icppfunc_t *rl_directory_completion_hook;
/* If non-zero, this is the address of a function to call when completing
a directory name. This function takes the address of the directory name
to be modified as an argument. Unlike rl_directory_completion_hook, it
only modifies the directory name used in opendir(2), not what is displayed
when the possible completions are printed or inserted. If set, it takes
precedence over rl_directory_completion_hook. The directory rewrite
hook should perform any necessary dequoting. This function has the same
return value properties as the directory_completion_hook.
I'm not happy with how this works yet, so it's undocumented. I'm trying
it in bash to see how well it goes. */
extern rl_icppfunc_t *rl_directory_rewrite_hook;
/* If non-zero, this is the address of a function for the completer to call
before deciding which character to append to a completed name. It should
modify the directory name passed as an argument if appropriate, and return
non-zero if it modifies the name. This should not worry about dequoting
the filename; that has already happened by the time it gets here. */
extern rl_icppfunc_t *rl_filename_stat_hook;
/* If non-zero, this is the address of a function to call when reading
directory entries from the filesystem for completion and comparing
them to the partial word to be completed. The function should
either return its first argument (if no conversion takes place) or
newly-allocated memory. This can, for instance, convert filenames
between character sets for comparison against what's typed at the
keyboard. The returned value is what is added to the list of
matches. The second argument is the length of the filename to be
converted. */
extern rl_dequote_func_t *rl_filename_rewrite_hook;
/* Backwards compatibility with previous versions of readline. */
#define rl_symbolic_link_hook rl_directory_completion_hook
/* If non-zero, then this is the address of a function to call when
completing a word would normally display the list of possible matches.
This function is called instead of actually doing the display.
It takes three arguments: (char **matches, int num_matches, int max_length)
where MATCHES is the array of strings that matched, NUM_MATCHES is the
number of strings in that array, and MAX_LENGTH is the length of the
longest string in that array. */
extern rl_compdisp_func_t *rl_completion_display_matches_hook;
/* Non-zero means that the results of the matches are to be treated
as filenames. This is ALWAYS zero on entry, and can only be changed
within a completion entry finder function. */
extern int rl_filename_completion_desired;
/* Non-zero means that the results of the matches are to be quoted using
double quotes (or an application-specific quoting mechanism) if the
filename contains any characters in rl_word_break_chars. This is
ALWAYS non-zero on entry, and can only be changed within a completion
entry finder function. */
extern int rl_filename_quoting_desired;
/* Set to a function to quote a filename in an application-specific fashion.
Called with the text to quote, the type of match found (single or multiple)
and a pointer to the quoting character to be used, which the function can
reset if desired. */
extern rl_quote_func_t *rl_filename_quoting_function;
/* Function to call to remove quoting characters from a filename. Called
before completion is attempted, so the embedded quotes do not interfere
with matching names in the file system. */
extern rl_dequote_func_t *rl_filename_dequoting_function;
/* Function to call to decide whether or not a word break character is
quoted. If a character is quoted, it does not break words for the
completer. */
extern rl_linebuf_func_t *rl_char_is_quoted_p;
/* Non-zero means to suppress normal filename completion after the
user-specified completion function has been called. */
extern int rl_attempted_completion_over;
/* Set to a character describing the type of completion being attempted by
rl_complete_internal; available for use by application completion
functions. */
extern int rl_completion_type;
/* Set to the last key used to invoke one of the completion functions */
extern int rl_completion_invoking_key;
/* Up to this many items will be displayed in response to a
possible-completions call. After that, we ask the user if she
is sure she wants to see them all. The default value is 100. */
extern int rl_completion_query_items;
/* Character appended to completed words when at the end of the line. The
default is a space. Nothing is added if this is '\0'. */
extern int rl_completion_append_character;
/* If set to non-zero by an application completion function,
rl_completion_append_character will not be appended. */
extern int rl_completion_suppress_append;
/* Set to any quote character readline thinks it finds before any application
completion function is called. */
extern int rl_completion_quote_character;
/* Set to a non-zero value if readline found quoting anywhere in the word to
be completed; set before any application completion function is called. */
extern int rl_completion_found_quote;
/* If non-zero, the completion functions don't append any closing quote.
This is set to 0 by rl_complete_internal and may be changed by an
application-specific completion function. */
extern int rl_completion_suppress_quote;
/* If non-zero, readline will sort the completion matches. On by default. */
extern int rl_sort_completion_matches;
/* If non-zero, a slash will be appended to completed filenames that are
symbolic links to directory names, subject to the value of the
mark-directories variable (which is user-settable). This exists so
that application completion functions can override the user's preference
(set via the mark-symlinked-directories variable) if appropriate.
It's set to the value of _rl_complete_mark_symlink_dirs in
rl_complete_internal before any application-specific completion
function is called, so without that function doing anything, the user's
preferences are honored. */
extern int rl_completion_mark_symlink_dirs;
/* If non-zero, then disallow duplicates in the matches. */
extern int rl_ignore_completion_duplicates;
/* If this is non-zero, completion is (temporarily) inhibited, and the
completion character will be inserted as any other. */
extern int rl_inhibit_completion;
/* Input error; can be returned by (*rl_getc_function) if readline is reading
a top-level command (RL_ISSTATE (RL_STATE_READCMD)). */
#define READERR (-2)
/* Definitions available for use by readline clients. */
#define RL_PROMPT_START_IGNORE '\001'
#define RL_PROMPT_END_IGNORE '\002'
/* Possible values for do_replace argument to rl_filename_quoting_function,
called by rl_complete_internal. */
#define NO_MATCH 0
#define SINGLE_MATCH 1
#define MULT_MATCH 2
/* Possible state values for rl_readline_state */
#define RL_STATE_NONE 0x000000 /* no state; before first call */
#define RL_STATE_INITIALIZING 0x0000001 /* initializing */
#define RL_STATE_INITIALIZED 0x0000002 /* initialization done */
#define RL_STATE_TERMPREPPED 0x0000004 /* terminal is prepped */
#define RL_STATE_READCMD 0x0000008 /* reading a command key */
#define RL_STATE_METANEXT 0x0000010 /* reading input after ESC */
#define RL_STATE_DISPATCHING 0x0000020 /* dispatching to a command */
#define RL_STATE_MOREINPUT 0x0000040 /* reading more input in a command function */
#define RL_STATE_ISEARCH 0x0000080 /* doing incremental search */
#define RL_STATE_NSEARCH 0x0000100 /* doing non-inc search */
#define RL_STATE_SEARCH 0x0000200 /* doing a history search */
#define RL_STATE_NUMERICARG 0x0000400 /* reading numeric argument */
#define RL_STATE_MACROINPUT 0x0000800 /* getting input from a macro */
#define RL_STATE_MACRODEF 0x0001000 /* defining keyboard macro */
#define RL_STATE_OVERWRITE 0x0002000 /* overwrite mode */
#define RL_STATE_COMPLETING 0x0004000 /* doing completion */
#define RL_STATE_SIGHANDLER 0x0008000 /* in readline sighandler */
#define RL_STATE_UNDOING 0x0010000 /* doing an undo */
#define RL_STATE_INPUTPENDING 0x0020000 /* rl_execute_next called */
#define RL_STATE_TTYCSAVED 0x0040000 /* tty special chars saved */
#define RL_STATE_CALLBACK 0x0080000 /* using the callback interface */
#define RL_STATE_VIMOTION 0x0100000 /* reading vi motion arg */
#define RL_STATE_MULTIKEY 0x0200000 /* reading multiple-key command */
#define RL_STATE_VICMDONCE 0x0400000 /* entered vi command mode at least once */
#define RL_STATE_REDISPLAYING 0x0800000 /* updating terminal display */
#define RL_STATE_DONE 0x1000000 /* done; accepted line */
#define RL_SETSTATE(x) (rl_readline_state |= (x))
#define RL_UNSETSTATE(x) (rl_readline_state &= ~(x))
#define RL_ISSTATE(x) (rl_readline_state & (x))
struct readline_state {
/* line state */
int point;
int end;
int mark;
char *buffer;
int buflen;
UNDO_LIST *ul;
char *prompt;
/* global state */
int rlstate;
int done;
Keymap kmap;
/* input state */
rl_command_func_t *lastfunc;
int insmode;
int edmode;
int kseqlen;
FILE *inf;
FILE *outf;
int pendingin;
char *macro;
/* signal state */
int catchsigs;
int catchsigwinch;
/* search state */
/* completion state */
/* options state */
/* reserved for future expansion, so the struct size doesn't change */
char reserved[64];
};
extern int rl_save_state PARAMS((struct readline_state *));
extern int rl_restore_state PARAMS((struct readline_state *));
#ifdef __cplusplus
}
#endif
#endif /* _READLINE_H_ */
0707010002ca47000081a40000000000000000000000015424dff7000011e1000001120001001bffffffffffffffff0000002b00000000root/usr/local/include/readline/chardefs.h /* chardefs.h -- Character definitions for readline. */
/* Copyright (C) 1994-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library
for reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#ifndef _CHARDEFS_H_
#define _CHARDEFS_H_
#include
#if defined (HAVE_CONFIG_H)
# if defined (HAVE_STRING_H)
# if ! defined (STDC_HEADERS) && defined (HAVE_MEMORY_H)
# include
# endif
# include
# endif /* HAVE_STRING_H */
# if defined (HAVE_STRINGS_H)
# include
# endif /* HAVE_STRINGS_H */
#else
# include
#endif /* !HAVE_CONFIG_H */
#ifndef whitespace
#define whitespace(c) (((c) == ' ') || ((c) == '\t'))
#endif
#ifdef CTRL
# undef CTRL
#endif
#ifdef UNCTRL
# undef UNCTRL
#endif
/* Some character stuff. */
#define control_character_threshold 0x020 /* Smaller than this is control. */
#define control_character_mask 0x1f /* 0x20 - 1 */
#define meta_character_threshold 0x07f /* Larger than this is Meta. */
#define control_character_bit 0x40 /* 0x000000, must be off. */
#define meta_character_bit 0x080 /* x0000000, must be on. */
#define largest_char 255 /* Largest character value. */
#define CTRL_CHAR(c) ((c) < control_character_threshold && (((c) & 0x80) == 0))
#define META_CHAR(c) ((c) > meta_character_threshold && (c) <= largest_char)
#define CTRL(c) ((c) & control_character_mask)
#define META(c) ((c) | meta_character_bit)
#define UNMETA(c) ((c) & (~meta_character_bit))
#define UNCTRL(c) _rl_to_upper(((c)|control_character_bit))
#if defined STDC_HEADERS || (!defined (isascii) && !defined (HAVE_ISASCII))
# define IN_CTYPE_DOMAIN(c) 1
#else
# define IN_CTYPE_DOMAIN(c) isascii(c)
#endif
#if !defined (isxdigit) && !defined (HAVE_ISXDIGIT) && !defined (__cplusplus)
# define isxdigit(c) (isdigit((c)) || ((c) >= 'a' && (c) <= 'f') || ((c) >= 'A' && (c) <= 'F'))
#endif
#if defined (CTYPE_NON_ASCII)
# define NON_NEGATIVE(c) 1
#else
# define NON_NEGATIVE(c) ((unsigned char)(c) == (c))
#endif
/* Some systems define these; we want our definitions. */
#undef ISPRINT
/* Beware: these only work with single-byte ASCII characters. */
#define ISALNUM(c) (IN_CTYPE_DOMAIN (c) && isalnum (c))
#define ISALPHA(c) (IN_CTYPE_DOMAIN (c) && isalpha (c))
#define ISDIGIT(c) (IN_CTYPE_DOMAIN (c) && isdigit (c))
#define ISLOWER(c) (IN_CTYPE_DOMAIN (c) && islower (c))
#define ISPRINT(c) (IN_CTYPE_DOMAIN (c) && isprint (c))
#define ISUPPER(c) (IN_CTYPE_DOMAIN (c) && isupper (c))
#define ISXDIGIT(c) (IN_CTYPE_DOMAIN (c) && isxdigit (c))
#define _rl_lowercase_p(c) (NON_NEGATIVE(c) && ISLOWER(c))
#define _rl_uppercase_p(c) (NON_NEGATIVE(c) && ISUPPER(c))
#define _rl_digit_p(c) ((c) >= '0' && (c) <= '9')
#define _rl_pure_alphabetic(c) (NON_NEGATIVE(c) && ISALPHA(c))
#define ALPHABETIC(c) (NON_NEGATIVE(c) && ISALNUM(c))
#ifndef _rl_to_upper
# define _rl_to_upper(c) (_rl_lowercase_p(c) ? toupper((unsigned char)c) : (c))
# define _rl_to_lower(c) (_rl_uppercase_p(c) ? tolower((unsigned char)c) : (c))
#endif
#ifndef _rl_digit_value
# define _rl_digit_value(x) ((x) - '0')
#endif
#ifndef _rl_isident
# define _rl_isident(c) (ISALNUM(c) || (c) == '_')
#endif
#ifndef ISOCTAL
# define ISOCTAL(c) ((c) >= '0' && (c) <= '7')
#endif
#define OCTVALUE(c) ((c) - '0')
#define HEXVALUE(c) \
(((c) >= 'a' && (c) <= 'f') \
? (c)-'a'+10 \
: (c) >= 'A' && (c) <= 'F' ? (c)-'A'+10 : (c)-'0')
#ifndef NEWLINE
#define NEWLINE '\n'
#endif
#ifndef RETURN
#define RETURN CTRL('M')
#endif
#ifndef RUBOUT
#define RUBOUT 0x7f
#endif
#ifndef TAB
#define TAB '\t'
#endif
#ifdef ABORT_CHAR
#undef ABORT_CHAR
#endif
#define ABORT_CHAR CTRL('G')
#ifdef PAGE
#undef PAGE
#endif
#define PAGE CTRL('L')
#ifdef SPACE
#undef SPACE
#endif
#define SPACE ' ' /* XXX - was 0x20 */
#ifdef ESC
#undef ESC
#endif
#define ESC CTRL('[')
#endif /* _CHARDEFS_H_ */
0707010002ca4b000081a40000000000000000000000015424dff700000986000001120001001bffffffffffffffff0000002900000000root/usr/local/include/readline/rlconf.h /* rlconf.h -- readline configuration definitions */
/* Copyright (C) 1992-2012 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library
for reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#if !defined (_RLCONF_H_)
#define _RLCONF_H_
/* Define this if you want the vi-mode editing available. */
#define VI_MODE
/* Define this to get an indication of file type when listing completions. */
#define VISIBLE_STATS
/* Define this to get support for colors when listing completions and in
other places. */
#define COLOR_SUPPORT
/* This definition is needed by readline.c, rltty.c, and signals.c. */
/* If on, then readline handles signals in a way that doesn't suck. */
#define HANDLE_SIGNALS
/* Ugly but working hack for binding prefix meta. */
#define PREFIX_META_HACK
/* The next-to-last-ditch effort file name for a user-specific init file. */
#define DEFAULT_INPUTRC "~/.inputrc"
/* The ultimate last-ditch filenname for an init file -- system-wide. */
#define SYS_INPUTRC "/etc/inputrc"
/* If defined, expand tabs to spaces. */
#define DISPLAY_TABS
/* If defined, use the terminal escape sequence to move the cursor forward
over a character when updating the line rather than rewriting it. */
/* #define HACK_TERMCAP_MOTION */
/* The string inserted by the `insert comment' command. */
#define RL_COMMENT_BEGIN_DEFAULT "#"
/* Define this if you want code that allows readline to be used in an
X `callback' style. */
#define READLINE_CALLBACKS
/* Define this if you want the cursor to indicate insert or overwrite mode. */
/* #define CURSOR_MODE */
/* Define this if you want to enable code that talks to the Linux kernel
tty auditing system. */
#define ENABLE_TTY_AUDIT_SUPPORT
#endif /* _RLCONF_H_ */
0707010002ca4e000081a40000000000000000000000015424dff700000be6000001120001001bffffffffffffffff0000002800000000root/usr/local/include/readline/tilde.h /* tilde.h: Externally available variables and function in libtilde.a. */
/* Copyright (C) 1992-2009 Free Software Foundation, Inc.
This file contains the Readline Library (Readline), a set of
routines for providing Emacs style line input to programs that ask
for it.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#if !defined (_TILDE_H_)
# define _TILDE_H_
#ifdef __cplusplus
extern "C" {
#endif
/* A function can be defined using prototypes and compile on both ANSI C
and traditional C compilers with something like this:
extern char *func PARAMS((char *, char *, int)); */
#if !defined (PARAMS)
# if defined (__STDC__) || defined (__GNUC__) || defined (__cplusplus)
# define PARAMS(protos) protos
# else
# define PARAMS(protos) ()
# endif
#endif
typedef char *tilde_hook_func_t PARAMS((char *));
/* If non-null, this contains the address of a function that the application
wants called before trying the standard tilde expansions. The function
is called with the text sans tilde, and returns a malloc()'ed string
which is the expansion, or a NULL pointer if the expansion fails. */
extern tilde_hook_func_t *tilde_expansion_preexpansion_hook;
/* If non-null, this contains the address of a function to call if the
standard meaning for expanding a tilde fails. The function is called
with the text (sans tilde, as in "foo"), and returns a malloc()'ed string
which is the expansion, or a NULL pointer if there is no expansion. */
extern tilde_hook_func_t *tilde_expansion_failure_hook;
/* When non-null, this is a NULL terminated array of strings which
are duplicates for a tilde prefix. Bash uses this to expand
`=~' and `:~'. */
extern char **tilde_additional_prefixes;
/* When non-null, this is a NULL terminated array of strings which match
the end of a username, instead of just "/". Bash sets this to
`:' and `=~'. */
extern char **tilde_additional_suffixes;
/* Return a new string which is the result of tilde expanding STRING. */
extern char *tilde_expand PARAMS((const char *));
/* Do the work of tilde expansion on FILENAME. FILENAME starts with a
tilde. If there is no expansion, call tilde_expansion_failure_hook. */
extern char *tilde_expand_word PARAMS((const char *));
/* Find the portion of the string beginning with ~ that should be expanded. */
extern char *tilde_find_word PARAMS((const char *, int, int *));
#ifdef __cplusplus
}
#endif
#endif /* _TILDE_H_ */
0707010002ca49000081a40000000000000000000000015424dff700000c5b000001120001001bffffffffffffffff0000002a00000000root/usr/local/include/readline/keymaps.h /* keymaps.h -- Manipulation of readline keymaps. */
/* Copyright (C) 1987, 1989, 1992 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library
for reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#ifndef _KEYMAPS_H_
#define _KEYMAPS_H_
#ifdef __cplusplus
extern "C" {
#endif
#if defined (READLINE_LIBRARY)
# include "rlstdc.h"
# include "chardefs.h"
# include "rltypedefs.h"
#else
# include
# include
# include
#endif
/* A keymap contains one entry for each key in the ASCII set.
Each entry consists of a type and a pointer.
FUNCTION is the address of a function to run, or the
address of a keymap to indirect through.
TYPE says which kind of thing FUNCTION is. */
typedef struct _keymap_entry {
char type;
rl_command_func_t *function;
} KEYMAP_ENTRY;
/* This must be large enough to hold bindings for all of the characters
in a desired character set (e.g, 128 for ASCII, 256 for ISO Latin-x,
and so on) plus one for subsequence matching. */
#define KEYMAP_SIZE 257
#define ANYOTHERKEY KEYMAP_SIZE-1
typedef KEYMAP_ENTRY KEYMAP_ENTRY_ARRAY[KEYMAP_SIZE];
typedef KEYMAP_ENTRY *Keymap;
/* The values that TYPE can have in a keymap entry. */
#define ISFUNC 0
#define ISKMAP 1
#define ISMACR 2
extern KEYMAP_ENTRY_ARRAY emacs_standard_keymap, emacs_meta_keymap, emacs_ctlx_keymap;
extern KEYMAP_ENTRY_ARRAY vi_insertion_keymap, vi_movement_keymap;
/* Return a new, empty keymap.
Free it with free() when you are done. */
extern Keymap rl_make_bare_keymap PARAMS((void));
/* Return a new keymap which is a copy of MAP. */
extern Keymap rl_copy_keymap PARAMS((Keymap));
/* Return a new keymap with the printing characters bound to rl_insert,
the lowercase Meta characters bound to run their equivalents, and
the Meta digits bound to produce numeric arguments. */
extern Keymap rl_make_keymap PARAMS((void));
/* Free the storage associated with a keymap. */
extern void rl_discard_keymap PARAMS((Keymap));
/* These functions actually appear in bind.c */
/* Return the keymap corresponding to a given name. Names look like
`emacs' or `emacs-meta' or `vi-insert'. */
extern Keymap rl_get_keymap_by_name PARAMS((const char *));
/* Return the current keymap. */
extern Keymap rl_get_keymap PARAMS((void));
/* Set the current keymap to MAP. */
extern void rl_set_keymap PARAMS((Keymap));
#ifdef __cplusplus
}
#endif
#endif /* _KEYMAPS_H_ */
0707010002ca4c000081a40000000000000000000000015424dff70000072b000001120001001bffffffffffffffff0000002900000000root/usr/local/include/readline/rlstdc.h /* stdc.h -- macros to make source compile on both ANSI C and K&R C compilers. */
/* Copyright (C) 1993-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library
for reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#if !defined (_RL_STDC_H_)
#define _RL_STDC_H_
/* Adapted from BSD /usr/include/sys/cdefs.h. */
/* A function can be defined using prototypes and compile on both ANSI C
and traditional C compilers with something like this:
extern char *func PARAMS((char *, char *, int)); */
#if !defined (PARAMS)
# if defined (__STDC__) || defined (__GNUC__) || defined (__cplusplus)
# define PARAMS(protos) protos
# else
# define PARAMS(protos) ()
# endif
#endif
#ifndef __attribute__
# if __GNUC__ < 2 || (__GNUC__ == 2 && __GNUC_MINOR__ < 8)
# define __attribute__(x)
# endif
#endif
/* Moved from config.h.in because readline.h:rl_message depends on these
defines. */
#if defined (__STDC__) && defined (HAVE_STDARG_H)
# define PREFER_STDARG
# define USE_VARARGS
#else
# if defined (HAVE_VARARGS_H)
# define PREFER_VARARGS
# define USE_VARARGS
# endif
#endif
#endif /* !_RL_STDC_H_ */
0707010002ca54000041ed0000000000000000000000065424e06e00000000000001120001001bffffffffffffffff0000001500000000root/usr/local/share 0707010002ca5f000041ed0000000000000000000000035424e06e00000000000001120001001bffffffffffffffff0000001900000000root/usr/local/share/man 0707010002ca60000041ed0000000000000000000000025424e06e00000000000001120001001bffffffffffffffff0000001e00000000root/usr/local/share/man/man3 0707010002ca62000081a40000000000000000000000015424dff70000ad14000001120001001bffffffffffffffff0000002900000000root/usr/local/share/man/man3/readline.3 .\"
.\" MAN PAGE COMMENTS to
.\"
.\" Chet Ramey
.\" Information Network Services
.\" Case Western Reserve University
.\" chet.ramey@case.edu
.\"
.\" Last Change: Mon Jan 6 16:34:55 EST 2014
.\"
.TH READLINE 3 "2014 January 6" "GNU Readline 6.3"
.\"
.\" File Name macro. This used to be `.PN', for Path Name,
.\" but Sun doesn't seem to like that very much.
.\"
.de FN
\fI\|\\$1\|\fP
..
.SH NAME
readline \- get a line from a user with editing
.SH SYNOPSIS
.LP
.nf
.ft B
#include
#include
#include
.ft
.fi
.LP
.nf
\fIchar *\fP
.br
\fBreadline\fP (\fIconst char *prompt\fP);
.fi
.SH COPYRIGHT
.if n Readline is Copyright (C) 1989\-2011 Free Software Foundation, Inc.
.if t Readline is Copyright \(co 1989\-2011 Free Software Foundation, Inc.
.SH DESCRIPTION
.LP
.B readline
will read a line from the terminal
and return it, using
.B prompt
as a prompt. If
.B prompt
is \fBNULL\fP or the empty string, no prompt is issued.
The line returned is allocated with
.IR malloc (3);
the caller must free it when finished. The line returned
has the final newline removed, so only the text of the line
remains.
.LP
.B readline
offers editing capabilities while the user is entering the
line.
By default, the line editing commands
are similar to those of emacs.
A vi\-style line editing interface is also available.
.LP
This manual page describes only the most basic use of \fBreadline\fP.
Much more functionality is available; see
\fIThe GNU Readline Library\fP and \fIThe GNU History Library\fP
for additional information.
.SH RETURN VALUE
.LP
.B readline
returns the text of the line read. A blank line
returns the empty string. If
.B EOF
is encountered while reading a line, and the line is empty,
.B NULL
is returned. If an
.B EOF
is read with a non\-empty line, it is
treated as a newline.
.SH NOTATION
.LP
An Emacs-style notation is used to denote
keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
means Control\-N. Similarly,
.I meta
keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards
without a
.I meta
key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
then the
.I x
key. This makes ESC the \fImeta prefix\fP.
The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
or press the Escape key
then hold the Control key while pressing the
.I x
key.)
.PP
Readline commands may be given numeric
.IR arguments ,
which normally act as a repeat count. Sometimes, however, it is the
sign of the argument that is significant. Passing a negative argument
to a command that acts in the forward direction (e.g., \fBkill\-line\fP)
causes that command to act in a backward direction. Commands whose
behavior with arguments deviates from this are noted.
.PP
When a command is described as \fIkilling\fP text, the text
deleted is saved for possible future retrieval
(\fIyanking\fP). The killed text is saved in a
\fIkill ring\fP. Consecutive kills cause the text to be
accumulated into one unit, which can be yanked all at once.
Commands which do not kill text separate the chunks of text
on the kill ring.
.SH INITIALIZATION FILE
.LP
Readline is customized by putting commands in an initialization
file (the \fIinputrc\fP file).
The name of this file is taken from the value of the
.B INPUTRC
environment variable. If that variable is unset, the default is
.IR ~/.inputrc .
If that file does not exist or cannot be read, the ultimate default is
.IR /etc/inputrc .
When a program which uses the readline library starts up, the
init file is read, and the key bindings and variables are set.
There are only a few basic constructs allowed in the
readline init file. Blank lines are ignored.
Lines beginning with a \fB#\fP are comments.
Lines beginning with a \fB$\fP indicate conditional constructs.
Other lines denote key bindings and variable settings.
Each program using this library may add its own commands
and bindings.
.PP
For example, placing
.RS
.PP
M\-Control\-u: universal\-argument
.RE
or
.RS
C\-Meta\-u: universal\-argument
.RE
.sp
into the
.I inputrc
would make M\-C\-u execute the readline command
.IR universal\-argument .
.PP
The following symbolic character names are recognized while
processing key bindings:
.IR DEL ,
.IR ESC ,
.IR ESCAPE ,
.IR LFD ,
.IR NEWLINE ,
.IR RET ,
.IR RETURN ,
.IR RUBOUT ,
.IR SPACE ,
.IR SPC ,
and
.IR TAB .
.PP
In addition to command names, readline allows keys to be bound
to a string that is inserted when the key is pressed (a \fImacro\fP).
.PP
.SS Key Bindings
.PP
The syntax for controlling key bindings in the
.I inputrc
file is simple. All that is required is the name of the
command or the text of a macro and a key sequence to which
it should be bound. The name may be specified in one of two ways:
as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
prefixes, or as a key sequence.
The name and key sequence are separated by a colon. There can be no
whitespace between the name and the colon.
.PP
When using the form \fBkeyname\fP:\^\fIfunction-name\fP or \fImacro\fP,
.I keyname
is the name of a key spelled out in English. For example:
.sp
.RS
Control\-u: universal\-argument
.br
Meta\-Rubout: backward\-kill\-word
.br
Control\-o: "> output"
.RE
.LP
In the above example,
.I C\-u
is bound to the function
.BR universal\-argument ,
.I M-DEL
is bound to the function
.BR backward\-kill\-word ,
and
.I C\-o
is bound to run the macro
expressed on the right hand side (that is, to insert the text
.if t \f(CW> output\fP
.if n ``> output''
into the line).
.PP
In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
.B keyseq
differs from
.B keyname
above in that strings denoting
an entire key sequence may be specified by placing the sequence
within double quotes. Some GNU Emacs style key escapes can be
used, as in the following example, but the symbolic character names
are not recognized.
.sp
.RS
"\eC\-u": universal\-argument
.br
"\eC\-x\eC\-r": re\-read\-init\-file
.br
"\ee[11~": "Function Key 1"
.RE
.PP
In this example,
.I C-u
is again bound to the function
.BR universal\-argument .
.I "C-x C-r"
is bound to the function
.BR re\-read\-init\-file ,
and
.I "ESC [ 1 1 ~"
is bound to insert the text
.if t \f(CWFunction Key 1\fP.
.if n ``Function Key 1''.
.PP
The full set of GNU Emacs style escape sequences available when specifying
key sequences is
.RS
.PD 0
.TP
.B \eC\-
control prefix
.TP
.B \eM\-
meta prefix
.TP
.B \ee
an escape character
.TP
.B \e\e
backslash
.TP
.B \e"
literal ", a double quote
.TP
.B \e'
literal ', a single quote
.RE
.PD
.PP
In addition to the GNU Emacs style escape sequences, a second
set of backslash escapes is available:
.RS
.PD 0
.TP
.B \ea
alert (bell)
.TP
.B \eb
backspace
.TP
.B \ed
delete
.TP
.B \ef
form feed
.TP
.B \en
newline
.TP
.B \er
carriage return
.TP
.B \et
horizontal tab
.TP
.B \ev
vertical tab
.TP
.B \e\fInnn\fP
the eight-bit character whose value is the octal value \fInnn\fP
(one to three digits)
.TP
.B \ex\fIHH\fP
the eight-bit character whose value is the hexadecimal value \fIHH\fP
(one or two hex digits)
.RE
.PD
.PP
When entering the text of a macro, single or double quotes should
be used to indicate a macro definition. Unquoted text
is assumed to be a function name.
In the macro body, the backslash escapes described above are expanded.
Backslash will quote any other character in the macro text,
including " and '.
.PP
.B Bash
allows the current readline key bindings to be displayed or modified
with the
.B bind
builtin command. The editing mode may be switched during interactive
use by using the
.B \-o
option to the
.B set
builtin command. Other programs using this library provide
similar mechanisms. The
.I inputrc
file may be edited and re-read if a program does not provide
any other means to incorporate new bindings.
.SS Variables
.PP
Readline has variables that can be used to further customize its
behavior. A variable may be set in the
.I inputrc
file with a statement of the form
.RS
.PP
\fBset\fP \fIvariable\-name\fP \fIvalue\fP
.RE
.PP
Except where noted, readline variables can take the values
.B On
or
.B Off
(without regard to case).
Unrecognized variable names are ignored.
When a variable value is read, empty or null values, "on" (case-insensitive),
and "1" are equivalent to \fBOn\fP. All other values are equivalent to
\fBOff\fP.
The variables and their default values are:
.PP
.PD 0
.TP
.B bell\-style (audible)
Controls what happens when readline wants to ring the terminal bell.
If set to \fBnone\fP, readline never rings the bell. If set to
\fBvisible\fP, readline uses a visible bell if one is available.
If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
.TP
.B bind\-tty\-special\-chars (On)
If set to \fBOn\fP, readline attempts to bind the control characters
treated specially by the kernel's terminal driver to their readline
equivalents.
.TP
.B colored\-stats (Off)
If set to \fBOn\fP, readline displays possible completions using different
colors to indicate their file type.
The color definitions are taken from the value of the \fBLS_COLORS\fP
environment variable.
.TP
.B comment\-begin (``#'')
The string that is inserted in \fBvi\fP mode when the
.B insert\-comment
command is executed.
This command is bound to
.B M\-#
in emacs mode and to
.B #
in vi command mode.
.TP
.B completion\-display\-width (-1)
The number of screen columns used to display possible matches
when performing completion.
The value is ignored if it is less than 0 or greater than the terminal
screen width.
A value of 0 will cause matches to be displayed one per line.
The default value is -1.
.TP
.B completion\-ignore\-case (Off)
If set to \fBOn\fP, readline performs filename matching and completion
in a case\-insensitive fashion.
.TP
.B completion\-map\-case (Off)
If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline
treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when
performing case\-insensitive filename matching and completion.
.TP
.B completion\-prefix\-display\-length (0)
The length in characters of the common prefix of a list of possible
completions that is displayed without modification. When set to a
value greater than zero, common prefixes longer than this value are
replaced with an ellipsis when displaying possible completions.
.TP
.B completion\-query\-items (100)
This determines when the user is queried about viewing
the number of possible completions
generated by the \fBpossible\-completions\fP command.
It may be set to any integer value greater than or equal to
zero. If the number of possible completions is greater than
or equal to the value of this variable, the user is asked whether
or not he wishes to view them; otherwise they are simply listed
on the terminal. A negative value causes readline to never ask.
.TP
.B convert\-meta (On)
If set to \fBOn\fP, readline will convert characters with the
eighth bit set to an ASCII key sequence
by stripping the eighth bit and prefixing it with an
escape character (in effect, using escape as the \fImeta prefix\fP).
.TP
.B disable\-completion (Off)
If set to \fBOn\fP, readline will inhibit word completion. Completion
characters will be inserted into the line as if they had been
mapped to \fBself-insert\fP.
.TP
.B editing\-mode (emacs)
Controls whether readline begins with a set of key bindings similar
to \fIEmacs\fP or \fIvi\fP.
.B editing\-mode
can be set to either
.B emacs
or
.BR vi .
.TP
.B echo\-control\-characters (On)
When set to \fBOn\fP, on operating systems that indicate they support it,
readline echoes a character corresponding to a signal generated from the
keyboard.
.TP
.B enable\-keypad (Off)
When set to \fBOn\fP, readline will try to enable the application
keypad when it is called. Some systems need this to enable the
arrow keys.
.TP
.B enable\-meta\-key (On)
When set to \fBOn\fP, readline will try to enable any meta modifier
key the terminal claims to support when it is called. On many terminals,
the meta key is used to send eight-bit characters.
.TP
.B expand\-tilde (Off)
If set to \fBOn\fP, tilde expansion is performed when readline
attempts word completion.
.TP
.B history\-preserve\-point (Off)
If set to \fBOn\fP, the history code attempts to place point at the
same location on each history line retrieved with \fBprevious-history\fP
or \fBnext-history\fP.
.TP
.B history\-size (0)
Set the maximum number of history entries saved in the history list.
If set to zero, any existing history entries are deleted and no new entries
are saved.
If set to a value less than zero, the number of history entries is not
limited.
By default, the number of history entries is not limited.
.TP
.B horizontal\-scroll\-mode (Off)
When set to \fBOn\fP, makes readline use a single line for display,
scrolling the input horizontally on a single screen line when it
becomes longer than the screen width rather than wrapping to a new line.
.TP
.B input\-meta (Off)
If set to \fBOn\fP, readline will enable eight-bit input (that is,
it will not clear the eighth bit in the characters it reads),
regardless of what the terminal claims it can support. The name
.B meta\-flag
is a synonym for this variable.
.TP
.B isearch\-terminators (``C\-[ C\-J'')
The string of characters that should terminate an incremental
search without subsequently executing the character as a command.
If this variable has not been given a value, the characters
\fIESC\fP and \fIC\-J\fP will terminate an incremental search.
.TP
.B keymap (emacs)
Set the current readline keymap. The set of legal keymap names is
\fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
vi-command\fP, and
.IR vi-insert .
\fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is
equivalent to \fIemacs-standard\fP. The default value is
.IR emacs .
The value of
.B editing\-mode
also affects the default keymap.
.TP
.B keyseq\-timeout (500)
Specifies the duration \fIreadline\fP will wait for a character when reading an
ambiguous key sequence (one that can form a complete key sequence using
the input read so far, or can take additional input to complete a longer
key sequence).
If no input is received within the timeout, \fIreadline\fP will use the shorter
but complete key sequence.
The value is specified in milliseconds, so a value of 1000 means that
\fIreadline\fP will wait one second for additional input.
If this variable is set to a value less than or equal to zero, or to a
non-numeric value, \fIreadline\fP will wait until another key is pressed to
decide which key sequence to complete.
.TP
.B mark\-directories (On)
If set to \fBOn\fP, completed directory names have a slash
appended.
.TP
.B mark\-modified\-lines (Off)
If set to \fBOn\fP, history lines that have been modified are displayed
with a preceding asterisk (\fB*\fP).
.TP
.B mark\-symlinked\-directories (Off)
If set to \fBOn\fP, completed names which are symbolic links to directories
have a slash appended (subject to the value of
\fBmark\-directories\fP).
.TP
.B match\-hidden\-files (On)
This variable, when set to \fBOn\fP, causes readline to match files whose
names begin with a `.' (hidden files) when performing filename
completion.
If set to \fBOff\fP, the leading `.' must be
supplied by the user in the filename to be completed.
.TP
.B menu\-complete\-display\-prefix (Off)
If set to \fBOn\fP, menu completion displays the common prefix of the
list of possible completions (which may be empty) before cycling through
the list.
.TP
.B output\-meta (Off)
If set to \fBOn\fP, readline will display characters with the
eighth bit set directly rather than as a meta-prefixed escape
sequence.
.TP
.B page\-completions (On)
If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager
to display a screenful of possible completions at a time.
.TP
.B print\-completions\-horizontally (Off)
If set to \fBOn\fP, readline will display completions with matches
sorted horizontally in alphabetical order, rather than down the screen.
.TP
.B revert\-all\-at\-newline (Off)
If set to \fBOn\fP, readline will undo all changes to history lines
before returning when \fBaccept\-line\fP is executed. By default,
history lines may be modified and retain individual undo lists across
calls to \fBreadline\fP.
.TP
.B show\-all\-if\-ambiguous (Off)
This alters the default behavior of the completion functions. If
set to
.BR On ,
words which have more than one possible completion cause the
matches to be listed immediately instead of ringing the bell.
.TP
.B show\-all\-if\-unmodified (Off)
This alters the default behavior of the completion functions in
a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
If set to
.BR On ,
words which have more than one possible completion without any
possible partial completion (the possible completions don't share
a common prefix) cause the matches to be listed immediately instead
of ringing the bell.
.TP
.B show\-mode\-in\-prompt (Off)
If set to \fBOn\fP, add a character to the beginning of the prompt
indicating the editing mode: emacs (@), vi command (:) or vi
insertion (+).
.TP
.B skip\-completed\-text (Off)
If set to \fBOn\fP, this alters the default completion behavior when
inserting a single match into the line. It's only active when
performing completion in the middle of a word. If enabled, readline
does not insert characters from the completion that match characters
after point in the word being completed, so portions of the word
following the cursor are not duplicated.
.TP
.B visible\-stats (Off)
If set to \fBOn\fP, a character denoting a file's type as reported
by \fIstat\fP(2) is appended to the filename when listing possible
completions.
.PD
.SS Conditional Constructs
.PP
Readline implements a facility similar in spirit to the conditional
compilation features of the C preprocessor which allows key
bindings and variable settings to be performed as the result
of tests. There are four parser directives used.
.IP \fB$if\fP
The
.B $if
construct allows bindings to be made based on the
editing mode, the terminal being used, or the application using
readline. The text of the test extends to the end of the line;
no characters are required to isolate it.
.RS
.IP \fBmode\fP
The \fBmode=\fP form of the \fB$if\fP directive is used to test
whether readline is in emacs or vi mode.
This may be used in conjunction
with the \fBset keymap\fP command, for instance, to set bindings in
the \fIemacs-standard\fP and \fIemacs-ctlx\fP keymaps only if
readline is starting out in emacs mode.
.IP \fBterm\fP
The \fBterm=\fP form may be used to include terminal-specific
key bindings, perhaps to bind the key sequences output by the
terminal's function keys. The word on the right side of the
.B =
is tested against the full name of the terminal and the portion
of the terminal name before the first \fB\-\fP. This allows
.I sun
to match both
.I sun
and
.IR sun\-cmd ,
for instance.
.IP \fBapplication\fP
The \fBapplication\fP construct is used to include
application-specific settings. Each program using the readline
library sets the \fIapplication name\fP, and an initialization
file can test for a particular value.
This could be used to bind key sequences to functions useful for
a specific program. For instance, the following command adds a
key sequence that quotes the current or previous word in \fBbash\fP:
.sp 1
.RS
.nf
\fB$if\fP Bash
# Quote the current or previous word
"\eC-xq": "\eeb\e"\eef\e""
\fB$endif\fP
.fi
.RE
.RE
.IP \fB$endif\fP
This command, as seen in the previous example, terminates an
\fB$if\fP command.
.IP \fB$else\fP
Commands in this branch of the \fB$if\fP directive are executed if
the test fails.
.IP \fB$include\fP
This directive takes a single filename as an argument and reads commands
and bindings from that file. For example, the following directive
would read \fI/etc/inputrc\fP:
.sp 1
.RS
.nf
\fB$include\fP \^ \fI/etc/inputrc\fP
.fi
.RE
.SH SEARCHING
.PP
Readline provides commands for searching through the command history
for lines containing a specified string.
There are two search modes:
.I incremental
and
.IR non-incremental .
.PP
Incremental searches begin before the user has finished typing the
search string.
As each character of the search string is typed, readline displays
the next entry from the history matching the string typed so far.
An incremental search requires only as many characters as needed to
find the desired history entry.
To search backward in the history for a particular string, type
\fBC\-r\fP. Typing \fBC\-s\fP searches forward through the history.
The characters present in the value of the \fBisearch-terminators\fP
variable are used to terminate an incremental search.
If that variable has not been assigned a value the \fIEscape\fP and
\fBC\-J\fP characters will terminate an incremental search.
\fBC\-G\fP will abort an incremental search and restore the original
line.
When the search is terminated, the history entry containing the
search string becomes the current line.
.PP
To find other matching entries in the history list, type \fBC\-s\fP or
\fBC\-r\fP as appropriate.
This will search backward or forward in the history for the next
line matching the search string typed so far.
Any other key sequence bound to a readline command will terminate
the search and execute that command.
For instance, a newline will terminate the search and accept
the line, thereby executing the command from the history list.
A movement command will terminate the search, make the last line found
the current line, and begin editing.
.PP
Non-incremental searches read the entire search string before starting
to search for matching history lines. The search string may be
typed by the user or be part of the contents of the current line.
.SH EDITING COMMANDS
.PP
The following is a list of the names of the commands and the default
key sequences to which they are bound.
Command names without an accompanying key sequence are unbound by default.
.PP
In the following descriptions, \fIpoint\fP refers to the current cursor
position, and \fImark\fP refers to a cursor position saved by the
\fBset\-mark\fP command.
The text between the point and mark is referred to as the \fIregion\fP.
.SS Commands for Moving
.PP
.PD 0
.TP
.B beginning\-of\-line (C\-a)
Move to the start of the current line.
.TP
.B end\-of\-line (C\-e)
Move to the end of the line.
.TP
.B forward\-char (C\-f)
Move forward a character.
.TP
.B backward\-char (C\-b)
Move back a character.
.TP
.B forward\-word (M\-f)
Move forward to the end of the next word. Words are composed of
alphanumeric characters (letters and digits).
.TP
.B backward\-word (M\-b)
Move back to the start of the current or previous word. Words are
composed of alphanumeric characters (letters and digits).
.TP
.B clear\-screen (C\-l)
Clear the screen leaving the current line at the top of the screen.
With an argument, refresh the current line without clearing the
screen.
.TP
.B redraw\-current\-line
Refresh the current line.
.PD
.SS Commands for Manipulating the History
.PP
.PD 0
.TP
.B accept\-line (Newline, Return)
Accept the line regardless of where the cursor is.
If this line is
non-empty, it may be added to the history list for future recall with
\fBadd_history()\fP.
If the line is a modified history line, the history line is restored to its original state.
.TP
.B previous\-history (C\-p)
Fetch the previous command from the history list, moving back in
the list.
.TP
.B next\-history (C\-n)
Fetch the next command from the history list, moving forward in the
list.
.TP
.B beginning\-of\-history (M\-<)
Move to the first line in the history.
.TP
.B end\-of\-history (M\->)
Move to the end of the input history, i.e., the line currently being
entered.
.TP
.B reverse\-search\-history (C\-r)
Search backward starting at the current line and moving `up' through
the history as necessary. This is an incremental search.
.TP
.B forward\-search\-history (C\-s)
Search forward starting at the current line and moving `down' through
the history as necessary. This is an incremental search.
.TP
.B non\-incremental\-reverse\-search\-history (M\-p)
Search backward through the history starting at the current line
using a non-incremental search for a string supplied by the user.
.TP
.B non\-incremental\-forward\-search\-history (M\-n)
Search forward through the history using a non-incremental search
for a string supplied by the user.
.TP
.B history\-search\-backward
Search backward through the history for the string of characters
between the start of the current line and the current cursor
position (the \fIpoint\fP).
The search string must match at the beginning of a history line.
This is a non-incremental search.
.TP
.B history\-search\-forward
Search forward through the history for the string of characters
between the start of the current line and the point.
The search string must match at the beginning of a history line.
This is a non-incremental search.
.TP
.B history\-substring\-search\-backward
Search backward through the history for the string of characters
between the start of the current line and the current cursor
position (the \fIpoint\fP).
The search string may match anywhere in a history line.
This is a non-incremental search.
.TP
.B history\-substring\-search\-forward
Search forward through the history for the string of characters
between the start of the current line and the point.
The search string may match anywhere in a history line.
This is a non-incremental search.
.TP
.B yank\-nth\-arg (M\-C\-y)
Insert the first argument to the previous command (usually
the second word on the previous line) at point.
With an argument
.IR n ,
insert the \fIn\fPth word from the previous command (the words
in the previous command begin with word 0). A negative argument
inserts the \fIn\fPth word from the end of the previous command.
Once the argument \fIn\fP is computed, the argument is extracted
as if the "!\fIn\fP" history expansion had been specified.
.TP
.B
yank\-last\-arg (M\-.\^, M\-_\^)
Insert the last argument to the previous command (the last word of
the previous history entry).
With a numeric argument, behave exactly like \fByank\-nth\-arg\fP.
Successive calls to \fByank\-last\-arg\fP move back through the history
list, inserting the last word (or the word specified by the argument to
the first call) of each line in turn.
Any numeric argument supplied to these successive calls determines
the direction to move through the history. A negative argument switches
the direction through the history (back or forward).
The history expansion facilities are used to extract the last argument,
as if the "!$" history expansion had been specified.
.PD
.SS Commands for Changing Text
.PP
.PD 0
.TP
.B \fIend\-of\-file\fP (usually C\-d)
The character indicating end-of-file as set, for example, by
.if t \f(CWstty\fP.
.if n ``stty''.
If this character is read when there are no characters
on the line, and point is at the beginning of the line, Readline
interprets it as the end of input and returns
.SM
.BR EOF .
.TP
.B delete\-char (C\-d)
Delete the character at point.
If this function is bound to the
same character as the tty \fBEOF\fP character, as \fBC\-d\fP
commonly is, see above for the effects.
.TP
.B backward\-delete\-char (Rubout)
Delete the character behind the cursor. When given a numeric argument,
save the deleted text on the kill ring.
.TP
.B forward\-backward\-delete\-char
Delete the character under the cursor, unless the cursor is at the
end of the line, in which case the character behind the cursor is
deleted.
.TP
.B quoted\-insert (C\-q, C\-v)
Add the next character that you type to the line verbatim. This is
how to insert characters like \fBC\-q\fP, for example.
.TP
.B tab\-insert (M-TAB)
Insert a tab character.
.TP
.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
Insert the character typed.
.TP
.B transpose\-chars (C\-t)
Drag the character before point forward over the character at point,
moving point forward as well.
If point is at the end of the line, then this transposes
the two characters before point.
Negative arguments have no effect.
.TP
.B transpose\-words (M\-t)
Drag the word before point past the word after point,
moving point over that word as well.
If point is at the end of the line, this transposes
the last two words on the line.
.TP
.B upcase\-word (M\-u)
Uppercase the current (or following) word. With a negative argument,
uppercase the previous word, but do not move point.
.TP
.B downcase\-word (M\-l)
Lowercase the current (or following) word. With a negative argument,
lowercase the previous word, but do not move point.
.TP
.B capitalize\-word (M\-c)
Capitalize the current (or following) word. With a negative argument,
capitalize the previous word, but do not move point.
.TP
.B overwrite\-mode
Toggle overwrite mode. With an explicit positive numeric argument,
switches to overwrite mode. With an explicit non-positive numeric
argument, switches to insert mode. This command affects only
\fBemacs\fP mode; \fBvi\fP mode does overwrite differently.
Each call to \fIreadline()\fP starts in insert mode.
In overwrite mode, characters bound to \fBself\-insert\fP replace
the text at point rather than pushing the text to the right.
Characters bound to \fBbackward\-delete\-char\fP replace the character
before point with a space. By default, this command is unbound.
.PD
.SS Killing and Yanking
.PP
.PD 0
.TP
.B kill\-line (C\-k)
Kill the text from point to the end of the line.
.TP
.B backward\-kill\-line (C\-x Rubout)
Kill backward to the beginning of the line.
.TP
.B unix\-line\-discard (C\-u)
Kill backward from point to the beginning of the line.
The killed text is saved on the kill-ring.
.\" There is no real difference between this and backward-kill-line
.TP
.B kill\-whole\-line
Kill all characters on the current line, no matter where point is.
.TP
.B kill\-word (M\-d)
Kill from point the end of the current word, or if between
words, to the end of the next word. Word boundaries are the same as
those used by \fBforward\-word\fP.
.TP
.B backward\-kill\-word (M\-Rubout)
Kill the word behind point.
Word boundaries are the same as those used by \fBbackward\-word\fP.
.TP
.B unix\-word\-rubout (C\-w)
Kill the word behind point, using white space as a word boundary.
The killed text is saved on the kill-ring.
.TP
.B unix\-filename\-rubout
Kill the word behind point, using white space and the slash character
as the word boundaries.
The killed text is saved on the kill-ring.
.TP
.B delete\-horizontal\-space (M\-\e)
Delete all spaces and tabs around point.
.TP
.B kill\-region
Kill the text between the point and \fImark\fP (saved cursor position).
This text is referred to as the \fIregion\fP.
.TP
.B copy\-region\-as\-kill
Copy the text in the region to the kill buffer.
.TP
.B copy\-backward\-word
Copy the word before point to the kill buffer.
The word boundaries are the same as \fBbackward\-word\fP.
.TP
.B copy\-forward\-word
Copy the word following point to the kill buffer.
The word boundaries are the same as \fBforward\-word\fP.
.TP
.B yank (C\-y)
Yank the top of the kill ring into the buffer at point.
.TP
.B yank\-pop (M\-y)
Rotate the kill ring, and yank the new top. Only works following
.B yank
or
.BR yank\-pop .
.PD
.SS Numeric Arguments
.PP
.PD 0
.TP
.B digit\-argument (M\-0, M\-1, ..., M\-\-)
Add this digit to the argument already accumulating, or start a new
argument. M\-\- starts a negative argument.
.TP
.B universal\-argument
This is another way to specify an argument.
If this command is followed by one or more digits, optionally with a
leading minus sign, those digits define the argument.
If the command is followed by digits, executing
.B universal\-argument
again ends the numeric argument, but is otherwise ignored.
As a special case, if this command is immediately followed by a
character that is neither a digit or minus sign, the argument count
for the next command is multiplied by four.
The argument count is initially one, so executing this function the
first time makes the argument count four, a second time makes the
argument count sixteen, and so on.
.PD
.SS Completing
.PP
.PD 0
.TP
.B complete (TAB)
Attempt to perform completion on the text before point.
The actual completion performed is application-specific.
.BR Bash ,
for instance, attempts completion treating the text as a variable
(if the text begins with \fB$\fP), username (if the text begins with
\fB~\fP), hostname (if the text begins with \fB@\fP), or
command (including aliases and functions) in turn. If none
of these produces a match, filename completion is attempted.
.BR Gdb ,
on the other hand,
allows completion of program functions and variables, and
only attempts filename completion under certain circumstances.
.TP
.B possible\-completions (M\-?)
List the possible completions of the text before point.
When displaying completions, readline sets the number of columns used
for display to the value of \fBcompletion-display-width\fP, the value of
the environment variable
.SM
.BR COLUMNS ,
or the screen width, in that order.
.TP
.B insert\-completions (M\-*)
Insert all completions of the text before point
that would have been generated by
\fBpossible\-completions\fP.
.TP
.B menu\-complete
Similar to \fBcomplete\fP, but replaces the word to be completed
with a single match from the list of possible completions.
Repeated execution of \fBmenu\-complete\fP steps through the list
of possible completions, inserting each match in turn.
At the end of the list of completions, the bell is rung
(subject to the setting of \fBbell\-style\fP)
and the original text is restored.
An argument of \fIn\fP moves \fIn\fP positions forward in the list
of matches; a negative argument may be used to move backward
through the list.
This command is intended to be bound to \fBTAB\fP, but is unbound
by default.
.TP
.B menu\-complete\-backward
Identical to \fBmenu\-complete\fP, but moves backward through the list
of possible completions, as if \fBmenu\-complete\fP had been given a
negative argument. This command is unbound by default.
.TP
.B delete\-char\-or\-list
Deletes the character under the cursor if not at the beginning or
end of the line (like \fBdelete-char\fP).
If at the end of the line, behaves identically to
\fBpossible-completions\fP.
.PD
.SS Keyboard Macros
.PP
.PD 0
.TP
.B start\-kbd\-macro (C\-x (\^)
Begin saving the characters typed into the current keyboard macro.
.TP
.B end\-kbd\-macro (C\-x )\^)
Stop saving the characters typed into the current keyboard macro
and store the definition.
.TP
.B call\-last\-kbd\-macro (C\-x e)
Re-execute the last keyboard macro defined, by making the characters
in the macro appear as if typed at the keyboard.
.B print\-last\-kbd\-macro ()
Print the last keyboard macro defined in a format suitable for the
\fIinputrc\fP file.
.PD
.SS Miscellaneous
.PP
.PD 0
.TP
.B re\-read\-init\-file (C\-x C\-r)
Read in the contents of the \fIinputrc\fP file, and incorporate
any bindings or variable assignments found there.
.TP
.B abort (C\-g)
Abort the current editing command and
ring the terminal's bell (subject to the setting of
.BR bell\-style ).
.TP
.B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...)
If the metafied character \fIx\fP is lowercase, run the command
that is bound to the corresponding uppercase character.
.TP
.B prefix\-meta (ESC)
Metafy the next character typed.
.SM
.B ESC
.B f
is equivalent to
.BR Meta\-f .
.TP
.B undo (C\-_, C\-x C\-u)
Incremental undo, separately remembered for each line.
.TP
.B revert\-line (M\-r)
Undo all changes made to this line. This is like executing the
.B undo
command enough times to return the line to its initial state.
.TP
.B tilde\-expand (M\-&)
Perform tilde expansion on the current word.
.TP
.B set\-mark (C\-@, M\-)
Set the mark to the point. If a
numeric argument is supplied, the mark is set to that position.
.TP
.B exchange\-point\-and\-mark (C\-x C\-x)
Swap the point with the mark. The current cursor position is set to
the saved position, and the old cursor position is saved as the mark.
.TP
.B character\-search (C\-])
A character is read and point is moved to the next occurrence of that
character. A negative count searches for previous occurrences.
.TP
.B character\-search\-backward (M\-C\-])
A character is read and point is moved to the previous occurrence of that
character. A negative count searches for subsequent occurrences.
.TP
.B skip\-csi\-sequence
Read enough characters to consume a multi-key sequence such as those
defined for keys like Home and End. Such sequences begin with a
Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is
bound to "\e[", keys producing such sequences will have no effect
unless explicitly bound to a readline command, instead of inserting
stray characters into the editing buffer. This is unbound by default,
but usually bound to ESC\-[.
.TP
.B insert\-comment (M\-#)
Without a numeric argument, the value of the readline
.B comment\-begin
variable is inserted at the beginning of the current line.
If a numeric argument is supplied, this command acts as a toggle: if
the characters at the beginning of the line do not match the value
of \fBcomment\-begin\fP, the value is inserted, otherwise
the characters in \fBcomment-begin\fP are deleted from the beginning of
the line.
In either case, the line is accepted as if a newline had been typed.
The default value of
.B comment\-begin
makes the current line a shell comment.
If a numeric argument causes the comment character to be removed, the line
will be executed by the shell.
.TP
.B dump\-functions
Print all of the functions and their key bindings to the
readline output stream. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an \fIinputrc\fP file.
.TP
.B dump\-variables
Print all of the settable variables and their values to the
readline output stream. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an \fIinputrc\fP file.
.TP
.B dump\-macros
Print all of the readline key sequences bound to macros and the
strings they output. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
of an \fIinputrc\fP file.
.TP
.B emacs\-editing\-mode (C\-e)
When in
.B vi
command mode, this causes a switch to
.B emacs
editing mode.
.TP
.B vi\-editing\-mode (M\-C\-j)
When in
.B emacs
editing mode, this causes a switch to
.B vi
editing mode.
.PD
.SH DEFAULT KEY BINDINGS
.LP
The following is a list of the default emacs and vi bindings.
Characters with the eighth bit set are written as M\-, and
are referred to as
.I metafied
characters.
The printable ASCII characters not mentioned in the list of emacs
standard bindings are bound to the
.B self\-insert
function, which just inserts the given character into the input line.
In vi insertion mode, all characters not specifically mentioned are
bound to
.BR self\-insert .
Characters assigned to signal generation by
.IR stty (1)
or the terminal driver, such as C-Z or C-C,
retain that function.
Upper and lower case metafied characters are bound to the same function in
the emacs mode meta keymap.
The remaining characters are unbound, which causes readline
to ring the bell (subject to the setting of the
.B bell\-style
variable).
.SS Emacs Mode
.RS +.6i
.nf
.ta 2.5i
.sp
Emacs Standard bindings
.sp
"C-@" set-mark
"C-A" beginning-of-line
"C-B" backward-char
"C-D" delete-char
"C-E" end-of-line
"C-F" forward-char
"C-G" abort
"C-H" backward-delete-char
"C-I" complete
"C-J" accept-line
"C-K" kill-line
"C-L" clear-screen
"C-M" accept-line
"C-N" next-history
"C-P" previous-history
"C-Q" quoted-insert
"C-R" reverse-search-history
"C-S" forward-search-history
"C-T" transpose-chars
"C-U" unix-line-discard
"C-V" quoted-insert
"C-W" unix-word-rubout
"C-Y" yank
"C-]" character-search
"C-_" undo
"\^ " to "/" self-insert
"0" to "9" self-insert
":" to "~" self-insert
"C-?" backward-delete-char
.PP
Emacs Meta bindings
.sp
"M-C-G" abort
"M-C-H" backward-kill-word
"M-C-I" tab-insert
"M-C-J" vi-editing-mode
"M-C-M" vi-editing-mode
"M-C-R" revert-line
"M-C-Y" yank-nth-arg
"M-C-[" complete
"M-C-]" character-search-backward
"M-space" set-mark
"M-#" insert-comment
"M-&" tilde-expand
"M-*" insert-completions
"M--" digit-argument
"M-." yank-last-arg
"M-0" digit-argument
"M-1" digit-argument
"M-2" digit-argument
"M-3" digit-argument
"M-4" digit-argument
"M-5" digit-argument
"M-6" digit-argument
"M-7" digit-argument
"M-8" digit-argument
"M-9" digit-argument
"M-<" beginning-of-history
"M-=" possible-completions
"M->" end-of-history
"M-?" possible-completions
"M-B" backward-word
"M-C" capitalize-word
"M-D" kill-word
"M-F" forward-word
"M-L" downcase-word
"M-N" non-incremental-forward-search-history
"M-P" non-incremental-reverse-search-history
"M-R" revert-line
"M-T" transpose-words
"M-U" upcase-word
"M-Y" yank-pop
"M-\e" delete-horizontal-space
"M-~" tilde-expand
"M-C-?" backward-kill-word
"M-_" yank-last-arg
.PP
Emacs Control-X bindings
.sp
"C-XC-G" abort
"C-XC-R" re-read-init-file
"C-XC-U" undo
"C-XC-X" exchange-point-and-mark
"C-X(" start-kbd-macro
"C-X)" end-kbd-macro
"C-XE" call-last-kbd-macro
"C-XC-?" backward-kill-line
.sp
.RE
.SS VI Mode bindings
.RS +.6i
.nf
.ta 2.5i
.sp
.PP
VI Insert Mode functions
.sp
"C-D" vi-eof-maybe
"C-H" backward-delete-char
"C-I" complete
"C-J" accept-line
"C-M" accept-line
"C-R" reverse-search-history
"C-S" forward-search-history
"C-T" transpose-chars
"C-U" unix-line-discard
"C-V" quoted-insert
"C-W" unix-word-rubout
"C-Y" yank
"C-[" vi-movement-mode
"C-_" undo
"\^ " to "~" self-insert
"C-?" backward-delete-char
.PP
VI Command Mode functions
.sp
"C-D" vi-eof-maybe
"C-E" emacs-editing-mode
"C-G" abort
"C-H" backward-char
"C-J" accept-line
"C-K" kill-line
"C-L" clear-screen
"C-M" accept-line
"C-N" next-history
"C-P" previous-history
"C-Q" quoted-insert
"C-R" reverse-search-history
"C-S" forward-search-history
"C-T" transpose-chars
"C-U" unix-line-discard
"C-V" quoted-insert
"C-W" unix-word-rubout
"C-Y" yank
"C-_" vi-undo
"\^ " forward-char
"#" insert-comment
"$" end-of-line
"%" vi-match
"&" vi-tilde-expand
"*" vi-complete
"+" next-history
"," vi-char-search
"-" previous-history
"." vi-redo
"/" vi-search
"0" beginning-of-line
"1" to "9" vi-arg-digit
";" vi-char-search
"=" vi-complete
"?" vi-search
"A" vi-append-eol
"B" vi-prev-word
"C" vi-change-to
"D" vi-delete-to
"E" vi-end-word
"F" vi-char-search
"G" vi-fetch-history
"I" vi-insert-beg
"N" vi-search-again
"P" vi-put
"R" vi-replace
"S" vi-subst
"T" vi-char-search
"U" revert-line
"W" vi-next-word
"X" backward-delete-char
"Y" vi-yank-to
"\e" vi-complete
"^" vi-first-print
"_" vi-yank-arg
"`" vi-goto-mark
"a" vi-append-mode
"b" vi-prev-word
"c" vi-change-to
"d" vi-delete-to
"e" vi-end-word
"f" vi-char-search
"h" backward-char
"i" vi-insertion-mode
"j" next-history
"k" prev-history
"l" forward-char
"m" vi-set-mark
"n" vi-search-again
"p" vi-put
"r" vi-change-char
"s" vi-subst
"t" vi-char-search
"u" vi-undo
"w" vi-next-word
"x" vi-delete
"y" vi-yank-to
"|" vi-column
"~" vi-change-case
.RE
.SH "SEE ALSO"
.PD 0
.TP
\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
.TP
\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
.TP
\fIbash\fP(1)
.PD
.SH FILES
.PD 0
.TP
.FN ~/.inputrc
Individual \fBreadline\fP initialization file
.PD
.SH AUTHORS
Brian Fox, Free Software Foundation
.br
bfox@gnu.org
.PP
Chet Ramey, Case Western Reserve University
.br
chet.ramey@case.edu
.SH BUG REPORTS
If you find a bug in
.B readline,
you should report it. But first, you should
make sure that it really is a bug, and that it appears in the latest
version of the
.B readline
library that you have.
.PP
Once you have determined that a bug actually exists, mail a
bug report to \fIbug\-readline\fP@\fIgnu.org\fP.
If you have a fix, you are welcome to mail that
as well! Suggestions and `philosophical' bug reports may be mailed
to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet
newsgroup
.BR gnu.bash.bug .
.PP
Comments and bug reports concerning
this manual page should be directed to
.IR chet.ramey@case.edu .
.SH BUGS
.PP
It's too big and too slow.
0707010002ca61000081a40000000000000000000000015424dff700005712000001120001001bffffffffffffffff0000002800000000root/usr/local/share/man/man3/history.3 .\"
.\" MAN PAGE COMMENTS to
.\"
.\" Chet Ramey
.\" Information Network Services
.\" Case Western Reserve University
.\" chet.ramey@case.edu
.\"
.\" Last Change: Thu Thu Jun 27 10:34:44 EDT 2013
.\"
.TH HISTORY 3 "2013 June 27" "GNU History 6.3"
.\"
.\" File Name macro. This used to be `.PN', for Path Name,
.\" but Sun doesn't seem to like that very much.
.\"
.de FN
\fI\|\\$1\|\fP
..
.ds lp \fR\|(\fP
.ds rp \fR\|)\fP
.\" FnN return-value fun-name N arguments
.de Fn1
\fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp
.br
..
.de Fn2
.if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp
.if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp
.br
..
.de Fn3
.if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp
.if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp
.br
..
.de Vb
\fI\\$1\fP \fB\\$2\fP
.br
..
.SH NAME
history \- GNU History Library
.SH COPYRIGHT
.if t The GNU History Library is Copyright \(co 1989-2011 by the Free Software Foundation, Inc.
.if n The GNU History Library is Copyright (C) 1989-2011 by the Free Software Foundation, Inc.
.SH DESCRIPTION
Many programs read input from the user a line at a time. The GNU
History library is able to keep track of those lines, associate arbitrary
data with each line, and utilize information from previous lines in
composing new ones.
.PP
.SH "HISTORY EXPANSION"
.PP
The history library supports a history expansion feature that
is identical to the history expansion in
.BR bash.
This section describes what syntax features are available.
.PP
History expansions introduce words from the history list into
the input stream, making it easy to repeat commands, insert the
arguments to a previous command into the current input line, or
fix errors in previous commands quickly.
.PP
History expansion is usually performed immediately after a complete line
is read.
It takes place in two parts.
The first is to determine which line from the history list
to use during substitution.
The second is to select portions of that line for inclusion into
the current one.
The line selected from the history is the \fIevent\fP,
and the portions of that line that are acted upon are \fIwords\fP.
Various \fImodifiers\fP are available to manipulate the selected words.
The line is broken into words in the same fashion as \fBbash\fP
does when reading input,
so that several words that would otherwise be separated
are considered one word when surrounded by quotes (see the
description of \fBhistory_tokenize()\fP below).
History expansions are introduced by the appearance of the
history expansion character, which is \^\fB!\fP\^ by default.
Only backslash (\^\fB\e\fP\^) and single quotes can quote
the history expansion character.
.SS Event Designators
.PP
An event designator is a reference to a command line entry in the
history list.
Unless the reference is absolute, events are relative to the current
position in the history list.
.PP
.PD 0
.TP
.B !
Start a history substitution, except when followed by a
.BR blank ,
newline, = or (.
.TP
.B !\fIn\fR
Refer to command line
.IR n .
.TP
.B !\-\fIn\fR
Refer to the current command minus
.IR n .
.TP
.B !!
Refer to the previous command. This is a synonym for `!\-1'.
.TP
.B !\fIstring\fR
Refer to the most recent command
preceding the current position in the history list
starting with
.IR string .
.TP
.B !?\fIstring\fR\fB[?]\fR
Refer to the most recent command
preceding the current position in the history list
containing
.IR string .
The trailing \fB?\fP may be omitted if
.I string
is followed immediately by a newline.
.TP
.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
Quick substitution. Repeat the last command, replacing
.I string1
with
.IR string2 .
Equivalent to
``!!:s/\fIstring1\fP/\fIstring2\fP/''
(see \fBModifiers\fP below).
.TP
.B !#
The entire command line typed so far.
.PD
.SS Word Designators
.PP
Word designators are used to select desired words from the event.
A
.B :
separates the event specification from the word designator.
It may be omitted if the word designator begins with a
.BR ^ ,
.BR $ ,
.BR * ,
.BR \- ,
or
.BR % .
Words are numbered from the beginning of the line,
with the first word being denoted by 0 (zero).
Words are inserted into the current line separated by single spaces.
.PP
.PD 0
.TP
.B 0 (zero)
The zeroth word. For the shell, this is the command
word.
.TP
.I n
The \fIn\fRth word.
.TP
.B ^
The first argument. That is, word 1.
.TP
.B $
The last word. This is usually the last argument, but will expand to the
zeroth word if there is only one word in the line.
.TP
.B %
The word matched by the most recent `?\fIstring\fR?' search.
.TP
.I x\fB\-\fPy
A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
.TP
.B *
All of the words but the zeroth. This is a synonym
for `\fI1\-$\fP'. It is not an error to use
.B *
if there is just one
word in the event; the empty string is returned in that case.
.TP
.B x*
Abbreviates \fIx\-$\fP.
.TP
.B x\-
Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
.PD
.PP
If a word designator is supplied without an event specification, the
previous command is used as the event.
.SS Modifiers
.PP
After the optional word designator, there may appear a sequence of
one or more of the following modifiers, each preceded by a `:'.
.PP
.PD 0
.PP
.TP
.B h
Remove a trailing file name component, leaving only the head.
.TP
.B t
Remove all leading file name components, leaving the tail.
.TP
.B r
Remove a trailing suffix of the form \fI.xxx\fP, leaving the
basename.
.TP
.B e
Remove all but the trailing suffix.
.TP
.B p
Print the new command but do not execute it.
.TP
.B q
Quote the substituted words, escaping further substitutions.
.TP
.B x
Quote the substituted words as with
.BR q ,
but break into words at
.B blanks
and newlines.
.TP
.B s/\fIold\fP/\fInew\fP/
Substitute
.I new
for the first occurrence of
.I old
in the event line. Any delimiter can be used in place of /. The
final delimiter is optional if it is the last character of the
event line. The delimiter may be quoted in
.I old
and
.I new
with a single backslash. If & appears in
.IR new ,
it is replaced by
.IR old .
A single backslash will quote the &. If
.I old
is null, it is set to the last
.I old
substituted, or, if no previous history substitutions took place,
the last
.I string
in a
.B !?\fIstring\fR\fB[?]\fR
search.
.TP
.B &
Repeat the previous substitution.
.TP
.B g
Cause changes to be applied over the entire event line. This is
used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')
or `\fB:&\fP'. If used with
`\fB:s\fP', any delimiter can be used
in place of /, and the final delimiter is optional
if it is the last character of the event line.
An \fBa\fP may be used as a synonym for \fBg\fP.
.TP
.B G
Apply the following `\fBs\fP' modifier once to each word in the event line.
.PD
.SH "PROGRAMMING WITH HISTORY FUNCTIONS"
This section describes how to use the History library in other programs.
.SS Introduction to History
.PP
The programmer using the History library has available functions
for remembering lines on a history list, associating arbitrary data
with a line, removing lines from the list, searching through the list
for a line containing an arbitrary text string, and referencing any line
in the list directly. In addition, a history \fIexpansion\fP function
is available which provides for a consistent user interface across
different programs.
.PP
The user using programs written with the History library has the
benefit of a consistent user interface with a set of well-known
commands for manipulating the text of previous lines and using that text
in new commands. The basic history manipulation commands are
identical to
the history substitution provided by \fBbash\fP.
.PP
If the programmer desires, he can use the Readline library, which
includes some history manipulation by default, and has the added
advantage of command line editing.
.PP
Before declaring any functions using any functionality the History
library provides in other code, an application writer should include
the file
.FN
in any file that uses the
History library's features. It supplies extern declarations for all
of the library's public functions and variables, and declares all of
the public data structures.
.SS History Storage
.PP
The history list is an array of history entries. A history entry is
declared as follows:
.PP
.Vb "typedef void *" histdata_t;
.PP
.nf
typedef struct _hist_entry {
char *line;
char *timestamp;
histdata_t data;
} HIST_ENTRY;
.fi
.PP
The history list itself might therefore be declared as
.PP
.Vb "HIST_ENTRY **" the_history_list;
.PP
The state of the History library is encapsulated into a single structure:
.PP
.nf
/*
* A structure used to pass around the current state of the history.
*/
typedef struct _hist_state {
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
int offset; /* The location pointer within this array. */
int length; /* Number of elements within this array. */
int size; /* Number of slots allocated to this array. */
int flags;
} HISTORY_STATE;
.fi
.PP
If the flags member includes \fBHS_STIFLED\fP, the history has been
stifled.
.SH "History Functions"
.PP
This section describes the calling sequence for the various functions
exported by the GNU History library.
.SS Initializing History and State Management
This section describes functions used to initialize and manage
the state of the History library when you want to use the history
functions in your program.
.Fn1 void using_history void
Begin a session in which the history functions might be used. This
initializes the interactive variables.
.Fn1 "HISTORY_STATE *" history_get_history_state void
Return a structure describing the current state of the input history.
.Fn1 void history_set_history_state "HISTORY_STATE *state"
Set the state of the history list according to \fIstate\fP.
.SS History List Management
These functions manage individual entries on the history list, or set
parameters managing the list itself.
.Fn1 void add_history "const char *string"
Place \fIstring\fP at the end of the history list. The associated data
field (if any) is set to \fBNULL\fP.
.Fn1 void add_history_time "const char *string"
Change the time stamp associated with the most recent history entry to
\fIstring\fP.
.Fn1 "HIST_ENTRY *" remove_history "int which"
Remove history entry at offset \fIwhich\fP from the history. The
removed element is returned so you can free the line, data,
and containing structure.
.Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent"
Free the history entry \fIhistent\fP and any history library private
data associated with it. Returns the application-specific data
so the caller can dispose of it.
.Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data"
Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP.
This returns the old entry so the caller can dispose of any
application-specific data. In the case
of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned.
.Fn1 void clear_history "void"
Clear the history list by deleting all the entries.
.Fn1 void stifle_history "int max"
Stifle the history list, remembering only the last \fImax\fP entries.
.Fn1 int unstifle_history "void"
Stop stifling the history. This returns the previously-set
maximum number of history entries (as set by \fBstifle_history()\fP).
history was stifled. The value is positive if the history was
stifled, negative if it wasn't.
.Fn1 int history_is_stifled "void"
Returns non-zero if the history is stifled, zero if it is not.
.SS Information About the History List
These functions return information about the entire history list or
individual list entries.
.Fn1 "HIST_ENTRY **" history_list "void"
Return a \fBNULL\fP terminated array of \fIHIST_ENTRY *\fP which is the
current input history. Element 0 of this list is the beginning of time.
If there is no history, return \fBNULL\fP.
.Fn1 int where_history "void"
Returns the offset of the current history element.
.Fn1 "HIST_ENTRY *" current_history "void"
Return the history entry at the current position, as determined by
\fBwhere_history()\fP. If there is no entry there, return a \fBNULL\fP
pointer.
.Fn1 "HIST_ENTRY *" history_get "int offset"
Return the history entry at position \fIoffset\fP, starting from
\fBhistory_base\fP.
If there is no entry there, or if \fIoffset\fP
is greater than the history length, return a \fBNULL\fP pointer.
.Fn1 "time_t" history_get_time "HIST_ENTRY *"
Return the time stamp associated with the history entry passed as the argument.
.Fn1 int history_total_bytes "void"
Return the number of bytes that the primary history entries are using.
This function returns the sum of the lengths of all the lines in the
history.
.SS Moving Around the History List
These functions allow the current index into the history list to be
set or changed.
.Fn1 int history_set_pos "int pos"
Set the current history offset to \fIpos\fP, an absolute index
into the list.
Returns 1 on success, 0 if \fIpos\fP is less than zero or greater
than the number of history entries.
.Fn1 "HIST_ENTRY *" previous_history "void"
Back up the current history offset to the previous history entry, and
return a pointer to that entry. If there is no previous entry, return
a \fBNULL\fP pointer.
.Fn1 "HIST_ENTRY *" next_history "void"
Move the current history offset forward to the next history entry, and
return the a pointer to that entry. If there is no next entry, return
a \fBNULL\fP pointer.
.SS Searching the History List
These functions allow searching of the history list for entries containing
a specific string. Searching may be performed both forward and backward
from the current history position. The search may be \fIanchored\fP,
meaning that the string must match at the beginning of the history entry.
.Fn2 int history_search "const char *string" "int direction"
Search the history for \fIstring\fP, starting at the current history offset.
If \fIdirection\fP is less than 0, then the search is through
previous entries, otherwise through subsequent entries.
If \fIstring\fP is found, then
the current history index is set to that history entry, and the value
returned is the offset in the line of the entry where
\fIstring\fP was found. Otherwise, nothing is changed, and a -1 is
returned.
.Fn2 int history_search_prefix "const char *string" "int direction"
Search the history for \fIstring\fP, starting at the current history
offset. The search is anchored: matching lines must begin with
\fIstring\fP. If \fIdirection\fP is less than 0, then the search is
through previous entries, otherwise through subsequent entries.
If \fIstring\fP is found, then the
current history index is set to that entry, and the return value is 0.
Otherwise, nothing is changed, and a -1 is returned.
.Fn3 int history_search_pos "const char *string" "int direction" "int pos"
Search for \fIstring\fP in the history list, starting at \fIpos\fP, an
absolute index into the list. If \fIdirection\fP is negative, the search
proceeds backward from \fIpos\fP, otherwise forward. Returns the absolute
index of the history element where \fIstring\fP was found, or -1 otherwise.
.SS Managing the History File
The History library can read the history from and write it to a file.
This section documents the functions for managing a history file.
.Fn1 int read_history "const char *filename"
Add the contents of \fIfilename\fP to the history list, a line at a time.
If \fIfilename\fP is \fBNULL\fP, then read from \fI~/.history\fP.
Returns 0 if successful, or \fBerrno\fP if not.
.Fn3 int read_history_range "const char *filename" "int from" "int to"
Read a range of lines from \fIfilename\fP, adding them to the history list.
Start reading at line \fIfrom\fP and end at \fIto\fP.
If \fIfrom\fP is zero, start at the beginning. If \fIto\fP is less than
\fIfrom\fP, then read until the end of the file. If \fIfilename\fP is
\fBNULL\fP, then read from \fI~/.history\fP. Returns 0 if successful,
or \fBerrno\fP if not.
.Fn1 int write_history "const char *filename"
Write the current history to \fIfilename\fP, overwriting \fIfilename\fP
if necessary.
If \fIfilename\fP is \fBNULL\fP, then write the history list to \fI~/.history\fP.
Returns 0 on success, or \fBerrno\fP on a read or write error.
.Fn2 int append_history "int nelements" "const char *filename"
Append the last \fInelements\fP of the history list to \fIfilename\fP.
If \fIfilename\fP is \fBNULL\fP, then append to \fI~/.history\fP.
Returns 0 on success, or \fBerrno\fP on a read or write error.
.Fn2 int history_truncate_file "const char *filename" "int nlines"
Truncate the history file \fIfilename\fP, leaving only the last
\fInlines\fP lines.
If \fIfilename\fP is \fBNULL\fP, then \fI~/.history\fP is truncated.
Returns 0 on success, or \fBerrno\fP on failure.
.SS History Expansion
These functions implement history expansion.
.Fn2 int history_expand "char *string" "char **output"
Expand \fIstring\fP, placing the result into \fIoutput\fP, a pointer
to a string. Returns:
.RS
.PD 0
.TP
0
If no expansions took place (or, if the only change in
the text was the removal of escape characters preceding the history expansion
character);
.TP
1
if expansions did take place;
.TP
-1
if there was an error in expansion;
.TP
2
if the returned line should be displayed, but not executed,
as with the \fB:p\fP modifier.
.PD
.RE
If an error ocurred in expansion, then \fIoutput\fP contains a descriptive
error message.
.Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar"
Returns the text of the history event beginning at \fIstring\fP +
\fI*cindex\fP. \fI*cindex\fP is modified to point to after the event
specifier. At function entry, \fIcindex\fP points to the index into
\fIstring\fP where the history event specification begins. \fIqchar\fP
is a character that is allowed to end the event specification in addition
to the ``normal'' terminating characters.
.Fn1 "char **" history_tokenize "const char *string"
Return an array of tokens parsed out of \fIstring\fP, much as the
shell might.
The tokens are split on the characters in the
\fBhistory_word_delimiters\fP variable,
and shell quoting conventions are obeyed.
.Fn3 "char *" history_arg_extract "int first" "int last" "const char *string"
Extract a string segment consisting of the \fIfirst\fP through \fIlast\fP
arguments present in \fIstring\fP. Arguments are split using
\fBhistory_tokenize()\fP.
.SS History Variables
This section describes the externally-visible variables exported by
the GNU History Library.
.Vb int history_base
The logical offset of the first entry in the history list.
.Vb int history_length
The number of entries currently stored in the history list.
.Vb int history_max_entries
The maximum number of history entries. This must be changed using
\fBstifle_history()\fP.
.Vb int history_wite_timestamps
If non-zero, timestamps are written to the history file, so they can be
preserved between sessions. The default value is 0, meaning that
timestamps are not saved.
The current timestamp format uses the value of \fIhistory_comment_char\fP
to delimit timestamp entries in the history file. If that variable does
not have a value (the default), timestamps will not be written.
.Vb char history_expansion_char
The character that introduces a history event. The default is \fB!\fP.
Setting this to 0 inhibits history expansion.
.Vb char history_subst_char
The character that invokes word substitution if found at the start of
a line. The default is \fB^\fP.
.Vb char history_comment_char
During tokenization, if this character is seen as the first character
of a word, then it and all subsequent characters up to a newline are
ignored, suppressing history expansion for the remainder of the line.
This is disabled by default.
.Vb "char *" history_word_delimiters
The characters that separate tokens for \fBhistory_tokenize()\fP.
The default value is \fB"\ \et\en()<>;&|"\fP.
.Vb "char *" history_no_expand_chars
The list of characters which inhibit history expansion if found immediately
following \fBhistory_expansion_char\fP. The default is space, tab, newline,
\fB\er\fP, and \fB=\fP.
.Vb "char *" history_search_delimiter_chars
The list of additional characters which can delimit a history search
string, in addition to space, tab, \fI:\fP and \fI?\fP in the case of
a substring search. The default is empty.
.Vb int history_quotes_inhibit_expansion
If non-zero, single-quoted words are not scanned for the history expansion
character. The default value is 0.
.Vb "rl_linebuf_func_t *" history_inhibit_expansion_function
This should be set to the address of a function that takes two arguments:
a \fBchar *\fP (\fIstring\fP)
and an \fBint\fP index into that string (\fIi\fP).
It should return a non-zero value if the history expansion starting at
\fIstring[i]\fP should not be performed; zero if the expansion should
be done.
It is intended for use by applications like \fBbash\fP that use the history
expansion character for additional purposes.
By default, this variable is set to \fBNULL\fP.
.SH FILES
.PD 0
.TP
.FN ~/.history
Default filename for reading and writing saved history
.PD
.SH "SEE ALSO"
.PD 0
.TP
\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
.TP
\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
.TP
\fIbash\fP(1)
.TP
\fIreadline\fP(3)
.PD
.SH AUTHORS
Brian Fox, Free Software Foundation
.br
bfox@gnu.org
.PP
Chet Ramey, Case Western Reserve University
.br
chet.ramey@case.edu
.SH BUG REPORTS
If you find a bug in the
.B history
library, you should report it. But first, you should
make sure that it really is a bug, and that it appears in the latest
version of the
.B history
library that you have.
.PP
Once you have determined that a bug actually exists, mail a
bug report to \fIbug\-readline\fP@\fIgnu.org\fP.
If you have a fix, you are welcome to mail that
as well! Suggestions and `philosophical' bug reports may be mailed
to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet
newsgroup
.BR gnu.bash.bug .
.PP
Comments and bug reports concerning
this manual page should be directed to
.IR chet.ramey@case.edu .
0707010002ca55000041ed0000000000000000000000035424e06e00000000000001120001001bffffffffffffffff0000001900000000root/usr/local/share/doc 0707010002ca56000041ed0000000000000000000000025424e06e00000000000001120001001bffffffffffffffff0000002200000000root/usr/local/share/doc/readline 0707010002ca57000081a40000000000000000000000015424dff70000e0b5000001120001001bffffffffffffffff0000002a00000000root/usr/local/share/doc/readline/CHANGES This document details the changes between this version, readline-6.3, and the
previous version, readline-6.2.
1. Changes to Readline
a. Fixed a bug that did not allow the `dd', `cc', or `yy' vi editing mode
commands to work on the entire line.
b. Fixed a bug that caused redisplay problems with prompts longer than 128
characters and history searches.
c. Fixed a bug that caused readline to try and run code to modify its idea
of the screen size in a signal handler context upon receiving a SIGWINCH.
d. Fixed a bug that caused the `meta' key to be enabled beyond the duration
of an individual call top readline().
e. Added a workaround for a wcwidth bug in Mac OS X that caused readline's
redisplay to mishandle zero-width combining characters.
f. Fixed a bug that caused readline to `forget' part of a key sequence when
a multiple-key sequence caused it to break out of an incremental search.
g. Fixed bugs that caused readline to execute code in a signal handler
context if interrupted while reading from the file system during completion.
h. Fixed a bug that caused readline to `forget' part of a key sequence when
reading an unbound multi-character key sequence.
i. Fixed a bug that caused Readline's signal handlers to be installed beyond
the bounds of a single call to readline().
j. Fixed a bug that caused the `.' command to not redo the most recent `R'
command in vi mode.
k. Fixed a bug that caused ignoring case in completion matches to result in
readline using the wrong match.
l. Paren matching now works in vi insert mode.
m. Fix menu-completion to make show-all-if-ambiguous and menu-complete-display-prefix
work together.
n. Fixed a bug that didn't allow the `cc', `dd', or `yy' commands to be redone
in vi editing mode.
o. Fixed a bug that caused the filename comparison code to not compare
multibyte characters correctly when using case-sensitive or case-mapping
comparisons.
p. Fixed the input reading loop to call the input hook function only when there
is no terminal input available.
q. Fixed a bug that caused binding a macro to a multi-character key sequence
where the sequence and macro value share a common prefix to not perform
the macro replacement.
r. Fixed several redisplay errors with multibyte characters and prompts
containing invisible characters when using horizontal scrolling.
s. Fixed a bug that caused redisplay errors when trying to overwrite
existing characters using multibyte characters.
t. Fixed a bug in vi mode that caused the arrow keys to set the saved last
vi-mode command to the wrong value.
u. Fixed a bug that caused double-quoted strings to be scanned incorrectly
when being used as the value of a readline variable assignment.
v. Fixed a bug with vi mode that prevented `.' from repeating a command
entered on a previous line (command).
w. Fixed a bug that could cause completion to core dump if it was interrupted
by a signal.
x. Fixed a bug that could cause readline to crash and seg fault attempting to
expand an empty history entry.
y. Fixed a bug that caused display problems with multi-line prompts containing
invisible characters on multiple lines.
z. Fixed a bug that caused effects made by undoing changes to a history line to
be discarded.
2. New Features in Readline
a. Readline is now more responsive to SIGHUP and other fatal signals when
reading input from the terminal or performing word completion but no
longer attempts to run any not-allowable functions from a signal handler
context.
b. There are new bindable commands to search the history for the string of
characters between the beginning of the line and the point
(history-substring-search-forward, history-substring-search-backward)
c. Readline allows quoted strings as the values of variables when setting
them with `set'. As a side effect, trailing spaces and tabs are ignored
when setting a string variable's value.
d. The history library creates a backup of the history file when writing it
and restores the backup on a write error.
e. New application-settable variable: rl_filename_stat_hook: a function called
with a filename before using it in a call to stat(2). Bash uses it to
expand shell variables so things like $HOME/Downloads have a slash
appended.
f. New bindable function `print-last-kbd-macro', prints the most-recently-
defined keyboard macro in a reusable format.
g. New user-settable variable `colored-stats', enables use of colored text
to denote file types when displaying possible completions (colored analog
of visible-stats).
h. New user-settable variable `keyseq-timout', acts as an inter-character
timeout when reading input or incremental search strings.
i. New application-callable function: rl_clear_history. Clears the history list
and frees all readline-associated private data.
j. New user-settable variable, show-mode-in-prompt, adds a characters to the
beginning of the prompt indicating the current editing mode.
k. New application-settable variable: rl_input_available_hook; function to be
called when readline needs to check whether there is data available on its
input source. The default hook checks rl_instream.
l. Readline calls an application-set event hook (rl_signal_event_hook) after
it gets a signal while reading input (read returns -1/EINTR but readline
does not handle the signal immediately) to allow the application to handle
or otherwise note it. Not currently called for SIGHUP or SIGTERM.
m. If the user-settable variable `history-size' is set to a value less than
0, the history list size is unlimited.
n. When creating shared libraries on Mac OS X, the pathname written into the
library (install_name) no longer includes the minor version number.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-6.2,
and the previous version, readline-6.1.
1. Changes to Readline
a. Fixed a bug that caused the unconverted filename to be added to the list of
completions when the application specified filename conversion functions.
b. Fixed a bug that caused the wrong filename to be passed to opendir when the
application has specified a filename dequoting function.
c. Fixed a bug when repeating a character search in vi mode in the case where
there was no search to repeat.
d. When show-all-if-ambiguous is set, the completion routines no longer insert
a common match prefix that is shorter than the text being completed.
e. The full set of vi editing commands may now be used in callback mode.
f. Fixed a bug that caused readline to not update its idea of the terminal
dimensions while running in `no-echo' mode.
h. Fixed a bug that caused readline to dump core if an application called
rl_prep_terminal without setting rl_instream.
i. Fixed a bug that caused meta-prefixed characters bound to incremental
search forward or backward to not be recognized if they were typed
subsequently.
j. The incremental search code treats key sequences that map to the same
functions as (default) ^G, ^W, and ^Y as equivalent to those characters.
k. Fixed a bug in menu-complete that caused it to misbehave with large
negative argument.
l. Fixed a bug that caused vi-mode yank-last-arg to ring the bell when invoked
at the end of the line.
m. Fixed a bug that made an explicit argument of 0 to yank-last-arg behave
as if it were a negative argument.
n. Fixed a bug that caused directory names in words to be completed to not
be dequoted correctly.
2. New Features in Readline
a. The history library does not try to write the history filename in the
current directory if $HOME is unset. This closes a potential security
problem if the application does not specify a history filename.
b. New bindable variable `completion-display-width' to set the number of
columns used when displaying completions.
c. New bindable variable `completion-case-map' to cause case-insensitive
completion to treat `-' and `_' as identical.
d. There are new bindable vi-mode command names to avoid readline's case-
insensitive matching not allowing them to be bound separately.
e. New bindable variable `menu-complete-display-prefix' causes the menu
completion code to display the common prefix of the possible completions
before cycling through the list, instead of after.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-6.1,
and the previous version, readline-6.0.
1. Changes to Readline
a. The SIGWINCH signal handler now avoids calling the redisplay code if
one arrives while in the middle of redisplay.
b. Changes to the timeout code to make sure that timeout values greater
than one second are handled better.
c. Fixed a bug in the redisplay code that was triggered by a prompt
containing invisible characters exactly the width of the screen.
d. Fixed a bug in the redisplay code encountered when running in horizontal
scroll mode.
e. Fixed a bug that prevented menu completion from properly completing
filenames.
f. Fixed a redisplay bug caused by a multibyte character causing a line to
wrap.
g. Fixed a bug that caused key sequences of two characters to not be
recognized when a longer sequence identical in the first two characters
was bound.
h. Fixed a bug that caused history expansion to be attempted on $'...'
single-quoted strings.
i. Fixed a bug that caused incorrect redisplay when the prompt contained
multibyte characters in an `invisible' sequence bracketed by \[ and
\].
j. Fixed a bug that caused history expansion to short-circuit after
encountering a multibyte character.
k. Fixed a bug that caused applications using the callback interface to not
react to SIGINT (or other signals) until another character arrived.
2. New Features in Readline
a. New bindable function: menu-complete-backward.
b. In the vi insertion keymap, C-n is now bound to menu-complete by default,
and C-p to menu-complete-backward.
c. When in vi command mode, repeatedly hitting ESC now does nothing, even
when ESC introduces a bound key sequence. This is closer to how
historical vi behaves.
d. New bindable function: skip-csi-sequence. Can be used as a default to
consume key sequences generated by keys like Home and End without having
to bind all keys.
e. New application-settable function: rl_filename_rewrite_hook. Can be used
to rewite or modify filenames read from the file system before they are
compared to the word to be completed.
f. New bindable variable: skip-completed-text, active when completing in the
middle of a word. If enabled, it means that characters in the completion
that match characters in the remainder of the word are "skipped" rather
than inserted into the line.
g. The pre-readline-6.0 version of menu completion is available as
"old-menu-complete" for users who do not like the readline-6.0 version.
h. New bindable variable: echo-control-characters. If enabled, and the
tty ECHOCTL bit is set, controls the echoing of characters corresponding
to keyboard-generated signals.
i. New bindable variable: enable-meta-key. Controls whether or not readline
sends the smm/rmm sequences if the terminal indicates it has a meta key
that enables eight-bit characters.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-6.0,
and the previous version, readline-5.2.
1. Changes to Readline
a. Fixed a number of redisplay errors in environments supporting multibyte
characters.
b. Fixed bugs in vi command mode that caused motion commands to inappropriately
set the mark.
c. When using the arrow keys in vi insertion mode, readline allows movement
beyond the current end of the line (unlike command mode).
d. Fixed bugs that caused readline to loop when the terminal has been taken
away and reads return -1/EIO.
e. Fixed bugs in redisplay occurring when displaying prompts containing
invisible characters.
f. Fixed a bug that caused the completion append character to not be reset to
the default after an application-specified completion function changed it.
g. Fixed a problem that caused incorrect positioning of the cursor while in
emacs editing mode when moving forward at the end of a line while using
a locale supporting multibyte characters.
h. Fixed an off-by-one error that caused readline to drop every 511th
character of buffered input.
i. Fixed a bug that resulted in SIGTERM not being caught or cleaned up.
j. Fixed redisplay bugs caused by multiline prompts with invisible characters
or no characters following the final newline.
k. Fixed redisplay bug caused by prompts consisting solely of invisible
characters.
l. Fixed a bug in the code that buffers characters received very quickly in
succession which caused characters to be dropped.
m. Fixed a bug that caused readline to reference uninitialized data structures
if it received a SIGWINCH before completing initialzation.
n. Fixed a bug that caused the vi-mode `last command' to be set incorrectly
and therefore unrepeatable.
o. Fixed a bug that caused readline to disable echoing when it was being used
with an output file descriptor that was not a terminal.
p. Readline now blocks SIGINT while manipulating internal data structures
during redisplay.
q. Fixed a bug in redisplay that caused readline to segfault when pasting a
very long line (over 130,000 characters).
r. Fixed bugs in redisplay when using prompts with no visible printing
characters.
s. Fixed a bug that caused redisplay errors when using prompts with invisible
characters and numeric arguments to a command in a multibyte locale.
t. Fixed a bug that caused redisplay errors when using prompts with invisible
characters spanning more than two physical screen lines.
2. New Features in Readline
a. A new variable, rl_sort_completion_matches; allows applications to inhibit
match list sorting (but beware: some things don't work right if
applications do this).
b. A new variable, rl_completion_invoking_key; allows applications to discover
the key that invoked rl_complete or rl_menu_complete.
c. The functions rl_block_sigint and rl_release_sigint are now public and
available to calling applications who want to protect critical sections
(like redisplay).
d. The functions rl_save_state and rl_restore_state are now public and
available to calling applications; documented rest of readline's state
flag values.
e. A new user-settable variable, `history-size', allows setting the maximum
number of entries in the history list.
f. There is a new implementation of menu completion, with several improvements
over the old; the most notable improvement is a better `completions
browsing' mode.
g. The menu completion code now uses the rl_menu_completion_entry_function
variable, allowing applications to provide their own menu completion
generators.
h. There is support for replacing a prefix of a pathname with a `...' when
displaying possible completions. This is controllable by setting the
`completion-prefix-display-length' variable. Matches with a common prefix
longer than this value have the common prefix replaced with `...'.
i. There is a new `revert-all-at-newline' variable. If enabled, readline will
undo all outstanding changes to all history lines when `accept-line' is
executed.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-5.2,
and the previous version, readline-5.1.
1. Changes to Readline
a. Fixed a problem that caused segmentation faults when using readline in
callback mode and typing consecutive DEL characters on an empty line.
b. Fixed several redisplay problems with multibyte characters, all having to
do with the different code paths and variable meanings between single-byte
and multibyte character redisplay.
c. Fixed a problem with key sequence translation when presented with the
sequence \M-\C-x.
d. Fixed a problem that prevented the `a' command in vi mode from being
undone and redone properly.
e. Fixed a problem that prevented empty inserts in vi mode from being undone
properly.
f. Fixed a problem that caused readline to initialize with an incorrect idea
of whether or not the terminal can autowrap.
g. Fixed output of key bindings (like bash `bind -p') to honor the setting of
convert-meta and use \e where appropriate.
h. Changed the default filename completion function to call the filename
dequoting function if the directory completion hook isn't set. This means
that any directory completion hooks need to dequote the directory name,
since application-specific hooks need to know how the word was quoted,
even if no other changes are made.
i. Fixed a bug with creating the prompt for a non-interactive search string
when there are non-printing characters in the primary prompt.
j. Fixed a bug that caused prompts with invisible characters to be redrawn
multiple times in a multibyte locale.
k. Fixed a bug that could cause the key sequence scanning code to return the
wrong function.
l. Fixed a problem with the callback interface that caused it to fail when
using multi-character keyboard macros.
m. Fixed a bug that could cause a core dump when an edited history entry was
re-executed under certain conditions.
n. Fixed a bug that caused readline to reference freed memory when attmpting
to display a portion of the prompt.
o. Fixed a bug with prompt redisplay in a multi-byte locale to avoid redrawing
the prompt and input line multiple times.
p. Fixed history expansion to not be confused by here-string redirection.
q. Readline no longer treats read errors by converting them to newlines, as
it does with EOF. This caused partial lines to be returned from readline().
r. Fixed a redisplay bug that occurred in multibyte-capable locales when the
prompt was one character longer than the screen width.
2. New Features in Readline
a. Calling applications can now set the keyboard timeout to 0, allowing
poll-like behavior.
b. The value of SYS_INPUTRC (configurable at compilation time) is now used as
the default last-ditch startup file.
c. The history file reading functions now allow windows-like \r\n line
terminators.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-5.1,
and the previous version, readline-5.0.
1. Changes to Readline
a. Fixed a bug that caused multiliine prompts to be wrapped and displayed
incorrectly.
b. Fixed a bug that caused ^P/^N in emacs mode to fail to display the current
line correctly.
c. Fixed a problem in computing the number of invisible characters on the first
line of a prompt whose length exceeds the screen width.
d. Fixed vi-mode searching so that failure preserves the current line rather
than the last line in the history list.
e. Fixed the vi-mode `~' command (change-case) to have the correct behavior at
end-of-line when manipulating multibyte characters.
f. Fixed the vi-mode `r' command (change-char) to have the correct behavior at
end-of-line when manipulating multibyte characters.
g. Fixed multiple bugs in the redisplay of multibyte characters: displaying
prompts longer than the screen width containing multibyte characters,
h. Fix the calculation of the number of physical characters in the prompt
string when it contains multibyte characters.
i. A non-zero value for the `rl_complete_suppress_append' variable now causes
no `/' to be appended to a directory name.
j. Fixed forward-word and backward-word to work when words contained
multibyte characters.
k. Fixed a bug in finding the delimiter of a `?' substring when performing
history expansion in a locale that supports multibyte characters.
l. Fixed a memory leak caused by not freeing the timestamp in a history entry.
m. Fixed a bug that caused "\M-x" style key bindings to not obey the setting
of the `convert-meta' variable.
n. Fixed saving and restoring primary prompt when prompting for incremental
and non-incremental searches; search prompts now display multibyte
characters correctly.
o. Fixed a bug that caused keys originally bound to self-insert but shadowed
by a multi-character key sequence to not be inserted.
p. Fixed code so rl_prep_term_function and rl_deprep_term_function aren't
dereferenced if NULL (matching the documentation).
q. Extensive changes to readline to add enough state so that commands
requiring additional characters (searches, multi-key sequences, numeric
arguments, commands requiring an additional specifier character like
vi-mode change-char, etc.) work without synchronously waiting for
additional input.
r. Lots of changes so readline builds and runs on MinGW.
s. Readline no longer tries to modify the terminal settings when running in
callback mode.
t. The Readline display code no longer sets the location of the last invisible
character in the prompt if the \[\] sequence is empty.
u. The `change-case' command now correctly changes the case of multibyte
characters.
v. Changes to the shared library construction scripts to deal with Windows
DLL naming conventions for Cygwin.
w. Fixed the redisplay code to avoid core dumps resulting from a poorly-timed
SIGWINCH.
x. Fixed the non-incremental search code in vi mode to dispose of any current
undo list when copying a line from the history into the current editing
buffer.
y. Fixed a bug that caused reversing the incremental search direction to
not work correctly.
z. Fixed the vi-mode `U' command to only undo up to the first time insert mode
was entered, as Posix specifies.
aa. Fixed a bug in the vi-mode `r' command that left the cursor in the wrong
place.
bb. Fixed a redisplay bug caused by moving the cursor vertically to a line
with invisible characters in the prompt in a multibyte locale.
cc. Fixed a bug that could cause the terminal special chars to be bound in the
wrong keymap in vi mode.
2. New Features in Readline
a. The key sequence sent by the keypad `delete' key is now automatically
bound to delete-char.
b. A negative argument to menu-complete now cycles backward through the
completion list.
c. A new bindable readline variable: bind-tty-special-chars. If non-zero,
readline will bind the terminal special characters to their readline
equivalents when it's called (on by default).
d. New bindable command: vi-rubout. Saves deleted text for possible
reinsertion, as with any vi-mode `text modification' command; `X' is bound
to this in vi command mode.
e. If the rl_completion_query_items is set to a value < 0, readline never
asks the user whether or not to view the possible completions.
f. The `C-w' binding in incremental search now understands multibyte
characters.
g. New application-callable auxiliary function, rl_variable_value, returns
a string corresponding to a readline variable's value.
h. When parsing inputrc files and variable binding commands, the parser
strips trailing whitespace from values assigned to boolean variables
before checking them.
i. A new external application-controllable variable that allows the LINES
and COLUMNS environment variables to set the window size regardless of
what the kernel returns.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-5.0,
and the previous version, readline-4.3.
1. Changes to Readline
a. Fixes to avoid core dumps because of null pointer references in the
multibyte character code.
b. Fix to avoid infinite recursion caused by certain key combinations.
c. Fixed a bug that caused the vi-mode `last command' to be set incorrectly.
d. Readline no longer tries to read ahead more than one line of input, even
when more is available.
e. Fixed the code that adjusts the point to not mishandle null wide
characters.
f. Fixed a bug in the history expansion `g' modifier that caused it to skip
every other match.
g. Fixed a bug that caused the prompt to overwrite previous output when the
output doesn't contain a newline and the locale supports multibyte
characters. This same change fixes the problem of readline redisplay
slowing down dramatically as the line gets longer in multibyte locales.
h. History traversal with arrow keys in vi insertion mode causes the cursor
to be placed at the end of the new line, like in emacs mode.
i. The locale initialization code does a better job of using the right
precedence and defaulting when checking the appropriate environment
variables.
j. Fixed the history word tokenizer to handle <( and >( better when used as
part of bash.
k. The overwrite mode code received several bug fixes to improve undo.
l. Many speedups to the multibyte character redisplay code.
m. The callback character reading interface should not hang waiting to read
keyboard input.
n. Fixed a bug with redoing vi-mode `s' command.
o. The code that initializes the terminal tracks changes made to the terminal
special characters with stty(1) (or equivalent), so that these changes
are reflected in the readline bindings. New application-callable function
to make it work: rl_tty_unset_default_bindings().
p. Fixed a bug that could cause garbage to be inserted in the buffer when
changing character case in vi mode when using a multibyte locale.
q. Fixed a bug in the redisplay code that caused problems on systems
supporting multibyte characters when moving between history lines when the
new line has more glyphs but fewer bytes.
r. Undo and redo now work better after exiting vi insertion mode.
s. Make sure system calls are restarted after a SIGWINCH is received using
SA_RESTART.
t. Improvements to the code that displays possible completions when using
multibyte characters.
u. Fixed a problem when parsing nested if statements in inputrc files.
v. The completer now takes multibyte characters into account when looking for
quoted substrings on which to perform completion.
w. The history search functions now perform better bounds checking on the
history list.
x. Change to history expansion functions to treat `^' as equivalent to word
one, as the documention states.
y. Some changes to the display code to improve display and redisplay of
multibyte characters.
z. Changes to speed up the multibyte character redisplay code.
aa. Fixed a bug in the vi-mode `E' command that caused it to skip over the
last character of a word if invoked while point was on the word's
next-to-last character.
bb. Fixed a bug that could cause incorrect filename quoting when
case-insensitive completion was enabled and the word being completed
contained backslashes quoting word break characters.
cc. Fixed a bug in redisplay triggered when the prompt string contains
invisible characters.
dd. Fixed some display (and other) bugs encountered in multibyte locales
when a non-ascii character was the last character on a line.
ee. Fixed some display bugs caused by multibyte characters in prompt strings.
ff. Fixed a problem with history expansion caused by non-whitespace characters
used as history word delimiters.
gg. Fixed a problem that could cause readline to refer to freed memory when
moving between history lines while doing searches.
hh. Improvements to the code that expands and displays prompt strings
containing multibyte characters.
ii. Fixed a problem with vi-mode not correctly remembering the numeric argument
to the last `c'hange command for later use with `.'.
jj. Fixed a bug in vi-mode that caused multi-digit count arguments to work
incorrectly.
kk. Fixed a problem in vi-mode that caused the last text modification command
to not be remembered across different command lines.
ll. Fixed problems with changing characters and changing case at the end of
the line.
mm. Fixed a problem with readline saving the contents of the current line
before beginning a non-interactive search.
nn. Fixed a problem with EOF detection when using rl_event_hook.
oo. Fixed a problem with the vi mode `p' and `P' commands ignoring numeric
arguments.
2. New Features in Readline
a. History expansion has a new `a' modifier equivalent to the `g' modifier
for compatibility with the BSD csh.
b. History expansion has a new `G' modifier equivalent to the BSD csh `g'
modifier, which performs a substitution once per word.
c. All non-incremental search operations may now undo the operation of
replacing the current line with the history line.
d. The text inserted by an `a' command in vi mode can be reinserted with
`.'.
e. New bindable variable, `show-all-if-unmodified'. If set, the readline
completer will list possible completions immediately if there is more
than one completion and partial completion cannot be performed.
f. There is a new application-callable `free_history_entry()' function.
g. History list entries now contain timestamp information; the history file
functions know how to read and write timestamp information associated
with each entry.
h. Four new key binding functions have been added:
rl_bind_key_if_unbound()
rl_bind_key_if_unbound_in_map()
rl_bind_keyseq_if_unbound()
rl_bind_keyseq_if_unbound_in_map()
i. New application variable, rl_completion_quote_character, set to any
quote character readline finds before it calls the application completion
function.
j. New application variable, rl_completion_suppress_quote, settable by an
application completion function. If set to non-zero, readline does not
attempt to append a closing quote to a completed word.
k. New application variable, rl_completion_found_quote, set to a non-zero
value if readline determines that the word to be completed is quoted.
Set before readline calls any application completion function.
l. New function hook, rl_completion_word_break_hook, called when readline
needs to break a line into words when completion is attempted. Allows
the word break characters to vary based on position in the line.
m. New bindable command: unix-filename-rubout. Does the same thing as
unix-word-rubout, but adds `/' to the set of word delimiters.
n. When listing completions, directories have a `/' appended if the
`mark-directories' option has been enabled.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-4.3,
and the previous version, readline-4.2a.
1. Changes to Readline
a. Fixed output of comment-begin character when listing variable values.
b. Added some default key bindings for common escape sequences produced by
HOME and END keys.
c. Fixed the mark handling code to be more emacs-compatible.
d. A bug was fixed in the code that prints possible completions to keep it
from printing empty strings in certain circumstances.
e. Change the key sequence printing code to print ESC as M\- if ESC is a
meta-prefix character -- it's easier for users to understand than \e.
f. Fixed unstifle_history() to return values that match the documentation.
g. Fixed the event loop (rl_event_hook) to handle the case where the input
file descriptor is invalidated.
h. Fixed the prompt display code to work better when the application has a
custom redisplay function.
i. Changes to make reading and writing the history file a little faster, and
to cope with huge history files without calling abort(3) from xmalloc.
j. The vi-mode `S' and `s' commands are now undone correctly.
k. Fixed a problem which caused the display to be messed up when the last
line of a multi-line prompt (possibly containing invisible characters)
was longer than the screen width.
2. New Features in Readline
a. Support for key `subsequences': allows, e.g., ESC and ESC-a to both
be bound to readline functions. Now the arrow keys may be used in vi
insert mode.
b. When listing completions, and the number of lines displayed is more than
the screen length, readline uses an internal pager to display the results.
This is controlled by the `page-completions' variable (default on).
c. New code to handle editing and displaying multibyte characters.
d. The behavior introduced in bash-2.05a of deciding whether or not to
append a slash to a completed name that is a symlink to a directory has
been made optional, controlled by the `mark-symlinked-directories'
variable (default is the 2.05a behavior).
e. The `insert-comment' command now acts as a toggle if given a numeric
argument: if the first characters on the line don't specify a
comment, insert one; if they do, delete the comment text
f. New application-settable completion variable:
rl_completion_mark_symlink_dirs, allows an application's completion
function to temporarily override the user's preference for appending
slashes to names which are symlinks to directories.
g. New function available to application completion functions:
rl_completion_mode, to tell how the completion function was invoked
and decide which argument to supply to rl_complete_internal (to list
completions, etc.).
h. Readline now has an overwrite mode, toggled by the `overwrite-mode'
bindable command, which could be bound to `Insert'.
i. New application-settable completion variable:
rl_completion_suppress_append, inhibits appending of
rl_completion_append_character to completed words.
j. New key bindings when reading an incremental search string: ^W yanks
the currently-matched word out of the current line into the search
string; ^Y yanks the rest of the current line into the search string,
DEL or ^H deletes characters from the search string.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-4.2a,
and the previous version, readline-4.2.
1. Changes to Readline
a. More `const' and type casting fixes.
b. Changed rl_message() to use vsnprintf(3) (if available) to fix buffer
overflow problems.
c. The completion code no longer appends a `/' or ` ' to a match when
completing a symbolic link that resolves to a directory name, unless
the match does not add anything to the word being completed. This
means that a tab will complete the word up to the full name, but not
add anything, and a subsequent tab will add a slash.
d. Fixed a trivial typo that made the vi-mode `dT' command not work.
e. Fixed the tty code so that ^S and ^Q can be inserted with rl_quoted_insert.
f. Fixed the tty code so that ^V works more than once.
g. Changed the use of __P((...)) for function prototypes to PARAMS((...))
because the use of __P in typedefs conflicted g++ and glibc.
h. The completion code now attempts to do a better job of preserving the
case of the word the user typed if ignoring case in completions.
i. Readline defaults to not echoing the input and lets the terminal
initialization code enable echoing if there is a controlling terminal.
j. The key binding code now processes only two hex digits after a `\x'
escape sequence, and the documentation was changed to note that the
octal and hex escape sequences result in an eight-bit value rather
than strict ASCII.
k. Fixed a few places where negative array subscripts could have occurred.
l. Fixed the vi-mode code to use a better method to determine the bounds of
the array used to hold the marks, and to avoid out-of-bounds references.
m. Fixed the defines in chardefs.h to work better when chars are signed.
n. Fixed configure.in to use the new names for bash autoconf macros.
o. Readline no longer attempts to define its own versions of some ctype
macros if they are implemented as functions in libc but not as macros in
.
p. Fixed a problem where rl_backward could possibly set point to before
the beginning of the line.
q. Fixed Makefile to not put -I/usr/include into CFLAGS, since it can cause
include file problems.
2. New Features in Readline
a. Added extern declaration for rl_get_termcap to readline.h, making it a
public function (it was always there, just not in readline.h).
b. New #defines in readline.h: RL_READLINE_VERSION, currently 0x0402,
RL_VERSION_MAJOR, currently 4, and RL_VERSION_MINOR, currently 2.
c. New readline variable: rl_readline_version, mirrors RL_READLINE_VERSION.
d. New bindable boolean readline variable: match-hidden-files. Controls
completion of files beginning with a `.' (on Unix). Enabled by default.
e. The history expansion code now allows any character to terminate a
`:first-' modifier, like csh.
f. The incremental search code remembers the last search string and uses
it if ^R^R is typed without a search string.
h. New bindable variable `history-preserve-point'. If set, the history
code attempts to place the user at the same location on each history
line retrived with previous-history or next-history.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-4.2,
and the previous version, readline-4.1.
1. Changes to Readline
a. When setting the terminal attributes on systems using `struct termio',
readline waits for output to drain before changing the attributes.
b. A fix was made to the history word tokenization code to avoid attempts to
dereference a null pointer.
c. Readline now defaults rl_terminal_name to $TERM if the calling application
has left it unset, and tries to initialize with the resultant value.
d. Instead of calling (*rl_getc_function)() directly to get input in certain
places, readline now calls rl_read_key() consistently.
e. Fixed a bug in the completion code that allowed a backslash to quote a
single quote inside a single-quoted string.
f. rl_prompt is no longer assigned directly from the argument to readline(),
but uses memory allocated by readline. This allows constant strings to
be passed to readline without problems arising when the prompt processing
code wants to modify the string.
g. Fixed a bug that caused non-interactive history searches to return the
wrong line when performing multiple searches backward for the same string.
h. Many variables, function arguments, and function return values are now
declared `const' where appropriate, to improve behavior when linking with
C++ code.
i. The control character detection code now works better on systems where
`char' is unsigned by default.
j. The vi-mode numeric argument is now capped at 999999, just like emacs mode.
k. The Function, CPFunction, CPPFunction, and VFunction typedefs have been
replaced with a set of specific prototyped typedefs, though they are
still in the readline header files for backwards compatibility.
m. Nearly all of the (undocumented) internal global variables in the library
now have an _rl_ prefix -- there were a number that did not, like
screenheight, screenwidth, alphabetic, etc.
n. The ding() convenience function has been renamed to rl_ding(), though the
old function is still defined for backwards compatibility.
o. The completion convenience functions filename_completion_function,
username_completion_function, and completion_matches now have an rl_
prefix, though the old names are still defined for backwards compatibility.
p. The functions shared by readline and bash (linkage is satisfied from bash
when compiling with bash, and internally otherwise) now have an sh_ prefix.
q. Changed the shared library creation procedure on Linux and BSD/OS 4.x so
that the `soname' contains only the major version number rather than the
major and minor numbers.
r. Fixed a redisplay bug that occurred when the prompt spanned more than one
physical line and contained invisible characters.
s. Added a missing `includedir' variable to the Makefile.
t. When installing the shared libraries, make sure symbolic links are relative.
u. Added configure test so that it can set `${MAKE}' appropriately.
v. Fixed a bug in rl_forward that could cause the point to be set to before
the beginning of the line in vi mode.
w. Fixed a bug in the callback read-char interface to make it work when a
readline function pushes some input onto the input stream with
rl_execute_next (like the incremental search functions).
x. Fixed a file descriptor leak in the history file manipulation code that
was tripped when attempting to truncate a non-regular file (like
/dev/null).
y. Changes to make all of the exported readline functions declared in
readline.h have an rl_ prefix (rltty_set_default_bindings is now
rl_tty_set_default_bindings, crlf is now rl_crlf, etc.)
z. The formatted documentation included in the base readline distribution
is no longer removed on a `make distclean'.
aa. Some changes were made to avoid gcc warnings with -Wall.
bb. rl_get_keymap_by_name now finds keymaps case-insensitively, so
`set keymap EMACS' works.
cc. The history file writing and truncation functions now return a useful
status on error.
dd. Fixed a bug that could cause applications to dereference a NULL pointer
if a NULL second argument was passed to history_expand().
ee. If a hook function assigned to rl_event_hook sets rl_done to a non-zero
value, rl_read_key() now immediately returns '\n' (which is assumed to
be bound to accept-line).
2. New Features in Readline
a. The blink timeout for paren matching is now settable by applications,
via the rl_set_paren_blink_timeout() function.
b. _rl_executing_macro has been renamed to rl_executing_macro, which means
it's now part of the public interface.
c. Readline has a new variable, rl_readline_state, which is a bitmap that
encapsulates the current state of the library; intended for use by
callbacks and hook functions.
d. rlfe has a new -l option to log input and output (-a appends to logfile),
a new -n option to set the readline application name, and -v and -h
options for version and help information.
e. rlfe can now perform filename completion for the inferior process if the
OS has a /proc//cwd that can be read with readlink(2) to get the
inferior's current working directory.
f. A new file, rltypedefs.h, contains the new typedefs for function pointers
and is installed by `make install'.
g. New application-callable function rl_set_prompt(const char *prompt):
expands its prompt string argument and sets rl_prompt to the result.
h. New application-callable function rl_set_screen_size(int rows, int cols):
public method for applications to set readline's idea of the screen
dimensions.
i. The history example program (examples/histexamp.c) is now built as one
of the examples.
j. The documentation has been updated to cover nearly all of the public
functions and variables declared in readline.h.
k. New function, rl_get_screen_size (int *rows, int *columns), returns
readline's idea of the screen dimensions.
l. The timeout in rl_gather_tyi (readline keyboard input polling function)
is now settable via a function (rl_set_keyboard_input_timeout()).
m. Renamed the max_input_history variable to history_max_entries; the old
variable is maintained for backwards compatibility.
n. The list of characters that separate words for the history tokenizer is
now settable with a variable: history_word_delimiters. The default
value is as before.
o. There is a new history.3 manual page documenting the history library.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-4.1,
and the previous version, readline-4.0.
1. Changes to Readline
a. Changed the HTML documents so that the table-of-contents is no longer
a separate file.
b. Changes to the shared object configuration for: Irix 5.x, Irix 6.x,
OSF/1.
c. The shared library major and minor versions are now constructed
automatically by configure and substituted into the makefiles.
d. It's now possible to install the shared libraries separately from the
static libraries.
e. The history library tries to truncate the history file only if it is a
regular file.
f. A bug that caused _rl_dispatch to address negative array indices on
systems with signed chars was fixed.
g. rl-yank-nth-arg now leaves the history position the same as when it was
called.
h. Changes to the completion code to handle MS-DOS drive-letter:pathname
filenames.
i. Completion is now case-insensitive by default on MS-DOS.
j. Fixes to the history file manipulation code for MS-DOS.
k. Readline attempts to bind the arrow keys to appropriate defaults on MS-DOS.
l. Some fixes were made to the redisplay code for better operation on MS-DOS.
m. The quoted-insert code will now insert tty special chars like ^C.
n. A bug was fixed that caused the display code to reference memory before
the start of the prompt string.
o. More support for __EMX__ (OS/2).
p. A bug was fixed in readline's signal handling that could cause infinite
recursion in signal handlers.
q. A bug was fixed that caused the point to be less than zero when rl_forward
was given a very large numeric argument.
r. The vi-mode code now gets characters via the application-settable value
of rl_getc_function rather than calling rl_getc directly.
s. The history file code now uses O_BINARY mode when reading and writing
the history file on cygwin32.
t. Fixed a bug in the redisplay code for lines with more than 256 line
breaks.
u. A bug was fixed which caused invisible character markers to not be
stripped from the prompt string if the terminal was in no-echo mode.
v. Readline no longer tries to get the variables it needs for redisplay
from the termcap entry if the calling application has specified its
own redisplay function. Readline treats the terminal as `dumb' in
this case.
w. Fixes to the SIGWINCH code so that a multiple-line prompt with escape
sequences is redrawn correctly.
x. Changes to the install and install-shared targets so that the libraries
and header files are installed separately.
2. New Features in Readline
a. A new Readline `user manual' is in doc/rluserman.texinfo.
b. Parentheses matching is now always compiled into readline, and enabled
or disabled when the value of the `blink-matching-paren' variable is
changed.
c. MS-DOS systems now use ~/_inputrc as the last-ditch inputrc filename.
d. MS-DOS systems now use ~/_history as the default history file.
e. history-search-{forward,backward} now leave the point at the end of the
line when the string to search for is empty, like
{reverse,forward}-search-history.
f. history-search-{forward,backward} now leave the last history line found
in the readline buffer if the second or subsequent search fails.
g. New function for use by applications: rl_on_new_line_with_prompt, used
when an application displays the prompt itself before calling readline().
h. New variable for use by applications: rl_already_prompted. An application
that displays the prompt itself before calling readline() must set this to
a non-zero value.
i. A new variable, rl_gnu_readline_p, always 1. The intent is that an
application can verify whether or not it is linked with the `real'
readline library or some substitute.
j. Per Bothner's `rlfe' (pronounced `Ralphie') readline front-end program
is included in the examples subdirectory, though it is not built
by default.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-4.0,
and the previous version, readline-2.2.
1. Changes to Readline
a. The version number is now 4.0, to match the major and minor version
numbers on the shared readline and history libraries. Future
releases will maintain the identical numbering.
b. Fixed a typo in the `make install' recipe that copied libreadline.a
to libhistory.old right after installing it.
c. The readline and history info files are now installed out of the source
directory if they are not found in the build directory.
d. The library no longer exports a function named `savestring' -- backwards
compatibility be damned.
e. There is no longer any #ifdef SHELL code in the source files.
f. Some changes were made to the key binding code to fix memory leaks and
better support Win32 systems.
g. Fixed a silly typo in the paren matching code -- it's microseconds, not
milliseconds.
h. The readline library should be compilable by C++ compilers.
i. The readline.h public header file now includes function prototypes for
all readline functions, and some changes were made to fix errors in the
source files uncovered by the use of prototypes.
j. The maximum numeric argument is now clamped at 1000000.
k. Fixes to rl_yank_last_arg to make it behave better.
l. Fixed a bug in the display code that caused core dumps if the prompt
string length exceeded 1024 characters.
m. The menu completion code was fixed to properly insert a single completion
if there is only one match.
n. A bug was fixed that caused the display code to improperly display tabs
after newlines.
o. A fix was made to the completion code in which a typo caused the wrong
value to be passed to the function that computed the longest common
prefix of the list of matches.
p. The completion code now checks the value of rl_filename_completion_desired,
which is set by application-supplied completion functions to indicate
that filename completion is being performed, to decide whether or not to
call an application-supplied `ignore completions' function.
q. Code was added to the history library to catch history substitutions
using `&' without a previous history substitution or search having been
performed.
2. New Features in Readline
a. There is a new script, support/shobj-conf, to do system-specific shared
object and library configuration. It generates variables for configure
to substitute into makefiles. The README file provides a detailed
explanation of the shared library creation process.
b. Shared libraries and objects are now built in the `shlib' subdirectory.
There is a shlib/Makefile.in to control the build process. `make shared'
from the top-level directory is still the right way to build shared
versions of the libraries.
c. rlconf.h is now installed, so applications can find out which features
have been compiled into the installed readline and history libraries.
d. rlstdc.h is now an installed header file.
e. Many changes to the signal handling:
o Readline now catches SIGQUIT and cleans up the tty before returning;
o A new variable, rl_catch_signals, is available to application writers
to indicate to readline whether or not it should install its own
signal handlers for SIGINT, SIGTERM, SIGQUIT, SIGALRM, SIGTSTP,
SIGTTIN, and SIGTTOU;
o A new variable, rl_catch_sigwinch, is available to application
writers to indicate to readline whether or not it should install its
own signal handler for SIGWINCH, which will chain to the calling
applications's SIGWINCH handler, if one is installed;
o There is a new function, rl_free_line_state, for application signal
handlers to call to free up the state associated with the current
line after receiving a signal;
o There is a new function, rl_cleanup_after_signal, to clean up the
display and terminal state after receiving a signal;
o There is a new function, rl_reset_after_signal, to reinitialize the
terminal and display state after an application signal handler
returns and readline continues
f. There is a new function, rl_resize_terminal, to reset readline's idea of
the screen size after a SIGWINCH.
g. New public functions: rl_save_prompt and rl_restore_prompt. These were
previously private functions with a `_' prefix. These functions are
used when an application wants to write a message to the `message area'
with rl_message and have the prompt restored correctly when the message
is erased.
h. New function hook: rl_pre_input_hook, called just before readline starts
reading input, after initialization.
i. New function hook: rl_display_matches_hook, called when readline would
display the list of completion matches. The new function
rl_display_match_list is what readline uses internally, and is available
for use by application functions called via this hook.
j. New bindable function, delete-char-or-list, like tcsh.
k. A new variable, rl_erase_empty_line, which, if set by an application using
readline, will cause readline to erase, prompt and all, lines on which the
only thing typed was a newline.
l. There is a new script, support/shlib-install, to install and uninstall
the shared readline and history libraries.
m. A new bindable variable, `isearch-terminators', which is a string
containing the set of characters that should terminate an incremental
search without being executed as a command.
n. A new bindable function, forward-backward-delete-char.
-------------------------------------------------------------------------------
This document details the changes between this version, readline-2.2,
and the previous version, readline-2.1.
1. Changes to Readline
a. Added a missing `extern' to a declaration in readline.h that kept
readline from compiling cleanly on some systems.
b. The history file is now opened with mode 0600 when it is written for
better security.
c. Changes were made to the SIGWINCH handling code so that prompt redisplay
is done better.
d. ^G now interrupts incremental searches correctly.
e. A bug that caused a core dump when the set of characters to be quoted
when completing words was empty was fixed.
f. Fixed a problem in the readline test program rltest.c that caused a core
dump.
g. The code that handles parser directives in inputrc files now displays
more error messages.
h. The history expansion code was fixed so that the appearance of the
history comment character at the beginning of a word inhibits history
expansion for that word and the rest of the input line.
i. The code that prints completion listings now behaves better if one or
more of the filenames contains non-printable characters.
j. The time delay when showing matching parentheses is now 0.5 seconds.
2. New Features in Readline
a. There is now an option for `iterative' yank-last-arg handline, so a user
can keep entering `M-.', yanking the last argument of successive history
lines.
b. New variable, `print-completions-horizontally', which causes completion
matches to be displayed across the screen (like `ls -x') rather than up
and down the screen (like `ls').
c. New variable, `completion-ignore-case', which causes filename completion
and matching to be performed case-insensitively.
d. There is a new bindable command, `magic-space', which causes history
expansion to be performed on the current readline buffer and a space to
be inserted into the result.
e. There is a new bindable command, `menu-complete', which enables tcsh-like
menu completion (successive executions of menu-complete insert a single
completion match, cycling through the list of possible completions).
f. There is a new bindable command, `paste-from-clipboard', for use on Win32
systems, to insert the text from the Win32 clipboard into the editing
buffer.
g. The key sequence translation code now understands printf-style backslash
escape sequences, including \NNN octal escapes. These escape sequences
may be used in key sequence definitions or macro values.
h. An `$include' inputrc file parser directive has been added.
0707010002ca58000081a40000000000000000000000015424dff700003010000001120001001bffffffffffffffff0000002a00000000root/usr/local/share/doc/readline/INSTALL Basic Installation
==================
These are installation instructions for Readline-6.3.
The simplest way to compile readline is:
1. `cd' to the directory containing the readline source code and type
`./configure' to configure readline for your system. If you're
using `csh' on an old version of System V, you might need to type
`sh ./configure' instead to prevent `csh' from trying to execute
`configure' itself.
Running `configure' takes some time. While running, it prints some
messages telling which features it is checking for.
2. Type `make' to compile readline and build the static readline
and history libraries. If supported, the shared readline and history
libraries will be built also. See below for instructions on compiling
the other parts of the distribution. Typing `make everything' will
cause the static and shared libraries (if supported) and the example
programs to be built.
3. Type `make install' to install the static readline and history
libraries, the readline include files, the documentation, and, if
supported, the shared readline and history libraries.
4. You can remove the created libraries and object files from the
build directory by typing `make clean'. To also remove the
files that `configure' created (so you can compile readline for
a different kind of computer), type `make distclean'. There is
also a `make maintainer-clean' target, but that is intended mainly
for the readline developers, and should be used with care.
The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation. It
uses those values to create a `Makefile' in the build directory,
and Makefiles in the `doc', `shlib', and `examples'
subdirectories. It also creates a `config.h' file containing
system-dependent definitions. Finally, it creates a shell script
`config.status' that you can run in the future to recreate the
current configuration, a file `config.cache' that saves the
results of its tests to speed up reconfiguring, and a file
`config.log' containing compiler output (useful mainly for
debugging `configure').
If you need to do unusual things to compile readline, please try
to figure out how `configure' could check whether to do them, and
mail diffs or instructions to so they can
be considered for the next release. If at some point
`config.cache' contains results you don't want to keep, you may
remove or edit it.
The file `configure.in' is used to create `configure' by a
program called `autoconf'. You only need `configure.in' if you
want to change it or regenerate `configure' using a newer version
of `autoconf'. The readline `configure.in' requires autoconf
version 2.50 or newer.
Compilers and Options
=====================
Some systems require unusual options for compilation or linking that
the `configure' script does not know about. You can give `configure'
initial values for variables by setting them in the environment. Using
a Bourne-compatible shell, you can do that on the command line like
this:
CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
Or on systems that have the `env' program, you can do it like this:
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
Compiling For Multiple Architectures
====================================
You can compile readline for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory. To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'. `cd' to the
directory where you want the object files and executables to go and run
the `configure' script. `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.
If you have to use a `make' that does not supports the `VPATH'
variable, you have to compile readline for one architecture at a
time in the source code directory. After you have installed
readline for one architecture, use `make distclean' before
reconfiguring for another architecture.
Installation Names
==================
By default, `make install' will install the readline libraries in
`/usr/local/lib', the include files in
`/usr/local/include/readline', the man pages in `/usr/local/man',
and the info files in `/usr/local/info'. You can specify an
installation prefix other than `/usr/local' by giving `configure'
the option `--prefix=PATH' or by supplying a value for the
DESTDIR variable when running `make install'.
You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.
If you give `configure' the option `--exec-prefix=PATH', the
readline Makefiles will use PATH as the prefix for installing the
libraries. Documentation and other data files will still use the
regular prefix.
Specifying the System Type
==========================
There may be some features `configure' can not figure out
automatically, but need to determine by the type of host readline
will run on. Usually `configure' can figure that out, but if it
prints a message saying it can not guess the host type, give it
the `--host=TYPE' option. TYPE can either be a short name for
the system type, such as `sun4', or a canonical name with three
fields: CPU-COMPANY-SYSTEM (e.g., i386-unknown-freebsd4.2).
See the file `config.sub' for the possible values of each field.
Sharing Defaults
================
If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists. Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: the readline `configure' looks for a site script, but not
all `configure' scripts do.
Operation Controls
==================
`configure' recognizes the following options to control how it
operates.
`--cache-file=FILE'
Use and save the results of the tests in FILE instead of
`./config.cache'. Set FILE to `/dev/null' to disable caching, for
debugging `configure'.
`--help'
Print a summary of the options to `configure', and exit.
`--quiet'
`--silent'
`-q'
Do not print messages saying which checks are being made.
`--srcdir=DIR'
Look for the package's source code in directory DIR. Usually
`configure' can determine that directory automatically.
`--version'
Print the version of Autoconf used to generate the `configure'
script, and exit.
`configure' also accepts some other, not widely useful, options.
Optional Features
=================
The readline `configure' recognizes a single `--with-PACKAGE' option:
`--with-curses'
This tells readline that it can find the termcap library functions
(tgetent, et al.) in the curses library, rather than a separate
termcap library. Readline uses the termcap functions, but does not
link with the termcap or curses library itself, allowing applications
which link with readline the to choose an appropriate library.
This option tells readline to link the example programs with the
curses library rather than libtermcap.
`configure' also recognizes two `--enable-FEATURE' options:
`--enable-shared'
Build the shared libraries by default on supported platforms. The
default is `yes'.
`--enable-static'
Build the static libraries by default. The default is `yes'.
Shared Libraries
================
There is support for building shared versions of the readline and
history libraries. The configure script creates a Makefile in
the `shlib' subdirectory, and typing `make shared' will cause
shared versions of the readline and history libraries to be built
on supported platforms.
If `configure' is given the `--enable-shared' option, it will attempt
to build the shared libraries by default on supported platforms.
Configure calls the script support/shobj-conf to test whether or
not shared library creation is supported and to generate the values
of variables that are substituted into shlib/Makefile. If you
try to build shared libraries on an unsupported platform, `make'
will display a message asking you to update support/shobj-conf for
your platform.
If you need to update support/shobj-conf, you will need to create
a `stanza' for your operating system and compiler. The script uses
the value of host_os and ${CC} as determined by configure. For
instance, FreeBSD 4.2 with any version of gcc is identified as
`freebsd4.2-gcc*'.
In the stanza for your operating system-compiler pair, you will need to
define several variables. They are:
SHOBJ_CC The C compiler used to compile source files into shareable
object files. This is normally set to the value of ${CC}
by configure, and should not need to be changed.
SHOBJ_CFLAGS Flags to pass to the C compiler ($SHOBJ_CC) to create
position-independent code. If you are using gcc, this
should probably be set to `-fpic'.
SHOBJ_LD The link editor to be used to create the shared library from
the object files created by $SHOBJ_CC. If you are using
gcc, a value of `gcc' will probably work.
SHOBJ_LDFLAGS Flags to pass to SHOBJ_LD to enable shared object creation.
If you are using gcc, `-shared' may be all that is necessary.
These should be the flags needed for generic shared object
creation.
SHLIB_XLDFLAGS Additional flags to pass to SHOBJ_LD for shared library
creation. Many systems use the -R option to the link
editor to embed a path within the library for run-time
library searches. A reasonable value for such systems would
be `-R$(libdir)'.
SHLIB_LIBS Any additional libraries that shared libraries should be
linked against when they are created.
SHLIB_LIBPREF The prefix to use when generating the filename of the shared
library. The default is `lib'; Cygwin uses `cyg'.
SHLIB_LIBSUFF The suffix to add to `libreadline' and `libhistory' when
generating the filename of the shared library. Many systems
use `so'; HP-UX uses `sl'.
SHLIB_LIBVERSION The string to append to the filename to indicate the version
of the shared library. It should begin with $(SHLIB_LIBSUFF),
and possibly include version information that allows the
run-time loader to load the version of the shared library
appropriate for a particular program. Systems using shared
libraries similar to SunOS 4.x use major and minor library
version numbers; for those systems a value of
`$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)$(SHLIB_MINOR)' is appropriate.
Systems based on System V Release 4 don't use minor version
numbers; use `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)' on those systems.
Other Unix versions use different schemes.
SHLIB_DLLVERSION The version number for shared libraries that determines API
compatibility between readline versions and the underlying
system. Used only on Cygwin. Defaults to $SHLIB_MAJOR, but
can be overridden at configuration time by defining DLLVERSION
in the environment.
SHLIB_DOT The character used to separate the name of the shared library
from the suffix and version information. The default is `.';
systems like Cygwin which don't separate version information
from the library name should set this to the empty string.
SHLIB_STATUS Set this to `supported' when you have defined the other
necessary variables. Make uses this to determine whether
or not shared library creation should be attempted. If
shared libraries are not supported, this will be set to
`unsupported'.
You should look at the existing stanzas in support/shobj-conf for ideas.
Once you have updated support/shobj-conf, re-run configure and type
`make shared' or `make'. The shared libraries will be created in the
shlib subdirectory.
If shared libraries are created, `make install' will install them.
You may install only the shared libraries by running `make
install-shared' from the top-level build directory. Running `make
install' in the shlib subdirectory will also work. If you don't want
to install any created shared libraries, run `make install-static'.
0707010002ca59000081a40000000000000000000000015424dff700001f5c000001120001001bffffffffffffffff0000002900000000root/usr/local/share/doc/readline/README Introduction
============
This is the Gnu Readline library, version 6.3.
The Readline library provides a set of functions for use by applications
that allow users to edit command lines as they are typed in. Both
Emacs and vi editing modes are available. The Readline library includes
additional functions to maintain a list of previously-entered command
lines, to recall and perhaps reedit those lines, and perform csh-like
history expansion on previous commands.
The history facilites are also placed into a separate library, the
History library, as part of the build process. The History library
may be used without Readline in applications which desire its
capabilities.
The Readline library is free software, distributed under the terms of
the [GNU] General Public License as published by the Free Software
Foundation, version 3 of the License. For more information, see the
file COPYING.
To build the library, try typing `./configure', then `make'. The
configuration process is automated, so no further intervention should
be necessary. Readline builds with `gcc' by default if it is
available. If you want to use `cc' instead, type
CC=cc ./configure
if you are using a Bourne-style shell. If you are not, the following
may work:
env CC=cc ./configure
Read the file INSTALL in this directory for more information about how
to customize and control the build process.
The file rlconf.h contains C preprocessor defines that enable and disable
certain Readline features.
The special make target `everything' will build the static and shared
libraries (if the target platform supports them) and the examples.
Examples
========
There are several example programs that use Readline features in the
examples directory. The `rl' program is of particular interest. It
is a command-line interface to Readline, suitable for use in shell
scripts in place of `read'.
Shared Libraries
================
There is skeletal support for building shared versions of the
Readline and History libraries. The configure script creates
a Makefile in the `shlib' subdirectory, and typing `make shared'
will cause shared versions of the Readline and History libraries
to be built on supported platforms.
If `configure' is given the `--enable-shared' option, it will attempt
to build the shared libraries by default on supported platforms.
Configure calls the script support/shobj-conf to test whether or
not shared library creation is supported and to generate the values
of variables that are substituted into shlib/Makefile. If you
try to build shared libraries on an unsupported platform, `make'
will display a message asking you to update support/shobj-conf for
your platform.
If you need to update support/shobj-conf, you will need to create
a `stanza' for your operating system and compiler. The script uses
the value of host_os and ${CC} as determined by configure. For
instance, FreeBSD 4.2 with any version of gcc is identified as
`freebsd4.2-gcc*'.
In the stanza for your operating system-compiler pair, you will need to
define several variables. They are:
SHOBJ_CC The C compiler used to compile source files into shareable
object files. This is normally set to the value of ${CC}
by configure, and should not need to be changed.
SHOBJ_CFLAGS Flags to pass to the C compiler ($SHOBJ_CC) to create
position-independent code. If you are using gcc, this
should probably be set to `-fpic'.
SHOBJ_LD The link editor to be used to create the shared library from
the object files created by $SHOBJ_CC. If you are using
gcc, a value of `gcc' will probably work.
SHOBJ_LDFLAGS Flags to pass to SHOBJ_LD to enable shared object creation.
If you are using gcc, `-shared' may be all that is necessary.
These should be the flags needed for generic shared object
creation.
SHLIB_XLDFLAGS Additional flags to pass to SHOBJ_LD for shared library
creation. Many systems use the -R option to the link
editor to embed a path within the library for run-time
library searches. A reasonable value for such systems would
be `-R$(libdir)'.
SHLIB_LIBS Any additional libraries that shared libraries should be
linked against when they are created.
SHLIB_LIBPREF The prefix to use when generating the filename of the shared
library. The default is `lib'; Cygwin uses `cyg'.
SHLIB_LIBSUFF The suffix to add to `libreadline' and `libhistory' when
generating the filename of the shared library. Many systems
use `so'; HP-UX uses `sl'.
SHLIB_LIBVERSION The string to append to the filename to indicate the version
of the shared library. It should begin with $(SHLIB_LIBSUFF),
and possibly include version information that allows the
run-time loader to load the version of the shared library
appropriate for a particular program. Systems using shared
libraries similar to SunOS 4.x use major and minor library
version numbers; for those systems a value of
`$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)$(SHLIB_MINOR)' is appropriate.
Systems based on System V Release 4 don't use minor version
numbers; use `$(SHLIB_LIBSUFF).$(SHLIB_MAJOR)' on those systems.
Other Unix versions use different schemes.
SHLIB_DLLVERSION The version number for shared libraries that determines API
compatibility between readline versions and the underlying
system. Used only on Cygwin. Defaults to $SHLIB_MAJOR, but
can be overridden at configuration time by defining DLLVERSION
in the environment.
SHLIB_DOT The character used to separate the name of the shared library
from the suffix and version information. The default is `.';
systems like Cygwin which don't separate version information
from the library name should set this to the empty string.
SHLIB_STATUS Set this to `supported' when you have defined the other
necessary variables. Make uses this to determine whether
or not shared library creation should be attempted.
You should look at the existing stanzas in support/shobj-conf for ideas.
Once you have updated support/shobj-conf, re-run configure and type
`make shared'. The shared libraries will be created in the shlib
subdirectory.
If shared libraries are created, `make install' will install them.
You may install only the shared libraries by running `make
install-shared' from the top-level build directory. Running `make
install' in the shlib subdirectory will also work. If you don't want
to install any created shared libraries, run `make install-static'.
Documentation
=============
The documentation for the Readline and History libraries appears in
the `doc' subdirectory. There are three texinfo files and a
Unix-style manual page describing the facilities available in the
Readline library. The texinfo files include both user and
programmer's manuals. HTML versions of the manuals appear in the
`doc' subdirectory as well.
Usage
=====
Our position on the use of Readline through a shared-library linking
mechanism is that there is no legal difference between shared-library
linking and static linking--either kind of linking combines various
modules into a single larger work. The conditions for using Readline
in a larger work are stated in section 3 of the GNU GPL.
Reporting Bugs
==============
Bug reports for Readline should be sent to:
bug-readline@gnu.org
When reporting a bug, please include the following information:
* the version number and release status of Readline (e.g., 4.2-release)
* the machine and OS that it is running on
* a list of the compilation flags or the contents of `config.h', if
appropriate
* a description of the bug
* a recipe for recreating the bug reliably
* a fix for the bug if you have one!
If you would like to contact the Readline maintainer directly, send mail
to bash-maintainers@gnu.org.
Since Readline is developed along with bash, the bug-bash@gnu.org mailing
list (mirrored to the Usenet newsgroup gnu.bash.bug) often contains
Readline bug reports and fixes.
Chet Ramey
chet.ramey@case.edu
0707010002ca63000041ed0000000000000000000000025424e06e00000000000001120001001bffffffffffffffff0000001e00000000root/usr/local/share/readline 0707010002ca66000081a40000000000000000000000015424dff700000acf000001120001001bffffffffffffffff0000002f00000000root/usr/local/share/readline/hist_erasedups.c /* hist_erasedups -- remove all duplicate entries from history file */
/* Copyright (C) 2011 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#ifndef READLINE_LIBRARY
#define READLINE_LIBRARY 1
#endif
#include
#include
#include
#ifdef READLINE_LIBRARY
# include "history.h"
#else
# include
#endif
#include
#define STREQ(a, b) ((a)[0] == (b)[0] && strcmp(a, b) == 0)
#define STREQN(a, b, n) ((n == 0) ? (1) \
: ((a)[0] == (b)[0] && strncmp(a, b, n) == 0))
extern int history_offset;
static void
usage()
{
fprintf (stderr, "hist_erasedups: usage: hist_erasedups [-t] [filename]\n");
exit (2);
}
int
main (argc, argv)
int argc;
char **argv;
{
char *fn;
int r;
while ((r = getopt (argc, argv, "t")) != -1)
{
switch (r)
{
case 't':
history_write_timestamps = 1;
break;
default:
usage ();
}
}
argv += optind;
argc -= optind;
fn = argc ? argv[0] : getenv ("HISTFILE");
if (fn == 0)
{
fprintf (stderr, "hist_erasedups: no history file\n");
usage ();
}
if ((r = read_history (fn)) != 0)
{
fprintf (stderr, "hist_erasedups: read_history: %s: %s\n", fn, strerror (r));
exit (1);
}
hist_erasedups ();
if ((r = write_history (fn)) != 0)
{
fprintf (stderr, "hist_erasedups: write_history: %s: %s\n", fn, strerror (r));
exit (1);
}
exit (0);
}
int
hist_erasedups ()
{
int r, n;
HIST_ENTRY *h, *temp;
using_history ();
while (h = previous_history ())
{
r = where_history ();
for (n = 0; n < r; n++)
{
temp = history_get (n+history_base);
if (STREQ (h->line, temp->line))
{
remove_history (n);
r--; /* have to get one fewer now */
n--; /* compensate for above increment */
history_offset--; /* moving backwards in history list */
}
}
}
using_history ();
return r;
}
0707010002ca67000081a40000000000000000000000015424dff700000d22000001120001001bffffffffffffffff0000002e00000000root/usr/local/share/readline/hist_purgecmd.c /* hist_purgecmd -- remove all instances of command or pattern from history
file */
/* Copyright (C) 2011 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#ifndef READLINE_LIBRARY
#define READLINE_LIBRARY 1
#endif
#include
#include
#include
#include
#ifdef READLINE_LIBRARY
# include "history.h"
#else
# include
#endif
#include
#define STREQ(a, b) ((a)[0] == (b)[0] && strcmp(a, b) == 0)
#define STREQN(a, b, n) ((n == 0) ? (1) \
: ((a)[0] == (b)[0] && strncmp(a, b, n) == 0))
extern int history_offset;
#define PURGE_REGEXP 0x01
static void
usage()
{
fprintf (stderr, "hist_purgecmd: usage: hist_purgecmd [-r] [-t] [-f filename] command-spec\n");
exit (2);
}
int
main (argc, argv)
int argc;
char **argv;
{
char *fn;
int r, flags;
flags = 0;
fn = 0;
while ((r = getopt (argc, argv, "f:rt")) != -1)
{
switch (r)
{
case 'f':
fn = optarg;
break;
case 'r':
flags |= PURGE_REGEXP;
break;
case 't':
history_write_timestamps = 1;
break;
default:
usage ();
}
}
argv += optind;
argc -= optind;
if (fn == 0)
fn = getenv ("HISTFILE");
if (fn == 0)
{
fprintf (stderr, "hist_purgecmd: no history file\n");
usage ();
}
if ((r = read_history (fn)) != 0)
{
fprintf (stderr, "hist_purgecmd: read_history: %s: %s\n", fn, strerror (r));
exit (1);
}
for (r = 0; r < argc; r++)
hist_purgecmd (argv[r], flags);
if ((r = write_history (fn)) != 0)
{
fprintf (stderr, "hist_purgecmd: write_history: %s: %s\n", fn, strerror (r));
exit (1);
}
exit (0);
}
int
hist_purgecmd (cmd, flags)
char *cmd;
int flags;
{
int r, n, rflags;
HIST_ENTRY *temp;
regex_t regex = { 0 };
if (flags & PURGE_REGEXP)
{
rflags = REG_EXTENDED|REG_NOSUB;
if (regcomp (®ex, cmd, rflags))
{
fprintf (stderr, "hist_purgecmd: %s: invalid regular expression\n", cmd);
return -1;
}
}
r = 0;
using_history ();
r = where_history ();
for (n = 0; n < r; n++)
{
temp = history_get (n+history_base);
if (((flags & PURGE_REGEXP) && (regexec (®ex, temp->line, 0, 0, 0) == 0)) ||
((flags & PURGE_REGEXP) == 0 && STREQ (temp->line, cmd)))
{
remove_history (n);
r--; /* have to get one fewer now */
n--; /* compensate for above increment */
history_offset--; /* moving backwards in history list */
}
}
using_history ();
if (flags & PURGE_REGEXP)
regfree (®ex);
return r;
}
0707010002ca6c000081a40000000000000000000000015424dff700000c6b000001120001001bffffffffffffffff0000002300000000root/usr/local/share/readline/rl.c /*
* rl - command-line interface to read a line from the standard input
* (or another fd) using readline.
*
* usage: rl [-p prompt] [-u unit] [-d default] [-n nchars]
*/
/* Copyright (C) 1987-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#if defined (HAVE_CONFIG_H)
# include
#endif
#include
#include
#ifdef HAVE_STDLIB_H
# include
#else
extern void exit();
#endif
#if defined (READLINE_LIBRARY)
# include "posixstat.h"
# include "readline.h"
# include "history.h"
#else
# include
# include
# include
#endif
extern int optind;
extern char *optarg;
#if !defined (strchr) && !defined (__STDC__)
extern char *strrchr();
#endif
static char *progname;
static char *deftext;
static int
set_deftext ()
{
if (deftext)
{
rl_insert_text (deftext);
deftext = (char *)NULL;
rl_startup_hook = (rl_hook_func_t *)NULL;
}
return 0;
}
static void
usage()
{
fprintf (stderr, "%s: usage: %s [-p prompt] [-u unit] [-d default] [-n nchars]\n",
progname, progname);
}
int
main (argc, argv)
int argc;
char **argv;
{
char *temp, *prompt;
struct stat sb;
int opt, fd, nch;
FILE *ifp;
progname = strrchr(argv[0], '/');
if (progname == 0)
progname = argv[0];
else
progname++;
/* defaults */
prompt = "readline$ ";
fd = nch = 0;
deftext = (char *)0;
while ((opt = getopt(argc, argv, "p:u:d:n:")) != EOF)
{
switch (opt)
{
case 'p':
prompt = optarg;
break;
case 'u':
fd = atoi(optarg);
if (fd < 0)
{
fprintf (stderr, "%s: bad file descriptor `%s'\n", progname, optarg);
exit (2);
}
break;
case 'd':
deftext = optarg;
break;
case 'n':
nch = atoi(optarg);
if (nch < 0)
{
fprintf (stderr, "%s: bad value for -n: `%s'\n", progname, optarg);
exit (2);
}
break;
default:
usage ();
exit (2);
}
}
if (fd != 0)
{
if (fstat (fd, &sb) < 0)
{
fprintf (stderr, "%s: %d: bad file descriptor\n", progname, fd);
exit (1);
}
ifp = fdopen (fd, "r");
rl_instream = ifp;
}
if (deftext && *deftext)
rl_startup_hook = set_deftext;
if (nch > 0)
rl_num_chars_to_read = nch;
temp = readline (prompt);
/* Test for EOF. */
if (temp == 0)
exit (1);
printf ("%s\n", temp);
exit (0);
}
0707010002ca70000081a40000000000000000000000015424dff700000862000001120001001bffffffffffffffff0000002700000000root/usr/local/share/readline/rltest.c /* **************************************************************** */
/* */
/* Testing Readline */
/* */
/* **************************************************************** */
/* Copyright (C) 1987-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#if defined (HAVE_CONFIG_H)
#include
#endif
#include
#include
#ifdef HAVE_STDLIB_H
# include
#else
extern void exit();
#endif
#ifdef READLINE_LIBRARY
# include "readline.h"
# include "history.h"
#else
# include
# include
#endif
extern HIST_ENTRY **history_list ();
main ()
{
char *temp, *prompt;
int done;
temp = (char *)NULL;
prompt = "readline$ ";
done = 0;
while (!done)
{
temp = readline (prompt);
/* Test for EOF. */
if (!temp)
exit (1);
/* If there is anything on the line, print it and remember it. */
if (*temp)
{
fprintf (stderr, "%s\r\n", temp);
add_history (temp);
}
/* Check for `command' that we handle. */
if (strcmp (temp, "quit") == 0)
done = 1;
if (strcmp (temp, "list") == 0)
{
HIST_ENTRY **list;
register int i;
list = history_list ();
if (list)
{
for (i = 0; list[i]; i++)
fprintf (stderr, "%d: %s\r\n", i, list[i]->line);
}
}
free (temp);
}
exit (0);
}
0707010002ca68000081a40000000000000000000000015424dff700000b49000001120001001bffffffffffffffff0000002a00000000root/usr/local/share/readline/histexamp.c /* histexamp.c - history library example program. */
/* Copyright (C) 1987-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#include
#ifdef READLINE_LIBRARY
# include "history.h"
#else
# include
#endif
#include
main (argc, argv)
int argc;
char **argv;
{
char line[1024], *t;
int len, done;
line[0] = 0;
done = 0;
using_history ();
while (!done)
{
printf ("history$ ");
fflush (stdout);
t = fgets (line, sizeof (line) - 1, stdin);
if (t && *t)
{
len = strlen (t);
if (t[len - 1] == '\n')
t[len - 1] = '\0';
}
if (!t)
strcpy (line, "quit");
if (line[0])
{
char *expansion;
int result;
using_history ();
result = history_expand (line, &expansion);
if (result)
fprintf (stderr, "%s\n", expansion);
if (result < 0 || result == 2)
{
free (expansion);
continue;
}
add_history (expansion);
strncpy (line, expansion, sizeof (line) - 1);
free (expansion);
}
if (strcmp (line, "quit") == 0)
done = 1;
else if (strcmp (line, "save") == 0)
write_history ("history_file");
else if (strcmp (line, "read") == 0)
read_history ("history_file");
else if (strcmp (line, "list") == 0)
{
register HIST_ENTRY **the_list;
register int i;
time_t tt;
char timestr[128];
the_list = history_list ();
if (the_list)
for (i = 0; the_list[i]; i++)
{
tt = history_get_time (the_list[i]);
if (tt)
strftime (timestr, sizeof (timestr), "%a %R", localtime(&tt));
else
strcpy (timestr, "??");
printf ("%d: %s: %s\n", i + history_base, timestr, the_list[i]->line);
}
}
else if (strncmp (line, "delete", 6) == 0)
{
int which;
if ((sscanf (line + 6, "%d", &which)) == 1)
{
HIST_ENTRY *entry = remove_history (which);
if (!entry)
fprintf (stderr, "No such entry %d\n", which);
else
{
free (entry->line);
free (entry);
}
}
else
{
fprintf (stderr, "non-numeric arg given to `delete'\n");
}
}
}
}
0707010002ca6a000081a40000000000000000000000015424dff7000007f6000001120001001bffffffffffffffff0000003000000000root/usr/local/share/readline/rl-callbacktest.c /* Standard include files. stdio.h is required. */
#include
#include
#include
/* Used for select(2) */
#include
#include
#include
/* Standard readline include files. */
#if defined (READLINE_LIBRARY)
# include "readline.h"
# include "history.h"
#else
# include
# include
#endif
static void cb_linehandler (char *);
int running;
const char *prompt = "rltest$ ";
/* Callback function called for each line when accept-line executed, EOF
seen, or EOF character read. This sets a flag and returns; it could
also call exit(3). */
static void
cb_linehandler (char *line)
{
/* Can use ^D (stty eof) or `exit' to exit. */
if (line == NULL || strcmp (line, "exit") == 0)
{
if (line == 0)
printf ("\n");
printf ("exit\n");
/* This function needs to be called to reset the terminal settings,
and calling it from the line handler keeps one extra prompt from
being displayed. */
rl_callback_handler_remove ();
running = 0;
}
else
{
if (*line)
add_history (line);
printf ("input line: %s\n", line);
free (line);
}
}
int
main (int c, char **v)
{
fd_set fds;
int r;
/* Install the line handler. */
rl_callback_handler_install (prompt, cb_linehandler);
/* Enter a simple event loop. This waits until something is available
to read on readline's input stream (defaults to standard input) and
calls the builtin character read callback to read it. It does not
have to modify the user's terminal settings. */
running = 1;
while (running)
{
FD_ZERO (&fds);
FD_SET (fileno (rl_instream), &fds);
r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
if (r < 0)
{
perror ("rltest: select");
rl_callback_handler_remove ();
break;
}
if (FD_ISSET (fileno (rl_instream), &fds))
rl_callback_read_char ();
}
printf ("rltest: Event loop has exited\n");
return 0;
}
0707010002ca65000081a40000000000000000000000015424dff700002ca2000001120001001bffffffffffffffff0000002800000000root/usr/local/share/readline/fileman.c /* fileman.c - file manager example for readline library. */
/* Copyright (C) 1987-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
/* fileman.c -- A tiny application which demonstrates how to use the
GNU Readline library. This application interactively allows users
to manipulate files and their modes. */
#ifdef HAVE_CONFIG_H
# include
#endif
#include
#ifdef HAVE_SYS_FILE_H
# include
#endif
#include
#ifdef HAVE_UNISTD_H
# include
#endif
#include
#include
#include
#if defined (HAVE_STRING_H)
# include
#else /* !HAVE_STRING_H */
# include
#endif /* !HAVE_STRING_H */
#ifdef HAVE_STDLIB_H
# include
#endif
#include
#ifdef READLINE_LIBRARY
# include "readline.h"
# include "history.h"
#else
# include
# include
#endif
extern char *xmalloc PARAMS((size_t));
/* The names of functions that actually do the manipulation. */
int com_list PARAMS((char *));
int com_view PARAMS((char *));
int com_rename PARAMS((char *));
int com_stat PARAMS((char *));
int com_pwd PARAMS((char *));
int com_delete PARAMS((char *));
int com_help PARAMS((char *));
int com_cd PARAMS((char *));
int com_quit PARAMS((char *));
/* A structure which contains information on the commands this program
can understand. */
typedef struct {
char *name; /* User printable name of the function. */
rl_icpfunc_t *func; /* Function to call to do the job. */
char *doc; /* Documentation for this function. */
} COMMAND;
COMMAND commands[] = {
{ "cd", com_cd, "Change to directory DIR" },
{ "delete", com_delete, "Delete FILE" },
{ "help", com_help, "Display this text" },
{ "?", com_help, "Synonym for `help'" },
{ "list", com_list, "List files in DIR" },
{ "ls", com_list, "Synonym for `list'" },
{ "pwd", com_pwd, "Print the current working directory" },
{ "quit", com_quit, "Quit using Fileman" },
{ "rename", com_rename, "Rename FILE to NEWNAME" },
{ "stat", com_stat, "Print out statistics on FILE" },
{ "view", com_view, "View the contents of FILE" },
{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL }
};
/* Forward declarations. */
char *stripwhite ();
COMMAND *find_command ();
/* The name of this program, as taken from argv[0]. */
char *progname;
/* When non-zero, this global means the user is done using this program. */
int done;
char *
dupstr (s)
char *s;
{
char *r;
r = xmalloc (strlen (s) + 1);
strcpy (r, s);
return (r);
}
main (argc, argv)
int argc;
char **argv;
{
char *line, *s;
progname = argv[0];
initialize_readline (); /* Bind our completer. */
/* Loop reading and executing lines until the user quits. */
for ( ; done == 0; )
{
line = readline ("FileMan: ");
if (!line)
break;
/* Remove leading and trailing whitespace from the line.
Then, if there is anything left, add it to the history list
and execute it. */
s = stripwhite (line);
if (*s)
{
add_history (s);
execute_line (s);
}
free (line);
}
exit (0);
}
/* Execute a command line. */
int
execute_line (line)
char *line;
{
register int i;
COMMAND *command;
char *word;
/* Isolate the command word. */
i = 0;
while (line[i] && whitespace (line[i]))
i++;
word = line + i;
while (line[i] && !whitespace (line[i]))
i++;
if (line[i])
line[i++] = '\0';
command = find_command (word);
if (!command)
{
fprintf (stderr, "%s: No such command for FileMan.\n", word);
return (-1);
}
/* Get argument to command, if any. */
while (whitespace (line[i]))
i++;
word = line + i;
/* Call the function. */
return ((*(command->func)) (word));
}
/* Look up NAME as the name of a command, and return a pointer to that
command. Return a NULL pointer if NAME isn't a command name. */
COMMAND *
find_command (name)
char *name;
{
register int i;
for (i = 0; commands[i].name; i++)
if (strcmp (name, commands[i].name) == 0)
return (&commands[i]);
return ((COMMAND *)NULL);
}
/* Strip whitespace from the start and end of STRING. Return a pointer
into STRING. */
char *
stripwhite (string)
char *string;
{
register char *s, *t;
for (s = string; whitespace (*s); s++)
;
if (*s == 0)
return (s);
t = s + strlen (s) - 1;
while (t > s && whitespace (*t))
t--;
*++t = '\0';
return s;
}
/* **************************************************************** */
/* */
/* Interface to Readline Completion */
/* */
/* **************************************************************** */
char *command_generator PARAMS((const char *, int));
char **fileman_completion PARAMS((const char *, int, int));
/* Tell the GNU Readline library how to complete. We want to try to complete
on command names if this is the first word in the line, or on filenames
if not. */
initialize_readline ()
{
/* Allow conditional parsing of the ~/.inputrc file. */
rl_readline_name = "FileMan";
/* Tell the completer that we want a crack first. */
rl_attempted_completion_function = fileman_completion;
}
/* Attempt to complete on the contents of TEXT. START and END bound the
region of rl_line_buffer that contains the word to complete. TEXT is
the word to complete. We can use the entire contents of rl_line_buffer
in case we want to do some simple parsing. Return the array of matches,
or NULL if there aren't any. */
char **
fileman_completion (text, start, end)
const char *text;
int start, end;
{
char **matches;
matches = (char **)NULL;
/* If this word is at the start of the line, then it is a command
to complete. Otherwise it is the name of a file in the current
directory. */
if (start == 0)
matches = rl_completion_matches (text, command_generator);
return (matches);
}
/* Generator function for command completion. STATE lets us know whether
to start from scratch; without any state (i.e. STATE == 0), then we
start at the top of the list. */
char *
command_generator (text, state)
const char *text;
int state;
{
static int list_index, len;
char *name;
/* If this is a new word to complete, initialize now. This includes
saving the length of TEXT for efficiency, and initializing the index
variable to 0. */
if (!state)
{
list_index = 0;
len = strlen (text);
}
/* Return the next name which partially matches from the command list. */
while (name = commands[list_index].name)
{
list_index++;
if (strncmp (name, text, len) == 0)
return (dupstr(name));
}
/* If no names matched, then return NULL. */
return ((char *)NULL);
}
/* **************************************************************** */
/* */
/* FileMan Commands */
/* */
/* **************************************************************** */
/* String to pass to system (). This is for the LIST, VIEW and RENAME
commands. */
static char syscom[1024];
/* List the file(s) named in arg. */
com_list (arg)
char *arg;
{
if (!arg)
arg = "";
sprintf (syscom, "ls -FClg %s", arg);
return (system (syscom));
}
com_view (arg)
char *arg;
{
if (!valid_argument ("view", arg))
return 1;
#if defined (__MSDOS__)
/* more.com doesn't grok slashes in pathnames */
sprintf (syscom, "less %s", arg);
#else
sprintf (syscom, "more %s", arg);
#endif
return (system (syscom));
}
com_rename (arg)
char *arg;
{
too_dangerous ("rename");
return (1);
}
com_stat (arg)
char *arg;
{
struct stat finfo;
if (!valid_argument ("stat", arg))
return (1);
if (stat (arg, &finfo) == -1)
{
perror (arg);
return (1);
}
printf ("Statistics for `%s':\n", arg);
printf ("%s has %d link%s, and is %d byte%s in length.\n",
arg,
finfo.st_nlink,
(finfo.st_nlink == 1) ? "" : "s",
finfo.st_size,
(finfo.st_size == 1) ? "" : "s");
printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
printf (" Last access at: %s", ctime (&finfo.st_atime));
printf (" Last modified at: %s", ctime (&finfo.st_mtime));
return (0);
}
com_delete (arg)
char *arg;
{
too_dangerous ("delete");
return (1);
}
/* Print out help for ARG, or for all of the commands if ARG is
not present. */
com_help (arg)
char *arg;
{
register int i;
int printed = 0;
for (i = 0; commands[i].name; i++)
{
if (!*arg || (strcmp (arg, commands[i].name) == 0))
{
printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
printed++;
}
}
if (!printed)
{
printf ("No commands match `%s'. Possibilties are:\n", arg);
for (i = 0; commands[i].name; i++)
{
/* Print in six columns. */
if (printed == 6)
{
printed = 0;
printf ("\n");
}
printf ("%s\t", commands[i].name);
printed++;
}
if (printed)
printf ("\n");
}
return (0);
}
/* Change to the directory ARG. */
com_cd (arg)
char *arg;
{
if (chdir (arg) == -1)
{
perror (arg);
return 1;
}
com_pwd ("");
return (0);
}
/* Print out the current working directory. */
com_pwd (ignore)
char *ignore;
{
char dir[1024], *s;
s = getcwd (dir, sizeof(dir) - 1);
if (s == 0)
{
printf ("Error getting pwd: %s\n", dir);
return 1;
}
printf ("Current directory is %s\n", dir);
return 0;
}
/* The user wishes to quit using this program. Just set DONE non-zero. */
com_quit (arg)
char *arg;
{
done = 1;
return (0);
}
/* Function which tells you that you can't do this. */
too_dangerous (caller)
char *caller;
{
fprintf (stderr,
"%s: Too dangerous for me to distribute. Write it yourself.\n",
caller);
}
/* Return non-zero if ARG is a valid argument for CALLER, else print
an error message and return zero. */
int
valid_argument (caller, arg)
char *caller, *arg;
{
if (!arg || !*arg)
{
fprintf (stderr, "%s: Argument required.\n", caller);
return (0);
}
return (1);
}
0707010002ca6b000081a40000000000000000000000015424dff700002b8b000001120001001bffffffffffffffff0000002900000000root/usr/local/share/readline/rl-fgets.c /*
Date: Tue, 16 Mar 2004 19:38:40 -0800
From: Harold Levy
Subject: fgets(stdin) --> readline() redirector
To: chet@po.cwru.edu
Hi Chet,
Here is something you may find useful enough to include in the readline
distribution. It is a shared library that redirects calls to fgets(stdin)
to readline() via LD_PRELOAD, and it supports a custom prompt and list of
command names. Many people have asked me for this file, so I thought I'd
pass it your way in hope of just including it with readline to begin with.
Best Regards,
-Harold
*/
/******************************************************************************
*******************************************************************************
FILE NAME: fgets.c TARGET: libfgets.so
AUTHOR: Harold Levy VERSION: 1.0
hlevy@synopsys.com
ABSTRACT: Customize fgets() behavior via LD_PRELOAD in the following ways:
-- If fgets(stdin) is called, redirect to GNU readline() to obtain
command-line editing, file-name completion, history, etc.
-- A list of commands for command-name completion can be configured by
setting the environment-variable FGETS_COMMAND_FILE to a file containing
the list of commands to be used.
-- Command-line editing with readline() works best when the prompt string
is known; you can set this with the FGETS_PROMPT environment variable.
-- There special strings that libfgets will interpret as internal commands:
_fgets_reset_ reset the command list
_fgets_dump_ dump status
_fgets_debug_ toggle debug messages
HOW TO BUILD: Here are examples of how to build libfgets.so on various
platforms; you will have to add -I and -L flags to configure access to
the readline header and library files.
(32-bit builds with gcc)
AIX: gcc -fPIC fgets.c -shared -o libfgets.so -lc -ldl -lreadline -ltermcap
HP-UX: gcc -fPIC fgets.c -shared -o libfgets.so -lc -ldld -lreadline
Linux: gcc -fPIC fgets.c -shared -o libfgets.so -lc -ldl -lreadline
SunOS: gcc -fPIC fgets.c -shared -o libfgets.so -lc -ldl -lgen -lreadline
(64-bit builds without gcc)
SunOS: SUNWspro/bin/cc -D_LARGEFILE64_SOURCE=1 -xtarget=ultra -xarch=v9 \
-KPIC fgets.c -Bdynamic -lc -ldl -lgen -ltermcap -lreadline
HOW TO USE: Different operating systems have different levels of support
for the LD_PRELOAD concept. The generic method for 32-bit platforms is to
put libtermcap.so, libfgets.so, and libreadline.so (with absolute paths)
in the LD_PRELOAD environment variable, and to put their parent directories
in the LD_LIBRARY_PATH environment variable. Unfortunately there is no
generic method for 64-bit platforms; e.g. for 64-bit SunOS, you would have
to build both 32-bit and 64-bit libfgets and libreadline libraries, and
use the LD_FLAGS_32 and LD_FLAGS_64 environment variables with preload and
library_path configurations (a mix of 32-bit and 64-bit calls are made under
64-bit SunOS).
EXAMPLE WRAPPER: Here is an example shell script wrapper around the
program "foo" that uses fgets() for command-line input:
#!/bin/csh
#### replace this with the libtermcap.so directory:
set dir1 = "/usr/lib"
#### replace this with the libfgets.so directory:
set dir2 = "/usr/fgets"
#### replace this with the libreadline.so directory:
set dir3 = "/usr/local/lib"
set lib1 = "${dir1}/libtermcap.so"
set lib2 = "${dir2}/libfgets.so"
set lib3 = "${dir3}/libreadline.so"
if ( "${?LD_PRELOAD}" ) then
setenv LD_PRELOAD "${lib1}:${lib2}:${lib3}:${LD_PRELOAD}"
else
setenv LD_PRELOAD "${lib1}:${lib2}:${lib3}"
endif
if ( "${?LD_LIBRARY_PATH}" ) then
setenv LD_LIBRARY_PATH "${dir1}:${dir2}:${dir3}:${LD_LIBRARY_PATH}"
else
setenv LD_LIBRARY_PATH "${dir1}:${dir2}:${dir3}"
endif
setenv FGETS_COMMAND_FILE "${dir2}/foo.commands"
setenv FGETS_PROMPT "foo> "
exec "foo" $*
Copyright (C)2003-2004 Harold Levy.
This code links to the GNU readline library, and as such is bound by the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 2 or (at your option) any later version.
The GNU General Public License is often shipped with GNU software, and is
generally kept in a file called COPYING or LICENSE. If you do not have a
copy of the license, write to the Free Software Foundation, 59 Temple Place,
Suite 330, Boston, MA 02111 USA.
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.
*******************************************************************************
******************************************************************************/
#include
#include
#include
#include
#include
#include
#include
/* for dynamically connecting to the native fgets() */
#if defined(RTLD_NEXT)
#define REAL_LIBC RTLD_NEXT
#else
#define REAL_LIBC ((void *) -1L)
#endif
typedef char * ( * fgets_t ) ( char * s, int n, FILE * stream ) ;
/* private data */
/* -- writeable data is stored in the shared library's data segment
-- every process that uses the shared library gets a private memory copy of
its entire data segment
-- static data in the shared library is not copied to the application
-- only read-only (i.e. 'const') data is stored in the shared library's
text segment
*/
static char ** my_fgets_names = NULL ;
static int my_fgets_number_of_names = 0 ;
static int my_fgets_debug_flag = 0 ;
/* invoked with _fgets_reset_ */
static void
my_fgets_reset (
void
) {
if ( my_fgets_names && (my_fgets_number_of_names > 0) ) {
int i ;
if ( my_fgets_debug_flag ) {
printf ( "libfgets: removing command list\n" ) ;
}
for ( i = 0 ; i < my_fgets_number_of_names ; i ++ ) {
if ( my_fgets_names[i] ) free ( my_fgets_names[i] ) ;
}
free ( my_fgets_names ) ;
}
my_fgets_names = NULL ;
my_fgets_number_of_names = 0 ;
}
/* invoked with _fgets_dump_ */
static void
my_fgets_dump (
void
) {
char * s ;
printf ( "\n" ) ;
s = getenv ( "FGETS_PROMPT" ) ;
printf ( "FGETS_PROMPT = %s\n", s ? s : "" ) ;
s = getenv ( "FGETS_COMMAND_FILE" ) ;
printf ( "FGETS_COMMAND_FILE = %s\n", s ? s : "" ) ;
printf ( "debug flag = %d\n", my_fgets_debug_flag ) ;
printf ( "#commands = %d\n", my_fgets_number_of_names ) ;
if ( my_fgets_debug_flag ) {
if ( my_fgets_names && (my_fgets_number_of_names > 0) ) {
int i ;
for ( i = 0 ; i < my_fgets_number_of_names ; i ++ ) {
printf ( "%s\n", my_fgets_names[i] ) ;
}
}
}
printf ( "\n" ) ;
}
/* invoked with _fgets_debug_ */
static void
my_fgets_debug_toggle (
void
) {
my_fgets_debug_flag = my_fgets_debug_flag ? 0 : 1 ;
if ( my_fgets_debug_flag ) {
printf ( "libfgets: debug flag = %d\n", my_fgets_debug_flag ) ;
}
}
/* read the command list if needed, return the i-th name */
static char *
my_fgets_lookup (
int index
) {
if ( (! my_fgets_names) || (! my_fgets_number_of_names) ) {
char * fname ;
FILE * fp ;
fgets_t _fgets ;
int i ;
char buf1[256], buf2[256] ;
fname = getenv ( "FGETS_COMMAND_FILE" ) ;
if ( ! fname ) {
if ( my_fgets_debug_flag ) {
printf ( "libfgets: empty or unset FGETS_COMMAND_FILE\n" ) ;
}
return NULL ;
}
fp = fopen ( fname, "r" ) ;
if ( ! fp ) {
if ( my_fgets_debug_flag ) {
printf ( "libfgets: cannot open '%s' for reading\n", fname ) ;
}
return NULL ;
}
_fgets = (fgets_t) dlsym ( REAL_LIBC, "fgets" ) ;
if ( ! _fgets ) {
fprintf ( stderr,
"libfgets: failed to dynamically link to native fgets()\n"
) ;
return NULL ;
}
for ( i = 0 ; _fgets(buf1,255,fp) ; i ++ ) ;
if ( ! i ) { fclose(fp) ; return NULL ; }
my_fgets_names = (char**) calloc ( i, sizeof(char*) ) ;
rewind ( fp ) ;
i = 0 ;
while ( _fgets(buf1,255,fp) ) {
buf1[255] = 0 ;
if ( 1 == sscanf(buf1,"%s",buf2) ) {
my_fgets_names[i] = strdup(buf2) ;
i ++ ;
}
}
fclose ( fp ) ;
my_fgets_number_of_names = i ;
if ( my_fgets_debug_flag ) {
printf ( "libfgets: successfully read %d commands\n", i ) ;
}
}
if ( index < my_fgets_number_of_names ) {
return my_fgets_names[index] ;
} else {
return NULL ;
}
}
/* generate a list of partial name matches for readline() */
static char *
my_fgets_generator (
const char * text,
int state
)
{
static int list_index, len ;
char * name ;
if ( ! state ) {
list_index = 0 ;
len = strlen ( text ) ;
}
while ( ( name = my_fgets_lookup(list_index) ) ) {
list_index ++ ;
if ( ! strncmp ( name, text, len ) ) {
return ( strdup ( name ) ) ;
}
}
return ( NULL ) ;
}
/* partial name completion callback for readline() */
static char **
my_fgets_completion (
const char * text,
int start,
int end
)
{
char ** matches ;
matches = NULL ;
if ( ! start ) {
matches = rl_completion_matches ( text, my_fgets_generator ) ;
}
return ( matches ) ;
}
/* fgets() intercept */
char *
fgets (
char * s,
int n,
FILE * stream
)
{
if ( ! s ) return NULL ;
if ( stream == stdin ) {
char * prompt ;
char * my_fgets_line ;
rl_already_prompted = 1 ;
rl_attempted_completion_function = my_fgets_completion ;
rl_catch_signals = 1 ;
rl_catch_sigwinch = 1 ;
rl_set_signals () ;
prompt = getenv ( "FGETS_PROMPT" ) ;
for (
my_fgets_line = 0 ; ! my_fgets_line ; my_fgets_line=readline(prompt)
) ;
if ( ! strncmp(my_fgets_line, "_fgets_reset_", 13) ) {
my_fgets_reset () ;
free ( my_fgets_line ) ;
strcpy ( s, "\n" ) ;
return ( s ) ;
}
if ( ! strncmp(my_fgets_line, "_fgets_dump_", 12) ) {
my_fgets_dump () ;
free ( my_fgets_line ) ;
strcpy ( s, "\n" ) ;
return ( s ) ;
}
if ( ! strncmp(my_fgets_line, "_fgets_debug_", 13) ) {
my_fgets_debug_toggle () ;
free ( my_fgets_line ) ;
strcpy ( s, "\n" ) ;
return ( s ) ;
}
(void) strncpy ( s, my_fgets_line, n-1 ) ;
(void) strcat ( s, "\n" ) ;
if ( *my_fgets_line ) add_history ( my_fgets_line ) ;
free ( my_fgets_line ) ;
return ( s ) ;
} else {
static fgets_t _fgets ;
_fgets = (fgets_t) dlsym ( REAL_LIBC, "fgets" ) ;
if ( ! _fgets ) {
fprintf ( stderr,
"libfgets: failed to dynamically link to native fgets()\n"
) ;
strcpy ( s, "\n" ) ;
return ( s ) ;
}
return (
_fgets ( s, n, stream )
) ;
}
}
0707010002ca64000081a40000000000000000000000015424dff7000016b0000001120001001bffffffffffffffff0000002b00000000root/usr/local/share/readline/excallback.c /*
From: Jeff Solomon
Date: Fri, 9 Apr 1999 10:13:27 -0700 (PDT)
To: chet@po.cwru.edu
Subject: new readline example
Message-ID: <14094.12094.527305.199695@mrclean.Stanford.EDU>
Chet,
I've been using readline 4.0. Specifically, I've been using the perl
version Term::ReadLine::Gnu. It works great.
Anyway, I've been playing around the alternate interface and I wanted
to contribute a little C program, callback.c, to you that you could
use as an example of the alternate interface in the /examples
directory of the readline distribution.
My example shows how, using the alternate interface, you can
interactively change the prompt (which is very nice imo). Also, I
point out that you must roll your own terminal setting when using the
alternate interface because readline depreps (using your parlance) the
terminal while in the user callback. I try to demostrate what I mean
with an example. I've included the program below.
To compile, I just put the program in the examples directory and made
the appropriate changes to the EXECUTABLES and OBJECTS line and added
an additional target 'callback'.
I compiled on my Sun Solaris2.6 box using Sun's cc.
Let me know what you think.
Jeff
*/
/*
Copyright (C) 1999 Jeff Solomon
*/
#if defined (HAVE_CONFIG_H)
#include
#endif
#include
#ifdef HAVE_UNISTD_H
#include
#endif
#include
#include
#include /* xxx - should make this more general */
#ifdef READLINE_LIBRARY
# include "readline.h"
#else
# include
#endif
#ifndef STDIN_FILENO
# define STDIN_FILENO 0
#endif
/* This little examples demonstrates the alternate interface to using readline.
* In the alternate interface, the user maintains control over program flow and
* only calls readline when STDIN is readable. Using the alternate interface,
* you can do anything else while still using readline (like talking to a
* network or another program) without blocking.
*
* Specifically, this program highlights two importants features of the
* alternate interface. The first is the ability to interactively change the
* prompt, which can't be done using the regular interface since rl_prompt is
* read-only.
*
* The second feature really highlights a subtle point when using the alternate
* interface. That is, readline will not alter the terminal when inside your
* callback handler. So let's so, your callback executes a user command that
* takes a non-trivial amount of time to complete (seconds). While your
* executing the command, the user continues to type keystrokes and expects them
* to be re-echoed on the new prompt when it returns. Unfortunately, the default
* terminal configuration doesn't do this. After the prompt returns, the user
* must hit one additional keystroke and then will see all of his previous
* keystrokes. To illustrate this, compile and run this program. Type "sleep" at
* the prompt and then type "bar" before the prompt returns (you have 3
* seconds). Notice how "bar" is re-echoed on the prompt after the prompt
* returns? This is what you expect to happen. Now comment out the 4 lines below
* the line that says COMMENT LINE BELOW. Recompile and rerun the program and do
* the same thing. When the prompt returns, you should not see "bar". Now type
* "f", see how "barf" magically appears? This behavior is un-expected and not
* desired.
*/
void process_line(char *line);
int change_prompt(void);
char *get_prompt(void);
int prompt = 1;
char prompt_buf[40], line_buf[256];
tcflag_t old_lflag;
cc_t old_vtime;
struct termios term;
int
main()
{
fd_set fds;
/* Adjust the terminal slightly before the handler is installed. Disable
* canonical mode processing and set the input character time flag to be
* non-blocking.
*/
if( tcgetattr(STDIN_FILENO, &term) < 0 ) {
perror("tcgetattr");
exit(1);
}
old_lflag = term.c_lflag;
old_vtime = term.c_cc[VTIME];
term.c_lflag &= ~ICANON;
term.c_cc[VTIME] = 1;
/* COMMENT LINE BELOW - see above */
if( tcsetattr(STDIN_FILENO, TCSANOW, &term) < 0 ) {
perror("tcsetattr");
exit(1);
}
rl_add_defun("change-prompt", change_prompt, CTRL('t'));
rl_callback_handler_install(get_prompt(), process_line);
while(1) {
FD_ZERO(&fds);
FD_SET(fileno(stdin), &fds);
if( select(FD_SETSIZE, &fds, NULL, NULL, NULL) < 0) {
perror("select");
exit(1);
}
if( FD_ISSET(fileno(stdin), &fds) ) {
rl_callback_read_char();
}
}
}
void
process_line(char *line)
{
if( line == NULL ) {
fprintf(stderr, "\n", line);
/* reset the old terminal setting before exiting */
term.c_lflag = old_lflag;
term.c_cc[VTIME] = old_vtime;
if( tcsetattr(STDIN_FILENO, TCSANOW, &term) < 0 ) {
perror("tcsetattr");
exit(1);
}
exit(0);
}
if( strcmp(line, "sleep") == 0 ) {
sleep(3);
} else {
fprintf(stderr, "|%s|\n", line);
}
free (line);
}
int
change_prompt(void)
{
/* toggle the prompt variable */
prompt = !prompt;
/* save away the current contents of the line */
strcpy(line_buf, rl_line_buffer);
/* install a new handler which will change the prompt and erase the current line */
rl_callback_handler_install(get_prompt(), process_line);
/* insert the old text on the new line */
rl_insert_text(line_buf);
/* redraw the current line - this is an undocumented function. It invokes the
* redraw-current-line command.
*/
rl_refresh_line(0, 0);
}
char *
get_prompt(void)
{
/* The prompts can even be different lengths! */
sprintf(prompt_buf, "%s",
prompt ? "Hit ctrl-t to toggle prompt> " : "Pretty cool huh?> ");
return prompt_buf;
}
0707010002ca6f000081a40000000000000000000000015424dff700001983000001120001001bffffffffffffffff0000002a00000000root/usr/local/share/readline/rlptytest.c /*
*
* Another test harness for the readline callback interface.
*
* Author: Bob Rossi
*/
#if defined (HAVE_CONFIG_H)
#include
#endif
#include
#include
#include
#include
#include
#include
#include
#if 1 /* LINUX */
#include
#else
#include
#endif
#ifdef READLINE_LIBRARY
# include "readline.h"
#else
# include
#endif
/**
* Master/Slave PTY used to keep readline off of stdin/stdout.
*/
static int masterfd = -1;
static int slavefd;
void
sigint (s)
int s;
{
tty_reset (STDIN_FILENO);
close (masterfd);
close (slavefd);
printf ("\n");
exit (0);
}
static int
user_input()
{
int size;
const int MAX = 1024;
char *buf = (char *)malloc(MAX+1);
size = read (STDIN_FILENO, buf, MAX);
if (size == -1)
return -1;
size = write (masterfd, buf, size);
if (size == -1)
return -1;
return 0;
}
static int
readline_input()
{
const int MAX = 1024;
char *buf = (char *)malloc(MAX+1);
int size;
size = read (masterfd, buf, MAX);
if (size == -1)
{
free( buf );
buf = NULL;
return -1;
}
buf[size] = 0;
/* Display output from readline */
if ( size > 0 )
fprintf(stderr, "%s", buf);
free( buf );
buf = NULL;
return 0;
}
static void
rlctx_send_user_command(char *line)
{
/* This happens when rl_callback_read_char gets EOF */
if ( line == NULL )
return;
if (strcmp (line, "exit") == 0) {
tty_reset (STDIN_FILENO);
close (masterfd);
close (slavefd);
printf ("\n");
exit (0);
}
/* Don't add the enter command */
if ( line && *line != '\0' )
add_history(line);
}
static void
custom_deprep_term_function ()
{
}
static int
init_readline (int inputfd, int outputfd)
{
FILE *inputFILE, *outputFILE;
inputFILE = fdopen (inputfd, "r");
if (!inputFILE)
return -1;
outputFILE = fdopen (outputfd, "w");
if (!outputFILE)
return -1;
rl_instream = inputFILE;
rl_outstream = outputFILE;
/* Tell readline what the prompt is if it needs to put it back */
rl_callback_handler_install("(rltest): ", rlctx_send_user_command);
/* Set the terminal type to dumb so the output of readline can be
* understood by tgdb */
if ( rl_reset_terminal("dumb") == -1 )
return -1;
/* For some reason, readline can not deprep the terminal.
* However, it doesn't matter because no other application is working on
* the terminal besides readline */
rl_deprep_term_function = custom_deprep_term_function;
using_history();
read_history(".history");
return 0;
}
static int
main_loop(void)
{
fd_set rset;
int max;
max = (masterfd > STDIN_FILENO) ? masterfd : STDIN_FILENO;
max = (max > slavefd) ? max : slavefd;
for (;;)
{
/* Reset the fd_set, and watch for input from GDB or stdin */
FD_ZERO(&rset);
FD_SET(STDIN_FILENO, &rset);
FD_SET(slavefd, &rset);
FD_SET(masterfd, &rset);
/* Wait for input */
if (select(max + 1, &rset, NULL, NULL, NULL) == -1)
{
if (errno == EINTR)
continue;
else
return -1;
}
/* Input received through the pty: Handle it
* Wrote to masterfd, slave fd has that input, alert readline to read it.
*/
if (FD_ISSET(slavefd, &rset))
rl_callback_read_char();
/* Input received through the pty.
* Readline read from slavefd, and it wrote to the masterfd.
*/
if (FD_ISSET(masterfd, &rset))
if ( readline_input() == -1 )
return -1;
/* Input received: Handle it, write to masterfd (input to readline) */
if (FD_ISSET(STDIN_FILENO, &rset))
if ( user_input() == -1 )
return -1;
}
return 0;
}
/* The terminal attributes before calling tty_cbreak */
static struct termios save_termios;
static struct winsize size;
static enum { RESET, TCBREAK } ttystate = RESET;
/* tty_cbreak: Sets terminal to cbreak mode. Also known as noncanonical mode.
* 1. Signal handling is still turned on, so the user can still type those.
* 2. echo is off
* 3. Read in one char at a time.
*
* fd - The file descriptor of the terminal
*
* Returns: 0 on sucess, -1 on error
*/
int tty_cbreak(int fd){
struct termios buf;
int ttysavefd = -1;
if(tcgetattr(fd, &save_termios) < 0)
return -1;
buf = save_termios;
buf.c_lflag &= ~(ECHO | ICANON);
buf.c_iflag &= ~(ICRNL | INLCR);
buf.c_cc[VMIN] = 1;
buf.c_cc[VTIME] = 0;
#if defined (VLNEXT) && defined (_POSIX_VDISABLE)
buf.c_cc[VLNEXT] = _POSIX_VDISABLE;
#endif
#if defined (VDSUSP) && defined (_POSIX_VDISABLE)
buf.c_cc[VDSUSP] = _POSIX_VDISABLE;
#endif
/* enable flow control; only stty start char can restart output */
#if 0
buf.c_iflag |= (IXON|IXOFF);
#ifdef IXANY
buf.c_iflag &= ~IXANY;
#endif
#endif
/* disable flow control; let ^S and ^Q through to pty */
buf.c_iflag &= ~(IXON|IXOFF);
#ifdef IXANY
buf.c_iflag &= ~IXANY;
#endif
if(tcsetattr(fd, TCSAFLUSH, &buf) < 0)
return -1;
ttystate = TCBREAK;
ttysavefd = fd;
/* set size */
if(ioctl(fd, TIOCGWINSZ, (char *)&size) < 0)
return -1;
#ifdef DEBUG
err_msg("%d rows and %d cols\n", size.ws_row, size.ws_col);
#endif
return (0);
}
int
tty_off_xon_xoff (int fd)
{
struct termios buf;
int ttysavefd = -1;
if(tcgetattr(fd, &buf) < 0)
return -1;
buf.c_iflag &= ~(IXON|IXOFF);
if(tcsetattr(fd, TCSAFLUSH, &buf) < 0)
return -1;
return 0;
}
/* tty_reset: Sets the terminal attributes back to their previous state.
* PRE: tty_cbreak must have already been called.
*
* fd - The file descrioptor of the terminal to reset.
*
* Returns: 0 on success, -1 on error
*/
int tty_reset(int fd)
{
if(ttystate != TCBREAK)
return (0);
if(tcsetattr(fd, TCSAFLUSH, &save_termios) < 0)
return (-1);
ttystate = RESET;
return 0;
}
int
main()
{
int val;
val = openpty (&masterfd, &slavefd, NULL, NULL, NULL);
if (val == -1)
return -1;
val = tty_off_xon_xoff (masterfd);
if (val == -1)
return -1;
signal (SIGINT, sigint);
val = init_readline (slavefd, slavefd);
if (val == -1)
return -1;
val = tty_cbreak (STDIN_FILENO);
if (val == -1)
return -1;
val = main_loop ();
tty_reset (STDIN_FILENO);
if (val == -1)
return -1;
return 0;
}
0707010002ca6d000081a40000000000000000000000015424dff700000ce3000001120001001bffffffffffffffff0000002600000000root/usr/local/share/readline/rlcat.c /*
* rlcat - cat(1) using readline
*
* usage: rlcat
*/
/* Copyright (C) 1987-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#if defined (HAVE_CONFIG_H)
# include
#endif
#ifdef HAVE_UNISTD_H
# include
#endif
#include
#include "posixstat.h"
#include
#include
#include
#include
#ifdef HAVE_STDLIB_H
# include
#else
extern void exit();
#endif
#ifndef errno
extern int errno;
#endif
#if defined (READLINE_LIBRARY)
# include "readline.h"
# include "history.h"
#else
# include
# include
#endif
extern int optind;
extern char *optarg;
static int stdcat();
static char *progname;
static int vflag;
static void
usage()
{
fprintf (stderr, "%s: usage: %s [-vEVN] [filename]\n", progname, progname);
}
int
main (argc, argv)
int argc;
char **argv;
{
char *temp;
int opt, Vflag, Nflag;
progname = strrchr(argv[0], '/');
if (progname == 0)
progname = argv[0];
else
progname++;
vflag = Vflag = Nflag = 0;
while ((opt = getopt(argc, argv, "vEVN")) != EOF)
{
switch (opt)
{
case 'v':
vflag = 1;
break;
case 'V':
Vflag = 1;
break;
case 'E':
Vflag = 0;
break;
case 'N':
Nflag = 1;
break;
default:
usage ();
exit (2);
}
}
argc -= optind;
argv += optind;
if (isatty(0) == 0 || argc || Nflag)
return stdcat(argc, argv);
rl_variable_bind ("editing-mode", Vflag ? "vi" : "emacs");
while (temp = readline (""))
{
if (*temp)
add_history (temp);
printf ("%s\n", temp);
}
return (ferror (stdout));
}
static int
fcopy(fp)
FILE *fp;
{
int c;
char *x;
while ((c = getc(fp)) != EOF)
{
if (vflag && isascii ((unsigned char)c) && isprint((unsigned char)c) == 0)
{
x = rl_untranslate_keyseq (c);
if (fputs (x, stdout) != 0)
return 1;
}
else if (putchar (c) == EOF)
return 1;
}
return (ferror (stdout));
}
int
stdcat (argc, argv)
int argc;
char **argv;
{
int i, fd, r;
char *s;
FILE *fp;
if (argc == 0)
return (fcopy(stdin));
for (i = 0, r = 1; i < argc; i++)
{
if (*argv[i] == '-' && argv[i][1] == 0)
fp = stdin;
else
{
fp = fopen (argv[i], "r");
if (fp == 0)
{
fprintf (stderr, "%s: %s: cannot open: %s\n", progname, argv[i], strerror(errno));
continue;
}
}
r = fcopy (fp);
if (fp != stdin)
fclose(fp);
}
return r;
}
0707010002ca69000081a40000000000000000000000015424dff700000ce4000001120001001bffffffffffffffff0000002900000000root/usr/local/share/readline/manexamp.c /* manexamp.c -- The examples which appear in the documentation are here. */
/* Copyright (C) 1987-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#include
#include
/* **************************************************************** */
/* */
/* How to Emulate gets () */
/* */
/* **************************************************************** */
/* A static variable for holding the line. */
static char *line_read = (char *)NULL;
/* Read a string, and return a pointer to it. Returns NULL on EOF. */
char *
rl_gets ()
{
/* If the buffer has already been allocated, return the memory
to the free pool. */
if (line_read)
{
free (line_read);
line_read = (char *)NULL;
}
/* Get a line from the user. */
line_read = readline ("");
/* If the line has any text in it, save it on the history. */
if (line_read && *line_read)
add_history (line_read);
return (line_read);
}
/* **************************************************************** */
/* */
/* Writing a Function to be Called by Readline. */
/* */
/* **************************************************************** */
/* Invert the case of the COUNT following characters. */
invert_case_line (count, key)
int count, key;
{
register int start, end;
start = rl_point;
if (count < 0)
{
direction = -1;
count = -count;
}
else
direction = 1;
/* Find the end of the range to modify. */
end = start + (count * direction);
/* Force it to be within range. */
if (end > rl_end)
end = rl_end;
else if (end < 0)
end = -1;
if (start > end)
{
int temp = start;
start = end;
end = temp;
}
if (start == end)
return;
/* Tell readline that we are modifying the line, so save the undo
information. */
rl_modifying (start, end);
for (; start != end; start += direction)
{
if (_rl_uppercase_p (rl_line_buffer[start]))
rl_line_buffer[start] = _rl_to_lower (rl_line_buffer[start]);
else if (_rl_lowercase_p (rl_line_buffer[start]))
rl_line_buffer[start] = _rl_to_upper (rl_line_buffer[start]);
}
/* Move point to on top of the last character changed. */
rl_point = end - direction;
}
0707010002ca6e000081a40000000000000000000000015424dff700000cdf000001120001001bffffffffffffffff0000002800000000root/usr/local/share/readline/rlevent.c /*
* rl - command-line interface to read a line from the standard input
* (or another fd) using readline.
*
* usage: rl [-p prompt] [-u unit] [-d default] [-n nchars]
*/
/* Copyright (C) 1987-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#if defined (HAVE_CONFIG_H)
# include
#endif
#include
#include
#ifdef HAVE_STDLIB_H
# include
#else
extern void exit();
#endif
#if defined (READLINE_LIBRARY)
# include "posixstat.h"
# include "readline.h"
# include "history.h"
#else
# include
# include
# include
#endif
extern int optind;
extern char *optarg;
#if !defined (strchr) && !defined (__STDC__)
extern char *strrchr();
#endif
static char *progname;
static char *deftext;
static int
event_hook ()
{
fprintf (stderr, "ding!\n");
sleep (1);
return 0;
}
static int
set_deftext ()
{
if (deftext)
{
rl_insert_text (deftext);
deftext = (char *)NULL;
rl_startup_hook = (rl_hook_func_t *)NULL;
}
return 0;
}
static void
usage()
{
fprintf (stderr, "%s: usage: %s [-p prompt] [-u unit] [-d default] [-n nchars]\n",
progname, progname);
}
int
main (argc, argv)
int argc;
char **argv;
{
char *temp, *prompt;
struct stat sb;
int opt, fd, nch;
FILE *ifp;
progname = strrchr(argv[0], '/');
if (progname == 0)
progname = argv[0];
else
progname++;
/* defaults */
prompt = "readline$ ";
fd = nch = 0;
deftext = (char *)0;
while ((opt = getopt(argc, argv, "p:u:d:n:")) != EOF)
{
switch (opt)
{
case 'p':
prompt = optarg;
break;
case 'u':
fd = atoi(optarg);
if (fd < 0)
{
fprintf (stderr, "%s: bad file descriptor `%s'\n", progname, optarg);
exit (2);
}
break;
case 'd':
deftext = optarg;
break;
case 'n':
nch = atoi(optarg);
if (nch < 0)
{
fprintf (stderr, "%s: bad value for -n: `%s'\n", progname, optarg);
exit (2);
}
break;
default:
usage ();
exit (2);
}
}
if (fd != 0)
{
if (fstat (fd, &sb) < 0)
{
fprintf (stderr, "%s: %d: bad file descriptor\n", progname, fd);
exit (1);
}
ifp = fdopen (fd, "r");
rl_instream = ifp;
}
if (deftext && *deftext)
rl_startup_hook = set_deftext;
if (nch > 0)
rl_num_chars_to_read = nch;
rl_event_hook = event_hook;
temp = readline (prompt);
/* Test for EOF. */
if (temp == 0)
exit (1);
printf ("%s\n", temp);
exit (0);
}
0707010002ca71000081a40000000000000000000000015424dff700000507000001120001001bffffffffffffffff0000002a00000000root/usr/local/share/readline/rlversion.c /*
* rlversion -- print out readline's version number
*/
/* Copyright (C) 1987-2009 Free Software Foundation, Inc.
This file is part of the GNU Readline Library (Readline), a library for
reading lines of text with interactive input and history editing.
Readline 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 3 of the License, or
(at your option) any later version.
Readline 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 Readline. If not, see .
*/
#if defined (HAVE_CONFIG_H)
# include
#endif
#include
#include
#include "posixstat.h"
#ifdef HAVE_STDLIB_H
# include
#else
extern void exit();
#endif
#ifdef READLINE_LIBRARY
# include "readline.h"
#else
# include
#endif
main()
{
printf ("%s\n", rl_library_version ? rl_library_version : "unknown");
exit (0);
}
0707010002ca5a000041ed0000000000000000000000025424e06e00000000000001120001001bffffffffffffffff0000001a00000000root/usr/local/share/info 0707010002ca5b000081a40000000000000000000000015424dff70000418a000001120001001bffffffffffffffff0000001e00000000root/usr/local/share/info/dir This is the file .../info/dir, which contains the
topmost node of the Info hierarchy, called (dir)Top.
The first time you invoke Info you start off looking at this node.
File: dir, Node: Top This is the top of the INFO tree
This (the Directory node) gives a menu of major topics.
Typing "q" exits, "?" lists all Info commands, "d" returns here,
"h" gives a primer for first-timers,
"mEmacs" visits the Emacs manual, etc.
In Emacs, you can click mouse button 2 on a menu item or cross reference
to select it.
* Menu:
Archiving
* Tar: (tar). Making tape (or disk) archives.
Basics
* Bash: (bash). The GNU Bourne-Again SHell.
* Common options: (coreutils)Common options.
* Coreutils: (coreutils). Core GNU (file, text, shell) utilities.
* Date input formats: (coreutils)Date input formats.
* File permissions: (coreutils)File permissions.
Access modes.
Development
* libffi: (libffi). Portable foreign-function interface library.
Emacs
* IDN Library: (libidn)Emacs API.
Emacs API for IDN functions.
Encryption
* Nettle: (nettle). A low-level cryptographic library.
GNU Libraries
* libgcrypt: (gcrypt). Cryptographic function library.
GNU libraries
* gmp: (gmp). GNU Multiple Precision Arithmetic Library.
GNU Packages
* CVS: (cvs). Concurrent Versions System
GNU Utilities
* gpg: (gnupg1). OpenPGP encryption and signing tool (v1).
Localization
* idn: (libidn)Invoking idn. Internationalized Domain Name (IDN) string
conversion.
Network applications
* Gawkinet: (gawkinet). TCP/IP Internetworking With `gawk'.
* Wget: (wget). Non-interactive network downloader.
Programming
* cvsclient: (cvsclient). The CVS client/server protocol.
* flex: (flex). Fast lexical analyzer generator (lex
replacement).
Software libraries
* libidn: (libidn). Internationalized string processing library.
* libtasn1: (libtasn1). Library for Abstract Syntax Notation One
(ASN.1).
* mpfr: (mpfr). Multiple Precision Floating-Point Reliable
Library.
Texinfo documentation system
* Info: (info). How to use the documentation browsing system.
* info stand-alone: (info-stnd).
Read Info documents without Emacs.
* infokey: (info-stnd)Invoking infokey.
Compile Info customizations.
* install-info: (texinfo)Invoking install-info.
Update info/dir entries.
* makeinfo: (texinfo)Invoking makeinfo.
Translate Texinfo source.
* pdftexi2dvi: (texinfo)PDF Output.
PDF output for Texinfo.
* pod2texi: (pod2texi)Invoking pod2texi.
Translate Perl POD to Texinfo.
* texi2dvi: (texinfo)Format with texi2dvi.
Print Texinfo documents.
* texi2pdf: (texinfo)PDF Output.
PDF output for Texinfo.
* texindex: (texinfo)Format with tex/texindex.
Sort Texinfo index files.
* Texinfo: (texinfo). The GNU documentation format.
Text creation and manipulation
* Diffutils: (diffutils). Comparing and merging files.
* Gawk: (gawk). A text scanning and processing language.
* M4: (m4). A powerful macro processor.
* sed: (sed). Stream EDitor.
C++ libraries
* autosprintf: (autosprintf). Support for printf format strings in C++.
GNU Gettext Utilities
* ISO3166: (gettext)Country Codes.
ISO 3166 country codes.
* ISO639: (gettext)Language Codes.
ISO 639 language codes.
* xgettext: (gettext)xgettext Invocation.
Extract strings into a PO file.
* autopoint: (gettext)autopoint Invocation.
Copy gettext infrastructure.
* envsubst: (gettext)envsubst Invocation.
Expand environment variables.
* gettext: (gettext). GNU gettext utilities.
* gettextize: (gettext)gettextize Invocation.
Prepare a package for gettext.
* msgattrib: (gettext)msgattrib Invocation.
Select part of a PO file.
* msgcat: (gettext)msgcat Invocation.
Combine several PO files.
* msgcmp: (gettext)msgcmp Invocation.
Compare a PO file and template.
* msgcomm: (gettext)msgcomm Invocation.
Match two PO files.
* msgconv: (gettext)msgconv Invocation.
Convert PO file to encoding.
* msgen: (gettext)msgen Invocation.
Create an English PO file.
* msgexec: (gettext)msgexec Invocation.
Process a PO file.
* msgfilter: (gettext)msgfilter Invocation.
Pipe a PO file through a filter.
* msgfmt: (gettext)msgfmt Invocation.
Make MO files out of PO files.
* msggrep: (gettext)msggrep Invocation.
Select part of a PO file.
* msginit: (gettext)msginit Invocation.
Create a fresh PO file.
* msgmerge: (gettext)msgmerge Invocation.
Update a PO file from template.
* msgunfmt: (gettext)msgunfmt Invocation.
Uncompile MO file into PO file.
* msguniq: (gettext)msguniq Invocation.
Unify duplicates for PO file.
* ngettext: (gettext)ngettext Invocation.
Translate a message with plural.
Software development
* Autoconf: (autoconf). Create source code configuration scripts.
* Automake: (automake). Making GNU standards-compliant Makefiles.
* Check: (check)Introduction.
* GNU libunistring: (libunistring).
Unicode string library.
* Make: (make). Remake files automatically.
* bison: (bison). GNU parser generator (Yacc replacement).
* help2man: (help2man). Automatic manual page generation.
Libraries
* History: (history). The GNU history library API.
* RLuserman: (rluserman). The GNU readline library User's Manual.
* Readline: (readline). The GNU readline library API.
* libIDL2: (libIDL2). Interface Definition Language parsing library.
Individual utilities
* aclocal: (automake)Invoking aclocal. Generating aclocal.m4.
* aclocal-invocation: (automake)aclocal Invocation.
Generating aclocal.m4.
* arch: (coreutils)arch invocation. Print machine hardware name.
* autoconf-invocation: (autoconf)autoconf Invocation.
How to create configuration
scripts
* autoheader: (autoconf)autoheader Invocation. How to create configuration
templates
* autom4te: (autoconf)autom4te Invocation. The Autoconf executables
backbone
* automake: (automake)Invoking Automake. Generating Makefile.in.
* automake-invocation: (automake)automake Invocation.
Generating Makefile.in.
* autoreconf: (autoconf)autoreconf Invocation. Remaking multiple `configure'
scripts
* autoscan: (autoconf)autoscan Invocation. Semi-automatic `configure.ac'
writing
* autoupdate: (autoconf)autoupdate Invocation. Automatic update of
`configure.ac'
* awk: (gawk)Invoking gawk. Text scanning and processing.
* base64: (coreutils)base64 invocation. Base64 encode/decode data.
* basename: (coreutils)basename invocation. Strip directory and suffix.
* cat: (coreutils)cat invocation. Concatenate and write files.
* chcon: (coreutils)chcon invocation. Change SELinux CTX of files.
* chgrp: (coreutils)chgrp invocation. Change file groups.
* chmod: (coreutils)chmod invocation. Change access permissions.
* chown: (coreutils)chown invocation. Change file owners and groups.
* chroot: (coreutils)chroot invocation. Specify the root directory.
* cksum: (coreutils)cksum invocation. Print POSIX CRC checksum.
* cmp: (diffutils)Invoking cmp. Compare 2 files byte by byte.
* comm: (coreutils)comm invocation. Compare sorted files by line.
* config.status: (autoconf)config.status Invocation.
Recreating configurations.
* configure: (autoconf)configure Invocation. Configuring a package.
* cp: (coreutils)cp invocation. Copy files.
* csplit: (coreutils)csplit invocation. Split by context.
* cut: (coreutils)cut invocation. Print selected parts of lines.
* cvs: (cvs)CVS commands. Concurrent Versions System
* date: (coreutils)date invocation. Print/set system date and time.
* dd: (coreutils)dd invocation. Copy and convert a file.
* df: (coreutils)df invocation. Report file system disk usage.
* diff: (diffutils)Invoking diff. Compare 2 files line by line.
* diff3: (diffutils)Invoking diff3. Compare 3 files line by line.
* dir: (coreutils)dir invocation. List directories briefly.
* dircolors: (coreutils)dircolors invocation. Color setup for ls.
* dirname: (coreutils)dirname invocation. Strip last file name component.
* du: (coreutils)du invocation. Report on disk usage.
* echo: (coreutils)echo invocation. Print a line of text.
* env: (coreutils)env invocation. Modify the environment.
* expand: (coreutils)expand invocation. Convert tabs to spaces.
* expr: (coreutils)expr invocation. Evaluate expressions.
* factor: (coreutils)factor invocation. Print prime factors
* false: (coreutils)false invocation. Do nothing, unsuccessfully.
* fmt: (coreutils)fmt invocation. Reformat paragraph text.
* fold: (coreutils)fold invocation. Wrap long input lines.
* groups: (coreutils)groups invocation. Print group names a user is in.
* head: (coreutils)head invocation. Output the first part of files.
* hostid: (coreutils)hostid invocation. Print numeric host identifier.
* hostname: (coreutils)hostname invocation. Print or set system name.
* id: (coreutils)id invocation. Print user identity.
* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
* install: (coreutils)install invocation. Copy and change attributes.
* join: (coreutils)join invocation. Join lines on a common field.
* kill: (coreutils)kill invocation. Send a signal to processes.
* libtool-invocation: (libtool)Invoking libtool.
Running the `libtool' script.
* libtoolize: (libtool)Invoking libtoolize. Adding libtool support.
* link: (coreutils)link invocation. Make hard links between files.
* ln: (coreutils)ln invocation. Make links between files.
* logname: (coreutils)logname invocation. Print current login name.
* ls: (coreutils)ls invocation. List directory contents.
* md5sum: (coreutils)md5sum invocation. Print or check MD5 digests.
* mkdir: (coreutils)mkdir invocation. Create directories.
* mkfifo: (coreutils)mkfifo invocation. Create FIFOs (named pipes).
* mknod: (coreutils)mknod invocation. Create special files.
* mktemp: (coreutils)mktemp invocation. Create temporary files.
* mv: (coreutils)mv invocation. Rename files.
* nice: (coreutils)nice invocation. Modify niceness.
* nl: (coreutils)nl invocation. Number lines and write files.
* nohup: (coreutils)nohup invocation. Immunize to hangups.
* nproc: (coreutils)nproc invocation. Print the number of processors.
* numfmt: (coreutils)numfmt invocation. Reformat numbers.
* od: (coreutils)od invocation. Dump files in octal, etc.
* paste: (coreutils)paste invocation. Merge lines of files.
* patch: (diffutils)Invoking patch. Apply a patch to a file.
* pathchk: (coreutils)pathchk invocation. Check file name portability.
* pr: (coreutils)pr invocation. Paginate or columnate files.
* printenv: (coreutils)printenv invocation. Print environment variables.
* printf: (coreutils)printf invocation. Format and print data.
* ptx: (coreutils)ptx invocation. Produce permuted indexes.
* pwd: (coreutils)pwd invocation. Print working directory.
* readlink: (coreutils)readlink invocation. Print referent of a symlink.
* realpath: (coreutils)readpath invocation. Print resolved file names.
* rm: (coreutils)rm invocation. Remove files.
* rmdir: (coreutils)rmdir invocation. Remove empty directories.
* runcon: (coreutils)runcon invocation. Run in specified SELinux CTX.
* sdiff: (diffutils)Invoking sdiff. Merge 2 files side-by-side.
* seq: (coreutils)seq invocation. Print numeric sequences
* sha1sum: (coreutils)sha1sum invocation. Print or check SHA-1 digests.
* sha2: (coreutils)sha2 utilities. Print or check SHA-2 digests.
* shred: (coreutils)shred invocation. Remove files more securely.
* shuf: (coreutils)shuf invocation. Shuffling text files.
* sleep: (coreutils)sleep invocation. Delay for a specified time.
* sort: (coreutils)sort invocation. Sort text files.
* split: (coreutils)split invocation. Split into pieces.
* stat: (coreutils)stat invocation. Report file(system) status.
* stdbuf: (coreutils)stdbuf invocation. Modify stdio buffering.
* stty: (coreutils)stty invocation. Print/change terminal settings.
* sum: (coreutils)sum invocation. Print traditional checksum.
* sync: (coreutils)sync invocation. Synchronize memory and disk.
* tac: (coreutils)tac invocation. Reverse files.
* tail: (coreutils)tail invocation. Output the last part of files.
* tar: (tar)tar invocation. Invoking GNU `tar'.
* tee: (coreutils)tee invocation. Redirect to multiple files.
* test: (coreutils)test invocation. File/string tests.
* testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
* timeout: (coreutils)timeout invocation. Run with time limit.
* touch: (coreutils)touch invocation. Change file timestamps.
* tr: (coreutils)tr invocation. Translate characters.
* true: (coreutils)true invocation. Do nothing, successfully.
* truncate: (coreutils)truncate invocation. Shrink/extend size of a file.
* tsort: (coreutils)tsort invocation. Topological sort.
* tty: (coreutils)tty invocation. Print terminal name.
* uname: (coreutils)uname invocation. Print system information.
* unexpand: (coreutils)unexpand invocation. Convert spaces to tabs.
* uniq: (coreutils)uniq invocation. Uniquify files.
* unlink: (coreutils)unlink invocation. Removal via unlink(2).
* uptime: (coreutils)uptime invocation. Print uptime and load.
* users: (coreutils)users invocation. Print current user names.
* vdir: (coreutils)vdir invocation. List directories verbosely.
* wc: (coreutils)wc invocation. Line, word, and byte counts.
* who: (coreutils)who invocation. Print who is logged in.
* whoami: (coreutils)whoami invocation. Print effective user ID.
* yes: (coreutils)yes invocation. Print a string indefinitely.
GNU organization
* Standards: (standards). GNU coding standards.
GNU programming tools
* Libtool: (libtool). Generic shared library support script.
Viewers
* gv: (gv). The GNU PostScript and PDF viewer.
0707010002ca5d000081a40000000000000000000000015424dff7000350ac000001120001001bffffffffffffffff0000002800000000root/usr/local/share/info/readline.info This is readline.info, produced by makeinfo version 4.13 from
/usr/homes/chet/src/bash/readline-src/doc/rlman.texi.
This manual describes the GNU Readline Library (version 6.3, 6 January
2014), a library which aids in the consistency of user interface across
discrete programs which provide a command line interface.
Copyright (C) 1988-2014 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Libraries
START-INFO-DIR-ENTRY
* Readline: (readline). The GNU readline library API.
END-INFO-DIR-ENTRY
File: readline.info, Node: Top, Next: Command Line Editing, Up: (dir)
GNU Readline Library
********************
This document describes the GNU Readline Library, a utility which aids
in the consistency of user interface across discrete programs which
provide a command line interface. The Readline home page is
`http://www.gnu.org/software/readline/'.
* Menu:
* Command Line Editing:: GNU Readline User's Manual.
* Programming with GNU Readline:: GNU Readline Programmer's Manual.
* GNU Free Documentation License:: License for copying this manual.
* Concept Index:: Index of concepts described in this manual.
* Function and Variable Index:: Index of externally visible functions
and variables.
File: readline.info, Node: Command Line Editing, Next: Programming with GNU Readline, Prev: Top, Up: Top
1 Command Line Editing
**********************
This chapter describes the basic features of the GNU command line
editing interface.
* Menu:
* Introduction and Notation:: Notation used in this text.
* Readline Interaction:: The minimum set of commands for editing a line.
* Readline Init File:: Customizing Readline from a user's view.
* Bindable Readline Commands:: A description of most of the Readline commands
available for binding
* Readline vi Mode:: A short description of how to make Readline
behave like the vi editor.
File: readline.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
1.1 Introduction to Line Editing
================================
The following paragraphs describe the notation used to represent
keystrokes.
The text `C-k' is read as `Control-K' and describes the character
produced when the key is pressed while the Control key is depressed.
The text `M-k' is read as `Meta-K' and describes the character
produced when the Meta key (if you have one) is depressed, and the
key is pressed. The Meta key is labeled on many keyboards. On
keyboards with two keys labeled (usually to either side of the
space bar), the on the left side is generally set to work as a
Meta key. The key on the right may also be configured to work as
a Meta key or may be configured as some other modifier, such as a
Compose key for typing accented characters.
If you do not have a Meta or key, or another key working as a
Meta key, the identical keystroke can be generated by typing
_first_, and then typing . Either process is known as "metafying"
the key.
The text `M-C-k' is read as `Meta-Control-k' and describes the
character produced by "metafying" `C-k'.
In addition, several keys have their own names. Specifically,
, , , , , and all stand for themselves
when seen in this text, or in an init file (*note Readline Init File::).
If your keyboard lacks a key, typing will produce the
desired character. The key may be labeled or on
some keyboards.
File: readline.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
1.2 Readline Interaction
========================
Often during an interactive session you type in a long line of text,
only to notice that the first word on the line is misspelled. The
Readline library gives you a set of commands for manipulating the text
as you type it in, allowing you to just fix your typo, and not forcing
you to retype the majority of the line. Using these editing commands,
you move the cursor to the place that needs correction, and delete or
insert the text of the corrections. Then, when you are satisfied with
the line, you simply press . You do not have to be at the end of
the line to press ; the entire line is accepted regardless of the
location of the cursor within the line.
* Menu:
* Readline Bare Essentials:: The least you need to know about Readline.
* Readline Movement Commands:: Moving about the input line.
* Readline Killing Commands:: How to delete text, and how to get it back!
* Readline Arguments:: Giving numeric arguments to commands.
* Searching:: Searching through previous lines.
File: readline.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
1.2.1 Readline Bare Essentials
------------------------------
In order to enter characters into the line, simply type them. The typed
character appears where the cursor was, and then the cursor moves one
space to the right. If you mistype a character, you can use your erase
character to back up and delete the mistyped character.
Sometimes you may mistype a character, and not notice the error
until you have typed several other characters. In that case, you can
type `C-b' to move the cursor to the left, and then correct your
mistake. Afterwards, you can move the cursor to the right with `C-f'.
When you add text in the middle of a line, you will notice that
characters to the right of the cursor are `pushed over' to make room
for the text that you have inserted. Likewise, when you delete text
behind the cursor, characters to the right of the cursor are `pulled
back' to fill in the blank space created by the removal of the text. A
list of the bare essentials for editing the text of an input line
follows.
`C-b'
Move back one character.
`C-f'
Move forward one character.
or
Delete the character to the left of the cursor.
`C-d'
Delete the character underneath the cursor.
Printing characters
Insert the character into the line at the cursor.
`C-_' or `C-x C-u'
Undo the last editing command. You can undo all the way back to an
empty line.
(Depending on your configuration, the key be set to delete
the character to the left of the cursor and the key set to delete
the character underneath the cursor, like `C-d', rather than the
character to the left of the cursor.)
File: readline.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
1.2.2 Readline Movement Commands
--------------------------------
The above table describes the most basic keystrokes that you need in
order to do editing of the input line. For your convenience, many
other commands have been added in addition to `C-b', `C-f', `C-d', and
. Here are some commands for moving more rapidly about the line.
`C-a'
Move to the start of the line.
`C-e'
Move to the end of the line.
`M-f'
Move forward a word, where a word is composed of letters and
digits.
`M-b'
Move backward a word.
`C-l'
Clear the screen, reprinting the current line at the top.
Notice how `C-f' moves forward a character, while `M-f' moves
forward a word. It is a loose convention that control keystrokes
operate on characters while meta keystrokes operate on words.
File: readline.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
1.2.3 Readline Killing Commands
-------------------------------
"Killing" text means to delete the text from the line, but to save it
away for later use, usually by "yanking" (re-inserting) it back into
the line. (`Cut' and `paste' are more recent jargon for `kill' and
`yank'.)
If the description for a command says that it `kills' text, then you
can be sure that you can get the text back in a different (or the same)
place later.
When you use a kill command, the text is saved in a "kill-ring".
Any number of consecutive kills save all of the killed text together, so
that when you yank it back, you get it all. The kill ring is not line
specific; the text that you killed on a previously typed line is
available to be yanked back later, when you are typing another line.
Here is the list of commands for killing text.
`C-k'
Kill the text from the current cursor position to the end of the
line.
`M-d'
Kill from the cursor to the end of the current word, or, if between
words, to the end of the next word. Word boundaries are the same
as those used by `M-f'.
`M-'
Kill from the cursor the start of the current word, or, if between
words, to the start of the previous word. Word boundaries are the
same as those used by `M-b'.
`C-w'
Kill from the cursor to the previous whitespace. This is
different than `M-' because the word boundaries differ.
Here is how to "yank" the text back into the line. Yanking means to
copy the most-recently-killed text from the kill buffer.
`C-y'
Yank the most recently killed text back into the buffer at the
cursor.
`M-y'
Rotate the kill-ring, and yank the new top. You can only do this
if the prior command is `C-y' or `M-y'.
File: readline.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
1.2.4 Readline Arguments
------------------------
You can pass numeric arguments to Readline commands. Sometimes the
argument acts as a repeat count, other times it is the sign of the
argument that is significant. If you pass a negative argument to a
command which normally acts in a forward direction, that command will
act in a backward direction. For example, to kill text back to the
start of the line, you might type `M-- C-k'.
The general way to pass numeric arguments to a command is to type
meta digits before the command. If the first `digit' typed is a minus
sign (`-'), then the sign of the argument will be negative. Once you
have typed one meta digit to get the argument started, you can type the
remainder of the digits, and then the command. For example, to give
the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
will delete the next ten characters on the input line.
File: readline.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
1.2.5 Searching for Commands in the History
-------------------------------------------
Readline provides commands for searching through the command history
for lines containing a specified string. There are two search modes:
"incremental" and "non-incremental".
Incremental searches begin before the user has finished typing the
search string. As each character of the search string is typed,
Readline displays the next entry from the history matching the string
typed so far. An incremental search requires only as many characters
as needed to find the desired history entry. To search backward in the
history for a particular string, type `C-r'. Typing `C-s' searches
forward through the history. The characters present in the value of
the `isearch-terminators' variable are used to terminate an incremental
search. If that variable has not been assigned a value, the and
`C-J' characters will terminate an incremental search. `C-g' will
abort an incremental search and restore the original line. When the
search is terminated, the history entry containing the search string
becomes the current line.
To find other matching entries in the history list, type `C-r' or
`C-s' as appropriate. This will search backward or forward in the
history for the next entry matching the search string typed so far.
Any other key sequence bound to a Readline command will terminate the
search and execute that command. For instance, a will terminate
the search and accept the line, thereby executing the command from the
history list. A movement command will terminate the search, make the
last line found the current line, and begin editing.
Readline remembers the last incremental search string. If two
`C-r's are typed without any intervening characters defining a new
search string, any remembered search string is used.
Non-incremental searches read the entire search string before
starting to search for matching history lines. The search string may be
typed by the user or be part of the contents of the current line.
File: readline.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
1.3 Readline Init File
======================
Although the Readline library comes with a set of Emacs-like
keybindings installed by default, it is possible to use a different set
of keybindings. Any user can customize programs that use Readline by
putting commands in an "inputrc" file, conventionally in his home
directory. The name of this file is taken from the value of the
environment variable `INPUTRC'. If that variable is unset, the default
is `~/.inputrc'. If that file does not exist or cannot be read, the
ultimate default is `/etc/inputrc'.
When a program which uses the Readline library starts up, the init
file is read, and the key bindings are set.
In addition, the `C-x C-r' command re-reads this init file, thus
incorporating any changes that you might have made to it.
* Menu:
* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
* Sample Init File:: An example inputrc file.
File: readline.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
1.3.1 Readline Init File Syntax
-------------------------------
There are only a few basic constructs allowed in the Readline init
file. Blank lines are ignored. Lines beginning with a `#' are
comments. Lines beginning with a `$' indicate conditional constructs
(*note Conditional Init Constructs::). Other lines denote variable
settings and key bindings.
Variable Settings
You can modify the run-time behavior of Readline by altering the
values of variables in Readline using the `set' command within the
init file. The syntax is simple:
set VARIABLE VALUE
Here, for example, is how to change from the default Emacs-like
key binding to use `vi' line editing commands:
set editing-mode vi
Variable names and values, where appropriate, are recognized
without regard to case. Unrecognized variable names are ignored.
Boolean variables (those that can be set to on or off) are set to
on if the value is null or empty, ON (case-insensitive), or 1.
Any other value results in the variable being set to off.
A great deal of run-time behavior is changeable with the following
variables.
`bell-style'
Controls what happens when Readline wants to ring the
terminal bell. If set to `none', Readline never rings the
bell. If set to `visible', Readline uses a visible bell if
one is available. If set to `audible' (the default),
Readline attempts to ring the terminal's bell.
`bind-tty-special-chars'
If set to `on', Readline attempts to bind the control
characters treated specially by the kernel's terminal driver
to their Readline equivalents.
`colored-stats'
If set to `on', Readline displays possible completions using
different colors to indicate their file type. The color
definitions are taken from the value of the `LS_COLORS'
environment variable. The default is `off'.
`comment-begin'
The string to insert at the beginning of the line when the
`insert-comment' command is executed. The default value is
`"#"'.
`completion-display-width'
The number of screen columns used to display possible matches
when performing completion. The value is ignored if it is
less than 0 or greater than the terminal screen width. A
value of 0 will cause matches to be displayed one per line.
The default value is -1.
`completion-ignore-case'
If set to `on', Readline performs filename matching and
completion in a case-insensitive fashion. The default value
is `off'.
`completion-map-case'
If set to `on', and COMPLETION-IGNORE-CASE is enabled,
Readline treats hyphens (`-') and underscores (`_') as
equivalent when performing case-insensitive filename matching
and completion.
`completion-prefix-display-length'
The length in characters of the common prefix of a list of
possible completions that is displayed without modification.
When set to a value greater than zero, common prefixes longer
than this value are replaced with an ellipsis when displaying
possible completions.
`completion-query-items'
The number of possible completions that determines when the
user is asked whether the list of possibilities should be
displayed. If the number of possible completions is greater
than this value, Readline will ask the user whether or not he
wishes to view them; otherwise, they are simply listed. This
variable must be set to an integer value greater than or
equal to 0. A negative value means Readline should never ask.
The default limit is `100'.
`convert-meta'
If set to `on', Readline will convert characters with the
eighth bit set to an ASCII key sequence by stripping the
eighth bit and prefixing an character, converting them
to a meta-prefixed key sequence. The default value is `on'.
`disable-completion'
If set to `On', Readline will inhibit word completion.
Completion characters will be inserted into the line as if
they had been mapped to `self-insert'. The default is `off'.
`editing-mode'
The `editing-mode' variable controls which default set of key
bindings is used. By default, Readline starts up in Emacs
editing mode, where the keystrokes are most similar to Emacs.
This variable can be set to either `emacs' or `vi'.
`echo-control-characters'
When set to `on', on operating systems that indicate they
support it, readline echoes a character corresponding to a
signal generated from the keyboard. The default is `on'.
`enable-keypad'
When set to `on', Readline will try to enable the application
keypad when it is called. Some systems need this to enable
the arrow keys. The default is `off'.
`enable-meta-key'
When set to `on', Readline will try to enable any meta
modifier key the terminal claims to support when it is
called. On many terminals, the meta key is used to send
eight-bit characters. The default is `on'.
`expand-tilde'
If set to `on', tilde expansion is performed when Readline
attempts word completion. The default is `off'.
`history-preserve-point'
If set to `on', the history code attempts to place the point
(the current cursor position) at the same location on each
history line retrieved with `previous-history' or
`next-history'. The default is `off'.
`history-size'
Set the maximum number of history entries saved in the
history list. If set to zero, any existing history entries
are deleted and no new entries are saved. If set to a value
less than zero, the number of history entries is not limited.
By default, the number of history entries is not limited.
`horizontal-scroll-mode'
This variable can be set to either `on' or `off'. Setting it
to `on' means that the text of the lines being edited will
scroll horizontally on a single screen line when they are
longer than the width of the screen, instead of wrapping onto
a new screen line. By default, this variable is set to `off'.
`input-meta'
If set to `on', Readline will enable eight-bit input (it will
not clear the eighth bit in the characters it reads),
regardless of what the terminal claims it can support. The
default value is `off'. The name `meta-flag' is a synonym
for this variable.
`isearch-terminators'
The string of characters that should terminate an incremental
search without subsequently executing the character as a
command (*note Searching::). If this variable has not been
given a value, the characters and `C-J' will terminate
an incremental search.
`keymap'
Sets Readline's idea of the current keymap for key binding
commands. Acceptable `keymap' names are `emacs',
`emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
`vi-command', and `vi-insert'. `vi' is equivalent to
`vi-command'; `emacs' is equivalent to `emacs-standard'. The
default value is `emacs'. The value of the `editing-mode'
variable also affects the default keymap.
`keyseq-timeout'
Specifies the duration Readline will wait for a character
when reading an ambiguous key sequence (one that can form a
complete key sequence using the input read so far, or can
take additional input to complete a longer key sequence). If
no input is received within the timeout, Readline will use
the shorter but complete key sequence. Readline uses this
value to determine whether or not input is available on the
current input source (`rl_instream' by default). The value
is specified in milliseconds, so a value of 1000 means that
Readline will wait one second for additional input. If this
variable is set to a value less than or equal to zero, or to a
non-numeric value, Readline will wait until another key is
pressed to decide which key sequence to complete. The
default value is `500'.
`mark-directories'
If set to `on', completed directory names have a slash
appended. The default is `on'.
`mark-modified-lines'
This variable, when set to `on', causes Readline to display an
asterisk (`*') at the start of history lines which have been
modified. This variable is `off' by default.
`mark-symlinked-directories'
If set to `on', completed names which are symbolic links to
directories have a slash appended (subject to the value of
`mark-directories'). The default is `off'.
`match-hidden-files'
This variable, when set to `on', causes Readline to match
files whose names begin with a `.' (hidden files) when
performing filename completion. If set to `off', the leading
`.' must be supplied by the user in the filename to be
completed. This variable is `on' by default.
`menu-complete-display-prefix'
If set to `on', menu completion displays the common prefix of
the list of possible completions (which may be empty) before
cycling through the list. The default is `off'.
`output-meta'
If set to `on', Readline will display characters with the
eighth bit set directly rather than as a meta-prefixed escape
sequence. The default is `off'.
`page-completions'
If set to `on', Readline uses an internal `more'-like pager
to display a screenful of possible completions at a time.
This variable is `on' by default.
`print-completions-horizontally'
If set to `on', Readline will display completions with matches
sorted horizontally in alphabetical order, rather than down
the screen. The default is `off'.
`revert-all-at-newline'
If set to `on', Readline will undo all changes to history
lines before returning when `accept-line' is executed. By
default, history lines may be modified and retain individual
undo lists across calls to `readline'. The default is `off'.
`show-all-if-ambiguous'
This alters the default behavior of the completion functions.
If set to `on', words which have more than one possible
completion cause the matches to be listed immediately instead
of ringing the bell. The default value is `off'.
`show-all-if-unmodified'
This alters the default behavior of the completion functions
in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
`on', words which have more than one possible completion
without any possible partial completion (the possible
completions don't share a common prefix) cause the matches to
be listed immediately instead of ringing the bell. The
default value is `off'.
`show-mode-in-prompt'
If set to `on', add a character to the beginning of the prompt
indicating the editing mode: emacs (`@'), vi command (`:'),
or vi insertion (`+'). The default value is `off'.
`skip-completed-text'
If set to `on', this alters the default completion behavior
when inserting a single match into the line. It's only
active when performing completion in the middle of a word.
If enabled, readline does not insert characters from the
completion that match characters after point in the word
being completed, so portions of the word following the cursor
are not duplicated. For instance, if this is enabled,
attempting completion when the cursor is after the `e' in
`Makefile' will result in `Makefile' rather than
`Makefilefile', assuming there is a single possible
completion. The default value is `off'.
`visible-stats'
If set to `on', a character denoting a file's type is
appended to the filename when listing possible completions.
The default is `off'.
Key Bindings
The syntax for controlling key bindings in the init file is
simple. First you need to find the name of the command that you
want to change. The following sections contain tables of the
command name, the default keybinding, if any, and a short
description of what the command does.
Once you know the name of the command, simply place on a line in
the init file the name of the key you wish to bind the command to,
a colon, and then the name of the command. There can be no space
between the key name and the colon - that will be interpreted as
part of the key name. The name of the key can be expressed in
different ways, depending on what you find most comfortable.
In addition to command names, readline allows keys to be bound to
a string that is inserted when the key is pressed (a MACRO).
KEYNAME: FUNCTION-NAME or MACRO
KEYNAME is the name of a key spelled out in English. For
example:
Control-u: universal-argument
Meta-Rubout: backward-kill-word
Control-o: "> output"
In the above example, `C-u' is bound to the function
`universal-argument', `M-DEL' is bound to the function
`backward-kill-word', and `C-o' is bound to run the macro
expressed on the right hand side (that is, to insert the text
`> output' into the line).
A number of symbolic character names are recognized while
processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
"KEYSEQ": FUNCTION-NAME or MACRO
KEYSEQ differs from KEYNAME above in that strings denoting an
entire key sequence can be specified, by placing the key
sequence in double quotes. Some GNU Emacs style key escapes
can be used, as in the following example, but the special
character names are not recognized.
"\C-u": universal-argument
"\C-x\C-r": re-read-init-file
"\e[11~": "Function Key 1"
In the above example, `C-u' is again bound to the function
`universal-argument' (just as it was in the first example),
`C-x C-r' is bound to the function `re-read-init-file', and
` <[> <1> <1> <~>' is bound to insert the text `Function
Key 1'.
The following GNU Emacs style escape sequences are available when
specifying key sequences:
`\C-'
control prefix
`\M-'
meta prefix
`\e'
an escape character
`\\'
backslash
`\"'
<">, a double quotation mark
`\''
<'>, a single quote or apostrophe
In addition to the GNU Emacs style escape sequences, a second set
of backslash escapes is available:
`\a'
alert (bell)
`\b'
backspace
`\d'
delete
`\f'
form feed
`\n'
newline
`\r'
carriage return
`\t'
horizontal tab
`\v'
vertical tab
`\NNN'
the eight-bit character whose value is the octal value NNN
(one to three digits)
`\xHH'
the eight-bit character whose value is the hexadecimal value
HH (one or two hex digits)
When entering the text of a macro, single or double quotes must be
used to indicate a macro definition. Unquoted text is assumed to
be a function name. In the macro body, the backslash escapes
described above are expanded. Backslash will quote any other
character in the macro text, including `"' and `''. For example,
the following binding will make `C-x \' insert a single `\' into
the line:
"\C-x\\": "\\"
File: readline.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
1.3.2 Conditional Init Constructs
---------------------------------
Readline implements a facility similar in spirit to the conditional
compilation features of the C preprocessor which allows key bindings
and variable settings to be performed as the result of tests. There
are four parser directives used.
`$if'
The `$if' construct allows bindings to be made based on the
editing mode, the terminal being used, or the application using
Readline. The text of the test extends to the end of the line; no
characters are required to isolate it.
`mode'
The `mode=' form of the `$if' directive is used to test
whether Readline is in `emacs' or `vi' mode. This may be
used in conjunction with the `set keymap' command, for
instance, to set bindings in the `emacs-standard' and
`emacs-ctlx' keymaps only if Readline is starting out in
`emacs' mode.
`term'
The `term=' form may be used to include terminal-specific key
bindings, perhaps to bind the key sequences output by the
terminal's function keys. The word on the right side of the
`=' is tested against both the full name of the terminal and
the portion of the terminal name before the first `-'. This
allows `sun' to match both `sun' and `sun-cmd', for instance.
`application'
The APPLICATION construct is used to include
application-specific settings. Each program using the
Readline library sets the APPLICATION NAME, and you can test
for a particular value. This could be used to bind key
sequences to functions useful for a specific program. For
instance, the following command adds a key sequence that
quotes the current or previous word in Bash:
$if Bash
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
$endif
`$endif'
This command, as seen in the previous example, terminates an `$if'
command.
`$else'
Commands in this branch of the `$if' directive are executed if the
test fails.
`$include'
This directive takes a single filename as an argument and reads
commands and bindings from that file. For example, the following
directive reads from `/etc/inputrc':
$include /etc/inputrc
File: readline.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
1.3.3 Sample Init File
----------------------
Here is an example of an INPUTRC file. This illustrates key binding,
variable assignment, and conditional syntax.
# This file controls the behaviour of line input editing for
# programs that use the GNU Readline library. Existing
# programs include FTP, Bash, and GDB.
#
# You can re-read the inputrc file with C-x C-r.
# Lines beginning with '#' are comments.
#
# First, include any system-wide bindings and variable
# assignments from /etc/Inputrc
$include /etc/Inputrc
#
# Set various bindings for emacs mode.
set editing-mode emacs
$if mode=emacs
Meta-Control-h: backward-kill-word Text after the function name is ignored
#
# Arrow keys in keypad mode
#
#"\M-OD": backward-char
#"\M-OC": forward-char
#"\M-OA": previous-history
#"\M-OB": next-history
#
# Arrow keys in ANSI mode
#
"\M-[D": backward-char
"\M-[C": forward-char
"\M-[A": previous-history
"\M-[B": next-history
#
# Arrow keys in 8 bit keypad mode
#
#"\M-\C-OD": backward-char
#"\M-\C-OC": forward-char
#"\M-\C-OA": previous-history
#"\M-\C-OB": next-history
#
# Arrow keys in 8 bit ANSI mode
#
#"\M-\C-[D": backward-char
#"\M-\C-[C": forward-char
#"\M-\C-[A": previous-history
#"\M-\C-[B": next-history
C-q: quoted-insert
$endif
# An old-style binding. This happens to be the default.
TAB: complete
# Macros that are convenient for shell interaction
$if Bash
# edit the path
"\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
# prepare to type a quoted word --
# insert open and close double quotes
# and move to just after the open quote
"\C-x\"": "\"\"\C-b"
# insert a backslash (testing backslash escapes
# in sequences and macros)
"\C-x\\": "\\"
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
# Add a binding to refresh the line, which is unbound
"\C-xr": redraw-current-line
# Edit variable on current line.
"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
$endif
# use a visible bell if one is available
set bell-style visible
# don't strip characters to 7 bits when reading
set input-meta on
# allow iso-latin1 characters to be inserted rather
# than converted to prefix-meta sequences
set convert-meta off
# display characters with the eighth bit set directly
# rather than as meta-prefixed characters
set output-meta on
# if there are more than 150 possible completions for
# a word, ask the user if he wants to see all of them
set completion-query-items 150
# For FTP
$if Ftp
"\C-xg": "get \M-?"
"\C-xt": "put \M-?"
"\M-.": yank-last-arg
$endif
File: readline.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
1.4 Bindable Readline Commands
==============================
* Menu:
* Commands For Moving:: Moving about the line.
* Commands For History:: Getting at previous lines.
* Commands For Text:: Commands for changing text.
* Commands For Killing:: Commands for killing and yanking.
* Numeric Arguments:: Specifying numeric arguments, repeat counts.
* Commands For Completion:: Getting Readline to do the typing for you.
* Keyboard Macros:: Saving and re-executing typed characters
* Miscellaneous Commands:: Other miscellaneous commands.
This section describes Readline commands that may be bound to key
sequences. Command names without an accompanying key sequence are
unbound by default.
In the following descriptions, "point" refers to the current cursor
position, and "mark" refers to a cursor position saved by the
`set-mark' command. The text between the point and mark is referred to
as the "region".
File: readline.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
1.4.1 Commands For Moving
-------------------------
`beginning-of-line (C-a)'
Move to the start of the current line.
`end-of-line (C-e)'
Move to the end of the line.
`forward-char (C-f)'
Move forward a character.
`backward-char (C-b)'
Move back a character.
`forward-word (M-f)'
Move forward to the end of the next word. Words are composed of
letters and digits.
`backward-word (M-b)'
Move back to the start of the current or previous word. Words are
composed of letters and digits.
`clear-screen (C-l)'
Clear the screen and redraw the current line, leaving the current
line at the top of the screen.
`redraw-current-line ()'
Refresh the current line. By default, this is unbound.
File: readline.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
1.4.2 Commands For Manipulating The History
-------------------------------------------
`accept-line (Newline or Return)'
Accept the line regardless of where the cursor is. If this line is
non-empty, it may be added to the history list for future recall
with `add_history()'. If this line is a modified history line,
the history line is restored to its original state.
`previous-history (C-p)'
Move `back' through the history list, fetching the previous
command.
`next-history (C-n)'
Move `forward' through the history list, fetching the next command.
`beginning-of-history (M-<)'
Move to the first line in the history.
`end-of-history (M->)'
Move to the end of the input history, i.e., the line currently
being entered.
`reverse-search-history (C-r)'
Search backward starting at the current line and moving `up'
through the history as necessary. This is an incremental search.
`forward-search-history (C-s)'
Search forward starting at the current line and moving `down'
through the the history as necessary. This is an incremental
search.
`non-incremental-reverse-search-history (M-p)'
Search backward starting at the current line and moving `up'
through the history as necessary using a non-incremental search
for a string supplied by the user.
`non-incremental-forward-search-history (M-n)'
Search forward starting at the current line and moving `down'
through the the history as necessary using a non-incremental search
for a string supplied by the user.
`history-search-forward ()'
Search forward through the history for the string of characters
between the start of the current line and the point. The search
string must match at the beginning of a history line. This is a
non-incremental search. By default, this command is unbound.
`history-search-backward ()'
Search backward through the history for the string of characters
between the start of the current line and the point. The search
string must match at the beginning of a history line. This is a
non-incremental search. By default, this command is unbound.
`history-substr-search-forward ()'
Search forward through the history for the string of characters
between the start of the current line and the point. The search
string may match anywhere in a history line. This is a
non-incremental search. By default, this command is unbound.
`history-substr-search-backward ()'
Search backward through the history for the string of characters
between the start of the current line and the point. The search
string may match anywhere in a history line. This is a
non-incremental search. By default, this command is unbound.
`yank-nth-arg (M-C-y)'
Insert the first argument to the previous command (usually the
second word on the previous line) at point. With an argument N,
insert the Nth word from the previous command (the words in the
previous command begin with word 0). A negative argument inserts
the Nth word from the end of the previous command. Once the
argument N is computed, the argument is extracted as if the `!N'
history expansion had been specified.
`yank-last-arg (M-. or M-_)'
Insert last argument to the previous command (the last word of the
previous history entry). With a numeric argument, behave exactly
like `yank-nth-arg'. Successive calls to `yank-last-arg' move
back through the history list, inserting the last word (or the
word specified by the argument to the first call) of each line in
turn. Any numeric argument supplied to these successive calls
determines the direction to move through the history. A negative
argument switches the direction through the history (back or
forward). The history expansion facilities are used to extract
the last argument, as if the `!$' history expansion had been
specified.
File: readline.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
1.4.3 Commands For Changing Text
--------------------------------
`end-of-file (usually C-d)'
The character indicating end-of-file as set, for example, by
`stty'. If this character is read when there are no characters on
the line, and point is at the beginning of the line, Readline
interprets it as the end of input and returns EOF.
`delete-char (C-d)'
Delete the character at point. If this function is bound to the
same character as the tty EOF character, as `C-d' commonly is, see
above for the effects.
`backward-delete-char (Rubout)'
Delete the character behind the cursor. A numeric argument means
to kill the characters instead of deleting them.
`forward-backward-delete-char ()'
Delete the character under the cursor, unless the cursor is at the
end of the line, in which case the character behind the cursor is
deleted. By default, this is not bound to a key.
`quoted-insert (C-q or C-v)'
Add the next character typed to the line verbatim. This is how to
insert key sequences like `C-q', for example.
`tab-insert (M-)'
Insert a tab character.
`self-insert (a, b, A, 1, !, ...)'
Insert yourself.
`transpose-chars (C-t)'
Drag the character before the cursor forward over the character at
the cursor, moving the cursor forward as well. If the insertion
point is at the end of the line, then this transposes the last two
characters of the line. Negative arguments have no effect.
`transpose-words (M-t)'
Drag the word before point past the word after point, moving point
past that word as well. If the insertion point is at the end of
the line, this transposes the last two words on the line.
`upcase-word (M-u)'
Uppercase the current (or following) word. With a negative
argument, uppercase the previous word, but do not move the cursor.
`downcase-word (M-l)'
Lowercase the current (or following) word. With a negative
argument, lowercase the previous word, but do not move the cursor.
`capitalize-word (M-c)'
Capitalize the current (or following) word. With a negative
argument, capitalize the previous word, but do not move the cursor.
`overwrite-mode ()'
Toggle overwrite mode. With an explicit positive numeric argument,
switches to overwrite mode. With an explicit non-positive numeric
argument, switches to insert mode. This command affects only
`emacs' mode; `vi' mode does overwrite differently. Each call to
`readline()' starts in insert mode.
In overwrite mode, characters bound to `self-insert' replace the
text at point rather than pushing the text to the right.
Characters bound to `backward-delete-char' replace the character
before point with a space.
By default, this command is unbound.
File: readline.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
1.4.4 Killing And Yanking
-------------------------
`kill-line (C-k)'
Kill the text from point to the end of the line.
`backward-kill-line (C-x Rubout)'
Kill backward to the beginning of the line.
`unix-line-discard (C-u)'
Kill backward from the cursor to the beginning of the current line.
`kill-whole-line ()'
Kill all characters on the current line, no matter where point is.
By default, this is unbound.
`kill-word (M-d)'
Kill from point to the end of the current word, or if between
words, to the end of the next word. Word boundaries are the same
as `forward-word'.
`backward-kill-word (M-)'
Kill the word behind point. Word boundaries are the same as
`backward-word'.
`unix-word-rubout (C-w)'
Kill the word behind point, using white space as a word boundary.
The killed text is saved on the kill-ring.
`unix-filename-rubout ()'
Kill the word behind point, using white space and the slash
character as the word boundaries. The killed text is saved on the
kill-ring.
`delete-horizontal-space ()'
Delete all spaces and tabs around point. By default, this is
unbound.
`kill-region ()'
Kill the text in the current region. By default, this command is
unbound.
`copy-region-as-kill ()'
Copy the text in the region to the kill buffer, so it can be yanked
right away. By default, this command is unbound.
`copy-backward-word ()'
Copy the word before point to the kill buffer. The word
boundaries are the same as `backward-word'. By default, this
command is unbound.
`copy-forward-word ()'
Copy the word following point to the kill buffer. The word
boundaries are the same as `forward-word'. By default, this
command is unbound.
`yank (C-y)'
Yank the top of the kill ring into the buffer at point.
`yank-pop (M-y)'
Rotate the kill-ring, and yank the new top. You can only do this
if the prior command is `yank' or `yank-pop'.
File: readline.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
1.4.5 Specifying Numeric Arguments
----------------------------------
`digit-argument (M-0, M-1, ... M--)'
Add this digit to the argument already accumulating, or start a new
argument. `M--' starts a negative argument.
`universal-argument ()'
This is another way to specify an argument. If this command is
followed by one or more digits, optionally with a leading minus
sign, those digits define the argument. If the command is
followed by digits, executing `universal-argument' again ends the
numeric argument, but is otherwise ignored. As a special case, if
this command is immediately followed by a character that is
neither a digit or minus sign, the argument count for the next
command is multiplied by four. The argument count is initially
one, so executing this function the first time makes the argument
count four, a second time makes the argument count sixteen, and so
on. By default, this is not bound to a key.
File: readline.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
1.4.6 Letting Readline Type For You
-----------------------------------
`complete ()'
Attempt to perform completion on the text before point. The
actual completion performed is application-specific. The default
is filename completion.
`possible-completions (M-?)'
List the possible completions of the text before point. When
displaying completions, Readline sets the number of columns used
for display to the value of `completion-display-width', the value
of the environment variable `COLUMNS', or the screen width, in
that order.
`insert-completions (M-*)'
Insert all completions of the text before point that would have
been generated by `possible-completions'.
`menu-complete ()'
Similar to `complete', but replaces the word to be completed with
a single match from the list of possible completions. Repeated
execution of `menu-complete' steps through the list of possible
completions, inserting each match in turn. At the end of the list
of completions, the bell is rung (subject to the setting of
`bell-style') and the original text is restored. An argument of N
moves N positions forward in the list of matches; a negative
argument may be used to move backward through the list. This
command is intended to be bound to , but is unbound by
default.
`menu-complete-backward ()'
Identical to `menu-complete', but moves backward through the list
of possible completions, as if `menu-complete' had been given a
negative argument.
`delete-char-or-list ()'
Deletes the character under the cursor if not at the beginning or
end of the line (like `delete-char'). If at the end of the line,
behaves identically to `possible-completions'. This command is
unbound by default.
File: readline.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
1.4.7 Keyboard Macros
---------------------
`start-kbd-macro (C-x ()'
Begin saving the characters typed into the current keyboard macro.
`end-kbd-macro (C-x ))'
Stop saving the characters typed into the current keyboard macro
and save the definition.
`call-last-kbd-macro (C-x e)'
Re-execute the last keyboard macro defined, by making the
characters in the macro appear as if typed at the keyboard.
`print-last-kbd-macro ()'
Print the last keboard macro defined in a format suitable for the
INPUTRC file.
File: readline.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
1.4.8 Some Miscellaneous Commands
---------------------------------
`re-read-init-file (C-x C-r)'
Read in the contents of the INPUTRC file, and incorporate any
bindings or variable assignments found there.
`abort (C-g)'
Abort the current editing command and ring the terminal's bell
(subject to the setting of `bell-style').
`do-uppercase-version (M-a, M-b, M-X, ...)'
If the metafied character X is lowercase, run the command that is
bound to the corresponding uppercase character.
`prefix-meta ()'
Metafy the next character typed. This is for keyboards without a
meta key. Typing ` f' is equivalent to typing `M-f'.
`undo (C-_ or C-x C-u)'
Incremental undo, separately remembered for each line.
`revert-line (M-r)'
Undo all changes made to this line. This is like executing the
`undo' command enough times to get back to the beginning.
`tilde-expand (M-~)'
Perform tilde expansion on the current word.
`set-mark (C-@)'
Set the mark to the point. If a numeric argument is supplied, the
mark is set to that position.
`exchange-point-and-mark (C-x C-x)'
Swap the point with the mark. The current cursor position is set
to the saved position, and the old cursor position is saved as the
mark.
`character-search (C-])'
A character is read and point is moved to the next occurrence of
that character. A negative count searches for previous
occurrences.
`character-search-backward (M-C-])'
A character is read and point is moved to the previous occurrence
of that character. A negative count searches for subsequent
occurrences.
`skip-csi-sequence ()'
Read enough characters to consume a multi-key sequence such as
those defined for keys like Home and End. Such sequences begin
with a Control Sequence Indicator (CSI), usually ESC-[. If this
sequence is bound to "\e[", keys producing such sequences will
have no effect unless explicitly bound to a readline command,
instead of inserting stray characters into the editing buffer.
This is unbound by default, but usually bound to ESC-[.
`insert-comment (M-#)'
Without a numeric argument, the value of the `comment-begin'
variable is inserted at the beginning of the current line. If a
numeric argument is supplied, this command acts as a toggle: if
the characters at the beginning of the line do not match the value
of `comment-begin', the value is inserted, otherwise the
characters in `comment-begin' are deleted from the beginning of
the line. In either case, the line is accepted as if a newline
had been typed.
`dump-functions ()'
Print all of the functions and their key bindings to the Readline
output stream. If a numeric argument is supplied, the output is
formatted in such a way that it can be made part of an INPUTRC
file. This command is unbound by default.
`dump-variables ()'
Print all of the settable variables and their values to the
Readline output stream. If a numeric argument is supplied, the
output is formatted in such a way that it can be made part of an
INPUTRC file. This command is unbound by default.
`dump-macros ()'
Print all of the Readline key sequences bound to macros and the
strings they output. If a numeric argument is supplied, the
output is formatted in such a way that it can be made part of an
INPUTRC file. This command is unbound by default.
`emacs-editing-mode (C-e)'
When in `vi' command mode, this causes a switch to `emacs' editing
mode.
`vi-editing-mode (M-C-j)'
When in `emacs' editing mode, this causes a switch to `vi' editing
mode.
File: readline.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
1.5 Readline vi Mode
====================
While the Readline library does not have a full set of `vi' editing
functions, it does contain enough to allow simple editing of the line.
The Readline `vi' mode behaves as specified in the POSIX standard.
In order to switch interactively between `emacs' and `vi' editing
modes, use the command `M-C-j' (bound to emacs-editing-mode when in
`vi' mode and to vi-editing-mode in `emacs' mode). The Readline
default is `emacs' mode.
When you enter a line in `vi' mode, you are already placed in
`insertion' mode, as if you had typed an `i'. Pressing switches
you into `command' mode, where you can edit the text of the line with
the standard `vi' movement keys, move to previous history lines with
`k' and subsequent lines with `j', and so forth.
This document describes the GNU Readline Library, a utility for
aiding in the consistency of user interface across discrete programs
that need to provide a command line interface.
Copyright (C) 1988-2014 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice pare
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: readline.info, Node: Programming with GNU Readline, Next: GNU Free Documentation License, Prev: Command Line Editing, Up: Top
2 Programming with GNU Readline
*******************************
This chapter describes the interface between the GNU Readline Library
and other programs. If you are a programmer, and you wish to include
the features found in GNU Readline such as completion, line editing,
and interactive history manipulation in your own programs, this section
is for you.
* Menu:
* Basic Behavior:: Using the default behavior of Readline.
* Custom Functions:: Adding your own functions to Readline.
* Readline Variables:: Variables accessible to custom
functions.
* Readline Convenience Functions:: Functions which Readline supplies to
aid in writing your own custom
functions.
* Readline Signal Handling:: How Readline behaves when it receives signals.
* Custom Completers:: Supplanting or supplementing Readline's
completion functions.
File: readline.info, Node: Basic Behavior, Next: Custom Functions, Up: Programming with GNU Readline
2.1 Basic Behavior
==================
Many programs provide a command line interface, such as `mail', `ftp',
and `sh'. For such programs, the default behaviour of Readline is
sufficient. This section describes how to use Readline in the simplest
way possible, perhaps to replace calls in your code to `gets()' or
`fgets()'.
The function `readline()' prints a prompt PROMPT and then reads and
returns a single line of text from the user. If PROMPT is `NULL' or
the empty string, no prompt is displayed. The line `readline' returns
is allocated with `malloc()'; the caller should `free()' the line when
it has finished with it. The declaration for `readline' in ANSI C is
`char *readline (const char *PROMPT);'
So, one might say
`char *line = readline ("Enter a line: ");'
in order to read a line of text from the user. The line returned
has the final newline removed, so only the text remains.
If `readline' encounters an `EOF' while reading the line, and the
line is empty at that point, then `(char *)NULL' is returned.
Otherwise, the line is ended just as if a newline had been typed.
If you want the user to be able to get at the line later, (with
for example), you must call `add_history()' to save the line away
in a "history" list of such lines.
`add_history (line)';
For full details on the GNU History Library, see the associated manual.
It is preferable to avoid saving empty lines on the history list,
since users rarely have a burning need to reuse a blank line. Here is
a function which usefully replaces the standard `gets()' library
function, and has the advantage of no static buffer to overflow:
/* A static variable for holding the line. */
static char *line_read = (char *)NULL;
/* Read a string, and return a pointer to it.
Returns NULL on EOF. */
char *
rl_gets ()
{
/* If the buffer has already been allocated,
return the memory to the free pool. */
if (line_read)
{
free (line_read);
line_read = (char *)NULL;
}
/* Get a line from the user. */
line_read = readline ("");
/* If the line has any text in it,
save it on the history. */
if (line_read && *line_read)
add_history (line_read);
return (line_read);
}
This function gives the user the default behaviour of
completion: completion on file names. If you do not want Readline to
complete on filenames, you can change the binding of the key with
`rl_bind_key()'.
`int rl_bind_key (int KEY, rl_command_func_t *FUNCTION);'
`rl_bind_key()' takes two arguments: KEY is the character that you
want to bind, and FUNCTION is the address of the function to call when
KEY is pressed. Binding to `rl_insert()' makes insert
itself. `rl_bind_key()' returns non-zero if KEY is not a valid ASCII
character code (between 0 and 255).
Thus, to disable the default behavior, the following suffices:
`rl_bind_key ('\t', rl_insert);'
This code should be executed once at the start of your program; you
might write a function called `initialize_readline()' which performs
this and other desired initializations, such as installing custom
completers (*note Custom Completers::).
File: readline.info, Node: Custom Functions, Next: Readline Variables, Prev: Basic Behavior, Up: Programming with GNU Readline
2.2 Custom Functions
====================
Readline provides many functions for manipulating the text of the line,
but it isn't possible to anticipate the needs of all programs. This
section describes the various functions and variables defined within
the Readline library which allow a user program to add customized
functionality to Readline.
Before declaring any functions that customize Readline's behavior, or
using any functionality Readline provides in other code, an application
writer should include the file `' in any file that
uses Readline's features. Since some of the definitions in
`readline.h' use the `stdio' library, the file `' should be
included before `readline.h'.
`readline.h' defines a C preprocessor variable that should be
treated as an integer, `RL_READLINE_VERSION', which may be used to
conditionally compile application code depending on the installed
Readline version. The value is a hexadecimal encoding of the major and
minor version numbers of the library, of the form 0xMMMM. MM is the
two-digit major version number; MM is the two-digit minor version
number. For Readline 4.2, for example, the value of
`RL_READLINE_VERSION' would be `0x0402'.
* Menu:
* Readline Typedefs:: C declarations to make code readable.
* Function Writing:: Variables and calling conventions.
File: readline.info, Node: Readline Typedefs, Next: Function Writing, Up: Custom Functions
2.2.1 Readline Typedefs
-----------------------
For readability, we declare a number of new object types, all pointers
to functions.
The reason for declaring these new types is to make it easier to
write code describing pointers to C functions with appropriately
prototyped arguments and return values.
For instance, say we want to declare a variable FUNC as a pointer to
a function which takes two `int' arguments and returns an `int' (this
is the type of all of the Readline bindable functions). Instead of the
classic C declaration
`int (*func)();'
or the ANSI-C style declaration
`int (*func)(int, int);'
we may write
`rl_command_func_t *func;'
The full list of function pointer types available is
`typedef int rl_command_func_t (int, int);'
`typedef char *rl_compentry_func_t (const char *, int);'
`typedef char **rl_completion_func_t (const char *, int, int);'
`typedef char *rl_quote_func_t (char *, int, char *);'
`typedef char *rl_dequote_func_t (char *, int);'
`typedef int rl_compignore_func_t (char **);'
`typedef void rl_compdisp_func_t (char **, int, int);'
`typedef int rl_hook_func_t (void);'
`typedef int rl_getc_func_t (FILE *);'
`typedef int rl_linebuf_func_t (char *, int);'
`typedef int rl_intfunc_t (int);'
`#define rl_ivoidfunc_t rl_hook_func_t'
`typedef int rl_icpfunc_t (char *);'
`typedef int rl_icppfunc_t (char **);'
`typedef void rl_voidfunc_t (void);'
`typedef void rl_vintfunc_t (int);'
`typedef void rl_vcpfunc_t (char *);'
`typedef void rl_vcppfunc_t (char **);'
File: readline.info, Node: Function Writing, Prev: Readline Typedefs, Up: Custom Functions
2.2.2 Writing a New Function
----------------------------
In order to write new functions for Readline, you need to know the
calling conventions for keyboard-invoked functions, and the names of the
variables that describe the current state of the line read so far.
The calling sequence for a command `foo' looks like
`int foo (int count, int key)'
where COUNT is the numeric argument (or 1 if defaulted) and KEY is the
key that invoked this function.
It is completely up to the function as to what should be done with
the numeric argument. Some functions use it as a repeat count, some as
a flag, and others to choose alternate behavior (refreshing the current
line as opposed to refreshing the screen, for example). Some choose to
ignore it. In general, if a function uses the numeric argument as a
repeat count, it should be able to do something useful with both
negative and positive arguments. At the very least, it should be aware
that it can be passed a negative argument.
A command function should return 0 if its action completes
successfully, and a non-zero value if some error occurs. This is the
convention obeyed by all of the builtin Readline bindable command
functions.
File: readline.info, Node: Readline Variables, Next: Readline Convenience Functions, Prev: Custom Functions, Up: Programming with GNU Readline
2.3 Readline Variables
======================
These variables are available to function writers.
-- Variable: char * rl_line_buffer
This is the line gathered so far. You are welcome to modify the
contents of the line, but see *note Allowing Undoing::. The
function `rl_extend_line_buffer' is available to increase the
memory allocated to `rl_line_buffer'.
-- Variable: int rl_point
The offset of the current cursor position in `rl_line_buffer' (the
_point_).
-- Variable: int rl_end
The number of characters present in `rl_line_buffer'. When
`rl_point' is at the end of the line, `rl_point' and `rl_end' are
equal.
-- Variable: int rl_mark
The MARK (saved position) in the current line. If set, the mark
and point define a _region_.
-- Variable: int rl_done
Setting this to a non-zero value causes Readline to return the
current line immediately.
-- Variable: int rl_num_chars_to_read
Setting this to a positive value before calling `readline()' causes
Readline to return after accepting that many characters, rather
than reading up to a character bound to `accept-line'.
-- Variable: int rl_pending_input
Setting this to a value makes it the next keystroke read. This is
a way to stuff a single character into the input stream.
-- Variable: int rl_dispatching
Set to a non-zero value if a function is being called from a key
binding; zero otherwise. Application functions can test this to
discover whether they were called directly or by Readline's
dispatching mechanism.
-- Variable: int rl_erase_empty_line
Setting this to a non-zero value causes Readline to completely
erase the current line, including any prompt, any time a newline
is typed as the only character on an otherwise-empty line. The
cursor is moved to the beginning of the newly-blank line.
-- Variable: char * rl_prompt
The prompt Readline uses. This is set from the argument to
`readline()', and should not be assigned to directly. The
`rl_set_prompt()' function (*note Redisplay::) may be used to
modify the prompt string after calling `readline()'.
-- Variable: char * rl_display_prompt
The string displayed as the prompt. This is usually identical to
RL_PROMPT, but may be changed temporarily by functions that use
the prompt string as a message area, such as incremental search.
-- Variable: int rl_already_prompted
If an application wishes to display the prompt itself, rather than
have Readline do it the first time `readline()' is called, it
should set this variable to a non-zero value after displaying the
prompt. The prompt must also be passed as the argument to
`readline()' so the redisplay functions can update the display
properly. The calling application is responsible for managing the
value; Readline never sets it.
-- Variable: const char * rl_library_version
The version number of this revision of the library.
-- Variable: int rl_readline_version
An integer encoding the current version of the library. The
encoding is of the form 0xMMMM, where MM is the two-digit major
version number, and MM is the two-digit minor version number. For
example, for Readline-4.2, `rl_readline_version' would have the
value 0x0402.
-- Variable: int rl_gnu_readline_p
Always set to 1, denoting that this is GNU readline rather than
some emulation.
-- Variable: const char * rl_terminal_name
The terminal type, used for initialization. If not set by the
application, Readline sets this to the value of the `TERM'
environment variable the first time it is called.
-- Variable: const char * rl_readline_name
This variable is set to a unique name by each application using
Readline. The value allows conditional parsing of the inputrc file
(*note Conditional Init Constructs::).
-- Variable: FILE * rl_instream
The stdio stream from which Readline reads input. If `NULL',
Readline defaults to STDIN.
-- Variable: FILE * rl_outstream
The stdio stream to which Readline performs output. If `NULL',
Readline defaults to STDOUT.
-- Variable: int rl_prefer_env_winsize
If non-zero, Readline gives values found in the `LINES' and
`COLUMNS' environment variables greater precedence than values
fetched from the kernel when computing the screen dimensions.
-- Variable: rl_command_func_t * rl_last_func
The address of the last command function Readline executed. May
be used to test whether or not a function is being executed twice
in succession, for example.
-- Variable: rl_hook_func_t * rl_startup_hook
If non-zero, this is the address of a function to call just before
`readline' prints the first prompt.
-- Variable: rl_hook_func_t * rl_pre_input_hook
If non-zero, this is the address of a function to call after the
first prompt has been printed and just before `readline' starts
reading input characters.
-- Variable: rl_hook_func_t * rl_event_hook
If non-zero, this is the address of a function to call periodically
when Readline is waiting for terminal input. By default, this
will be called at most ten times a second if there is no keyboard
input.
-- Variable: rl_getc_func_t * rl_getc_function
If non-zero, Readline will call indirectly through this pointer to
get a character from the input stream. By default, it is set to
`rl_getc', the default Readline character input function (*note
Character Input::). In general, an application that sets
RL_GETC_FUNCTION should consider setting RL_INPUT_AVAILABLE_HOOK
as well.
-- Variable: rl_hook_func_t * rl_signal_event_hook
If non-zero, this is the address of a function to call if a read
system call is interrupted when Readline is reading terminal input.
-- Variable: rl_hook_func_t * rl_input_available_hook
If non-zero, Readline will use this function's return value when
it needs to determine whether or not there is available input on
the current input source. The default hook checks `rl_instream';
if an application is using a different input source, it should set
the hook appropriately. Readline queries for available input when
implementing intra-key-sequence timeouts during input and
incremental searches. This may use an application-specific
timeout before returning a value; Readline uses the value passed
to `rl_set_keyboard_input_timeout()' or the value of the
user-settable KEYSEQ-TIMEOUT variable. This is designed for use
by applications using Readline's callback interface (*note
Alternate Interface::), which may not use the traditional
`read(2)' and file descriptor interface, or other applications
using a different input mechanism. If an application uses an
input mechanism or hook that can potentially exceed the value of
KEYSEQ-TIMEOUT, it should increase the timeout or set this hook
appropriately even when not using the callback interface. In
general, an application that sets RL_GETC_FUNCTION should consider
setting RL_INPUT_AVAILABLE_HOOK as well.
-- Variable: rl_voidfunc_t * rl_redisplay_function
If non-zero, Readline will call indirectly through this pointer to
update the display with the current contents of the editing buffer.
By default, it is set to `rl_redisplay', the default Readline
redisplay function (*note Redisplay::).
-- Variable: rl_vintfunc_t * rl_prep_term_function
If non-zero, Readline will call indirectly through this pointer to
initialize the terminal. The function takes a single argument, an
`int' flag that says whether or not to use eight-bit characters.
By default, this is set to `rl_prep_terminal' (*note Terminal
Management::).
-- Variable: rl_voidfunc_t * rl_deprep_term_function
If non-zero, Readline will call indirectly through this pointer to
reset the terminal. This function should undo the effects of
`rl_prep_term_function'. By default, this is set to
`rl_deprep_terminal' (*note Terminal Management::).
-- Variable: Keymap rl_executing_keymap
This variable is set to the keymap (*note Keymaps::) in which the
currently executing readline function was found.
-- Variable: Keymap rl_binding_keymap
This variable is set to the keymap (*note Keymaps::) in which the
last key binding occurred.
-- Variable: char * rl_executing_macro
This variable is set to the text of any currently-executing macro.
-- Variable: int rl_executing_key
The key that caused the dispatch to the currently-executing
Readline function.
-- Variable: char * rl_executing_keyseq
The full key sequence that caused the dispatch to the
currently-executing Readline function.
-- Variable: int rl_key_sequence_length
The number of characters in RL_EXECUTING_KEYSEQ.
-- Variable: int rl_readline_state
A variable with bit values that encapsulate the current Readline
state. A bit is set with the `RL_SETSTATE' macro, and unset with
the `RL_UNSETSTATE' macro. Use the `RL_ISSTATE' macro to test
whether a particular state bit is set. Current state bits include:
`RL_STATE_NONE'
Readline has not yet been called, nor has it begun to
initialize.
`RL_STATE_INITIALIZING'
Readline is initializing its internal data structures.
`RL_STATE_INITIALIZED'
Readline has completed its initialization.
`RL_STATE_TERMPREPPED'
Readline has modified the terminal modes to do its own input
and redisplay.
`RL_STATE_READCMD'
Readline is reading a command from the keyboard.
`RL_STATE_METANEXT'
Readline is reading more input after reading the meta-prefix
character.
`RL_STATE_DISPATCHING'
Readline is dispatching to a command.
`RL_STATE_MOREINPUT'
Readline is reading more input while executing an editing
command.
`RL_STATE_ISEARCH'
Readline is performing an incremental history search.
`RL_STATE_NSEARCH'
Readline is performing a non-incremental history search.
`RL_STATE_SEARCH'
Readline is searching backward or forward through the history
for a string.
`RL_STATE_NUMERICARG'
Readline is reading a numeric argument.
`RL_STATE_MACROINPUT'
Readline is currently getting its input from a
previously-defined keyboard macro.
`RL_STATE_MACRODEF'
Readline is currently reading characters defining a keyboard
macro.
`RL_STATE_OVERWRITE'
Readline is in overwrite mode.
`RL_STATE_COMPLETING'
Readline is performing word completion.
`RL_STATE_SIGHANDLER'
Readline is currently executing the readline signal handler.
`RL_STATE_UNDOING'
Readline is performing an undo.
`RL_STATE_INPUTPENDING'
Readline has input pending due to a call to
`rl_execute_next()'.
`RL_STATE_TTYCSAVED'
Readline has saved the values of the terminal's special
characters.
`RL_STATE_CALLBACK'
Readline is currently using the alternate (callback) interface
(*note Alternate Interface::).
`RL_STATE_VIMOTION'
Readline is reading the argument to a vi-mode "motion"
command.
`RL_STATE_MULTIKEY'
Readline is reading a multiple-keystroke command.
`RL_STATE_VICMDONCE'
Readline has entered vi command (movement) mode at least one
time during the current call to `readline()'.
`RL_STATE_DONE'
Readline has read a key sequence bound to `accept-line' and
is about to return the line to the caller.
-- Variable: int rl_explicit_arg
Set to a non-zero value if an explicit numeric argument was
specified by the user. Only valid in a bindable command function.
-- Variable: int rl_numeric_arg
Set to the value of any numeric argument explicitly specified by
the user before executing the current Readline function. Only
valid in a bindable command function.
-- Variable: int rl_editing_mode
Set to a value denoting Readline's current editing mode. A value
of 1 means Readline is currently in emacs mode; 0 means that vi
mode is active.
File: readline.info, Node: Readline Convenience Functions, Next: Readline Signal Handling, Prev: Readline Variables, Up: Programming with GNU Readline
2.4 Readline Convenience Functions
==================================
* Menu:
* Function Naming:: How to give a function you write a name.
* Keymaps:: Making keymaps.
* Binding Keys:: Changing Keymaps.
* Associating Function Names and Bindings:: Translate function names to
key sequences.
* Allowing Undoing:: How to make your functions undoable.
* Redisplay:: Functions to control line display.
* Modifying Text:: Functions to modify `rl_line_buffer'.
* Character Input:: Functions to read keyboard input.
* Terminal Management:: Functions to manage terminal settings.
* Utility Functions:: Generally useful functions and hooks.
* Miscellaneous Functions:: Functions that don't fall into any category.
* Alternate Interface:: Using Readline in a `callback' fashion.
* A Readline Example:: An example Readline function.
* Alternate Interface Example:: An example program using the alternate interface.
File: readline.info, Node: Function Naming, Next: Keymaps, Up: Readline Convenience Functions
2.4.1 Naming a Function
-----------------------
The user can dynamically change the bindings of keys while using
Readline. This is done by representing the function with a descriptive
name. The user is able to type the descriptive name when referring to
the function. Thus, in an init file, one might find
Meta-Rubout: backward-kill-word
This binds the keystroke to the function
_descriptively_ named `backward-kill-word'. You, as the programmer,
should bind the functions you write to descriptive names as well.
Readline provides a function for doing that:
-- Function: int rl_add_defun (const char *name, rl_command_func_t
*function, int key)
Add NAME to the list of named functions. Make FUNCTION be the
function that gets called. If KEY is not -1, then bind it to
FUNCTION using `rl_bind_key()'.
Using this function alone is sufficient for most applications. It
is the recommended way to add a few functions to the default functions
that Readline has built in. If you need to do something other than
adding a function to Readline, you may need to use the underlying
functions described below.
File: readline.info, Node: Keymaps, Next: Binding Keys, Prev: Function Naming, Up: Readline Convenience Functions
2.4.2 Selecting a Keymap
------------------------
Key bindings take place on a "keymap". The keymap is the association
between the keys that the user types and the functions that get run.
You can make your own keymaps, copy existing keymaps, and tell Readline
which keymap to use.
-- Function: Keymap rl_make_bare_keymap (void)
Returns a new, empty keymap. The space for the keymap is
allocated with `malloc()'; the caller should free it by calling
`rl_free_keymap()' when done.
-- Function: Keymap rl_copy_keymap (Keymap map)
Return a new keymap which is a copy of MAP.
-- Function: Keymap rl_make_keymap (void)
Return a new keymap with the printing characters bound to
rl_insert, the lowercase Meta characters bound to run their
equivalents, and the Meta digits bound to produce numeric
arguments.
-- Function: void rl_discard_keymap (Keymap keymap)
Free the storage associated with the data in KEYMAP. The caller
should free KEYMAP.
-- Function: void rl_free_keymap (Keymap keymap)
Free all storage associated with KEYMAP. This calls
`rl_discard_keymap' to free subordindate keymaps and macros.
Readline has several internal keymaps. These functions allow you to
change which keymap is active.
-- Function: Keymap rl_get_keymap (void)
Returns the currently active keymap.
-- Function: void rl_set_keymap (Keymap keymap)
Makes KEYMAP the currently active keymap.
-- Function: Keymap rl_get_keymap_by_name (const char *name)
Return the keymap matching NAME. NAME is one which would be
supplied in a `set keymap' inputrc line (*note Readline Init
File::).
-- Function: char * rl_get_keymap_name (Keymap keymap)
Return the name matching KEYMAP. NAME is one which would be
supplied in a `set keymap' inputrc line (*note Readline Init
File::).
File: readline.info, Node: Binding Keys, Next: Associating Function Names and Bindings, Prev: Keymaps, Up: Readline Convenience Functions
2.4.3 Binding Keys
------------------
Key sequences are associate with functions through the keymap.
Readline has several internal keymaps: `emacs_standard_keymap',
`emacs_meta_keymap', `emacs_ctlx_keymap', `vi_movement_keymap', and
`vi_insertion_keymap'. `emacs_standard_keymap' is the default, and the
examples in this manual assume that.
Since `readline()' installs a set of default key bindings the first
time it is called, there is always the danger that a custom binding
installed before the first call to `readline()' will be overridden. An
alternate mechanism is to install custom key bindings in an
initialization function assigned to the `rl_startup_hook' variable
(*note Readline Variables::).
These functions manage key bindings.
-- Function: int rl_bind_key (int key, rl_command_func_t *function)
Binds KEY to FUNCTION in the currently active keymap. Returns
non-zero in the case of an invalid KEY.
-- Function: int rl_bind_key_in_map (int key, rl_command_func_t
*function, Keymap map)
Bind KEY to FUNCTION in MAP. Returns non-zero in the case of an
invalid KEY.
-- Function: int rl_bind_key_if_unbound (int key, rl_command_func_t
*function)
Binds KEY to FUNCTION if it is not already bound in the currently
active keymap. Returns non-zero in the case of an invalid KEY or
if KEY is already bound.
-- Function: int rl_bind_key_if_unbound_in_map (int key,
rl_command_func_t *function, Keymap map)
Binds KEY to FUNCTION if it is not already bound in MAP. Returns
non-zero in the case of an invalid KEY or if KEY is already bound.
-- Function: int rl_unbind_key (int key)
Bind KEY to the null function in the currently active keymap.
Returns non-zero in case of error.
-- Function: int rl_unbind_key_in_map (int key, Keymap map)
Bind KEY to the null function in MAP. Returns non-zero in case of
error.
-- Function: int rl_unbind_function_in_map (rl_command_func_t
*function, Keymap map)
Unbind all keys that execute FUNCTION in MAP.
-- Function: int rl_unbind_command_in_map (const char *command, Keymap
map)
Unbind all keys that are bound to COMMAND in MAP.
-- Function: int rl_bind_keyseq (const char *keyseq, rl_command_func_t
*function)
Bind the key sequence represented by the string KEYSEQ to the
function FUNCTION, beginning in the current keymap. This makes
new keymaps as necessary. The return value is non-zero if KEYSEQ
is invalid.
-- Function: int rl_bind_keyseq_in_map (const char *keyseq,
rl_command_func_t *function, Keymap map)
Bind the key sequence represented by the string KEYSEQ to the
function FUNCTION. This makes new keymaps as necessary. Initial
bindings are performed in MAP. The return value is non-zero if
KEYSEQ is invalid.
-- Function: int rl_set_key (const char *keyseq, rl_command_func_t
*function, Keymap map)
Equivalent to `rl_bind_keyseq_in_map'.
-- Function: int rl_bind_keyseq_if_unbound (const char *keyseq,
rl_command_func_t *function)
Binds KEYSEQ to FUNCTION if it is not already bound in the
currently active keymap. Returns non-zero in the case of an
invalid KEYSEQ or if KEYSEQ is already bound.
-- Function: int rl_bind_keyseq_if_unbound_in_map (const char *keyseq,
rl_command_func_t *function, Keymap map)
Binds KEYSEQ to FUNCTION if it is not already bound in MAP.
Returns non-zero in the case of an invalid KEYSEQ or if KEYSEQ is
already bound.
-- Function: int rl_generic_bind (int type, const char *keyseq, char
*data, Keymap map)
Bind the key sequence represented by the string KEYSEQ to the
arbitrary pointer DATA. TYPE says what kind of data is pointed to
by DATA; this can be a function (`ISFUNC'), a macro (`ISMACR'), or
a keymap (`ISKMAP'). This makes new keymaps as necessary. The
initial keymap in which to do bindings is MAP.
-- Function: int rl_parse_and_bind (char *line)
Parse LINE as if it had been read from the `inputrc' file and
perform any key bindings and variable assignments found (*note
Readline Init File::).
-- Function: int rl_read_init_file (const char *filename)
Read keybindings and variable assignments from FILENAME (*note
Readline Init File::).
File: readline.info, Node: Associating Function Names and Bindings, Next: Allowing Undoing, Prev: Binding Keys, Up: Readline Convenience Functions
2.4.4 Associating Function Names and Bindings
---------------------------------------------
These functions allow you to find out what keys invoke named functions
and the functions invoked by a particular key sequence. You may also
associate a new function name with an arbitrary function.
-- Function: rl_command_func_t * rl_named_function (const char *name)
Return the function with name NAME.
-- Function: rl_command_func_t * rl_function_of_keyseq (const char
*keyseq, Keymap map, int *type)
Return the function invoked by KEYSEQ in keymap MAP. If MAP is
`NULL', the current keymap is used. If TYPE is not `NULL', the
type of the object is returned in the `int' variable it points to
(one of `ISFUNC', `ISKMAP', or `ISMACR').
-- Function: char ** rl_invoking_keyseqs (rl_command_func_t *function)
Return an array of strings representing the key sequences used to
invoke FUNCTION in the current keymap.
-- Function: char ** rl_invoking_keyseqs_in_map (rl_command_func_t
*function, Keymap map)
Return an array of strings representing the key sequences used to
invoke FUNCTION in the keymap MAP.
-- Function: void rl_function_dumper (int readable)
Print the readline function names and the key sequences currently
bound to them to `rl_outstream'. If READABLE is non-zero, the
list is formatted in such a way that it can be made part of an
`inputrc' file and re-read.
-- Function: void rl_list_funmap_names (void)
Print the names of all bindable Readline functions to
`rl_outstream'.
-- Function: const char ** rl_funmap_names (void)
Return a NULL terminated array of known function names. The array
is sorted. The array itself is allocated, but not the strings
inside. You should free the array, but not the pointers, using
`free' or `rl_free' when you are done.
-- Function: int rl_add_funmap_entry (const char *name,
rl_command_func_t *function)
Add NAME to the list of bindable Readline command names, and make
FUNCTION the function to be called when NAME is invoked.
File: readline.info, Node: Allowing Undoing, Next: Redisplay, Prev: Associating Function Names and Bindings, Up: Readline Convenience Functions
2.4.5 Allowing Undoing
----------------------
Supporting the undo command is a painless thing, and makes your
functions much more useful. It is certainly easy to try something if
you know you can undo it.
If your function simply inserts text once, or deletes text once, and
uses `rl_insert_text()' or `rl_delete_text()' to do it, then undoing is
already done for you automatically.
If you do multiple insertions or multiple deletions, or any
combination of these operations, you should group them together into
one operation. This is done with `rl_begin_undo_group()' and
`rl_end_undo_group()'.
The types of events that can be undone are:
enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END };
Notice that `UNDO_DELETE' means to insert some text, and
`UNDO_INSERT' means to delete some text. That is, the undo code tells
what to undo, not how to undo it. `UNDO_BEGIN' and `UNDO_END' are tags
added by `rl_begin_undo_group()' and `rl_end_undo_group()'.
-- Function: int rl_begin_undo_group (void)
Begins saving undo information in a group construct. The undo
information usually comes from calls to `rl_insert_text()' and
`rl_delete_text()', but could be the result of calls to
`rl_add_undo()'.
-- Function: int rl_end_undo_group (void)
Closes the current undo group started with `rl_begin_undo_group
()'. There should be one call to `rl_end_undo_group()' for each
call to `rl_begin_undo_group()'.
-- Function: void rl_add_undo (enum undo_code what, int start, int
end, char *text)
Remember how to undo an event (according to WHAT). The affected
text runs from START to END, and encompasses TEXT.
-- Function: void rl_free_undo_list (void)
Free the existing undo list.
-- Function: int rl_do_undo (void)
Undo the first thing on the undo list. Returns `0' if there was
nothing to undo, non-zero if something was undone.
Finally, if you neither insert nor delete text, but directly modify
the existing text (e.g., change its case), call `rl_modifying()' once,
just before you modify the text. You must supply the indices of the
text range that you are going to modify.
-- Function: int rl_modifying (int start, int end)
Tell Readline to save the text between START and END as a single
undo unit. It is assumed that you will subsequently modify that
text.
File: readline.info, Node: Redisplay, Next: Modifying Text, Prev: Allowing Undoing, Up: Readline Convenience Functions
2.4.6 Redisplay
---------------
-- Function: void rl_redisplay (void)
Change what's displayed on the screen to reflect the current
contents of `rl_line_buffer'.
-- Function: int rl_forced_update_display (void)
Force the line to be updated and redisplayed, whether or not
Readline thinks the screen display is correct.
-- Function: int rl_on_new_line (void)
Tell the update functions that we have moved onto a new (empty)
line, usually after outputting a newline.
-- Function: int rl_on_new_line_with_prompt (void)
Tell the update functions that we have moved onto a new line, with
RL_PROMPT already displayed. This could be used by applications
that want to output the prompt string themselves, but still need
Readline to know the prompt string length for redisplay. It
should be used after setting RL_ALREADY_PROMPTED.
-- Function: int rl_reset_line_state (void)
Reset the display state to a clean state and redisplay the current
line starting on a new line.
-- Function: int rl_crlf (void)
Move the cursor to the start of the next screen line.
-- Function: int rl_show_char (int c)
Display character C on `rl_outstream'. If Readline has not been
set to display meta characters directly, this will convert meta
characters to a meta-prefixed key sequence. This is intended for
use by applications which wish to do their own redisplay.
-- Function: int rl_message (const char *, ...)
The arguments are a format string as would be supplied to `printf',
possibly containing conversion specifications such as `%d', and
any additional arguments necessary to satisfy the conversion
specifications. The resulting string is displayed in the "echo
area". The echo area is also used to display numeric arguments
and search strings. You should call `rl_save_prompt' to save the
prompt information before calling this function.
-- Function: int rl_clear_message (void)
Clear the message in the echo area. If the prompt was saved with
a call to `rl_save_prompt' before the last call to `rl_message',
call `rl_restore_prompt' before calling this function.
-- Function: void rl_save_prompt (void)
Save the local Readline prompt display state in preparation for
displaying a new message in the message area with `rl_message()'.
-- Function: void rl_restore_prompt (void)
Restore the local Readline prompt display state saved by the most
recent call to `rl_save_prompt'. if `rl_save_prompt' was called
to save the prompt before a call to `rl_message', this function
should be called before the corresponding call to
`rl_clear_message'.
-- Function: int rl_expand_prompt (char *prompt)
Expand any special character sequences in PROMPT and set up the
local Readline prompt redisplay variables. This function is
called by `readline()'. It may also be called to expand the
primary prompt if the `rl_on_new_line_with_prompt()' function or
`rl_already_prompted' variable is used. It returns the number of
visible characters on the last line of the (possibly multi-line)
prompt. Applications may indicate that the prompt contains
characters that take up no physical screen space when displayed by
bracketing a sequence of such characters with the special markers
`RL_PROMPT_START_IGNORE' and `RL_PROMPT_END_IGNORE' (declared in
`readline.h'. This may be used to embed terminal-specific escape
sequences in prompts.
-- Function: int rl_set_prompt (const char *prompt)
Make Readline use PROMPT for subsequent redisplay. This calls
`rl_expand_prompt()' to expand the prompt and sets `rl_prompt' to
the result.
File: readline.info, Node: Modifying Text, Next: Character Input, Prev: Redisplay, Up: Readline Convenience Functions
2.4.7 Modifying Text
--------------------
-- Function: int rl_insert_text (const char *text)
Insert TEXT into the line at the current cursor position. Returns
the number of characters inserted.
-- Function: int rl_delete_text (int start, int end)
Delete the text between START and END in the current line.
Returns the number of characters deleted.
-- Function: char * rl_copy_text (int start, int end)
Return a copy of the text between START and END in the current
line.
-- Function: int rl_kill_text (int start, int end)
Copy the text between START and END in the current line to the
kill ring, appending or prepending to the last kill if the last
command was a kill command. The text is deleted. If START is
less than END, the text is appended, otherwise prepended. If the
last command was not a kill, a new kill ring slot is used.
-- Function: int rl_push_macro_input (char *macro)
Cause MACRO to be inserted into the line, as if it had been invoked
by a key bound to a macro. Not especially useful; use
`rl_insert_text()' instead.
File: readline.info, Node: Character Input, Next: Terminal Management, Prev: Modifying Text, Up: Readline Convenience Functions
2.4.8 Character Input
---------------------
-- Function: int rl_read_key (void)
Return the next character available from Readline's current input
stream. This handles input inserted into the input stream via
RL_PENDING_INPUT (*note Readline Variables::) and
`rl_stuff_char()', macros, and characters read from the keyboard.
While waiting for input, this function will call any function
assigned to the `rl_event_hook' variable.
-- Function: int rl_getc (FILE *stream)
Return the next character available from STREAM, which is assumed
to be the keyboard.
-- Function: int rl_stuff_char (int c)
Insert C into the Readline input stream. It will be "read" before
Readline attempts to read characters from the terminal with
`rl_read_key()'. Up to 512 characters may be pushed back.
`rl_stuff_char' returns 1 if the character was successfully
inserted; 0 otherwise.
-- Function: int rl_execute_next (int c)
Make C be the next command to be executed when `rl_read_key()' is
called. This sets RL_PENDING_INPUT.
-- Function: int rl_clear_pending_input (void)
Unset RL_PENDING_INPUT, effectively negating the effect of any
previous call to `rl_execute_next()'. This works only if the
pending input has not already been read with `rl_read_key()'.
-- Function: int rl_set_keyboard_input_timeout (int u)
While waiting for keyboard input in `rl_read_key()', Readline will
wait for U microseconds for input before calling any function
assigned to `rl_event_hook'. U must be greater than or equal to
zero (a zero-length timeout is equivalent to a poll). The default
waiting period is one-tenth of a second. Returns the old timeout
value.
File: readline.info, Node: Terminal Management, Next: Utility Functions, Prev: Character Input, Up: Readline Convenience Functions
2.4.9 Terminal Management
-------------------------
-- Function: void rl_prep_terminal (int meta_flag)
Modify the terminal settings for Readline's use, so `readline()'
can read a single character at a time from the keyboard. The
META_FLAG argument should be non-zero if Readline should read
eight-bit input.
-- Function: void rl_deprep_terminal (void)
Undo the effects of `rl_prep_terminal()', leaving the terminal in
the state in which it was before the most recent call to
`rl_prep_terminal()'.
-- Function: void rl_tty_set_default_bindings (Keymap kmap)
Read the operating system's terminal editing characters (as would
be displayed by `stty') to their Readline equivalents. The
bindings are performed in KMAP.
-- Function: void rl_tty_unset_default_bindings (Keymap kmap)
Reset the bindings manipulated by `rl_tty_set_default_bindings' so
that the terminal editing characters are bound to `rl_insert'.
The bindings are performed in KMAP.
-- Function: int rl_reset_terminal (const char *terminal_name)
Reinitialize Readline's idea of the terminal settings using
TERMINAL_NAME as the terminal type (e.g., `vt100'). If
TERMINAL_NAME is `NULL', the value of the `TERM' environment
variable is used.
File: readline.info, Node: Utility Functions, Next: Miscellaneous Functions, Prev: Terminal Management, Up: Readline Convenience Functions
2.4.10 Utility Functions
------------------------
-- Function: int rl_save_state (struct readline_state *sp)
Save a snapshot of Readline's internal state to SP. The contents
of the READLINE_STATE structure are documented in `readline.h'.
The caller is responsible for allocating the structure.
-- Function: int rl_restore_state (struct readline_state *sp)
Restore Readline's internal state to that stored in SP, which must
have been saved by a call to `rl_save_state'. The contents of the
READLINE_STATE structure are documented in `readline.h'. The
caller is responsible for freeing the structure.
-- Function: void rl_free (void *mem)
Deallocate the memory pointed to by MEM. MEM must have been
allocated by `malloc'.
-- Function: void rl_replace_line (const char *text, int clear_undo)
Replace the contents of `rl_line_buffer' with TEXT. The point and
mark are preserved, if possible. If CLEAR_UNDO is non-zero, the
undo list associated with the current line is cleared.
-- Function: void rl_extend_line_buffer (int len)
Ensure that `rl_line_buffer' has enough space to hold LEN
characters, possibly reallocating it if necessary.
-- Function: int rl_initialize (void)
Initialize or re-initialize Readline's internal state. It's not
strictly necessary to call this; `readline()' calls it before
reading any input.
-- Function: int rl_ding (void)
Ring the terminal bell, obeying the setting of `bell-style'.
-- Function: int rl_alphabetic (int c)
Return 1 if C is an alphabetic character.
-- Function: void rl_display_match_list (char **matches, int len, int
max)
A convenience function for displaying a list of strings in
columnar format on Readline's output stream. `matches' is the list
of strings, in argv format, such as a list of completion matches.
`len' is the number of strings in `matches', and `max' is the
length of the longest string in `matches'. This function uses the
setting of `print-completions-horizontally' to select how the
matches are displayed (*note Readline Init File Syntax::). When
displaying completions, this function sets the number of columns
used for display to the value of `completion-display-width', the
value of the environment variable `COLUMNS', or the screen width,
in that order.
The following are implemented as macros, defined in `chardefs.h'.
Applications should refrain from using them.
-- Function: int _rl_uppercase_p (int c)
Return 1 if C is an uppercase alphabetic character.
-- Function: int _rl_lowercase_p (int c)
Return 1 if C is a lowercase alphabetic character.
-- Function: int _rl_digit_p (int c)
Return 1 if C is a numeric character.
-- Function: int _rl_to_upper (int c)
If C is a lowercase alphabetic character, return the corresponding
uppercase character.
-- Function: int _rl_to_lower (int c)
If C is an uppercase alphabetic character, return the corresponding
lowercase character.
-- Function: int _rl_digit_value (int c)
If C is a number, return the value it represents.
File: readline.info, Node: Miscellaneous Functions, Next: Alternate Interface, Prev: Utility Functions, Up: Readline Convenience Functions
2.4.11 Miscellaneous Functions
------------------------------
-- Function: int rl_macro_bind (const char *keyseq, const char *macro,
Keymap map)
Bind the key sequence KEYSEQ to invoke the macro MACRO. The
binding is performed in MAP. When KEYSEQ is invoked, the MACRO
will be inserted into the line. This function is deprecated; use
`rl_generic_bind()' instead.
-- Function: void rl_macro_dumper (int readable)
Print the key sequences bound to macros and their values, using
the current keymap, to `rl_outstream'. If READABLE is non-zero,
the list is formatted in such a way that it can be made part of an
`inputrc' file and re-read.
-- Function: int rl_variable_bind (const char *variable, const char
*value)
Make the Readline variable VARIABLE have VALUE. This behaves as
if the readline command `set VARIABLE VALUE' had been executed in
an `inputrc' file (*note Readline Init File Syntax::).
-- Function: char * rl_variable_value (const char *variable)
Return a string representing the value of the Readline variable
VARIABLE. For boolean variables, this string is either `on' or
`off'.
-- Function: void rl_variable_dumper (int readable)
Print the readline variable names and their current values to
`rl_outstream'. If READABLE is non-zero, the list is formatted in
such a way that it can be made part of an `inputrc' file and
re-read.
-- Function: int rl_set_paren_blink_timeout (int u)
Set the time interval (in microseconds) that Readline waits when
showing a balancing character when `blink-matching-paren' has been
enabled.
-- Function: char * rl_get_termcap (const char *cap)
Retrieve the string value of the termcap capability CAP. Readline
fetches the termcap entry for the current terminal name and uses
those capabilities to move around the screen line and perform other
terminal-specific operations, like erasing a line. Readline does
not use all of a terminal's capabilities, and this function will
return values for only those capabilities Readline uses.
-- Function: void rl_clear_history (void)
Clear the history list by deleting all of the entries, in the same
manner as the History library's `clear_history()' function. This
differs from `clear_history' because it frees private data
Readline saves in the history list.
File: readline.info, Node: Alternate Interface, Next: A Readline Example, Prev: Miscellaneous Functions, Up: Readline Convenience Functions
2.4.12 Alternate Interface
--------------------------
An alternate interface is available to plain `readline()'. Some
applications need to interleave keyboard I/O with file, device, or
window system I/O, typically by using a main loop to `select()' on
various file descriptors. To accommodate this need, readline can also
be invoked as a `callback' function from an event loop. There are
functions available to make this easy.
-- Function: void rl_callback_handler_install (const char *prompt,
rl_vcpfunc_t *lhandler)
Set up the terminal for readline I/O and display the initial
expanded value of PROMPT. Save the value of LHANDLER to use as a
handler function to call when a complete line of input has been
entered. The handler function receives the text of the line as an
argument.
-- Function: void rl_callback_read_char (void)
Whenever an application determines that keyboard input is
available, it should call `rl_callback_read_char()', which will
read the next character from the current input source. If that
character completes the line, `rl_callback_read_char' will invoke
the LHANDLER function installed by `rl_callback_handler_install'
to process the line. Before calling the LHANDLER function, the
terminal settings are reset to the values they had before calling
`rl_callback_handler_install'. If the LHANDLER function returns,
and the line handler remains installed, the terminal settings are
modified for Readline's use again. `EOF' is indicated by calling
LHANDLER with a `NULL' line.
-- Function: void rl_callback_handler_remove (void)
Restore the terminal to its initial state and remove the line
handler. This may be called from within a callback as well as
independently. If the LHANDLER installed by
`rl_callback_handler_install' does not exit the program, either
this function or the function referred to by the value of
`rl_deprep_term_function' should be called before the program
exits to reset the terminal settings.
File: readline.info, Node: A Readline Example, Next: Alternate Interface Example, Prev: Alternate Interface, Up: Readline Convenience Functions
2.4.13 A Readline Example
-------------------------
Here is a function which changes lowercase characters to their uppercase
equivalents, and uppercase characters to lowercase. If this function
was bound to `M-c', then typing `M-c' would change the case of the
character under point. Typing `M-1 0 M-c' would change the case of the
following 10 characters, leaving the cursor on the last character
changed.
/* Invert the case of the COUNT following characters. */
int
invert_case_line (count, key)
int count, key;
{
register int start, end, i;
start = rl_point;
if (rl_point >= rl_end)
return (0);
if (count < 0)
{
direction = -1;
count = -count;
}
else
direction = 1;
/* Find the end of the range to modify. */
end = start + (count * direction);
/* Force it to be within range. */
if (end > rl_end)
end = rl_end;
else if (end < 0)
end = 0;
if (start == end)
return (0);
if (start > end)
{
int temp = start;
start = end;
end = temp;
}
/* Tell readline that we are modifying the line,
so it will save the undo information. */
rl_modifying (start, end);
for (i = start; i != end; i++)
{
if (_rl_uppercase_p (rl_line_buffer[i]))
rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
else if (_rl_lowercase_p (rl_line_buffer[i]))
rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
}
/* Move point to on top of the last character changed. */
rl_point = (direction == 1) ? end - 1 : start;
return (0);
}
File: readline.info, Node: Alternate Interface Example, Prev: A Readline Example, Up: Readline Convenience Functions
2.4.14 Alternate Interface Example
----------------------------------
Here is a complete program that illustrates Readline's alternate
interface. It reads lines from the terminal and displays them,
providing the standard history and TAB completion functions. It
understands the EOF character or "exit" to exit the program.
/* Standard include files. stdio.h is required. */
#include
#include
/* Used for select(2) */
#include
#include
#include
/* Standard readline include files. */
#include
#include
static void cb_linehandler (char *);
int running;
const char *prompt = "rltest$ ";
/* Callback function called for each line when accept-line executed, EOF
seen, or EOF character read. This sets a flag and returns; it could
also call exit(3). */
static void
cb_linehandler (char *line)
{
/* Can use ^D (stty eof) or `exit' to exit. */
if (line == NULL || strcmp (line, "exit") == 0)
{
if (line == 0)
printf ("\n");
printf ("exit\n");
/* This function needs to be called to reset the terminal settings,
and calling it from the line handler keeps one extra prompt from
being displayed. */
rl_callback_handler_remove ();
running = 0;
}
else
{
if (*line)
add_history (line);
printf ("input line: %s\n", line);
free (line);
}
}
int
main (int c, char **v)
{
fd_set fds;
int r;
/* Install the line handler. */
rl_callback_handler_install (prompt, cb_linehandler);
/* Enter a simple event loop. This waits until something is available
to read on readline's input stream (defaults to standard input) and
calls the builtin character read callback to read it. It does not
have to modify the user's terminal settings. */
running = 1;
while (running)
{
FD_ZERO (&fds);
FD_SET (fileno (rl_instream), &fds);
r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
if (r < 0)
{
perror ("rltest: select");
rl_callback_handler_remove ();
break;
}
if (FD_ISSET (fileno (rl_instream), &fds))
rl_callback_read_char ();
}
printf ("rltest: Event loop has exited\n");
return 0;
}
File: readline.info, Node: Readline Signal Handling, Next: Custom Completers, Prev: Readline Convenience Functions, Up: Programming with GNU Readline
2.5 Readline Signal Handling
============================
Signals are asynchronous events sent to a process by the Unix kernel,
sometimes on behalf of another process. They are intended to indicate
exceptional events, like a user pressing the interrupt key on his
terminal, or a network connection being broken. There is a class of
signals that can be sent to the process currently reading input from
the keyboard. Since Readline changes the terminal attributes when it
is called, it needs to perform special processing when such a signal is
received in order to restore the terminal to a sane state, or provide
application writers with functions to do so manually.
Readline contains an internal signal handler that is installed for a
number of signals (`SIGINT', `SIGQUIT', `SIGTERM', `SIGHUP', `SIGALRM',
`SIGTSTP', `SIGTTIN', and `SIGTTOU'). When one of these signals is
received, the signal handler will reset the terminal attributes to
those that were in effect before `readline()' was called, reset the
signal handling to what it was before `readline()' was called, and
resend the signal to the calling application. If and when the calling
application's signal handler returns, Readline will reinitialize the
terminal and continue to accept input. When a `SIGINT' is received,
the Readline signal handler performs some additional work, which will
cause any partially-entered line to be aborted (see the description of
`rl_free_line_state()' below).
There is an additional Readline signal handler, for `SIGWINCH', which
the kernel sends to a process whenever the terminal's size changes (for
example, if a user resizes an `xterm'). The Readline `SIGWINCH'
handler updates Readline's internal screen size information, and then
calls any `SIGWINCH' signal handler the calling application has
installed. Readline calls the application's `SIGWINCH' signal handler
without resetting the terminal to its original state. If the
application's signal handler does more than update its idea of the
terminal size and return (for example, a `longjmp' back to a main
processing loop), it _must_ call `rl_cleanup_after_signal()' (described
below), to restore the terminal state.
Readline provides two variables that allow application writers to
control whether or not it will catch certain signals and act on them
when they are received. It is important that applications change the
values of these variables only when calling `readline()', not in a
signal handler, so Readline's internal signal state is not corrupted.
-- Variable: int rl_catch_signals
If this variable is non-zero, Readline will install signal
handlers for `SIGINT', `SIGQUIT', `SIGTERM', `SIGHUP', `SIGALRM',
`SIGTSTP', `SIGTTIN', and `SIGTTOU'.
The default value of `rl_catch_signals' is 1.
-- Variable: int rl_catch_sigwinch
If this variable is set to a non-zero value, Readline will install
a signal handler for `SIGWINCH'.
The default value of `rl_catch_sigwinch' is 1.
-- Variable: int rl_change_environment
If this variable is set to a non-zero value, and Readline is
handling `SIGWINCH', Readline will modify the LINES and COLUMNS
environment variables upon receipt of a `SIGWINCH'
The default value of `rl_change_environment' is 1.
If an application does not wish to have Readline catch any signals,
or to handle signals other than those Readline catches (`SIGHUP', for
example), Readline provides convenience functions to do the necessary
terminal and internal state cleanup upon receipt of a signal.
-- Function: void rl_cleanup_after_signal (void)
This function will reset the state of the terminal to what it was
before `readline()' was called, and remove the Readline signal
handlers for all signals, depending on the values of
`rl_catch_signals' and `rl_catch_sigwinch'.
-- Function: void rl_free_line_state (void)
This will free any partial state associated with the current input
line (undo information, any partial history entry, any
partially-entered keyboard macro, and any partially-entered
numeric argument). This should be called before
`rl_cleanup_after_signal()'. The Readline signal handler for
`SIGINT' calls this to abort the current input line.
-- Function: void rl_reset_after_signal (void)
This will reinitialize the terminal and reinstall any Readline
signal handlers, depending on the values of `rl_catch_signals' and
`rl_catch_sigwinch'.
If an application does not wish Readline to catch `SIGWINCH', it may
call `rl_resize_terminal()' or `rl_set_screen_size()' to force Readline
to update its idea of the terminal size when a `SIGWINCH' is received.
-- Function: void rl_echo_signal_char (int sig)
If an application wishes to install its own signal handlers, but
still have readline display characters that generate signals,
calling this function with SIG set to `SIGINT', `SIGQUIT', or
`SIGTSTP' will display the character generating that signal.
-- Function: void rl_resize_terminal (void)
Update Readline's internal screen size by reading values from the
kernel.
-- Function: void rl_set_screen_size (int rows, int cols)
Set Readline's idea of the terminal size to ROWS rows and COLS
columns. If either ROWS or COLUMNS is less than or equal to 0,
Readline's idea of that terminal dimension is unchanged.
If an application does not want to install a `SIGWINCH' handler, but
is still interested in the screen dimensions, Readline's idea of the
screen size may be queried.
-- Function: void rl_get_screen_size (int *rows, int *cols)
Return Readline's idea of the terminal's size in the variables
pointed to by the arguments.
-- Function: void rl_reset_screen_size (void)
Cause Readline to reobtain the screen size and recalculate its
dimensions.
The following functions install and remove Readline's signal
handlers.
-- Function: int rl_set_signals (void)
Install Readline's signal handler for `SIGINT', `SIGQUIT',
`SIGTERM', `SIGHUP', `SIGALRM', `SIGTSTP', `SIGTTIN', `SIGTTOU',
and `SIGWINCH', depending on the values of `rl_catch_signals' and
`rl_catch_sigwinch'.
-- Function: int rl_clear_signals (void)
Remove all of the Readline signal handlers installed by
`rl_set_signals()'.
File: readline.info, Node: Custom Completers, Prev: Readline Signal Handling, Up: Programming with GNU Readline
2.6 Custom Completers
=====================
Typically, a program that reads commands from the user has a way of
disambiguating commands and data. If your program is one of these, then
it can provide completion for commands, data, or both. The following
sections describe how your program and Readline cooperate to provide
this service.
* Menu:
* How Completing Works:: The logic used to do completion.
* Completion Functions:: Functions provided by Readline.
* Completion Variables:: Variables which control completion.
* A Short Completion Example:: An example of writing completer subroutines.
File: readline.info, Node: How Completing Works, Next: Completion Functions, Up: Custom Completers
2.6.1 How Completing Works
--------------------------
In order to complete some text, the full list of possible completions
must be available. That is, it is not possible to accurately expand a
partial word without knowing all of the possible words which make sense
in that context. The Readline library provides the user interface to
completion, and two of the most common completion functions: filename
and username. For completing other types of text, you must write your
own completion function. This section describes exactly what such
functions must do, and provides an example.
There are three major functions used to perform completion:
1. The user-interface function `rl_complete()'. This function is
called with the same arguments as other bindable Readline
functions: COUNT and INVOKING_KEY. It isolates the word to be
completed and calls `rl_completion_matches()' to generate a list
of possible completions. It then either lists the possible
completions, inserts the possible completions, or actually
performs the completion, depending on which behavior is desired.
2. The internal function `rl_completion_matches()' uses an
application-supplied "generator" function to generate the list of
possible matches, and then returns the array of these matches.
The caller should place the address of its generator function in
`rl_completion_entry_function'.
3. The generator function is called repeatedly from
`rl_completion_matches()', returning a string each time. The
arguments to the generator function are TEXT and STATE. TEXT is
the partial word to be completed. STATE is zero the first time
the function is called, allowing the generator to perform any
necessary initialization, and a positive non-zero integer for each
subsequent call. The generator function returns `(char *)NULL' to
inform `rl_completion_matches()' that there are no more
possibilities left. Usually the generator function computes the
list of possible completions when STATE is zero, and returns them
one at a time on subsequent calls. Each string the generator
function returns as a match must be allocated with `malloc()';
Readline frees the strings when it has finished with them. Such a
generator function is referred to as an "application-specific
completion function".
-- Function: int rl_complete (int ignore, int invoking_key)
Complete the word at or before point. You have supplied the
function that does the initial simple matching selection algorithm
(see `rl_completion_matches()'). The default is to do filename
completion.
-- Variable: rl_compentry_func_t * rl_completion_entry_function
This is a pointer to the generator function for
`rl_completion_matches()'. If the value of
`rl_completion_entry_function' is `NULL' then the default filename
generator function, `rl_filename_completion_function()', is used.
An "application-specific completion function" is a function whose
address is assigned to `rl_completion_entry_function' and whose
return values are used to generate possible completions.
File: readline.info, Node: Completion Functions, Next: Completion Variables, Prev: How Completing Works, Up: Custom Completers
2.6.2 Completion Functions
--------------------------
Here is the complete list of callable completion functions present in
Readline.
-- Function: int rl_complete_internal (int what_to_do)
Complete the word at or before point. WHAT_TO_DO says what to do
with the completion. A value of `?' means list the possible
completions. `TAB' means do standard completion. `*' means
insert all of the possible completions. `!' means to display all
of the possible completions, if there is more than one, as well as
performing partial completion. `@' is similar to `!', but
possible completions are not listed if the possible completions
share a common prefix.
-- Function: int rl_complete (int ignore, int invoking_key)
Complete the word at or before point. You have supplied the
function that does the initial simple matching selection algorithm
(see `rl_completion_matches()' and `rl_completion_entry_function').
The default is to do filename completion. This calls
`rl_complete_internal()' with an argument depending on
INVOKING_KEY.
-- Function: int rl_possible_completions (int count, int invoking_key)
List the possible completions. See description of `rl_complete
()'. This calls `rl_complete_internal()' with an argument of `?'.
-- Function: int rl_insert_completions (int count, int invoking_key)
Insert the list of possible completions into the line, deleting the
partially-completed word. See description of `rl_complete()'.
This calls `rl_complete_internal()' with an argument of `*'.
-- Function: int rl_completion_mode (rl_command_func_t *cfunc)
Returns the appropriate value to pass to `rl_complete_internal()'
depending on whether CFUNC was called twice in succession and the
values of the `show-all-if-ambiguous' and `show-all-if-unmodified'
variables. Application-specific completion functions may use this
function to present the same interface as `rl_complete()'.
-- Function: char ** rl_completion_matches (const char *text,
rl_compentry_func_t *entry_func)
Returns an array of strings which is a list of completions for
TEXT. If there are no completions, returns `NULL'. The first
entry in the returned array is the substitution for TEXT. The
remaining entries are the possible completions. The array is
terminated with a `NULL' pointer.
ENTRY_FUNC is a function of two args, and returns a `char *'. The
first argument is TEXT. The second is a state argument; it is
zero on the first call, and non-zero on subsequent calls.
ENTRY_FUNC returns a `NULL' pointer to the caller when there are
no more matches.
-- Function: char * rl_filename_completion_function (const char *text,
int state)
A generator function for filename completion in the general case.
TEXT is a partial filename. The Bash source is a useful reference
for writing application-specific completion functions (the Bash
completion functions call this and other Readline functions).
-- Function: char * rl_username_completion_function (const char *text,
int state)
A completion generator for usernames. TEXT contains a partial
username preceded by a random character (usually `~'). As with all
completion generators, STATE is zero on the first call and non-zero
for subsequent calls.
File: readline.info, Node: Completion Variables, Next: A Short Completion Example, Prev: Completion Functions, Up: Custom Completers
2.6.3 Completion Variables
--------------------------
-- Variable: rl_compentry_func_t * rl_completion_entry_function
A pointer to the generator function for `rl_completion_matches()'.
`NULL' means to use `rl_filename_completion_function()', the
default filename completer.
-- Variable: rl_completion_func_t * rl_attempted_completion_function
A pointer to an alternative function to create matches. The
function is called with TEXT, START, and END. START and END are
indices in `rl_line_buffer' defining the boundaries of TEXT, which
is a character string. If this function exists and returns
`NULL', or if this variable is set to `NULL', then `rl_complete()'
will call the value of `rl_completion_entry_function' to generate
matches, otherwise the array of strings returned will be used. If
this function sets the `rl_attempted_completion_over' variable to
a non-zero value, Readline will not perform its default completion
even if this function returns no matches.
-- Variable: rl_quote_func_t * rl_filename_quoting_function
A pointer to a function that will quote a filename in an
application-specific fashion. This is called if filename
completion is being attempted and one of the characters in
`rl_filename_quote_characters' appears in a completed filename.
The function is called with TEXT, MATCH_TYPE, and QUOTE_POINTER.
The TEXT is the filename to be quoted. The MATCH_TYPE is either
`SINGLE_MATCH', if there is only one completion match, or
`MULT_MATCH'. Some functions use this to decide whether or not to
insert a closing quote character. The QUOTE_POINTER is a pointer
to any opening quote character the user typed. Some functions
choose to reset this character.
-- Variable: rl_dequote_func_t * rl_filename_dequoting_function
A pointer to a function that will remove application-specific
quoting characters from a filename before completion is attempted,
so those characters do not interfere with matching the text
against names in the filesystem. It is called with TEXT, the text
of the word to be dequoted, and QUOTE_CHAR, which is the quoting
character that delimits the filename (usually `'' or `"'). If
QUOTE_CHAR is zero, the filename was not in an embedded string.
-- Variable: rl_linebuf_func_t * rl_char_is_quoted_p
A pointer to a function to call that determines whether or not a
specific character in the line buffer is quoted, according to
whatever quoting mechanism the program calling Readline uses. The
function is called with two arguments: TEXT, the text of the line,
and INDEX, the index of the character in the line. It is used to
decide whether a character found in
`rl_completer_word_break_characters' should be used to break words
for the completer.
-- Variable: rl_compignore_func_t * rl_ignore_some_completions_function
This function, if defined, is called by the completer when real
filename completion is done, after all the matching names have
been generated. It is passed a `NULL' terminated array of matches.
The first element (`matches[0]') is the maximal substring common
to all matches. This function can re-arrange the list of matches
as required, but each element deleted from the array must be freed.
-- Variable: rl_icppfunc_t * rl_directory_completion_hook
This function, if defined, is allowed to modify the directory
portion of filenames Readline completes. It could be used to
expand symbolic links or shell variables in pathnames. It is
called with the address of a string (the current directory name)
as an argument, and may modify that string. If the string is
replaced with a new string, the old value should be freed. Any
modified directory name should have a trailing slash. The
modified value will be used as part of the completion, replacing
the directory portion of the pathname the user typed. At the
least, even if no other expansion is performed, this function
should remove any quote characters from the directory name,
because its result will be passed directly to `opendir()'.
The directory completion hook returns an integer that should be
non-zero if the function modifies its directory argument. The
function should not modify the directory argument if it returns 0.
-- Variable: rl_icppfunc_t * rl_directory_rewrite_hook;
If non-zero, this is the address of a function to call when
completing a directory name. This function takes the address of
the directory name to be modified as an argument. Unlike
`rl_directory_completion_hook', it only modifies the directory
name used in `opendir', not what is displayed when the possible
completions are printed or inserted. It is called before
rl_directory_completion_hook. At the least, even if no other
expansion is performed, this function should remove any quote
characters from the directory name, because its result will be
passed directly to `opendir()'.
The directory rewrite hook returns an integer that should be
non-zero if the function modfies its directory argument. The
function should not modify the directory argument if it returns 0.
-- Variable: rl_icppfunc_t * rl_filename_stat_hook
If non-zero, this is the address of a function for the completer to
call before deciding which character to append to a completed name.
This function modifies its filename name argument, and the
modified value is passed to `stat()' to determine the file's type
and characteristics. This function does not need to remove quote
characters from the filename.
The stat hook returns an integer that should be non-zero if the
function modfies its directory argument. The function should not
modify the directory argument if it returns 0.
-- Variable: rl_dequote_func_t * rl_filename_rewrite_hook
If non-zero, this is the address of a function called when reading
directory entries from the filesystem for completion and comparing
them to the partial word to be completed. The function should
perform any necessary application or system-specific conversion on
the filename, such as converting between character sets or
converting from a filesystem format to a character input format.
The function takes two arguments: FNAME, the filename to be
converted, and FNLEN, its length in bytes. It must either return
its first argument (if no conversion takes place) or the converted
filename in newly-allocated memory. The converted form is used to
compare against the word to be completed, and, if it matches, is
added to the list of matches. Readline will free the allocated
string.
-- Variable: rl_compdisp_func_t * rl_completion_display_matches_hook
If non-zero, then this is the address of a function to call when
completing a word would normally display the list of possible
matches. This function is called in lieu of Readline displaying
the list. It takes three arguments: (`char **'MATCHES, `int'
NUM_MATCHES, `int' MAX_LENGTH) where MATCHES is the array of
matching strings, NUM_MATCHES is the number of strings in that
array, and MAX_LENGTH is the length of the longest string in that
array. Readline provides a convenience function,
`rl_display_match_list', that takes care of doing the display to
Readline's output stream. That function may be called from this
hook.
-- Variable: const char * rl_basic_word_break_characters
The basic list of characters that signal a break between words for
the completer routine. The default value of this variable is the
characters which break words for completion in Bash: `"
\t\n\"\\'`@$><=;|&{("'.
-- Variable: const char * rl_basic_quote_characters
A list of quote characters which can cause a word break.
-- Variable: const char * rl_completer_word_break_characters
The list of characters that signal a break between words for
`rl_complete_internal()'. The default list is the value of
`rl_basic_word_break_characters'.
-- Variable: rl_cpvfunc_t * rl_completion_word_break_hook
If non-zero, this is the address of a function to call when
Readline is deciding where to separate words for word completion.
It should return a character string like
`rl_completer_word_break_characters' to be used to perform the
current completion. The function may choose to set
`rl_completer_word_break_characters' itself. If the function
returns `NULL', `rl_completer_word_break_characters' is used.
-- Variable: const char * rl_completer_quote_characters
A list of characters which can be used to quote a substring of the
line. Completion occurs on the entire substring, and within the
substring `rl_completer_word_break_characters' are treated as any
other character, unless they also appear within this list.
-- Variable: const char * rl_filename_quote_characters
A list of characters that cause a filename to be quoted by the
completer when they appear in a completed filename. The default
is the null string.
-- Variable: const char * rl_special_prefixes
The list of characters that are word break characters, but should
be left in TEXT when it is passed to the completion function.
Programs can use this to help determine what kind of completing to
do. For instance, Bash sets this variable to "$@" so that it can
complete shell variables and hostnames.
-- Variable: int rl_completion_query_items
Up to this many items will be displayed in response to a
possible-completions call. After that, readline asks the user if
she is sure she wants to see them all. The default value is 100.
A negative value indicates that Readline should never ask the user.
-- Variable: int rl_completion_append_character
When a single completion alternative matches at the end of the
command line, this character is appended to the inserted
completion text. The default is a space character (` '). Setting
this to the null character (`\0') prevents anything being appended
automatically. This can be changed in application-specific
completion functions to provide the "most sensible word separator
character" according to an application-specific command line
syntax specification.
-- Variable: int rl_completion_suppress_append
If non-zero, RL_COMPLETION_APPEND_CHARACTER is not appended to
matches at the end of the command line, as described above. It is
set to 0 before any application-specific completion function is
called, and may only be changed within such a function.
-- Variable: int rl_completion_quote_character
When Readline is completing quoted text, as delimited by one of the
characters in RL_COMPLETER_QUOTE_CHARACTERS, it sets this variable
to the quoting character found. This is set before any
application-specific completion function is called.
-- Variable: int rl_completion_suppress_quote
If non-zero, Readline does not append a matching quote character
when performing completion on a quoted string. It is set to 0
before any application-specific completion function is called, and
may only be changed within such a function.
-- Variable: int rl_completion_found_quote
When Readline is completing quoted text, it sets this variable to
a non-zero value if the word being completed contains or is
delimited by any quoting characters, including backslashes. This
is set before any application-specific completion function is
called.
-- Variable: int rl_completion_mark_symlink_dirs
If non-zero, a slash will be appended to completed filenames that
are symbolic links to directory names, subject to the value of the
user-settable MARK-DIRECTORIES variable. This variable exists so
that application-specific completion functions can override the
user's global preference (set via the MARK-SYMLINKED-DIRECTORIES
Readline variable) if appropriate. This variable is set to the
user's preference before any application-specific completion
function is called, so unless that function modifies the value,
the user's preferences are honored.
-- Variable: int rl_ignore_completion_duplicates
If non-zero, then duplicates in the matches are removed. The
default is 1.
-- Variable: int rl_filename_completion_desired
Non-zero means that the results of the matches are to be treated as
filenames. This is _always_ zero when completion is attempted,
and can only be changed within an application-specific completion
function. If it is set to a non-zero value by such a function,
directory names have a slash appended and Readline attempts to
quote completed filenames if they contain any characters in
`rl_filename_quote_characters' and `rl_filename_quoting_desired'
is set to a non-zero value.
-- Variable: int rl_filename_quoting_desired
Non-zero means that the results of the matches are to be quoted
using double quotes (or an application-specific quoting mechanism)
if the completed filename contains any characters in
`rl_filename_quote_chars'. This is _always_ non-zero when
completion is attempted, and can only be changed within an
application-specific completion function. The quoting is effected
via a call to the function pointed to by
`rl_filename_quoting_function'.
-- Variable: int rl_attempted_completion_over
If an application-specific completion function assigned to
`rl_attempted_completion_function' sets this variable to a non-zero
value, Readline will not perform its default filename completion
even if the application's completion function returns no matches.
It should be set only by an application's completion function.
-- Variable: int rl_sort_completion_matches
If an application sets this variable to 0, Readline will not sort
the list of completions (which implies that it cannot remove any
duplicate completions). The default value is 1, which means that
Readline will sort the completions and, depending on the value of
`rl_ignore_completion_duplicates', will attempt to remove duplicate
matches.
-- Variable: int rl_completion_type
Set to a character describing the type of completion Readline is
currently attempting; see the description of
`rl_complete_internal()' (*note Completion Functions::) for the
list of characters. This is set to the appropriate value before
any application-specific completion function is called, allowing
such functions to present the same interface as `rl_complete()'.
-- Variable: int rl_completion_invoking_key
Set to the final character in the key sequence that invoked one of
the completion functions that call `rl_complete_internal()'. This
is set to the appropriate value before any application-specific
completion function is called.
-- Variable: int rl_inhibit_completion
If this variable is non-zero, completion is inhibited. The
completion character will be inserted as any other bound to
`self-insert'.
File: readline.info, Node: A Short Completion Example, Prev: Completion Variables, Up: Custom Completers
2.6.4 A Short Completion Example
--------------------------------
Here is a small application demonstrating the use of the GNU Readline
library. It is called `fileman', and the source code resides in
`examples/fileman.c'. This sample application provides completion of
command names, line editing features, and access to the history list.
/* fileman.c -- A tiny application which demonstrates how to use the
GNU Readline library. This application interactively allows users
to manipulate files and their modes. */
#ifdef HAVE_CONFIG_H
# include
#endif
#include
#ifdef HAVE_SYS_FILE_H
# include
#endif
#include
#ifdef HAVE_UNISTD_H
# include
#endif
#include
#include
#include
#if defined (HAVE_STRING_H)
# include
#else /* !HAVE_STRING_H */
# include
#endif /* !HAVE_STRING_H */
#ifdef HAVE_STDLIB_H
# include
#endif
#include
#include
#include
extern char *xmalloc PARAMS((size_t));
/* The names of functions that actually do the manipulation. */
int com_list PARAMS((char *));
int com_view PARAMS((char *));
int com_rename PARAMS((char *));
int com_stat PARAMS((char *));
int com_pwd PARAMS((char *));
int com_delete PARAMS((char *));
int com_help PARAMS((char *));
int com_cd PARAMS((char *));
int com_quit PARAMS((char *));
/* A structure which contains information on the commands this program
can understand. */
typedef struct {
char *name; /* User printable name of the function. */
rl_icpfunc_t *func; /* Function to call to do the job. */
char *doc; /* Documentation for this function. */
} COMMAND;
COMMAND commands[] = {
{ "cd", com_cd, "Change to directory DIR" },
{ "delete", com_delete, "Delete FILE" },
{ "help", com_help, "Display this text" },
{ "?", com_help, "Synonym for `help'" },
{ "list", com_list, "List files in DIR" },
{ "ls", com_list, "Synonym for `list'" },
{ "pwd", com_pwd, "Print the current working directory" },
{ "quit", com_quit, "Quit using Fileman" },
{ "rename", com_rename, "Rename FILE to NEWNAME" },
{ "stat", com_stat, "Print out statistics on FILE" },
{ "view", com_view, "View the contents of FILE" },
{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL }
};
/* Forward declarations. */
char *stripwhite ();
COMMAND *find_command ();
/* The name of this program, as taken from argv[0]. */
char *progname;
/* When non-zero, this global means the user is done using this program. */
int done;
char *
dupstr (s)
char *s;
{
char *r;
r = xmalloc (strlen (s) + 1);
strcpy (r, s);
return (r);
}
main (argc, argv)
int argc;
char **argv;
{
char *line, *s;
progname = argv[0];
initialize_readline (); /* Bind our completer. */
/* Loop reading and executing lines until the user quits. */
for ( ; done == 0; )
{
line = readline ("FileMan: ");
if (!line)
break;
/* Remove leading and trailing whitespace from the line.
Then, if there is anything left, add it to the history list
and execute it. */
s = stripwhite (line);
if (*s)
{
add_history (s);
execute_line (s);
}
free (line);
}
exit (0);
}
/* Execute a command line. */
int
execute_line (line)
char *line;
{
register int i;
COMMAND *command;
char *word;
/* Isolate the command word. */
i = 0;
while (line[i] && whitespace (line[i]))
i++;
word = line + i;
while (line[i] && !whitespace (line[i]))
i++;
if (line[i])
line[i++] = '\0';
command = find_command (word);
if (!command)
{
fprintf (stderr, "%s: No such command for FileMan.\n", word);
return (-1);
}
/* Get argument to command, if any. */
while (whitespace (line[i]))
i++;
word = line + i;
/* Call the function. */
return ((*(command->func)) (word));
}
/* Look up NAME as the name of a command, and return a pointer to that
command. Return a NULL pointer if NAME isn't a command name. */
COMMAND *
find_command (name)
char *name;
{
register int i;
for (i = 0; commands[i].name; i++)
if (strcmp (name, commands[i].name) == 0)
return (&commands[i]);
return ((COMMAND *)NULL);
}
/* Strip whitespace from the start and end of STRING. Return a pointer
into STRING. */
char *
stripwhite (string)
char *string;
{
register char *s, *t;
for (s = string; whitespace (*s); s++)
;
if (*s == 0)
return (s);
t = s + strlen (s) - 1;
while (t > s && whitespace (*t))
t--;
*++t = '\0';
return s;
}
/* **************************************************************** */
/* */
/* Interface to Readline Completion */
/* */
/* **************************************************************** */
char *command_generator PARAMS((const char *, int));
char **fileman_completion PARAMS((const char *, int, int));
/* Tell the GNU Readline library how to complete. We want to try to complete
on command names if this is the first word in the line, or on filenames
if not. */
initialize_readline ()
{
/* Allow conditional parsing of the ~/.inputrc file. */
rl_readline_name = "FileMan";
/* Tell the completer that we want a crack first. */
rl_attempted_completion_function = fileman_completion;
}
/* Attempt to complete on the contents of TEXT. START and END bound the
region of rl_line_buffer that contains the word to complete. TEXT is
the word to complete. We can use the entire contents of rl_line_buffer
in case we want to do some simple parsing. Return the array of matches,
or NULL if there aren't any. */
char **
fileman_completion (text, start, end)
const char *text;
int start, end;
{
char **matches;
matches = (char **)NULL;
/* If this word is at the start of the line, then it is a command
to complete. Otherwise it is the name of a file in the current
directory. */
if (start == 0)
matches = rl_completion_matches (text, command_generator);
return (matches);
}
/* Generator function for command completion. STATE lets us know whether
to start from scratch; without any state (i.e. STATE == 0), then we
start at the top of the list. */
char *
command_generator (text, state)
const char *text;
int state;
{
static int list_index, len;
char *name;
/* If this is a new word to complete, initialize now. This includes
saving the length of TEXT for efficiency, and initializing the index
variable to 0. */
if (!state)
{
list_index = 0;
len = strlen (text);
}
/* Return the next name which partially matches from the command list. */
while (name = commands[list_index].name)
{
list_index++;
if (strncmp (name, text, len) == 0)
return (dupstr(name));
}
/* If no names matched, then return NULL. */
return ((char *)NULL);
}
/* **************************************************************** */
/* */
/* FileMan Commands */
/* */
/* **************************************************************** */
/* String to pass to system (). This is for the LIST, VIEW and RENAME
commands. */
static char syscom[1024];
/* List the file(s) named in arg. */
com_list (arg)
char *arg;
{
if (!arg)
arg = "";
sprintf (syscom, "ls -FClg %s", arg);
return (system (syscom));
}
com_view (arg)
char *arg;
{
if (!valid_argument ("view", arg))
return 1;
#if defined (__MSDOS__)
/* more.com doesn't grok slashes in pathnames */
sprintf (syscom, "less %s", arg);
#else
sprintf (syscom, "more %s", arg);
#endif
return (system (syscom));
}
com_rename (arg)
char *arg;
{
too_dangerous ("rename");
return (1);
}
com_stat (arg)
char *arg;
{
struct stat finfo;
if (!valid_argument ("stat", arg))
return (1);
if (stat (arg, &finfo) == -1)
{
perror (arg);
return (1);
}
printf ("Statistics for `%s':\n", arg);
printf ("%s has %d link%s, and is %d byte%s in length.\n",
arg,
finfo.st_nlink,
(finfo.st_nlink == 1) ? "" : "s",
finfo.st_size,
(finfo.st_size == 1) ? "" : "s");
printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
printf (" Last access at: %s", ctime (&finfo.st_atime));
printf (" Last modified at: %s", ctime (&finfo.st_mtime));
return (0);
}
com_delete (arg)
char *arg;
{
too_dangerous ("delete");
return (1);
}
/* Print out help for ARG, or for all of the commands if ARG is
not present. */
com_help (arg)
char *arg;
{
register int i;
int printed = 0;
for (i = 0; commands[i].name; i++)
{
if (!*arg || (strcmp (arg, commands[i].name) == 0))
{
printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
printed++;
}
}
if (!printed)
{
printf ("No commands match `%s'. Possibilties are:\n", arg);
for (i = 0; commands[i].name; i++)
{
/* Print in six columns. */
if (printed == 6)
{
printed = 0;
printf ("\n");
}
printf ("%s\t", commands[i].name);
printed++;
}
if (printed)
printf ("\n");
}
return (0);
}
/* Change to the directory ARG. */
com_cd (arg)
char *arg;
{
if (chdir (arg) == -1)
{
perror (arg);
return 1;
}
com_pwd ("");
return (0);
}
/* Print out the current working directory. */
com_pwd (ignore)
char *ignore;
{
char dir[1024], *s;
s = getcwd (dir, sizeof(dir) - 1);
if (s == 0)
{
printf ("Error getting pwd: %s\n", dir);
return 1;
}
printf ("Current directory is %s\n", dir);
return 0;
}
/* The user wishes to quit using this program. Just set DONE non-zero. */
com_quit (arg)
char *arg;
{
done = 1;
return (0);
}
/* Function which tells you that you can't do this. */
too_dangerous (caller)
char *caller;
{
fprintf (stderr,
"%s: Too dangerous for me to distribute. Write it yourself.\n",
caller);
}
/* Return non-zero if ARG is a valid argument for CALLER, else print
an error message and return zero. */
int
valid_argument (caller, arg)
char *caller, *arg;
{
if (!arg || !*arg)
{
fprintf (stderr, "%s: Argument required.\n", caller);
return (0);
}
return (1);
}
File: readline.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Programming with GNU Readline, Up: Top
Appendix A GNU Free Documentation License
*****************************************
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
`http://fsf.org/'
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book.
We recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it
can be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
"Document", below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as "you". You
accept the license if you copy, modify or distribute the work in a
way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in
the notice that says that the Document is released under this
License. If a section does not fit the above definition of
Secondary then it is not allowed to be designated as Invariant.
The Document may contain zero Invariant Sections. If the Document
does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images
composed of pixels) generic paint programs or (for drawings) some
widely available drawing editor, and that is suitable for input to
text formatters or for automatic translation to a variety of
formats suitable for input to text formatters. A copy made in an
otherwise Transparent file format whose markup, or absence of
markup, has been arranged to thwart or discourage subsequent
modification by readers is not Transparent. An image format is
not Transparent if used for any substantial amount of text. A
copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and
standard-conforming simple HTML, PostScript or PDF designed for
human modification. Examples of transparent image formats include
PNG, XCF and JPG. Opaque formats include proprietary formats that
can be read and edited only by proprietary word processors, SGML or
XML for which the DTD and/or processing tools are not generally
available, and the machine-generated HTML, PostScript or PDF
produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, "Title
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies
of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
"Acknowledgements", "Dedications", "Endorsements", or "History".)
To "Preserve the Title" of such a section when you modify the
Document means that it remains a section "Entitled XYZ" according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow
the conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the
title equally prominent and visible. You may add other material
on the covers in addition. Copying with changes limited to the
covers, as long as they preserve the title of the Document and
satisfy these conditions, can be treated as verbatim copying in
other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or
state in or with each Opaque copy a computer-network location from
which the general network-using public has access to download
using public-standard network protocols a complete Transparent
copy of the Document, free of added material. If you use the
latter option, you must take reasonably prudent steps, when you
begin distribution of Opaque copies in quantity, to ensure that
this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you
distribute an Opaque copy (directly or through your agents or
retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of
copies, to give them a chance to provide you with an updated
version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with
the Modified Version filling the role of the Document, thus
licensing distribution and modification of the Modified Version to
whoever possesses a copy of it. In addition, you must do these
things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of
previous versions (which should, if there were any, be listed
in the History section of the Document). You may use the
same title as a previous version if the original publisher of
that version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on
the Title Page. If there is no section Entitled "History" in
the Document, create one stating the title, year, authors,
and publisher of the Document as given on its Title Page,
then add an item describing the Modified Version as stated in
the previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in
the "History" section. You may omit a network location for a
work that was published at least four years before the
Document itself, or if the original publisher of the version
it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the
section all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section
titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this,
add their titles to the list of Invariant Sections in the Modified
Version's license notice. These titles must be distinct from any
other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end
of the list of Cover Texts in the Modified Version. Only one
passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the
Document already includes a cover text for the same cover,
previously added by you or by arrangement made by the same entity
you are acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination
all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one section
Entitled "History"; likewise combine any sections Entitled
"Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the
documents in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow
this License in all other respects regarding verbatim copying of
that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of
a storage or distribution medium, is called an "aggregate" if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual
works permit. When the Document is included in an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document's Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void,
and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly
and finally terminates your license, and (b) permanently, if the
copyright holder fails to notify you of the violation by some
reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from
that copyright holder, and you cure the violation prior to 30 days
after your receipt of the notice.
Termination of your rights under this section does not terminate
the licenses of parties who have received copies or rights from
you under this License. If your rights have been terminated and
not permanently reinstated, receipt of a copy of some or all of
the same material does not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
`http://www.gnu.org/copyleft/'.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License "or any later version" applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If
the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by the
Free Software Foundation. If the Document specifies that a proxy
can decide which future versions of this License can be used, that
proxy's public statement of acceptance of a version permanently
authorizes you to choose that version for the Document.
11. RELICENSING
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server.
A "Massive Multiauthor Collaboration" (or "MMC") contained in the
site means any set of copyrightable works thus published on the MMC
site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this
License somewhere other than this MMC, and subsequently
incorporated in whole or in part into the MMC, (1) had no cover
texts or invariant sections, and (2) were thus incorporated prior
to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the
site under CC-BY-SA on the same site at any time before August 1,
2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
====================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.
File: readline.info, Node: Concept Index, Next: Function and Variable Index, Prev: GNU Free Documentation License, Up: Top
Concept Index
*************
[index ]
* Menu:
* application-specific completion functions: Custom Completers.
(line 6)
* command editing: Readline Bare Essentials.
(line 6)
* editing command lines: Readline Bare Essentials.
(line 6)
* initialization file, readline: Readline Init File. (line 6)
* interaction, readline: Readline Interaction. (line 6)
* kill ring: Readline Killing Commands.
(line 19)
* killing text: Readline Killing Commands.
(line 6)
* notation, readline: Readline Bare Essentials.
(line 6)
* readline, function: Basic Behavior. (line 12)
* variables, readline: Readline Init File Syntax.
(line 34)
* yanking text: Readline Killing Commands.
(line 6)
File: readline.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
Function and Variable Index
***************************
[index ]
* Menu:
* _rl_digit_p: Utility Functions. (line 65)
* _rl_digit_value: Utility Functions. (line 76)
* _rl_lowercase_p: Utility Functions. (line 62)
* _rl_to_lower: Utility Functions. (line 72)
* _rl_to_upper: Utility Functions. (line 68)
* _rl_uppercase_p: Utility Functions. (line 59)
* abort (C-g): Miscellaneous Commands.
(line 10)
* accept-line (Newline or Return): Commands For History.
(line 6)
* backward-char (C-b): Commands For Moving. (line 15)
* backward-delete-char (Rubout): Commands For Text. (line 17)
* backward-kill-line (C-x Rubout): Commands For Killing.
(line 9)
* backward-kill-word (M-): Commands For Killing.
(line 24)
* backward-word (M-b): Commands For Moving. (line 22)
* beginning-of-history (M-<): Commands For History.
(line 19)
* beginning-of-line (C-a): Commands For Moving. (line 6)
* bell-style: Readline Init File Syntax.
(line 35)
* bind-tty-special-chars: Readline Init File Syntax.
(line 42)
* call-last-kbd-macro (C-x e): Keyboard Macros. (line 13)
* capitalize-word (M-c): Commands For Text. (line 55)
* character-search (C-]): Miscellaneous Commands.
(line 41)
* character-search-backward (M-C-]): Miscellaneous Commands.
(line 46)
* clear-screen (C-l): Commands For Moving. (line 26)
* colored-stats: Readline Init File Syntax.
(line 47)
* comment-begin: Readline Init File Syntax.
(line 53)
* complete (): Commands For Completion.
(line 6)
* completion-display-width: Readline Init File Syntax.
(line 58)
* completion-ignore-case: Readline Init File Syntax.
(line 65)
* completion-map-case: Readline Init File Syntax.
(line 70)
* completion-prefix-display-length: Readline Init File Syntax.
(line 76)
* completion-query-items: Readline Init File Syntax.
(line 83)
* convert-meta: Readline Init File Syntax.
(line 93)
* copy-backward-word (): Commands For Killing.
(line 49)
* copy-forward-word (): Commands For Killing.
(line 54)
* copy-region-as-kill (): Commands For Killing.
(line 45)
* delete-char (C-d): Commands For Text. (line 12)
* delete-char-or-list (): Commands For Completion.
(line 39)
* delete-horizontal-space (): Commands For Killing.
(line 37)
* digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6)
* disable-completion: Readline Init File Syntax.
(line 99)
* do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands.
(line 14)
* downcase-word (M-l): Commands For Text. (line 51)
* dump-functions (): Miscellaneous Commands.
(line 70)
* dump-macros (): Miscellaneous Commands.
(line 82)
* dump-variables (): Miscellaneous Commands.
(line 76)
* editing-mode: Readline Init File Syntax.
(line 104)
* enable-keypad: Readline Init File Syntax.
(line 115)
* end-kbd-macro (C-x )): Keyboard Macros. (line 9)
* end-of-file (usually C-d): Commands For Text. (line 6)
* end-of-history (M->): Commands For History.
(line 22)
* end-of-line (C-e): Commands For Moving. (line 9)
* exchange-point-and-mark (C-x C-x): Miscellaneous Commands.
(line 36)
* expand-tilde: Readline Init File Syntax.
(line 126)
* forward-backward-delete-char (): Commands For Text. (line 21)
* forward-char (C-f): Commands For Moving. (line 12)
* forward-search-history (C-s): Commands For History.
(line 30)
* forward-word (M-f): Commands For Moving. (line 18)
* history-preserve-point: Readline Init File Syntax.
(line 130)
* history-search-backward (): Commands For History.
(line 51)
* history-search-forward (): Commands For History.
(line 45)
* history-size: Readline Init File Syntax.
(line 136)
* history-substr-search-backward (): Commands For History.
(line 63)
* history-substr-search-forward (): Commands For History.
(line 57)
* horizontal-scroll-mode: Readline Init File Syntax.
(line 143)
* input-meta: Readline Init File Syntax.
(line 150)
* insert-comment (M-#): Miscellaneous Commands.
(line 60)
* insert-completions (M-*): Commands For Completion.
(line 18)
* isearch-terminators: Readline Init File Syntax.
(line 157)
* keymap: Readline Init File Syntax.
(line 164)
* kill-line (C-k): Commands For Killing.
(line 6)
* kill-region (): Commands For Killing.
(line 41)
* kill-whole-line (): Commands For Killing.
(line 15)
* kill-word (M-d): Commands For Killing.
(line 19)
* mark-modified-lines: Readline Init File Syntax.
(line 193)
* mark-symlinked-directories: Readline Init File Syntax.
(line 198)
* match-hidden-files: Readline Init File Syntax.
(line 203)
* menu-complete (): Commands For Completion.
(line 22)
* menu-complete-backward (): Commands For Completion.
(line 34)
* menu-complete-display-prefix: Readline Init File Syntax.
(line 210)
* meta-flag: Readline Init File Syntax.
(line 150)
* next-history (C-n): Commands For History.
(line 16)
* non-incremental-forward-search-history (M-n): Commands For History.
(line 40)
* non-incremental-reverse-search-history (M-p): Commands For History.
(line 35)
* output-meta: Readline Init File Syntax.
(line 215)
* overwrite-mode (): Commands For Text. (line 59)
* page-completions: Readline Init File Syntax.
(line 220)
* possible-completions (M-?): Commands For Completion.
(line 11)
* prefix-meta (): Miscellaneous Commands.
(line 18)
* previous-history (C-p): Commands For History.
(line 12)
* print-last-kbd-macro (): Keyboard Macros. (line 17)
* quoted-insert (C-q or C-v): Commands For Text. (line 26)
* re-read-init-file (C-x C-r): Miscellaneous Commands.
(line 6)
* readline: Basic Behavior. (line 12)
* redraw-current-line (): Commands For Moving. (line 30)
* reverse-search-history (C-r): Commands For History.
(line 26)
* revert-all-at-newline: Readline Init File Syntax.
(line 230)
* revert-line (M-r): Miscellaneous Commands.
(line 25)
* rl_add_defun: Function Naming. (line 20)
* rl_add_funmap_entry: Associating Function Names and Bindings.
(line 47)
* rl_add_undo: Allowing Undoing. (line 41)
* rl_alphabetic: Utility Functions. (line 39)
* rl_already_prompted: Readline Variables. (line 64)
* rl_attempted_completion_function: Completion Variables.
(line 12)
* rl_attempted_completion_over: Completion Variables.
(line 255)
* rl_basic_quote_characters: Completion Variables.
(line 144)
* rl_basic_word_break_characters: Completion Variables.
(line 138)
* rl_begin_undo_group: Allowing Undoing. (line 29)
* rl_bind_key: Binding Keys. (line 22)
* rl_bind_key_if_unbound: Binding Keys. (line 32)
* rl_bind_key_if_unbound_in_map: Binding Keys. (line 38)
* rl_bind_key_in_map: Binding Keys. (line 27)
* rl_bind_keyseq: Binding Keys. (line 59)
* rl_bind_keyseq_if_unbound: Binding Keys. (line 77)
* rl_bind_keyseq_if_unbound_in_map: Binding Keys. (line 83)
* rl_bind_keyseq_in_map: Binding Keys. (line 66)
* rl_binding_keymap: Readline Variables. (line 186)
* rl_callback_handler_install: Alternate Interface. (line 15)
* rl_callback_handler_remove: Alternate Interface. (line 35)
* rl_callback_read_char: Alternate Interface. (line 22)
* rl_catch_signals: Readline Signal Handling.
(line 48)
* rl_catch_sigwinch: Readline Signal Handling.
(line 55)
* rl_change_environment: Readline Signal Handling.
(line 61)
* rl_char_is_quoted_p: Completion Variables.
(line 46)
* rl_cleanup_after_signal: Readline Signal Handling.
(line 73)
* rl_clear_history: Miscellaneous Functions.
(line 50)
* rl_clear_message: Redisplay. (line 48)
* rl_clear_pending_input: Character Input. (line 30)
* rl_clear_signals: Readline Signal Handling.
(line 132)
* rl_complete <1>: How Completing Works.
(line 49)
* rl_complete: Completion Functions.
(line 20)
* rl_complete_internal: Completion Functions.
(line 10)
* rl_completer_quote_characters: Completion Variables.
(line 161)
* rl_completer_word_break_characters: Completion Variables.
(line 147)
* rl_completion_append_character: Completion Variables.
(line 185)
* rl_completion_display_matches_hook: Completion Variables.
(line 125)
* rl_completion_entry_function <1>: How Completing Works.
(line 55)
* rl_completion_entry_function: Completion Variables.
(line 7)
* rl_completion_found_quote: Completion Variables.
(line 213)
* rl_completion_invoking_key: Completion Variables.
(line 278)
* rl_completion_mark_symlink_dirs: Completion Variables.
(line 220)
* rl_completion_matches: Completion Functions.
(line 45)
* rl_completion_mode: Completion Functions.
(line 37)
* rl_completion_query_items: Completion Variables.
(line 179)
* rl_completion_quote_character: Completion Variables.
(line 201)
* rl_completion_suppress_append: Completion Variables.
(line 195)
* rl_completion_suppress_quote: Completion Variables.
(line 207)
* rl_completion_type: Completion Variables.
(line 270)
* rl_completion_word_break_hook: Completion Variables.
(line 152)
* rl_copy_keymap: Keymaps. (line 17)
* rl_copy_text: Modifying Text. (line 15)
* rl_crlf: Redisplay. (line 30)
* rl_delete_text: Modifying Text. (line 11)
* rl_deprep_term_function: Readline Variables. (line 176)
* rl_deprep_terminal: Terminal Management. (line 13)
* rl_ding: Utility Functions. (line 36)
* rl_directory_completion_hook: Completion Variables.
(line 64)
* rl_directory_rewrite_hook;: Completion Variables.
(line 82)
* rl_discard_keymap: Keymaps. (line 26)
* rl_dispatching: Readline Variables. (line 41)
* rl_display_match_list: Utility Functions. (line 43)
* rl_display_prompt: Readline Variables. (line 59)
* rl_do_undo: Allowing Undoing. (line 48)
* rl_done: Readline Variables. (line 28)
* rl_echo_signal_char: Readline Signal Handling.
(line 96)
* rl_editing_mode: Readline Variables. (line 308)
* rl_end: Readline Variables. (line 19)
* rl_end_undo_group: Allowing Undoing. (line 35)
* rl_erase_empty_line: Readline Variables. (line 47)
* rl_event_hook: Readline Variables. (line 124)
* rl_execute_next: Character Input. (line 26)
* rl_executing_key: Readline Variables. (line 193)
* rl_executing_keymap: Readline Variables. (line 182)
* rl_executing_keyseq: Readline Variables. (line 197)
* rl_executing_macro: Readline Variables. (line 190)
* rl_expand_prompt: Redisplay. (line 64)
* rl_explicit_arg: Readline Variables. (line 299)
* rl_extend_line_buffer: Utility Functions. (line 27)
* rl_filename_completion_desired: Completion Variables.
(line 235)
* rl_filename_completion_function: Completion Functions.
(line 59)
* rl_filename_dequoting_function: Completion Variables.
(line 37)
* rl_filename_quote_characters: Completion Variables.
(line 167)
* rl_filename_quoting_desired: Completion Variables.
(line 245)
* rl_filename_quoting_function: Completion Variables.
(line 24)
* rl_filename_rewrite_hook: Completion Variables.
(line 110)
* rl_filename_stat_hook: Completion Variables.
(line 98)
* rl_forced_update_display: Redisplay. (line 11)
* rl_free: Utility Functions. (line 18)
* rl_free_keymap: Keymaps. (line 30)
* rl_free_line_state: Readline Signal Handling.
(line 79)
* rl_free_undo_list: Allowing Undoing. (line 45)
* rl_function_dumper: Associating Function Names and Bindings.
(line 30)
* rl_function_of_keyseq: Associating Function Names and Bindings.
(line 15)
* rl_funmap_names: Associating Function Names and Bindings.
(line 40)
* rl_generic_bind: Binding Keys. (line 89)
* rl_get_keymap: Keymaps. (line 37)
* rl_get_keymap_by_name: Keymaps. (line 43)
* rl_get_keymap_name: Keymaps. (line 48)
* rl_get_screen_size: Readline Signal Handling.
(line 115)
* rl_get_termcap: Miscellaneous Functions.
(line 42)
* rl_getc: Character Input. (line 15)
* rl_getc_function: Readline Variables. (line 130)
* rl_gnu_readline_p: Readline Variables. (line 83)
* rl_ignore_completion_duplicates: Completion Variables.
(line 231)
* rl_ignore_some_completions_function: Completion Variables.
(line 56)
* rl_inhibit_completion: Completion Variables.
(line 284)
* rl_initialize: Utility Functions. (line 31)
* rl_input_available_hook: Readline Variables. (line 142)
* rl_insert_completions: Completion Functions.
(line 32)
* rl_insert_text: Modifying Text. (line 7)
* rl_instream: Readline Variables. (line 97)
* rl_invoking_keyseqs: Associating Function Names and Bindings.
(line 21)
* rl_invoking_keyseqs_in_map: Associating Function Names and Bindings.
(line 26)
* rl_key_sequence_length: Readline Variables. (line 201)
* rl_kill_text: Modifying Text. (line 19)
* rl_last_func: Readline Variables. (line 110)
* rl_library_version: Readline Variables. (line 73)
* rl_line_buffer: Readline Variables. (line 9)
* rl_list_funmap_names: Associating Function Names and Bindings.
(line 36)
* rl_macro_bind: Miscellaneous Functions.
(line 8)
* rl_macro_dumper: Miscellaneous Functions.
(line 14)
* rl_make_bare_keymap: Keymaps. (line 12)
* rl_make_keymap: Keymaps. (line 20)
* rl_mark: Readline Variables. (line 24)
* rl_message: Redisplay. (line 39)
* rl_modifying: Allowing Undoing. (line 57)
* rl_named_function: Associating Function Names and Bindings.
(line 11)
* rl_num_chars_to_read: Readline Variables. (line 32)
* rl_numeric_arg: Readline Variables. (line 303)
* rl_on_new_line: Redisplay. (line 15)
* rl_on_new_line_with_prompt: Redisplay. (line 19)
* rl_outstream: Readline Variables. (line 101)
* rl_parse_and_bind: Binding Keys. (line 96)
* rl_pending_input: Readline Variables. (line 37)
* rl_point: Readline Variables. (line 15)
* rl_possible_completions: Completion Functions.
(line 28)
* rl_pre_input_hook: Readline Variables. (line 119)
* rl_prefer_env_winsize: Readline Variables. (line 105)
* rl_prep_term_function: Readline Variables. (line 169)
* rl_prep_terminal: Terminal Management. (line 7)
* rl_prompt: Readline Variables. (line 53)
* rl_push_macro_input: Modifying Text. (line 26)
* rl_read_init_file: Binding Keys. (line 101)
* rl_read_key: Character Input. (line 7)
* rl_readline_name: Readline Variables. (line 92)
* rl_readline_state: Readline Variables. (line 204)
* rl_readline_version: Readline Variables. (line 76)
* rl_redisplay: Redisplay. (line 7)
* rl_redisplay_function: Readline Variables. (line 163)
* rl_replace_line: Utility Functions. (line 22)
* rl_reset_after_signal: Readline Signal Handling.
(line 87)
* rl_reset_line_state: Redisplay. (line 26)
* rl_reset_screen_size: Readline Signal Handling.
(line 119)
* rl_reset_terminal: Terminal Management. (line 28)
* rl_resize_terminal: Readline Signal Handling.
(line 102)
* rl_restore_prompt: Redisplay. (line 57)
* rl_restore_state: Utility Functions. (line 12)
* rl_save_prompt: Redisplay. (line 53)
* rl_save_state: Utility Functions. (line 7)
* rl_set_key: Binding Keys. (line 73)
* rl_set_keyboard_input_timeout: Character Input. (line 35)
* rl_set_keymap: Keymaps. (line 40)
* rl_set_paren_blink_timeout: Miscellaneous Functions.
(line 37)
* rl_set_prompt: Redisplay. (line 78)
* rl_set_screen_size: Readline Signal Handling.
(line 106)
* rl_set_signals: Readline Signal Handling.
(line 126)
* rl_show_char: Redisplay. (line 33)
* rl_signal_event_hook: Readline Variables. (line 138)
* rl_sort_completion_matches: Completion Variables.
(line 262)
* rl_special_prefixes: Completion Variables.
(line 172)
* rl_startup_hook: Readline Variables. (line 115)
* rl_stuff_char: Character Input. (line 19)
* rl_terminal_name: Readline Variables. (line 87)
* rl_tty_set_default_bindings: Terminal Management. (line 18)
* rl_tty_unset_default_bindings: Terminal Management. (line 23)
* rl_unbind_command_in_map: Binding Keys. (line 55)
* rl_unbind_function_in_map: Binding Keys. (line 51)
* rl_unbind_key: Binding Keys. (line 42)
* rl_unbind_key_in_map: Binding Keys. (line 46)
* rl_username_completion_function: Completion Functions.
(line 66)
* rl_variable_bind: Miscellaneous Functions.
(line 21)
* rl_variable_dumper: Miscellaneous Functions.
(line 31)
* rl_variable_value: Miscellaneous Functions.
(line 26)
* self-insert (a, b, A, 1, !, ...): Commands For Text. (line 33)
* set-mark (C-@): Miscellaneous Commands.
(line 32)
* show-all-if-ambiguous: Readline Init File Syntax.
(line 236)
* show-all-if-unmodified: Readline Init File Syntax.
(line 242)
* show-mode-in-prompt: Readline Init File Syntax.
(line 251)
* skip-completed-text: Readline Init File Syntax.
(line 256)
* skip-csi-sequence (): Miscellaneous Commands.
(line 51)
* start-kbd-macro (C-x (): Keyboard Macros. (line 6)
* transpose-chars (C-t): Commands For Text. (line 36)
* transpose-words (M-t): Commands For Text. (line 42)
* undo (C-_ or C-x C-u): Miscellaneous Commands.
(line 22)
* universal-argument (): Numeric Arguments. (line 10)
* unix-filename-rubout (): Commands For Killing.
(line 32)
* unix-line-discard (C-u): Commands For Killing.
(line 12)
* unix-word-rubout (C-w): Commands For Killing.
(line 28)
* upcase-word (M-u): Commands For Text. (line 47)
* visible-stats: Readline Init File Syntax.
(line 269)
* yank (C-y): Commands For Killing.
(line 59)
* yank-last-arg (M-. or M-_): Commands For History.
(line 78)
* yank-nth-arg (M-C-y): Commands For History.
(line 69)
* yank-pop (M-y): Commands For Killing.
(line 62)
Tag Table:
Node: Top907
Node: Command Line Editing1632
Node: Introduction and Notation2284
Node: Readline Interaction3907
Node: Readline Bare Essentials5099
Node: Readline Movement Commands6889
Node: Readline Killing Commands7855
Node: Readline Arguments9776
Node: Searching10821
Node: Readline Init File12973
Node: Readline Init File Syntax14127
Node: Conditional Init Constructs30832
Node: Sample Init File33366
Node: Bindable Readline Commands36485
Node: Commands For Moving37543
Node: Commands For History38405
Node: Commands For Text42560
Node: Commands For Killing45543
Node: Numeric Arguments47686
Node: Commands For Completion48826
Node: Keyboard Macros50796
Node: Miscellaneous Commands51485
Node: Readline vi Mode55342
Node: Programming with GNU Readline57159
Node: Basic Behavior58145
Node: Custom Functions61562
Node: Readline Typedefs63046
Node: Function Writing64686
Node: Readline Variables65993
Node: Readline Convenience Functions78671
Node: Function Naming79743
Node: Keymaps81005
Node: Binding Keys82998
Node: Associating Function Names and Bindings87545
Node: Allowing Undoing89830
Node: Redisplay92380
Node: Modifying Text96281
Node: Character Input97527
Node: Terminal Management99425
Node: Utility Functions100861
Node: Miscellaneous Functions104189
Node: Alternate Interface106778
Node: A Readline Example109012
Node: Alternate Interface Example110951
Node: Readline Signal Handling113724
Node: Custom Completers120246
Node: How Completing Works120966
Node: Completion Functions124280
Node: Completion Variables127854
Node: A Short Completion Example143502
Node: GNU Free Documentation License156281
Node: Concept Index181474
Node: Function and Variable Index182995
End Tag Table
0707010002ca5c000081a40000000000000000000000015424dff70000ee33000001120001001bffffffffffffffff0000002700000000root/usr/local/share/info/history.info This is history.info, produced by makeinfo version 4.13 from
/usr/homes/chet/src/bash/readline-src/doc/history.texi.
This document describes the GNU History library (version 6.3, 6 January
2014), a programming tool that provides a consistent user interface for
recalling lines of previously typed input.
Copyright (C) 1988-2014 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Libraries
START-INFO-DIR-ENTRY
* History: (history). The GNU history library API.
END-INFO-DIR-ENTRY
File: history.info, Node: Top, Next: Using History Interactively, Up: (dir)
GNU History Library
*******************
This document describes the GNU History library, a programming tool that
provides a consistent user interface for recalling lines of previously
typed input.
* Menu:
* Using History Interactively:: GNU History User's Manual.
* Programming with GNU History:: GNU History Programmer's Manual.
* GNU Free Documentation License:: License for copying this manual.
* Concept Index:: Index of concepts described in this manual.
* Function and Variable Index:: Index of externally visible functions
and variables.
File: history.info, Node: Using History Interactively, Next: Programming with GNU History, Prev: Top, Up: Top
1 Using History Interactively
*****************************
This chapter describes how to use the GNU History Library interactively,
from a user's standpoint. It should be considered a user's guide. For
information on using the GNU History Library in your own programs,
*note Programming with GNU History::.
* Menu:
* History Interaction:: What it feels like using History as a user.
File: history.info, Node: History Interaction, Up: Using History Interactively
1.1 History Expansion
=====================
The History library provides a history expansion feature that is similar
to the history expansion provided by `csh'. This section describes the
syntax used to manipulate the history information.
History expansions introduce words from the history list into the
input stream, making it easy to repeat commands, insert the arguments
to a previous command into the current input line, or fix errors in
previous commands quickly.
History expansion takes place in two parts. The first is to
determine which line from the history list should be used during
substitution. The second is to select portions of that line for
inclusion into the current one. The line selected from the history is
called the "event", and the portions of that line that are acted upon
are called "words". Various "modifiers" are available to manipulate
the selected words. The line is broken into words in the same fashion
that Bash does, so that several words surrounded by quotes are
considered one word. History expansions are introduced by the
appearance of the history expansion character, which is `!' by default.
* Menu:
* Event Designators:: How to specify which history line to use.
* Word Designators:: Specifying which words are of interest.
* Modifiers:: Modifying the results of substitution.
File: history.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
1.1.1 Event Designators
-----------------------
An event designator is a reference to a command line entry in the
history list. Unless the reference is absolute, events are relative to
the current position in the history list.
`!'
Start a history substitution, except when followed by a space, tab,
the end of the line, or `='.
`!N'
Refer to command line N.
`!-N'
Refer to the command N lines back.
`!!'
Refer to the previous command. This is a synonym for `!-1'.
`!STRING'
Refer to the most recent command preceding the current position in
the history list starting with STRING.
`!?STRING[?]'
Refer to the most recent command preceding the current position in
the history list containing STRING. The trailing `?' may be
omitted if the STRING is followed immediately by a newline.
`^STRING1^STRING2^'
Quick Substitution. Repeat the last command, replacing STRING1
with STRING2. Equivalent to `!!:s/STRING1/STRING2/'.
`!#'
The entire command line typed so far.
File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
1.1.2 Word Designators
----------------------
Word designators are used to select desired words from the event. A
`:' separates the event specification from the word designator. It may
be omitted if the word designator begins with a `^', `$', `*', `-', or
`%'. Words are numbered from the beginning of the line, with the first
word being denoted by 0 (zero). Words are inserted into the current
line separated by single spaces.
For example,
`!!'
designates the preceding command. When you type this, the
preceding command is repeated in toto.
`!!:$'
designates the last argument of the preceding command. This may be
shortened to `!$'.
`!fi:2'
designates the second argument of the most recent command starting
with the letters `fi'.
Here are the word designators:
`0 (zero)'
The `0'th word. For many applications, this is the command word.
`N'
The Nth word.
`^'
The first argument; that is, word 1.
`$'
The last argument.
`%'
The word matched by the most recent `?STRING?' search.
`X-Y'
A range of words; `-Y' abbreviates `0-Y'.
`*'
All of the words, except the `0'th. This is a synonym for `1-$'.
It is not an error to use `*' if there is just one word in the
event; the empty string is returned in that case.
`X*'
Abbreviates `X-$'
`X-'
Abbreviates `X-$' like `X*', but omits the last word.
If a word designator is supplied without an event specification, the
previous command is used as the event.
File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
1.1.3 Modifiers
---------------
After the optional word designator, you can add a sequence of one or
more of the following modifiers, each preceded by a `:'.
`h'
Remove a trailing pathname component, leaving only the head.
`t'
Remove all leading pathname components, leaving the tail.
`r'
Remove a trailing suffix of the form `.SUFFIX', leaving the
basename.
`e'
Remove all but the trailing suffix.
`p'
Print the new command but do not execute it.
`s/OLD/NEW/'
Substitute NEW for the first occurrence of OLD in the event line.
Any delimiter may be used in place of `/'. The delimiter may be
quoted in OLD and NEW with a single backslash. If `&' appears in
NEW, it is replaced by OLD. A single backslash will quote the
`&'. The final delimiter is optional if it is the last character
on the input line.
`&'
Repeat the previous substitution.
`g'
`a'
Cause changes to be applied over the entire event line. Used in
conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
`G'
Apply the following `s' modifier once to each word in the event.
File: history.info, Node: Programming with GNU History, Next: GNU Free Documentation License, Prev: Using History Interactively, Up: Top
2 Programming with GNU History
******************************
This chapter describes how to interface programs that you write with
the GNU History Library. It should be considered a technical guide.
For information on the interactive use of GNU History, *note Using
History Interactively::.
* Menu:
* Introduction to History:: What is the GNU History library for?
* History Storage:: How information is stored.
* History Functions:: Functions that you can use.
* History Variables:: Variables that control behaviour.
* History Programming Example:: Example of using the GNU History Library.
File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History
2.1 Introduction to History
===========================
Many programs read input from the user a line at a time. The GNU
History library is able to keep track of those lines, associate
arbitrary data with each line, and utilize information from previous
lines in composing new ones.
The programmer using the History library has available functions for
remembering lines on a history list, associating arbitrary data with a
line, removing lines from the list, searching through the list for a
line containing an arbitrary text string, and referencing any line in
the list directly. In addition, a history "expansion" function is
available which provides for a consistent user interface across
different programs.
The user using programs written with the History library has the
benefit of a consistent user interface with a set of well-known
commands for manipulating the text of previous lines and using that text
in new commands. The basic history manipulation commands are similar to
the history substitution provided by `csh'.
If the programmer desires, he can use the Readline library, which
includes some history manipulation by default, and has the added
advantage of command line editing.
Before declaring any functions using any functionality the History
library provides in other code, an application writer should include
the file `' in any file that uses the History
library's features. It supplies extern declarations for all of the
library's public functions and variables, and declares all of the
public data structures.
File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History
2.2 History Storage
===================
The history list is an array of history entries. A history entry is
declared as follows:
typedef void *histdata_t;
typedef struct _hist_entry {
char *line;
char *timestamp;
histdata_t data;
} HIST_ENTRY;
The history list itself might therefore be declared as
HIST_ENTRY **the_history_list;
The state of the History library is encapsulated into a single
structure:
/*
* A structure used to pass around the current state of the history.
*/
typedef struct _hist_state {
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
int offset; /* The location pointer within this array. */
int length; /* Number of elements within this array. */
int size; /* Number of slots allocated to this array. */
int flags;
} HISTORY_STATE;
If the flags member includes `HS_STIFLED', the history has been
stifled.
File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History
2.3 History Functions
=====================
This section describes the calling sequence for the various functions
exported by the GNU History library.
* Menu:
* Initializing History and State Management:: Functions to call when you
want to use history in a
program.
* History List Management:: Functions used to manage the list
of history entries.
* Information About the History List:: Functions returning information about
the history list.
* Moving Around the History List:: Functions used to change the position
in the history list.
* Searching the History List:: Functions to search the history list
for entries containing a string.
* Managing the History File:: Functions that read and write a file
containing the history list.
* History Expansion:: Functions to perform csh-like history
expansion.
File: history.info, Node: Initializing History and State Management, Next: History List Management, Up: History Functions
2.3.1 Initializing History and State Management
-----------------------------------------------
This section describes functions used to initialize and manage the
state of the History library when you want to use the history functions
in your program.
-- Function: void using_history (void)
Begin a session in which the history functions might be used. This
initializes the interactive variables.
-- Function: HISTORY_STATE * history_get_history_state (void)
Return a structure describing the current state of the input
history.
-- Function: void history_set_history_state (HISTORY_STATE *state)
Set the state of the history list according to STATE.
File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions
2.3.2 History List Management
-----------------------------
These functions manage individual entries on the history list, or set
parameters managing the list itself.
-- Function: void add_history (const char *string)
Place STRING at the end of the history list. The associated data
field (if any) is set to `NULL'.
-- Function: void add_history_time (const char *string)
Change the time stamp associated with the most recent history
entry to STRING.
-- Function: HIST_ENTRY * remove_history (int which)
Remove history entry at offset WHICH from the history. The
removed element is returned so you can free the line, data, and
containing structure.
-- Function: histdata_t free_history_entry (HIST_ENTRY *histent)
Free the history entry HISTENT and any history library private
data associated with it. Returns the application-specific data so
the caller can dispose of it.
-- Function: HIST_ENTRY * replace_history_entry (int which, const char
*line, histdata_t data)
Make the history entry at offset WHICH have LINE and DATA. This
returns the old entry so the caller can dispose of any
application-specific data. In the case of an invalid WHICH, a
`NULL' pointer is returned.
-- Function: void clear_history (void)
Clear the history list by deleting all the entries.
-- Function: void stifle_history (int max)
Stifle the history list, remembering only the last MAX entries.
-- Function: int unstifle_history (void)
Stop stifling the history. This returns the previously-set
maximum number of history entries (as set by `stifle_history()').
The value is positive if the history was stifled, negative if it
wasn't.
-- Function: int history_is_stifled (void)
Returns non-zero if the history is stifled, zero if it is not.
File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions
2.3.3 Information About the History List
----------------------------------------
These functions return information about the entire history list or
individual list entries.
-- Function: HIST_ENTRY ** history_list (void)
Return a `NULL' terminated array of `HIST_ENTRY *' which is the
current input history. Element 0 of this list is the beginning of
time. If there is no history, return `NULL'.
-- Function: int where_history (void)
Returns the offset of the current history element.
-- Function: HIST_ENTRY * current_history (void)
Return the history entry at the current position, as determined by
`where_history()'. If there is no entry there, return a `NULL'
pointer.
-- Function: HIST_ENTRY * history_get (int offset)
Return the history entry at position OFFSET, starting from
`history_base' (*note History Variables::). If there is no entry
there, or if OFFSET is greater than the history length, return a
`NULL' pointer.
-- Function: time_t history_get_time (HIST_ENTRY *entry)
Return the time stamp associated with the history entry ENTRY.
-- Function: int history_total_bytes (void)
Return the number of bytes that the primary history entries are
using. This function returns the sum of the lengths of all the
lines in the history.
File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions
2.3.4 Moving Around the History List
------------------------------------
These functions allow the current index into the history list to be set
or changed.
-- Function: int history_set_pos (int pos)
Set the current history offset to POS, an absolute index into the
list. Returns 1 on success, 0 if POS is less than zero or greater
than the number of history entries.
-- Function: HIST_ENTRY * previous_history (void)
Back up the current history offset to the previous history entry,
and return a pointer to that entry. If there is no previous
entry, return a `NULL' pointer.
-- Function: HIST_ENTRY * next_history (void)
Move the current history offset forward to the next history entry,
and return the a pointer to that entry. If there is no next
entry, return a `NULL' pointer.
File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions
2.3.5 Searching the History List
--------------------------------
These functions allow searching of the history list for entries
containing a specific string. Searching may be performed both forward
and backward from the current history position. The search may be
"anchored", meaning that the string must match at the beginning of the
history entry.
-- Function: int history_search (const char *string, int direction)
Search the history for STRING, starting at the current history
offset. If DIRECTION is less than 0, then the search is through
previous entries, otherwise through subsequent entries. If STRING
is found, then the current history index is set to that history
entry, and the value returned is the offset in the line of the
entry where STRING was found. Otherwise, nothing is changed, and
a -1 is returned.
-- Function: int history_search_prefix (const char *string, int
direction)
Search the history for STRING, starting at the current history
offset. The search is anchored: matching lines must begin with
STRING. If DIRECTION is less than 0, then the search is through
previous entries, otherwise through subsequent entries. If STRING
is found, then the current history index is set to that entry, and
the return value is 0. Otherwise, nothing is changed, and a -1 is
returned.
-- Function: int history_search_pos (const char *string, int
direction, int pos)
Search for STRING in the history list, starting at POS, an
absolute index into the list. If DIRECTION is negative, the search
proceeds backward from POS, otherwise forward. Returns the
absolute index of the history element where STRING was found, or
-1 otherwise.
File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions
2.3.6 Managing the History File
-------------------------------
The History library can read the history from and write it to a file.
This section documents the functions for managing a history file.
-- Function: int read_history (const char *filename)
Add the contents of FILENAME to the history list, a line at a time.
If FILENAME is `NULL', then read from `~/.history'. Returns 0 if
successful, or `errno' if not.
-- Function: int read_history_range (const char *filename, int from,
int to)
Read a range of lines from FILENAME, adding them to the history
list. Start reading at line FROM and end at TO. If FROM is zero,
start at the beginning. If TO is less than FROM, then read until
the end of the file. If FILENAME is `NULL', then read from
`~/.history'. Returns 0 if successful, or `errno' if not.
-- Function: int write_history (const char *filename)
Write the current history to FILENAME, overwriting FILENAME if
necessary. If FILENAME is `NULL', then write the history list to
`~/.history'. Returns 0 on success, or `errno' on a read or write
error.
-- Function: int append_history (int nelements, const char *filename)
Append the last NELEMENTS of the history list to FILENAME. If
FILENAME is `NULL', then append to `~/.history'. Returns 0 on
success, or `errno' on a read or write error.
-- Function: int history_truncate_file (const char *filename, int
nlines)
Truncate the history file FILENAME, leaving only the last NLINES
lines. If FILENAME is `NULL', then `~/.history' is truncated.
Returns 0 on success, or `errno' on failure.
File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions
2.3.7 History Expansion
-----------------------
These functions implement history expansion.
-- Function: int history_expand (char *string, char **output)
Expand STRING, placing the result into OUTPUT, a pointer to a
string (*note History Interaction::). Returns:
`0'
If no expansions took place (or, if the only change in the
text was the removal of escape characters preceding the
history expansion character);
`1'
if expansions did take place;
`-1'
if there was an error in expansion;
`2'
if the returned line should be displayed, but not executed,
as with the `:p' modifier (*note Modifiers::).
If an error occurred in expansion, then OUTPUT contains a
descriptive error message.
-- Function: char * get_history_event (const char *string, int
*cindex, int qchar)
Returns the text of the history event beginning at STRING +
*CINDEX. *CINDEX is modified to point to after the event
specifier. At function entry, CINDEX points to the index into
STRING where the history event specification begins. QCHAR is a
character that is allowed to end the event specification in
addition to the "normal" terminating characters.
-- Function: char ** history_tokenize (const char *string)
Return an array of tokens parsed out of STRING, much as the shell
might. The tokens are split on the characters in the
HISTORY_WORD_DELIMITERS variable, and shell quoting conventions
are obeyed.
-- Function: char * history_arg_extract (int first, int last, const
char *string)
Extract a string segment consisting of the FIRST through LAST
arguments present in STRING. Arguments are split using
`history_tokenize'.
File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History
2.4 History Variables
=====================
This section describes the externally-visible variables exported by the
GNU History Library.
-- Variable: int history_base
The logical offset of the first entry in the history list.
-- Variable: int history_length
The number of entries currently stored in the history list.
-- Variable: int history_max_entries
The maximum number of history entries. This must be changed using
`stifle_history()'.
-- Variable: int history_write_timestamps
If non-zero, timestamps are written to the history file, so they
can be preserved between sessions. The default value is 0,
meaning that timestamps are not saved.
The current timestamp format uses the value of HISTORY_COMMENT_CHAR
to delimit timestamp entries in the history file. If that
variable does not have a value (the default), timestamps will not
be written.
-- Variable: char history_expansion_char
The character that introduces a history event. The default is `!'.
Setting this to 0 inhibits history expansion.
-- Variable: char history_subst_char
The character that invokes word substitution if found at the start
of a line. The default is `^'.
-- Variable: char history_comment_char
During tokenization, if this character is seen as the first
character of a word, then it and all subsequent characters up to a
newline are ignored, suppressing history expansion for the
remainder of the line. This is disabled by default.
-- Variable: char * history_word_delimiters
The characters that separate tokens for `history_tokenize()'. The
default value is `" \t\n()<>;&|"'.
-- Variable: char * history_search_delimiter_chars
The list of additional characters which can delimit a history
search string, in addition to space, TAB, `:' and `?' in the case
of a substring search. The default is empty.
-- Variable: char * history_no_expand_chars
The list of characters which inhibit history expansion if found
immediately following HISTORY_EXPANSION_CHAR. The default is
space, tab, newline, carriage return, and `='.
-- Variable: int history_quotes_inhibit_expansion
If non-zero, single-quoted words are not scanned for the history
expansion character. The default value is 0.
-- Variable: rl_linebuf_func_t * history_inhibit_expansion_function
This should be set to the address of a function that takes two
arguments: a `char *' (STRING) and an `int' index into that string
(I). It should return a non-zero value if the history expansion
starting at STRING[I] should not be performed; zero if the
expansion should be done. It is intended for use by applications
like Bash that use the history expansion character for additional
purposes. By default, this variable is set to `NULL'.
File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History
2.5 History Programming Example
===============================
The following program demonstrates simple use of the GNU History
Library.
#include
#include
main (argc, argv)
int argc;
char **argv;
{
char line[1024], *t;
int len, done = 0;
line[0] = 0;
using_history ();
while (!done)
{
printf ("history$ ");
fflush (stdout);
t = fgets (line, sizeof (line) - 1, stdin);
if (t && *t)
{
len = strlen (t);
if (t[len - 1] == '\n')
t[len - 1] = '\0';
}
if (!t)
strcpy (line, "quit");
if (line[0])
{
char *expansion;
int result;
result = history_expand (line, &expansion);
if (result)
fprintf (stderr, "%s\n", expansion);
if (result < 0 || result == 2)
{
free (expansion);
continue;
}
add_history (expansion);
strncpy (line, expansion, sizeof (line) - 1);
free (expansion);
}
if (strcmp (line, "quit") == 0)
done = 1;
else if (strcmp (line, "save") == 0)
write_history ("history_file");
else if (strcmp (line, "read") == 0)
read_history ("history_file");
else if (strcmp (line, "list") == 0)
{
register HIST_ENTRY **the_list;
register int i;
the_list = history_list ();
if (the_list)
for (i = 0; the_list[i]; i++)
printf ("%d: %s\n", i + history_base, the_list[i]->line);
}
else if (strncmp (line, "delete", 6) == 0)
{
int which;
if ((sscanf (line + 6, "%d", &which)) == 1)
{
HIST_ENTRY *entry = remove_history (which);
if (!entry)
fprintf (stderr, "No such entry %d\n", which);
else
{
free (entry->line);
free (entry);
}
}
else
{
fprintf (stderr, "non-numeric arg given to `delete'\n");
}
}
}
}
File: history.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Programming with GNU History, Up: Top
Appendix A GNU Free Documentation License
*****************************************
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
`http://fsf.org/'
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book.
We recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it
can be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
"Document", below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as "you". You
accept the license if you copy, modify or distribute the work in a
way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in
the notice that says that the Document is released under this
License. If a section does not fit the above definition of
Secondary then it is not allowed to be designated as Invariant.
The Document may contain zero Invariant Sections. If the Document
does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images
composed of pixels) generic paint programs or (for drawings) some
widely available drawing editor, and that is suitable for input to
text formatters or for automatic translation to a variety of
formats suitable for input to text formatters. A copy made in an
otherwise Transparent file format whose markup, or absence of
markup, has been arranged to thwart or discourage subsequent
modification by readers is not Transparent. An image format is
not Transparent if used for any substantial amount of text. A
copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and
standard-conforming simple HTML, PostScript or PDF designed for
human modification. Examples of transparent image formats include
PNG, XCF and JPG. Opaque formats include proprietary formats that
can be read and edited only by proprietary word processors, SGML or
XML for which the DTD and/or processing tools are not generally
available, and the machine-generated HTML, PostScript or PDF
produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, "Title
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies
of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
"Acknowledgements", "Dedications", "Endorsements", or "History".)
To "Preserve the Title" of such a section when you modify the
Document means that it remains a section "Entitled XYZ" according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow
the conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the
title equally prominent and visible. You may add other material
on the covers in addition. Copying with changes limited to the
covers, as long as they preserve the title of the Document and
satisfy these conditions, can be treated as verbatim copying in
other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or
state in or with each Opaque copy a computer-network location from
which the general network-using public has access to download
using public-standard network protocols a complete Transparent
copy of the Document, free of added material. If you use the
latter option, you must take reasonably prudent steps, when you
begin distribution of Opaque copies in quantity, to ensure that
this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you
distribute an Opaque copy (directly or through your agents or
retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of
copies, to give them a chance to provide you with an updated
version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with
the Modified Version filling the role of the Document, thus
licensing distribution and modification of the Modified Version to
whoever possesses a copy of it. In addition, you must do these
things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of
previous versions (which should, if there were any, be listed
in the History section of the Document). You may use the
same title as a previous version if the original publisher of
that version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on
the Title Page. If there is no section Entitled "History" in
the Document, create one stating the title, year, authors,
and publisher of the Document as given on its Title Page,
then add an item describing the Modified Version as stated in
the previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in
the "History" section. You may omit a network location for a
work that was published at least four years before the
Document itself, or if the original publisher of the version
it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the
section all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section
titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this,
add their titles to the list of Invariant Sections in the Modified
Version's license notice. These titles must be distinct from any
other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end
of the list of Cover Texts in the Modified Version. Only one
passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the
Document already includes a cover text for the same cover,
previously added by you or by arrangement made by the same entity
you are acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination
all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one section
Entitled "History"; likewise combine any sections Entitled
"Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the
documents in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow
this License in all other respects regarding verbatim copying of
that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of
a storage or distribution medium, is called an "aggregate" if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual
works permit. When the Document is included in an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document's Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void,
and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly
and finally terminates your license, and (b) permanently, if the
copyright holder fails to notify you of the violation by some
reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from
that copyright holder, and you cure the violation prior to 30 days
after your receipt of the notice.
Termination of your rights under this section does not terminate
the licenses of parties who have received copies or rights from
you under this License. If your rights have been terminated and
not permanently reinstated, receipt of a copy of some or all of
the same material does not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
`http://www.gnu.org/copyleft/'.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License "or any later version" applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If
the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by the
Free Software Foundation. If the Document specifies that a proxy
can decide which future versions of this License can be used, that
proxy's public statement of acceptance of a version permanently
authorizes you to choose that version for the Document.
11. RELICENSING
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server.
A "Massive Multiauthor Collaboration" (or "MMC") contained in the
site means any set of copyrightable works thus published on the MMC
site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this
License somewhere other than this MMC, and subsequently
incorporated in whole or in part into the MMC, (1) had no cover
texts or invariant sections, and (2) were thus incorporated prior
to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the
site under CC-BY-SA on the same site at any time before August 1,
2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
====================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.
File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: GNU Free Documentation License, Up: Top
Appendix B Concept Index
************************
[index ]
* Menu:
* anchored search: Searching the History List.
(line 10)
* event designators: Event Designators. (line 6)
* history events: Event Designators. (line 8)
* history expansion: History Interaction. (line 6)
* History Searching: Searching the History List.
(line 6)
File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
Appendix C Function and Variable Index
**************************************
[index ]
* Menu:
* add_history: History List Management.
(line 10)
* add_history_time: History List Management.
(line 14)
* append_history: Managing the History File.
(line 29)
* clear_history: History List Management.
(line 35)
* current_history: Information About the History List.
(line 18)
* free_history_entry: History List Management.
(line 23)
* get_history_event: History Expansion. (line 31)
* history_arg_extract: History Expansion. (line 46)
* history_base: History Variables. (line 10)
* history_comment_char: History Variables. (line 38)
* history_expand: History Expansion. (line 9)
* history_expansion_char: History Variables. (line 30)
* history_get: Information About the History List.
(line 23)
* history_get_history_state: Initializing History and State Management.
(line 15)
* history_get_time: Information About the History List.
(line 29)
* history_inhibit_expansion_function: History Variables. (line 62)
* history_is_stifled: History List Management.
(line 47)
* history_length: History Variables. (line 13)
* history_list: Information About the History List.
(line 10)
* history_max_entries: History Variables. (line 16)
* history_no_expand_chars: History Variables. (line 53)
* history_quotes_inhibit_expansion: History Variables. (line 58)
* history_search: Searching the History List.
(line 13)
* history_search_delimiter_chars: History Variables. (line 48)
* history_search_pos: Searching the History List.
(line 33)
* history_search_prefix: Searching the History List.
(line 23)
* history_set_history_state: Initializing History and State Management.
(line 19)
* history_set_pos: Moving Around the History List.
(line 10)
* history_subst_char: History Variables. (line 34)
* history_tokenize: History Expansion. (line 39)
* history_total_bytes: Information About the History List.
(line 32)
* history_truncate_file: Managing the History File.
(line 35)
* history_word_delimiters: History Variables. (line 44)
* history_write_timestamps: History Variables. (line 20)
* next_history: Moving Around the History List.
(line 20)
* previous_history: Moving Around the History List.
(line 15)
* read_history: Managing the History File.
(line 10)
* read_history_range: Managing the History File.
(line 16)
* remove_history: History List Management.
(line 18)
* replace_history_entry: History List Management.
(line 29)
* stifle_history: History List Management.
(line 38)
* unstifle_history: History List Management.
(line 41)
* using_history: Initializing History and State Management.
(line 11)
* where_history: Information About the History List.
(line 15)
* write_history: Managing the History File.
(line 23)
Tag Table:
Node: Top891
Node: Using History Interactively1536
Node: History Interaction2044
Node: Event Designators3468
Node: Word Designators4610
Node: Modifiers6249
Node: Programming with GNU History7474
Node: Introduction to History8217
Node: History Storage9907
Node: History Functions11042
Node: Initializing History and State Management12031
Node: History List Management12843
Node: Information About the History List14875
Node: Moving Around the History List16372
Node: Searching the History List17373
Node: Managing the History File19305
Node: History Expansion21125
Node: History Variables23034
Node: History Programming Example26066
Node: GNU Free Documentation License28743
Node: Concept Index53934
Node: Function and Variable Index54639
End Tag Table
0707010002ca5e000081a40000000000000000000000015424dff7000140af000001120001001bffffffffffffffff0000002900000000root/usr/local/share/info/rluserman.info This is rluserman.info, produced by makeinfo version 4.13 from
/usr/homes/chet/src/bash/readline-src/doc/rluserman.texi.
This manual describes the end user interface of the GNU Readline Library
(version 6.3, 6 January 2014), a library which aids in the consistency
of user interface across discrete programs which provide a command line
interface.
Copyright (C) 1988-2014 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Libraries
START-INFO-DIR-ENTRY
* RLuserman: (rluserman). The GNU readline library User's Manual.
END-INFO-DIR-ENTRY
File: rluserman.info, Node: Top, Next: Command Line Editing, Up: (dir)
GNU Readline Library
********************
This document describes the end user interface of the GNU Readline
Library, a utility which aids in the consistency of user interface
across discrete programs which provide a command line interface. The
Readline home page is `http://www.gnu.org/software/readline/'.
* Menu:
* Command Line Editing:: GNU Readline User's Manual.
* GNU Free Documentation License:: License for copying this manual.
File: rluserman.info, Node: Command Line Editing, Next: GNU Free Documentation License, Prev: Top, Up: Top
1 Command Line Editing
**********************
This chapter describes the basic features of the GNU command line
editing interface.
* Menu:
* Introduction and Notation:: Notation used in this text.
* Readline Interaction:: The minimum set of commands for editing a line.
* Readline Init File:: Customizing Readline from a user's view.
* Bindable Readline Commands:: A description of most of the Readline commands
available for binding
* Readline vi Mode:: A short description of how to make Readline
behave like the vi editor.
File: rluserman.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
1.1 Introduction to Line Editing
================================
The following paragraphs describe the notation used to represent
keystrokes.
The text `C-k' is read as `Control-K' and describes the character
produced when the key is pressed while the Control key is depressed.
The text `M-k' is read as `Meta-K' and describes the character
produced when the Meta key (if you have one) is depressed, and the
key is pressed. The Meta key is labeled on many keyboards. On
keyboards with two keys labeled (usually to either side of the
space bar), the on the left side is generally set to work as a
Meta key. The key on the right may also be configured to work as
a Meta key or may be configured as some other modifier, such as a
Compose key for typing accented characters.
If you do not have a Meta or key, or another key working as a
Meta key, the identical keystroke can be generated by typing
_first_, and then typing . Either process is known as "metafying"
the key.
The text `M-C-k' is read as `Meta-Control-k' and describes the
character produced by "metafying" `C-k'.
In addition, several keys have their own names. Specifically,
, , , , , and all stand for themselves
when seen in this text, or in an init file (*note Readline Init File::).
If your keyboard lacks a key, typing will produce the
desired character. The key may be labeled or on
some keyboards.
File: rluserman.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
1.2 Readline Interaction
========================
Often during an interactive session you type in a long line of text,
only to notice that the first word on the line is misspelled. The
Readline library gives you a set of commands for manipulating the text
as you type it in, allowing you to just fix your typo, and not forcing
you to retype the majority of the line. Using these editing commands,
you move the cursor to the place that needs correction, and delete or
insert the text of the corrections. Then, when you are satisfied with
the line, you simply press . You do not have to be at the end of
the line to press ; the entire line is accepted regardless of the
location of the cursor within the line.
* Menu:
* Readline Bare Essentials:: The least you need to know about Readline.
* Readline Movement Commands:: Moving about the input line.
* Readline Killing Commands:: How to delete text, and how to get it back!
* Readline Arguments:: Giving numeric arguments to commands.
* Searching:: Searching through previous lines.
File: rluserman.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
1.2.1 Readline Bare Essentials
------------------------------
In order to enter characters into the line, simply type them. The typed
character appears where the cursor was, and then the cursor moves one
space to the right. If you mistype a character, you can use your erase
character to back up and delete the mistyped character.
Sometimes you may mistype a character, and not notice the error
until you have typed several other characters. In that case, you can
type `C-b' to move the cursor to the left, and then correct your
mistake. Afterwards, you can move the cursor to the right with `C-f'.
When you add text in the middle of a line, you will notice that
characters to the right of the cursor are `pushed over' to make room
for the text that you have inserted. Likewise, when you delete text
behind the cursor, characters to the right of the cursor are `pulled
back' to fill in the blank space created by the removal of the text. A
list of the bare essentials for editing the text of an input line
follows.
`C-b'
Move back one character.
`C-f'
Move forward one character.
or
Delete the character to the left of the cursor.
`C-d'
Delete the character underneath the cursor.
Printing characters
Insert the character into the line at the cursor.
`C-_' or `C-x C-u'
Undo the last editing command. You can undo all the way back to an
empty line.
(Depending on your configuration, the key be set to delete
the character to the left of the cursor and the key set to delete
the character underneath the cursor, like `C-d', rather than the
character to the left of the cursor.)
File: rluserman.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
1.2.2 Readline Movement Commands
--------------------------------
The above table describes the most basic keystrokes that you need in
order to do editing of the input line. For your convenience, many
other commands have been added in addition to `C-b', `C-f', `C-d', and
. Here are some commands for moving more rapidly about the line.
`C-a'
Move to the start of the line.
`C-e'
Move to the end of the line.
`M-f'
Move forward a word, where a word is composed of letters and
digits.
`M-b'
Move backward a word.
`C-l'
Clear the screen, reprinting the current line at the top.
Notice how `C-f' moves forward a character, while `M-f' moves
forward a word. It is a loose convention that control keystrokes
operate on characters while meta keystrokes operate on words.
File: rluserman.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
1.2.3 Readline Killing Commands
-------------------------------
"Killing" text means to delete the text from the line, but to save it
away for later use, usually by "yanking" (re-inserting) it back into
the line. (`Cut' and `paste' are more recent jargon for `kill' and
`yank'.)
If the description for a command says that it `kills' text, then you
can be sure that you can get the text back in a different (or the same)
place later.
When you use a kill command, the text is saved in a "kill-ring".
Any number of consecutive kills save all of the killed text together, so
that when you yank it back, you get it all. The kill ring is not line
specific; the text that you killed on a previously typed line is
available to be yanked back later, when you are typing another line.
Here is the list of commands for killing text.
`C-k'
Kill the text from the current cursor position to the end of the
line.
`M-d'
Kill from the cursor to the end of the current word, or, if between
words, to the end of the next word. Word boundaries are the same
as those used by `M-f'.
`M-'
Kill from the cursor the start of the current word, or, if between
words, to the start of the previous word. Word boundaries are the
same as those used by `M-b'.
`C-w'
Kill from the cursor to the previous whitespace. This is
different than `M-' because the word boundaries differ.
Here is how to "yank" the text back into the line. Yanking means to
copy the most-recently-killed text from the kill buffer.
`C-y'
Yank the most recently killed text back into the buffer at the
cursor.
`M-y'
Rotate the kill-ring, and yank the new top. You can only do this
if the prior command is `C-y' or `M-y'.
File: rluserman.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
1.2.4 Readline Arguments
------------------------
You can pass numeric arguments to Readline commands. Sometimes the
argument acts as a repeat count, other times it is the sign of the
argument that is significant. If you pass a negative argument to a
command which normally acts in a forward direction, that command will
act in a backward direction. For example, to kill text back to the
start of the line, you might type `M-- C-k'.
The general way to pass numeric arguments to a command is to type
meta digits before the command. If the first `digit' typed is a minus
sign (`-'), then the sign of the argument will be negative. Once you
have typed one meta digit to get the argument started, you can type the
remainder of the digits, and then the command. For example, to give
the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
will delete the next ten characters on the input line.
File: rluserman.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
1.2.5 Searching for Commands in the History
-------------------------------------------
Readline provides commands for searching through the command history
for lines containing a specified string. There are two search modes:
"incremental" and "non-incremental".
Incremental searches begin before the user has finished typing the
search string. As each character of the search string is typed,
Readline displays the next entry from the history matching the string
typed so far. An incremental search requires only as many characters
as needed to find the desired history entry. To search backward in the
history for a particular string, type `C-r'. Typing `C-s' searches
forward through the history. The characters present in the value of
the `isearch-terminators' variable are used to terminate an incremental
search. If that variable has not been assigned a value, the and
`C-J' characters will terminate an incremental search. `C-g' will
abort an incremental search and restore the original line. When the
search is terminated, the history entry containing the search string
becomes the current line.
To find other matching entries in the history list, type `C-r' or
`C-s' as appropriate. This will search backward or forward in the
history for the next entry matching the search string typed so far.
Any other key sequence bound to a Readline command will terminate the
search and execute that command. For instance, a will terminate
the search and accept the line, thereby executing the command from the
history list. A movement command will terminate the search, make the
last line found the current line, and begin editing.
Readline remembers the last incremental search string. If two
`C-r's are typed without any intervening characters defining a new
search string, any remembered search string is used.
Non-incremental searches read the entire search string before
starting to search for matching history lines. The search string may be
typed by the user or be part of the contents of the current line.
File: rluserman.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
1.3 Readline Init File
======================
Although the Readline library comes with a set of Emacs-like
keybindings installed by default, it is possible to use a different set
of keybindings. Any user can customize programs that use Readline by
putting commands in an "inputrc" file, conventionally in his home
directory. The name of this file is taken from the value of the
environment variable `INPUTRC'. If that variable is unset, the default
is `~/.inputrc'. If that file does not exist or cannot be read, the
ultimate default is `/etc/inputrc'.
When a program which uses the Readline library starts up, the init
file is read, and the key bindings are set.
In addition, the `C-x C-r' command re-reads this init file, thus
incorporating any changes that you might have made to it.
* Menu:
* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
* Sample Init File:: An example inputrc file.
File: rluserman.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
1.3.1 Readline Init File Syntax
-------------------------------
There are only a few basic constructs allowed in the Readline init
file. Blank lines are ignored. Lines beginning with a `#' are
comments. Lines beginning with a `$' indicate conditional constructs
(*note Conditional Init Constructs::). Other lines denote variable
settings and key bindings.
Variable Settings
You can modify the run-time behavior of Readline by altering the
values of variables in Readline using the `set' command within the
init file. The syntax is simple:
set VARIABLE VALUE
Here, for example, is how to change from the default Emacs-like
key binding to use `vi' line editing commands:
set editing-mode vi
Variable names and values, where appropriate, are recognized
without regard to case. Unrecognized variable names are ignored.
Boolean variables (those that can be set to on or off) are set to
on if the value is null or empty, ON (case-insensitive), or 1.
Any other value results in the variable being set to off.
A great deal of run-time behavior is changeable with the following
variables.
`bell-style'
Controls what happens when Readline wants to ring the
terminal bell. If set to `none', Readline never rings the
bell. If set to `visible', Readline uses a visible bell if
one is available. If set to `audible' (the default),
Readline attempts to ring the terminal's bell.
`bind-tty-special-chars'
If set to `on', Readline attempts to bind the control
characters treated specially by the kernel's terminal driver
to their Readline equivalents.
`colored-stats'
If set to `on', Readline displays possible completions using
different colors to indicate their file type. The color
definitions are taken from the value of the `LS_COLORS'
environment variable. The default is `off'.
`comment-begin'
The string to insert at the beginning of the line when the
`insert-comment' command is executed. The default value is
`"#"'.
`completion-display-width'
The number of screen columns used to display possible matches
when performing completion. The value is ignored if it is
less than 0 or greater than the terminal screen width. A
value of 0 will cause matches to be displayed one per line.
The default value is -1.
`completion-ignore-case'
If set to `on', Readline performs filename matching and
completion in a case-insensitive fashion. The default value
is `off'.
`completion-map-case'
If set to `on', and COMPLETION-IGNORE-CASE is enabled,
Readline treats hyphens (`-') and underscores (`_') as
equivalent when performing case-insensitive filename matching
and completion.
`completion-prefix-display-length'
The length in characters of the common prefix of a list of
possible completions that is displayed without modification.
When set to a value greater than zero, common prefixes longer
than this value are replaced with an ellipsis when displaying
possible completions.
`completion-query-items'
The number of possible completions that determines when the
user is asked whether the list of possibilities should be
displayed. If the number of possible completions is greater
than this value, Readline will ask the user whether or not he
wishes to view them; otherwise, they are simply listed. This
variable must be set to an integer value greater than or
equal to 0. A negative value means Readline should never ask.
The default limit is `100'.
`convert-meta'
If set to `on', Readline will convert characters with the
eighth bit set to an ASCII key sequence by stripping the
eighth bit and prefixing an character, converting them
to a meta-prefixed key sequence. The default value is `on'.
`disable-completion'
If set to `On', Readline will inhibit word completion.
Completion characters will be inserted into the line as if
they had been mapped to `self-insert'. The default is `off'.
`editing-mode'
The `editing-mode' variable controls which default set of key
bindings is used. By default, Readline starts up in Emacs
editing mode, where the keystrokes are most similar to Emacs.
This variable can be set to either `emacs' or `vi'.
`echo-control-characters'
When set to `on', on operating systems that indicate they
support it, readline echoes a character corresponding to a
signal generated from the keyboard. The default is `on'.
`enable-keypad'
When set to `on', Readline will try to enable the application
keypad when it is called. Some systems need this to enable
the arrow keys. The default is `off'.
`enable-meta-key'
When set to `on', Readline will try to enable any meta
modifier key the terminal claims to support when it is
called. On many terminals, the meta key is used to send
eight-bit characters. The default is `on'.
`expand-tilde'
If set to `on', tilde expansion is performed when Readline
attempts word completion. The default is `off'.
`history-preserve-point'
If set to `on', the history code attempts to place the point
(the current cursor position) at the same location on each
history line retrieved with `previous-history' or
`next-history'. The default is `off'.
`history-size'
Set the maximum number of history entries saved in the
history list. If set to zero, any existing history entries
are deleted and no new entries are saved. If set to a value
less than zero, the number of history entries is not limited.
By default, the number of history entries is not limited.
`horizontal-scroll-mode'
This variable can be set to either `on' or `off'. Setting it
to `on' means that the text of the lines being edited will
scroll horizontally on a single screen line when they are
longer than the width of the screen, instead of wrapping onto
a new screen line. By default, this variable is set to `off'.
`input-meta'
If set to `on', Readline will enable eight-bit input (it will
not clear the eighth bit in the characters it reads),
regardless of what the terminal claims it can support. The
default value is `off'. The name `meta-flag' is a synonym
for this variable.
`isearch-terminators'
The string of characters that should terminate an incremental
search without subsequently executing the character as a
command (*note Searching::). If this variable has not been
given a value, the characters and `C-J' will terminate
an incremental search.
`keymap'
Sets Readline's idea of the current keymap for key binding
commands. Acceptable `keymap' names are `emacs',
`emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
`vi-command', and `vi-insert'. `vi' is equivalent to
`vi-command'; `emacs' is equivalent to `emacs-standard'. The
default value is `emacs'. The value of the `editing-mode'
variable also affects the default keymap.
`keyseq-timeout'
Specifies the duration Readline will wait for a character
when reading an ambiguous key sequence (one that can form a
complete key sequence using the input read so far, or can
take additional input to complete a longer key sequence). If
no input is received within the timeout, Readline will use
the shorter but complete key sequence. Readline uses this
value to determine whether or not input is available on the
current input source (`rl_instream' by default). The value
is specified in milliseconds, so a value of 1000 means that
Readline will wait one second for additional input. If this
variable is set to a value less than or equal to zero, or to a
non-numeric value, Readline will wait until another key is
pressed to decide which key sequence to complete. The
default value is `500'.
`mark-directories'
If set to `on', completed directory names have a slash
appended. The default is `on'.
`mark-modified-lines'
This variable, when set to `on', causes Readline to display an
asterisk (`*') at the start of history lines which have been
modified. This variable is `off' by default.
`mark-symlinked-directories'
If set to `on', completed names which are symbolic links to
directories have a slash appended (subject to the value of
`mark-directories'). The default is `off'.
`match-hidden-files'
This variable, when set to `on', causes Readline to match
files whose names begin with a `.' (hidden files) when
performing filename completion. If set to `off', the leading
`.' must be supplied by the user in the filename to be
completed. This variable is `on' by default.
`menu-complete-display-prefix'
If set to `on', menu completion displays the common prefix of
the list of possible completions (which may be empty) before
cycling through the list. The default is `off'.
`output-meta'
If set to `on', Readline will display characters with the
eighth bit set directly rather than as a meta-prefixed escape
sequence. The default is `off'.
`page-completions'
If set to `on', Readline uses an internal `more'-like pager
to display a screenful of possible completions at a time.
This variable is `on' by default.
`print-completions-horizontally'
If set to `on', Readline will display completions with matches
sorted horizontally in alphabetical order, rather than down
the screen. The default is `off'.
`revert-all-at-newline'
If set to `on', Readline will undo all changes to history
lines before returning when `accept-line' is executed. By
default, history lines may be modified and retain individual
undo lists across calls to `readline'. The default is `off'.
`show-all-if-ambiguous'
This alters the default behavior of the completion functions.
If set to `on', words which have more than one possible
completion cause the matches to be listed immediately instead
of ringing the bell. The default value is `off'.
`show-all-if-unmodified'
This alters the default behavior of the completion functions
in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
`on', words which have more than one possible completion
without any possible partial completion (the possible
completions don't share a common prefix) cause the matches to
be listed immediately instead of ringing the bell. The
default value is `off'.
`show-mode-in-prompt'
If set to `on', add a character to the beginning of the prompt
indicating the editing mode: emacs (`@'), vi command (`:'),
or vi insertion (`+'). The default value is `off'.
`skip-completed-text'
If set to `on', this alters the default completion behavior
when inserting a single match into the line. It's only
active when performing completion in the middle of a word.
If enabled, readline does not insert characters from the
completion that match characters after point in the word
being completed, so portions of the word following the cursor
are not duplicated. For instance, if this is enabled,
attempting completion when the cursor is after the `e' in
`Makefile' will result in `Makefile' rather than
`Makefilefile', assuming there is a single possible
completion. The default value is `off'.
`visible-stats'
If set to `on', a character denoting a file's type is
appended to the filename when listing possible completions.
The default is `off'.
Key Bindings
The syntax for controlling key bindings in the init file is
simple. First you need to find the name of the command that you
want to change. The following sections contain tables of the
command name, the default keybinding, if any, and a short
description of what the command does.
Once you know the name of the command, simply place on a line in
the init file the name of the key you wish to bind the command to,
a colon, and then the name of the command. There can be no space
between the key name and the colon - that will be interpreted as
part of the key name. The name of the key can be expressed in
different ways, depending on what you find most comfortable.
In addition to command names, readline allows keys to be bound to
a string that is inserted when the key is pressed (a MACRO).
KEYNAME: FUNCTION-NAME or MACRO
KEYNAME is the name of a key spelled out in English. For
example:
Control-u: universal-argument
Meta-Rubout: backward-kill-word
Control-o: "> output"
In the above example, `C-u' is bound to the function
`universal-argument', `M-DEL' is bound to the function
`backward-kill-word', and `C-o' is bound to run the macro
expressed on the right hand side (that is, to insert the text
`> output' into the line).
A number of symbolic character names are recognized while
processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
"KEYSEQ": FUNCTION-NAME or MACRO
KEYSEQ differs from KEYNAME above in that strings denoting an
entire key sequence can be specified, by placing the key
sequence in double quotes. Some GNU Emacs style key escapes
can be used, as in the following example, but the special
character names are not recognized.
"\C-u": universal-argument
"\C-x\C-r": re-read-init-file
"\e[11~": "Function Key 1"
In the above example, `C-u' is again bound to the function
`universal-argument' (just as it was in the first example),
`C-x C-r' is bound to the function `re-read-init-file', and
` <[> <1> <1> <~>' is bound to insert the text `Function
Key 1'.
The following GNU Emacs style escape sequences are available when
specifying key sequences:
`\C-'
control prefix
`\M-'
meta prefix
`\e'
an escape character
`\\'
backslash
`\"'
<">, a double quotation mark
`\''
<'>, a single quote or apostrophe
In addition to the GNU Emacs style escape sequences, a second set
of backslash escapes is available:
`\a'
alert (bell)
`\b'
backspace
`\d'
delete
`\f'
form feed
`\n'
newline
`\r'
carriage return
`\t'
horizontal tab
`\v'
vertical tab
`\NNN'
the eight-bit character whose value is the octal value NNN
(one to three digits)
`\xHH'
the eight-bit character whose value is the hexadecimal value
HH (one or two hex digits)
When entering the text of a macro, single or double quotes must be
used to indicate a macro definition. Unquoted text is assumed to
be a function name. In the macro body, the backslash escapes
described above are expanded. Backslash will quote any other
character in the macro text, including `"' and `''. For example,
the following binding will make `C-x \' insert a single `\' into
the line:
"\C-x\\": "\\"
File: rluserman.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
1.3.2 Conditional Init Constructs
---------------------------------
Readline implements a facility similar in spirit to the conditional
compilation features of the C preprocessor which allows key bindings
and variable settings to be performed as the result of tests. There
are four parser directives used.
`$if'
The `$if' construct allows bindings to be made based on the
editing mode, the terminal being used, or the application using
Readline. The text of the test extends to the end of the line; no
characters are required to isolate it.
`mode'
The `mode=' form of the `$if' directive is used to test
whether Readline is in `emacs' or `vi' mode. This may be
used in conjunction with the `set keymap' command, for
instance, to set bindings in the `emacs-standard' and
`emacs-ctlx' keymaps only if Readline is starting out in
`emacs' mode.
`term'
The `term=' form may be used to include terminal-specific key
bindings, perhaps to bind the key sequences output by the
terminal's function keys. The word on the right side of the
`=' is tested against both the full name of the terminal and
the portion of the terminal name before the first `-'. This
allows `sun' to match both `sun' and `sun-cmd', for instance.
`application'
The APPLICATION construct is used to include
application-specific settings. Each program using the
Readline library sets the APPLICATION NAME, and you can test
for a particular value. This could be used to bind key
sequences to functions useful for a specific program. For
instance, the following command adds a key sequence that
quotes the current or previous word in Bash:
$if Bash
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
$endif
`$endif'
This command, as seen in the previous example, terminates an `$if'
command.
`$else'
Commands in this branch of the `$if' directive are executed if the
test fails.
`$include'
This directive takes a single filename as an argument and reads
commands and bindings from that file. For example, the following
directive reads from `/etc/inputrc':
$include /etc/inputrc
File: rluserman.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
1.3.3 Sample Init File
----------------------
Here is an example of an INPUTRC file. This illustrates key binding,
variable assignment, and conditional syntax.
# This file controls the behaviour of line input editing for
# programs that use the GNU Readline library. Existing
# programs include FTP, Bash, and GDB.
#
# You can re-read the inputrc file with C-x C-r.
# Lines beginning with '#' are comments.
#
# First, include any system-wide bindings and variable
# assignments from /etc/Inputrc
$include /etc/Inputrc
#
# Set various bindings for emacs mode.
set editing-mode emacs
$if mode=emacs
Meta-Control-h: backward-kill-word Text after the function name is ignored
#
# Arrow keys in keypad mode
#
#"\M-OD": backward-char
#"\M-OC": forward-char
#"\M-OA": previous-history
#"\M-OB": next-history
#
# Arrow keys in ANSI mode
#
"\M-[D": backward-char
"\M-[C": forward-char
"\M-[A": previous-history
"\M-[B": next-history
#
# Arrow keys in 8 bit keypad mode
#
#"\M-\C-OD": backward-char
#"\M-\C-OC": forward-char
#"\M-\C-OA": previous-history
#"\M-\C-OB": next-history
#
# Arrow keys in 8 bit ANSI mode
#
#"\M-\C-[D": backward-char
#"\M-\C-[C": forward-char
#"\M-\C-[A": previous-history
#"\M-\C-[B": next-history
C-q: quoted-insert
$endif
# An old-style binding. This happens to be the default.
TAB: complete
# Macros that are convenient for shell interaction
$if Bash
# edit the path
"\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
# prepare to type a quoted word --
# insert open and close double quotes
# and move to just after the open quote
"\C-x\"": "\"\"\C-b"
# insert a backslash (testing backslash escapes
# in sequences and macros)
"\C-x\\": "\\"
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
# Add a binding to refresh the line, which is unbound
"\C-xr": redraw-current-line
# Edit variable on current line.
"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
$endif
# use a visible bell if one is available
set bell-style visible
# don't strip characters to 7 bits when reading
set input-meta on
# allow iso-latin1 characters to be inserted rather
# than converted to prefix-meta sequences
set convert-meta off
# display characters with the eighth bit set directly
# rather than as meta-prefixed characters
set output-meta on
# if there are more than 150 possible completions for
# a word, ask the user if he wants to see all of them
set completion-query-items 150
# For FTP
$if Ftp
"\C-xg": "get \M-?"
"\C-xt": "put \M-?"
"\M-.": yank-last-arg
$endif
File: rluserman.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
1.4 Bindable Readline Commands
==============================
* Menu:
* Commands For Moving:: Moving about the line.
* Commands For History:: Getting at previous lines.
* Commands For Text:: Commands for changing text.
* Commands For Killing:: Commands for killing and yanking.
* Numeric Arguments:: Specifying numeric arguments, repeat counts.
* Commands For Completion:: Getting Readline to do the typing for you.
* Keyboard Macros:: Saving and re-executing typed characters
* Miscellaneous Commands:: Other miscellaneous commands.
This section describes Readline commands that may be bound to key
sequences. Command names without an accompanying key sequence are
unbound by default.
In the following descriptions, "point" refers to the current cursor
position, and "mark" refers to a cursor position saved by the
`set-mark' command. The text between the point and mark is referred to
as the "region".
File: rluserman.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
1.4.1 Commands For Moving
-------------------------
`beginning-of-line (C-a)'
Move to the start of the current line.
`end-of-line (C-e)'
Move to the end of the line.
`forward-char (C-f)'
Move forward a character.
`backward-char (C-b)'
Move back a character.
`forward-word (M-f)'
Move forward to the end of the next word. Words are composed of
letters and digits.
`backward-word (M-b)'
Move back to the start of the current or previous word. Words are
composed of letters and digits.
`clear-screen (C-l)'
Clear the screen and redraw the current line, leaving the current
line at the top of the screen.
`redraw-current-line ()'
Refresh the current line. By default, this is unbound.
File: rluserman.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
1.4.2 Commands For Manipulating The History
-------------------------------------------
`accept-line (Newline or Return)'
Accept the line regardless of where the cursor is. If this line is
non-empty, it may be added to the history list for future recall
with `add_history()'. If this line is a modified history line,
the history line is restored to its original state.
`previous-history (C-p)'
Move `back' through the history list, fetching the previous
command.
`next-history (C-n)'
Move `forward' through the history list, fetching the next command.
`beginning-of-history (M-<)'
Move to the first line in the history.
`end-of-history (M->)'
Move to the end of the input history, i.e., the line currently
being entered.
`reverse-search-history (C-r)'
Search backward starting at the current line and moving `up'
through the history as necessary. This is an incremental search.
`forward-search-history (C-s)'
Search forward starting at the current line and moving `down'
through the the history as necessary. This is an incremental
search.
`non-incremental-reverse-search-history (M-p)'
Search backward starting at the current line and moving `up'
through the history as necessary using a non-incremental search
for a string supplied by the user.
`non-incremental-forward-search-history (M-n)'
Search forward starting at the current line and moving `down'
through the the history as necessary using a non-incremental search
for a string supplied by the user.
`history-search-forward ()'
Search forward through the history for the string of characters
between the start of the current line and the point. The search
string must match at the beginning of a history line. This is a
non-incremental search. By default, this command is unbound.
`history-search-backward ()'
Search backward through the history for the string of characters
between the start of the current line and the point. The search
string must match at the beginning of a history line. This is a
non-incremental search. By default, this command is unbound.
`history-substr-search-forward ()'
Search forward through the history for the string of characters
between the start of the current line and the point. The search
string may match anywhere in a history line. This is a
non-incremental search. By default, this command is unbound.
`history-substr-search-backward ()'
Search backward through the history for the string of characters
between the start of the current line and the point. The search
string may match anywhere in a history line. This is a
non-incremental search. By default, this command is unbound.
`yank-nth-arg (M-C-y)'
Insert the first argument to the previous command (usually the
second word on the previous line) at point. With an argument N,
insert the Nth word from the previous command (the words in the
previous command begin with word 0). A negative argument inserts
the Nth word from the end of the previous command. Once the
argument N is computed, the argument is extracted as if the `!N'
history expansion had been specified.
`yank-last-arg (M-. or M-_)'
Insert last argument to the previous command (the last word of the
previous history entry). With a numeric argument, behave exactly
like `yank-nth-arg'. Successive calls to `yank-last-arg' move
back through the history list, inserting the last word (or the
word specified by the argument to the first call) of each line in
turn. Any numeric argument supplied to these successive calls
determines the direction to move through the history. A negative
argument switches the direction through the history (back or
forward). The history expansion facilities are used to extract
the last argument, as if the `!$' history expansion had been
specified.
File: rluserman.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
1.4.3 Commands For Changing Text
--------------------------------
`end-of-file (usually C-d)'
The character indicating end-of-file as set, for example, by
`stty'. If this character is read when there are no characters on
the line, and point is at the beginning of the line, Readline
interprets it as the end of input and returns EOF.
`delete-char (C-d)'
Delete the character at point. If this function is bound to the
same character as the tty EOF character, as `C-d' commonly is, see
above for the effects.
`backward-delete-char (Rubout)'
Delete the character behind the cursor. A numeric argument means
to kill the characters instead of deleting them.
`forward-backward-delete-char ()'
Delete the character under the cursor, unless the cursor is at the
end of the line, in which case the character behind the cursor is
deleted. By default, this is not bound to a key.
`quoted-insert (C-q or C-v)'
Add the next character typed to the line verbatim. This is how to
insert key sequences like `C-q', for example.
`tab-insert (M-)'
Insert a tab character.
`self-insert (a, b, A, 1, !, ...)'
Insert yourself.
`transpose-chars (C-t)'
Drag the character before the cursor forward over the character at
the cursor, moving the cursor forward as well. If the insertion
point is at the end of the line, then this transposes the last two
characters of the line. Negative arguments have no effect.
`transpose-words (M-t)'
Drag the word before point past the word after point, moving point
past that word as well. If the insertion point is at the end of
the line, this transposes the last two words on the line.
`upcase-word (M-u)'
Uppercase the current (or following) word. With a negative
argument, uppercase the previous word, but do not move the cursor.
`downcase-word (M-l)'
Lowercase the current (or following) word. With a negative
argument, lowercase the previous word, but do not move the cursor.
`capitalize-word (M-c)'
Capitalize the current (or following) word. With a negative
argument, capitalize the previous word, but do not move the cursor.
`overwrite-mode ()'
Toggle overwrite mode. With an explicit positive numeric argument,
switches to overwrite mode. With an explicit non-positive numeric
argument, switches to insert mode. This command affects only
`emacs' mode; `vi' mode does overwrite differently. Each call to
`readline()' starts in insert mode.
In overwrite mode, characters bound to `self-insert' replace the
text at point rather than pushing the text to the right.
Characters bound to `backward-delete-char' replace the character
before point with a space.
By default, this command is unbound.
File: rluserman.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
1.4.4 Killing And Yanking
-------------------------
`kill-line (C-k)'
Kill the text from point to the end of the line.
`backward-kill-line (C-x Rubout)'
Kill backward to the beginning of the line.
`unix-line-discard (C-u)'
Kill backward from the cursor to the beginning of the current line.
`kill-whole-line ()'
Kill all characters on the current line, no matter where point is.
By default, this is unbound.
`kill-word (M-d)'
Kill from point to the end of the current word, or if between
words, to the end of the next word. Word boundaries are the same
as `forward-word'.
`backward-kill-word (M-)'
Kill the word behind point. Word boundaries are the same as
`backward-word'.
`unix-word-rubout (C-w)'
Kill the word behind point, using white space as a word boundary.
The killed text is saved on the kill-ring.
`unix-filename-rubout ()'
Kill the word behind point, using white space and the slash
character as the word boundaries. The killed text is saved on the
kill-ring.
`delete-horizontal-space ()'
Delete all spaces and tabs around point. By default, this is
unbound.
`kill-region ()'
Kill the text in the current region. By default, this command is
unbound.
`copy-region-as-kill ()'
Copy the text in the region to the kill buffer, so it can be yanked
right away. By default, this command is unbound.
`copy-backward-word ()'
Copy the word before point to the kill buffer. The word
boundaries are the same as `backward-word'. By default, this
command is unbound.
`copy-forward-word ()'
Copy the word following point to the kill buffer. The word
boundaries are the same as `forward-word'. By default, this
command is unbound.
`yank (C-y)'
Yank the top of the kill ring into the buffer at point.
`yank-pop (M-y)'
Rotate the kill-ring, and yank the new top. You can only do this
if the prior command is `yank' or `yank-pop'.
File: rluserman.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
1.4.5 Specifying Numeric Arguments
----------------------------------
`digit-argument (M-0, M-1, ... M--)'
Add this digit to the argument already accumulating, or start a new
argument. `M--' starts a negative argument.
`universal-argument ()'
This is another way to specify an argument. If this command is
followed by one or more digits, optionally with a leading minus
sign, those digits define the argument. If the command is
followed by digits, executing `universal-argument' again ends the
numeric argument, but is otherwise ignored. As a special case, if
this command is immediately followed by a character that is
neither a digit or minus sign, the argument count for the next
command is multiplied by four. The argument count is initially
one, so executing this function the first time makes the argument
count four, a second time makes the argument count sixteen, and so
on. By default, this is not bound to a key.
File: rluserman.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
1.4.6 Letting Readline Type For You
-----------------------------------
`complete ()'
Attempt to perform completion on the text before point. The
actual completion performed is application-specific. The default
is filename completion.
`possible-completions (M-?)'
List the possible completions of the text before point. When
displaying completions, Readline sets the number of columns used
for display to the value of `completion-display-width', the value
of the environment variable `COLUMNS', or the screen width, in
that order.
`insert-completions (M-*)'
Insert all completions of the text before point that would have
been generated by `possible-completions'.
`menu-complete ()'
Similar to `complete', but replaces the word to be completed with
a single match from the list of possible completions. Repeated
execution of `menu-complete' steps through the list of possible
completions, inserting each match in turn. At the end of the list
of completions, the bell is rung (subject to the setting of
`bell-style') and the original text is restored. An argument of N
moves N positions forward in the list of matches; a negative
argument may be used to move backward through the list. This
command is intended to be bound to , but is unbound by
default.
`menu-complete-backward ()'
Identical to `menu-complete', but moves backward through the list
of possible completions, as if `menu-complete' had been given a
negative argument.
`delete-char-or-list ()'
Deletes the character under the cursor if not at the beginning or
end of the line (like `delete-char'). If at the end of the line,
behaves identically to `possible-completions'. This command is
unbound by default.
File: rluserman.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
1.4.7 Keyboard Macros
---------------------
`start-kbd-macro (C-x ()'
Begin saving the characters typed into the current keyboard macro.
`end-kbd-macro (C-x ))'
Stop saving the characters typed into the current keyboard macro
and save the definition.
`call-last-kbd-macro (C-x e)'
Re-execute the last keyboard macro defined, by making the
characters in the macro appear as if typed at the keyboard.
`print-last-kbd-macro ()'
Print the last keboard macro defined in a format suitable for the
INPUTRC file.
File: rluserman.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
1.4.8 Some Miscellaneous Commands
---------------------------------
`re-read-init-file (C-x C-r)'
Read in the contents of the INPUTRC file, and incorporate any
bindings or variable assignments found there.
`abort (C-g)'
Abort the current editing command and ring the terminal's bell
(subject to the setting of `bell-style').
`do-uppercase-version (M-a, M-b, M-X, ...)'
If the metafied character X is lowercase, run the command that is
bound to the corresponding uppercase character.
`prefix-meta ()'
Metafy the next character typed. This is for keyboards without a
meta key. Typing ` f' is equivalent to typing `M-f'.
`undo (C-_ or C-x C-u)'
Incremental undo, separately remembered for each line.
`revert-line (M-r)'
Undo all changes made to this line. This is like executing the
`undo' command enough times to get back to the beginning.
`tilde-expand (M-~)'
Perform tilde expansion on the current word.
`set-mark (C-@)'
Set the mark to the point. If a numeric argument is supplied, the
mark is set to that position.
`exchange-point-and-mark (C-x C-x)'
Swap the point with the mark. The current cursor position is set
to the saved position, and the old cursor position is saved as the
mark.
`character-search (C-])'
A character is read and point is moved to the next occurrence of
that character. A negative count searches for previous
occurrences.
`character-search-backward (M-C-])'
A character is read and point is moved to the previous occurrence
of that character. A negative count searches for subsequent
occurrences.
`skip-csi-sequence ()'
Read enough characters to consume a multi-key sequence such as
those defined for keys like Home and End. Such sequences begin
with a Control Sequence Indicator (CSI), usually ESC-[. If this
sequence is bound to "\e[", keys producing such sequences will
have no effect unless explicitly bound to a readline command,
instead of inserting stray characters into the editing buffer.
This is unbound by default, but usually bound to ESC-[.
`insert-comment (M-#)'
Without a numeric argument, the value of the `comment-begin'
variable is inserted at the beginning of the current line. If a
numeric argument is supplied, this command acts as a toggle: if
the characters at the beginning of the line do not match the value
of `comment-begin', the value is inserted, otherwise the
characters in `comment-begin' are deleted from the beginning of
the line. In either case, the line is accepted as if a newline
had been typed.
`dump-functions ()'
Print all of the functions and their key bindings to the Readline
output stream. If a numeric argument is supplied, the output is
formatted in such a way that it can be made part of an INPUTRC
file. This command is unbound by default.
`dump-variables ()'
Print all of the settable variables and their values to the
Readline output stream. If a numeric argument is supplied, the
output is formatted in such a way that it can be made part of an
INPUTRC file. This command is unbound by default.
`dump-macros ()'
Print all of the Readline key sequences bound to macros and the
strings they output. If a numeric argument is supplied, the
output is formatted in such a way that it can be made part of an
INPUTRC file. This command is unbound by default.
`emacs-editing-mode (C-e)'
When in `vi' command mode, this causes a switch to `emacs' editing
mode.
`vi-editing-mode (M-C-j)'
When in `emacs' editing mode, this causes a switch to `vi' editing
mode.
File: rluserman.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
1.5 Readline vi Mode
====================
While the Readline library does not have a full set of `vi' editing
functions, it does contain enough to allow simple editing of the line.
The Readline `vi' mode behaves as specified in the POSIX standard.
In order to switch interactively between `emacs' and `vi' editing
modes, use the command `M-C-j' (bound to emacs-editing-mode when in
`vi' mode and to vi-editing-mode in `emacs' mode). The Readline
default is `emacs' mode.
When you enter a line in `vi' mode, you are already placed in
`insertion' mode, as if you had typed an `i'. Pressing switches
you into `command' mode, where you can edit the text of the line with
the standard `vi' movement keys, move to previous history lines with
`k' and subsequent lines with `j', and so forth.
File: rluserman.info, Node: GNU Free Documentation License, Prev: Command Line Editing, Up: Top
Appendix A GNU Free Documentation License
*****************************************
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
`http://fsf.org/'
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book.
We recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it
can be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
"Document", below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as "you". You
accept the license if you copy, modify or distribute the work in a
way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in
the notice that says that the Document is released under this
License. If a section does not fit the above definition of
Secondary then it is not allowed to be designated as Invariant.
The Document may contain zero Invariant Sections. If the Document
does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images
composed of pixels) generic paint programs or (for drawings) some
widely available drawing editor, and that is suitable for input to
text formatters or for automatic translation to a variety of
formats suitable for input to text formatters. A copy made in an
otherwise Transparent file format whose markup, or absence of
markup, has been arranged to thwart or discourage subsequent
modification by readers is not Transparent. An image format is
not Transparent if used for any substantial amount of text. A
copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and
standard-conforming simple HTML, PostScript or PDF designed for
human modification. Examples of transparent image formats include
PNG, XCF and JPG. Opaque formats include proprietary formats that
can be read and edited only by proprietary word processors, SGML or
XML for which the DTD and/or processing tools are not generally
available, and the machine-generated HTML, PostScript or PDF
produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, "Title
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies
of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
"Acknowledgements", "Dedications", "Endorsements", or "History".)
To "Preserve the Title" of such a section when you modify the
Document means that it remains a section "Entitled XYZ" according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow
the conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the
title equally prominent and visible. You may add other material
on the covers in addition. Copying with changes limited to the
covers, as long as they preserve the title of the Document and
satisfy these conditions, can be treated as verbatim copying in
other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or
state in or with each Opaque copy a computer-network location from
which the general network-using public has access to download
using public-standard network protocols a complete Transparent
copy of the Document, free of added material. If you use the
latter option, you must take reasonably prudent steps, when you
begin distribution of Opaque copies in quantity, to ensure that
this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you
distribute an Opaque copy (directly or through your agents or
retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of
copies, to give them a chance to provide you with an updated
version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with
the Modified Version filling the role of the Document, thus
licensing distribution and modification of the Modified Version to
whoever possesses a copy of it. In addition, you must do these
things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of
previous versions (which should, if there were any, be listed
in the History section of the Document). You may use the
same title as a previous version if the original publisher of
that version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on
the Title Page. If there is no section Entitled "History" in
the Document, create one stating the title, year, authors,
and publisher of the Document as given on its Title Page,
then add an item describing the Modified Version as stated in
the previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in
the "History" section. You may omit a network location for a
work that was published at least four years before the
Document itself, or if the original publisher of the version
it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the
section all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section
titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this,
add their titles to the list of Invariant Sections in the Modified
Version's license notice. These titles must be distinct from any
other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end
of the list of Cover Texts in the Modified Version. Only one
passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the
Document already includes a cover text for the same cover,
previously added by you or by arrangement made by the same entity
you are acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination
all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one section
Entitled "History"; likewise combine any sections Entitled
"Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the
documents in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow
this License in all other respects regarding verbatim copying of
that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of
a storage or distribution medium, is called an "aggregate" if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual
works permit. When the Document is included in an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document's Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void,
and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly
and finally terminates your license, and (b) permanently, if the
copyright holder fails to notify you of the violation by some
reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from
that copyright holder, and you cure the violation prior to 30 days
after your receipt of the notice.
Termination of your rights under this section does not terminate
the licenses of parties who have received copies or rights from
you under this License. If your rights have been terminated and
not permanently reinstated, receipt of a copy of some or all of
the same material does not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
`http://www.gnu.org/copyleft/'.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License "or any later version" applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If
the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by the
Free Software Foundation. If the Document specifies that a proxy
can decide which future versions of this License can be used, that
proxy's public statement of acceptance of a version permanently
authorizes you to choose that version for the Document.
11. RELICENSING
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server.
A "Massive Multiauthor Collaboration" (or "MMC") contained in the
site means any set of copyrightable works thus published on the MMC
site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this
License somewhere other than this MMC, and subsequently
incorporated in whole or in part into the MMC, (1) had no cover
texts or invariant sections, and (2) were thus incorporated prior
to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the
site under CC-BY-SA on the same site at any time before August 1,
2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
====================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.
Tag Table:
Node: Top950
Node: Command Line Editing1472
Node: Introduction and Notation2126
Node: Readline Interaction3750
Node: Readline Bare Essentials4943
Node: Readline Movement Commands6734
Node: Readline Killing Commands7701
Node: Readline Arguments9623
Node: Searching10669
Node: Readline Init File12822
Node: Readline Init File Syntax13977
Node: Conditional Init Constructs30683
Node: Sample Init File33218
Node: Bindable Readline Commands36338
Node: Commands For Moving37397
Node: Commands For History38260
Node: Commands For Text42416
Node: Commands For Killing45400
Node: Numeric Arguments47544
Node: Commands For Completion48685
Node: Keyboard Macros50656
Node: Miscellaneous Commands51346
Node: Readline vi Mode55204
Node: GNU Free Documentation License56118
End Tag Table
0707010002ca4f000041ed0000000000000000000000025424e06e00000000000001120001001bffffffffffffffff0000001300000000root/usr/local/lib 0707010002ca50000081a40000000000000000000000015424dff70000cd94000001120001001bffffffffffffffff0000002000000000root/usr/local/lib/libhistory.a !
/ 1411702772 0 0 0 1496 `
C &$ &$ &$ &$ &$ &$ &$ &$ &$ &$ &$ u u u u u u t t t t | | | | | history_get_history_state history_offset history_length history_set_history_state using_history history_total_bytes where_history history_set_pos history_list current_history previous_history next_history history_get history_base alloc_history_entry history_get_time add_history history_max_entries free_history_entry add_history_time copy_history_entry replace_history_entry replace_history_data remove_history stifle_history max_input_history unstifle_history history_is_stifled clear_history get_history_event history_expansion_char history_expand history_subst_char history_comment_char history_word_delimiters history_no_expand_chars history_inhibit_expansion_function history_quotes_inhibit_expansion history_arg_extract history_tokenize read_history read_history_range history_truncate_file history_write_timestamps append_history write_history history_search history_search_prefix history_search_pos history_search_delimiter_chars sh_single_quote sh_set_lines_and_columns sh_get_env_value sh_get_home_dir sh_unset_nodelay_mode _rl_adjust_point _rl_get_char_len _rl_compare_chars _rl_is_mbchar_matched _rl_char_value rl_byte_oriented _rl_find_next_mbchar _rl_find_prev_mbchar _rl_utf8locale xmalloc xrealloc xfree history.o/ 1411702771 0 0 100644 8140 `
ELF 4 ( .strtab .text .annotate .bss .data .rodata .tbss .tdata .rodata1 .comment .debug_info .debug_line .debug_abbrev .symtab history.c the_history history_size history_stifled hist_inittime Bbss.bss Ddata.data Drodata.rodata Ttbss.bss Ttdata.data history_get_history_state xmalloc history_offset history_length history_set_history_state using_history history_total_bytes strlen where_history history_set_pos history_list current_history previous_history next_history history_get history_base alloc_history_entry strcpy history_get_time history_comment_char strtol time snprintf add_history history_max_entries free_history_entry xrealloc add_history_time free xfree copy_history_entry replace_history_entry replace_history_data remove_history stifle_history max_input_history unstifle_history history_is_stifled clear_history .rel.text .rel.annotate .rel.debug_info Uj jEE P E PE PE PE@ tEPEPEEEÐUE@ E@ E@ E@ E@ t
ÐU ÐU]E EE toU t_U j @ P؋U j @PUЉUE@E tU uEEE]ÐU EEÐUE; E |
u E E E EÐU EEÐU ; t
uE EEEEÐU t H E E EEEÐU ; u E @ EEEEÐUE+ EE; }E |
u E U EEEEÐUj jEE t/j EPj @PЋEPREEEEUP E@ EUPEEEÐUE tE@ uE @E@EEP ;t E Ej
j @PEEEEÐULj j Ej j EPh j?EPj EPj @PЍEPRE UB EEEÐU] ; u| u* @ t j @ PE E; }*U ]
DE@EE; |֡ @ u2 2 j P H H;u- 2 P P @ WPEPE ML]ÐUE t
}a DEE@ tEj @Pj EPj @PЋEPRЋEPÐUE u
E VE@ tEj @ PE@ tEj @PE@Ej EPEEEÐUE uEE Ej @ PEE@ t5Ej @Pj @PЋE@PRE
E@EEEEUPEU@BEEEÐUE |E; |E j jEU Ej EPj @PЋEPRЋEP EUPEj @Pj @PЋE@PRЋEPU MEEEÐUE|E; } t
u E |0U EE tE@;Eu EUP EE E; }OU EE u%E@;EuEEEu EUPE@EE; |EuE |U EEUPÐU]E |E; } t
uE ]U EEEE; }*U ]
DE@EE; |֡ H EEE]ÐU]E }E ;E E +EEE;E}%U j PE@EE;E|ۋE E +EEE;E}3U ]
E@EEEE@EE;E|͋U E E E ]ÐU t E
؉EEÐU EEÐUE E; }7U j PU E@EE; | anotate < , s D I @ @ D D @ D 0 D P D D B D C D @ Q D y D 0 g D t D b @ } @ r D D P D 0 @ @
D
@ 3 D 0 D P e @ X%lu acomp: Sun C 5.12 SunOS_i386 2011/11/16 as: Sun Compiler Common 12.3 SunOS_i386 2011/11/16 history.c /var/tmp/readline-6.3 /opt/solarisstudio12.3/prod/bin/cc -c -DHAVE_CONFIG_H -I. -I. -DRL_LIBRARY_VERSION='"6.3"' -I/usr/local/include history.c Xa;R=Sun C 5.12 SunOS_i386 2011/11/16;backend;raw;cd; DBG_GEN 5.3.3 #
history.c DD% y t
s ! 0 ? I Y g { @ 0 P D B C @ Q y 0 g 5 < A J b V j r } } P 0 @
3 ! 0 4 P e * 6 B N ` ' 4 D R _ m 7 W ] d z
K &