Print this page 
12212 typos in some section 3tecla man pages
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3tecla/gl_get_line.3tecla
          +++ new/usr/src/man/man3tecla/gl_get_line.3tecla
↓ open down ↓ 17 lines elided ↑ open up ↑ 
  18   18  .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
  19   19  .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  20   20  .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  21   21  .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  22   22  .\"
  23   23  .\" Except as contained in this notice, the name of a copyright holder
  24   24  .\" shall not be used in advertising or otherwise to promote the sale, use
  25   25  .\" or other dealings in this Software without prior written authorization
  26   26  .\" of the copyright holder.
  27   27  .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
  28      -.TH GL_GET_LINE 3TECLA "April 9, 2016"
       28 +.TH GL_GET_LINE 3TECLA "January 18, 2020"
  29   29  .SH NAME
  30   30  gl_get_line, new_GetLine, del_GetLine, gl_customize_completion,
  31   31  gl_change_terminal, gl_configure_getline, gl_load_history, gl_save_history,
  32   32  gl_group_history, gl_show_history, gl_watch_fd, gl_inactivity_timeout,
  33   33  gl_terminal_size, gl_set_term_size, gl_resize_history, gl_limit_history,
  34   34  gl_clear_history, gl_toggle_history, gl_lookup_history, gl_state_of_history,
  35   35  gl_range_of_history, gl_size_of_history, gl_echo_mode, gl_replace_prompt,
  36   36  gl_prompt_style, gl_ignore_signal, gl_trap_signal, gl_last_signal,
  37   37  gl_completion_action, gl_register_action, gl_display_text, gl_return_status,
  38   38  gl_error_message, gl_catch_blocked, gl_list_signals, gl_bind_keyseq,
  39   39  gl_erase_terminal, gl_automatic_history, gl_append_history, gl_query_char,
  40   40  gl_read_char \- allow the user to compose an input line
  41   41  .SH SYNOPSIS
  42      -.LP
  43   42  .nf
  44   43  cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
  45   44  #include <stdio.h>
  46   45  #include <libtecla.h>
  47   46  
  48   47  \fBGetLine *\fR\fBnew_GetLine\fR(\fBsize_t\fR \fIlinelen\fR, \fBsize_t\fR \fIhistlen\fR);
  49   48  .fi
  50   49  
  51   50  .LP
  52   51  .nf
↓ open down ↓ 207 lines elided ↑ open up ↑ 
 260  259  .nf
 261  260  \fBint\fR \fBgl_automatic_history\fR(\fBGetLine *\fR\fIgl\fR, \fBint\fR \fIenable\fR);
 262  261  .fi
 263  262  
 264  263  .LP
 265  264  .nf
 266  265  \fBint\fR \fBgl_erase_terminal\fR(\fBGetLine *\fR\fIgl\fR);
 267  266  .fi
 268  267  
 269  268  .SH DESCRIPTION
 270      -.LP
 271  269  The \fBgl_get_line()\fR function is part of the \fBlibtecla\fR(3LIB) library.
 272  270  If the user is typing at a terminal, each call prompts them for a line of
 273  271  input, then provides interactive editing facilities, similar to those of the
 274  272  UNIX \fBtcsh\fR shell. In addition to simple command-line editing, it supports
 275  273  recall of previously entered command lines, TAB completion of file names, and
 276  274  in-line wild-card expansion of filenames. Documentation of both the user-level
 277  275  command-line editing features and all user configuration options can be found
 278  276  on the \fBtecla\fR(5) manual page.
 279  277  .SS "An Example"
 280      -.LP
 281  278  The following shows a complete example of how to use the \fBgl_get_line()\fR
 282  279  function to get input from the user:
 283  280  .sp
 284  281  .in +2
 285  282  .nf
 286  283  #include <stdio.h>
 287  284  #include <locale.h>
 288  285  #include <libtecla.h>
 289  286  
 290  287  int main(int argc, char *argv[])
↓ open down ↓ 24 lines elided ↑ open up ↑ 
 315  312  subsequent calls to the \fBgl_get_line()\fR function, including the history
 316  313  buffer for recording previously entered lines. Then one or more lines are read
 317  314  from the user, until either an error occurs, or the user types exit. Then
 318  315  finally the resources that were allocated by \fBnew_GetLine()\fR, are returned
 319  316  to the system by calling \fBdel_GetLine()\fR. Note the use of the \fINULL\fR
 320  317  return value of \fBdel_GetLine()\fR to make \fIgl\fR \fINULL\fR. This is a
 321  318  safety precaution. If the program subsequently attempts to pass \fIgl\fR to
 322  319  \fBgl_get_line()\fR, said function will complain, and return an error, instead
 323  320  of attempting to use the deleted resource object.
 324  321  .SS "The Functions Used In The Example"
 325      -.LP
 326  322  The \fBnew_GetLine()\fR function creates the resources used by the
 327  323  \fBgl_get_line()\fR function and returns an opaque pointer to the object that
 328  324  contains them. The maximum length of an input line is specified by the
 329  325  \fIlinelen\fR argument, and the number of bytes to allocate for storing history
 330  326  lines is set by the \fIhistlen\fR argument. History lines are stored
 331  327  back-to-back in a single buffer of this size. Note that this means that the
 332  328  number of history lines that can be stored at any given time, depends on the
 333  329  lengths of the individual lines. If you want to place an upper limit on the
 334  330  number of lines that can be stored, see the description of the
 335  331  \fBgl_limit_history()\fR function. If you do not want history at all, specify
