home | help 
libtecla(3)		    Library Functions Manual		     libtecla(3)

NAME
     libtecla - An interactive command-line input library.

SYNOPSIS
     cc ... -ltecla -lcurses

DESCRIPTION
     The  tecla  library provides programs with interactive command line editing
     facilities, similar to those of the unix tcsh shell. In addition to  simple
     command-line  editing,  it  supports  recall  of previously entered command
     lines, TAB completion of file names or other tokens, and in-line  wild-card
     expansion of filenames. The internal functions which perform file-name com-
     pletion  and wild-card expansion are also available externally for optional
     use by the calling program.

     The various parts of the library are documented in the following man pages:

       tecla(7) 	     -	Use level documentation of the
			     command-line editing facilities
			     provided by gl_get_line().
       gl_get_line(3)	     -	The interactive line-input module.
       gl_io_mode(3)	     -	How to use gl_get_line() in an
			     incremental, non-blocking fashion.
       cpl_complete_word(3)  -	The word completion module.
       ef_expand_file(3)     -	The filename expansion module.
       pca_lookup_file(3)    -	A directory-list based filename
			     lookup and completion module.

     In addition there is one optional application distributed with the library:

       enhance(1)	     -	Add command-line editing to third
				party applications.

THREAD SAFETY
     If the library is compiled with -D_POSIX_C_SOURCE=199506L,  reentrant  ver-
     sions  of as many functions as possible are used. This includes using getp-
     wuid_r() and getpwnam_r() instead of getpwuid() and getpwnam() when looking
     up the home directories of specific users in the password file (for  ~user/
     expansion),  and readdir_r() instead of readdir() for reading directory en-
     tries when doing filename completion. The reentrant version of the  library
     is usually called libtecla_r.a instead of libtecla.a, so if only the latter
     is  available,  it probably isn't the correct version to link with threaded
     programs.

     Reentrant functions for iterating through the password file  aren't  avail-
     able,  so	when  the library is compiled to be reentrant, TAB completion of
     incomplete usernames in ~username/ expressions is	disabled.  This  doesn't
     disable  expansion  of  complete  ~username  expressions, which can be done
     reentrantly, or expansion of the parts of filenames that  follow  them,  so
     this doesn't remove much functionality.

     The terminfo functions setupterm(), tigetstr(), tigetnum() and tputs() also
     aren't reentrant, but very few programs will want to interact with multiple
     terminals,  so  this  shouldn't  prevent  this  library  from being used in
     threaded programs.

LIBRARY VERSION NUMBER
     The version number of the library can be queried using the following  func-
     tion.

      void libtecla_version(int *major, int *minor, int *micro);

     On  return, this function records the three components of the libtecla ver-
     sion number in *major, *minor, *micro. The formal meaning of the three com-
     ponents is as follows.

      major - Incrementing this number implies that a change has
	      been made to the library's public interface, which
	      makes it binary incompatible  with programs that
	      were linked with previous shared versions of the
	      tecla library.

      minor - This number is incremented by one whenever
	      additional functionality, such as new functions or
	      modules, are added to the library.

      micro - This is incremented whenever modifications to the
	      library are made which make no changes to the
	      public interface, but which fix bugs and/or improve
	      the behind-the-scenes implementation.

TRIVIA
     In Spanish, a "tecla" is the key of a keyboard. Since this library  centers
     on keyboard input, and given that I wrote much of the library while working
     in Chile, this seemed like a suitable name.

FILES
     libtecla.a    -   The tecla library.
     libtecla.h    -   The tecla header file.
     ~/.teclarc    -   The tecla personal customization file.

SEE ALSO
     gl_get_line(3), tecla(7), gl_io_mode(3), ef_expand_file(3),
     cpl_complete_word(3), pca_lookup_file(3), enhance(1)

AUTHOR
     Martin Shepherd  (mcs@astro.caltech.edu)

ACKNOWLEDGMENTS
     Markus Gyger  - Lots of assistance, including help with
		     shared libraries, configuration information,
		     particularly for Solaris; modifications to
		     support C++ compilers, improvements for ksh
		     users, faster cursor motion, output
		     buffering, and changes to make gl_get_line()
		     8-bit clean.
     Mike MacFaden - Suggestions, feedback and testing that led
		     to many of the major new functions that were
		     added in version 1.4.0.
     Tim Eliseo    - Many vi-mode bindings and fixes.

								     libtecla(3)
home | help