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