↓ open down ↓ 32 lines elided ↑ open up ↑ 
 368  364  is part of the specified \fIgl\fR resource object, and thus should not be freed
 369  365  by the caller, or assumed to be unchanging from one call to the next. When
 370  366  reading from a user at a terminal, there will always be a newline character at
 371  367  the end of the returned line. When standard input is being taken from a pipe or
 372  368  a file, there will similarly be a newline unless the input line was too long to
 373  369  store in the internal buffer. In the latter case you should call
 374  370  \fBgl_get_line()\fR again to read the rest of the line. Note that this behavior
 375  371  makes \fBgl_get_line()\fR similar to \fBfgets\fR(3C). When \fBstdin\fR is not
 376  372  connected to a terminal, \fBgl_get_line()\fR simply calls \fBfgets()\fR.
 377  373  .SS "The Return Status Of \fBgl_get_line()\fR"
 378      -.LP
 379  374  The \fBgl_get_line()\fR function has two possible return values: a pointer to
 380  375  the completed input line, or \fINULL\fR. Additional information about what
 381  376  caused \fBgl_get_line()\fR to return is available both by inspecting
 382  377  \fBerrno\fR and by calling the \fBgl_return_status()\fR function.
 383  378  .sp
 384  379  .LP
 385  380  The following are the possible enumerated values returned by
 386  381  \fBgl_return_status()\fR:
 387  382  .sp
 388  383  .ne 2
↓ open down ↓ 37 lines elided ↑ open up ↑ 
 426  421  and the timeout callback function returned \fBGLTO_ABORT\fR. See
 427  422  \fBgl_inactivity_timeout()\fR for information about timeouts.
 428  423  .RE
 429  424  
 430  425  .sp
 431  426  .ne 2
 432  427  .na
 433  428  \fB\fBGLR_FDABORT\fR\fR
 434  429  .ad
 435  430  .RS 15n
 436      -An application I/O callback returned \fBGLFD_ABORT\fR. Ssee
      431 +An application I/O callback returned \fBGLFD_ABORT\fR. See
 437  432  \fBgl_watch_fd()\fR.
 438  433  .RE
 439  434  
 440  435  .sp
 441  436  .ne 2
 442  437  .na
 443  438  \fB\fBGLR_EOF\fR\fR
 444  439  .ad
 445  440  .RS 15n
 446  441  End of file reached. This can happen when input is coming from a file or a
↓ open down ↓ 21 lines elided ↑ open up ↑ 
 468  463  .LP
 469  464  The return value of \fBgl_error_message()\fR is a pointer to the message that
 470  465  occurred. If the \fIbuff\fR argument is \fINULL\fR, this will be a pointer to a
 471  466  buffer within \fIgl\fR whose value will probably change on the next call to any
 472  467  function associated with \fBgl_get_line()\fR. Otherwise, if a non-null
 473  468  \fIbuff\fR argument is provided, the error message, including a '\e0'
 474  469  terminator, will be written within the first \fIn\fR elements of this buffer,
 475  470  and the return value will be a pointer to the first element of this buffer. If
 476  471  the message will not fit in the provided buffer, it will be truncated to fit.
 477  472  .SS "Optional Prompt Formatting"
 478      -.LP
 479  473  Whereas by default the prompt string that you specify is displayed literally
 480  474  without any special interpretation of the characters within it, the
 481  475  \fBgl_prompt_style()\fR function can be used to enable optional formatting
 482  476  directives within the prompt.
 483  477  .sp
 484  478  .LP
 485  479  The \fIstyle\fR argument, which specifies the formatting style, can take any of
 486  480  the following values:
 487  481  .sp
 488  482  .ne 2
↓ open down ↓ 136 lines elided ↑ open up ↑ 
 625  619  .ne 2
 626  620  .na
 627  621  \fB\fBGL_LITERAL_PROMPT\fR\fR
 628  622  .ad
 629  623  .RS 21n
 630  624  In this style, the prompt string is printed literally. This is the default
 631  625  style.
 632  626  .RE
 633  627  
 634  628  .SS "Alternate Configuration Sources"
 635      -.LP
 636  629  By default users have the option of configuring the behavior of
 637  630  \fBgl_get_line()\fR with a configuration file called \fB\&.teclarc\fR in their
 638  631  home directories. The fact that all applications share this same configuration
 639  632  file is both an advantage and a disadvantage. In most cases it is an advantage,
 640  633  since it encourages uniformity, and frees the user from having to configure
 641  634  each application separately. In some applications, however, this single means
 642  635  of configuration is a problem. This is particularly true of embedded software,
 643  636  where there's no filesystem to read a configuration file from, and also in
 644  637  applications where a radically different choice of keybindings is needed to
 645  638  emulate a legacy keyboard interface. To cater for such cases, the
↓ open down ↓ 28 lines elided ↑ open up ↑ 
 674  667  
 675  668  .sp
 676  669  .LP
 677  670  The \fIapp_string\fR argument causes the calling application to start in
 678  671  \fBvi\fR(1) edit-mode, instead of the default \fBemacs\fR mode, and turns off
 679  672  the use of the terminal bell by the library. It then attempts to read
 680  673  system-wide configuration commands from an optional file called
 681  674  \fB/usr/share/myapp/teclarc\fR, then finally reads user-specific configuration
 682  675  commands from an optional \fB\&.teclarc\fR file in the user's home directory.
 683  676  Note that the arguments are listed in ascending order of priority, with the
 684      -contents of \fIapp_string\fR being potentially over riden by commands in
      677 +contents of \fIapp_string\fR being potentially overridden by commands in
 685  678  \fIapp_file\fR, and commands in \fIapp_file\fR potentially being overridden by
 686  679  commands in \fIuser_file\fR.
 687  680  .sp
 688  681  .LP
 689  682  You can call this function as many times as needed, the results being
 690  683  cumulative, but note that copies of any file names specified with the
 691  684  \fIapp_file\fR and \fIuser_file\fR arguments are recorded internally for
 692  685  subsequent use by the read-init-files key-binding function, so if you plan to
 693  686  call this function multiple times, be sure that the last call specifies the
 694  687  filenames that you want re-read when the user requests that the configuration
