1 @comment %**start of header (This is for running Texinfo on a region.)
2 @setfilename rltech.info
3 @comment %**end of header (This is for running Texinfo on a region.)
7 This document describes the GNU Readline Library, a utility for aiding
8 in the consistency of user interface across discrete programs that need
9 to provide a command line interface.
11 Copyright (C) 1988-2006 Free Software Foundation, Inc.
13 Permission is granted to make and distribute verbatim copies of
14 this manual provided the copyright notice and this permission notice
15 pare preserved on all copies.
18 Permission is granted to process this file through TeX and print the
19 results, provided the printed document carries copying permission
20 notice identical to this one except for the removal of this paragraph
21 (this paragraph not being relevant to the printed manual).
24 Permission is granted to copy and distribute modified versions of this
25 manual under the conditions for verbatim copying, provided that the entire
26 resulting derived work is distributed under the terms of a permission
27 notice identical to this one.
29 Permission is granted to copy and distribute translations of this manual
30 into another language, under the above conditions for modified versions,
31 except that this permission notice may be stated in a translation approved
35 @node Programming with GNU Readline
36 @chapter Programming with GNU Readline
38 This chapter describes the interface between the @sc{gnu} Readline Library and
39 other programs. If you are a programmer, and you wish to include the
40 features found in @sc{gnu} Readline
41 such as completion, line editing, and interactive history manipulation
42 in your own programs, this section is for you.
45 * Basic Behavior:: Using the default behavior of Readline.
46 * Custom Functions:: Adding your own functions to Readline.
47 * Readline Variables:: Variables accessible to custom
49 * Readline Convenience Functions:: Functions which Readline supplies to
50 aid in writing your own custom
52 * Readline Signal Handling:: How Readline behaves when it receives signals.
53 * Custom Completers:: Supplanting or supplementing Readline's
58 @section Basic Behavior
60 Many programs provide a command line interface, such as @code{mail},
61 @code{ftp}, and @code{sh}. For such programs, the default behaviour of
62 Readline is sufficient. This section describes how to use Readline in
63 the simplest way possible, perhaps to replace calls in your code to
64 @code{gets()} or @code{fgets()}.
67 @cindex readline, function
69 The function @code{readline()} prints a prompt @var{prompt}
70 and then reads and returns a single line of text from the user.
71 If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed.
72 The line @code{readline} returns is allocated with @code{malloc()};
73 the caller should @code{free()} the line when it has finished with it.
74 The declaration for @code{readline} in ANSI C is
77 @code{char *readline (const char *@var{prompt});}
83 @code{char *line = readline ("Enter a line: ");}
86 in order to read a line of text from the user.
87 The line returned has the final newline removed, so only the
90 If @code{readline} encounters an @code{EOF} while reading the line, and the
91 line is empty at that point, then @code{(char *)NULL} is returned.
92 Otherwise, the line is ended just as if a newline had been typed.
94 If you want the user to be able to get at the line later, (with
95 @key{C-p} for example), you must call @code{add_history()} to save the
96 line away in a @dfn{history} list of such lines.
99 @code{add_history (line)};
103 For full details on the GNU History Library, see the associated manual.
105 It is preferable to avoid saving empty lines on the history list, since
106 users rarely have a burning need to reuse a blank line. Here is
107 a function which usefully replaces the standard @code{gets()} library
108 function, and has the advantage of no static buffer to overflow:
111 /* A static variable for holding the line. */
112 static char *line_read = (char *)NULL;
114 /* Read a string, and return a pointer to it.
115 Returns NULL on EOF. */
119 /* If the buffer has already been allocated,
120 return the memory to the free pool. */
124 line_read = (char *)NULL;
127 /* Get a line from the user. */
128 line_read = readline ("");
130 /* If the line has any text in it,
131 save it on the history. */
132 if (line_read && *line_read)
133 add_history (line_read);
139 This function gives the user the default behaviour of @key{TAB}
140 completion: completion on file names. If you do not want Readline to
141 complete on filenames, you can change the binding of the @key{TAB} key
142 with @code{rl_bind_key()}.
145 @code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});}
148 @code{rl_bind_key()} takes two arguments: @var{key} is the character that
149 you want to bind, and @var{function} is the address of the function to
150 call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()}
151 makes @key{TAB} insert itself.
152 @code{rl_bind_key()} returns non-zero if @var{key} is not a valid
153 ASCII character code (between 0 and 255).
155 Thus, to disable the default @key{TAB} behavior, the following suffices:
157 @code{rl_bind_key ('\t', rl_insert);}
160 This code should be executed once at the start of your program; you
161 might write a function called @code{initialize_readline()} which
162 performs this and other desired initializations, such as installing
163 custom completers (@pxref{Custom Completers}).
165 @node Custom Functions
166 @section Custom Functions
168 Readline provides many functions for manipulating the text of
169 the line, but it isn't possible to anticipate the needs of all
170 programs. This section describes the various functions and variables
171 defined within the Readline library which allow a user program to add
172 customized functionality to Readline.
174 Before declaring any functions that customize Readline's behavior, or
175 using any functionality Readline provides in other code, an
176 application writer should include the file @code{<readline/readline.h>}
177 in any file that uses Readline's features. Since some of the definitions
178 in @code{readline.h} use the @code{stdio} library, the file
179 @code{<stdio.h>} should be included before @code{readline.h}.
181 @code{readline.h} defines a C preprocessor variable that should
182 be treated as an integer, @code{RL_READLINE_VERSION}, which may
183 be used to conditionally compile application code depending on
184 the installed Readline version. The value is a hexadecimal
185 encoding of the major and minor version numbers of the library,
186 of the form 0x@var{MMmm}. @var{MM} is the two-digit major
187 version number; @var{mm} is the two-digit minor version number.
188 For Readline 4.2, for example, the value of
189 @code{RL_READLINE_VERSION} would be @code{0x0402}.
192 * Readline Typedefs:: C declarations to make code readable.
193 * Function Writing:: Variables and calling conventions.
196 @node Readline Typedefs
197 @subsection Readline Typedefs
199 For readabilty, we declare a number of new object types, all pointers
202 The reason for declaring these new types is to make it easier to write
203 code describing pointers to C functions with appropriately prototyped
204 arguments and return values.
206 For instance, say we want to declare a variable @var{func} as a pointer
207 to a function which takes two @code{int} arguments and returns an
208 @code{int} (this is the type of all of the Readline bindable functions).
209 Instead of the classic C declaration
211 @code{int (*func)();}
214 or the ANSI-C style declaration
216 @code{int (*func)(int, int);}
221 @code{rl_command_func_t *func;}
223 The full list of function pointer types available is
226 @item typedef int rl_command_func_t (int, int);
228 @item typedef char *rl_compentry_func_t (const char *, int);
230 @item typedef char **rl_completion_func_t (const char *, int, int);
232 @item typedef char *rl_quote_func_t (char *, int, char *);
234 @item typedef char *rl_dequote_func_t (char *, int);
236 @item typedef int rl_compignore_func_t (char **);
238 @item typedef void rl_compdisp_func_t (char **, int, int);
240 @item typedef int rl_hook_func_t (void);
242 @item typedef int rl_getc_func_t (FILE *);
244 @item typedef int rl_linebuf_func_t (char *, int);
246 @item typedef int rl_intfunc_t (int);
247 @item #define rl_ivoidfunc_t rl_hook_func_t
248 @item typedef int rl_icpfunc_t (char *);
249 @item typedef int rl_icppfunc_t (char **);
251 @item typedef void rl_voidfunc_t (void);
252 @item typedef void rl_vintfunc_t (int);
253 @item typedef void rl_vcpfunc_t (char *);
254 @item typedef void rl_vcppfunc_t (char **);
258 @node Function Writing
259 @subsection Writing a New Function
261 In order to write new functions for Readline, you need to know the
262 calling conventions for keyboard-invoked functions, and the names of the
263 variables that describe the current state of the line read so far.
265 The calling sequence for a command @code{foo} looks like
268 @code{int foo (int count, int key)}
272 where @var{count} is the numeric argument (or 1 if defaulted) and
273 @var{key} is the key that invoked this function.
275 It is completely up to the function as to what should be done with the
276 numeric argument. Some functions use it as a repeat count, some
277 as a flag, and others to choose alternate behavior (refreshing the current
278 line as opposed to refreshing the screen, for example). Some choose to
279 ignore it. In general, if a
280 function uses the numeric argument as a repeat count, it should be able
281 to do something useful with both negative and positive arguments.
282 At the very least, it should be aware that it can be passed a
285 A command function should return 0 if its action completes successfully,
286 and a non-zero value if some error occurs.
287 This is the convention obeyed by all of the builtin Readline bindable
290 @node Readline Variables
291 @section Readline Variables
293 These variables are available to function writers.
295 @deftypevar {char *} rl_line_buffer
296 This is the line gathered so far. You are welcome to modify the
297 contents of the line, but see @ref{Allowing Undoing}. The
298 function @code{rl_extend_line_buffer} is available to increase
299 the memory allocated to @code{rl_line_buffer}.
302 @deftypevar int rl_point
303 The offset of the current cursor position in @code{rl_line_buffer}
307 @deftypevar int rl_end
308 The number of characters present in @code{rl_line_buffer}. When
309 @code{rl_point} is at the end of the line, @code{rl_point} and
310 @code{rl_end} are equal.
313 @deftypevar int rl_mark
314 The @var{mark} (saved position) in the current line. If set, the mark
315 and point define a @emph{region}.
318 @deftypevar int rl_done
319 Setting this to a non-zero value causes Readline to return the current
323 @deftypevar int rl_num_chars_to_read
324 Setting this to a positive value before calling @code{readline()} causes
325 Readline to return after accepting that many characters, rather
326 than reading up to a character bound to @code{accept-line}.
329 @deftypevar int rl_pending_input
330 Setting this to a value makes it the next keystroke read. This is a
331 way to stuff a single character into the input stream.
334 @deftypevar int rl_dispatching
335 Set to a non-zero value if a function is being called from a key binding;
336 zero otherwise. Application functions can test this to discover whether
337 they were called directly or by Readline's dispatching mechanism.
340 @deftypevar int rl_erase_empty_line
341 Setting this to a non-zero value causes Readline to completely erase
342 the current line, including any prompt, any time a newline is typed as
343 the only character on an otherwise-empty line. The cursor is moved to
344 the beginning of the newly-blank line.
347 @deftypevar {char *} rl_prompt
348 The prompt Readline uses. This is set from the argument to
349 @code{readline()}, and should not be assigned to directly.
350 The @code{rl_set_prompt()} function (@pxref{Redisplay}) may
351 be used to modify the prompt string after calling @code{readline()}.
354 @deftypevar {char *} rl_display_prompt
355 The string displayed as the prompt. This is usually identical to
356 @var{rl_prompt}, but may be changed temporarily by functions that
357 use the prompt string as a message area, such as incremental search.
360 @deftypevar int rl_already_prompted
361 If an application wishes to display the prompt itself, rather than have
362 Readline do it the first time @code{readline()} is called, it should set
363 this variable to a non-zero value after displaying the prompt.
364 The prompt must also be passed as the argument to @code{readline()} so
365 the redisplay functions can update the display properly.
366 The calling application is responsible for managing the value; Readline
370 @deftypevar {const char *} rl_library_version
371 The version number of this revision of the library.
374 @deftypevar int rl_readline_version
375 An integer encoding the current version of the library. The encoding is
376 of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
377 number, and @var{mm} is the two-digit minor version number.
378 For example, for Readline-4.2, @code{rl_readline_version} would have the
382 @deftypevar {int} rl_gnu_readline_p
383 Always set to 1, denoting that this is @sc{gnu} readline rather than some
387 @deftypevar {const char *} rl_terminal_name
388 The terminal type, used for initialization. If not set by the application,
389 Readline sets this to the value of the @env{TERM} environment variable
390 the first time it is called.
393 @deftypevar {const char *} rl_readline_name
394 This variable is set to a unique name by each application using Readline.
395 The value allows conditional parsing of the inputrc file
396 (@pxref{Conditional Init Constructs}).
399 @deftypevar {FILE *} rl_instream
400 The stdio stream from which Readline reads input.
401 If @code{NULL}, Readline defaults to @var{stdin}.
404 @deftypevar {FILE *} rl_outstream
405 The stdio stream to which Readline performs output.
406 If @code{NULL}, Readline defaults to @var{stdout}.
409 @deftypevar int rl_prefer_env_winsize
410 If non-zero, Readline gives values found in the @env{LINES} and
411 @env{COLUMNS} environment variables greater precedence than values fetched
412 from the kernel when computing the screen dimensions.
415 @deftypevar {rl_command_func_t *} rl_last_func
416 The address of the last command function Readline executed. May be used to
417 test whether or not a function is being executed twice in succession, for
421 @deftypevar {rl_hook_func_t *} rl_startup_hook
422 If non-zero, this is the address of a function to call just
423 before @code{readline} prints the first prompt.
426 @deftypevar {rl_hook_func_t *} rl_pre_input_hook
427 If non-zero, this is the address of a function to call after
428 the first prompt has been printed and just before @code{readline}
429 starts reading input characters.
432 @deftypevar {rl_hook_func_t *} rl_event_hook
433 If non-zero, this is the address of a function to call periodically
434 when Readline is waiting for terminal input.
435 By default, this will be called at most ten times a second if there
436 is no keyboard input.
439 @deftypevar {rl_getc_func_t *} rl_getc_function
440 If non-zero, Readline will call indirectly through this pointer
441 to get a character from the input stream. By default, it is set to
442 @code{rl_getc}, the default Readline character input function
443 (@pxref{Character Input}).
446 @deftypevar {rl_voidfunc_t *} rl_redisplay_function
447 If non-zero, Readline will call indirectly through this pointer
448 to update the display with the current contents of the editing buffer.
449 By default, it is set to @code{rl_redisplay}, the default Readline
450 redisplay function (@pxref{Redisplay}).
453 @deftypevar {rl_vintfunc_t *} rl_prep_term_function
454 If non-zero, Readline will call indirectly through this pointer
455 to initialize the terminal. The function takes a single argument, an
456 @code{int} flag that says whether or not to use eight-bit characters.
457 By default, this is set to @code{rl_prep_terminal}
458 (@pxref{Terminal Management}).
461 @deftypevar {rl_voidfunc_t *} rl_deprep_term_function
462 If non-zero, Readline will call indirectly through this pointer
463 to reset the terminal. This function should undo the effects of
464 @code{rl_prep_term_function}.
465 By default, this is set to @code{rl_deprep_terminal}
466 (@pxref{Terminal Management}).
469 @deftypevar {Keymap} rl_executing_keymap
470 This variable is set to the keymap (@pxref{Keymaps}) in which the
471 currently executing readline function was found.
474 @deftypevar {Keymap} rl_binding_keymap
475 This variable is set to the keymap (@pxref{Keymaps}) in which the
476 last key binding occurred.
479 @deftypevar {char *} rl_executing_macro
480 This variable is set to the text of any currently-executing macro.
483 @deftypevar {int} rl_readline_state
484 A variable with bit values that encapsulate the current Readline state.
485 A bit is set with the @code{RL_SETSTATE} macro, and unset with the
486 @code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test
487 whether a particular state bit is set. Current state bits include:
491 Readline has not yet been called, nor has it begun to intialize.
492 @item RL_STATE_INITIALIZING
493 Readline is initializing its internal data structures.
494 @item RL_STATE_INITIALIZED
495 Readline has completed its initialization.
496 @item RL_STATE_TERMPREPPED
497 Readline has modified the terminal modes to do its own input and redisplay.
498 @item RL_STATE_READCMD
499 Readline is reading a command from the keyboard.
500 @item RL_STATE_METANEXT
501 Readline is reading more input after reading the meta-prefix character.
502 @item RL_STATE_DISPATCHING
503 Readline is dispatching to a command.
504 @item RL_STATE_MOREINPUT
505 Readline is reading more input while executing an editing command.
506 @item RL_STATE_ISEARCH
507 Readline is performing an incremental history search.
508 @item RL_STATE_NSEARCH
509 Readline is performing a non-incremental history search.
510 @item RL_STATE_SEARCH
511 Readline is searching backward or forward through the history for a string.
512 @item RL_STATE_NUMERICARG
513 Readline is reading a numeric argument.
514 @item RL_STATE_MACROINPUT
515 Readline is currently getting its input from a previously-defined keyboard
517 @item RL_STATE_MACRODEF
518 Readline is currently reading characters defining a keyboard macro.
519 @item RL_STATE_OVERWRITE
520 Readline is in overwrite mode.
521 @item RL_STATE_COMPLETING
522 Readline is performing word completion.
523 @item RL_STATE_SIGHANDLER
524 Readline is currently executing the readline signal handler.
525 @item RL_STATE_UNDOING
526 Readline is performing an undo.
528 Readline has read a key sequence bound to @code{accept-line}
529 and is about to return the line to the caller.
534 @deftypevar {int} rl_explicit_arg
535 Set to a non-zero value if an explicit numeric argument was specified by
536 the user. Only valid in a bindable command function.
539 @deftypevar {int} rl_numeric_arg
540 Set to the value of any numeric argument explicitly specified by the user
541 before executing the current Readline function. Only valid in a bindable
545 @deftypevar {int} rl_editing_mode
546 Set to a value denoting Readline's current editing mode. A value of
547 @var{1} means Readline is currently in emacs mode; @var{0}
548 means that vi mode is active.
552 @node Readline Convenience Functions
553 @section Readline Convenience Functions
556 * Function Naming:: How to give a function you write a name.
557 * Keymaps:: Making keymaps.
558 * Binding Keys:: Changing Keymaps.
559 * Associating Function Names and Bindings:: Translate function names to
561 * Allowing Undoing:: How to make your functions undoable.
562 * Redisplay:: Functions to control line display.
563 * Modifying Text:: Functions to modify @code{rl_line_buffer}.
564 * Character Input:: Functions to read keyboard input.
565 * Terminal Management:: Functions to manage terminal settings.
566 * Utility Functions:: Generally useful functions and hooks.
567 * Miscellaneous Functions:: Functions that don't fall into any category.
568 * Alternate Interface:: Using Readline in a `callback' fashion.
569 * A Readline Example:: An example Readline function.
572 @node Function Naming
573 @subsection Naming a Function
575 The user can dynamically change the bindings of keys while using
576 Readline. This is done by representing the function with a descriptive
577 name. The user is able to type the descriptive name when referring to
578 the function. Thus, in an init file, one might find
581 Meta-Rubout: backward-kill-word
584 This binds the keystroke @key{Meta-Rubout} to the function
585 @emph{descriptively} named @code{backward-kill-word}. You, as the
586 programmer, should bind the functions you write to descriptive names as
587 well. Readline provides a function for doing that:
589 @deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key)
590 Add @var{name} to the list of named functions. Make @var{function} be
591 the function that gets called. If @var{key} is not -1, then bind it to
592 @var{function} using @code{rl_bind_key()}.
595 Using this function alone is sufficient for most applications.
596 It is the recommended way to add a few functions to the default
597 functions that Readline has built in.
598 If you need to do something other than adding a function to Readline,
599 you may need to use the underlying functions described below.
602 @subsection Selecting a Keymap
604 Key bindings take place on a @dfn{keymap}. The keymap is the
605 association between the keys that the user types and the functions that
606 get run. You can make your own keymaps, copy existing keymaps, and tell
607 Readline which keymap to use.
609 @deftypefun Keymap rl_make_bare_keymap (void)
610 Returns a new, empty keymap. The space for the keymap is allocated with
611 @code{malloc()}; the caller should free it by calling
612 @code{rl_discard_keymap()} when done.
615 @deftypefun Keymap rl_copy_keymap (Keymap map)
616 Return a new keymap which is a copy of @var{map}.
619 @deftypefun Keymap rl_make_keymap (void)
620 Return a new keymap with the printing characters bound to rl_insert,
621 the lowercase Meta characters bound to run their equivalents, and
622 the Meta digits bound to produce numeric arguments.
625 @deftypefun void rl_discard_keymap (Keymap keymap)
626 Free the storage associated with @var{keymap}.
629 Readline has several internal keymaps. These functions allow you to
630 change which keymap is active.
632 @deftypefun Keymap rl_get_keymap (void)
633 Returns the currently active keymap.
636 @deftypefun void rl_set_keymap (Keymap keymap)
637 Makes @var{keymap} the currently active keymap.
640 @deftypefun Keymap rl_get_keymap_by_name (const char *name)
641 Return the keymap matching @var{name}. @var{name} is one which would
642 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
645 @deftypefun {char *} rl_get_keymap_name (Keymap keymap)
646 Return the name matching @var{keymap}. @var{name} is one which would
647 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
651 @subsection Binding Keys
653 Key sequences are associate with functions through the keymap.
654 Readline has several internal keymaps: @code{emacs_standard_keymap},
655 @code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
656 @code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
657 @code{emacs_standard_keymap} is the default, and the examples in
658 this manual assume that.
660 Since @code{readline()} installs a set of default key bindings the first
661 time it is called, there is always the danger that a custom binding
662 installed before the first call to @code{readline()} will be overridden.
663 An alternate mechanism is to install custom key bindings in an
664 initialization function assigned to the @code{rl_startup_hook} variable
665 (@pxref{Readline Variables}).
667 These functions manage key bindings.
669 @deftypefun int rl_bind_key (int key, rl_command_func_t *function)
670 Binds @var{key} to @var{function} in the currently active keymap.
671 Returns non-zero in the case of an invalid @var{key}.
674 @deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map)
675 Bind @var{key} to @var{function} in @var{map}.
676 Returns non-zero in the case of an invalid @var{key}.
679 @deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function)
680 Binds @var{key} to @var{function} if it is not already bound in the
681 currently active keymap.
682 Returns non-zero in the case of an invalid @var{key} or if @var{key} is
686 @deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map)
687 Binds @var{key} to @var{function} if it is not already bound in @var{map}.
688 Returns non-zero in the case of an invalid @var{key} or if @var{key} is
692 @deftypefun int rl_unbind_key (int key)
693 Bind @var{key} to the null function in the currently active keymap.
694 Returns non-zero in case of error.
697 @deftypefun int rl_unbind_key_in_map (int key, Keymap map)
698 Bind @var{key} to the null function in @var{map}.
699 Returns non-zero in case of error.
702 @deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map)
703 Unbind all keys that execute @var{function} in @var{map}.
706 @deftypefun int rl_unbind_command_in_map (const char *command, Keymap map)
707 Unbind all keys that are bound to @var{command} in @var{map}.
710 @deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function)
711 Bind the key sequence represented by the string @var{keyseq} to the function
712 @var{function}, beginning in the current keymap.
713 This makes new keymaps as necessary.
714 The return value is non-zero if @var{keyseq} is invalid.
717 @deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
718 Bind the key sequence represented by the string @var{keyseq} to the function
719 @var{function}. This makes new keymaps as necessary.
720 Initial bindings are performed in @var{map}.
721 The return value is non-zero if @var{keyseq} is invalid.
724 @deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map)
725 Equivalent to @code{rl_bind_keyseq_in_map}.
728 @deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function)
729 Binds @var{keyseq} to @var{function} if it is not already bound in the
730 currently active keymap.
731 Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
735 @deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
736 Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}.
737 Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
741 @deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map)
742 Bind the key sequence represented by the string @var{keyseq} to the arbitrary
743 pointer @var{data}. @var{type} says what kind of data is pointed to by
744 @var{data}; this can be a function (@code{ISFUNC}), a macro
745 (@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as
746 necessary. The initial keymap in which to do bindings is @var{map}.
749 @deftypefun int rl_parse_and_bind (char *line)
750 Parse @var{line} as if it had been read from the @code{inputrc} file and
751 perform any key bindings and variable assignments found
752 (@pxref{Readline Init File}).
755 @deftypefun int rl_read_init_file (const char *filename)
756 Read keybindings and variable assignments from @var{filename}
757 (@pxref{Readline Init File}).
760 @node Associating Function Names and Bindings
761 @subsection Associating Function Names and Bindings
763 These functions allow you to find out what keys invoke named functions
764 and the functions invoked by a particular key sequence. You may also
765 associate a new function name with an arbitrary function.
767 @deftypefun {rl_command_func_t *} rl_named_function (const char *name)
768 Return the function with name @var{name}.
771 @deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type)
772 Return the function invoked by @var{keyseq} in keymap @var{map}.
773 If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is
774 not @code{NULL}, the type of the object is returned in the @code{int} variable
775 it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
778 @deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function)
779 Return an array of strings representing the key sequences used to
780 invoke @var{function} in the current keymap.
783 @deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map)
784 Return an array of strings representing the key sequences used to
785 invoke @var{function} in the keymap @var{map}.
788 @deftypefun void rl_function_dumper (int readable)
789 Print the readline function names and the key sequences currently
790 bound to them to @code{rl_outstream}. If @var{readable} is non-zero,
791 the list is formatted in such a way that it can be made part of an
792 @code{inputrc} file and re-read.
795 @deftypefun void rl_list_funmap_names (void)
796 Print the names of all bindable Readline functions to @code{rl_outstream}.
799 @deftypefun {const char **} rl_funmap_names (void)
800 Return a NULL terminated array of known function names. The array is
801 sorted. The array itself is allocated, but not the strings inside. You
802 should free the array, but not the pointers, using @code{free} or
803 @code{rl_free} when you are done.
806 @deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function)
807 Add @var{name} to the list of bindable Readline command names, and make
808 @var{function} the function to be called when @var{name} is invoked.
811 @node Allowing Undoing
812 @subsection Allowing Undoing
814 Supporting the undo command is a painless thing, and makes your
815 functions much more useful. It is certainly easy to try
816 something if you know you can undo it.
818 If your function simply inserts text once, or deletes text once, and
819 uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then
820 undoing is already done for you automatically.
822 If you do multiple insertions or multiple deletions, or any combination
823 of these operations, you should group them together into one operation.
824 This is done with @code{rl_begin_undo_group()} and
825 @code{rl_end_undo_group()}.
827 The types of events that can be undone are:
830 enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
833 Notice that @code{UNDO_DELETE} means to insert some text, and
834 @code{UNDO_INSERT} means to delete some text. That is, the undo code
835 tells what to undo, not how to undo it. @code{UNDO_BEGIN} and
836 @code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and
837 @code{rl_end_undo_group()}.
839 @deftypefun int rl_begin_undo_group (void)
840 Begins saving undo information in a group construct. The undo
841 information usually comes from calls to @code{rl_insert_text()} and
842 @code{rl_delete_text()}, but could be the result of calls to
843 @code{rl_add_undo()}.
846 @deftypefun int rl_end_undo_group (void)
847 Closes the current undo group started with @code{rl_begin_undo_group
848 ()}. There should be one call to @code{rl_end_undo_group()}
849 for each call to @code{rl_begin_undo_group()}.
852 @deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
853 Remember how to undo an event (according to @var{what}). The affected
854 text runs from @var{start} to @var{end}, and encompasses @var{text}.
857 @deftypefun void rl_free_undo_list (void)
858 Free the existing undo list.
861 @deftypefun int rl_do_undo (void)
862 Undo the first thing on the undo list. Returns @code{0} if there was
863 nothing to undo, non-zero if something was undone.
866 Finally, if you neither insert nor delete text, but directly modify the
867 existing text (e.g., change its case), call @code{rl_modifying()}
868 once, just before you modify the text. You must supply the indices of
869 the text range that you are going to modify.
871 @deftypefun int rl_modifying (int start, int end)
872 Tell Readline to save the text between @var{start} and @var{end} as a
873 single undo unit. It is assumed that you will subsequently modify
878 @subsection Redisplay
880 @deftypefun void rl_redisplay (void)
881 Change what's displayed on the screen to reflect the current contents
882 of @code{rl_line_buffer}.
885 @deftypefun int rl_forced_update_display (void)
886 Force the line to be updated and redisplayed, whether or not
887 Readline thinks the screen display is correct.
890 @deftypefun int rl_on_new_line (void)
891 Tell the update functions that we have moved onto a new (empty) line,
892 usually after ouputting a newline.
895 @deftypefun int rl_on_new_line_with_prompt (void)
896 Tell the update functions that we have moved onto a new line, with
897 @var{rl_prompt} already displayed.
898 This could be used by applications that want to output the prompt string
899 themselves, but still need Readline to know the prompt string length for
901 It should be used after setting @var{rl_already_prompted}.
904 @deftypefun int rl_reset_line_state (void)
905 Reset the display state to a clean state and redisplay the current line
906 starting on a new line.
909 @deftypefun int rl_crlf (void)
910 Move the cursor to the start of the next screen line.
913 @deftypefun int rl_show_char (int c)
914 Display character @var{c} on @code{rl_outstream}.
915 If Readline has not been set to display meta characters directly, this
916 will convert meta characters to a meta-prefixed key sequence.
917 This is intended for use by applications which wish to do their own
921 @deftypefun int rl_message (const char *, @dots{})
922 The arguments are a format string as would be supplied to @code{printf},
923 possibly containing conversion specifications such as @samp{%d}, and
924 any additional arguments necessary to satisfy the conversion specifications.
925 The resulting string is displayed in the @dfn{echo area}. The echo area
926 is also used to display numeric arguments and search strings.
927 You should call @code{rl_save_prompt} to save the prompt information
928 before calling this function.
931 @deftypefun int rl_clear_message (void)
932 Clear the message in the echo area. If the prompt was saved with a call to
933 @code{rl_save_prompt} before the last call to @code{rl_message},
934 call @code{rl_restore_prompt} before calling this function.
937 @deftypefun void rl_save_prompt (void)
938 Save the local Readline prompt display state in preparation for
939 displaying a new message in the message area with @code{rl_message()}.
942 @deftypefun void rl_restore_prompt (void)
943 Restore the local Readline prompt display state saved by the most
944 recent call to @code{rl_save_prompt}.
945 if @code{rl_save_prompt} was called to save the prompt before a call
946 to @code{rl_message}, this function should be called before the
947 corresponding call to @code{rl_clear_message}.
950 @deftypefun int rl_expand_prompt (char *prompt)
951 Expand any special character sequences in @var{prompt} and set up the
952 local Readline prompt redisplay variables.
953 This function is called by @code{readline()}. It may also be called to
954 expand the primary prompt if the @code{rl_on_new_line_with_prompt()}
955 function or @code{rl_already_prompted} variable is used.
956 It returns the number of visible characters on the last line of the
957 (possibly multi-line) prompt.
958 Applications may indicate that the prompt contains characters that take
959 up no physical screen space when displayed by bracketing a sequence of
960 such characters with the special markers @code{RL_PROMPT_START_IGNORE}
961 and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}. This may
962 be used to embed terminal-specific escape sequences in prompts.
965 @deftypefun int rl_set_prompt (const char *prompt)
966 Make Readline use @var{prompt} for subsequent redisplay. This calls
967 @code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt}
972 @subsection Modifying Text
974 @deftypefun int rl_insert_text (const char *text)
975 Insert @var{text} into the line at the current cursor position.
976 Returns the number of characters inserted.
979 @deftypefun int rl_delete_text (int start, int end)
980 Delete the text between @var{start} and @var{end} in the current line.
981 Returns the number of characters deleted.
984 @deftypefun {char *} rl_copy_text (int start, int end)
985 Return a copy of the text between @var{start} and @var{end} in
989 @deftypefun int rl_kill_text (int start, int end)
990 Copy the text between @var{start} and @var{end} in the current line
991 to the kill ring, appending or prepending to the last kill if the
992 last command was a kill command. The text is deleted.
993 If @var{start} is less than @var{end},
994 the text is appended, otherwise prepended. If the last command was
995 not a kill, a new kill ring slot is used.
998 @deftypefun int rl_push_macro_input (char *macro)
999 Cause @var{macro} to be inserted into the line, as if it had been invoked
1000 by a key bound to a macro. Not especially useful; use
1001 @code{rl_insert_text()} instead.
1004 @node Character Input
1005 @subsection Character Input
1007 @deftypefun int rl_read_key (void)
1008 Return the next character available from Readline's current input stream.
1009 This handles input inserted into
1010 the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
1011 and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
1012 While waiting for input, this function will call any function assigned to
1013 the @code{rl_event_hook} variable.
1016 @deftypefun int rl_getc (FILE *stream)
1017 Return the next character available from @var{stream}, which is assumed to
1021 @deftypefun int rl_stuff_char (int c)
1022 Insert @var{c} into the Readline input stream. It will be "read"
1023 before Readline attempts to read characters from the terminal with
1024 @code{rl_read_key()}. Up to 512 characters may be pushed back.
1025 @code{rl_stuff_char} returns 1 if the character was successfully inserted;
1029 @deftypefun int rl_execute_next (int c)
1030 Make @var{c} be the next command to be executed when @code{rl_read_key()}
1031 is called. This sets @var{rl_pending_input}.
1034 @deftypefun int rl_clear_pending_input (void)
1035 Unset @var{rl_pending_input}, effectively negating the effect of any
1036 previous call to @code{rl_execute_next()}. This works only if the
1037 pending input has not already been read with @code{rl_read_key()}.
1040 @deftypefun int rl_set_keyboard_input_timeout (int u)
1041 While waiting for keyboard input in @code{rl_read_key()}, Readline will
1042 wait for @var{u} microseconds for input before calling any function
1043 assigned to @code{rl_event_hook}. @var{u} must be greater than or equal
1044 to zero (a zero-length timeout is equivalent to a poll).
1045 The default waiting period is one-tenth of a second.
1046 Returns the old timeout value.
1049 @node Terminal Management
1050 @subsection Terminal Management
1052 @deftypefun void rl_prep_terminal (int meta_flag)
1053 Modify the terminal settings for Readline's use, so @code{readline()}
1054 can read a single character at a time from the keyboard.
1055 The @var{meta_flag} argument should be non-zero if Readline should
1056 read eight-bit input.
1059 @deftypefun void rl_deprep_terminal (void)
1060 Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
1061 the state in which it was before the most recent call to
1062 @code{rl_prep_terminal()}.
1065 @deftypefun void rl_tty_set_default_bindings (Keymap kmap)
1066 Read the operating system's terminal editing characters (as would be
1067 displayed by @code{stty}) to their Readline equivalents.
1068 The bindings are performed in @var{kmap}.
1071 @deftypefun void rl_tty_unset_default_bindings (Keymap kmap)
1072 Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so
1073 that the terminal editing characters are bound to @code{rl_insert}.
1074 The bindings are performed in @var{kmap}.
1077 @deftypefun int rl_reset_terminal (const char *terminal_name)
1078 Reinitialize Readline's idea of the terminal settings using
1079 @var{terminal_name} as the terminal type (e.g., @code{vt100}).
1080 If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
1081 environment variable is used.
1084 @node Utility Functions
1085 @subsection Utility Functions
1087 @deftypefun void rl_free (void *mem)
1088 Deallocate the memory pointed to by @var{mem}. @var{mem} must have been
1089 allocated by @code{malloc}.
1092 @deftypefun void rl_replace_line (const char *text, int clear_undo)
1093 Replace the contents of @code{rl_line_buffer} with @var{text}.
1094 The point and mark are preserved, if possible.
1095 If @var{clear_undo} is non-zero, the undo list associated with the
1096 current line is cleared.
1099 @deftypefun int rl_extend_line_buffer (int len)
1100 Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
1101 characters, possibly reallocating it if necessary.
1104 @deftypefun int rl_initialize (void)
1105 Initialize or re-initialize Readline's internal state.
1106 It's not strictly necessary to call this; @code{readline()} calls it before
1110 @deftypefun int rl_ding (void)
1111 Ring the terminal bell, obeying the setting of @code{bell-style}.
1114 @deftypefun int rl_alphabetic (int c)
1115 Return 1 if @var{c} is an alphabetic character.
1118 @deftypefun void rl_display_match_list (char **matches, int len, int max)
1119 A convenience function for displaying a list of strings in
1120 columnar format on Readline's output stream. @code{matches} is the list
1121 of strings, in argv format, such as a list of completion matches.
1122 @code{len} is the number of strings in @code{matches}, and @code{max}
1123 is the length of the longest string in @code{matches}. This function uses
1124 the setting of @code{print-completions-horizontally} to select how the
1125 matches are displayed (@pxref{Readline Init File Syntax}).
1128 The following are implemented as macros, defined in @code{chardefs.h}.
1129 Applications should refrain from using them.
1131 @deftypefun int _rl_uppercase_p (int c)
1132 Return 1 if @var{c} is an uppercase alphabetic character.
1135 @deftypefun int _rl_lowercase_p (int c)
1136 Return 1 if @var{c} is a lowercase alphabetic character.
1139 @deftypefun int _rl_digit_p (int c)
1140 Return 1 if @var{c} is a numeric character.
1143 @deftypefun int _rl_to_upper (int c)
1144 If @var{c} is a lowercase alphabetic character, return the corresponding
1145 uppercase character.
1148 @deftypefun int _rl_to_lower (int c)
1149 If @var{c} is an uppercase alphabetic character, return the corresponding
1150 lowercase character.
1153 @deftypefun int _rl_digit_value (int c)
1154 If @var{c} is a number, return the value it represents.
1157 @node Miscellaneous Functions
1158 @subsection Miscellaneous Functions
1160 @deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
1161 Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
1162 The binding is performed in @var{map}. When @var{keyseq} is invoked, the
1163 @var{macro} will be inserted into the line. This function is deprecated;
1164 use @code{rl_generic_bind()} instead.
1167 @deftypefun void rl_macro_dumper (int readable)
1168 Print the key sequences bound to macros and their values, using
1169 the current keymap, to @code{rl_outstream}.
1170 If @var{readable} is non-zero, the list is formatted in such a way
1171 that it can be made part of an @code{inputrc} file and re-read.
1174 @deftypefun int rl_variable_bind (const char *variable, const char *value)
1175 Make the Readline variable @var{variable} have @var{value}.
1176 This behaves as if the readline command
1177 @samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
1178 file (@pxref{Readline Init File Syntax}).
1181 @deftypefun {char *} rl_variable_value (const char *variable)
1182 Return a string representing the value of the Readline variable @var{variable}.
1183 For boolean variables, this string is either @samp{on} or @samp{off}.
1186 @deftypefun void rl_variable_dumper (int readable)
1187 Print the readline variable names and their current values
1188 to @code{rl_outstream}.
1189 If @var{readable} is non-zero, the list is formatted in such a way
1190 that it can be made part of an @code{inputrc} file and re-read.
1193 @deftypefun int rl_set_paren_blink_timeout (int u)
1194 Set the time interval (in microseconds) that Readline waits when showing
1195 a balancing character when @code{blink-matching-paren} has been enabled.
1198 @deftypefun {char *} rl_get_termcap (const char *cap)
1199 Retrieve the string value of the termcap capability @var{cap}.
1200 Readline fetches the termcap entry for the current terminal name and
1201 uses those capabilities to move around the screen line and perform other
1202 terminal-specific operations, like erasing a line. Readline does not
1203 use all of a terminal's capabilities, and this function will return
1204 values for only those capabilities Readline uses.
1207 @node Alternate Interface
1208 @subsection Alternate Interface
1210 An alternate interface is available to plain @code{readline()}. Some
1211 applications need to interleave keyboard I/O with file, device, or
1212 window system I/O, typically by using a main loop to @code{select()}
1213 on various file descriptors. To accomodate this need, readline can
1214 also be invoked as a `callback' function from an event loop. There
1215 are functions available to make this easy.
1217 @deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler)
1218 Set up the terminal for readline I/O and display the initial
1219 expanded value of @var{prompt}. Save the value of @var{lhandler} to
1220 use as a function to call when a complete line of input has been entered.
1221 The function takes the text of the line as an argument.
1224 @deftypefun void rl_callback_read_char (void)
1225 Whenever an application determines that keyboard input is available, it
1226 should call @code{rl_callback_read_char()}, which will read the next
1227 character from the current input source.
1228 If that character completes the line, @code{rl_callback_read_char} will
1229 invoke the @var{lhandler} function saved by @code{rl_callback_handler_install}
1230 to process the line.
1231 Before calling the @var{lhandler} function, the terminal settings are
1232 reset to the values they had before calling
1233 @code{rl_callback_handler_install}.
1234 If the @var{lhandler} function returns,
1235 the terminal settings are modified for Readline's use again.
1236 @code{EOF} is indicated by calling @var{lhandler} with a
1240 @deftypefun void rl_callback_handler_remove (void)
1241 Restore the terminal to its initial state and remove the line handler.
1242 This may be called from within a callback as well as independently.
1243 If the @var{lhandler} installed by @code{rl_callback_handler_install}
1244 does not exit the program, either this function or the function referred
1245 to by the value of @code{rl_deprep_term_function} should be called before
1246 the program exits to reset the terminal settings.
1249 @node A Readline Example
1250 @subsection A Readline Example
1252 Here is a function which changes lowercase characters to their uppercase
1253 equivalents, and uppercase characters to lowercase. If
1254 this function was bound to @samp{M-c}, then typing @samp{M-c} would
1255 change the case of the character under point. Typing @samp{M-1 0 M-c}
1256 would change the case of the following 10 characters, leaving the cursor on
1257 the last character changed.
1260 /* Invert the case of the COUNT following characters. */
1262 invert_case_line (count, key)
1265 register int start, end, i;
1269 if (rl_point >= rl_end)
1280 /* Find the end of the range to modify. */
1281 end = start + (count * direction);
1283 /* Force it to be within range. */
1299 /* Tell readline that we are modifying the line,
1300 so it will save the undo information. */
1301 rl_modifying (start, end);
1303 for (i = start; i != end; i++)
1305 if (_rl_uppercase_p (rl_line_buffer[i]))
1306 rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
1307 else if (_rl_lowercase_p (rl_line_buffer[i]))
1308 rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
1310 /* Move point to on top of the last character changed. */
1311 rl_point = (direction == 1) ? end - 1 : start;
1316 @node Readline Signal Handling
1317 @section Readline Signal Handling
1319 Signals are asynchronous events sent to a process by the Unix kernel,
1320 sometimes on behalf of another process. They are intended to indicate
1321 exceptional events, like a user pressing the interrupt key on his terminal,
1322 or a network connection being broken. There is a class of signals that can
1323 be sent to the process currently reading input from the keyboard. Since
1324 Readline changes the terminal attributes when it is called, it needs to
1325 perform special processing when such a signal is received in order to
1326 restore the terminal to a sane state, or provide application writers with
1327 functions to do so manually.
1329 Readline contains an internal signal handler that is installed for a
1330 number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
1331 @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
1332 When one of these signals is received, the signal handler
1333 will reset the terminal attributes to those that were in effect before
1334 @code{readline()} was called, reset the signal handling to what it was
1335 before @code{readline()} was called, and resend the signal to the calling
1337 If and when the calling application's signal handler returns, Readline
1338 will reinitialize the terminal and continue to accept input.
1339 When a @code{SIGINT} is received, the Readline signal handler performs
1340 some additional work, which will cause any partially-entered line to be
1341 aborted (see the description of @code{rl_free_line_state()} below).
1343 There is an additional Readline signal handler, for @code{SIGWINCH}, which
1344 the kernel sends to a process whenever the terminal's size changes (for
1345 example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH}
1346 handler updates Readline's internal screen size information, and then calls
1347 any @code{SIGWINCH} signal handler the calling application has installed.
1348 Readline calls the application's @code{SIGWINCH} signal handler without
1349 resetting the terminal to its original state. If the application's signal
1350 handler does more than update its idea of the terminal size and return (for
1351 example, a @code{longjmp} back to a main processing loop), it @emph{must}
1352 call @code{rl_cleanup_after_signal()} (described below), to restore the
1355 Readline provides two variables that allow application writers to
1356 control whether or not it will catch certain signals and act on them
1357 when they are received. It is important that applications change the
1358 values of these variables only when calling @code{readline()}, not in
1359 a signal handler, so Readline's internal signal state is not corrupted.
1361 @deftypevar int rl_catch_signals
1362 If this variable is non-zero, Readline will install signal handlers for
1363 @code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGALRM},
1364 @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
1366 The default value of @code{rl_catch_signals} is 1.
1369 @deftypevar int rl_catch_sigwinch
1370 If this variable is non-zero, Readline will install a signal handler for
1373 The default value of @code{rl_catch_sigwinch} is 1.
1376 If an application does not wish to have Readline catch any signals, or
1377 to handle signals other than those Readline catches (@code{SIGHUP},
1379 Readline provides convenience functions to do the necessary terminal
1380 and internal state cleanup upon receipt of a signal.
1382 @deftypefun void rl_cleanup_after_signal (void)
1383 This function will reset the state of the terminal to what it was before
1384 @code{readline()} was called, and remove the Readline signal handlers for
1385 all signals, depending on the values of @code{rl_catch_signals} and
1386 @code{rl_catch_sigwinch}.
1389 @deftypefun void rl_free_line_state (void)
1390 This will free any partial state associated with the current input line
1391 (undo information, any partial history entry, any partially-entered
1392 keyboard macro, and any partially-entered numeric argument). This
1393 should be called before @code{rl_cleanup_after_signal()}. The
1394 Readline signal handler for @code{SIGINT} calls this to abort the
1398 @deftypefun void rl_reset_after_signal (void)
1399 This will reinitialize the terminal and reinstall any Readline signal
1400 handlers, depending on the values of @code{rl_catch_signals} and
1401 @code{rl_catch_sigwinch}.
1404 If an application does not wish Readline to catch @code{SIGWINCH}, it may
1405 call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
1406 Readline to update its idea of the terminal size when a @code{SIGWINCH}
1409 @deftypefun void rl_resize_terminal (void)
1410 Update Readline's internal screen size by reading values from the kernel.
1413 @deftypefun void rl_set_screen_size (int rows, int cols)
1414 Set Readline's idea of the terminal size to @var{rows} rows and
1415 @var{cols} columns. If either @var{rows} or @var{columns} is less than
1416 or equal to 0, Readline's idea of that terminal dimension is unchanged.
1419 If an application does not want to install a @code{SIGWINCH} handler, but
1420 is still interested in the screen dimensions, Readline's idea of the screen
1421 size may be queried.
1423 @deftypefun void rl_get_screen_size (int *rows, int *cols)
1424 Return Readline's idea of the terminal's size in the
1425 variables pointed to by the arguments.
1428 @deftypefun void rl_reset_screen_size (void)
1429 Cause Readline to reobtain the screen size and recalculate its dimensions.
1432 The following functions install and remove Readline's signal handlers.
1434 @deftypefun int rl_set_signals (void)
1435 Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
1436 @code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
1437 @code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
1438 @code{rl_catch_signals} and @code{rl_catch_sigwinch}.
1441 @deftypefun int rl_clear_signals (void)
1442 Remove all of the Readline signal handlers installed by
1443 @code{rl_set_signals()}.
1446 @node Custom Completers
1447 @section Custom Completers
1448 @cindex application-specific completion functions
1450 Typically, a program that reads commands from the user has a way of
1451 disambiguating commands and data. If your program is one of these, then
1452 it can provide completion for commands, data, or both.
1453 The following sections describe how your program and Readline
1454 cooperate to provide this service.
1457 * How Completing Works:: The logic used to do completion.
1458 * Completion Functions:: Functions provided by Readline.
1459 * Completion Variables:: Variables which control completion.
1460 * A Short Completion Example:: An example of writing completer subroutines.
1463 @node How Completing Works
1464 @subsection How Completing Works
1466 In order to complete some text, the full list of possible completions
1467 must be available. That is, it is not possible to accurately
1468 expand a partial word without knowing all of the possible words
1469 which make sense in that context. The Readline library provides
1470 the user interface to completion, and two of the most common
1471 completion functions: filename and username. For completing other types
1472 of text, you must write your own completion function. This section
1473 describes exactly what such functions must do, and provides an example.
1475 There are three major functions used to perform completion:
1479 The user-interface function @code{rl_complete()}. This function is
1480 called with the same arguments as other bindable Readline functions:
1481 @var{count} and @var{invoking_key}.
1482 It isolates the word to be completed and calls
1483 @code{rl_completion_matches()} to generate a list of possible completions.
1484 It then either lists the possible completions, inserts the possible
1485 completions, or actually performs the
1486 completion, depending on which behavior is desired.
1489 The internal function @code{rl_completion_matches()} uses an
1490 application-supplied @dfn{generator} function to generate the list of
1491 possible matches, and then returns the array of these matches.
1492 The caller should place the address of its generator function in
1493 @code{rl_completion_entry_function}.
1496 The generator function is called repeatedly from
1497 @code{rl_completion_matches()}, returning a string each time. The
1498 arguments to the generator function are @var{text} and @var{state}.
1499 @var{text} is the partial word to be completed. @var{state} is zero the
1500 first time the function is called, allowing the generator to perform
1501 any necessary initialization, and a positive non-zero integer for
1502 each subsequent call. The generator function returns
1503 @code{(char *)NULL} to inform @code{rl_completion_matches()} that there are
1504 no more possibilities left. Usually the generator function computes the
1505 list of possible completions when @var{state} is zero, and returns them
1506 one at a time on subsequent calls. Each string the generator function
1507 returns as a match must be allocated with @code{malloc()}; Readline
1508 frees the strings when it has finished with them.
1509 Such a generator function is referred to as an
1510 @dfn{application-specific completion function}.
1514 @deftypefun int rl_complete (int ignore, int invoking_key)
1515 Complete the word at or before point. You have supplied the function
1516 that does the initial simple matching selection algorithm (see
1517 @code{rl_completion_matches()}). The default is to do filename completion.
1520 @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1521 This is a pointer to the generator function for
1522 @code{rl_completion_matches()}.
1523 If the value of @code{rl_completion_entry_function} is
1524 @code{NULL} then the default filename generator
1525 function, @code{rl_filename_completion_function()}, is used.
1526 An @dfn{application-specific completion function} is a function whose
1527 address is assigned to @code{rl_completion_entry_function} and whose
1528 return values are used to generate possible completions.
1531 @node Completion Functions
1532 @subsection Completion Functions
1534 Here is the complete list of callable completion functions present in
1537 @deftypefun int rl_complete_internal (int what_to_do)
1538 Complete the word at or before point. @var{what_to_do} says what to do
1539 with the completion. A value of @samp{?} means list the possible
1540 completions. @samp{TAB} means do standard completion. @samp{*} means
1541 insert all of the possible completions. @samp{!} means to display
1542 all of the possible completions, if there is more than one, as well as
1543 performing partial completion. @samp{@@} is similar to @samp{!}, but
1544 possible completions are not listed if the possible completions share
1548 @deftypefun int rl_complete (int ignore, int invoking_key)
1549 Complete the word at or before point. You have supplied the function
1550 that does the initial simple matching selection algorithm (see
1551 @code{rl_completion_matches()} and @code{rl_completion_entry_function}).
1552 The default is to do filename
1553 completion. This calls @code{rl_complete_internal()} with an
1554 argument depending on @var{invoking_key}.
1557 @deftypefun int rl_possible_completions (int count, int invoking_key)
1558 List the possible completions. See description of @code{rl_complete
1559 ()}. This calls @code{rl_complete_internal()} with an argument of
1563 @deftypefun int rl_insert_completions (int count, int invoking_key)
1564 Insert the list of possible completions into the line, deleting the
1565 partially-completed word. See description of @code{rl_complete()}.
1566 This calls @code{rl_complete_internal()} with an argument of @samp{*}.
1569 @deftypefun int rl_completion_mode (rl_command_func_t *cfunc)
1570 Returns the apppriate value to pass to @code{rl_complete_internal()}
1571 depending on whether @var{cfunc} was called twice in succession and
1572 the values of the @code{show-all-if-ambiguous} and
1573 @code{show-all-if-unmodified} variables.
1574 Application-specific completion functions may use this function to present
1575 the same interface as @code{rl_complete()}.
1578 @deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
1579 Returns an array of strings which is a list of completions for
1580 @var{text}. If there are no completions, returns @code{NULL}.
1581 The first entry in the returned array is the substitution for @var{text}.
1582 The remaining entries are the possible completions. The array is
1583 terminated with a @code{NULL} pointer.
1585 @var{entry_func} is a function of two args, and returns a
1586 @code{char *}. The first argument is @var{text}. The second is a
1587 state argument; it is zero on the first call, and non-zero on subsequent
1588 calls. @var{entry_func} returns a @code{NULL} pointer to the caller
1589 when there are no more matches.
1592 @deftypefun {char *} rl_filename_completion_function (const char *text, int state)
1593 A generator function for filename completion in the general case.
1594 @var{text} is a partial filename.
1595 The Bash source is a useful reference for writing application-specific
1596 completion functions (the Bash completion functions call this and other
1597 Readline functions).
1600 @deftypefun {char *} rl_username_completion_function (const char *text, int state)
1601 A completion generator for usernames. @var{text} contains a partial
1602 username preceded by a random character (usually @samp{~}). As with all
1603 completion generators, @var{state} is zero on the first call and non-zero
1604 for subsequent calls.
1607 @node Completion Variables
1608 @subsection Completion Variables
1610 @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1611 A pointer to the generator function for @code{rl_completion_matches()}.
1612 @code{NULL} means to use @code{rl_filename_completion_function()},
1613 the default filename completer.
1616 @deftypevar {rl_completion_func_t *} rl_attempted_completion_function
1617 A pointer to an alternative function to create matches.
1618 The function is called with @var{text}, @var{start}, and @var{end}.
1619 @var{start} and @var{end} are indices in @code{rl_line_buffer} defining
1620 the boundaries of @var{text}, which is a character string.
1621 If this function exists and returns @code{NULL}, or if this variable is
1622 set to @code{NULL}, then @code{rl_complete()} will call the value of
1623 @code{rl_completion_entry_function} to generate matches, otherwise the
1624 array of strings returned will be used.
1625 If this function sets the @code{rl_attempted_completion_over}
1626 variable to a non-zero value, Readline will not perform its default
1627 completion even if this function returns no matches.
1630 @deftypevar {rl_quote_func_t *} rl_filename_quoting_function
1631 A pointer to a function that will quote a filename in an
1632 application-specific fashion. This is called if filename completion is being
1633 attempted and one of the characters in @code{rl_filename_quote_characters}
1634 appears in a completed filename. The function is called with
1635 @var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text}
1636 is the filename to be quoted. The @var{match_type} is either
1637 @code{SINGLE_MATCH}, if there is only one completion match, or
1638 @code{MULT_MATCH}. Some functions use this to decide whether or not to
1639 insert a closing quote character. The @var{quote_pointer} is a pointer
1640 to any opening quote character the user typed. Some functions choose
1641 to reset this character.
1644 @deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function
1645 A pointer to a function that will remove application-specific quoting
1646 characters from a filename before completion is attempted, so those
1647 characters do not interfere with matching the text against names in
1648 the filesystem. It is called with @var{text}, the text of the word
1649 to be dequoted, and @var{quote_char}, which is the quoting character
1650 that delimits the filename (usually @samp{'} or @samp{"}). If
1651 @var{quote_char} is zero, the filename was not in an embedded string.
1654 @deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p
1655 A pointer to a function to call that determines whether or not a specific
1656 character in the line buffer is quoted, according to whatever quoting
1657 mechanism the program calling Readline uses. The function is called with
1658 two arguments: @var{text}, the text of the line, and @var{index}, the
1659 index of the character in the line. It is used to decide whether a
1660 character found in @code{rl_completer_word_break_characters} should be
1661 used to break words for the completer.
1664 @deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function
1665 This function, if defined, is called by the completer when real filename
1666 completion is done, after all the matching names have been generated.
1667 It is passed a @code{NULL} terminated array of matches.
1668 The first element (@code{matches[0]}) is the
1669 maximal substring common to all matches. This function can
1670 re-arrange the list of matches as required, but each element deleted
1671 from the array must be freed.
1674 @deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
1675 This function, if defined, is allowed to modify the directory portion
1676 of filenames Readline completes. It is called with the address of a
1677 string (the current directory name) as an argument, and may modify that string.
1678 If the string is replaced with a new string, the old value should be freed.
1679 Any modified directory name should have a trailing slash.
1680 The modified value will be displayed as part of the completion, replacing
1681 the directory portion of the pathname the user typed.
1682 It returns an integer that should be non-zero if the function modifies
1683 its directory argument.
1684 It could be used to expand symbolic links or shell variables in pathnames.
1685 At the least, even if no other expansion is performed, this function should
1686 remove any quote characters from the directory name, because its result will
1687 be passed directly to @code{opendir()}.
1690 @deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
1691 If non-zero, then this is the address of a function to call when
1692 completing a word would normally display the list of possible matches.
1693 This function is called in lieu of Readline displaying the list.
1694 It takes three arguments:
1695 (@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
1696 where @var{matches} is the array of matching strings,
1697 @var{num_matches} is the number of strings in that array, and
1698 @var{max_length} is the length of the longest string in that array.
1699 Readline provides a convenience function, @code{rl_display_match_list},
1700 that takes care of doing the display to Readline's output stream. That
1701 function may be called from this hook.
1704 @deftypevar {const char *} rl_basic_word_break_characters
1705 The basic list of characters that signal a break between words for the
1706 completer routine. The default value of this variable is the characters
1707 which break words for completion in Bash:
1708 @code{" \t\n\"\\'`@@$><=;|&@{("}.
1711 @deftypevar {const char *} rl_basic_quote_characters
1712 A list of quote characters which can cause a word break.
1715 @deftypevar {const char *} rl_completer_word_break_characters
1716 The list of characters that signal a break between words for
1717 @code{rl_complete_internal()}. The default list is the value of
1718 @code{rl_basic_word_break_characters}.
1721 @deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook
1722 If non-zero, this is the address of a function to call when Readline is
1723 deciding where to separate words for word completion. It should return
1724 a character string like @code{rl_completer_word_break_characters} to be
1725 used to perform the current completion. The function may choose to set
1726 @code{rl_completer_word_break_characters} itself. If the function
1727 returns @code{NULL}, @code{rl_completer_word_break_characters} is used.
1730 @deftypevar {const char *} rl_completer_quote_characters
1731 A list of characters which can be used to quote a substring of the line.
1732 Completion occurs on the entire substring, and within the substring
1733 @code{rl_completer_word_break_characters} are treated as any other character,
1734 unless they also appear within this list.
1737 @deftypevar {const char *} rl_filename_quote_characters
1738 A list of characters that cause a filename to be quoted by the completer
1739 when they appear in a completed filename. The default is the null string.
1742 @deftypevar {const char *} rl_special_prefixes
1743 The list of characters that are word break characters, but should be
1744 left in @var{text} when it is passed to the completion function.
1745 Programs can use this to help determine what kind of completing to do.
1746 For instance, Bash sets this variable to "$@@" so that it can complete
1747 shell variables and hostnames.
1750 @deftypevar int rl_completion_query_items
1751 Up to this many items will be displayed in response to a
1752 possible-completions call. After that, readline asks the user if she is sure
1753 she wants to see them all. The default value is 100. A negative value
1754 indicates that Readline should never ask the user.
1757 @deftypevar {int} rl_completion_append_character
1758 When a single completion alternative matches at the end of the command
1759 line, this character is appended to the inserted completion text. The
1760 default is a space character (@samp{ }). Setting this to the null
1761 character (@samp{\0}) prevents anything being appended automatically.
1762 This can be changed in application-specific completion functions to
1763 provide the ``most sensible word separator character'' according to
1764 an application-specific command line syntax specification.
1767 @deftypevar int rl_completion_suppress_append
1768 If non-zero, @var{rl_completion_append_character} is not appended to
1769 matches at the end of the command line, as described above.
1770 It is set to 0 before any application-specific completion function
1771 is called, and may only be changed within such a function.
1774 @deftypevar int rl_completion_quote_character
1775 When Readline is completing quoted text, as delimited by one of the
1776 characters in @var{rl_completer_quote_characters}, it sets this variable
1777 to the quoting character found.
1778 This is set before any application-specific completion function is called.
1781 @deftypevar int rl_completion_suppress_quote
1782 If non-zero, Readline does not append a matching quote character when
1783 performing completion on a quoted string.
1784 It is set to 0 before any application-specific completion function
1785 is called, and may only be changed within such a function.
1788 @deftypevar int rl_completion_found_quote
1789 When Readline is completing quoted text, it sets this variable
1790 to a non-zero value if the word being completed contains or is delimited
1791 by any quoting characters, including backslashes.
1792 This is set before any application-specific completion function is called.
1795 @deftypevar int rl_completion_mark_symlink_dirs
1796 If non-zero, a slash will be appended to completed filenames that are
1797 symbolic links to directory names, subject to the value of the
1798 user-settable @var{mark-directories} variable.
1799 This variable exists so that application-specific completion functions
1800 can override the user's global preference (set via the
1801 @var{mark-symlinked-directories} Readline variable) if appropriate.
1802 This variable is set to the user's preference before any
1803 application-specific completion function is called, so unless that
1804 function modifies the value, the user's preferences are honored.
1807 @deftypevar int rl_ignore_completion_duplicates
1808 If non-zero, then duplicates in the matches are removed.
1812 @deftypevar int rl_filename_completion_desired
1813 Non-zero means that the results of the matches are to be treated as
1814 filenames. This is @emph{always} zero when completion is attempted,
1815 and can only be changed
1816 within an application-specific completion function. If it is set to a
1817 non-zero value by such a function, directory names have a slash appended
1818 and Readline attempts to quote completed filenames if they contain any
1819 characters in @code{rl_filename_quote_characters} and
1820 @code{rl_filename_quoting_desired} is set to a non-zero value.
1823 @deftypevar int rl_filename_quoting_desired
1824 Non-zero means that the results of the matches are to be quoted using
1825 double quotes (or an application-specific quoting mechanism) if the
1826 completed filename contains any characters in
1827 @code{rl_filename_quote_chars}. This is @emph{always} non-zero
1828 when completion is attempted, and can only be changed within an
1829 application-specific completion function.
1830 The quoting is effected via a call to the function pointed to
1831 by @code{rl_filename_quoting_function}.
1834 @deftypevar int rl_attempted_completion_over
1835 If an application-specific completion function assigned to
1836 @code{rl_attempted_completion_function} sets this variable to a non-zero
1837 value, Readline will not perform its default filename completion even
1838 if the application's completion function returns no matches.
1839 It should be set only by an application's completion function.
1842 @deftypevar int rl_sort_completion_matches
1843 If an application sets this variable to 0, Readline will not sort the
1844 list of completions (which implies that it cannot remove any duplicate
1845 completions). The default value is 1, which means that Readline will
1846 sort the completions and, depending on the value of
1847 @code{rl_ignore_completion_duplicates}, will attempt to remove duplicate
1851 @deftypevar int rl_completion_type
1852 Set to a character describing the type of completion Readline is currently
1853 attempting; see the description of @code{rl_complete_internal()}
1854 (@pxref{Completion Functions}) for the list of characters.
1855 This is set to the appropriate value before any application-specific
1856 completion function is called, allowing such functions to present
1857 the same interface as @code{rl_complete()}.
1860 @deftypevar int rl_completion_invoking_key
1861 Set to the final character in the key sequence that invoked one of the
1862 completion functions that call @code{rl_complete_internal()}. This is
1863 set to the appropriate value before any application-specific completion
1867 @deftypevar int rl_inhibit_completion
1868 If this variable is non-zero, completion is inhibited. The completion
1869 character will be inserted as any other bound to @code{self-insert}.
1872 @node A Short Completion Example
1873 @subsection A Short Completion Example
1875 Here is a small application demonstrating the use of the GNU Readline
1876 library. It is called @code{fileman}, and the source code resides in
1877 @file{examples/fileman.c}. This sample application provides
1878 completion of command names, line editing features, and access to the
1883 /* fileman.c -- A tiny application which demonstrates how to use the
1884 GNU Readline library. This application interactively allows users
1885 to manipulate files and their modes. */
1888 #include <sys/types.h>
1889 #include <sys/file.h>
1890 #include <sys/stat.h>
1891 #include <sys/errno.h>
1893 #include <readline/readline.h>
1894 #include <readline/history.h>
1896 extern char *xmalloc ();
1898 /* The names of functions that actually do the manipulation. */
1899 int com_list __P((char *));
1900 int com_view __P((char *));
1901 int com_rename __P((char *));
1902 int com_stat __P((char *));
1903 int com_pwd __P((char *));
1904 int com_delete __P((char *));
1905 int com_help __P((char *));
1906 int com_cd __P((char *));
1907 int com_quit __P((char *));
1909 /* A structure which contains information on the commands this program
1913 char *name; /* User printable name of the function. */
1914 rl_icpfunc_t *func; /* Function to call to do the job. */
1915 char *doc; /* Documentation for this function. */
1918 COMMAND commands[] = @{
1919 @{ "cd", com_cd, "Change to directory DIR" @},
1920 @{ "delete", com_delete, "Delete FILE" @},
1921 @{ "help", com_help, "Display this text" @},
1922 @{ "?", com_help, "Synonym for `help'" @},
1923 @{ "list", com_list, "List files in DIR" @},
1924 @{ "ls", com_list, "Synonym for `list'" @},
1925 @{ "pwd", com_pwd, "Print the current working directory" @},
1926 @{ "quit", com_quit, "Quit using Fileman" @},
1927 @{ "rename", com_rename, "Rename FILE to NEWNAME" @},
1928 @{ "stat", com_stat, "Print out statistics on FILE" @},
1929 @{ "view", com_view, "View the contents of FILE" @},
1930 @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @}
1933 /* Forward declarations. */
1934 char *stripwhite ();
1935 COMMAND *find_command ();
1937 /* The name of this program, as taken from argv[0]. */
1940 /* When non-zero, this means the user is done using this program. */
1949 r = xmalloc (strlen (s) + 1);
1962 initialize_readline (); /* Bind our completer. */
1964 /* Loop reading and executing lines until the user quits. */
1965 for ( ; done == 0; )
1967 line = readline ("FileMan: ");
1972 /* Remove leading and trailing whitespace from the line.
1973 Then, if there is anything left, add it to the history list
1975 s = stripwhite (line);
1988 /* Execute a command line. */
1997 /* Isolate the command word. */
1999 while (line[i] && whitespace (line[i]))
2003 while (line[i] && !whitespace (line[i]))
2009 command = find_command (word);
2013 fprintf (stderr, "%s: No such command for FileMan.\n", word);
2017 /* Get argument to command, if any. */
2018 while (whitespace (line[i]))
2023 /* Call the function. */
2024 return ((*(command->func)) (word));
2027 /* Look up NAME as the name of a command, and return a pointer to that
2028 command. Return a NULL pointer if NAME isn't a command name. */
2035 for (i = 0; commands[i].name; i++)
2036 if (strcmp (name, commands[i].name) == 0)
2037 return (&commands[i]);
2039 return ((COMMAND *)NULL);
2042 /* Strip whitespace from the start and end of STRING. Return a pointer
2048 register char *s, *t;
2050 for (s = string; whitespace (*s); s++)
2056 t = s + strlen (s) - 1;
2057 while (t > s && whitespace (*t))
2064 /* **************************************************************** */
2066 /* Interface to Readline Completion */
2068 /* **************************************************************** */
2070 char *command_generator __P((const char *, int));
2071 char **fileman_completion __P((const char *, int, int));
2073 /* Tell the GNU Readline library how to complete. We want to try to
2074 complete on command names if this is the first word in the line, or
2075 on filenames if not. */
2076 initialize_readline ()
2078 /* Allow conditional parsing of the ~/.inputrc file. */
2079 rl_readline_name = "FileMan";
2081 /* Tell the completer that we want a crack first. */
2082 rl_attempted_completion_function = fileman_completion;
2085 /* Attempt to complete on the contents of TEXT. START and END
2086 bound the region of rl_line_buffer that contains the word to
2087 complete. TEXT is the word to complete. We can use the entire
2088 contents of rl_line_buffer in case we want to do some simple
2089 parsing. Returnthe array of matches, or NULL if there aren't any. */
2091 fileman_completion (text, start, end)
2097 matches = (char **)NULL;
2099 /* If this word is at the start of the line, then it is a command
2100 to complete. Otherwise it is the name of a file in the current
2103 matches = rl_completion_matches (text, command_generator);
2108 /* Generator function for command completion. STATE lets us
2109 know whether to start from scratch; without any state
2110 (i.e. STATE == 0), then we start at the top of the list. */
2112 command_generator (text, state)
2116 static int list_index, len;
2119 /* If this is a new word to complete, initialize now. This
2120 includes saving the length of TEXT for efficiency, and
2121 initializing the index variable to 0. */
2125 len = strlen (text);
2128 /* Return the next name which partially matches from the
2130 while (name = commands[list_index].name)
2134 if (strncmp (name, text, len) == 0)
2135 return (dupstr(name));
2138 /* If no names matched, then return NULL. */
2139 return ((char *)NULL);
2142 /* **************************************************************** */
2144 /* FileMan Commands */
2146 /* **************************************************************** */
2148 /* String to pass to system (). This is for the LIST, VIEW and RENAME
2150 static char syscom[1024];
2152 /* List the file(s) named in arg. */
2159 sprintf (syscom, "ls -FClg %s", arg);
2160 return (system (syscom));
2166 if (!valid_argument ("view", arg))
2169 sprintf (syscom, "more %s", arg);
2170 return (system (syscom));
2176 too_dangerous ("rename");
2185 if (!valid_argument ("stat", arg))
2188 if (stat (arg, &finfo) == -1)
2194 printf ("Statistics for `%s':\n", arg);
2196 printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
2198 (finfo.st_nlink == 1) ? "" : "s",
2200 (finfo.st_size == 1) ? "" : "s");
2201 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
2202 printf (" Last access at: %s", ctime (&finfo.st_atime));
2203 printf (" Last modified at: %s", ctime (&finfo.st_mtime));
2210 too_dangerous ("delete");
2214 /* Print out help for ARG, or for all of the commands if ARG is
2222 for (i = 0; commands[i].name; i++)
2224 if (!*arg || (strcmp (arg, commands[i].name) == 0))
2226 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
2233 printf ("No commands match `%s'. Possibilties are:\n", arg);
2235 for (i = 0; commands[i].name; i++)
2237 /* Print in six columns. */
2244 printf ("%s\t", commands[i].name);
2254 /* Change to the directory ARG. */
2258 if (chdir (arg) == -1)
2268 /* Print out the current working directory. */
2274 s = getcwd (dir, sizeof(dir) - 1);
2277 printf ("Error getting pwd: %s\n", dir);
2281 printf ("Current directory is %s\n", dir);
2285 /* The user wishes to quit using this program. Just set DONE
2294 /* Function which tells you that you can't do this. */
2295 too_dangerous (caller)
2299 "%s: Too dangerous for me to distribute.\n",
2301 fprintf (stderr, "Write it yourself.\n");
2304 /* Return non-zero if ARG is a valid argument for CALLER,
2305 else print an error message and return zero. */
2307 valid_argument (caller, arg)
2312 fprintf (stderr, "%s: Argument required.\n", caller);