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.) 4 5@ifinfo 6This document describes the GNU Readline Library, a utility for aiding 7in the consistency of user interface across discrete programs that need 8to provide a command line interface. 9 10Copyright (C) 1988--2020 Free Software Foundation, Inc. 11 12Permission is granted to make and distribute verbatim copies of 13this manual provided the copyright notice and this permission notice 14pare preserved on all copies. 15 16@ignore 17Permission is granted to process this file through TeX and print the 18results, provided the printed document carries copying permission 19notice identical to this one except for the removal of this paragraph 20(this paragraph not being relevant to the printed manual). 21@end ignore 22 23Permission is granted to copy and distribute modified versions of this 24manual under the conditions for verbatim copying, provided that the entire 25resulting derived work is distributed under the terms of a permission 26notice identical to this one. 27 28Permission is granted to copy and distribute translations of this manual 29into another language, under the above conditions for modified versions, 30except that this permission notice may be stated in a translation approved 31by the Foundation. 32@end ifinfo 33 34@node Programming with GNU Readline 35@chapter Programming with GNU Readline 36 37This chapter describes the interface between the @sc{gnu} Readline Library and 38other programs. If you are a programmer, and you wish to include the 39features found in @sc{gnu} Readline 40such as completion, line editing, and interactive history manipulation 41in your own programs, this section is for you. 42 43@menu 44* Basic Behavior:: Using the default behavior of Readline. 45* Custom Functions:: Adding your own functions to Readline. 46* Readline Variables:: Variables accessible to custom 47 functions. 48* Readline Convenience Functions:: Functions which Readline supplies to 49 aid in writing your own custom 50 functions. 51* Readline Signal Handling:: How Readline behaves when it receives signals. 52* Custom Completers:: Supplanting or supplementing Readline's 53 completion functions. 54@end menu 55 56@node Basic Behavior 57@section Basic Behavior 58 59Many programs provide a command line interface, such as @code{mail}, 60@code{ftp}, and @code{sh}. For such programs, the default behaviour of 61Readline is sufficient. This section describes how to use Readline in 62the simplest way possible, perhaps to replace calls in your code to 63@code{gets()} or @code{fgets()}. 64 65@findex readline 66@cindex readline, function 67 68The function @code{readline()} prints a prompt @var{prompt} 69and then reads and returns a single line of text from the user. 70If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed. 71The line @code{readline} returns is allocated with @code{malloc()}; 72the caller should @code{free()} the line when it has finished with it. 73The declaration for @code{readline} in ANSI C is 74 75@example 76@code{char *readline (const char *@var{prompt});} 77@end example 78 79@noindent 80So, one might say 81@example 82@code{char *line = readline ("Enter a line: ");} 83@end example 84@noindent 85in order to read a line of text from the user. 86The line returned has the final newline removed, so only the 87text remains. 88 89If @code{readline} encounters an @code{EOF} while reading the line, and the 90line is empty at that point, then @code{(char *)NULL} is returned. 91Otherwise, the line is ended just as if a newline had been typed. 92 93Readline performs some expansion on the @var{prompt} before it is 94displayed on the screen. See the description of @code{rl_expand_prompt} 95(@pxref{Redisplay}) for additional details, especially if @var{prompt} 96will contain characters that do not consume physical screen space when 97displayed. 98 99If you want the user to be able to get at the line later, (with 100@key{C-p} for example), you must call @code{add_history()} to save the 101line away in a @dfn{history} list of such lines. 102 103@example 104@code{add_history (line)}; 105@end example 106 107@noindent 108For full details on the GNU History Library, see the associated manual. 109 110It is preferable to avoid saving empty lines on the history list, since 111users rarely have a burning need to reuse a blank line. Here is 112a function which usefully replaces the standard @code{gets()} library 113function, and has the advantage of no static buffer to overflow: 114 115@example 116/* A static variable for holding the line. */ 117static char *line_read = (char *)NULL; 118 119/* Read a string, and return a pointer to it. 120 Returns NULL on EOF. */ 121char * 122rl_gets () 123@{ 124 /* If the buffer has already been allocated, 125 return the memory to the free pool. */ 126 if (line_read) 127 @{ 128 free (line_read); 129 line_read = (char *)NULL; 130 @} 131 132 /* Get a line from the user. */ 133 line_read = readline (""); 134 135 /* If the line has any text in it, 136 save it on the history. */ 137 if (line_read && *line_read) 138 add_history (line_read); 139 140 return (line_read); 141@} 142@end example 143 144This function gives the user the default behaviour of @key{TAB} 145completion: completion on file names. If you do not want Readline to 146complete on filenames, you can change the binding of the @key{TAB} key 147with @code{rl_bind_key()}. 148 149@example 150@code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});} 151@end example 152 153@code{rl_bind_key()} takes two arguments: @var{key} is the character that 154you want to bind, and @var{function} is the address of the function to 155call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()} 156makes @key{TAB} insert itself. 157@code{rl_bind_key()} returns non-zero if @var{key} is not a valid 158ASCII character code (between 0 and 255). 159 160Thus, to disable the default @key{TAB} behavior, the following suffices: 161@example 162@code{rl_bind_key ('\t', rl_insert);} 163@end example 164 165This code should be executed once at the start of your program; you 166might write a function called @code{initialize_readline()} which 167performs this and other desired initializations, such as installing 168custom completers (@pxref{Custom Completers}). 169 170@node Custom Functions 171@section Custom Functions 172 173Readline provides many functions for manipulating the text of 174the line, but it isn't possible to anticipate the needs of all 175programs. This section describes the various functions and variables 176defined within the Readline library which allow a user program to add 177customized functionality to Readline. 178 179Before declaring any functions that customize Readline's behavior, or 180using any functionality Readline provides in other code, an 181application writer should include the file @code{<readline/readline.h>} 182in any file that uses Readline's features. Since some of the definitions 183in @code{readline.h} use the @code{stdio} library, the file 184@code{<stdio.h>} should be included before @code{readline.h}. 185 186@code{readline.h} defines a C preprocessor variable that should 187be treated as an integer, @code{RL_READLINE_VERSION}, which may 188be used to conditionally compile application code depending on 189the installed Readline version. The value is a hexadecimal 190encoding of the major and minor version numbers of the library, 191of the form 0x@var{MMmm}. @var{MM} is the two-digit major 192version number; @var{mm} is the two-digit minor version number. 193For Readline 4.2, for example, the value of 194@code{RL_READLINE_VERSION} would be @code{0x0402}. 195 196@menu 197* Readline Typedefs:: C declarations to make code readable. 198* Function Writing:: Variables and calling conventions. 199@end menu 200 201@node Readline Typedefs 202@subsection Readline Typedefs 203 204For readability, we declare a number of new object types, all pointers 205to functions. 206 207The reason for declaring these new types is to make it easier to write 208code describing pointers to C functions with appropriately prototyped 209arguments and return values. 210 211For instance, say we want to declare a variable @var{func} as a pointer 212to a function which takes two @code{int} arguments and returns an 213@code{int} (this is the type of all of the Readline bindable functions). 214Instead of the classic C declaration 215 216@code{int (*func)();} 217 218@noindent 219or the ANSI-C style declaration 220 221@code{int (*func)(int, int);} 222 223@noindent 224we may write 225 226@code{rl_command_func_t *func;} 227 228The full list of function pointer types available is 229 230@table @code 231@item typedef int rl_command_func_t (int, int); 232 233@item typedef char *rl_compentry_func_t (const char *, int); 234 235@item typedef char **rl_completion_func_t (const char *, int, int); 236 237@item typedef char *rl_quote_func_t (char *, int, char *); 238 239@item typedef char *rl_dequote_func_t (char *, int); 240 241@item typedef int rl_compignore_func_t (char **); 242 243@item typedef void rl_compdisp_func_t (char **, int, int); 244 245@item typedef int rl_hook_func_t (void); 246 247@item typedef int rl_getc_func_t (FILE *); 248 249@item typedef int rl_linebuf_func_t (char *, int); 250 251@item typedef int rl_intfunc_t (int); 252@item #define rl_ivoidfunc_t rl_hook_func_t 253@item typedef int rl_icpfunc_t (char *); 254@item typedef int rl_icppfunc_t (char **); 255 256@item typedef void rl_voidfunc_t (void); 257@item typedef void rl_vintfunc_t (int); 258@item typedef void rl_vcpfunc_t (char *); 259@item typedef void rl_vcppfunc_t (char **); 260 261@end table 262 263@node Function Writing 264@subsection Writing a New Function 265 266In order to write new functions for Readline, you need to know the 267calling conventions for keyboard-invoked functions, and the names of the 268variables that describe the current state of the line read so far. 269 270The calling sequence for a command @code{foo} looks like 271 272@example 273@code{int foo (int count, int key)} 274@end example 275 276@noindent 277where @var{count} is the numeric argument (or 1 if defaulted) and 278@var{key} is the key that invoked this function. 279 280It is completely up to the function as to what should be done with the 281numeric argument. Some functions use it as a repeat count, some 282as a flag, and others to choose alternate behavior (refreshing the current 283line as opposed to refreshing the screen, for example). Some choose to 284ignore it. In general, if a 285function uses the numeric argument as a repeat count, it should be able 286to do something useful with both negative and positive arguments. 287At the very least, it should be aware that it can be passed a 288negative argument. 289 290A command function should return 0 if its action completes successfully, 291and a value greater than zero if some error occurs. 292This is the convention obeyed by all of the builtin Readline bindable 293command functions. 294 295@node Readline Variables 296@section Readline Variables 297 298These variables are available to function writers. 299 300@deftypevar {char *} rl_line_buffer 301This is the line gathered so far. You are welcome to modify the 302contents of the line, but see @ref{Allowing Undoing}. The 303function @code{rl_extend_line_buffer} is available to increase 304the memory allocated to @code{rl_line_buffer}. 305@end deftypevar 306 307@deftypevar int rl_point 308The offset of the current cursor position in @code{rl_line_buffer} 309(the @emph{point}). 310@end deftypevar 311 312@deftypevar int rl_end 313The number of characters present in @code{rl_line_buffer}. When 314@code{rl_point} is at the end of the line, @code{rl_point} and 315@code{rl_end} are equal. 316@end deftypevar 317 318@deftypevar int rl_mark 319The @var{mark} (saved position) in the current line. If set, the mark 320and point define a @emph{region}. 321@end deftypevar 322 323@deftypevar int rl_done 324Setting this to a non-zero value causes Readline to return the current 325line immediately. 326@end deftypevar 327 328@deftypevar int rl_num_chars_to_read 329Setting this to a positive value before calling @code{readline()} causes 330Readline to return after accepting that many characters, rather 331than reading up to a character bound to @code{accept-line}. 332@end deftypevar 333 334@deftypevar int rl_pending_input 335Setting this to a value makes it the next keystroke read. This is a 336way to stuff a single character into the input stream. 337@end deftypevar 338 339@deftypevar int rl_dispatching 340Set to a non-zero value if a function is being called from a key binding; 341zero otherwise. Application functions can test this to discover whether 342they were called directly or by Readline's dispatching mechanism. 343@end deftypevar 344 345@deftypevar int rl_erase_empty_line 346Setting this to a non-zero value causes Readline to completely erase 347the current line, including any prompt, any time a newline is typed as 348the only character on an otherwise-empty line. The cursor is moved to 349the beginning of the newly-blank line. 350@end deftypevar 351 352@deftypevar {char *} rl_prompt 353The prompt Readline uses. This is set from the argument to 354@code{readline()}, and should not be assigned to directly. 355The @code{rl_set_prompt()} function (@pxref{Redisplay}) may 356be used to modify the prompt string after calling @code{readline()}. 357@end deftypevar 358 359@deftypevar {char *} rl_display_prompt 360The string displayed as the prompt. This is usually identical to 361@var{rl_prompt}, but may be changed temporarily by functions that 362use the prompt string as a message area, such as incremental search. 363@end deftypevar 364 365@deftypevar int rl_already_prompted 366If an application wishes to display the prompt itself, rather than have 367Readline do it the first time @code{readline()} is called, it should set 368this variable to a non-zero value after displaying the prompt. 369The prompt must also be passed as the argument to @code{readline()} so 370the redisplay functions can update the display properly. 371The calling application is responsible for managing the value; Readline 372never sets it. 373@end deftypevar 374 375@deftypevar {const char *} rl_library_version 376The version number of this revision of the library. 377@end deftypevar 378 379@deftypevar int rl_readline_version 380An integer encoding the current version of the library. The encoding is 381of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version 382number, and @var{mm} is the two-digit minor version number. 383For example, for Readline-4.2, @code{rl_readline_version} would have the 384value 0x0402. 385@end deftypevar 386 387@deftypevar {int} rl_gnu_readline_p 388Always set to 1, denoting that this is @sc{gnu} readline rather than some 389emulation. 390@end deftypevar 391 392@deftypevar {const char *} rl_terminal_name 393The terminal type, used for initialization. If not set by the application, 394Readline sets this to the value of the @env{TERM} environment variable 395the first time it is called. 396@end deftypevar 397 398@deftypevar {const char *} rl_readline_name 399This variable is set to a unique name by each application using Readline. 400The value allows conditional parsing of the inputrc file 401(@pxref{Conditional Init Constructs}). 402@end deftypevar 403 404@deftypevar {FILE *} rl_instream 405The stdio stream from which Readline reads input. 406If @code{NULL}, Readline defaults to @var{stdin}. 407@end deftypevar 408 409@deftypevar {FILE *} rl_outstream 410The stdio stream to which Readline performs output. 411If @code{NULL}, Readline defaults to @var{stdout}. 412@end deftypevar 413 414@deftypevar int rl_prefer_env_winsize 415If non-zero, Readline gives values found in the @env{LINES} and 416@env{COLUMNS} environment variables greater precedence than values fetched 417from the kernel when computing the screen dimensions. 418@end deftypevar 419 420@deftypevar {rl_command_func_t *} rl_last_func 421The address of the last command function Readline executed. May be used to 422test whether or not a function is being executed twice in succession, for 423example. 424@end deftypevar 425 426@deftypevar {rl_hook_func_t *} rl_startup_hook 427If non-zero, this is the address of a function to call just 428before @code{readline} prints the first prompt. 429@end deftypevar 430 431@deftypevar {rl_hook_func_t *} rl_pre_input_hook 432If non-zero, this is the address of a function to call after 433the first prompt has been printed and just before @code{readline} 434starts reading input characters. 435@end deftypevar 436 437@deftypevar {rl_hook_func_t *} rl_event_hook 438If non-zero, this is the address of a function to call periodically 439when Readline is waiting for terminal input. 440By default, this will be called at most ten times a second if there 441is no keyboard input. 442@end deftypevar 443 444@deftypevar {rl_getc_func_t *} rl_getc_function 445If non-zero, Readline will call indirectly through this pointer 446to get a character from the input stream. By default, it is set to 447@code{rl_getc}, the default Readline character input function 448(@pxref{Character Input}). 449In general, an application that sets @var{rl_getc_function} should consider 450setting @var{rl_input_available_hook} as well. 451@end deftypevar 452 453@deftypevar {rl_hook_func_t *} rl_signal_event_hook 454If non-zero, this is the address of a function to call if a read system 455call is interrupted when Readline is reading terminal input. 456@end deftypevar 457 458@deftypevar {rl_hook_func_t *} rl_input_available_hook 459If non-zero, Readline will use this function's return value when it needs 460to determine whether or not there is available input on the current input 461source. 462The default hook checks @code{rl_instream}; if an application is using a 463different input source, it should set the hook appropriately. 464Readline queries for available input when implementing intra-key-sequence 465timeouts during input and incremental searches. 466This may use an application-specific timeout before returning a value; 467Readline uses the value passed to @code{rl_set_keyboard_input_timeout()} 468or the value of the user-settable @var{keyseq-timeout} variable. 469This is designed for use by applications using Readline's callback interface 470(@pxref{Alternate Interface}), which may not use the traditional 471@code{read(2)} and file descriptor interface, or other applications using 472a different input mechanism. 473If an application uses an input mechanism or hook that can potentially exceed 474the value of @var{keyseq-timeout}, it should increase the timeout or set 475this hook appropriately even when not using the callback interface. 476In general, an application that sets @var{rl_getc_function} should consider 477setting @var{rl_input_available_hook} as well. 478@end deftypevar 479 480@deftypevar {rl_voidfunc_t *} rl_redisplay_function 481If non-zero, Readline will call indirectly through this pointer 482to update the display with the current contents of the editing buffer. 483By default, it is set to @code{rl_redisplay}, the default Readline 484redisplay function (@pxref{Redisplay}). 485@end deftypevar 486 487@deftypevar {rl_vintfunc_t *} rl_prep_term_function 488If non-zero, Readline will call indirectly through this pointer 489to initialize the terminal. The function takes a single argument, an 490@code{int} flag that says whether or not to use eight-bit characters. 491By default, this is set to @code{rl_prep_terminal} 492(@pxref{Terminal Management}). 493@end deftypevar 494 495@deftypevar {rl_voidfunc_t *} rl_deprep_term_function 496If non-zero, Readline will call indirectly through this pointer 497to reset the terminal. This function should undo the effects of 498@code{rl_prep_term_function}. 499By default, this is set to @code{rl_deprep_terminal} 500(@pxref{Terminal Management}). 501@end deftypevar 502 503@deftypevar {Keymap} rl_executing_keymap 504This variable is set to the keymap (@pxref{Keymaps}) in which the 505currently executing readline function was found. 506@end deftypevar 507 508@deftypevar {Keymap} rl_binding_keymap 509This variable is set to the keymap (@pxref{Keymaps}) in which the 510last key binding occurred. 511@end deftypevar 512 513@deftypevar {char *} rl_executing_macro 514This variable is set to the text of any currently-executing macro. 515@end deftypevar 516 517@deftypevar int rl_executing_key 518The key that caused the dispatch to the currently-executing Readline function. 519@end deftypevar 520 521@deftypevar {char *} rl_executing_keyseq 522The full key sequence that caused the dispatch to the currently-executing 523Readline function. 524@end deftypevar 525 526@deftypevar int rl_key_sequence_length 527The number of characters in @var{rl_executing_keyseq}. 528@end deftypevar 529 530@deftypevar {int} rl_readline_state 531A variable with bit values that encapsulate the current Readline state. 532A bit is set with the @code{RL_SETSTATE} macro, and unset with the 533@code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test 534whether a particular state bit is set. Current state bits include: 535 536@table @code 537@item RL_STATE_NONE 538Readline has not yet been called, nor has it begun to initialize. 539@item RL_STATE_INITIALIZING 540Readline is initializing its internal data structures. 541@item RL_STATE_INITIALIZED 542Readline has completed its initialization. 543@item RL_STATE_TERMPREPPED 544Readline has modified the terminal modes to do its own input and redisplay. 545@item RL_STATE_READCMD 546Readline is reading a command from the keyboard. 547@item RL_STATE_METANEXT 548Readline is reading more input after reading the meta-prefix character. 549@item RL_STATE_DISPATCHING 550Readline is dispatching to a command. 551@item RL_STATE_MOREINPUT 552Readline is reading more input while executing an editing command. 553@item RL_STATE_ISEARCH 554Readline is performing an incremental history search. 555@item RL_STATE_NSEARCH 556Readline is performing a non-incremental history search. 557@item RL_STATE_SEARCH 558Readline is searching backward or forward through the history for a string. 559@item RL_STATE_NUMERICARG 560Readline is reading a numeric argument. 561@item RL_STATE_MACROINPUT 562Readline is currently getting its input from a previously-defined keyboard 563macro. 564@item RL_STATE_MACRODEF 565Readline is currently reading characters defining a keyboard macro. 566@item RL_STATE_OVERWRITE 567Readline is in overwrite mode. 568@item RL_STATE_COMPLETING 569Readline is performing word completion. 570@item RL_STATE_SIGHANDLER 571Readline is currently executing the readline signal handler. 572@item RL_STATE_UNDOING 573Readline is performing an undo. 574@item RL_STATE_INPUTPENDING 575Readline has input pending due to a call to @code{rl_execute_next()}. 576@item RL_STATE_TTYCSAVED 577Readline has saved the values of the terminal's special characters. 578@item RL_STATE_CALLBACK 579Readline is currently using the alternate (callback) interface 580(@pxref{Alternate Interface}). 581@item RL_STATE_VIMOTION 582Readline is reading the argument to a vi-mode "motion" command. 583@item RL_STATE_MULTIKEY 584Readline is reading a multiple-keystroke command. 585@item RL_STATE_VICMDONCE 586Readline has entered vi command (movement) mode at least one time during 587the current call to @code{readline()}. 588@item RL_STATE_DONE 589Readline has read a key sequence bound to @code{accept-line} 590and is about to return the line to the caller. 591@end table 592 593@end deftypevar 594 595@deftypevar {int} rl_explicit_arg 596Set to a non-zero value if an explicit numeric argument was specified by 597the user. Only valid in a bindable command function. 598@end deftypevar 599 600@deftypevar {int} rl_numeric_arg 601Set to the value of any numeric argument explicitly specified by the user 602before executing the current Readline function. Only valid in a bindable 603command function. 604@end deftypevar 605 606@deftypevar {int} rl_editing_mode 607Set to a value denoting Readline's current editing mode. A value of 608@var{1} means Readline is currently in emacs mode; @var{0} 609means that vi mode is active. 610@end deftypevar 611 612 613@node Readline Convenience Functions 614@section Readline Convenience Functions 615 616@menu 617* Function Naming:: How to give a function you write a name. 618* Keymaps:: Making keymaps. 619* Binding Keys:: Changing Keymaps. 620* Associating Function Names and Bindings:: Translate function names to 621 key sequences. 622* Allowing Undoing:: How to make your functions undoable. 623* Redisplay:: Functions to control line display. 624* Modifying Text:: Functions to modify @code{rl_line_buffer}. 625* Character Input:: Functions to read keyboard input. 626* Terminal Management:: Functions to manage terminal settings. 627* Utility Functions:: Generally useful functions and hooks. 628* Miscellaneous Functions:: Functions that don't fall into any category. 629* Alternate Interface:: Using Readline in a `callback' fashion. 630* A Readline Example:: An example Readline function. 631* Alternate Interface Example:: An example program using the alternate interface. 632@end menu 633 634@node Function Naming 635@subsection Naming a Function 636 637The user can dynamically change the bindings of keys while using 638Readline. This is done by representing the function with a descriptive 639name. The user is able to type the descriptive name when referring to 640the function. Thus, in an init file, one might find 641 642@example 643Meta-Rubout: backward-kill-word 644@end example 645 646This binds the keystroke @key{Meta-Rubout} to the function 647@emph{descriptively} named @code{backward-kill-word}. You, as the 648programmer, should bind the functions you write to descriptive names as 649well. Readline provides a function for doing that: 650 651@deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key) 652Add @var{name} to the list of named functions. Make @var{function} be 653the function that gets called. If @var{key} is not -1, then bind it to 654@var{function} using @code{rl_bind_key()}. 655@end deftypefun 656 657Using this function alone is sufficient for most applications. 658It is the recommended way to add a few functions to the default 659functions that Readline has built in. 660If you need to do something other than adding a function to Readline, 661you may need to use the underlying functions described below. 662 663@node Keymaps 664@subsection Selecting a Keymap 665 666Key bindings take place on a @dfn{keymap}. The keymap is the 667association between the keys that the user types and the functions that 668get run. You can make your own keymaps, copy existing keymaps, and tell 669Readline which keymap to use. 670 671@deftypefun Keymap rl_make_bare_keymap (void) 672Returns a new, empty keymap. The space for the keymap is allocated with 673@code{malloc()}; the caller should free it by calling 674@code{rl_free_keymap()} when done. 675@end deftypefun 676 677@deftypefun Keymap rl_copy_keymap (Keymap map) 678Return a new keymap which is a copy of @var{map}. 679@end deftypefun 680 681@deftypefun Keymap rl_make_keymap (void) 682Return a new keymap with the printing characters bound to rl_insert, 683the lowercase Meta characters bound to run their equivalents, and 684the Meta digits bound to produce numeric arguments. 685@end deftypefun 686 687@deftypefun void rl_discard_keymap (Keymap keymap) 688Free the storage associated with the data in @var{keymap}. 689The caller should free @var{keymap}. 690@end deftypefun 691 692@deftypefun void rl_free_keymap (Keymap keymap) 693Free all storage associated with @var{keymap}. This calls 694@code{rl_discard_keymap} to free subordindate keymaps and macros. 695@end deftypefun 696 697@deftypefun int rl_empty_keymap (Keymap keymap) 698Return non-zero if there are no keys bound to functions in @var{keymap}; 699zero if there are any keys bound. 700@end deftypefun 701 702Readline has several internal keymaps. These functions allow you to 703change which keymap is active. 704 705@deftypefun Keymap rl_get_keymap (void) 706Returns the currently active keymap. 707@end deftypefun 708 709@deftypefun void rl_set_keymap (Keymap keymap) 710Makes @var{keymap} the currently active keymap. 711@end deftypefun 712 713@deftypefun Keymap rl_get_keymap_by_name (const char *name) 714Return the keymap matching @var{name}. @var{name} is one which would 715be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}). 716@end deftypefun 717 718@deftypefun {char *} rl_get_keymap_name (Keymap keymap) 719Return the name matching @var{keymap}. @var{name} is one which would 720be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}). 721@end deftypefun 722 723@deftypefun int rl_set_keymap_name (const char *name, Keymap keymap) 724Set the name of @var{keymap}. This name will then be "registered" and 725available for use in a @code{set keymap} inputrc directive 726@pxref{Readline Init File}). 727The @var{name} may not be one of Readline's builtin keymap names; 728you may not add a different name for one of Readline's builtin keymaps. 729You may replace the name associated with a given keymap by calling this 730function more than once with the same @var{keymap} argument. 731You may associate a registered @var{name} with a new keymap by calling this 732function more than once with the same @var{name} argument. 733There is no way to remove a named keymap once the name has been 734registered. 735Readline will make a copy of @var{name}. 736The return value is greater than zero unless @var{name} is one of 737Readline's builtin keymap names or @var{keymap} is one of Readline's 738builtin keymaps. 739@end deftypefun 740 741@node Binding Keys 742@subsection Binding Keys 743 744Key sequences are associate with functions through the keymap. 745Readline has several internal keymaps: @code{emacs_standard_keymap}, 746@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap}, 747@code{vi_movement_keymap}, and @code{vi_insertion_keymap}. 748@code{emacs_standard_keymap} is the default, and the examples in 749this manual assume that. 750 751Since @code{readline()} installs a set of default key bindings the first 752time it is called, there is always the danger that a custom binding 753installed before the first call to @code{readline()} will be overridden. 754An alternate mechanism is to install custom key bindings in an 755initialization function assigned to the @code{rl_startup_hook} variable 756(@pxref{Readline Variables}). 757 758These functions manage key bindings. 759 760@deftypefun int rl_bind_key (int key, rl_command_func_t *function) 761Binds @var{key} to @var{function} in the currently active keymap. 762Returns non-zero in the case of an invalid @var{key}. 763@end deftypefun 764 765@deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map) 766Bind @var{key} to @var{function} in @var{map}. 767Returns non-zero in the case of an invalid @var{key}. 768@end deftypefun 769 770@deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function) 771Binds @var{key} to @var{function} if it is not already bound in the 772currently active keymap. 773Returns non-zero in the case of an invalid @var{key} or if @var{key} is 774already bound. 775@end deftypefun 776 777@deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map) 778Binds @var{key} to @var{function} if it is not already bound in @var{map}. 779Returns non-zero in the case of an invalid @var{key} or if @var{key} is 780already bound. 781@end deftypefun 782 783@deftypefun int rl_unbind_key (int key) 784Bind @var{key} to the null function in the currently active keymap. 785Returns non-zero in case of error. 786@end deftypefun 787 788@deftypefun int rl_unbind_key_in_map (int key, Keymap map) 789Bind @var{key} to the null function in @var{map}. 790Returns non-zero in case of error. 791@end deftypefun 792 793@deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map) 794Unbind all keys that execute @var{function} in @var{map}. 795@end deftypefun 796 797@deftypefun int rl_unbind_command_in_map (const char *command, Keymap map) 798Unbind all keys that are bound to @var{command} in @var{map}. 799@end deftypefun 800 801@deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function) 802Bind the key sequence represented by the string @var{keyseq} to the function 803@var{function}, beginning in the current keymap. 804This makes new keymaps as necessary. 805The return value is non-zero if @var{keyseq} is invalid. 806@end deftypefun 807 808@deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map) 809Bind the key sequence represented by the string @var{keyseq} to the function 810@var{function}. This makes new keymaps as necessary. 811Initial bindings are performed in @var{map}. 812The return value is non-zero if @var{keyseq} is invalid. 813@end deftypefun 814 815@deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map) 816Equivalent to @code{rl_bind_keyseq_in_map}. 817@end deftypefun 818 819@deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function) 820Binds @var{keyseq} to @var{function} if it is not already bound in the 821currently active keymap. 822Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is 823already bound. 824@end deftypefun 825 826@deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map) 827Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}. 828Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is 829already bound. 830@end deftypefun 831 832@deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map) 833Bind the key sequence represented by the string @var{keyseq} to the arbitrary 834pointer @var{data}. @var{type} says what kind of data is pointed to by 835@var{data}; this can be a function (@code{ISFUNC}), a macro 836(@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as 837necessary. The initial keymap in which to do bindings is @var{map}. 838@end deftypefun 839 840@deftypefun int rl_parse_and_bind (char *line) 841Parse @var{line} as if it had been read from the @code{inputrc} file and 842perform any key bindings and variable assignments found 843(@pxref{Readline Init File}). 844@end deftypefun 845 846@deftypefun int rl_read_init_file (const char *filename) 847Read keybindings and variable assignments from @var{filename} 848(@pxref{Readline Init File}). 849@end deftypefun 850 851@node Associating Function Names and Bindings 852@subsection Associating Function Names and Bindings 853 854These functions allow you to find out what keys invoke named functions 855and the functions invoked by a particular key sequence. You may also 856associate a new function name with an arbitrary function. 857 858@deftypefun {rl_command_func_t *} rl_named_function (const char *name) 859Return the function with name @var{name}. 860@end deftypefun 861 862@deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type) 863Return the function invoked by @var{keyseq} in keymap @var{map}. 864If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is 865not @code{NULL}, the type of the object is returned in the @code{int} variable 866it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}). 867It takes a "translated" key sequence and should not be used if the key sequence 868can include NUL. 869@end deftypefun 870 871@deftypefun {rl_command_func_t *} rl_function_of_keyseq_len (const char *keyseq, size_t len, Keymap map, int *type) 872Return the function invoked by @var{keyseq} of length @var{len} 873in keymap @var{map}. Equivalent to @code{rl_function_of_keyseq} with the 874addition of the @var{len} parameter. 875It takes a "translated" key sequence and should be used if the key sequence 876can include NUL. 877@end deftypefun 878 879@deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function) 880Return an array of strings representing the key sequences used to 881invoke @var{function} in the current keymap. 882@end deftypefun 883 884@deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map) 885Return an array of strings representing the key sequences used to 886invoke @var{function} in the keymap @var{map}. 887@end deftypefun 888 889@deftypefun void rl_function_dumper (int readable) 890Print the readline function names and the key sequences currently 891bound to them to @code{rl_outstream}. If @var{readable} is non-zero, 892the list is formatted in such a way that it can be made part of an 893@code{inputrc} file and re-read. 894@end deftypefun 895 896@deftypefun void rl_list_funmap_names (void) 897Print the names of all bindable Readline functions to @code{rl_outstream}. 898@end deftypefun 899 900@deftypefun {const char **} rl_funmap_names (void) 901Return a NULL terminated array of known function names. The array is 902sorted. The array itself is allocated, but not the strings inside. You 903should free the array, but not the pointers, using @code{free} or 904@code{rl_free} when you are done. 905@end deftypefun 906 907@deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function) 908Add @var{name} to the list of bindable Readline command names, and make 909@var{function} the function to be called when @var{name} is invoked. 910@end deftypefun 911 912@node Allowing Undoing 913@subsection Allowing Undoing 914 915Supporting the undo command is a painless thing, and makes your 916functions much more useful. It is certainly easy to try 917something if you know you can undo it. 918 919If your function simply inserts text once, or deletes text once, and 920uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then 921undoing is already done for you automatically. 922 923If you do multiple insertions or multiple deletions, or any combination 924of these operations, you should group them together into one operation. 925This is done with @code{rl_begin_undo_group()} and 926@code{rl_end_undo_group()}. 927 928The types of events that can be undone are: 929 930@smallexample 931enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @}; 932@end smallexample 933 934Notice that @code{UNDO_DELETE} means to insert some text, and 935@code{UNDO_INSERT} means to delete some text. That is, the undo code 936tells what to undo, not how to undo it. @code{UNDO_BEGIN} and 937@code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and 938@code{rl_end_undo_group()}. 939 940@deftypefun int rl_begin_undo_group (void) 941Begins saving undo information in a group construct. The undo 942information usually comes from calls to @code{rl_insert_text()} and 943@code{rl_delete_text()}, but could be the result of calls to 944@code{rl_add_undo()}. 945@end deftypefun 946 947@deftypefun int rl_end_undo_group (void) 948Closes the current undo group started with @code{rl_begin_undo_group 949()}. There should be one call to @code{rl_end_undo_group()} 950for each call to @code{rl_begin_undo_group()}. 951@end deftypefun 952 953@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text) 954Remember how to undo an event (according to @var{what}). The affected 955text runs from @var{start} to @var{end}, and encompasses @var{text}. 956@end deftypefun 957 958@deftypefun void rl_free_undo_list (void) 959Free the existing undo list. 960@end deftypefun 961 962@deftypefun int rl_do_undo (void) 963Undo the first thing on the undo list. Returns @code{0} if there was 964nothing to undo, non-zero if something was undone. 965@end deftypefun 966 967Finally, if you neither insert nor delete text, but directly modify the 968existing text (e.g., change its case), call @code{rl_modifying()} 969once, just before you modify the text. You must supply the indices of 970the text range that you are going to modify. 971 972@deftypefun int rl_modifying (int start, int end) 973Tell Readline to save the text between @var{start} and @var{end} as a 974single undo unit. It is assumed that you will subsequently modify 975that text. 976@end deftypefun 977 978@node Redisplay 979@subsection Redisplay 980 981@deftypefun void rl_redisplay (void) 982Change what's displayed on the screen to reflect the current contents 983of @code{rl_line_buffer}. 984@end deftypefun 985 986@deftypefun int rl_forced_update_display (void) 987Force the line to be updated and redisplayed, whether or not 988Readline thinks the screen display is correct. 989@end deftypefun 990 991@deftypefun int rl_on_new_line (void) 992Tell the update functions that we have moved onto a new (empty) line, 993usually after outputting a newline. 994@end deftypefun 995 996@deftypefun int rl_on_new_line_with_prompt (void) 997Tell the update functions that we have moved onto a new line, with 998@var{rl_prompt} already displayed. 999This could be used by applications that want to output the prompt string 1000themselves, but still need Readline to know the prompt string length for 1001redisplay. 1002It should be used after setting @var{rl_already_prompted}. 1003@end deftypefun 1004 1005@deftypefun int rl_clear_visible_line (void) 1006Clear the screen lines corresponding to the current line's contents. 1007@end deftypefun 1008 1009@deftypefun int rl_reset_line_state (void) 1010Reset the display state to a clean state and redisplay the current line 1011starting on a new line. 1012@end deftypefun 1013 1014@deftypefun int rl_crlf (void) 1015Move the cursor to the start of the next screen line. 1016@end deftypefun 1017 1018@deftypefun int rl_show_char (int c) 1019Display character @var{c} on @code{rl_outstream}. 1020If Readline has not been set to display meta characters directly, this 1021will convert meta characters to a meta-prefixed key sequence. 1022This is intended for use by applications which wish to do their own 1023redisplay. 1024@end deftypefun 1025 1026@deftypefun int rl_message (const char *, @dots{}) 1027The arguments are a format string as would be supplied to @code{printf}, 1028possibly containing conversion specifications such as @samp{%d}, and 1029any additional arguments necessary to satisfy the conversion specifications. 1030The resulting string is displayed in the @dfn{echo area}. The echo area 1031is also used to display numeric arguments and search strings. 1032You should call @code{rl_save_prompt} to save the prompt information 1033before calling this function. 1034@end deftypefun 1035 1036@deftypefun int rl_clear_message (void) 1037Clear the message in the echo area. If the prompt was saved with a call to 1038@code{rl_save_prompt} before the last call to @code{rl_message}, 1039call @code{rl_restore_prompt} before calling this function. 1040@end deftypefun 1041 1042@deftypefun void rl_save_prompt (void) 1043Save the local Readline prompt display state in preparation for 1044displaying a new message in the message area with @code{rl_message()}. 1045@end deftypefun 1046 1047@deftypefun void rl_restore_prompt (void) 1048Restore the local Readline prompt display state saved by the most 1049recent call to @code{rl_save_prompt}. 1050if @code{rl_save_prompt} was called to save the prompt before a call 1051to @code{rl_message}, this function should be called before the 1052corresponding call to @code{rl_clear_message}. 1053@end deftypefun 1054 1055@deftypefun int rl_expand_prompt (char *prompt) 1056Expand any special character sequences in @var{prompt} and set up the 1057local Readline prompt redisplay variables. 1058This function is called by @code{readline()}. It may also be called to 1059expand the primary prompt if the @code{rl_on_new_line_with_prompt()} 1060function or @code{rl_already_prompted} variable is used. 1061It returns the number of visible characters on the last line of the 1062(possibly multi-line) prompt. 1063Applications may indicate that the prompt contains characters that take 1064up no physical screen space when displayed by bracketing a sequence of 1065such characters with the special markers @code{RL_PROMPT_START_IGNORE} 1066and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}). This may 1067be used to embed terminal-specific escape sequences in prompts. 1068@end deftypefun 1069 1070@deftypefun int rl_set_prompt (const char *prompt) 1071Make Readline use @var{prompt} for subsequent redisplay. This calls 1072@code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt} 1073to the result. 1074@end deftypefun 1075 1076@node Modifying Text 1077@subsection Modifying Text 1078 1079@deftypefun int rl_insert_text (const char *text) 1080Insert @var{text} into the line at the current cursor position. 1081Returns the number of characters inserted. 1082@end deftypefun 1083 1084@deftypefun int rl_delete_text (int start, int end) 1085Delete the text between @var{start} and @var{end} in the current line. 1086Returns the number of characters deleted. 1087@end deftypefun 1088 1089@deftypefun {char *} rl_copy_text (int start, int end) 1090Return a copy of the text between @var{start} and @var{end} in 1091the current line. 1092@end deftypefun 1093 1094@deftypefun int rl_kill_text (int start, int end) 1095Copy the text between @var{start} and @var{end} in the current line 1096to the kill ring, appending or prepending to the last kill if the 1097last command was a kill command. The text is deleted. 1098If @var{start} is less than @var{end}, 1099the text is appended, otherwise prepended. If the last command was 1100not a kill, a new kill ring slot is used. 1101@end deftypefun 1102 1103@deftypefun int rl_push_macro_input (char *macro) 1104Cause @var{macro} to be inserted into the line, as if it had been invoked 1105by a key bound to a macro. Not especially useful; use 1106@code{rl_insert_text()} instead. 1107@end deftypefun 1108 1109@node Character Input 1110@subsection Character Input 1111 1112@deftypefun int rl_read_key (void) 1113Return the next character available from Readline's current input stream. 1114This handles input inserted into 1115the input stream via @var{rl_pending_input} (@pxref{Readline Variables}) 1116and @code{rl_stuff_char()}, macros, and characters read from the keyboard. 1117While waiting for input, this function will call any function assigned to 1118the @code{rl_event_hook} variable. 1119@end deftypefun 1120 1121@deftypefun int rl_getc (FILE *stream) 1122Return the next character available from @var{stream}, which is assumed to 1123be the keyboard. 1124@end deftypefun 1125 1126@deftypefun int rl_stuff_char (int c) 1127Insert @var{c} into the Readline input stream. It will be "read" 1128before Readline attempts to read characters from the terminal with 1129@code{rl_read_key()}. Up to 512 characters may be pushed back. 1130@code{rl_stuff_char} returns 1 if the character was successfully inserted; 11310 otherwise. 1132@end deftypefun 1133 1134@deftypefun int rl_execute_next (int c) 1135Make @var{c} be the next command to be executed when @code{rl_read_key()} 1136is called. This sets @var{rl_pending_input}. 1137@end deftypefun 1138 1139@deftypefun int rl_clear_pending_input (void) 1140Unset @var{rl_pending_input}, effectively negating the effect of any 1141previous call to @code{rl_execute_next()}. This works only if the 1142pending input has not already been read with @code{rl_read_key()}. 1143@end deftypefun 1144 1145@deftypefun int rl_set_keyboard_input_timeout (int u) 1146While waiting for keyboard input in @code{rl_read_key()}, Readline will 1147wait for @var{u} microseconds for input before calling any function 1148assigned to @code{rl_event_hook}. @var{u} must be greater than or equal 1149to zero (a zero-length timeout is equivalent to a poll). 1150The default waiting period is one-tenth of a second. 1151Returns the old timeout value. 1152@end deftypefun 1153 1154@node Terminal Management 1155@subsection Terminal Management 1156 1157@deftypefun void rl_prep_terminal (int meta_flag) 1158Modify the terminal settings for Readline's use, so @code{readline()} 1159can read a single character at a time from the keyboard. 1160The @var{meta_flag} argument should be non-zero if Readline should 1161read eight-bit input. 1162@end deftypefun 1163 1164@deftypefun void rl_deprep_terminal (void) 1165Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in 1166the state in which it was before the most recent call to 1167@code{rl_prep_terminal()}. 1168@end deftypefun 1169 1170@deftypefun void rl_tty_set_default_bindings (Keymap kmap) 1171Read the operating system's terminal editing characters (as would be 1172displayed by @code{stty}) to their Readline equivalents. 1173The bindings are performed in @var{kmap}. 1174@end deftypefun 1175 1176@deftypefun void rl_tty_unset_default_bindings (Keymap kmap) 1177Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so 1178that the terminal editing characters are bound to @code{rl_insert}. 1179The bindings are performed in @var{kmap}. 1180@end deftypefun 1181 1182@deftypefun int rl_tty_set_echoing (int value) 1183Set Readline's idea of whether or not it is echoing output to its output 1184stream (@var{rl_outstream}). If @var{value} is 0, Readline does not display 1185output to @var{rl_outstream}; any other value enables output. The initial 1186value is set when Readline initializes the terminal settings. 1187This function returns the previous value. 1188@end deftypefun 1189 1190@deftypefun int rl_reset_terminal (const char *terminal_name) 1191Reinitialize Readline's idea of the terminal settings using 1192@var{terminal_name} as the terminal type (e.g., @code{vt100}). 1193If @var{terminal_name} is @code{NULL}, the value of the @code{TERM} 1194environment variable is used. 1195@end deftypefun 1196 1197@node Utility Functions 1198@subsection Utility Functions 1199 1200@deftypefun int rl_save_state (struct readline_state *sp) 1201Save a snapshot of Readline's internal state to @var{sp}. 1202The contents of the @var{readline_state} structure are documented 1203in @file{readline.h}. 1204The caller is responsible for allocating the structure. 1205@end deftypefun 1206 1207@deftypefun int rl_restore_state (struct readline_state *sp) 1208Restore Readline's internal state to that stored in @var{sp}, which must 1209have been saved by a call to @code{rl_save_state}. 1210The contents of the @var{readline_state} structure are documented 1211in @file{readline.h}. 1212The caller is responsible for freeing the structure. 1213@end deftypefun 1214 1215@deftypefun void rl_free (void *mem) 1216Deallocate the memory pointed to by @var{mem}. @var{mem} must have been 1217allocated by @code{malloc}. 1218@end deftypefun 1219 1220@deftypefun void rl_replace_line (const char *text, int clear_undo) 1221Replace the contents of @code{rl_line_buffer} with @var{text}. 1222The point and mark are preserved, if possible. 1223If @var{clear_undo} is non-zero, the undo list associated with the 1224current line is cleared. 1225@end deftypefun 1226 1227@deftypefun void rl_extend_line_buffer (int len) 1228Ensure that @code{rl_line_buffer} has enough space to hold @var{len} 1229characters, possibly reallocating it if necessary. 1230@end deftypefun 1231 1232@deftypefun int rl_initialize (void) 1233Initialize or re-initialize Readline's internal state. 1234It's not strictly necessary to call this; @code{readline()} calls it before 1235reading any input. 1236@end deftypefun 1237 1238@deftypefun int rl_ding (void) 1239Ring the terminal bell, obeying the setting of @code{bell-style}. 1240@end deftypefun 1241 1242@deftypefun int rl_alphabetic (int c) 1243Return 1 if @var{c} is an alphabetic character. 1244@end deftypefun 1245 1246@deftypefun void rl_display_match_list (char **matches, int len, int max) 1247A convenience function for displaying a list of strings in 1248columnar format on Readline's output stream. @code{matches} is the list 1249of strings, in argv format, such as a list of completion matches. 1250@code{len} is the number of strings in @code{matches}, and @code{max} 1251is the length of the longest string in @code{matches}. This function uses 1252the setting of @code{print-completions-horizontally} to select how the 1253matches are displayed (@pxref{Readline Init File Syntax}). 1254When displaying completions, this function sets the number of columns used 1255for display to the value of @code{completion-display-width}, the value of 1256the environment variable @env{COLUMNS}, or the screen width, in that order. 1257@end deftypefun 1258 1259The following are implemented as macros, defined in @code{chardefs.h}. 1260Applications should refrain from using them. 1261 1262@deftypefun int _rl_uppercase_p (int c) 1263Return 1 if @var{c} is an uppercase alphabetic character. 1264@end deftypefun 1265 1266@deftypefun int _rl_lowercase_p (int c) 1267Return 1 if @var{c} is a lowercase alphabetic character. 1268@end deftypefun 1269 1270@deftypefun int _rl_digit_p (int c) 1271Return 1 if @var{c} is a numeric character. 1272@end deftypefun 1273 1274@deftypefun int _rl_to_upper (int c) 1275If @var{c} is a lowercase alphabetic character, return the corresponding 1276uppercase character. 1277@end deftypefun 1278 1279@deftypefun int _rl_to_lower (int c) 1280If @var{c} is an uppercase alphabetic character, return the corresponding 1281lowercase character. 1282@end deftypefun 1283 1284@deftypefun int _rl_digit_value (int c) 1285If @var{c} is a number, return the value it represents. 1286@end deftypefun 1287 1288@node Miscellaneous Functions 1289@subsection Miscellaneous Functions 1290 1291@deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map) 1292Bind the key sequence @var{keyseq} to invoke the macro @var{macro}. 1293The binding is performed in @var{map}. When @var{keyseq} is invoked, the 1294@var{macro} will be inserted into the line. This function is deprecated; 1295use @code{rl_generic_bind()} instead. 1296@end deftypefun 1297 1298@deftypefun void rl_macro_dumper (int readable) 1299Print the key sequences bound to macros and their values, using 1300the current keymap, to @code{rl_outstream}. 1301If @var{readable} is non-zero, the list is formatted in such a way 1302that it can be made part of an @code{inputrc} file and re-read. 1303@end deftypefun 1304 1305@deftypefun int rl_variable_bind (const char *variable, const char *value) 1306Make the Readline variable @var{variable} have @var{value}. 1307This behaves as if the readline command 1308@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc} 1309file (@pxref{Readline Init File Syntax}). 1310@end deftypefun 1311 1312@deftypefun {char *} rl_variable_value (const char *variable) 1313Return a string representing the value of the Readline variable @var{variable}. 1314For boolean variables, this string is either @samp{on} or @samp{off}. 1315@end deftypefun 1316 1317@deftypefun void rl_variable_dumper (int readable) 1318Print the readline variable names and their current values 1319to @code{rl_outstream}. 1320If @var{readable} is non-zero, the list is formatted in such a way 1321that it can be made part of an @code{inputrc} file and re-read. 1322@end deftypefun 1323 1324@deftypefun int rl_set_paren_blink_timeout (int u) 1325Set the time interval (in microseconds) that Readline waits when showing 1326a balancing character when @code{blink-matching-paren} has been enabled. 1327@end deftypefun 1328 1329@deftypefun {char *} rl_get_termcap (const char *cap) 1330Retrieve the string value of the termcap capability @var{cap}. 1331Readline fetches the termcap entry for the current terminal name and 1332uses those capabilities to move around the screen line and perform other 1333terminal-specific operations, like erasing a line. Readline does not 1334use all of a terminal's capabilities, and this function will return 1335values for only those capabilities Readline uses. 1336@end deftypefun 1337 1338@deftypefun {void} rl_clear_history (void) 1339Clear the history list by deleting all of the entries, in the same manner 1340as the History library's @code{clear_history()} function. 1341This differs from @code{clear_history} because it frees private data 1342Readline saves in the history list. 1343@end deftypefun 1344 1345@deftypefun {void} rl_activate_mark (void) 1346Enable an @emph{active} mark. 1347When this is enabled, the text between point and mark (the @var{region}) is 1348displayed in the terminal's standout mode (a @var{face}). 1349This is called by various readline functions that set the mark and insert 1350text, and is available for applications to call. 1351@end deftypefun 1352 1353@deftypefun {void} rl_deactivate_mark (void) 1354Turn off the active mark. 1355@end deftypefun 1356 1357@deftypefun {void} rl_keep_mark_active (void) 1358Indicate that the mark should remain active when the current readline function 1359completes and after redisplay occurs. 1360In most cases, the mark remains active for only the duration of a single 1361bindable readline function. 1362@end deftypefun 1363 1364@deftypefun {int} rl_mark_active_p (void) 1365Return a non-zero value if the mark is currently active; zero otherwise. 1366@end deftypefun 1367 1368@node Alternate Interface 1369@subsection Alternate Interface 1370 1371An alternate interface is available to plain @code{readline()}. Some 1372applications need to interleave keyboard I/O with file, device, or 1373window system I/O, typically by using a main loop to @code{select()} 1374on various file descriptors. To accommodate this need, readline can 1375also be invoked as a `callback' function from an event loop. There 1376are functions available to make this easy. 1377 1378@deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler) 1379Set up the terminal for readline I/O and display the initial 1380expanded value of @var{prompt}. Save the value of @var{lhandler} to 1381use as a handler function to call when a complete line of input has been 1382entered. 1383The handler function receives the text of the line as an argument. 1384As with @code{readline()}, the handler function should @code{free} the 1385line when it it finished with it. 1386@end deftypefun 1387 1388@deftypefun void rl_callback_read_char (void) 1389Whenever an application determines that keyboard input is available, it 1390should call @code{rl_callback_read_char()}, which will read the next 1391character from the current input source. 1392If that character completes the line, @code{rl_callback_read_char} will 1393invoke the @var{lhandler} function installed by 1394@code{rl_callback_handler_install} to process the line. 1395Before calling the @var{lhandler} function, the terminal settings are 1396reset to the values they had before calling 1397@code{rl_callback_handler_install}. 1398If the @var{lhandler} function returns, 1399and the line handler remains installed, 1400the terminal settings are modified for Readline's use again. 1401@code{EOF} is indicated by calling @var{lhandler} with a 1402@code{NULL} line. 1403@end deftypefun 1404 1405@deftypefun void rl_callback_sigcleanup (void) 1406Clean up any internal state the callback interface uses to maintain state 1407between calls to rl_callback_read_char (e.g., the state of any active 1408incremental searches). This is intended to be used by applications that 1409wish to perform their own signal handling; Readline's internal signal handler 1410calls this when appropriate. 1411@end deftypefun 1412 1413@deftypefun void rl_callback_handler_remove (void) 1414Restore the terminal to its initial state and remove the line handler. 1415You may call this function from within a callback as well as independently. 1416If the @var{lhandler} installed by @code{rl_callback_handler_install} 1417does not exit the program, either this function or the function referred 1418to by the value of @code{rl_deprep_term_function} should be called before 1419the program exits to reset the terminal settings. 1420@end deftypefun 1421 1422@node A Readline Example 1423@subsection A Readline Example 1424 1425Here is a function which changes lowercase characters to their uppercase 1426equivalents, and uppercase characters to lowercase. If 1427this function was bound to @samp{M-c}, then typing @samp{M-c} would 1428change the case of the character under point. Typing @samp{M-1 0 M-c} 1429would change the case of the following 10 characters, leaving the cursor on 1430the last character changed. 1431 1432@example 1433/* Invert the case of the COUNT following characters. */ 1434int 1435invert_case_line (count, key) 1436 int count, key; 1437@{ 1438 register int start, end, i; 1439 1440 start = rl_point; 1441 1442 if (rl_point >= rl_end) 1443 return (0); 1444 1445 if (count < 0) 1446 @{ 1447 direction = -1; 1448 count = -count; 1449 @} 1450 else 1451 direction = 1; 1452 1453 /* Find the end of the range to modify. */ 1454 end = start + (count * direction); 1455 1456 /* Force it to be within range. */ 1457 if (end > rl_end) 1458 end = rl_end; 1459 else if (end < 0) 1460 end = 0; 1461 1462 if (start == end) 1463 return (0); 1464 1465 if (start > end) 1466 @{ 1467 int temp = start; 1468 start = end; 1469 end = temp; 1470 @} 1471 1472 /* Tell readline that we are modifying the line, 1473 so it will save the undo information. */ 1474 rl_modifying (start, end); 1475 1476 for (i = start; i != end; i++) 1477 @{ 1478 if (_rl_uppercase_p (rl_line_buffer[i])) 1479 rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]); 1480 else if (_rl_lowercase_p (rl_line_buffer[i])) 1481 rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]); 1482 @} 1483 /* Move point to on top of the last character changed. */ 1484 rl_point = (direction == 1) ? end - 1 : start; 1485 return (0); 1486@} 1487@end example 1488 1489@node Alternate Interface Example 1490@subsection Alternate Interface Example 1491 1492Here is a complete program that illustrates Readline's alternate interface. 1493It reads lines from the terminal and displays them, providing the 1494standard history and TAB completion functions. 1495It understands the EOF character or "exit" to exit the program. 1496 1497@example 1498/* Standard include files. stdio.h is required. */ 1499#include <stdlib.h> 1500#include <string.h> 1501#include <unistd.h> 1502#include <locale.h> 1503 1504/* Used for select(2) */ 1505#include <sys/types.h> 1506#include <sys/select.h> 1507 1508#include <signal.h> 1509 1510#include <stdio.h> 1511 1512/* Standard readline include files. */ 1513#include <readline/readline.h> 1514#include <readline/history.h> 1515 1516static void cb_linehandler (char *); 1517static void sighandler (int); 1518 1519int running; 1520int sigwinch_received; 1521const char *prompt = "rltest$ "; 1522 1523/* Handle SIGWINCH and window size changes when readline is not active and 1524 reading a character. */ 1525static void 1526sighandler (int sig) 1527@{ 1528 sigwinch_received = 1; 1529@} 1530 1531/* Callback function called for each line when accept-line executed, EOF 1532 seen, or EOF character read. This sets a flag and returns; it could 1533 also call exit(3). */ 1534static void 1535cb_linehandler (char *line) 1536@{ 1537 /* Can use ^D (stty eof) or `exit' to exit. */ 1538 if (line == NULL || strcmp (line, "exit") == 0) 1539 @{ 1540 if (line == 0) 1541 printf ("\n"); 1542 printf ("exit\n"); 1543 /* This function needs to be called to reset the terminal settings, 1544 and calling it from the line handler keeps one extra prompt from 1545 being displayed. */ 1546 rl_callback_handler_remove (); 1547 1548 running = 0; 1549 @} 1550 else 1551 @{ 1552 if (*line) 1553 add_history (line); 1554 printf ("input line: %s\n", line); 1555 free (line); 1556 @} 1557@} 1558 1559int 1560main (int c, char **v) 1561@{ 1562 fd_set fds; 1563 int r; 1564 1565 /* Set the default locale values according to environment variables. */ 1566 setlocale (LC_ALL, ""); 1567 1568 /* Handle window size changes when readline is not active and reading 1569 characters. */ 1570 signal (SIGWINCH, sighandler); 1571 1572 /* Install the line handler. */ 1573 rl_callback_handler_install (prompt, cb_linehandler); 1574 1575 /* Enter a simple event loop. This waits until something is available 1576 to read on readline's input stream (defaults to standard input) and 1577 calls the builtin character read callback to read it. It does not 1578 have to modify the user's terminal settings. */ 1579 running = 1; 1580 while (running) 1581 @{ 1582 FD_ZERO (&fds); 1583 FD_SET (fileno (rl_instream), &fds); 1584 1585 r = select (FD_SETSIZE, &fds, NULL, NULL, NULL); 1586 if (r < 0 && errno != EINTR) 1587 @{ 1588 perror ("rltest: select"); 1589 rl_callback_handler_remove (); 1590 break; 1591 @} 1592 if (sigwinch_received) 1593 @{ 1594 rl_resize_terminal (); 1595 sigwinch_received = 0; 1596 @} 1597 if (r < 0) 1598 continue; 1599 1600 if (FD_ISSET (fileno (rl_instream), &fds)) 1601 rl_callback_read_char (); 1602 @} 1603 1604 printf ("rltest: Event loop has exited\n"); 1605 return 0; 1606@} 1607@end example 1608 1609@node Readline Signal Handling 1610@section Readline Signal Handling 1611 1612Signals are asynchronous events sent to a process by the Unix kernel, 1613sometimes on behalf of another process. They are intended to indicate 1614exceptional events, like a user pressing the interrupt key on his terminal, 1615or a network connection being broken. There is a class of signals that can 1616be sent to the process currently reading input from the keyboard. Since 1617Readline changes the terminal attributes when it is called, it needs to 1618perform special processing when such a signal is received in order to 1619restore the terminal to a sane state, or provide application writers with 1620functions to do so manually. 1621 1622Readline contains an internal signal handler that is installed for a 1623number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, 1624@code{SIGHUP}, 1625@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}). 1626When one of these signals is received, the signal handler 1627will reset the terminal attributes to those that were in effect before 1628@code{readline()} was called, reset the signal handling to what it was 1629before @code{readline()} was called, and resend the signal to the calling 1630application. 1631If and when the calling application's signal handler returns, Readline 1632will reinitialize the terminal and continue to accept input. 1633When a @code{SIGINT} is received, the Readline signal handler performs 1634some additional work, which will cause any partially-entered line to be 1635aborted (see the description of @code{rl_free_line_state()} below). 1636 1637There is an additional Readline signal handler, for @code{SIGWINCH}, which 1638the kernel sends to a process whenever the terminal's size changes (for 1639example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH} 1640handler updates Readline's internal screen size information, and then calls 1641any @code{SIGWINCH} signal handler the calling application has installed. 1642Readline calls the application's @code{SIGWINCH} signal handler without 1643resetting the terminal to its original state. If the application's signal 1644handler does more than update its idea of the terminal size and return (for 1645example, a @code{longjmp} back to a main processing loop), it @emph{must} 1646call @code{rl_cleanup_after_signal()} (described below), to restore the 1647terminal state. 1648 1649When an application is using the callback interface 1650(@pxref{Alternate Interface}), Readline installs signal handlers only for 1651the duration of the call to @code{rl_callback_read_char}. Applications 1652using the callback interface should be prepared to clean up Readline's 1653state if they wish to handle the signal before the line handler completes 1654and restores the terminal state. 1655 1656If an application using the callback interface wishes to have Readline 1657install its signal handlers at the time the application calls 1658@code{rl_callback_handler_install} and remove them only when a complete 1659line of input has been read, it should set the 1660@code{rl_persistent_signal_handlers} variable to a non-zero value. 1661This allows an application to defer all of the handling of the signals 1662Readline catches to Readline. 1663Applications should use this variable with care; it can result in Readline 1664catching signals and not acting on them (or allowing the application to react 1665to them) until the application calls @code{rl_callback_read_char}. This 1666can result in an application becoming less responsive to keyboard signals 1667like SIGINT. 1668If an application does not want or need to perform any signal handling, or 1669does not need to do any processing between calls to @code{rl_callback_read_char}, 1670setting this variable may be desirable. 1671 1672Readline provides two variables that allow application writers to 1673control whether or not it will catch certain signals and act on them 1674when they are received. It is important that applications change the 1675values of these variables only when calling @code{readline()}, not in 1676a signal handler, so Readline's internal signal state is not corrupted. 1677 1678@deftypevar int rl_catch_signals 1679If this variable is non-zero, Readline will install signal handlers for 1680@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, 1681@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}. 1682 1683The default value of @code{rl_catch_signals} is 1. 1684@end deftypevar 1685 1686@deftypevar int rl_catch_sigwinch 1687If this variable is set to a non-zero value, 1688Readline will install a signal handler for @code{SIGWINCH}. 1689 1690The default value of @code{rl_catch_sigwinch} is 1. 1691@end deftypevar 1692 1693@deftypevar int rl_persistent_signal_handlers 1694If an application using the callback interface wishes Readline's signal 1695handlers to be installed and active during the set of calls to 1696@code{rl_callback_read_char} that constitutes an entire single line, 1697it should set this variable to a non-zero value. 1698 1699The default value of @code{rl_persistent_signal_handlers} is 0. 1700@end deftypevar 1701 1702@deftypevar int rl_change_environment 1703If this variable is set to a non-zero value, 1704and Readline is handling @code{SIGWINCH}, Readline will modify the 1705@var{LINES} and @var{COLUMNS} environment variables upon receipt of a 1706@code{SIGWINCH} 1707 1708The default value of @code{rl_change_environment} is 1. 1709@end deftypevar 1710 1711If an application does not wish to have Readline catch any signals, or 1712to handle signals other than those Readline catches (@code{SIGHUP}, 1713for example), 1714Readline provides convenience functions to do the necessary terminal 1715and internal state cleanup upon receipt of a signal. 1716 1717@deftypefun int rl_pending_signal (void) 1718Return the signal number of the most recent signal Readline received but 1719has not yet handled, or 0 if there is no pending signal. 1720@end deftypefun 1721 1722@deftypefun void rl_cleanup_after_signal (void) 1723This function will reset the state of the terminal to what it was before 1724@code{readline()} was called, and remove the Readline signal handlers for 1725all signals, depending on the values of @code{rl_catch_signals} and 1726@code{rl_catch_sigwinch}. 1727@end deftypefun 1728 1729@deftypefun void rl_free_line_state (void) 1730This will free any partial state associated with the current input line 1731(undo information, any partial history entry, any partially-entered 1732keyboard macro, and any partially-entered numeric argument). This 1733should be called before @code{rl_cleanup_after_signal()}. The 1734Readline signal handler for @code{SIGINT} calls this to abort the 1735current input line. 1736@end deftypefun 1737 1738@deftypefun void rl_reset_after_signal (void) 1739This will reinitialize the terminal and reinstall any Readline signal 1740handlers, depending on the values of @code{rl_catch_signals} and 1741@code{rl_catch_sigwinch}. 1742@end deftypefun 1743 1744If an application wants to force Readline to handle any signals that 1745have arrived while it has been executing, @code{rl_check_signals()} 1746will call Readline's internal signal handler if there are any pending 1747signals. This is primarily intended for those applications that use 1748a custom @code{rl_getc_function} (@pxref{Readline Variables}) and wish 1749to handle signals received while waiting for input. 1750 1751@deftypefun void rl_check_signals (void) 1752If there are any pending signals, call Readline's internal signal handling 1753functions to process them. @code{rl_pending_signal()} can be used independently 1754to determine whether or not there are any pending signals. 1755@end deftypefun 1756 1757If an application does not wish Readline to catch @code{SIGWINCH}, it may 1758call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force 1759Readline to update its idea of the terminal size when it receives 1760a @code{SIGWINCH}. 1761 1762@deftypefun void rl_echo_signal_char (int sig) 1763If an application wishes to install its own signal handlers, but still 1764have readline display characters that generate signals, calling this 1765function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or 1766@code{SIGTSTP} will display the character generating that signal. 1767@end deftypefun 1768 1769@deftypefun void rl_resize_terminal (void) 1770Update Readline's internal screen size by reading values from the kernel. 1771@end deftypefun 1772 1773@deftypefun void rl_set_screen_size (int rows, int cols) 1774Set Readline's idea of the terminal size to @var{rows} rows and 1775@var{cols} columns. If either @var{rows} or @var{columns} is less than 1776or equal to 0, Readline's idea of that terminal dimension is unchanged. 1777This is intended to tell Readline the physical dimensions of the terminal, 1778and is used internally to calculate the maximum number of characters that 1779may appear on a single line and on the screen. 1780@end deftypefun 1781 1782If an application does not want to install a @code{SIGWINCH} handler, but 1783is still interested in the screen dimensions, it may query Readline's idea 1784of the screen size. 1785 1786@deftypefun void rl_get_screen_size (int *rows, int *cols) 1787Return Readline's idea of the terminal's size in the 1788variables pointed to by the arguments. 1789@end deftypefun 1790 1791@deftypefun void rl_reset_screen_size (void) 1792Cause Readline to reobtain the screen size and recalculate its dimensions. 1793@end deftypefun 1794 1795The following functions install and remove Readline's signal handlers. 1796 1797@deftypefun int rl_set_signals (void) 1798Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT}, 1799@code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, 1800@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of 1801@code{rl_catch_signals} and @code{rl_catch_sigwinch}. 1802@end deftypefun 1803 1804@deftypefun int rl_clear_signals (void) 1805Remove all of the Readline signal handlers installed by 1806@code{rl_set_signals()}. 1807@end deftypefun 1808 1809@node Custom Completers 1810@section Custom Completers 1811@cindex application-specific completion functions 1812 1813Typically, a program that reads commands from the user has a way of 1814disambiguating commands and data. If your program is one of these, then 1815it can provide completion for commands, data, or both. 1816The following sections describe how your program and Readline 1817cooperate to provide this service. 1818 1819@menu 1820* How Completing Works:: The logic used to do completion. 1821* Completion Functions:: Functions provided by Readline. 1822* Completion Variables:: Variables which control completion. 1823* A Short Completion Example:: An example of writing completer subroutines. 1824@end menu 1825 1826@node How Completing Works 1827@subsection How Completing Works 1828 1829In order to complete some text, the full list of possible completions 1830must be available. That is, it is not possible to accurately 1831expand a partial word without knowing all of the possible words 1832which make sense in that context. The Readline library provides 1833the user interface to completion, and two of the most common 1834completion functions: filename and username. For completing other types 1835of text, you must write your own completion function. This section 1836describes exactly what such functions must do, and provides an example. 1837 1838There are three major functions used to perform completion: 1839 1840@enumerate 1841@item 1842The user-interface function @code{rl_complete()}. This function is 1843called with the same arguments as other bindable Readline functions: 1844@var{count} and @var{invoking_key}. 1845It isolates the word to be completed and calls 1846@code{rl_completion_matches()} to generate a list of possible completions. 1847It then either lists the possible completions, inserts the possible 1848completions, or actually performs the 1849completion, depending on which behavior is desired. 1850 1851@item 1852The internal function @code{rl_completion_matches()} uses an 1853application-supplied @dfn{generator} function to generate the list of 1854possible matches, and then returns the array of these matches. 1855The caller should place the address of its generator function in 1856@code{rl_completion_entry_function}. 1857 1858@item 1859The generator function is called repeatedly from 1860@code{rl_completion_matches()}, returning a string each time. The 1861arguments to the generator function are @var{text} and @var{state}. 1862@var{text} is the partial word to be completed. @var{state} is zero the 1863first time the function is called, allowing the generator to perform 1864any necessary initialization, and a positive non-zero integer for 1865each subsequent call. The generator function returns 1866@code{(char *)NULL} to inform @code{rl_completion_matches()} that there are 1867no more possibilities left. Usually the generator function computes the 1868list of possible completions when @var{state} is zero, and returns them 1869one at a time on subsequent calls. Each string the generator function 1870returns as a match must be allocated with @code{malloc()}; Readline 1871frees the strings when it has finished with them. 1872Such a generator function is referred to as an 1873@dfn{application-specific completion function}. 1874 1875@end enumerate 1876 1877@deftypefun int rl_complete (int ignore, int invoking_key) 1878Complete the word at or before point. You have supplied the function 1879that does the initial simple matching selection algorithm (see 1880@code{rl_completion_matches()}). The default is to do filename completion. 1881@end deftypefun 1882 1883@deftypevar {rl_compentry_func_t *} rl_completion_entry_function 1884This is a pointer to the generator function for 1885@code{rl_completion_matches()}. 1886If the value of @code{rl_completion_entry_function} is 1887@code{NULL} then the default filename generator 1888function, @code{rl_filename_completion_function()}, is used. 1889An @dfn{application-specific completion function} is a function whose 1890address is assigned to @code{rl_completion_entry_function} and whose 1891return values are used to generate possible completions. 1892@end deftypevar 1893 1894@node Completion Functions 1895@subsection Completion Functions 1896 1897Here is the complete list of callable completion functions present in 1898Readline. 1899 1900@deftypefun int rl_complete_internal (int what_to_do) 1901Complete the word at or before point. @var{what_to_do} says what to do 1902with the completion. A value of @samp{?} means list the possible 1903completions. @samp{TAB} means do standard completion. @samp{*} means 1904insert all of the possible completions. @samp{!} means to display 1905all of the possible completions, if there is more than one, as well as 1906performing partial completion. @samp{@@} is similar to @samp{!}, but 1907possible completions are not listed if the possible completions share 1908a common prefix. 1909@end deftypefun 1910 1911@deftypefun int rl_complete (int ignore, int invoking_key) 1912Complete the word at or before point. You have supplied the function 1913that does the initial simple matching selection algorithm (see 1914@code{rl_completion_matches()} and @code{rl_completion_entry_function}). 1915The default is to do filename 1916completion. This calls @code{rl_complete_internal()} with an 1917argument depending on @var{invoking_key}. 1918@end deftypefun 1919 1920@deftypefun int rl_possible_completions (int count, int invoking_key) 1921List the possible completions. See description of @code{rl_complete 1922()}. This calls @code{rl_complete_internal()} with an argument of 1923@samp{?}. 1924@end deftypefun 1925 1926@deftypefun int rl_insert_completions (int count, int invoking_key) 1927Insert the list of possible completions into the line, deleting the 1928partially-completed word. See description of @code{rl_complete()}. 1929This calls @code{rl_complete_internal()} with an argument of @samp{*}. 1930@end deftypefun 1931 1932@deftypefun int rl_completion_mode (rl_command_func_t *cfunc) 1933Returns the appropriate value to pass to @code{rl_complete_internal()} 1934depending on whether @var{cfunc} was called twice in succession and 1935the values of the @code{show-all-if-ambiguous} and 1936@code{show-all-if-unmodified} variables. 1937Application-specific completion functions may use this function to present 1938the same interface as @code{rl_complete()}. 1939@end deftypefun 1940 1941@deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func) 1942Returns an array of strings which is a list of completions for 1943@var{text}. If there are no completions, returns @code{NULL}. 1944The first entry in the returned array is the substitution for @var{text}. 1945The remaining entries are the possible completions. The array is 1946terminated with a @code{NULL} pointer. 1947 1948@var{entry_func} is a function of two args, and returns a 1949@code{char *}. The first argument is @var{text}. The second is a 1950state argument; it is zero on the first call, and non-zero on subsequent 1951calls. @var{entry_func} returns a @code{NULL} pointer to the caller 1952when there are no more matches. 1953@end deftypefun 1954 1955@deftypefun {char *} rl_filename_completion_function (const char *text, int state) 1956A generator function for filename completion in the general case. 1957@var{text} is a partial filename. 1958The Bash source is a useful reference for writing application-specific 1959completion functions (the Bash completion functions call this and other 1960Readline functions). 1961@end deftypefun 1962 1963@deftypefun {char *} rl_username_completion_function (const char *text, int state) 1964A completion generator for usernames. @var{text} contains a partial 1965username preceded by a random character (usually @samp{~}). As with all 1966completion generators, @var{state} is zero on the first call and non-zero 1967for subsequent calls. 1968@end deftypefun 1969 1970@node Completion Variables 1971@subsection Completion Variables 1972 1973@deftypevar {rl_compentry_func_t *} rl_completion_entry_function 1974A pointer to the generator function for @code{rl_completion_matches()}. 1975@code{NULL} means to use @code{rl_filename_completion_function()}, 1976the default filename completer. 1977@end deftypevar 1978 1979@deftypevar {rl_completion_func_t *} rl_attempted_completion_function 1980A pointer to an alternative function to create matches. 1981The function is called with @var{text}, @var{start}, and @var{end}. 1982@var{start} and @var{end} are indices in @code{rl_line_buffer} defining 1983the boundaries of @var{text}, which is a character string. 1984If this function exists and returns @code{NULL}, or if this variable is 1985set to @code{NULL}, then @code{rl_complete()} will call the value of 1986@code{rl_completion_entry_function} to generate matches, otherwise the 1987array of strings returned will be used. 1988If this function sets the @code{rl_attempted_completion_over} 1989variable to a non-zero value, Readline will not perform its default 1990completion even if this function returns no matches. 1991@end deftypevar 1992 1993@deftypevar {rl_quote_func_t *} rl_filename_quoting_function 1994A pointer to a function that will quote a filename in an 1995application-specific fashion. This is called if filename completion is being 1996attempted and one of the characters in @code{rl_filename_quote_characters} 1997appears in a completed filename. The function is called with 1998@var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text} 1999is the filename to be quoted. The @var{match_type} is either 2000@code{SINGLE_MATCH}, if there is only one completion match, or 2001@code{MULT_MATCH}. Some functions use this to decide whether or not to 2002insert a closing quote character. The @var{quote_pointer} is a pointer 2003to any opening quote character the user typed. Some functions choose 2004to reset this character. 2005@end deftypevar 2006 2007@deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function 2008A pointer to a function that will remove application-specific quoting 2009characters from a filename before completion is attempted, so those 2010characters do not interfere with matching the text against names in 2011the filesystem. It is called with @var{text}, the text of the word 2012to be dequoted, and @var{quote_char}, which is the quoting character 2013that delimits the filename (usually @samp{'} or @samp{"}). If 2014@var{quote_char} is zero, the filename was not in an embedded string. 2015@end deftypevar 2016 2017@deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p 2018A pointer to a function to call that determines whether or not a specific 2019character in the line buffer is quoted, according to whatever quoting 2020mechanism the program calling Readline uses. The function is called with 2021two arguments: @var{text}, the text of the line, and @var{index}, the 2022index of the character in the line. It is used to decide whether a 2023character found in @code{rl_completer_word_break_characters} should be 2024used to break words for the completer. 2025@end deftypevar 2026 2027@deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function 2028This function, if defined, is called by the completer when real filename 2029completion is done, after all the matching names have been generated. 2030It is passed a @code{NULL} terminated array of matches. 2031The first element (@code{matches[0]}) is the 2032maximal substring common to all matches. This function can 2033re-arrange the list of matches as required, but each element deleted 2034from the array must be freed. 2035@end deftypevar 2036 2037@deftypevar {rl_icppfunc_t *} rl_directory_completion_hook 2038This function, if defined, is allowed to modify the directory portion 2039of filenames Readline completes. 2040It could be used to expand symbolic links or shell variables in pathnames. 2041It is called with the address of a string (the current directory name) as an 2042argument, and may modify that string. 2043If the string is replaced with a new string, the old value should be freed. 2044Any modified directory name should have a trailing slash. 2045The modified value will be used as part of the completion, replacing 2046the directory portion of the pathname the user typed. 2047At the least, even if no other expansion is performed, this function should 2048remove any quote characters from the directory name, because its result will 2049be passed directly to @code{opendir()}. 2050 2051The directory completion hook returns an integer that should be non-zero if 2052the function modifies its directory argument. 2053The function should not modify the directory argument if it returns 0. 2054@end deftypevar 2055 2056@deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook; 2057If non-zero, this is the address of a function to call when completing 2058a directory name. This function takes the address of the directory name 2059to be modified as an argument. Unlike @code{rl_directory_completion_hook}, 2060it only modifies the directory name used in @code{opendir}, not what is 2061displayed when the possible completions are printed or inserted. It is 2062called before rl_directory_completion_hook. 2063At the least, even if no other expansion is performed, this function should 2064remove any quote characters from the directory name, because its result will 2065be passed directly to @code{opendir()}. 2066 2067The directory rewrite hook returns an integer that should be non-zero if 2068the function modifies its directory argument. 2069The function should not modify the directory argument if it returns 0. 2070@end deftypevar 2071 2072@deftypevar {rl_icppfunc_t *} rl_filename_stat_hook 2073If non-zero, this is the address of a function for the completer to 2074call before deciding which character to append to a completed name. 2075This function modifies its filename name argument, and the modified value 2076is passed to @code{stat()} to determine the file's type and characteristics. 2077This function does not need to remove quote characters from the filename. 2078 2079The stat hook returns an integer that should be non-zero if 2080the function modifies its directory argument. 2081The function should not modify the directory argument if it returns 0. 2082@end deftypevar 2083 2084@deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook 2085If non-zero, this is the address of a function called when reading 2086directory entries from the filesystem for completion and comparing 2087them to the partial word to be completed. The function should 2088perform any necessary application or system-specific conversion on 2089the filename, such as converting between character sets or converting 2090from a filesystem format to a character input format. 2091The function takes two arguments: @var{fname}, the filename to be converted, 2092and @var{fnlen}, its length in bytes. 2093It must either return its first argument (if no conversion takes place) 2094or the converted filename in newly-allocated memory. The converted 2095form is used to compare against the word to be completed, and, if it 2096matches, is added to the list of matches. Readline will free the 2097allocated string. 2098@end deftypevar 2099 2100@deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook 2101If non-zero, then this is the address of a function to call when 2102completing a word would normally display the list of possible matches. 2103This function is called in lieu of Readline displaying the list. 2104It takes three arguments: 2105(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length}) 2106where @var{matches} is the array of matching strings, 2107@var{num_matches} is the number of strings in that array, and 2108@var{max_length} is the length of the longest string in that array. 2109Readline provides a convenience function, @code{rl_display_match_list}, 2110that takes care of doing the display to Readline's output stream. 2111You may call that function from this hook. 2112@end deftypevar 2113 2114@deftypevar {const char *} rl_basic_word_break_characters 2115The basic list of characters that signal a break between words for the 2116completer routine. The default value of this variable is the characters 2117which break words for completion in Bash: 2118@code{" \t\n\"\\'`@@$><=;|&@{("}. 2119@end deftypevar 2120 2121@deftypevar {const char *} rl_basic_quote_characters 2122A list of quote characters which can cause a word break. 2123@end deftypevar 2124 2125@deftypevar {const char *} rl_completer_word_break_characters 2126The list of characters that signal a break between words for 2127@code{rl_complete_internal()}. The default list is the value of 2128@code{rl_basic_word_break_characters}. 2129@end deftypevar 2130 2131@deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook 2132If non-zero, this is the address of a function to call when Readline is 2133deciding where to separate words for word completion. It should return 2134a character string like @code{rl_completer_word_break_characters} to be 2135used to perform the current completion. The function may choose to set 2136@code{rl_completer_word_break_characters} itself. If the function 2137returns @code{NULL}, @code{rl_completer_word_break_characters} is used. 2138@end deftypevar 2139 2140@deftypevar {const char *} rl_completer_quote_characters 2141A list of characters which can be used to quote a substring of the line. 2142Completion occurs on the entire substring, and within the substring 2143@code{rl_completer_word_break_characters} are treated as any other character, 2144unless they also appear within this list. 2145@end deftypevar 2146 2147@deftypevar {const char *} rl_filename_quote_characters 2148A list of characters that cause a filename to be quoted by the completer 2149when they appear in a completed filename. The default is the null string. 2150@end deftypevar 2151 2152@deftypevar {const char *} rl_special_prefixes 2153The list of characters that are word break characters, but should be 2154left in @var{text} when it is passed to the completion function. 2155Programs can use this to help determine what kind of completing to do. 2156For instance, Bash sets this variable to "$@@" so that it can complete 2157shell variables and hostnames. 2158@end deftypevar 2159 2160@deftypevar int rl_completion_query_items 2161Up to this many items will be displayed in response to a 2162possible-completions call. After that, readline asks the user if she is sure 2163she wants to see them all. The default value is 100. A negative value 2164indicates that Readline should never ask the user. 2165@end deftypevar 2166 2167@deftypevar {int} rl_completion_append_character 2168When a single completion alternative matches at the end of the command 2169line, this character is appended to the inserted completion text. The 2170default is a space character (@samp{ }). Setting this to the null 2171character (@samp{\0}) prevents anything being appended automatically. 2172This can be changed in application-specific completion functions to 2173provide the ``most sensible word separator character'' according to 2174an application-specific command line syntax specification. 2175It is set to the default before any application-specific completion function 2176is called, and may only be changed within such a function. 2177@end deftypevar 2178 2179@deftypevar int rl_completion_suppress_append 2180If non-zero, @var{rl_completion_append_character} is not appended to 2181matches at the end of the command line, as described above. 2182It is set to 0 before any application-specific completion function 2183is called, and may only be changed within such a function. 2184@end deftypevar 2185 2186@deftypevar int rl_completion_quote_character 2187When Readline is completing quoted text, as delimited by one of the 2188characters in @var{rl_completer_quote_characters}, it sets this variable 2189to the quoting character found. 2190This is set before any application-specific completion function is called. 2191@end deftypevar 2192 2193@deftypevar int rl_completion_suppress_quote 2194If non-zero, Readline does not append a matching quote character when 2195performing completion on a quoted string. 2196It is set to 0 before any application-specific completion function 2197is called, and may only be changed within such a function. 2198@end deftypevar 2199 2200@deftypevar int rl_completion_found_quote 2201When Readline is completing quoted text, it sets this variable 2202to a non-zero value if the word being completed contains or is delimited 2203by any quoting characters, including backslashes. 2204This is set before any application-specific completion function is called. 2205@end deftypevar 2206 2207@deftypevar int rl_completion_mark_symlink_dirs 2208If non-zero, a slash will be appended to completed filenames that are 2209symbolic links to directory names, subject to the value of the 2210user-settable @var{mark-directories} variable. 2211This variable exists so that application-specific completion functions 2212can override the user's global preference (set via the 2213@var{mark-symlinked-directories} Readline variable) if appropriate. 2214This variable is set to the user's preference before any 2215application-specific completion function is called, so unless that 2216function modifies the value, the user's preferences are honored. 2217@end deftypevar 2218 2219@deftypevar int rl_ignore_completion_duplicates 2220If non-zero, then duplicates in the matches are removed. 2221The default is 1. 2222@end deftypevar 2223 2224@deftypevar int rl_filename_completion_desired 2225Non-zero means that the results of the matches are to be treated as 2226filenames. This is @emph{always} zero when completion is attempted, 2227and can only be changed 2228within an application-specific completion function. If it is set to a 2229non-zero value by such a function, directory names have a slash appended 2230and Readline attempts to quote completed filenames if they contain any 2231characters in @code{rl_filename_quote_characters} and 2232@code{rl_filename_quoting_desired} is set to a non-zero value. 2233@end deftypevar 2234 2235@deftypevar int rl_filename_quoting_desired 2236Non-zero means that the results of the matches are to be quoted using 2237double quotes (or an application-specific quoting mechanism) if the 2238completed filename contains any characters in 2239@code{rl_filename_quote_chars}. This is @emph{always} non-zero 2240when completion is attempted, and can only be changed within an 2241application-specific completion function. 2242The quoting is effected via a call to the function pointed to 2243by @code{rl_filename_quoting_function}. 2244@end deftypevar 2245 2246@deftypevar int rl_attempted_completion_over 2247If an application-specific completion function assigned to 2248@code{rl_attempted_completion_function} sets this variable to a non-zero 2249value, Readline will not perform its default filename completion even 2250if the application's completion function returns no matches. 2251It should be set only by an application's completion function. 2252@end deftypevar 2253 2254@deftypevar int rl_sort_completion_matches 2255If an application sets this variable to 0, Readline will not sort the 2256list of completions (which implies that it cannot remove any duplicate 2257completions). The default value is 1, which means that Readline will 2258sort the completions and, depending on the value of 2259@code{rl_ignore_completion_duplicates}, will attempt to remove duplicate 2260matches. 2261@end deftypevar 2262 2263@deftypevar int rl_completion_type 2264Set to a character describing the type of completion Readline is currently 2265attempting; see the description of @code{rl_complete_internal()} 2266(@pxref{Completion Functions}) for the list of characters. 2267This is set to the appropriate value before any application-specific 2268completion function is called, allowing such functions to present 2269the same interface as @code{rl_complete()}. 2270@end deftypevar 2271 2272@deftypevar int rl_completion_invoking_key 2273Set to the final character in the key sequence that invoked one of the 2274completion functions that call @code{rl_complete_internal()}. This is 2275set to the appropriate value before any application-specific completion 2276function is called. 2277@end deftypevar 2278 2279@deftypevar int rl_inhibit_completion 2280If this variable is non-zero, completion is inhibited. The completion 2281character will be inserted as any other bound to @code{self-insert}. 2282@end deftypevar 2283 2284@node A Short Completion Example 2285@subsection A Short Completion Example 2286 2287Here is a small application demonstrating the use of the GNU Readline 2288library. It is called @code{fileman}, and the source code resides in 2289@file{examples/fileman.c}. This sample application provides 2290completion of command names, line editing features, and access to the 2291history list. 2292 2293@page 2294@smallexample 2295/* fileman.c -- A tiny application which demonstrates how to use the 2296 GNU Readline library. This application interactively allows users 2297 to manipulate files and their modes. */ 2298 2299#ifdef HAVE_CONFIG_H 2300# include <config.h> 2301#endif 2302 2303#include <sys/types.h> 2304#ifdef HAVE_SYS_FILE_H 2305# include <sys/file.h> 2306#endif 2307#include <sys/stat.h> 2308 2309#ifdef HAVE_UNISTD_H 2310# include <unistd.h> 2311#endif 2312 2313#include <fcntl.h> 2314#include <stdio.h> 2315#include <errno.h> 2316 2317#if defined (HAVE_STRING_H) 2318# include <string.h> 2319#else /* !HAVE_STRING_H */ 2320# include <strings.h> 2321#endif /* !HAVE_STRING_H */ 2322 2323#ifdef HAVE_STDLIB_H 2324# include <stdlib.h> 2325#endif 2326 2327#include <time.h> 2328 2329#include <readline/readline.h> 2330#include <readline/history.h> 2331 2332extern char *xmalloc PARAMS((size_t)); 2333 2334/* The names of functions that actually do the manipulation. */ 2335int com_list PARAMS((char *)); 2336int com_view PARAMS((char *)); 2337int com_rename PARAMS((char *)); 2338int com_stat PARAMS((char *)); 2339int com_pwd PARAMS((char *)); 2340int com_delete PARAMS((char *)); 2341int com_help PARAMS((char *)); 2342int com_cd PARAMS((char *)); 2343int com_quit PARAMS((char *)); 2344 2345/* A structure which contains information on the commands this program 2346 can understand. */ 2347 2348typedef struct @{ 2349 char *name; /* User printable name of the function. */ 2350 rl_icpfunc_t *func; /* Function to call to do the job. */ 2351 char *doc; /* Documentation for this function. */ 2352@} COMMAND; 2353 2354COMMAND commands[] = @{ 2355 @{ "cd", com_cd, "Change to directory DIR" @}, 2356 @{ "delete", com_delete, "Delete FILE" @}, 2357 @{ "help", com_help, "Display this text" @}, 2358 @{ "?", com_help, "Synonym for `help'" @}, 2359 @{ "list", com_list, "List files in DIR" @}, 2360 @{ "ls", com_list, "Synonym for `list'" @}, 2361 @{ "pwd", com_pwd, "Print the current working directory" @}, 2362 @{ "quit", com_quit, "Quit using Fileman" @}, 2363 @{ "rename", com_rename, "Rename FILE to NEWNAME" @}, 2364 @{ "stat", com_stat, "Print out statistics on FILE" @}, 2365 @{ "view", com_view, "View the contents of FILE" @}, 2366 @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @} 2367@}; 2368 2369/* Forward declarations. */ 2370char *stripwhite (); 2371COMMAND *find_command (); 2372 2373/* The name of this program, as taken from argv[0]. */ 2374char *progname; 2375 2376/* When non-zero, this global means the user is done using this program. */ 2377int done; 2378 2379char * 2380dupstr (s) 2381 char *s; 2382@{ 2383 char *r; 2384 2385 r = xmalloc (strlen (s) + 1); 2386 strcpy (r, s); 2387 return (r); 2388@} 2389 2390main (argc, argv) 2391 int argc; 2392 char **argv; 2393@{ 2394 char *line, *s; 2395 2396 progname = argv[0]; 2397 2398 initialize_readline (); /* Bind our completer. */ 2399 2400 /* Loop reading and executing lines until the user quits. */ 2401 for ( ; done == 0; ) 2402 @{ 2403 line = readline ("FileMan: "); 2404 2405 if (!line) 2406 break; 2407 2408 /* Remove leading and trailing whitespace from the line. 2409 Then, if there is anything left, add it to the history list 2410 and execute it. */ 2411 s = stripwhite (line); 2412 2413 if (*s) 2414 @{ 2415 add_history (s); 2416 execute_line (s); 2417 @} 2418 2419 free (line); 2420 @} 2421 exit (0); 2422@} 2423 2424/* Execute a command line. */ 2425int 2426execute_line (line) 2427 char *line; 2428@{ 2429 register int i; 2430 COMMAND *command; 2431 char *word; 2432 2433 /* Isolate the command word. */ 2434 i = 0; 2435 while (line[i] && whitespace (line[i])) 2436 i++; 2437 word = line + i; 2438 2439 while (line[i] && !whitespace (line[i])) 2440 i++; 2441 2442 if (line[i]) 2443 line[i++] = '\0'; 2444 2445 command = find_command (word); 2446 2447 if (!command) 2448 @{ 2449 fprintf (stderr, "%s: No such command for FileMan.\n", word); 2450 return (-1); 2451 @} 2452 2453 /* Get argument to command, if any. */ 2454 while (whitespace (line[i])) 2455 i++; 2456 2457 word = line + i; 2458 2459 /* Call the function. */ 2460 return ((*(command->func)) (word)); 2461@} 2462 2463/* Look up NAME as the name of a command, and return a pointer to that 2464 command. Return a NULL pointer if NAME isn't a command name. */ 2465COMMAND * 2466find_command (name) 2467 char *name; 2468@{ 2469 register int i; 2470 2471 for (i = 0; commands[i].name; i++) 2472 if (strcmp (name, commands[i].name) == 0) 2473 return (&commands[i]); 2474 2475 return ((COMMAND *)NULL); 2476@} 2477 2478/* Strip whitespace from the start and end of STRING. Return a pointer 2479 into STRING. */ 2480char * 2481stripwhite (string) 2482 char *string; 2483@{ 2484 register char *s, *t; 2485 2486 for (s = string; whitespace (*s); s++) 2487 ; 2488 2489 if (*s == 0) 2490 return (s); 2491 2492 t = s + strlen (s) - 1; 2493 while (t > s && whitespace (*t)) 2494 t--; 2495 *++t = '\0'; 2496 2497 return s; 2498@} 2499 2500/* **************************************************************** */ 2501/* */ 2502/* Interface to Readline Completion */ 2503/* */ 2504/* **************************************************************** */ 2505 2506char *command_generator PARAMS((const char *, int)); 2507char **fileman_completion PARAMS((const char *, int, int)); 2508 2509/* Tell the GNU Readline library how to complete. We want to try to complete 2510 on command names if this is the first word in the line, or on filenames 2511 if not. */ 2512initialize_readline () 2513@{ 2514 /* Allow conditional parsing of the ~/.inputrc file. */ 2515 rl_readline_name = "FileMan"; 2516 2517 /* Tell the completer that we want a crack first. */ 2518 rl_attempted_completion_function = fileman_completion; 2519@} 2520 2521/* Attempt to complete on the contents of TEXT. START and END bound the 2522 region of rl_line_buffer that contains the word to complete. TEXT is 2523 the word to complete. We can use the entire contents of rl_line_buffer 2524 in case we want to do some simple parsing. Return the array of matches, 2525 or NULL if there aren't any. */ 2526char ** 2527fileman_completion (text, start, end) 2528 const char *text; 2529 int start, end; 2530@{ 2531 char **matches; 2532 2533 matches = (char **)NULL; 2534 2535 /* If this word is at the start of the line, then it is a command 2536 to complete. Otherwise it is the name of a file in the current 2537 directory. */ 2538 if (start == 0) 2539 matches = rl_completion_matches (text, command_generator); 2540 2541 return (matches); 2542@} 2543 2544/* Generator function for command completion. STATE lets us know whether 2545 to start from scratch; without any state (i.e. STATE == 0), then we 2546 start at the top of the list. */ 2547char * 2548command_generator (text, state) 2549 const char *text; 2550 int state; 2551@{ 2552 static int list_index, len; 2553 char *name; 2554 2555 /* If this is a new word to complete, initialize now. This includes 2556 saving the length of TEXT for efficiency, and initializing the index 2557 variable to 0. */ 2558 if (!state) 2559 @{ 2560 list_index = 0; 2561 len = strlen (text); 2562 @} 2563 2564 /* Return the next name which partially matches from the command list. */ 2565 while (name = commands[list_index].name) 2566 @{ 2567 list_index++; 2568 2569 if (strncmp (name, text, len) == 0) 2570 return (dupstr(name)); 2571 @} 2572 2573 /* If no names matched, then return NULL. */ 2574 return ((char *)NULL); 2575@} 2576 2577/* **************************************************************** */ 2578/* */ 2579/* FileMan Commands */ 2580/* */ 2581/* **************************************************************** */ 2582 2583/* String to pass to system (). This is for the LIST, VIEW and RENAME 2584 commands. */ 2585static char syscom[1024]; 2586 2587/* List the file(s) named in arg. */ 2588com_list (arg) 2589 char *arg; 2590@{ 2591 if (!arg) 2592 arg = ""; 2593 2594 sprintf (syscom, "ls -FClg %s", arg); 2595 return (system (syscom)); 2596@} 2597 2598com_view (arg) 2599 char *arg; 2600@{ 2601 if (!valid_argument ("view", arg)) 2602 return 1; 2603 2604#if defined (__MSDOS__) 2605 /* more.com doesn't grok slashes in pathnames */ 2606 sprintf (syscom, "less %s", arg); 2607#else 2608 sprintf (syscom, "more %s", arg); 2609#endif 2610 return (system (syscom)); 2611@} 2612 2613com_rename (arg) 2614 char *arg; 2615@{ 2616 too_dangerous ("rename"); 2617 return (1); 2618@} 2619 2620com_stat (arg) 2621 char *arg; 2622@{ 2623 struct stat finfo; 2624 2625 if (!valid_argument ("stat", arg)) 2626 return (1); 2627 2628 if (stat (arg, &finfo) == -1) 2629 @{ 2630 perror (arg); 2631 return (1); 2632 @} 2633 2634 printf ("Statistics for `%s':\n", arg); 2635 2636 printf ("%s has %d link%s, and is %d byte%s in length.\n", 2637 arg, 2638 finfo.st_nlink, 2639 (finfo.st_nlink == 1) ? "" : "s", 2640 finfo.st_size, 2641 (finfo.st_size == 1) ? "" : "s"); 2642 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime)); 2643 printf (" Last access at: %s", ctime (&finfo.st_atime)); 2644 printf (" Last modified at: %s", ctime (&finfo.st_mtime)); 2645 return (0); 2646@} 2647 2648com_delete (arg) 2649 char *arg; 2650@{ 2651 too_dangerous ("delete"); 2652 return (1); 2653@} 2654 2655/* Print out help for ARG, or for all of the commands if ARG is 2656 not present. */ 2657com_help (arg) 2658 char *arg; 2659@{ 2660 register int i; 2661 int printed = 0; 2662 2663 for (i = 0; commands[i].name; i++) 2664 @{ 2665 if (!*arg || (strcmp (arg, commands[i].name) == 0)) 2666 @{ 2667 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); 2668 printed++; 2669 @} 2670 @} 2671 2672 if (!printed) 2673 @{ 2674 printf ("No commands match `%s'. Possibilities are:\n", arg); 2675 2676 for (i = 0; commands[i].name; i++) 2677 @{ 2678 /* Print in six columns. */ 2679 if (printed == 6) 2680 @{ 2681 printed = 0; 2682 printf ("\n"); 2683 @} 2684 2685 printf ("%s\t", commands[i].name); 2686 printed++; 2687 @} 2688 2689 if (printed) 2690 printf ("\n"); 2691 @} 2692 return (0); 2693@} 2694 2695/* Change to the directory ARG. */ 2696com_cd (arg) 2697 char *arg; 2698@{ 2699 if (chdir (arg) == -1) 2700 @{ 2701 perror (arg); 2702 return 1; 2703 @} 2704 2705 com_pwd (""); 2706 return (0); 2707@} 2708 2709/* Print out the current working directory. */ 2710com_pwd (ignore) 2711 char *ignore; 2712@{ 2713 char dir[1024], *s; 2714 2715 s = getcwd (dir, sizeof(dir) - 1); 2716 if (s == 0) 2717 @{ 2718 printf ("Error getting pwd: %s\n", dir); 2719 return 1; 2720 @} 2721 2722 printf ("Current directory is %s\n", dir); 2723 return 0; 2724@} 2725 2726/* The user wishes to quit using this program. Just set DONE non-zero. */ 2727com_quit (arg) 2728 char *arg; 2729@{ 2730 done = 1; 2731 return (0); 2732@} 2733 2734/* Function which tells you that you can't do this. */ 2735too_dangerous (caller) 2736 char *caller; 2737@{ 2738 fprintf (stderr, 2739 "%s: Too dangerous for me to distribute. Write it yourself.\n", 2740 caller); 2741@} 2742 2743/* Return non-zero if ARG is a valid argument for CALLER, else print 2744 an error message and return zero. */ 2745int 2746valid_argument (caller, arg) 2747 char *caller, *arg; 2748@{ 2749 if (!arg || !*arg) 2750 @{ 2751 fprintf (stderr, "%s: Argument required.\n", caller); 2752 return (0); 2753 @} 2754 2755 return (1); 2756@} 2757@end smallexample 2758