↓ open down ↓ 29 lines elided ↑ open up ↑ 
 724  717  subsequently reinstated if the user's binding is later unbound with either
 725  718  another call to this function, or a call to \fBgl_configure_getline()\fR.
 726  719  .sp
 727  720  .LP
 728  721  The \fIkeyseq\fR argument specifies the key sequence to be bound or unbound,
 729  722  and is expressed in the same way as in a \fB~/.teclarc\fR configuration file.
 730  723  The \fIaction\fR argument must either be a string containing the name of the
 731  724  action to bind the key sequence to, or it must be \fINULL\fR or \fB""\fR to
 732  725  unbind the key sequence.
 733  726  .SS "Customized Word Completion"
 734      -.LP
 735  727  If in your application you would like to have TAB completion complete other
 736  728  things in addition to or instead of filenames, you can arrange this by
 737  729  registering an alternate completion callback function with a call to the
 738  730  \fBgl_customize_completion()\fR function.
 739  731  .sp
 740  732  .LP
 741  733  The \fIdata\fR argument provides a way for your application to pass arbitrary,
 742  734  application-specific information to the callback function. This is passed to
 743  735  the callback every time that it is called. It might for example point to the
 744  736  symbol table from which possible completions are to be sought. The
↓ open down ↓ 4 lines elided ↑ open up ↑ 
 749  741  described in depth on the \fBcpl_complete_word\fR(3TECLA) manual page.
 750  742  .sp
 751  743  .LP
 752  744  The callback function is responsible for looking backwards in the input line
 753  745  from the point at which the user pressed TAB, to find the start of the word
 754  746  being completed. It then must lookup possible completions of this word, and
 755  747  record them one by one in the \fBWordCompletion\fR object that is passed to it
 756  748  as an argument, by calling the \fBcpl_add_completion()\fR function. If the
 757  749  callback function wants to provide filename completion in addition to its own
 758  750  specific completions, it has the option of itself calling the builtin filename
 759      -completion callback. This also is documented on the
      751 +completion callback. This is also documented in the
 760  752  \fBcpl_complete_word\fR(3TECLA) manual page.
 761  753  .sp
 762  754  .LP
 763  755  If you would like \fBgl_get_line()\fR to return the current input line when a
 764      -successful completion is been made, you can arrange this when you call
      756 +successful completion has been made, you can arrange this when you call
 765  757  \fBcpl_add_completion()\fR by making the last character of the continuation
 766  758  suffix a newline character. The input line will be updated to display the
 767      -completion, together with any contiuation suffix up to the newline character,
      759 +completion, together with any continuation suffix up to the newline character,
 768  760  and \fBgl_get_line()\fR will return this input line.
 769  761  .sp
 770  762  .LP
 771  763  If your callback function needs to write something to the terminal, it must
 772  764  call \fBgl_normal_io()\fR before doing so. This will start a new line after the
 773  765  input line that is currently being edited, reinstate normal terminal I/O, and
 774  766  notify \fBgl_get_line()\fR that the input line will need to be redrawn when the
 775  767  callback returns.
 776  768  .SS "Adding Completion Actions"
 777      -.LP
 778  769  In the previous section the ability to customize the behavior of the only
 779  770  default completion action, complete-word, was described. In this section the
 780  771  ability to install additional action functions, so that different types of word
 781  772  completion can be bound to different key sequences, is described. This is
 782  773  achieved by using the \fBgl_completion_action()\fR function.
 783  774  .sp
 784  775  .LP
 785  776  The \fIdata\fR and \fImatch_fn\fR arguments are as described on the
 786  777  \fBcpl_complete_word\fR(3TECLA) manual page, and specify the callback function
 787  778  that should be invoked to identify possible completions. The \fIlist_only\fR
↓ open down ↓ 4 lines elided ↑ open up ↑ 
 792  783  selected by specifying a value of 0, and the latter by specifying a value of 1.
 793  784  The \fIname\fR argument specifies the name by which configuration files and
 794  785  future invocations of this function should refer to the action. This must
 795  786  either be the name of an existing completion action to be changed, or be a new
 796  787  unused name for a new action. Finally, the \fIkeyseq\fR argument specifies the
 797  788  default key sequence to bind the action to. If this is \fINULL\fR, no new key
 798  789  sequence will be bound to the action.
 799  790  .sp
 800  791  .LP
 801  792  Beware that in order for the user to be able to change the key sequence that is
 802      -bound to actions that are installed in this manner, you shouldcall
      793 +bound to actions that are installed in this manner, you should call
 803  794  \fBgl_completion_action()\fR to install a given action for the first time
 804  795  between calling \fBnew_GetLine()\fR and the first call to \fBgl_get_line()\fR.
 805  796  Otherwise, when the user's configuration file is read on the first call to
 806  797  \fBgl_get_line()\fR, the name of the your additional action will not be known,
 807  798  and any reference to it in the configuration file will generate an error.
 808  799  .sp
 809  800  .LP
 810  801  As discussed for \fBgl_customize_completion()\fR, if your callback function
 811  802  needs to write anything to the terminal, it must call \fBgl_normal_io()\fR
 812  803  before doing so.
 813  804  .SS "Defining Custom Actions"
 814      -.LP
 815  805  Although the built-in key-binding actions are sufficient for the needs of most
 816  806  applications, occasionally a specialized application may need to define one or
 817  807  more custom actions, bound to application-specific key sequences. For example,
 818  808  a sales application would benefit from having a key sequence that displayed the
 819  809  part name that corresponded to a part number preceding the cursor. Such a
 820  810  feature is clearly beyond the scope of the built-in action functions. So for
 821  811  such special cases, the \fBgl_register_action()\fR function is provided.
 822  812  .sp
 823  813  .LP
 824  814  The \fBgl_register_action()\fR function lets the application register an
↓ open down ↓ 105 lines elided ↑ open up ↑ 
 930  920  .RE
 931  921  
 932  922  .sp
 933  923  .LP
 934  924  Note that the \fIname\fR argument of \fBgl_register_action()\fR specifies the
 935  925  name by which a user can refer to the action in their configuration file. This
 936  926  allows them to re-bind the action to an alternate key-sequence. In order for
 937  927  this to work, it is necessary to call \fBgl_register_action()\fR between
 938  928  calling \fBnew_GetLine()\fR and the first call to \fBgl_get_line()\fR.
 939  929  .SS "History Files"
 940      -.LP
 941  930  To save the contents of the history buffer before quitting your application and
 942  931  subsequently restore them when you next start the application, the
 943  932  \fBgl_save_history()\fR and \fBgl_load_history()\fR functions are provided.
 944  933  .sp
 945  934  .LP
 946  935  The \fIfilename\fR argument specifies the name to give the history file when
 947  936  saving, or the name of an existing history file, when loading. This may contain
 948  937  home directory and environment variable expressions, such as
 949  938  \fB~/.myapp_history\fR or \fB$HOME/.myapp_history\fR.
 950  939  .sp
↓ open down ↓ 8 lines elided ↑ open up ↑ 
 959  948  would specify "#" here. Whatever you choose for the comment character, you must
 960  949  specify the same prefix to \fBgl_load_history()\fR that you used when you
 961  950  called \fBgl_save_history()\fR to write the history file.
 962  951  .sp
 963  952  .LP
 964  953  The \fImax_lines\fR argument must be either -1 to specify that all lines in the
 965  954  history list be saved, or a positive number specifying a ceiling on how many of
 966  955  the most recent lines should be saved.
 967  956  .sp
 968  957  .LP
 969      -Both fuctions return non-zero on error, after writing an error message to
      958 +Both functions return non-zero on error, after writing an error message to
 970  959  \fBstderr\fR. Note that \fBgl_load_history()\fR does not consider the
 971  960  non-existence of a file to be an error.
 972  961  .SS "Multiple History Lists"
 973      -.LP
 974  962  If your application uses a single \fBGetLine\fR object for entering many
 975  963  different types of input lines, you might want \fBgl_get_line()\fR to
 976  964  distinguish the different types of lines in the history list, and only recall
 977  965  lines that match the current type of line. To support this requirement,
 978  966  \fBgl_get_line()\fR marks lines being recorded in the history list with an
 979  967  integer identifier chosen by the application. Initially this identifier is set
 980  968  to 0 by \fBnew_GetLine()\fR, but it can be changed subsequently by calling
 981  969  \fBgl_group_history()\fR.
 982  970  .sp
 983  971  .LP
↓ open down ↓ 2 lines elided ↑ open up ↑ 
 986  974  association between identifiers and historical input lines between program
 987  975  invocations, so you should choose fixed identifiers for the different types of
 988  976  input line used by your application.
 989  977  .sp
 990  978  .LP
 991  979  Whenever \fBgl_get_line()\fR appends a new input line to the history list, the
 992  980  current history identifier is recorded with it, and when it is asked to recall
 993  981  a historical input line, it only recalls lines that are marked with the current
 994  982  identifier.
 995  983  .SS "Displaying History"
 996      -.LP
 997  984  The history list can be displayed by calling \fBgl_show_history()\fR. This
 998  985  function displays the current contents of the history list to the \fBstdio\fR
 999  986  output stream \fIfp\fR. If the \fImax_lines\fR argument is greater than or
1000  987  equal to zero, then no more than this number of  the most recent lines will be
1001  988  displayed. If the \fIall_groups\fR argument is non-zero, lines from all history
1002  989  groups are displayed. Otherwise only those of the currently selected history
1003  990  group are displayed. The format string argument, \fIfmt\fR, determines how the
1004  991  line is displayed. This can contain arbitrary characters which are written
1005  992  verbatim, interleaved with any of the following format directives:
1006  993  .sp
↓ open down ↓ 57 lines elided ↑ open up ↑ 
1064 1051  .in +2
1065 1052  .nf
1066 1053  2001-11-20 10:23:34  Hello world
1067 1054  .fi
1068 1055  .in -2
1069 1056  
1070 1057  .sp
1071 1058  .LP
1072 1059  Note the inclusion of an explicit newline character in the format string.
1073 1060  .SS "Looking Up History"
1074      -.LP
1075 1061  The \fBgl_lookup_history()\fR function allows the calling application to look
1076 1062  up lines in the history list.
1077 1063  .sp
1078 1064  .LP
1079 1065  The \fIid\fR argument indicates which line to look up, where the first line
1080 1066  that was entered in the history list after \fBnew_GetLine()\fR was called is
1081 1067  denoted by 0, and subsequently entered lines are denoted with successively
1082 1068  higher numbers. Note that the range of lines currently preserved in the history
1083 1069  list can be queried by calling the \fBgl_range_of_history()\fR function. If the
1084 1070  requested line is in the history list, the details of the line are recorded in
1085 1071  the variable pointed to by the \fIhline\fR argument, and 1 is returned.
1086 1072  Otherwise 0 is returned, and the variable pointed to by \fIhline\fR is left
1087 1073  unchanged.
1088 1074  .sp
1089 1075  .LP
1090 1076  Beware that the string returned in \fIhline\fR->\fIline\fR is part of the
1091 1077  history buffer, so it must not be modified by the caller, and will be recycled
1092 1078  on the next call to any function that takes \fIgl\fR as its argument. Therefore
1093 1079  you should make a private copy of this string if you need to keep it.
1094 1080  .SS "Manual History Archival"
1095      -.LP
1096 1081  By default, whenever a line is entered by the user, it is automatically
1097 1082  appended to the history list, just before \fBgl_get_line()\fR returns the line
1098 1083  to the caller. This is convenient for the majority of applications, but there
1099 1084  are also applications that need finer-grained control over what gets added to
1100 1085  the history list. In such cases, the automatic addition of entered lines to the
1101 1086  history list can be turned off by calling the \fBgl_automatic_history()\fR
1102 1087  function.
1103 1088  .sp
1104 1089  .LP
1105 1090  If this function is called with its \fIenable\fR argument set to 0,
↓ open down ↓ 34 lines elided ↑ open up ↑ 
1140 1125  specified when \fBnew_GetLine()\fR was called), so it could not be archived.
1141 1126  .RE
1142 1127  
1143 1128  .sp
1144 1129  .LP
1145 1130  A textual description of the error can optionally be obtained by calling
1146 1131  \fBgl_error_message()\fR. Note that after such an error, the history list
1147 1132  remains in a valid state to receive new history lines, so there is little harm
1148 1133  in simply ignoring the return status of \fBgl_append_history()\fR.
1149 1134  .SS "Miscellaneous History Configuration"
1150      -.LP
1151 1135  If you wish to change the size of the history buffer that was originally
1152 1136  specified in the call to \fBnew_GetLine()\fR, you can do so with the
1153 1137  \fBgl_resize_history()\fR function.
1154 1138  .sp
1155 1139  .LP
1156 1140  The \fIhistlen\fR argument specifies the new size in bytes, and if you specify
1157 1141  this as 0, the buffer will be deleted.
1158 1142  .sp
1159 1143  .LP
1160 1144  As mentioned in the discussion of \fBnew_GetLine()\fR, the number of lines that
↓ open down ↓ 24 lines elided ↑ open up ↑ 
1185 1169  .LP
1186 1170  The \fBgl_toggle_history()\fR function allows you to toggle history on and off
1187 1171  without losing the current contents of the history list.
1188 1172  .sp
1189 1173  .LP
1190 1174  Setting the \fIenable\fR argument to 0 turns off the history mechanism, and
1191 1175  setting it to 1 turns it back on. When history is turned off, no new lines will
1192 1176  be added to the history list, and history lookup key-bindings will act as
1193 1177  though there is nothing in the history buffer.
1194 1178  .SS "Querying History Information"
1195      -.LP
1196 1179  The configured state of the history list can be queried with the
1197 1180  \fBgl_history_state()\fR function. On return, the status information is
1198 1181  recorded in the variable pointed to by the \fIstate\fR argument.
1199 1182  .sp
1200 1183  .LP
1201 1184  The \fBgl_range_of_history()\fR function returns the number and range of lines
1202 1185  in the history list. The return values are recorded in the variable pointed to
1203 1186  by the range argument. If the \fInlines\fR member of this structure is greater
1204 1187  than zero, then the oldest and newest members report the range of lines in the
1205 1188  list, and \fInewest\fR=\fIoldest\fR+\fInlines\fR-1. Otherwise they are both
1206 1189  zero.
1207 1190  .sp
1208 1191  .LP
1209 1192  The \fBgl_size_of_history()\fR function returns the total size of the history
1210 1193  buffer and the amount of the buffer that is currently occupied.
1211 1194  .sp
1212 1195  .LP
1213 1196  On return, the size information is recorded in the variable pointed to by the
1214 1197  \fIsize\fR argument.
1215 1198  .SS "Changing Terminals"
1216      -.LP
1217 1199  The \fBnew_GetLine()\fR constructor function assumes that input is to be read
1218 1200  from \fBstdin\fR and output written to \fBstdout\fR. The following function
1219 1201  allows you to switch to different input and output streams.
1220 1202  .sp
1221 1203  .LP
1222 1204  The \fIgl\fR argument is the object that was returned by \fBnew_GetLine()\fR.
1223 1205  The \fIinput_fp\fR argument specifies the stream to read from, and
1224 1206  \fIoutput_fp\fR specifies the stream to be written to. Only if both of these
1225 1207  refer to a terminal, will interactive terminal input be enabled. Otherwise
1226 1208  \fBgl_get_line()\fR will simply call \fBfgets()\fR to read command input. If
↓ open down ↓ 5 lines elided ↑ open up ↑ 
1232 1214  \fBnew_GetLine()\fR for example, passes the return value of
1233 1215  \fBgetenv\fR("TERM") in this argument. Note that if one or both of
1234 1216  \fIinput_fp\fR and \fIoutput_fp\fR do not refer to a terminal, then it is legal
1235 1217  to pass \fINULL\fR instead of a terminal type.
1236 1218  .sp
1237 1219  .LP
1238 1220  Note that if you want to pass file descriptors to \fBgl_change_terminal()\fR,
1239 1221  you can do this by creating \fBstdio\fR stream wrappers using the POSIX
1240 1222  \fBfdopen\fR(3C) function.
1241 1223  .SS "External Event Handling"
1242      -.LP
1243 1224  By default, \fBgl_get_line()\fR does not return until either a complete input
1244 1225  line has been entered by the user, or an error occurs. In programs that need to
1245 1226  watch for I/O from other sources than the terminal, there are two options.
1246 1227  .RS +4
1247 1228  .TP
1248 1229  .ie t \(bu
1249 1230  .el o
1250 1231  Use the functions described in the \fBgl_io_mode\fR(3TECLA) manual page to
1251 1232  switch \fBgl_get_line()\fR into non-blocking server mode. In this mode,
1252 1233  \fBgl_get_line()\fR becomes a non-blocking, incremental line-editing function
↓ open down ↓ 120 lines elided ↑ open up ↑ 
1373 1354  to the terminal, be sure to output a newline first, and when your callback
1374 1355  returns, tell \fBgl_get_line()\fR that the input line needs to be redrawn, by
1375 1356  returning the \fBGLFD_REFRESH\fR status code.
1376 1357  .sp
1377 1358  .LP
1378 1359  To remove a callback function that you previously registered for a given file
1379 1360  descriptor and event, simply call \fBgl_watch_fd()\fR with the same \fIfd\fR
1380 1361  and \fIevent\fR arguments, but with a \fIcallback\fR argument of 0. The
1381 1362  \fIdata\fR argument is ignored in this case.
1382 1363  .SS "Setting An Inactivity Timeout"
1383      -.LP
1384 1364  The \fBgl_inactivity_timeout()\fR function can be used to set or cancel an
1385 1365  inactivity timeout. Inactivity in this case refers both to keyboard input, and
1386 1366  to I/O on any file descriptors registered by prior and subsequent calls to
1387 1367  \fBgl_watch_fd()\fR.
1388 1368  .sp
1389 1369  .LP
1390 1370  The timeout is specified in the form of an integral number of seconds and an
1391 1371  integral number of nanoseconds, specified by the \fIsec\fR and \fInsec\fR
1392 1372  arguments, respectively. Subsequently, whenever no activity is seen for this
1393 1373  time period, the function specified by the \fIcallback\fR argument is called.
↓ open down ↓ 73 lines elided ↑ open up ↑ 
1467 1447  component, few computer clocks presently have resolutions that are finer than a
1468 1448  few milliseconds, so asking for less than a few milliseconds is equivalent to
1469 1449  requesting zero seconds on many systems. If this would be a problem, you should
1470 1450  base your timeout selection on the actual resolution of the host clock (for
1471 1451  example, by calling \fBsysconf\fR(\fB_SC_CLK_TCK\fR)).
1472 1452  .sp
1473 1453  .LP
1474 1454  To turn off timeouts, simply call \fBgl_inactivity_timeout()\fR with a
1475 1455  \fIcallback\fR argument of 0. The \fIdata\fR argument is ignored in this case.
1476 1456  .SS "Signal Handling Defaults"
1477      -.LP
1478 1457  By default, the \fBgl_get_line()\fR function intercepts a number of signals.
1479 1458  This is particularly important for signals that would by default terminate the
1480 1459  process, since the terminal needs to be restored to a usable state before this
1481 1460  happens. This section describes the signals that are trapped by default and how
1482 1461  \fBgl_get_line()\fR responds to them. Changing these defaults is the topic of
1483 1462  the following section.
1484 1463  .sp
1485 1464  .LP
1486 1465  When the following subset of signals are caught, \fBgl_get_line()\fR first
1487 1466  restores the terminal settings and signal handling to how they were before
↓ open down ↓ 217 lines elided ↑ open up ↑ 
1705 1684  .LP
1706 1685  Note that if \fBSIGKILL\fR or \fBSIGPOLL\fR, which by definition cannot be
1707 1686  caught, or any of the hardware generated exception signals, such as
1708 1687  \fBSIGSEGV\fR, \fBSIGBUS\fR, and \fBSIGFPE\fR, are received and unhandled while
1709 1688  \fBgl_get_line()\fR has the terminal in raw mode, the program will be
1710 1689  terminated without the terminal having been restored to a usable state. In
1711 1690  practice, job-control shells usually reset the terminal settings when a process
1712 1691  relinquishes the controlling terminal, so this is only a problem with older
1713 1692  shells.
1714 1693  .SS "Customized Signal Handling"
1715      -.LP
1716 1694  The previous section listed the signals that \fBgl_get_line()\fR traps by
1717 1695  default, and described how it responds to them. This section describes how to
1718 1696  both add and remove signals from the list of trapped signals, and how to
1719 1697  specify how \fBgl_get_line()\fR should respond to a given signal.
1720 1698  .sp
1721 1699  .LP
1722 1700  If you do not need \fBgl_get_line()\fR to do anything in response to a signal
1723 1701  that it normally traps, you can tell to \fBgl_get_line()\fR to ignore that
1724 1702  signal by calling \fBgl_ignore_signal()\fR.
1725 1703  .sp
↓ open down ↓ 132 lines elided ↑ open up ↑ 
1858 1836  only occasionally writes to the terminal, where using \fBGL_SUSPEND_LINE\fR
1859 1837  would cause the input line to be unnecessarily duplicated when nothing had been
1860 1838  written to the terminal. Such a signal handler, when it does write to the
1861 1839  terminal, should be sure to start a new line at the start of its first write,
1862 1840  by writing a new line before returning. If the signal arrives while the user is
1863 1841  entering a line that only occupies a signal terminal line, or if the cursor is
1864 1842  on the last terminal line of a longer input line, this will have the same
1865 1843  effect as \fBGL_SUSPEND_INPUT\fR. Otherwise it will start writing on a line
1866 1844  that already contains part of the displayed input line. This does not do any
1867 1845  harm, but it looks a bit ugly, which is why the \fBGL_SUSPEND_INPUT\fR
1868      -combination is better if you know that you are always going to be writting to
     1846 +combination is better if you know that you are always going to be writing to
1869 1847  the terminal.
1870 1848  .sp
1871 1849  .LP
1872 1850  The \fIafter\fR argument, which determines what \fBgl_get_line()\fR does after
1873 1851  the application's signal handler returns (if  it returns), can take any one of
1874 1852  the following values:
1875 1853  .sp
1876 1854  .ne 2
1877 1855  .na
1878 1856  \fB\fBGLS_RETURN\fR\fR
↓ open down ↓ 27 lines elided ↑ open up ↑ 
1906 1884  
1907 1885  .sp
1908 1886  .LP
1909 1887  The \fIerrno_value\fR argument is intended to be combined with the
1910 1888  \fBGLS_ABORT\fR option, telling \fBgl_get_line()\fR what to set the standard
1911 1889  \fBerrno\fR variable to before returning \fINULL\fR to the calling program. It
1912 1890  can also, however, be used with the \fBGL_RETURN\fR option, in case you want to
1913 1891  have a way to distinguish between an input line that was entered using the
1914 1892  return key, and one that was entered by the receipt of a signal.
1915 1893  .SS "Reliable Signal Handling"
1916      -.LP
1917 1894  Signal handling is surprisingly hard to do reliably without race conditions. In
1918 1895  \fBgl_get_line()\fR a lot of care has been taken to allow applications to
1919 1896  perform reliable signal handling around \fBgl_get_line()\fR. This section
1920 1897  explains how to make use of this.
1921 1898  .sp
1922 1899  .LP
1923 1900  As an example of the problems that can arise if the application is not written
1924 1901  correctly, imagine that one's application has a \fBSIGINT\fR signal handler
1925 1902  that sets a global flag. Now suppose that the application tests this flag just
1926 1903  before invoking \fBgl_get_line()\fR. If a \fBSIGINT\fR signal happens to be
↓ open down ↓ 193 lines elided ↑ open up ↑ 
2120 2097  7.
2121 2098  \fBgl_get_line()\fR then either resumes trying to read a character, or
2122 2099  aborts, depending on the configuration of the signal that was caught.
2123 2100  .RE
2124 2101  .sp
2125 2102  .LP
2126 2103  What the above steps do in essence is to take asynchronously delivered signals
2127 2104  and handle them synchronously, one at a time, at a point in the code where
2128 2105  \fBgl_get_line()\fR has complete control over its environment.
2129 2106  .SS "The Terminal Size"
2130      -.LP
2131 2107  On most systems the combination of the \fBTIOCGWINSZ\fR ioctl and the
2132 2108  \fBSIGWINCH\fR signal is used to maintain an accurate idea of the terminal
2133 2109  size. The terminal size is newly queried every time that \fBgl_get_line()\fR is
2134 2110  called and whenever a \fBSIGWINCH\fR signal is received.
2135 2111  .sp
2136 2112  .LP
2137 2113  On the few systems where this mechanism is not available, at startup
2138 2114  \fBnew_GetLine()\fR first looks for the \fBLINES\fR and \fBCOLUMNS\fR
2139 2115  environment variables. If these are not found, or they contain unusable values,
2140 2116  then if a terminal information database like \fBterminfo\fR or \fBtermcap\fR is
↓ open down ↓ 30 lines elided ↑ open up ↑ 
2171 2147  .sp
2172 2148  .LP
2173 2149  This function first updates \fBgl_get_line()\fR's fallback terminal dimensions,
2174 2150  then records its findings in the return value.
2175 2151  .sp
2176 2152  .LP
2177 2153  The \fIdef_ncolumn\fR and \fIdef_nline\fR arguments specify the default number
2178 2154  of terminal columns and lines to use if the terminal size cannot be determined
2179 2155  by ioctl(\fBTIOCGWINSZ\fR) or environment variables.
2180 2156  .SS "Hiding What You Type"
2181      -.LP
2182 2157  When entering sensitive information, such as passwords, it is best not to have
2183 2158  the text that you are entering echoed on the terminal. Furthermore, such text
2184 2159  should not be recorded in the history list, since somebody finding your
2185 2160  terminal unattended could then recall it, or somebody snooping through your
2186 2161  directories could see it in your history file. With this in mind, the
2187 2162  \fBgl_echo_mode()\fR function allows you to toggle on and off the display and
2188 2163  archival of any text that is subsequently entered in calls to
2189 2164  \fBgl_get_line()\fR.
2190 2165  .sp
2191 2166  .LP
↓ open down ↓ 6 lines elided ↑ open up ↑ 
2198 2173  is -1, then the echoing mode is left unchanged, which allows you to
2199 2174  non-destructively query the current setting through the return value. In all
2200 2175  cases, the return value of the function is 0 if echoing was disabled before the
2201 2176  function was called, and 1 if it was enabled.
2202 2177  .sp
2203 2178  .LP
2204 2179  When echoing is turned off, note that although tab completion will invisibly
2205 2180  complete your prefix as far as possible, ambiguous completions will not be
2206 2181  displayed.
2207 2182  .SS "Single Character Queries"
2208      -.LP
2209 2183  Using \fBgl_get_line()\fR to query the user for a single character reply, is
2210 2184  inconvenient for the user, since they must hit the enter or return key before
2211 2185  the character that they typed is returned to the program. Thus the
2212 2186  \fBgl_query_char()\fR function has been provided for single character queries
2213 2187  like this.
2214 2188  .sp
2215 2189  .LP
2216 2190  This function displays the specified prompt at the start of a new line, and
2217 2191  waits for the user to type a character. When the user types a character,
2218 2192  \fBgl_query_char()\fR displays it to the right of the prompt, starts a newline,
↓ open down ↓ 27 lines elided ↑ open up ↑ 
2246 2220  the process resumes, the prompt is redisplayed, and \fBgl_query_char()\fR
2247 2221  resumes waiting for the user to type a character.
2248 2222  .sp
2249 2223  .LP
2250 2224  Note that in non-blocking server mode, if an incomplete input line is in the
2251 2225  process of being read when \fBgl_query_char()\fR is called, the partial input
2252 2226  line is discarded, and erased from the terminal, before the new prompt is
2253 2227  displayed. The next call to \fBgl_get_line()\fR will thus start editing a new
2254 2228  line.
2255 2229  .SS "Reading Raw Characters"
2256      -.LP
2257 2230  Whereas the \fBgl_query_char()\fR function visibly prompts the user for a
2258 2231  character, and displays what they typed, the \fBgl_read_char()\fR function
2259 2232  reads a signal character from the user, without writing anything to the
2260 2233  terminal, or perturbing any incompletely entered input line. This means that it
2261 2234  can be called not only from between calls to \fBgl_get_line()\fR, but also from
2262 2235  callback functions that the application has registered to be called by
2263 2236  \fBgl_get_line()\fR.
2264 2237  .sp
2265 2238  .LP
2266 2239  On success, the return value of \fBgl_read_char()\fR is the character that was
↓ open down ↓ 1 lines elided ↑ open up ↑ 
2268 2241  can be called to find out what went wrong. Possibilities include the optional
2269 2242  inactivity timer going off, the receipt of a signal that is configured to abort
2270 2243  \fBgl_get_line()\fR, or terminal I/O blocking, when in non-blocking server-I/O
2271 2244  mode.
2272 2245  .sp
2273 2246  .LP
2274 2247  Beware that certain keyboard keys, such as function keys, and cursor keys,
2275 2248  usually generate at least three characters each, so a single call to
2276 2249  \fBgl_read_char()\fR will not be enough to identify such keystrokes.
2277 2250  .SS "Clearing The Terminal"
2278      -.LP
2279 2251  The calling program can clear the terminal by calling
2280 2252  \fBgl_erase_terminal()\fR. In non-blocking server-I/O mode, this function also
2281 2253  arranges for the current input line to be redrawn from scratch when
2282 2254  \fBgl_get_line()\fR is next called.
2283 2255  .SS "Displaying Text Dynamically"
2284      -.LP
2285 2256  Between calls to \fBgl_get_line()\fR, the \fBgl_display_text()\fR function
2286 2257  provides a convenient way to display paragraphs of text, left-justified and
2287 2258  split over one or more terminal lines according to the constraints of the
2288 2259  current width of the terminal. Examples of the use of this function may be
2289 2260  found in the demo programs, where it is used to display introductions. In those
2290 2261  examples the advanced use  of optional prefixes, suffixes and filled lines to
2291 2262  draw a box around the text is also illustrated.
2292 2263  .sp
2293 2264  .LP
2294 2265  If \fIgl\fR is not currently connected to a terminal, for example if the output
↓ open down ↓ 22 lines elided ↑ open up ↑ 
2317 2288  \fBgl_display_text()\fR is the ending column index of the cursor, by passing
2318 2289  the return value of one call to the start argument of the next call, a
2319 2290  paragraph that is broken between more than one string can be composed by
2320 2291  calling \fBgl_display_text()\fR for each successive portion of the paragraph.
2321 2292  Note that literal newline characters are necessary at the end of each paragraph
2322 2293  to force a new line to be started.
2323 2294  .sp
2324 2295  .LP
2325 2296  On error, \fBgl_display_text()\fR returns -1.
2326 2297  .SS "Callback Function Facilities"
2327      -.LP
2328 2298  Unless otherwise stated, callback functions such as tab completion callbacks
2329 2299  and event callbacks should not call any functions in this module. The following
2330 2300  functions, however, are designed specifically to be used by callback functions.
2331 2301  .sp
2332 2302  .LP
2333 2303  Calling the \fBgl_replace_prompt()\fR function from a callback tells
2334 2304  \fBgl_get_line()\fR to display a different prompt when the callback returns.
2335 2305  Except in non-blocking server mode, it has no effect if used between calls to
2336 2306  \fBgl_get_line()\fR. In non-blocking server mode, when used between two calls
2337 2307  to \fBgl_get_line()\fR that are operating on the same input line, the current
2338 2308  input line will be re-drawn with the new prompt on the following call to
2339 2309  \fBgl_get_line()\fR.
2340 2310  .SS "International Character Sets"
2341      -.LP
2342 2311  Since \fBlibtecla\fR(3LIB) version 1.4.0, \fBgl_get_line()\fR has been 8-bit
2343 2312  clean. This means that all 8-bit characters that are printable in the user's
2344 2313  current locale are now displayed verbatim and included in the returned input
2345 2314  line. Assuming that the calling program correctly contains a call like the
2346 2315  following,
2347 2316  .sp
2348 2317  .in +2
2349 2318  .nf
2350 2319  setlocale(LC_CTYPE, "")
2351 2320  .fi
↓ open down ↓ 13 lines elided ↑ open up ↑ 
2365 2334  locale -a
2366 2335  .fi
2367 2336  .in -2
2368 2337  .sp
2369 2338  
2370 2339  .sp
2371 2340  .LP
2372 2341  at the shell prompt. Further documentation on how the user can make use of this
2373 2342  to enter international characters can be found in the \fBtecla\fR(5) man page.
2374 2343  .SS "Thread Safety"
2375      -.LP
2376 2344  Unfortunately neither \fBterminfo\fR nor \fBtermcap\fR were designed to be
2377 2345  reentrant, so you cannot safely use the functions of the getline module in
2378 2346  multiple threads (you can use the separate file-expansion and word-completion
2379 2347  modules in multiple threads, see the corresponding man pages for details).
2380 2348  However due to the use of POSIX reentrant functions for looking up home
2381 2349  directories, it is safe to use this module from a single thread of a
2382 2350  multi-threaded program, provided that your other threads do not use any
2383 2351  \fBtermcap\fR or \fBterminfo\fR functions.
2384 2352  .SH ATTRIBUTES
2385      -.LP
2386 2353  See \fBattributes\fR(5) for descriptions of the following attributes:
2387 2354  .sp
2388 2355  
2389 2356  .sp
2390 2357  .TS
2391 2358  box;
2392 2359  c | c
2393 2360  l | l .
2394 2361  ATTRIBUTE TYPE  ATTRIBUTE VALUE
2395 2362  _
2396 2363  Interface Stability     Committed
2397 2364  _
2398 2365  MT-Level        MT-Safe
2399 2366  .TE
2400 2367  
2401 2368  .SH SEE ALSO
2402      -.LP
2403 2369  \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
2404 2370  \fBgl_io_mode\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBpca_lookup_file\fR(3TECLA),
2405 2371  \fBattributes\fR(5), \fBtecla\fR(5)
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX