libtecla - zygaena/hammerhead

root / base / usr / src / lib / libtecla
libtecla Plain Text 29566 lines 936.8 KB
#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#
#
# Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#

include		../Makefile.lib

HDRS =		libtecla.h
CHECKHDRS =
HDRDIR =	.

# Hammerhead: amd64-only
SUBDIRS = $(MACH64)

all :		TARGET = all
clean :	TARGET = clean
clobber :	TARGET = clobber
install :	TARGET = install

.KEEP_STATE:

all clean clobber install: $(SUBDIRS)

install_h:	$(ROOTHDRS)

check:		$(CHECKHDRS)

$(SUBDIRS):  FRC
	@cd $@; pwd; $(MAKE) $(TARGET)

FRC:

include ../Makefile.targ
include ../../Makefile.msg.targ
#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#
#
# Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# Copyright (c) 2018, Joyent, Inc.

LIBRARY=	libtecla.a
VERS=		.1
OBJECTS=	getline.o keytab.o freelist.o strngmem.o hash.o history.o \
	direader.o homedir.o pathutil.o expand.o stringrp.o cplfile.o \
	cplmatch.o pcache.o version.o chrqueue.o ioutil.o errmsg.o

include ../../Makefile.lib

SRCDIR =	../common
LIBS =		$(DYNLIB)
LDLIBS +=	-lc
$(DYNLIB) :	LDLIBS += -lcurses
CPPFLAGS +=	-I$(SRCDIR) -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 \
	-DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STRING_H=1 \
	-DHAVE_MEMORY_H=1 -DHAVE_STRINGS_H=1 -DHAVE_INTTYPES_H=1 \
	-DHAVE_STDINT_H=1 -DHAVE_UNISTD_H=1 -DUSE_TERMINFO=1 -DHAVE_CURSES_H=1 \
	-DHAVE_TERM_H=1 -DHAVE_SYS_SELECT_H=1 -DHAVE_SELECT=1 \
	-DHAVE_SYSV_PTY=1 -D__EXTENSIONS__=1 -D_POSIX_C_SOURCE=199506L \
	-DPREFER_REENTRANT

CERRWARN +=	-Wno-type-limits

# not linted
SMATCH=off

.KEEP_STATE:

all:	$(LIBS)


include ../../Makefile.targ
#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#
#
# Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"%Z%%M%	%I%	%E% SMI"
#
# lib/libtecla/README
#

The source code here is derived from libtecla version 1.6 plus one bug
fix (6353321) from 1.6.1 .
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 * 
 * All rights reserved.
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 * 
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
TECLA SOFTWARE
#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License, Version 1.0 only
# (the "License").  You may not use this file except in compliance
# with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#
#
# Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#

include ../Makefile.com
include ../../Makefile.lib.64

install: all $(ROOTLIBS64) $(ROOTLINKS64)
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <errno.h>

#include "ioutil.h"
#include "chrqueue.h"
#include "freelist.h"
#include "errmsg.h"

/*
 * Set the number of bytes allocated to each node of the list of
 * character buffers. This facility is designed principally as
 * an expandible I/O output buffer, so use the stdio buffer size
 * where available.
 */
#ifdef BUFSIZ
#define GL_CQ_SIZE BUFSIZ
#else
#define GL_CQ_SIZE 512
#endif

/*
 * The queue is contained in a list of fixed sized buffers. New nodes
 * are appended to this list as needed to accomodate newly added bytes.
 * Old nodes at the head of the list are removed as they are emptied.
 */
typedef struct CqCharBuff CqCharBuff;
struct CqCharBuff {
  CqCharBuff *next;          /* The next node in the list of buffers */
  char bytes[GL_CQ_SIZE];    /* The fixed size buffer of this node */
};

/*
 * Define the structure that is used to contain a list of character
 * buffers.
 */
struct GlCharQueue {
  ErrMsg *err;          /* A buffer in which to record error messages */
  FreeList *bufmem;     /* A free-list of CqCharBuff structures */
  struct {
    CqCharBuff *head;   /* The head of the list of output buffers */
    CqCharBuff *tail;   /* The tail of the list of output buffers */
  } buffers;
  int nflush;           /* The total number of characters that have been */
                        /*  flushed from the start of the queue since */
                        /*  _glq_empty_queue() was last called. */
  int ntotal;           /* The total number of characters that have been */
                        /*  appended to the queue since _glq_empty_queue() */
                        /*  was last called. */
};

/*.......................................................................
 * Create a new GlCharQueue object.
 *
 * Output:
 *  return  GlCharQueue *  The new object, or NULL on error.
 */
GlCharQueue *_new_GlCharQueue(void)
{
  GlCharQueue *cq;  /* The object to be returned */
/*
 * Allocate the container.
 */
  cq = malloc(sizeof(GlCharQueue));
  if(!cq) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_GlCharQueue().
 */
  cq->err = NULL;
  cq->bufmem = NULL;
  cq->buffers.head = NULL;
  cq->buffers.tail = NULL;
  cq->nflush = cq->ntotal = 0;
/*
 * Allocate a place to record error messages.
 */
  cq->err = _new_ErrMsg();
  if(!cq->err)
    return _del_GlCharQueue(cq);
/*
 * Allocate the freelist of CqCharBuff structures.
 */
  cq->bufmem = _new_FreeList(sizeof(CqCharBuff), 1);
  if(!cq->bufmem)
    return _del_GlCharQueue(cq);
  return cq;
}

/*.......................................................................
 * Delete a GlCharQueue object.
 *
 * Input:
 *  cq     GlCharQueue *  The object to be deleted.
 * Output:
 *  return GlCharQueue *  The deleted object (always NULL).
 */
GlCharQueue *_del_GlCharQueue(GlCharQueue *cq)
{
  if(cq) {
    cq->err = _del_ErrMsg(cq->err);
    cq->bufmem = _del_FreeList(cq->bufmem, 1);
    free(cq);
  };
  return NULL;
}

/*.......................................................................
 * Append an array of n characters to a character queue.
 *
 * Input:
 *  cq        GlCharQueue *  The queue to append to.
 *  chars      const char *  The array of n characters to be appended.
 *  n                 int    The number of characters in chars[].
 *  write_fn  GL_WRITE_FN *  The function to call to output characters,
 *                           or 0 to simply discard the contents of the
 *                           queue. This will be called whenever the
 *                           buffer becomes full. If it fails to release
 *                           any space, the buffer will be extended.
 *  data             void *  Anonymous data to pass to write_fn().
 * Output:
 *  return        int    The number of characters successfully
 *                       appended. This will only be < n on error.
 */
int _glq_append_chars(GlCharQueue *cq, const char *chars, int n,
		      GlWriteFn *write_fn, void *data)
{
  int ndone = 0;  /* The number of characters appended so far */
/*
 * Check the arguments.
 */
  if(!cq || !chars) {
    errno = EINVAL;
    return 0;
  };
/*
 * The appended characters may have to be split between multiple
 * buffers, so loop for each buffer.
 */
  while(ndone < n) {
    int ntodo;     /* The number of characters remaining to be appended */
    int nleft;     /* The amount of space remaining in cq->buffers.tail */
    int nnew;      /* The number of characters to append to cq->buffers.tail */
/*
 * Compute the offset at which the next character should be written
 * into the tail buffer segment.
 */
    int boff = cq->ntotal % GL_CQ_SIZE;
/*
 * Since we don't allocate a new buffer until we have at least one
 * character to write into it, if boff is 0 at this point, it means
 * that we hit the end of the tail buffer segment on the last append,
 * so we need to allocate a new one.
 *
 * If allocating this new node will require a call to malloc(), as
 * opposed to using a currently unused node in the freelist, first try
 * flushing the current contents of the buffer to the terminal. When
 * write_fn() uses blocking I/O, this stops the buffer size ever getting
 * bigger than a single buffer node. When it is non-blocking, it helps
 * to keep the amount of memory, but it isn't gauranteed to do so.
 */
    if(boff == 0 && _idle_FreeListNodes(cq->bufmem) == 0) {
      switch(_glq_flush_queue(cq, write_fn, data)) {
      case GLQ_FLUSH_DONE:
	break;
      case GLQ_FLUSH_AGAIN:
	errno = 0;          /* Don't confuse the caller */
	break;
      default:
	return ndone;       /* Error */
      };
      boff = cq->ntotal % GL_CQ_SIZE;
    };
/*
 * Since we don't allocate a new buffer until we have at least one
 * character to write into it, if boff is 0 at this point, it means
 * that we hit the end of the tail buffer segment on the last append,
 * so we need to allocate a new one.
 */
    if(boff == 0) {
/*
 * Allocate the new node.
 */
      CqCharBuff *node = (CqCharBuff *) _new_FreeListNode(cq->bufmem);
      if(!node) {
	_err_record_msg(cq->err, "Insufficient memory to buffer output.",
			END_ERR_MSG);
	return ndone;
      };
/*
 * Initialize the node.
 */
      node->next = NULL;
/*
 * Append the new node to the tail of the list.
 */
      if(cq->buffers.tail)
	cq->buffers.tail->next = node;
      else
	cq->buffers.head = node;
      cq->buffers.tail = node;
    };
/*
 * How much room is there for new characters in the current tail node?
 */
    nleft = GL_CQ_SIZE - boff;
/*
 * How many characters remain to be appended?
 */
    ntodo = n - ndone;
/*
 * How many characters should we append to the current tail node?
 */
    nnew = nleft < ntodo ? nleft : ntodo;
/*
 * Append the latest prefix of nnew characters.
 */
    memcpy(cq->buffers.tail->bytes + boff, chars + ndone, nnew);
    cq->ntotal += nnew;
    ndone += nnew;
  };
/*
 * Return the count of the number of characters successfully appended.
 */
  return ndone;
}

/*.......................................................................
 * Discard the contents of a queue of characters.
 *
 * Input:
 *  cq    GlCharQueue *  The queue to clear.
 */
void _glq_empty_queue(GlCharQueue *cq)
{
  if(cq) {
/*
 * Return all list nodes to their respective free-lists.
 */
    _rst_FreeList(cq->bufmem);
/*
 * Mark the lists as empty.
 */
    cq->buffers.head = cq->buffers.tail = NULL;
    cq->nflush = cq->ntotal = 0;
  };
}

/*.......................................................................
 * Return a count of the number of characters currently in the queue.
 *
 * Input:
 *  cq    GlCharQueue *  The queue of interest.
 * Output:
 *  return        int    The number of characters in the queue.
 */
int _glq_char_count(GlCharQueue *cq)
{
  return (cq && cq->buffers.head) ? (cq->ntotal - cq->nflush) : 0;
}

/*.......................................................................
 * Write as many characters as possible from the start of a character
 * queue via a given output callback function, removing those written
 * from the queue.
 *
 * Input:
 *  cq        GlCharQueue *  The queue to write characters from.
 *  write_fn  GL_WRITE_FN *  The function to call to output characters,
 *                           or 0 to simply discard the contents of the
 *                           queue.
 *  data             void *  Anonymous data to pass to write_fn().
 * Output:
 *  return   GlFlushState    The status of the flush operation:
 *                             GLQ_FLUSH_DONE  -  The flush operation
 *                                                completed successfully.
 *                             GLQ_FLUSH_AGAIN -  The flush operation
 *                                                couldn't be completed
 *                                                on this call. Call this
 *                                                function again when the
 *                                                output channel can accept
 *                                                further output.
 *                             GLQ_FLUSH_ERROR    Unrecoverable error.
 */
GlqFlushState _glq_flush_queue(GlCharQueue *cq, GlWriteFn *write_fn,
			       void *data)
{
/*
 * Check the arguments.
 */
  if(!cq) {
    errno = EINVAL;
    return GLQ_FLUSH_ERROR;
  };
/*
 * If possible keep writing until all of the chained buffers have been
 * emptied and removed from the list.
 */
  while(cq->buffers.head) {
/*
 * Are we looking at the only node in the list?
 */
    int is_tail = cq->buffers.head == cq->buffers.tail;
/*
 * How many characters more than an exact multiple of the buffer-segment
 * size have been added to the buffer so far?
 */
    int nmodulo = cq->ntotal % GL_CQ_SIZE;
/*
 * How many characters of the buffer segment at the head of the list
 * have been used? Note that this includes any characters that have
 * already been flushed. Also note that if nmodulo==0, this means that
 * the tail buffer segment is full. The reason for this is that we
 * don't allocate new tail buffer segments until there is at least one
 * character to be added to them.
 */
    int nhead = (!is_tail || nmodulo == 0) ? GL_CQ_SIZE : nmodulo;
/*
 * How many characters remain to be flushed from the buffer
 * at the head of the list?
 */
    int nbuff = nhead - (cq->nflush % GL_CQ_SIZE);
/*
 * Attempt to write this number.
 */
    int nnew = write_fn(data, cq->buffers.head->bytes +
			cq->nflush % GL_CQ_SIZE, nbuff);
/*
 * Was anything written?
 */
    if(nnew > 0) {
/*
 * Increment the count of the number of characters that have
 * been flushed from the head of the queue.
 */
      cq->nflush += nnew;
/*
 * If we succeded in writing all of the contents of the current
 * buffer segment, remove it from the queue.
 */
      if(nnew == nbuff) {
/*
 * If we just emptied the last node left in the list, then the queue is
 * now empty and should be reset.
 */
	if(is_tail) {
	  _glq_empty_queue(cq);
	} else {
/*
 * Get the node to be removed from the head of the list.
 */
	  CqCharBuff *node = cq->buffers.head;
/*
 * Make the node that follows it the new head of the queue.
 */
	  cq->buffers.head = node->next;
/*
 * Return it to the freelist.
 */
	  node = (CqCharBuff *) _del_FreeListNode(cq->bufmem, node);
	};
      };
/*
 * If the write blocked, request that this function be called again
 * when space to write next becomes available.
 */
    } else if(nnew==0) {
      return GLQ_FLUSH_AGAIN;
/*
 * I/O error.
 */
    } else {
      _err_record_msg(cq->err, "Error writing to terminal", END_ERR_MSG);
      return GLQ_FLUSH_ERROR;
    };
  };
/*
 * To get here the queue must now be empty.
 */
  return GLQ_FLUSH_DONE;
}

/*.......................................................................
 * Return extra information (ie. in addition to that provided by errno)
 * about the last error to occur in any of the public functions of this
 * module.
 *
 * Input:
 *  cq     GlCharQueue *  The container of the history list.
 * Output:
 *  return  const char *  A pointer to the internal buffer in which
 *                        the error message is temporarily stored.
 */
const char *_glq_last_error(GlCharQueue *cq)
{
  return cq ? _err_get_msg(cq->err) : "NULL GlCharQueue argument";
}
#ifndef chrqueue_h
#define chrqueue_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*-----------------------------------------------------------------------
 * This module implements a queue of characters to be processed in some
 * way. It is used by gl_get_line() to maintain a queue of characters
 * to be sent to a remote terminal. Characters are recorded in a
 * dynamically extensible list of fixed sized buffers.
 */

typedef struct GlCharQueue GlCharQueue;

/*
 * Create a new character queue.
 */
GlCharQueue *_new_GlCharQueue(void);

/*
 * Delete a redundant character queue.
 */
GlCharQueue *_del_GlCharQueue(GlCharQueue *cq);

/*
 * Append an array of n characters to a character queue.
 */
int _glq_append_chars(GlCharQueue *cq, const char *chars, int n,
		      GlWriteFn *write_fn, void *data);

/*
 * Clear a character queue.
 */
void _glq_empty_queue(GlCharQueue *cq);

/*
 * Return a count of the number of characters in the queue.
 */
int _glq_char_count(GlCharQueue *cq);

/*
 * A structure of the following type is used by _glq_peek_chars() to
 * return characters at the start of the queue.
 */
typedef struct {
  const char *buff;  /* A pointer to the first undeleted byte in the */
                     /*  first buffer of the queue. */
  int nbuff;         /* The number of characters in buff[] */
} GlCharQueueBuff;

/*
 * Enumerator values of the following type are returned by
 * _glq_flush_queue() to indicate the status of the flush operation.
 */
typedef enum {
  GLQ_FLUSH_DONE,   /* The flush operation completed successfully */
  GLQ_FLUSH_AGAIN,  /* The flush operation couldn't be completed on this */
                    /*  call. Call this function again when the output */
                    /*  channel can accept further output. */
  GLQ_FLUSH_ERROR   /* Unrecoverable error. */
} GlqFlushState;

/*
 * Transfer as much of the contents of a character queue to an output
 * channel as possible, returning before the queue is empty if the
 * write_fn() callback says that it can't currently write anymore.
 */
GlqFlushState _glq_flush_queue(GlCharQueue *cq, GlWriteFn *write_fn,
			       void *data);

/*
 * Provide information about the last error that occurred while calling
 * any of the above functions.
 */
const char *_glq_last_error(GlCharQueue *cq);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

/*
 * If file-system access is to be excluded, this module has no function,
 * so all of its code should be excluded.
 */
#ifndef WITHOUT_FILE_SYSTEM

/*
 * Standard includes.
 */
#include <stdio.h>
#include <stdlib.h>
#include <limits.h>
#include <errno.h>
#include <string.h>
#include <ctype.h>

/*
 * Local includes.
 */
#include "libtecla.h"
#include "direader.h"
#include "homedir.h"
#include "pathutil.h"
#include "cplfile.h"
#include "errmsg.h"

/*
 * Set the maximum length allowed for usernames.
 * names.
 */
#define USR_LEN 100

/*
 * Set the maximum length allowed for environment variable names.
 */
#define ENV_LEN 100

/*
 * The resources needed to complete a filename are maintained in objects
 * of the following type.
 */
struct CompleteFile {
  ErrMsg *err;                 /* The error reporting buffer */
  DirReader *dr;               /* A directory reader */
  HomeDir *home;               /* A home directory expander */
  PathName *path;              /* The buffer in which to accumulate the path */
  PathName *buff;              /* A pathname work buffer */
  char usrnam[USR_LEN+1];      /* The buffer used when reading the names of */
                               /*  users. */
  char envnam[ENV_LEN+1];      /* The buffer used when reading the names of */
                               /*  environment variables. */
};

static int cf_expand_home_dir(CompleteFile *cf, const char *user);
static int cf_complete_username(CompleteFile *cf, WordCompletion *cpl,
				const char *prefix, const char *line,
				int word_start, int word_end, int escaped);
static HOME_DIR_FN(cf_homedir_callback);
static int cf_complete_entry(CompleteFile *cf, WordCompletion *cpl,
			     const char *line, int word_start, int word_end,
			     int escaped, CplCheckFn *check_fn,
			     void *check_data);
static char *cf_read_name(CompleteFile *cf, const char *type,
			  const char *string, int slen,
			  char *nambuf, int nammax);
static int cf_prepare_suffix(CompleteFile *cf, const char *suffix,
			     int add_escapes);

/*
 * A stack based object of the following type is used to pass data to the
 * cf_homedir_callback() function.
 */
typedef struct {
  CompleteFile *cf;    /* The file-completion resource object */
  WordCompletion *cpl; /* The string-completion rsource object */
  size_t prefix_len;   /* The length of the prefix being completed */
  const char *line;    /* The line from which the prefix was extracted */
  int word_start;      /* The index in line[] of the start of the username */
  int word_end;        /* The index in line[] following the end of the prefix */
  int escaped;         /* If true, add escapes to the completion suffixes */
} CfHomeArgs;

/*.......................................................................
 * Create a new file-completion object.
 *
 * Output:
 *  return  CompleteFile *  The new object, or NULL on error.
 */
CompleteFile *_new_CompleteFile(void)
{
  CompleteFile *cf;  /* The object to be returned */
/*
 * Allocate the container.
 */
  cf = (CompleteFile *) malloc(sizeof(CompleteFile));
  if(!cf) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to _del_CompleteFile().
 */
  cf->err = NULL;
  cf->dr = NULL;
  cf->home = NULL;
  cf->path = NULL;
  cf->buff = NULL;
  cf->usrnam[0] = '\0';
  cf->envnam[0] = '\0';
/*
 * Allocate a place to record error messages.
 */
  cf->err = _new_ErrMsg();
  if(!cf->err)
    return _del_CompleteFile(cf);
/*
 * Create the object that is used for reading directories.
 */
  cf->dr = _new_DirReader();
  if(!cf->dr)
    return _del_CompleteFile(cf);
/*
 * Create the object that is used to lookup home directories.
 */
  cf->home = _new_HomeDir();
  if(!cf->home)
    return _del_CompleteFile(cf);
/*
 * Create the buffer in which the completed pathname is accumulated.
 */
  cf->path = _new_PathName();
  if(!cf->path)
    return _del_CompleteFile(cf);
/*
 * Create a pathname work buffer.
 */
  cf->buff = _new_PathName();
  if(!cf->buff)
    return _del_CompleteFile(cf);
  return cf;
}

/*.......................................................................
 * Delete a file-completion object.
 *
 * Input:
 *  cf     CompleteFile *  The object to be deleted.
 * Output:
 *  return CompleteFile *  The deleted object (always NULL).
 */
CompleteFile *_del_CompleteFile(CompleteFile *cf)
{
  if(cf) {
    cf->err = _del_ErrMsg(cf->err);
    cf->dr = _del_DirReader(cf->dr);
    cf->home = _del_HomeDir(cf->home);
    cf->path = _del_PathName(cf->path);
    cf->buff = _del_PathName(cf->buff);
    free(cf);
  };
  return NULL;
}

/*.......................................................................
 * Look up the possible completions of the incomplete filename that
 * lies between specified indexes of a given command-line string.
 *
 * Input:
 *  cpl   WordCompletion *  The object in which to record the completions.
 *  cf      CompleteFile *  The filename-completion resource object.
 *  line      const char *  The string containing the incomplete filename.
 *  word_start       int    The index of the first character in line[]
 *                          of the incomplete filename.
 *  word_end         int    The index of the character in line[] that
 *                          follows the last character of the incomplete
 *                          filename.
 *  escaped          int    If true, backslashes in line[] are
 *                          interpreted as escaping the characters
 *                          that follow them, and any spaces, tabs,
 *                          backslashes, or wildcard characters in the
 *                          returned suffixes will be similarly escaped.
 *                          If false, backslashes will be interpreted as
 *                          literal parts of the file name, and no
 *                          backslashes will be added to the returned
 *                          suffixes.
 *  check_fn  CplCheckFn *  If not zero, this argument specifies a
 *                          function to call to ask whether a given
 *                          file should be included in the list
 *                          of completions.
 *  check_data      void *  Anonymous data to be passed to check_fn().
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error. A description of the error can be
 *                                     acquired by calling _cf_last_error(cf).
 */
int _cf_complete_file(WordCompletion *cpl, CompleteFile *cf,
		     const char *line, int word_start, int word_end,
		     int escaped, CplCheckFn *check_fn, void *check_data)
{
  const char *lptr; /* A pointer into line[] */
  int nleft;        /* The number of characters still to be processed */
                    /*  in line[]. */
/*
 * Check the arguments.
 */
  if(!cpl || !cf || !line || word_end < word_start) {
    if(cf) {
      _err_record_msg(cf->err, "_cf_complete_file: Invalid arguments",
		      END_ERR_MSG);
    };
    return 1;
  };
/*
 * Clear the buffer in which the filename will be constructed.
 */
  _pn_clear_path(cf->path);
/*
 * How many characters are to be processed?
 */
  nleft = word_end - word_start;
/*
 * Get a pointer to the start of the incomplete filename.
 */
  lptr = line + word_start;
/*
 * If the first character is a tilde, then perform home-directory
 * interpolation.
 */
  if(nleft > 0 && *lptr == '~') {
    int slen;
    if(!cf_read_name(cf, "User", ++lptr, --nleft, cf->usrnam, USR_LEN))
      return 1;
/*
 * Advance over the username in the input line.
 */
    slen = strlen(cf->usrnam);
    lptr += slen;
    nleft -= slen;
/*
 * If we haven't hit the end of the input string then we have a complete
 * username to translate to the corresponding home directory.
 */
    if(nleft > 0) {
      if(cf_expand_home_dir(cf, cf->usrnam))
	return 1;
/*
 * ~user and ~ are usually followed by a directory separator to
 * separate them from the file contained in the home directory.
 * If the home directory is the root directory, then we don't want
 * to follow the home directory by a directory separator, so we should
 * skip over it so that it doesn't get copied into the filename.
 */
      if(strcmp(cf->path->name, FS_ROOT_DIR) == 0 &&
	 strncmp(lptr, FS_DIR_SEP, FS_DIR_SEP_LEN) == 0) {
	lptr += FS_DIR_SEP_LEN;
	nleft -= FS_DIR_SEP_LEN;
      };
/*
 * If we have reached the end of the input string, then the username
 * may be incomplete, and we should attempt to complete it.
 */
    } else {
/*
 * Look up the possible completions of the username.
 */
      return cf_complete_username(cf, cpl, cf->usrnam, line, word_start+1,
				  word_end, escaped);
    };
  };
/*
 * Copy the rest of the path, stopping to expand $envvar expressions
 * where encountered.
 */
  while(nleft > 0) {
    int seglen;   /* The length of the next segment to be copied */
/*
 * Find the length of the next segment to be copied, stopping if an
 * unescaped '$' is seen, or the end of the path is reached.
 */
    for(seglen=0; seglen < nleft; seglen++) {
      int c = lptr[seglen];
      if(escaped && c == '\\')
	seglen++;
      else if(c == '$')
	break;
/*
 * We will be completing the last component of the file name,
 * so whenever a directory separator is seen, assume that it
 * might be the start of the last component, and mark the character
 * that follows it as the start of the name that is to be completed.
 */
      if(nleft >= FS_DIR_SEP_LEN &&
	 strncmp(lptr + seglen, FS_DIR_SEP, FS_DIR_SEP_LEN)==0) {
	word_start = (lptr + seglen) - line + FS_DIR_SEP_LEN;
      };
    };
/*
 * We have reached either the end of the filename or the start of
 * $environment_variable expression. Record the newly checked
 * segment of the filename in the output filename, removing
 * backslash-escapes where needed.
 */
    if(_pn_append_to_path(cf->path, lptr, seglen, escaped) == NULL) {
      _err_record_msg(cf->err, "Insufficient memory to complete filename",
		      END_ERR_MSG);
      return 1;
    };
    lptr += seglen;
    nleft -= seglen;
/*
 * If the above loop finished before we hit the end of the filename,
 * then this was because an unescaped $ was seen. In this case, interpolate
 * the value of the environment variable that follows it into the output
 * filename.
 */
    if(nleft > 0) {
      char *value;    /* The value of the environment variable */
      int vlen;       /* The length of the value string */
      int nlen;       /* The length of the environment variable name */
/*
 * Read the name of the environment variable.
 */
      if(!cf_read_name(cf, "Environment", ++lptr, --nleft, cf->envnam, ENV_LEN))
	return 1;
/*
 * Advance over the environment variable name in the input line.
 */
      nlen = strlen(cf->envnam);
      lptr += nlen;
      nleft -= nlen;
/*
 * Get the value of the environment variable.
 */
      value = getenv(cf->envnam);
      if(!value) {
	_err_record_msg(cf->err, "Unknown environment variable: ", cf->envnam,
			END_ERR_MSG);
	return 1;
      };
      vlen = strlen(value);
/*
 * If we are at the start of the filename and the first character of the
 * environment variable value is a '~', attempt home-directory
 * interpolation.
 */
      if(cf->path->name[0] == '\0' && value[0] == '~') {
	if(!cf_read_name(cf, "User", value+1, vlen-1, cf->usrnam, USR_LEN) ||
	   cf_expand_home_dir(cf, cf->usrnam))
	  return 1;
/*
 * If the home directory is the root directory, and the ~usrname expression
 * was followed by a directory separator, prevent the directory separator
 * from being appended to the root directory by skipping it in the
 * input line.
 */
	if(strcmp(cf->path->name, FS_ROOT_DIR) == 0 &&
	   strncmp(lptr, FS_DIR_SEP, FS_DIR_SEP_LEN) == 0) {
	  lptr += FS_DIR_SEP_LEN;
	  nleft -= FS_DIR_SEP_LEN;
	};
      } else {
/*
 * Append the value of the environment variable to the output path.
 */
	if(_pn_append_to_path(cf->path, value, strlen(value), escaped)==NULL) {
	  _err_record_msg(cf->err, "Insufficient memory to complete filename",
			  END_ERR_MSG);
	  return 1;
	};
/*
 * Prevent extra directory separators from being added.
 */
	if(nleft >= FS_DIR_SEP_LEN &&
	   strcmp(cf->path->name, FS_ROOT_DIR) == 0 &&
	   strncmp(lptr, FS_DIR_SEP, FS_DIR_SEP_LEN) == 0) {
	  lptr += FS_DIR_SEP_LEN;
	  nleft -= FS_DIR_SEP_LEN;
	} else if(vlen > FS_DIR_SEP_LEN &&
		  strcmp(value + vlen - FS_DIR_SEP_LEN, FS_DIR_SEP)==0) {
	  cf->path->name[vlen-FS_DIR_SEP_LEN] = '\0';
	};
      };
/*
 * If adding the environment variable didn't form a valid directory,
 * we can't complete the line, since there is no way to separate append
 * a partial filename to an environment variable reference without
 * that appended part of the name being seen later as part of the
 * environment variable name. Thus if the currently constructed path
 * isn't a directory, quite now with no completions having been
 * registered.
 */
      if(!_pu_path_is_dir(cf->path->name))
	return 0;
/*
 * For the reasons given above, if we have reached the end of the filename
 * with the expansion of an environment variable, the only allowed
 * completion involves the addition of a directory separator.
 */
      if(nleft == 0) {
	if(cpl_add_completion(cpl, line, lptr-line, word_end, FS_DIR_SEP,
			      "", "")) {
	  _err_record_msg(cf->err, cpl_last_error(cpl), END_ERR_MSG);
	  return 1;
	};
	return 0;
      };
    };
  };
/*
 * Complete the filename if possible.
 */
  return cf_complete_entry(cf, cpl, line, word_start, word_end, escaped,
			   check_fn, check_data);
}

/*.......................................................................
 * Return a description of the last path-completion error that occurred.
 *
 * Input:
 *  cf    CompleteFile *  The path-completion resource object.
 * Output:
 *  return  const char *  The description of the last error.
 */
const char *_cf_last_error(CompleteFile *cf)
{
  return cf ? _err_get_msg(cf->err) : "NULL CompleteFile argument";
}

/*.......................................................................
 * Lookup the home directory of the specified user, or the current user
 * if no name is specified, appending it to output pathname.
 *
 * Input:
 *  cf  CompleteFile *  The pathname completion resource object.
 *  user  const char *  The username to lookup, or "" to lookup the
 *                      current user.
 * Output:
 *  return        int    0 - OK.
 *                       1 - Error.
 */
static int cf_expand_home_dir(CompleteFile *cf, const char *user)
{
/*
 * Attempt to lookup the home directory.
 */
  const char *home_dir = _hd_lookup_home_dir(cf->home, user);
/*
 * Failed?
 */
  if(!home_dir) {
    _err_record_msg(cf->err, _hd_last_home_dir_error(cf->home), END_ERR_MSG);
    return 1;
  };
/*
 * Append the home directory to the pathname string.
 */
  if(_pn_append_to_path(cf->path, home_dir, -1, 0) == NULL) {
    _err_record_msg(cf->err, "Insufficient memory for home directory expansion",
		    END_ERR_MSG);
    return 1;
  };
  return 0;
}

/*.......................................................................
 * Lookup and report all completions of a given username prefix.
 *
 * Input:
 *  cf     CompleteFile *  The filename-completion resource object.
 *  cpl  WordCompletion *  The object in which to record the completions.
 *  prefix   const char *  The prefix of the usernames to lookup.
 *  line     const char *  The command-line in which the username appears.
 *  word_start      int    The index within line[] of the start of the
 *                         username that is being completed.
 *  word_end        int    The index within line[] of the character which
 *                         follows the incomplete username.
 *  escaped         int    True if the completions need to have special
 *                         characters escaped.
 * Output:
 *  return          int    0 - OK.
 *                         1 - Error.
 */
static int cf_complete_username(CompleteFile *cf, WordCompletion *cpl,
				const char *prefix, const char *line,
				int word_start, int word_end, int escaped)
{
/*
 * Set up a container of anonymous arguments to be sent to the
 * username-lookup iterator.
 */
  CfHomeArgs args;
  args.cf = cf;
  args.cpl = cpl;
  args.prefix_len = strlen(prefix);
  args.line = line;
  args.word_start = word_start;
  args.word_end = word_end;
  args.escaped = escaped;
/*
 * Iterate through the list of users, recording those which start
 * with the specified prefix.
 */
  if(_hd_scan_user_home_dirs(cf->home, prefix, &args, cf_homedir_callback)) {
    _err_record_msg(cf->err, _hd_last_home_dir_error(cf->home), END_ERR_MSG);
    return 1;
  };
  return 0;
}

/*.......................................................................
 * The user/home-directory scanner callback function (see homedir.h)
 * used by cf_complete_username().
 */
static HOME_DIR_FN(cf_homedir_callback)
{
/*
 * Get the file-completion resources from the anonymous data argument.
 */
  CfHomeArgs *args = (CfHomeArgs *) data;
  WordCompletion *cpl = args->cpl;
  CompleteFile *cf = args->cf;
/*
 * Copy the username into the pathname work buffer, adding backslash
 * escapes where needed.
 */
  if(cf_prepare_suffix(cf, usrnam+args->prefix_len, args->escaped)) {
    strncpy(errmsg, _err_get_msg(cf->err), maxerr);
    errmsg[maxerr] = '\0';
    return 1;
  };
/*
 * Report the completion suffix that was copied above.
 */
  if(cpl_add_completion(cpl, args->line, args->word_start, args->word_end,
			cf->buff->name, FS_DIR_SEP, FS_DIR_SEP)) {
    strncpy(errmsg, cpl_last_error(cpl), maxerr);
    errmsg[maxerr] = '\0';
    return 1;
  };
  return 0;
}

/*.......................................................................
 * Report possible completions of the filename in cf->path->name[].
 *
 * Input:
 *  cf      CompleteFile *  The file-completion resource object.
 *  cpl   WordCompletion *  The object in which to record the completions.
 *  line      const char *  The input line, as received by the callback
 *                          function.
 *  word_start       int    The index within line[] of the start of the
 *                          last component of the filename that is being
 *                          completed.
 *  word_end         int    The index within line[] of the character which
 *                          follows the incomplete filename.
 *  escaped          int    If true, escape special characters in the
 *                          completion suffixes.
 *  check_fn  CplCheckFn *  If not zero, this argument specifies a
 *                          function to call to ask whether a given
 *                          file should be included in the list
 *                          of completions.
 *  check_data      void *  Anonymous data to be passed to check_fn().
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
static int cf_complete_entry(CompleteFile *cf, WordCompletion *cpl,
			     const char *line, int word_start, int word_end,
			     int escaped, CplCheckFn *check_fn,
			     void *check_data)
{
  const char *dirpath;   /* The name of the parent directory */
  int start;             /* The index of the start of the last filename */
                         /*  component in the transcribed filename. */
  const char *prefix;    /* The filename prefix to be completed */
  int prefix_len;        /* The length of the filename prefix */
  const char *file_name; /* The lastest filename being compared */
  int waserr = 0;        /* True after errors */
  int terminated=0;      /* True if the directory part had to be terminated */
/*
 * Get the pathname string and its current length.
 */
  char *pathname = cf->path->name;
  int pathlen = strlen(pathname);
/*
 * Locate the start of the final component of the pathname.
 */
  for(start=pathlen - 1; start >= 0 &&
      strncmp(pathname + start, FS_DIR_SEP, FS_DIR_SEP_LEN) != 0; start--)
    ;
/*
 * Is the parent directory the root directory?
 */
  if(start==0 ||
     (start < 0 && strncmp(pathname, FS_ROOT_DIR, FS_ROOT_DIR_LEN) == 0)) {
    dirpath = FS_ROOT_DIR;
    start += FS_ROOT_DIR_LEN;
/*
 * If we found a directory separator then the part which precedes the
 * last component is the name of the directory to be opened.
 */
  } else if(start > 0) {
/*
 * The _dr_open_dir() function requires the directory name to be '\0'
 * terminated, so temporarily do this by overwriting the first character
 * of the directory separator.
 */
    pathname[start] = '\0';
    dirpath = pathname;
    terminated = 1;
/*
 * We reached the start of the pathname before finding a directory
 * separator, so arrange to open the current working directory.
 */
  } else {
    start = 0;
    dirpath = FS_PWD;
  };
/*
 * Attempt to open the directory.
 */
  if(_dr_open_dir(cf->dr, dirpath, NULL)) {
    _err_record_msg(cf->err, "Can't open directory: ", dirpath, END_ERR_MSG);
    return 1;
  };
/*
 * If removed above, restore the directory separator and skip over it
 * to the start of the filename.
 */
  if(terminated) {
    memcpy(pathname + start, FS_DIR_SEP, FS_DIR_SEP_LEN);
    start += FS_DIR_SEP_LEN;
  };
/*
 * Get the filename prefix and its length.
 */
  prefix = pathname + start;
  prefix_len = strlen(prefix);
/*
 * Traverse the directory, looking for files who's prefixes match the
 * last component of the pathname.
 */
  while((file_name = _dr_next_file(cf->dr)) != NULL && !waserr) {
    int name_len = strlen(file_name);
/*
 * Is the latest filename a possible completion of the filename prefix?
 */
    if(name_len >= prefix_len && strncmp(prefix, file_name, prefix_len)==0) {
/*
 * When listing all files in a directory, don't list files that start
 * with '.'. This is how hidden files are denoted in UNIX.
 */
      if(prefix_len > 0 || file_name[0] != '.') {
/*
 * Copy the completion suffix into the work pathname cf->buff->name,
 * adding backslash escapes if needed.
 */
	if(cf_prepare_suffix(cf, file_name + prefix_len, escaped)) {
	  waserr = 1;
	} else {
/*
 * We want directories to be displayed with directory suffixes,
 * and other fully completed filenames to be followed by spaces.
 * To check the type of the file, append the current suffix
 * to the path being completed, check the filetype, then restore
 * the path to its original form.
 */
	  const char *cont_suffix = "";  /* The suffix to add if fully */
                                         /*  completed. */
	  const char *type_suffix = "";  /* The suffix to add when listing */
	  if(_pn_append_to_path(cf->path, file_name + prefix_len,
				-1, escaped) == NULL) {
	    _err_record_msg(cf->err,
			    "Insufficient memory to complete filename.",
			    END_ERR_MSG);
	    return 1;
	  };
/*
 * Specify suffixes according to the file type.
 */
	  if(_pu_path_is_dir(cf->path->name)) {
	    cont_suffix = FS_DIR_SEP;
	    type_suffix = FS_DIR_SEP;
	  } else if(!check_fn || check_fn(check_data, cf->path->name)) {
	    cont_suffix = " ";
	  } else {
	    cf->path->name[pathlen] = '\0';
	    continue;
	  };
/*
 * Remove the temporarily added suffix.
 */
	  cf->path->name[pathlen] = '\0';
/*
 * Record the latest completion.
 */
	  if(cpl_add_completion(cpl, line, word_start, word_end, cf->buff->name,
				type_suffix, cont_suffix))
	    waserr = 1;
	};
      };
    };
  };
/*
 * Close the directory.
 */
  _dr_close_dir(cf->dr);
  return waserr;
}

/*.......................................................................
 * Read a username or environment variable name, stopping when a directory
 * separator is seen, when the end of the string is reached, or the
 * output buffer overflows.
 *
 * Input:
 *  cf   CompleteFile *  The file-completion resource object.
 *  type         char *  The capitalized name of the type of name being read.
 *  string       char *  The string who's prefix contains the name.
 *  slen          int    The number of characters in string[].
 *  nambuf       char *  The output name buffer.
 *  nammax        int    The longest string that will fit in nambuf[], excluding
 *                       the '\0' terminator.
 * Output:
 *  return       char *  A pointer to nambuf on success. On error NULL is
 *                       returned and a description of the error is recorded
 *                       in cf->err.
 */
static char *cf_read_name(CompleteFile *cf, const char *type,
			  const char *string, int slen,
			  char *nambuf, int nammax)
{
  int namlen;         /* The number of characters in nambuf[] */
  const char *sptr;   /* A pointer into string[] */
/*
 * Work out the max number of characters that should be copied.
 */
  int nmax = nammax < slen ? nammax : slen;
/*
 * Get the environment variable name that follows the dollar.
 */
  for(sptr=string,namlen=0;
      namlen < nmax && (slen-namlen < FS_DIR_SEP_LEN ||
			strncmp(sptr, FS_DIR_SEP, FS_DIR_SEP_LEN) != 0);
      namlen++) {
    nambuf[namlen] = *sptr++;
  };
/*
 * Did the name overflow the buffer?
 */
  if(namlen >= nammax) {
    _err_record_msg(cf->err, type, " name too long", END_ERR_MSG);
    return NULL;
  };
/*
 * Terminate the string.
 */
  nambuf[namlen] = '\0';
  return nambuf;
}

/*.......................................................................
 * Using the work buffer cf->buff, make a suitably escaped copy of a
 * given completion suffix, ready to be passed to cpl_add_completion().
 *
 * Input:
 *  cf   CompleteFile *  The file-completion resource object.
 *  suffix       char *  The suffix to be copied.
 *  add_escapes   int    If true, escape special characters.
 * Output:
 *  return        int    0 - OK.
 *                       1 - Error.
 */
static int cf_prepare_suffix(CompleteFile *cf, const char *suffix,
			     int add_escapes)
{
  const char *sptr; /* A pointer into suffix[] */
  int nbsl;         /* The number of backslashes to add to the suffix */
  int i;
/*
 * How long is the suffix?
 */
  int suffix_len = strlen(suffix);
/*
 * Clear the work buffer.
 */
  _pn_clear_path(cf->buff);
/*
 * Count the number of backslashes that will have to be added to
 * escape spaces, tabs, backslashes and wildcard characters.
 */
  nbsl = 0;
  if(add_escapes) {
    for(sptr = suffix; *sptr; sptr++) {
      switch(*sptr) {
      case ' ': case '\t': case '\\': case '*': case '?': case '[':
	nbsl++;
	break;
      };
    };
  };
/*
 * Arrange for the output path buffer to have sufficient room for the
 * both the suffix and any backslashes that have to be inserted.
 */
  if(_pn_resize_path(cf->buff, suffix_len + nbsl) == NULL) {
    _err_record_msg(cf->err, "Insufficient memory to complete filename",
		    END_ERR_MSG);
    return 1;
  };
/*
 * If the suffix doesn't need any escapes, copy it directly into the
 * work buffer.
 */
  if(nbsl==0) {
    strlcpy(cf->buff->name, suffix, cf->buff->dim);
  } else {
/*
 * Make a copy with special characters escaped?
 */
    if(nbsl > 0) {
      const char *src = suffix;
      char *dst = cf->buff->name;
      for(i=0; i<suffix_len; i++) {
	switch(*src) {
	case ' ': case '\t': case '\\': case '*': case '?': case '[':
	  *dst++ = '\\';
	};
	*dst++ = *src++;
      };
      *dst = '\0';
    };
  };
  return 0;
}

#endif  /* ifndef WITHOUT_FILE_SYSTEM */
#ifndef cplfile_h
#define cplfile_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

typedef struct CompleteFile CompleteFile;

/*
 * Create a file-completion resource object.
 */
CompleteFile *_new_CompleteFile(void);
/*
 * Delete a file-completion resource object.
 */
CompleteFile *_del_CompleteFile(CompleteFile *cf);

/*.......................................................................
 * Complete the string between path[0] and path[len-1] as a pathname,
 * leaving the last component uncompleted if it is potentially ambiguous,
 * and returning an array of possible completions. Note that the returned
 * container belongs to the 'cf' object and its contents will change on
 * subsequent calls to this function.
 *
 * Input:
 *  cpl   WordCompletion *  The object in which to record the completions.
 *  cf      CompleteFile *  The filename-completion resource object.
 *  line      const char *  The string containing the incomplete filename.
 *  word_start       int    The index of the first character in line[]
 *                          of the incomplete filename.
 *  word_end         int    The index of the character in line[] that
 *                          follows the last character of the incomplete
 *                          filename.
 *  escaped          int    If true, backslashes in path[] are
 *                          interpreted as escaping the characters
 *                          that follow them, and any spaces, tabs,
 *                          backslashes, or wildcard characters in the
 *                          returned suffixes will be similarly be escaped.
 *                          If false, backslashes will be interpreted as
 *                          literal parts of the file name, and no
 *                          backslashes will be added to the returned
 *                          suffixes.
 *  check_fn  CplCheckFn *  If not zero, this argument specifies a
 *                          function to call to ask whether a given
 *                          file should be included in the list
 *                          of completions.
 *  check_data      void *  Anonymous data to be passed to check_fn().
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error. A description of the error can be
 *                                     acquired by calling cf_last_error(cf).
 */
int _cf_complete_file(WordCompletion *cpl, CompleteFile *cf,
		     const char *line, int word_start, int word_end,
		     int escaped, CplCheckFn *check_fn, void *check_data);

/*.......................................................................
 * Return a description of the error that occurred on the last call to
 * cf_complete_file().
 *
 * Input:
 *  cf    CompleteFile *  The path-completion resource object.
 * Output:
 *  return        char *  The description of the last error.
 */
const char *_cf_last_error(CompleteFile *cf);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

/*
 * Standard includes.
 */
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <errno.h>

/*
 * Local includes.
 */
#include "libtecla.h"
#include "ioutil.h"
#include "stringrp.h"
#include "pathutil.h"
#include "cplfile.h"
#include "cplmatch.h"
#include "errmsg.h"

/*
 * Specify the number of strings to allocate when the string free-list
 * is exhausted. This also sets the number of elements to expand the
 * matches[] array by whenever it is found to be too small.
 */
#define STR_BLK_FACT 100

/*
 * Set the default number of spaces place between columns when listing
 * a set of completions.
 */
#define CPL_COL_SEP 2

/*
 * Completion matches are recorded in containers of the following
 * type.
 */
struct WordCompletion {
  ErrMsg *err;            /* The error reporting buffer */
  StringGroup *sg;        /* Memory for a group of strings */
  int matches_dim;        /* The allocated size of result.matches[] */
  CplMatches result;      /* Completions to be returned to the caller */
#ifndef WITHOUT_FILE_SYSTEM
  CompleteFile *cf;       /* The resources used for filename completion */
#endif
};

static void cpl_sort_matches(WordCompletion *cpl);
static void cpl_zap_duplicates(WordCompletion *cpl);
static void cpl_clear_completions(WordCompletion *cpl);
static int cpl_cmp_matches(const void *v1, const void *v2);
static int cpl_cmp_suffixes(const void *v1, const void *v2);

/*
 * The new_CplFileConf() constructor sets the integer first member of
 * the returned object to the following magic number. On seeing this,
 * cpl_file_completions() knows when it is passed a valid CplFileConf
 * object.
 */
#define CFC_ID_CODE 4568

#ifndef WITHOUT_FILE_SYSTEM
/*
 * A pointer to a structure of the following type can be passed to
 * the builtin file-completion callback function to modify its behavior.
 */
struct CplFileConf {
  int id;             /* new_CplFileConf() sets this to CFC_ID_CODE */
  int escaped;        /* If none-zero, backslashes in the input line are */
                      /*  interpreted as escaping special characters and */
                      /*  spaces, and any special characters and spaces in */
                      /*  the listed completions will also be escaped with */
                      /*  added backslashes. This is the default behaviour. */
                      /* If zero, backslashes are interpreted as being */
                      /*  literal parts of the filename, and none are added */
                      /*  to the completion suffixes. */
  int file_start;     /* The index in the input line of the first character */
                      /*  of the filename. If you specify -1 here, */
                      /*  cpl_file_completions() identifies the */
                      /*  the start of the filename by looking backwards for */
                      /*  an unescaped space, or the beginning of the line. */
  CplCheckFn *chk_fn; /* If not zero, this argument specifies a */
                      /*  function to call to ask whether a given */
                      /*  file should be included in the list */
                      /*  of completions. */
  void *chk_data;     /* Anonymous data to be passed to check_fn(). */
};

static void cpl_init_FileConf(CplFileConf *cfc);

/*
 * When file-system access is being excluded, define a dummy structure
 * to satisfy the typedef in libtecla.h.
 */
#else
struct CplFileConf {int dummy;};
#endif

/*
 * Encapsulate the formatting information needed to layout a
 * multi-column listing of completions.
 */
typedef struct {
  int term_width;     /* The width of the terminal (characters) */
  int column_width;   /* The number of characters within in each column. */
  int ncol;           /* The number of columns needed */
  int nline;          /* The number of lines needed */
} CplListFormat;

/*
 * Given the current terminal width, and a list of completions, determine
 * how to best use the terminal width to display a multi-column listing
 * of completions.
 */
static void cpl_plan_listing(CplMatches *result, int term_width,
			     CplListFormat *fmt);

/*
 * Display a given line of a multi-column list of completions.
 */
static int cpl_format_line(CplMatches *result, CplListFormat *fmt, int lnum,
			   GlWriteFn *write_fn, void *data);

/*.......................................................................
 * Create a new string-completion object.
 *
 * Output:
 *  return    WordCompletion *  The new object, or NULL on error.
 */
WordCompletion *new_WordCompletion(void)
{
  WordCompletion *cpl;  /* The object to be returned */
/*
 * Allocate the container.
 */
  cpl = (WordCompletion *) malloc(sizeof(WordCompletion));
  if(!cpl) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_WordCompletion().
 */
  cpl->err = NULL;
  cpl->sg = NULL;
  cpl->matches_dim = 0;
  cpl->result.suffix = NULL;
  cpl->result.cont_suffix = NULL;
  cpl->result.matches = NULL;
  cpl->result.nmatch = 0;
#ifndef WITHOUT_FILE_SYSTEM
  cpl->cf = NULL;
#endif
/*
 * Allocate a place to record error messages.
 */
  cpl->err = _new_ErrMsg();
  if(!cpl->err)
    return del_WordCompletion(cpl);
/*
 * Allocate an object that allows a group of strings to be allocated
 * efficiently by placing many of them in contiguous string segments.
 */
#ifdef WITHOUT_FILE_SYSTEM
  cpl->sg = _new_StringGroup(MAX_PATHLEN_FALLBACK);
#else
  cpl->sg = _new_StringGroup(_pu_pathname_dim());
#endif
  if(!cpl->sg)
    return del_WordCompletion(cpl);
/*
 * Allocate an array for matching completions. This will be extended later
 * if needed.
 */
  cpl->matches_dim = STR_BLK_FACT;
  cpl->result.matches = (CplMatch *) malloc(sizeof(cpl->result.matches[0]) *
					    cpl->matches_dim);
  if(!cpl->result.matches) {
    errno = ENOMEM;
    return del_WordCompletion(cpl);
  };
/*
 * Allocate a filename-completion resource object.
 */
#ifndef WITHOUT_FILE_SYSTEM
  cpl->cf = _new_CompleteFile();
  if(!cpl->cf)
    return del_WordCompletion(cpl);
#endif
  return cpl;
}

/*.......................................................................
 * Delete a string-completion object.
 *
 * Input:
 *  cpl    WordCompletion *  The object to be deleted.
 * Output:
 *  return WordCompletion *  The deleted object (always NULL).
 */
WordCompletion *del_WordCompletion(WordCompletion *cpl)
{
  if(cpl) {
    cpl->err = _del_ErrMsg(cpl->err);
    cpl->sg = _del_StringGroup(cpl->sg);
    if(cpl->result.matches) {
      free(cpl->result.matches);
      cpl->result.matches = NULL;
#ifndef WITHOUT_FILE_SYSTEM
      cpl->cf = _del_CompleteFile(cpl->cf);
#endif
    };
    free(cpl);
  };
  return NULL;
}

/*.......................................................................
 * This function is designed to be called by CplMatchFn callback
 * functions. It adds one possible completion of the token that is being
 * completed to an array of completions. If the completion needs any
 * special quoting to be valid when displayed in the input line, this
 * quoting must be included in the string.
 *
 * Input:
 *  cpl     WordCompletion *  The argument of the same name that was passed
 *                            to the calling CplMatchFn callback function.
 *  line        const char *  The input line, as received by the callback
 *                            function.
 *  word_start         int    The index within line[] of the start of the
 *                            word that is being completed.
 *  word_end           int    The index within line[] of the character which
 *                            follows the incomplete word, as received by the
 *                            calling callback function.
 *  suffix      const char *  The appropriately quoted string that could
 *                            be appended to the incomplete token to complete
 *                            it. A copy of this string will be allocated
 *                            internally.
 *  type_suffix const char *  When listing multiple completions, gl_get_line()
 *                            appends this string to the completion to indicate
 *                            its type to the user. If not pertinent pass "".
 *                            Otherwise pass a literal or static string.
 *  cont_suffix const char *  If this turns out to be the only completion,
 *                            gl_get_line() will append this string as
 *                            a continuation. For example, the builtin
 *                            file-completion callback registers a directory
 *                            separator here for directory matches, and a
 *                            space otherwise. If the match were a function
 *                            name you might want to append an open
 *                            parenthesis, etc.. If not relevant pass "".
 *                            Otherwise pass a literal or static string.
 * Output:
 *  return             int    0 - OK.
 *                            1 - Error.
 */
int cpl_add_completion(WordCompletion *cpl, const char *line,
		       int word_start, int word_end, const char *suffix,
		       const char *type_suffix, const char *cont_suffix)
{
  CplMatch *match; /* The container of the new match */
  char *string;    /* A newly allocated copy of the completion string */
  size_t len;
/*
 * Check the arguments.
 */
  if(!cpl)
    return 1;
  if(!suffix)
    return 0;
  if(!type_suffix)
    type_suffix = "";
  if(!cont_suffix)
    cont_suffix = "";
/*
 * Do we need to extend the array of matches[]?
 */
  if(cpl->result.nmatch+1 > cpl->matches_dim) {
    int needed = cpl->matches_dim + STR_BLK_FACT;
    CplMatch *matches = (CplMatch *) realloc(cpl->result.matches,
			    sizeof(cpl->result.matches[0]) * needed);
    if(!matches) {
      _err_record_msg(cpl->err,
		      "Insufficient memory to extend array of matches.",
		      END_ERR_MSG);
      return 1;
    };
    cpl->result.matches = matches;
    cpl->matches_dim = needed;
  };
/*
 * Allocate memory to store the combined completion prefix and the
 * new suffix.
 */
  len = strlen(suffix);
  string = _sg_alloc_string(cpl->sg, word_end-word_start + len);
  if(!string) {
    _err_record_msg(cpl->err, "Insufficient memory to extend array of matches.",
		    END_ERR_MSG);
    return 1;
  };
/*
 * Compose the string.
 */
  strncpy(string, line + word_start, word_end - word_start);
  strlcpy(string + word_end - word_start, suffix, len + 1);
/*
 * Record the new match.
 */
  match = cpl->result.matches + cpl->result.nmatch++;
  match->completion = string;
  match->suffix = string + word_end - word_start;
  match->type_suffix = type_suffix;
/*
 * Record the continuation suffix.
 */
  cpl->result.cont_suffix = cont_suffix;
  return 0;
}

/*.......................................................................
 * Sort the array of matches.
 *
 * Input:
 *  cpl   WordCompletion *  The completion resource object.
 */
static void cpl_sort_matches(WordCompletion *cpl)
{
  qsort(cpl->result.matches, cpl->result.nmatch,
	sizeof(cpl->result.matches[0]), cpl_cmp_matches);
}

/*.......................................................................
 * This is a qsort() comparison function used to sort matches.
 *
 * Input:
 *  v1, v2   void *  Pointers to the two matches to be compared.
 * Output:
 *  return    int    -1 -> v1 < v2.
 *                    0 -> v1 == v2
 *                    1 -> v1 > v2
 */
static int cpl_cmp_matches(const void *v1, const void *v2)
{
  const CplMatch *m1 = (const CplMatch *) v1;
  const CplMatch *m2 = (const CplMatch *) v2;
  return strcmp(m1->completion, m2->completion);
}

/*.......................................................................
 * Sort the array of matches in order of their suffixes.
 *
 * Input:
 *  cpl   WordCompletion *  The completion resource object.
 */
static void cpl_sort_suffixes(WordCompletion *cpl)
{
  qsort(cpl->result.matches, cpl->result.nmatch,
	sizeof(cpl->result.matches[0]), cpl_cmp_suffixes);
}

/*.......................................................................
 * This is a qsort() comparison function used to sort matches in order of
 * their suffixes.
 *
 * Input:
 *  v1, v2   void *  Pointers to the two matches to be compared.
 * Output:
 *  return    int    -1 -> v1 < v2.
 *                    0 -> v1 == v2
 *                    1 -> v1 > v2
 */
static int cpl_cmp_suffixes(const void *v1, const void *v2)
{
  const CplMatch *m1 = (const CplMatch *) v1;
  const CplMatch *m2 = (const CplMatch *) v2;
  return strcmp(m1->suffix, m2->suffix);
}

/*.......................................................................
 * Find the common prefix of all of the matching completion matches,
 * and record a pointer to it in cpl->result.suffix. Note that this has
 * the side effect of sorting the matches into suffix order.
 *
 * Input:
 *  cpl   WordCompletion *  The completion resource object.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
static int cpl_common_suffix(WordCompletion *cpl)
{
  CplMatches *result;       /* The result container */
  const char *first, *last; /* The first and last matching suffixes */
  int length;               /* The length of the common suffix */
/*
 * Get the container of the array of matching files.
 */
  result = &cpl->result;
/*
 * No matching completions?
 */
  if(result->nmatch < 1)
    return 0;
/*
 * Sort th matches into suffix order.
 */
  cpl_sort_suffixes(cpl);
/*
 * Given that the array of matches is sorted, the first and last
 * suffixes are those that differ most in their prefixes, so the common
 * prefix of these strings is the longest common prefix of all of the
 * suffixes.
 */
  first = result->matches[0].suffix;
  last = result->matches[result->nmatch - 1].suffix;
/*
 * Find the point at which the first and last matching strings
 * first difffer.
 */
  while(*first && *first == *last) {
    first++;
    last++;
  };
/*
 * How long is the common suffix?
 */
  length = first - result->matches[0].suffix;
/*
 * Allocate memory to record the common suffix.
 */
  result->suffix = _sg_alloc_string(cpl->sg, length);
  if(!result->suffix) {
    _err_record_msg(cpl->err,
		    "Insufficient memory to record common completion suffix.",
		    END_ERR_MSG);
    return 1;
  };
/*
 * Record the common suffix.
 */
  strncpy(result->suffix, result->matches[0].suffix, length);
  result->suffix[length] = '\0';
  return 0;
}

/*.......................................................................
 * Discard the contents of the array of possible completion matches.
 *
 * Input:
 *  cpl   WordCompletion *  The word-completion resource object.
 */
static void cpl_clear_completions(WordCompletion *cpl)
{
/*
 * Discard all of the strings.
 */
  _clr_StringGroup(cpl->sg);
/*
 * Record the fact that the array is now empty.
 */
  cpl->result.nmatch = 0;
  cpl->result.suffix = NULL;
  cpl->result.cont_suffix = "";
/*
 * Also clear the error message.
 */
  _err_clear_msg(cpl->err);
  return;
}

/*.......................................................................
 * Given an input line and the point at which it completion is to be
 * attempted, return an array of possible completions.
 *
 * Input:
 *  cpl    WordCompletion *  The completion resource object.
 *  line             char *  The current input line.
 *  word_end          int    The index of the character in line[] which
 *                           follows the end of the token that is being
 *                           completed.
 *  data             void *  Anonymous 'data' to be passed to match_fn().
 *  match_fn   CplMatchFn *  The function that will identify the prefix
 *                           to be completed from the input line, and
 *                           record completion matches.
 * Output:
 *  return     CplMatches *  The container of the array of possible
 *                           completions. The returned pointer refers
 *                           to a container owned by the parent WordCompletion
 *                           object, and its contents thus potentially
 *                           change on every call to cpl_matches().
 *                           On error, NULL is returned, and a description
 *                           of the error can be acquired by calling
 *                           cpl_last_error(cpl).
 */
CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
			      int word_end, void *data,
			      CplMatchFn *match_fn)
{
  int line_len;   /* The total length of the input line */
/*
 * How long is the input line?
 */
  line_len = strlen(line);
/*
 * Check the arguments.
 */
  if(!cpl || !line || !match_fn || word_end < 0 || word_end > line_len) {
    if(cpl) {
      _err_record_msg(cpl->err, "cpl_complete_word: Invalid arguments.",
		      END_ERR_MSG);
    };
    return NULL;
  };
/*
 * Clear the return container.
 */
  cpl_clear_completions(cpl);
/*
 * Have the matching function record possible completion matches in
 * cpl->result.matches.
 */
  if(match_fn(cpl, data, line, word_end)) {
    if(_err_get_msg(cpl->err)[0] == '\0')
      _err_record_msg(cpl->err, "Error completing word.", END_ERR_MSG);
    return NULL;
  };
/*
 * Record a copy of the common initial part of all of the prefixes
 * in cpl->result.common.
 */
  if(cpl_common_suffix(cpl))
    return NULL;
/*
 * Sort the matches into lexicographic order.
 */
  cpl_sort_matches(cpl);
/*
 * Discard any duplicate matches.
 */
  cpl_zap_duplicates(cpl);
/*
 * If there is more than one match, discard the continuation suffix.
 */
  if(cpl->result.nmatch > 1)
    cpl->result.cont_suffix = "";
/*
 * Return the array of matches.
 */
  return &cpl->result;
}

/*.......................................................................
 * Recall the return value of the last call to cpl_complete_word().
 *
 * Input:
 *  cpl    WordCompletion *  The completion resource object.
 * Output:
 *  return     CplMatches *  The container of the array of possible
 *                           completions, as returned by the last call to
 *                           cpl_complete_word(). The returned pointer refers
 *                           to a container owned by the parent WordCompletion
 *                           object, and its contents thus potentially
 *                           change on every call to cpl_complete_word().
 *                           On error, either in the execution of this
 *                           function, or in the last call to
 *                           cpl_complete_word(), NULL is returned, and a
 *                           description of the error can be acquired by
 *                           calling cpl_last_error(cpl).
 */
CplMatches *cpl_recall_matches(WordCompletion *cpl)
{
  return (!cpl || *_err_get_msg(cpl->err)!='\0') ? NULL : &cpl->result;
}

/*.......................................................................
 * Print out an array of matching completions.
 *
 * Input:
 *  result  CplMatches *   The container of the sorted array of
 *                         completions.
 *  fp            FILE *   The output stream to write to.
 *  term_width     int     The width of the terminal.
 * Output:
 *  return         int     0 - OK.
 *                         1 - Error.
 */
int cpl_list_completions(CplMatches *result, FILE *fp, int term_width)
{
  return _cpl_output_completions(result, _io_write_stdio, fp, term_width);
}

/*.......................................................................
 * Print an array of matching completions via a callback function.
 *
 * Input:
 *  result   CplMatches *  The container of the sorted array of
 *                         completions.
 *  write_fn  GlWriteFn *  The function to call to write the completions,
 *                         or 0 to discard the output.
 *  data           void *  Anonymous data to pass to write_fn().
 *  term_width      int    The width of the terminal.
 * Output:
 *  return          int     0 - OK.
 *                          1 - Error.
 */
int _cpl_output_completions(CplMatches *result, GlWriteFn *write_fn, void *data,
			    int term_width)
{
  CplListFormat fmt; /* List formatting information */
  int lnum;          /* The sequential number of the line to print next */
/*
 * Not enough space to list anything?
 */
  if(term_width < 1)
    return 0;
/*
 * Do we have a callback to write via, and any completions to be listed?
 */
  if(write_fn && result && result->nmatch>0) {
/*
 * Work out how to arrange the listing into fixed sized columns.
 */
    cpl_plan_listing(result, term_width, &fmt);
/*
 * Print the listing via the specified callback.
 */
    for(lnum=0; lnum < fmt.nline; lnum++) {
      if(cpl_format_line(result, &fmt, lnum, write_fn, data))
	return 1;
    };
  };
  return 0;
}

/*.......................................................................
 * Return a description of the string-completion error that occurred.
 *
 * Input:
 *  cpl   WordCompletion *  The string-completion resource object.
 * Output:
 *  return    const char *  The description of the last error.
 */
const char *cpl_last_error(WordCompletion *cpl)
{
  return cpl ? _err_get_msg(cpl->err) : "NULL WordCompletion argument";
}

/*.......................................................................
 * When an error occurs while performing a completion, you registerf a
 * terse description of the error by calling cpl_record_error(). This
 * message will then be returned on the next call to cpl_last_error().
 *
 * Input:
 *  cpl   WordCompletion *  The string-completion resource object that was
 *                          originally passed to the callback.
 *  errmsg    const char *  The description of the error.
 */
void cpl_record_error(WordCompletion *cpl, const char *errmsg)
{
  if(cpl && errmsg)
    _err_record_msg(cpl->err, errmsg, END_ERR_MSG);
}

/*.......................................................................
 * This is the builtin completion callback function which performs file
 * completion.
 *
 * Input:
 *  cpl  WordCompletion *  An opaque pointer to the object that will
 *                         contain the matches. This should be filled
 *                         via zero or more calls to cpl_add_completion().
 *  data           void *  Either NULL to request the default
 *                         file-completion behavior, or a pointer to a
 *                         CplFileConf structure, whose members specify
 *                         a different behavior.
 *  line           char *  The current input line.
 *  word_end        int    The index of the character in line[] which
 *                         follows the end of the token that is being
 *                         completed.
 * Output
 *  return          int    0 - OK.
 *                         1 - Error.
 */
CPL_MATCH_FN(cpl_file_completions)
{
#ifdef WITHOUT_FILE_SYSTEM
  return 0;
#else
  const char *start_path;  /* The pointer to the start of the pathname */
                           /*  in line[]. */
  CplFileConf *conf;       /* The new-style configuration object. */
/*
 * The following configuration object will be used if the caller didn't
 * provide one.
 */
  CplFileConf default_conf;
/*
 * This function can be called externally, so check its arguments.
 */
  if(!cpl)
    return 1;
  if(!line || word_end < 0) {
    _err_record_msg(cpl->err, "cpl_file_completions: Invalid arguments.",
		    END_ERR_MSG);
    return 1;
  };
/*
 * The 'data' argument is either a CplFileConf pointer, identifiable
 * by having an integer id code as its first member, or the deprecated
 * CplFileArgs pointer, or can be NULL to request the default
 * configuration.
 */
  if(data && *(int *)data == CFC_ID_CODE) {
    conf = (CplFileConf *) data;
  } else {
/*
 * Select the defaults.
 */
    conf = &default_conf;
    cpl_init_FileConf(&default_conf);
/*
 * If we have been passed an instance of the deprecated CplFileArgs
 * structure, copy its configuration parameters over the defaults.
 */
    if(data) {
      CplFileArgs *args = (CplFileArgs *) data;
      conf->escaped = args->escaped;
      conf->file_start = args->file_start;
    };
  };
/*
 * Get the start of the filename. If not specified by the caller
 * identify it by searching backwards in the input line for an
 * unescaped space or the start of the line.
 */
  if(conf->file_start < 0) {
    start_path = _pu_start_of_path(line, word_end);
    if(!start_path) {
      _err_record_msg(cpl->err, "Unable to find the start of the filename.",
		      END_ERR_MSG);
      return 1;
    };
  } else {
    start_path = line + conf->file_start;
  };
/*
 * Perform the completion.
 */
  if(_cf_complete_file(cpl, cpl->cf, line, start_path - line, word_end,
		      conf->escaped, conf->chk_fn, conf->chk_data)) {
    cpl_record_error(cpl, _cf_last_error(cpl->cf));
    return 1;
  };
  return 0;
#endif
}

/*.......................................................................
 * Initialize a CplFileArgs structure with default configuration
 * parameters. Note that the CplFileArgs configuration type is
 * deprecated. The opaque CplFileConf object should be used in future
 * applications.
 *
 * Input:
 *  cfa  CplFileArgs *  The configuration object of the
 *                      cpl_file_completions() callback.
 */
void cpl_init_FileArgs(CplFileArgs *cfa)
{
  if(cfa) {
    cfa->escaped = 1;
    cfa->file_start = -1;
  };
}

#ifndef WITHOUT_FILE_SYSTEM
/*.......................................................................
 * Initialize a CplFileConf structure with default configuration
 * parameters.
 *
 * Input:
 *  cfc  CplFileConf *  The configuration object of the
 *                      cpl_file_completions() callback.
 */
static void cpl_init_FileConf(CplFileConf *cfc)
{
  if(cfc) {
    cfc->id = CFC_ID_CODE;
    cfc->escaped = 1;
    cfc->file_start = -1;
    cfc->chk_fn = 0;
    cfc->chk_data = NULL;
  };
}
#endif

/*.......................................................................
 * Create a new CplFileConf object and initialize it with defaults.
 *
 * Output:
 *  return  CplFileConf *  The new object, or NULL on error.
 */
CplFileConf *new_CplFileConf(void)
{
#ifdef WITHOUT_FILE_SYSTEM
  errno = EINVAL;
  return NULL;
#else
  CplFileConf *cfc;  /* The object to be returned */
/*
 * Allocate the container.
 */
  cfc = (CplFileConf *)malloc(sizeof(CplFileConf));
  if(!cfc)
    return NULL;
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_CplFileConf().
 */
  cpl_init_FileConf(cfc);
  return cfc;
#endif
}

/*.......................................................................
 * Delete a CplFileConf object.
 *
 * Input:
 *  cfc    CplFileConf *  The object to be deleted.
 * Output:
 *  return CplFileConf *  The deleted object (always NULL).
 */
CplFileConf *del_CplFileConf(CplFileConf *cfc)
{
#ifndef WITHOUT_FILE_SYSTEM
  if(cfc) {
/*
 * Delete the container.
 */
    free(cfc);
  };
#endif
  return NULL;
}

/*.......................................................................
 * If backslashes in the filename should be treated as literal
 * characters, call the following function with literal=1. Otherwise
 * the default is to treat them as escape characters, used for escaping
 * spaces etc..
 *
 * Input:
 *  cfc    CplFileConf *  The cpl_file_completions() configuration object
 *                        to be configured.
 *  literal        int    Pass non-zero here to enable literal interpretation
 *                        of backslashes. Pass 0 to turn off literal
 *                        interpretation.
 */
void cfc_literal_escapes(CplFileConf *cfc, int literal)
{
#ifndef WITHOUT_FILE_SYSTEM
  if(cfc)
    cfc->escaped = !literal;
#endif
}

/*.......................................................................
 * Call this function if you know where the index at which the
 * filename prefix starts in the input line. Otherwise by default,
 * or if you specify start_index to be -1, the filename is taken
 * to start after the first unescaped space preceding the cursor,
 * or the start of the line, which ever comes first.
 *
 * Input:
 *  cfc    CplFileConf *  The cpl_file_completions() configuration object
 *                        to be configured.
 *  start_index    int    The index of the start of the filename in
 *                        the input line, or -1 to select the default.
 */
void cfc_file_start(CplFileConf *cfc, int start_index)
{
#ifndef WITHOUT_FILE_SYSTEM
  if(cfc)
    cfc->file_start = start_index;
#endif
}

/*.......................................................................
 * If you only want certain types of files to be included in the
 * list of completions, you use the following function to specify a
 * callback function which will be called to ask whether a given file
 * should be included.
 *
 * Input:
 *  cfc    CplFileConf *  The cpl_file_completions() configuration object
 *                        to be configured.
 *  chk_fn  CplCheckFn *  Zero to disable filtering, or a pointer to a
 *                        function that returns 1 if a given file should
 *                        be included in the list of completions.
 *  chk_data      void *  Anonymous data to be passed to chk_fn()
 *                        every time that it is called.
 */
void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, void *chk_data)
{
#ifndef WITHOUT_FILE_SYSTEM
  if(cfc) {
    cfc->chk_fn = chk_fn;
    cfc->chk_data = chk_data;
  };
#endif
}

/*.......................................................................
 * The following CplCheckFn callback returns non-zero if the specified
 * filename is that of an executable.
 */
CPL_CHECK_FN(cpl_check_exe)
{
#ifdef WITHOUT_FILE_SYSTEM
  return 0;
#else
  return _pu_path_is_exe(pathname);
#endif
}

/*.......................................................................
 * Remove duplicates from a sorted array of matches.
 *
 * Input:
 *  cpl   WordCompletion *  The completion resource object.
 */
static void cpl_zap_duplicates(WordCompletion *cpl)
{
  CplMatch *matches;       /* The array of matches */
  int nmatch;              /* The number of elements in matches[] */
  const char *completion;  /* The completion string of the last unique match */
  const char *type_suffix; /* The type of the last unique match */
  int src;                 /* The index of the match being considered */
  int dst;                 /* The index at which to record the next */
                           /*  unique match. */
/*
 * Get the array of matches and the number of matches that it
 * contains.
 */
  matches = cpl->result.matches;
  nmatch = cpl->result.nmatch;
/*
 * No matches?
 */
  if(nmatch < 1)
    return;
/*
 * Initialize the comparison strings with the first match.
 */
  completion = matches[0].completion;
  type_suffix = matches[0].type_suffix;
/*
 * Go through the array of matches, copying each new unrecorded
 * match at the head of the array, while discarding duplicates.
 */
  for(src=dst=1; src<nmatch; src++) {
    CplMatch *match = matches + src;
    if(strcmp(completion, match->completion) != 0 ||
       strcmp(type_suffix, match->type_suffix) != 0) {
      if(src != dst)
	matches[dst] = *match;
      dst++;
      completion = match->completion;
      type_suffix = match->type_suffix;
    };
  };
/*
 * Record the number of unique matches that remain.
 */
  cpl->result.nmatch = dst;
  return;
}

/*.......................................................................
 * Work out how to arrange a given array of completions into a listing
 * of one or more fixed size columns.
 *
 * Input:
 *  result   CplMatches *   The set of completions to be listed.
 *  term_width      int     The width of the terminal. A lower limit of
 *                          zero is quietly enforced.
 * Input/Output:
 *  fmt   CplListFormat *   The formatting information will be assigned
 *                          to the members of *fmt.
 */
static void cpl_plan_listing(CplMatches *result, int term_width,
			     CplListFormat *fmt)
{
  int maxlen;    /* The length of the longest matching string */
  int i;
/*
 * Ensure that term_width >= 0.
 */
  if(term_width < 0)
    term_width = 0;
/*
 * Start by assuming the worst case, that either nothing will fit
 * on the screen, or that there are no matches to be listed.
 */
  fmt->term_width = term_width;
  fmt->column_width = 0;
  fmt->nline = fmt->ncol = 0;
/*
 * Work out the maximum length of the matching strings.
 */
  maxlen = 0;
  for(i=0; i<result->nmatch; i++) {
    CplMatch *match = result->matches + i;
    int len = strlen(match->completion) + strlen(match->type_suffix);
    if(len > maxlen)
      maxlen = len;
  };
/*
 * Nothing to list?
 */
  if(maxlen == 0)
    return;
/*
 * Split the available terminal width into columns of
 * maxlen + CPL_COL_SEP characters.
 */
  fmt->column_width = maxlen;
  fmt->ncol = fmt->term_width / (fmt->column_width + CPL_COL_SEP);
/*
 * If the column width is greater than the terminal width, zero columns
 * will have been selected. Set a lower limit of one column. Leave it
 * up to the caller how to deal with completions who's widths exceed
 * the available terminal width.
 */
  if(fmt->ncol < 1)
    fmt->ncol = 1;
/*
 * How many lines of output will be needed?
 */
  fmt->nline = (result->nmatch + fmt->ncol - 1) / fmt->ncol;
  return;
}

/*.......................................................................
 * Render one line of a multi-column listing of completions, using a
 * callback function to pass the output to an arbitrary destination.
 *
 * Input:
 *  result      CplMatches *  The container of the sorted array of
 *                            completions.
 *  fmt      CplListFormat *  Formatting information.
 *  lnum               int    The index of the line to print, starting
 *                            from 0, and incrementing until the return
 *                            value indicates that there is nothing more
 *                            to be printed.
 *  write_fn     GlWriteFn *  The function to call to write the line, or
 *                            0 to discard the output.
 *  data              void *  Anonymous data to pass to write_fn().
 * Output:
 *  return             int    0 - Line printed ok.
 *                            1 - Nothing to print.
 */
static int cpl_format_line(CplMatches *result, CplListFormat *fmt, int lnum,
			   GlWriteFn *write_fn, void *data)
{
  int col;             /* The index of the list column being output */
/*
 * If the line index is out of bounds, there is nothing to be written.
 */
  if(lnum < 0 || lnum >= fmt->nline)
    return 1;
/*
 * If no output function has been provided, return as though the
 * line had been printed.
 */
  if(!write_fn)
    return 0;
/*
 * Print the matches in 'ncol' columns, sorted in line order within each
 * column.
 */
  for(col=0; col < fmt->ncol; col++) {
    int m = col*fmt->nline + lnum;
/*
 * Is there another match to be written? Note that in general
 * the last line of a listing will have fewer filled columns
 * than the initial lines.
 */
    if(m < result->nmatch) {
      CplMatch *match = result->matches + m;
/*
 * How long are the completion and type-suffix strings?
 */
      int clen = strlen(match->completion);
      int tlen = strlen(match->type_suffix);
/*
 * Write the completion string.
 */
      if(write_fn(data, match->completion, clen) != clen)
	return 1;
/*
 * Write the type suffix, if any.
 */
      if(tlen > 0 && write_fn(data, match->type_suffix, tlen) != tlen)
	return 1;
/*
 * If another column follows the current one, pad to its start with spaces.
 */
      if(col+1 < fmt->ncol) {
/*
 * The following constant string of spaces is used to pad the output.
 */
	static const char spaces[] = "                    ";
	static const int nspace = sizeof(spaces) - 1;
/*
 * Pad to the next column, using as few sub-strings of the spaces[]
 * array as possible.
 */
	int npad = fmt->column_width + CPL_COL_SEP - clen - tlen;
	while(npad>0) {
	  int n = npad > nspace ? nspace : npad;
	  if(write_fn(data, spaces + nspace - n, n) != n)
	    return 1;
	  npad -= n;
	};
      };
    };
  };
/*
 * Start a new line.
 */
  {
    char s[] = "\r\n";
    int n = strlen(s);
    if(write_fn(data, s, n) != n)
      return 1;
  };
  return 0;
}
#ifndef cplmatch_h
#define cplmatch_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * This header is not for use by external applicatons. It contains
 * internal immplementation features of the libtecla library, which
 * may change incompatibly between releases.
 */

/*
 * Display a list of completions via a callback function.
 */
int _cpl_output_completions(CplMatches *result, GlWriteFn *write_fn, void *data,
			    int term_width);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * If file-system access is to be excluded, this module has no function,
 * so all of its code should be excluded.
 */
#ifndef WITHOUT_FILE_SYSTEM

/*
 * Standard includes.
 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>

/*
 * Operating system includes.
 */
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <dirent.h>

#include "direader.h"
#include "errmsg.h"

/*
 * Use the reentrant POSIX threads version of readdir()?
 */
#if defined(PREFER_REENTRANT) && defined(_POSIX_C_SOURCE) && _POSIX_C_SOURCE >= 199506L
#define USE_READDIR_R 1
#endif

/*
 * Objects of the following type are used to maintain the resources
 * needed to read directories.
 */
struct DirReader {
  ErrMsg *err;             /* The error reporting buffer */
  DIR *dir;                /* The directory stream (if open, NULL otherwise) */
  struct dirent *file;     /* The latest directory entry */
#ifdef USE_READDIR_R
  struct dirent *buffer;   /* A buffer used by the threaded version of */
                           /*  readdir() */
  int buffer_dim;          /* The allocated size of buffer[] */
#endif
};

static int _dr_path_is_dir(const char *pathname);

/*.......................................................................
 * Create a new DirReader object.
 *
 * Output:
 *  return  DirReader *  The new object, or NULL on error.
 */
DirReader *_new_DirReader(void)
{
  DirReader *dr;  /* The object to be returned */
/*
 * Allocate the container.
 */
  dr = (DirReader *) malloc(sizeof(DirReader));
  if(!dr) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to _del_DirReader().
 */
  dr->err = NULL;
  dr->dir = NULL;
  dr->file = NULL;
#ifdef USE_READDIR_R
  dr->buffer = NULL;
  dr->buffer_dim = 0;
#endif
/*
 * Allocate a place to record error messages.
 */
  dr->err = _new_ErrMsg();
  if(!dr->err)
    return _del_DirReader(dr);
  return dr;
}

/*.......................................................................
 * Delete a DirReader object.
 *
 * Input:
 *  dr     DirReader *  The object to be deleted.
 * Output:
 *  return DirReader *  The deleted object (always NULL).
 */
DirReader *_del_DirReader(DirReader *dr)
{
  if(dr) {
    _dr_close_dir(dr);
#ifdef USE_READDIR_R
    free(dr->buffer);
#endif
    dr->err = _del_ErrMsg(dr->err);
    free(dr);
  };
  return NULL;
}

/*.......................................................................
 * Open a new directory.
 *
 * Input:
 *  dr      DirReader *   The directory reader resource object.
 *  path   const char *   The directory to be opened.
 * Input/Output:
 *  errmsg       char **  If an error occurs and errmsg isn't NULL, a
 *                        pointer to an error description will be assigned
 *                        to *errmsg.
 * Output:
 *  return        int     0 - OK.
 *                        1 - Error (see *errmsg for a description).
 */
int _dr_open_dir(DirReader *dr, const char *path, char **errmsg)
{
  DIR *dir = NULL;   /* The directory stream */
/*
 * If a directory is already open, close it first.
 */
  (void) _dr_close_dir(dr);
/*
 * Is the path a directory?
 */
  if(!_dr_path_is_dir(path)) {
    if(errmsg) {
      _err_record_msg(dr->err, "Can't open directory: ", path, END_ERR_MSG);
      *errmsg = _err_get_msg(dr->err);
    };
    return 1;
  };
/*
 * Attempt to open the directory.
 */
  dir = opendir(path);
  if(!dir) {
    if(errmsg) {
      _err_record_msg(dr->err, "Can't open directory: ", path, END_ERR_MSG);
      *errmsg = _err_get_msg(dr->err);
    };
    return 1;
  };
/*
 * If using POSIX threads, allocate a buffer for readdir_r().
 */
#ifdef USE_READDIR_R
  {
    size_t size;
    int name_max = pathconf(path, _PC_NAME_MAX);
#ifdef NAME_MAX
    if(name_max < 0)
      name_max = NAME_MAX;
#endif
    if(name_max < 0) {
      if(errmsg) {
	_err_record_msg(dr->err, "Unable to deduce readdir() buffer size.",
			END_ERR_MSG);
	*errmsg = _err_get_msg(dr->err);
      };
      closedir(dir);
      return 1;
    };
/*
 * How big a buffer do we need to allocate?
 */
    size = sizeof(struct dirent) + name_max;
/*
 * Extend the buffer?
 */
    if(size > dr->buffer_dim || !dr->buffer) {
      struct dirent *buffer = (struct dirent *) (dr->buffer ?
						 realloc(dr->buffer, size) :
						 malloc(size));
      if(!buffer) {
	if(errmsg) {
	  _err_record_msg(dr->err, "Insufficient memory for readdir() buffer.",
			  END_ERR_MSG);
	  *errmsg = _err_get_msg(dr->err);
	};
	closedir(dir);
	errno = ENOMEM;
	return 1;
      };
      dr->buffer = buffer;
      dr->buffer_dim = size;
    };
  };
#endif
/*
 * Record the successfully opened directory.
 */
  dr->dir = dir;
  return 0;
}

/*.......................................................................
 * If the DirReader object is currently contains an open directory,
 * close it.
 *
 * Input:
 *  dr    DirReader *   The directory reader resource object.
 */
void _dr_close_dir(DirReader *dr)
{
  if(dr && dr->dir) {
    closedir(dr->dir);
    dr->dir = NULL;
    dr->file = NULL;
    _err_clear_msg(dr->err);
  };
}

/*.......................................................................
 * Read the next file from the directory opened with _dr_open_dir().
 *
 * Input:
 *  dr    DirReader *  The directory reader resource object.
 * Output:
 *  return     char *  The name of the new file, or NULL if we reached
 *                     the end of the directory.
 */
char *_dr_next_file(DirReader *dr)
{
/*
 * Are we currently reading a directory?
 */
  if(dr->dir) {
/*
 * Read the next directory entry.
 */
#ifdef USE_READDIR_R
    if(readdir_r(dr->dir, dr->buffer, &dr->file) == 0 && dr->file)
      return dr->file->d_name;
#else
    dr->file = readdir(dr->dir);
    if(dr->file)
      return dr->file->d_name;
#endif
  };
/*
 * When the end of a directory is reached, close it.
 */
  _dr_close_dir(dr);
  return NULL;
}

/*.......................................................................
 * Return 1 if the specified pathname refers to a directory.
 *
 * Input:
 *  pathname  const char *  The path to test.
 * Output:
 *  return           int    0 - Not a directory.
 *                          1 - pathname[] refers to a directory.
 */
static int _dr_path_is_dir(const char *pathname)
{
  struct stat statbuf;    /* The file-statistics return buffer */
/*
 * Look up the file attributes.
 */
  if(stat(pathname, &statbuf) < 0)
    return 0;
/*
 * Is the file a directory?
 */
  return S_ISDIR(statbuf.st_mode) != 0;
}

#endif  /* ifndef WITHOUT_FILE_SYSTEM */
#ifndef dirreader_h
#define dirreader_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

typedef struct DirReader DirReader;

DirReader *_new_DirReader(void);
DirReader *_del_DirReader(DirReader *dr);

int _dr_open_dir(DirReader *dr, const char *pathname, char **errmsg);
char *_dr_next_file(DirReader *dr);
void _dr_close_dir(DirReader *dr);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <stdarg.h>

#include "errmsg.h"

/*
 * Encapsulate the error reporting buffer in an opaque object.
 */
struct ErrMsg {
  char msg[ERR_MSG_LEN+1];  /* An error message */
};

/*.......................................................................
 * Create a new error-message object.
 *
 * Output:
 *  return  ErrMsg *  The new object, or NULL on error.
 */
ErrMsg *_new_ErrMsg(void)
{
  ErrMsg *err;  /* The object to be returned */
/*
 * Allocate the container.
 */
  err = malloc(sizeof(ErrMsg));
  if(!err) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_ErrMsg().
 */
  err->msg[0] = '\0';
  return err;
}

/*.......................................................................
 * Delete an error-message object.
 *
 * Input:
 *  err     ErrMsg *  The object to be deleted.
 * Output:
 *  return  ErrMsg *  The deleted object (always NULL).
 */
ErrMsg *_del_ErrMsg(ErrMsg *err)
{
  if(err) {
    free(err);
  };
  return NULL;
}

/*.......................................................................
 * Record the concatenation of a list of string arguments in an error
 * message object. The last argument must be END_ERR_MSG to terminate
 * the argument list.
 *
 * Input:
 *  err      ErrMsg *   The error-message container.
 *  ...  const char *   Zero or more strings to be concatenated in buff[].
 *  ...  const char *   The last argument must always be END_ERR_MSG to
 *                      terminate the argument list.
 */
void _err_record_msg(ErrMsg *err, ...)
{
  va_list ap;         /* The variable argument list */
  const char *s;      /* The string being printed */
  size_t msglen = 0;  /* The total length of the message */
/*
 * Nowhere to record the result?
 */
  if(!err) {
    errno = EINVAL;
    return;
  };
/*
 * Concatenate the list of argument strings in err->msg[].
 */
  va_start(ap, err);
  while((s = va_arg(ap, const char *)) != END_ERR_MSG) {
/*
 * How much room is left in the output buffer (note that the output
 * buffer has ERR_MSG_LEN+1 elements).
 */
    int nleft = ERR_MSG_LEN - msglen;
/*
 * How long is the next string to be appended?
 */
    size_t slen = strlen(s);
/*
 * If there is any room left, append as much of the string
 * as will fit.
 */
    if(nleft > 0) {
      int nnew = slen < nleft ? slen : nleft;
      strncpy(err->msg + msglen, s, nnew);
      msglen += nnew;
    };
  };
  va_end(ap);
/*
 * Terminate the message.
 */
  err->msg[msglen] = '\0';
  return;
}

/*.......................................................................
 * Return a pointer to the error message buffer.
 *
 * Input:
 *  err     ErrMsg *  The container of the error message buffer.
 * Output:
 *  return    char *  The current error message, or NULL if err==NULL.
 */
char *_err_get_msg(ErrMsg *err)
{
  return err ? err->msg : NULL;
}

/*.......................................................................
 * Replace the current error message with an empty string.
 *
 * Input:
 *  err     ErrMsg *  The container of the error message buffer.
 */
void _err_clear_msg(ErrMsg *err)
{
  if(err)
    err->msg[0] = '\0';
}

#ifndef errmsg_h
#define errmsg_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Set the longest expected length of an error message (excluding its
 * '\0' terminator. Since any message over a nominal terminal width of
 * 80 characters is going to look a mess, it makes no sense to support
 * huge lengths. Note that many uses of strings declared with this
 * macro assume that it will be at least 81, so don't reduce it below
 * this limit.
 */
#define ERR_MSG_LEN 128

/*
 * Provide an opaque typedef to the error-message object.
 */
typedef struct ErrMsg ErrMsg;

/*
 * The following token is used to terminate the argument lists of calls
 * to _err_record_msg().
 */
#define END_ERR_MSG ((const char *)0)

/*
 * Allocate a new error-message buffer.
 */
ErrMsg *_new_ErrMsg(void);

/*
 * Delete an error message buffer.
 */
ErrMsg *_del_ErrMsg(ErrMsg *err);

/*
 * Concatenate a list of string arguments into the specified buffer, buff[],
 * which has an allocated size of buffdim characters.
 * The last argument must be END_ERR_MSG to terminate the argument list.
 */
void _err_record_msg(ErrMsg *err, ...);

/*
 * Replace the current error message with an empty string.
 */
void _err_clear_msg(ErrMsg *err);

/*
 * Return a pointer to the error message buffer. This is
 * a '\0' terminated character array containing ERR_MSG_LEN+1
 * elements.
 */
char *_err_get_msg(ErrMsg *err);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * If file-system access is to be excluded, this module has no function,
 * so all of its code should be excluded.
 */
#ifndef WITHOUT_FILE_SYSTEM

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>

#include "freelist.h"
#include "direader.h"
#include "pathutil.h"
#include "homedir.h"
#include "stringrp.h"
#include "libtecla.h"
#include "ioutil.h"
#include "expand.h"
#include "errmsg.h"

/*
 * Specify the number of elements to extend the files[] array by
 * when it proves to be too small. This also sets the initial size
 * of the array.
 */
#define MATCH_BLK_FACT 256

/*
 * A list of directory iterators is maintained using nodes of the
 * following form.
 */
typedef struct DirNode DirNode;
struct DirNode {
  DirNode *next;       /* The next directory in the list */
  DirNode *prev;       /* The node that precedes this node in the list */
  DirReader *dr;       /* The directory reader object */
};

typedef struct {
  FreeList *mem;       /* Memory for DirNode list nodes */
  DirNode *head;       /* The head of the list of used and unused cache nodes */
  DirNode *next;       /* The next unused node between head and tail */
  DirNode *tail;       /* The tail of the list of unused cache nodes */
} DirCache;

/*
 * Specify how many directory cache nodes to allocate at a time.
 */
#define DIR_CACHE_BLK 20

/*
 * Set the maximum length allowed for usernames.
 */
#define USR_LEN 100

/*
 * Set the maximum length allowed for environment variable names.
 */
#define ENV_LEN 100

/*
 * Set the default number of spaces place between columns when listing
 * a set of expansions.
 */
#define EF_COL_SEP 2

struct ExpandFile {
  ErrMsg *err;            /* The error reporting buffer */
  StringGroup *sg;        /* A list of string segments in which */
                          /*  matching filenames are stored. */
  DirCache cache;         /* The cache of directory reader objects */
  PathName *path;         /* The pathname being matched */
  HomeDir *home;          /* Home-directory lookup object */
  int files_dim;          /* The allocated dimension of result.files[] */
  char usrnam[USR_LEN+1]; /* A user name */
  char envnam[ENV_LEN+1]; /* An environment variable name */
  FileExpansion result;   /* The container used to return the results of */
                          /*  expanding a path. */
};

static int ef_record_pathname(ExpandFile *ef, const char *pathname,
			      int remove_escapes);
static char *ef_cache_pathname(ExpandFile *ef, const char *pathname,
			       int remove_escapes);
static void ef_clear_files(ExpandFile *ef);

static DirNode *ef_open_dir(ExpandFile *ef, const char *pathname);
static DirNode *ef_close_dir(ExpandFile *ef, DirNode *node);
static char *ef_expand_special(ExpandFile *ef, const char *path, int pathlen);
static int ef_match_relative_pathname(ExpandFile *ef, DirReader *dr,
				      const char *pattern, int separate);
static int ef_matches_range(int c, const char *pattern, const char **endp);
static int ef_string_matches_pattern(const char *file, const char *pattern,
				      int xplicit, const char *nextp);
static int ef_cmp_strings(const void *v1, const void *v2);

/*
 * Encapsulate the formatting information needed to layout a
 * multi-column listing of expansions.
 */
typedef struct {
  int term_width;     /* The width of the terminal (characters) */
  int column_width;   /* The number of characters within in each column. */
  int ncol;           /* The number of columns needed */
  int nline;          /* The number of lines needed */
} EfListFormat;

/*
 * Given the current terminal width, and a list of file expansions,
 * determine how to best use the terminal width to display a multi-column
 * listing of expansions.
 */
static void ef_plan_listing(FileExpansion *result, int term_width,
			    EfListFormat *fmt);

/*
 * Display a given line of a multi-column list of file-expansions.
 */
static int ef_format_line(FileExpansion *result, EfListFormat *fmt, int lnum,
			  GlWriteFn *write_fn, void *data);

/*.......................................................................
 * Create the resources needed to expand filenames.
 *
 * Output:
 *  return  ExpandFile *  The new object, or NULL on error.
 */
ExpandFile *new_ExpandFile(void)
{
  ExpandFile *ef;  /* The object to be returned */
/*
 * Allocate the container.
 */
  ef = (ExpandFile *) malloc(sizeof(ExpandFile));
  if(!ef) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_ExpandFile().
 */
  ef->err = NULL;
  ef->sg = NULL;
  ef->cache.mem = NULL;
  ef->cache.head = NULL;
  ef->cache.next = NULL;
  ef->cache.tail = NULL;
  ef->path = NULL;
  ef->home = NULL;
  ef->result.files = NULL;
  ef->result.nfile = 0;
  ef->usrnam[0] = '\0';
  ef->envnam[0] = '\0';
/*
 * Allocate a place to record error messages.
 */
  ef->err = _new_ErrMsg();
  if(!ef->err)
    return del_ExpandFile(ef);
/*
 * Allocate a list of string segments for storing filenames.
 */
  ef->sg = _new_StringGroup(_pu_pathname_dim());
  if(!ef->sg)
    return del_ExpandFile(ef);
/*
 * Allocate a freelist for allocating directory cache nodes.
 */
  ef->cache.mem = _new_FreeList(sizeof(DirNode), DIR_CACHE_BLK);
  if(!ef->cache.mem)
    return del_ExpandFile(ef);
/*
 * Allocate a pathname buffer.
 */
  ef->path = _new_PathName();
  if(!ef->path)
    return del_ExpandFile(ef);
/*
 * Allocate an object for looking up home-directories.
 */
  ef->home = _new_HomeDir();
  if(!ef->home)
    return del_ExpandFile(ef);
/*
 * Allocate an array for files. This will be extended later if needed.
 */
  ef->files_dim = MATCH_BLK_FACT;
  ef->result.files = (char **) malloc(sizeof(ef->result.files[0]) *
				      ef->files_dim);
  if(!ef->result.files) {
    errno = ENOMEM;
    return del_ExpandFile(ef);
  };
  return ef;
}

/*.......................................................................
 * Delete a ExpandFile object.
 *
 * Input:
 *  ef     ExpandFile *  The object to be deleted.
 * Output:
 *  return ExpandFile *  The deleted object (always NULL).
 */
ExpandFile *del_ExpandFile(ExpandFile *ef)
{
  if(ef) {
    DirNode *dnode;
/*
 * Delete the string segments.
 */
    ef->sg = _del_StringGroup(ef->sg);
/*
 * Delete the cached directory readers.
 */
    for(dnode=ef->cache.head; dnode; dnode=dnode->next)
      dnode->dr = _del_DirReader(dnode->dr);
/*
 * Delete the memory from which the DirNode list was allocated, thus
 * deleting the list at the same time.
 */
    ef->cache.mem = _del_FreeList(ef->cache.mem, 1);
    ef->cache.head = ef->cache.tail = ef->cache.next = NULL;
/*
 * Delete the pathname buffer.
 */
    ef->path = _del_PathName(ef->path);
/*
 * Delete the home-directory lookup object.
 */
    ef->home = _del_HomeDir(ef->home);
/*
 * Delete the array of pointers to files.
 */
    if(ef->result.files) {
      free(ef->result.files);
      ef->result.files = NULL;
    };
/*
 * Delete the error report buffer.
 */
    ef->err = _del_ErrMsg(ef->err);
/*
 * Delete the container.
 */
    free(ef);
  };
  return NULL;
}

/*.......................................................................
 * Expand a pathname, converting ~user/ and ~/ patterns at the start
 * of the pathname to the corresponding home directories, replacing
 * $envvar with the value of the corresponding environment variable,
 * and then, if there are any wildcards, matching these against existing
 * filenames.
 *
 * If no errors occur, a container is returned containing the array of
 * files that resulted from the expansion. If there were no wildcards
 * in the input pathname, this will contain just the original pathname
 * after expansion of ~ and $ expressions. If there were any wildcards,
 * then the array will contain the files that matched them. Note that
 * if there were any wildcards but no existing files match them, this
 * is counted as an error and NULL is returned.
 *
 * The supported wildcards and their meanings are:
 *  *        -  Match any sequence of zero or more characters.
 *  ?        -  Match any single character.
 *  [chars]  -  Match any single character that appears in 'chars'.
 *              If 'chars' contains an expression of the form a-b,
 *              then any character between a and b, including a and b,
 *              matches. The '-' character looses its special meaning
 *              as a range specifier when it appears at the start
 *              of the sequence of characters.
 *  [^chars] -  The same as [chars] except that it matches any single
 *              character that doesn't appear in 'chars'.
 *
 * Wildcard expressions are applied to individual filename components.
 * They don't match across directory separators. A '.' character at
 * the beginning of a filename component must also be matched
 * explicitly by a '.' character in the input pathname, since these
 * are UNIX's hidden files.
 *
 * Input:
 *  ef         ExpandFile *  The pathname expansion resource object.
 *  path             char *  The path name to be expanded.
 *  pathlen           int    The length of the suffix of path[] that
 *                           constitutes the filename to be expanded,
 *                           or -1 to specify that the whole of the
 *                           path string should be used. Note that
 *                           regardless of the value of this argument,
 *                           path[] must contain a '\0' terminated
 *                           string, since this function checks that
 *                           pathlen isn't mistakenly too long.
 * Output:
 *  return  FileExpansion *  A pointer to a container within the given
 *                           ExpandFile object. This contains an array
 *                           of the pathnames that resulted from expanding
 *                           ~ and $ expressions and from matching any
 *                           wildcards, sorted into lexical order.
 *                           This container and its contents will be
 *                           recycled on subsequent calls, so if you need
 *                           to keep the results of two successive runs,
 *                           you will either have to allocate a private
 *                           copy of the array, or use two ExpandFile
 *                           objects.
 *
 *                           On error NULL is returned. A description
 *                           of the error can be acquired by calling the
 *                           ef_last_error() function.
 */
FileExpansion *ef_expand_file(ExpandFile *ef, const char *path, int pathlen)
{
  DirNode *dnode;       /* A directory-reader cache node */
  const char *dirname;  /* The name of the top level directory of the search */
  const char *pptr;     /* A pointer into path[] */
  int wild;             /* True if the path contains any wildcards */
/*
 * Check the arguments.
 */
  if(!ef || !path) {
    if(ef) {
      _err_record_msg(ef->err, "ef_expand_file: NULL path argument",
		      END_ERR_MSG);
    };
    errno = EINVAL;
    return NULL;
  };
/*
 * If the caller specified that the whole of path[] be matched,
 * work out the corresponding length.
 */
  if(pathlen < 0 || pathlen > strlen(path))
    pathlen = strlen(path);
/*
 * Discard previous expansion results.
 */
  ef_clear_files(ef);
/*
 * Preprocess the path, expanding ~/, ~user/ and $envvar references,
 * using ef->path as a work directory and returning a pointer to
 * a copy of the resulting pattern in the cache.
 */
  path = ef_expand_special(ef, path, pathlen);
  if(!path)
    return NULL;
/*
 * Clear the pathname buffer.
 */
  _pn_clear_path(ef->path);
/*
 * Does the pathname contain any wildcards?
 */
  for(wild=0,pptr=path; !wild && *pptr; pptr++) {
    switch(*pptr) {
    case '\\':                      /* Skip escaped characters */
      if(pptr[1])
	pptr++;
      break;
    case '*': case '?': case '[':   /* A wildcard character? */
      wild = 1;
      break;
    };
  };
/*
 * If there are no wildcards to match, copy the current expanded
 * path into the output array, removing backslash escapes while doing so.
 */
  if(!wild) {
    if(ef_record_pathname(ef, path, 1))
      return NULL;
/*
 * Does the filename exist?
 */
    ef->result.exists = _pu_file_exists(ef->result.files[0]);
/*
 * Match wildcards against existing files.
 */
  } else {
/*
 * Only existing files that match the pattern will be returned in the
 * cache.
 */
    ef->result.exists = 1;
/*
 * Treat matching of the root-directory as a special case since it
 * isn't contained in a directory.
 */
    if(strcmp(path, FS_ROOT_DIR) == 0) {
      if(ef_record_pathname(ef, FS_ROOT_DIR, 0))
	return NULL;
    } else {
/*
 * What should the top level directory of the search be?
 */
      if(strncmp(path, FS_ROOT_DIR, FS_ROOT_DIR_LEN) == 0) {
	dirname = FS_ROOT_DIR;
	if(!_pn_append_to_path(ef->path, FS_ROOT_DIR, -1, 0)) {
	  _err_record_msg(ef->err, "Insufficient memory to record path",
			  END_ERR_MSG);
	  return NULL;
	};
	path += FS_ROOT_DIR_LEN;
      } else {
	dirname = FS_PWD;
      };
/*
 * Open the top-level directory of the search.
 */
      dnode = ef_open_dir(ef, dirname);
      if(!dnode)
	return NULL;
/*
 * Recursively match successive directory components of the path.
 */
      if(ef_match_relative_pathname(ef, dnode->dr, path, 0)) {
	dnode = ef_close_dir(ef, dnode);
	return NULL;
      };
/*
 * Cleanup.
 */
      dnode = ef_close_dir(ef, dnode);
    };
/*
 * No files matched?
 */
    if(ef->result.nfile < 1) {
      _err_record_msg(ef->err, "No files match", END_ERR_MSG);
      return NULL;
    };
/*
 * Sort the pathnames that matched.
 */
    qsort(ef->result.files, ef->result.nfile, sizeof(ef->result.files[0]),
	  ef_cmp_strings);
  };
/*
 * Return the result container.
 */
  return &ef->result;
}

/*.......................................................................
 * Attempt to recursively match the given pattern with the contents of
 * the current directory, descending sub-directories as needed.
 *
 * Input:
 *  ef      ExpandFile *  The pathname expansion resource object.
 *  dr       DirReader *  The directory reader object of the directory
 *                        to be searched.
 *  pattern const char *  The pattern to match with files in the current
 *                        directory.
 *  separate       int    When appending a filename from the specified
 *                        directory to ef->pathname, insert a directory
 *                        separator between the existing pathname and
 *                        the filename, unless separate is zero.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error.
 */
static int ef_match_relative_pathname(ExpandFile *ef, DirReader *dr,
				       const char *pattern, int separate)
{
  const char *nextp;  /* The pointer to the character that follows the part */
                      /*  of the pattern that is to be matched with files */
                      /*  in the current directory. */
  char *file;         /* The name of the file being matched */
  int pathlen;        /* The length of ef->pathname[] on entry to this */
                      /*  function */
/*
 * Record the current length of the pathname string recorded in
 * ef->pathname[].
 */
  pathlen = strlen(ef->path->name);
/*
 * Get a pointer to the character that follows the end of the part of
 * the pattern that should be matched to files within the current directory.
 * This will either point to a directory separator, or to the '\0' terminator
 * of the pattern string.
 */
  for(nextp=pattern; *nextp && strncmp(nextp, FS_DIR_SEP, FS_DIR_SEP_LEN) != 0;
      nextp++)
    ;
/*
 * Read each file from the directory, attempting to match it to the
 * current pattern.
 */
  while((file=_dr_next_file(dr)) != NULL) {
/*
 * Does the latest file match the pattern up to nextp?
 */
    if(ef_string_matches_pattern(file, pattern, file[0]=='.', nextp)) {
/*
 * Append the new directory entry to the current matching pathname.
 */
      if((separate && _pn_append_to_path(ef->path, FS_DIR_SEP, -1, 0)==NULL) ||
	 _pn_append_to_path(ef->path, file, -1, 0)==NULL) {
	_err_record_msg(ef->err, "Insufficient memory to record path",
			END_ERR_MSG);
	return 1;
      };
/*
 * If we have reached the end of the pattern, record the accumulated
 * pathname in the list of matching files.
 */
      if(*nextp == '\0') {
	if(ef_record_pathname(ef, ef->path->name, 0))
	  return 1;
/*
 * If the matching directory entry is a subdirectory, and the
 * next character of the pattern is a directory separator,
 * recursively call the current function to scan the sub-directory
 * for matches.
 */
      } else if(_pu_path_is_dir(ef->path->name) &&
		strncmp(nextp, FS_DIR_SEP, FS_DIR_SEP_LEN) == 0) {
/*
 * If the pattern finishes with the directory separator, then
 * record the pathame as matching.
 */
	if(nextp[FS_DIR_SEP_LEN] == '\0') {
	  if(ef_record_pathname(ef, ef->path->name, 0))
	    return 1;
/*
 * Match files within the directory.
 */
	} else {
	  DirNode *subdnode = ef_open_dir(ef, ef->path->name);
	  if(subdnode) {
	    if(ef_match_relative_pathname(ef, subdnode->dr,
					   nextp+FS_DIR_SEP_LEN, 1)) {
	      subdnode = ef_close_dir(ef, subdnode);
	      return 1;
	    };
	    subdnode = ef_close_dir(ef, subdnode);
	  };
	};
      };
/*
 * Remove the latest filename from the pathname string, so that
 * another matching file can be appended.
 */
      ef->path->name[pathlen] = '\0';
    };
  };
  return 0;
}

/*.......................................................................
 * Record a new matching filename.
 *
 * Input:
 *  ef        ExpandFile *  The filename-match resource object.
 *  pathname  const char *  The pathname to record.
 *  remove_escapes   int    If true, remove backslash escapes in the
 *                          recorded copy of the pathname.
 * Output:
 *  return           int     0 - OK.
 *                           1 - Error (ef->err will contain a
 *                                      description of the error).
 */
static int ef_record_pathname(ExpandFile *ef, const char *pathname,
			      int remove_escapes)
{
  char *copy;          /* The recorded copy of pathname[] */
/*
 * Attempt to make a copy of the pathname in the cache.
 */
  copy = ef_cache_pathname(ef, pathname, remove_escapes);
  if(!copy)
    return 1;
/*
 * If there isn't room to record a pointer to the recorded pathname in the
 * array of files, attempt to extend the array.
 */
  if(ef->result.nfile + 1 > ef->files_dim) {
    int files_dim = ef->files_dim + MATCH_BLK_FACT;
    char **files = (char **) realloc(ef->result.files,
				     files_dim * sizeof(files[0]));
    if(!files) {
      _err_record_msg(ef->err,
	     "Insufficient memory to record all of the matching filenames",
	     END_ERR_MSG);
      errno = ENOMEM;
      return 1;
    };
    ef->result.files = files;
    ef->files_dim = files_dim;
  };
/*
 * Record a pointer to the new match.
 */
  ef->result.files[ef->result.nfile++] = copy;
  return 0;
}

/*.......................................................................
 * Record a pathname in the cache.
 *
 * Input:
 *  ef       ExpandFile *  The filename-match resource object.
 *  pathname       char *  The pathname to record.
 *  remove_escapes  int    If true, remove backslash escapes in the
 *                         copy of the pathname.
 * Output:
 *  return         char *  The pointer to the copy of the pathname.
 *                         On error NULL is returned and a description
 *                         of the error is left in ef->err.
 */
static char *ef_cache_pathname(ExpandFile *ef, const char *pathname,
			       int remove_escapes)
{
  char *copy = _sg_store_string(ef->sg, pathname, remove_escapes);
  if(!copy)
    _err_record_msg(ef->err, "Insufficient memory to store pathname",
		    END_ERR_MSG);
  return copy;
}

/*.......................................................................
 * Clear the results of the previous expansion operation, ready for the
 * next.
 *
 * Input:
 *  ef    ExpandFile *  The pathname expansion resource object.
 */
static void ef_clear_files(ExpandFile *ef)
{
  _clr_StringGroup(ef->sg);
  _pn_clear_path(ef->path);
  ef->result.exists = 0;
  ef->result.nfile = 0;
  _err_clear_msg(ef->err);
  return;
}

/*.......................................................................
 * Get a new directory reader object from the cache.
 *
 * Input:
 *  ef        ExpandFile *  The pathname expansion resource object.
 *  pathname  const char *  The pathname of the directory.
 * Output:
 *  return       DirNode *  The cache entry of the new directory reader,
 *                          or NULL on error. On error, ef->err will
 *                          contain a description of the error.
 */
static DirNode *ef_open_dir(ExpandFile *ef, const char *pathname)
{
  char *errmsg = NULL;  /* An error message from a called function */
  DirNode *node;        /* The cache node used */
/*
 * Get the directory reader cache.
 */
  DirCache *cache = &ef->cache;
/*
 * Extend the cache if there are no free cache nodes.
 */
  if(!cache->next) {
    node = (DirNode *) _new_FreeListNode(cache->mem);
    if(!node) {
      _err_record_msg(ef->err, "Insufficient memory to open a new directory",
		      END_ERR_MSG);
      return NULL;
    };
/*
 * Initialize the cache node.
 */
    node->next = NULL;
    node->prev = NULL;
    node->dr = NULL;
/*
 * Allocate a directory reader object.
 */
    node->dr = _new_DirReader();
    if(!node->dr) {
      _err_record_msg(ef->err, "Insufficient memory to open a new directory",
		      END_ERR_MSG);
      node = (DirNode *) _del_FreeListNode(cache->mem, node);
      return NULL;
    };
/*
 * Append the node to the cache list.
 */
    node->prev = cache->tail;
    if(cache->tail)
      cache->tail->next = node;
    else
      cache->head = node;
    cache->next = cache->tail = node;
  };
/*
 * Get the first unused node, but don't remove it from the list yet.
 */
  node = cache->next;
/*
 * Attempt to open the specified directory.
 */
  if(_dr_open_dir(node->dr, pathname, &errmsg)) {
    _err_record_msg(ef->err, errmsg, END_ERR_MSG);
    return NULL;
  };
/*
 * Now that we have successfully opened the specified directory,
 * remove the cache node from the list, and relink the list around it.
 */
  cache->next = node->next;
  if(node->prev)
    node->prev->next = node->next;
  else
    cache->head = node->next;
  if(node->next)
    node->next->prev = node->prev;
  else
    cache->tail = node->prev;
  node->next = node->prev = NULL;
/*
 * Return the successfully initialized cache node to the caller.
 */
  return node;
}

/*.......................................................................
 * Return a directory reader object to the cache, after first closing
 * the directory that it was managing.
 *
 * Input:
 *  ef    ExpandFile *  The pathname expansion resource object.
 *  node     DirNode *  The cache entry of the directory reader, as returned
 *                      by ef_open_dir().
 * Output:
 *  return   DirNode *  The deleted DirNode (ie. allways NULL).
 */
static DirNode *ef_close_dir(ExpandFile *ef, DirNode *node)
{
/*
 * Get the directory reader cache.
 */
  DirCache *cache = &ef->cache;
/*
 * Close the directory.
 */
  _dr_close_dir(node->dr);
/*
 * Return the node to the tail of the cache list.
 */
  node->next = NULL;
  node->prev = cache->tail;
  if(cache->tail)
    cache->tail->next = node;
  else
    cache->head = cache->tail = node;
  if(!cache->next)
    cache->next = node;
  return NULL;
}

/*.......................................................................
 * Return non-zero if the specified file name matches a given glob
 * pattern.
 *
 * Input:
 *  file     const char *  The file-name component to be matched to the pattern.
 *  pattern  const char *  The start of the pattern to match against file[].
 *  xplicit         int    If non-zero, the first character must be matched
 *                         explicitly (ie. not with a wildcard).
 *  nextp    const char *  The pointer to the the character following the
 *                         end of the pattern in pattern[].
 * Output:
 *  return    int          0 - Doesn't match.
 *                         1 - The file-name string matches the pattern.
 */
static int ef_string_matches_pattern(const char *file, const char *pattern,
				      int xplicit, const char *nextp)
{
  const char *pptr = pattern; /* The pointer used to scan the pattern */
  const char *fptr = file;    /* The pointer used to scan the filename string */
/*
 * Match each character of the pattern in turn.
 */
  while(pptr < nextp) {
/*
 * Handle the next character of the pattern.
 */
    switch(*pptr) {
/*
 * A match zero-or-more characters wildcard operator.
 */
    case '*':
/*
 * Skip the '*' character in the pattern.
 */
      pptr++;
/*
 * If wildcards aren't allowed, the pattern doesn't match.
 */
      if(xplicit)
	return 0;
/*
 * If the pattern ends with a the '*' wildcard, then the
 * rest of the filename matches this.
 */
      if(pptr >= nextp)
	return 1;
/*
 * Using the wildcard to match successively longer sections of
 * the remaining characters of the filename, attempt to match
 * the tail of the filename against the tail of the pattern.
 */
      for( ; *fptr; fptr++) {
	if(ef_string_matches_pattern(fptr, pptr, 0, nextp))
	  return 1;
      };
      return 0; /* The pattern following the '*' didn't match */
      break;
/*
 * A match-one-character wildcard operator.
 */
    case '?':
/*
 * If there is a character to be matched, skip it and advance the
 * pattern pointer.
 */
      if(!xplicit && *fptr) {
        fptr++;
        pptr++;
/*
 * If we hit the end of the filename string, there is no character
 * matching the operator, so the string doesn't match.
 */
      } else {
        return 0;
      };
      break;
/*
 * A character range operator, with the character ranges enclosed
 * in matching square brackets.
 */
    case '[':
      if(xplicit || !ef_matches_range(*fptr++, ++pptr, &pptr))
        return 0;
      break;
/*
 * A backslash in the pattern prevents the following character as
 * being seen as a special character.
 */
    case '\\':
      pptr++;
      /* Note fallthrough to default */
/*
 * A normal character to be matched explicitly.
 */
      /* FALLTHROUGH */
    default:
      if(*fptr == *pptr) {
        fptr++;
        pptr++;
      } else {
        return 0;
      };
      break;
    };
/*
 * After passing the first character, turn off the explicit match
 * requirement.
 */
    xplicit = 0;
  };
/*
 * To get here the pattern must have been exhausted. If the filename
 * string matched, then the filename string must also have been
 * exhausted.
 */
  return *fptr == '\0';
}

/*.......................................................................
 * Match a character range expression terminated by an unescaped close
 * square bracket.
 *
 * Input:
 *  c               int     The character to be matched with the range
 *                          pattern.
 *  pattern  const char *   The range pattern to be matched (ie. after the
 *                          initiating '[' character).
 *  endp     const char **  On output a pointer to the character following the
 *                          range expression will be assigned to *endp.
 * Output:
 *  return          int     0 - Doesn't match.
 *                          1 - The character matched.
 */
static int ef_matches_range(int c, const char *pattern, const char **endp)
{
  const char *pptr = pattern;  /* The pointer used to scan the pattern */
  int invert = 0;              /* True to invert the sense of the match */
  int matched = 0;             /* True if the character matched the pattern */
/*
 * If the first character is a caret, the sense of the match is
 * inverted and only if the character isn't one of those in the
 * range, do we say that it matches.
 */
  if(*pptr == '^') {
    pptr++;
    invert = 1;
  };
/*
 * The hyphen is only a special character when it follows the first
 * character of the range (not including the caret).
 */
  if(*pptr == '-') {
    pptr++;
    if(c == '-') {
      *endp = pptr;
      matched = 1;
    };
/*
 * Skip other leading '-' characters since they make no sense.
 */
    while(*pptr == '-')
      pptr++;
  };
/*
 * The hyphen is only a special character when it follows the first
 * character of the range (not including the caret or a hyphen).
 */
  if(*pptr == ']') {
    pptr++;
    if(c == ']') {
      *endp = pptr;
      matched = 1;
    };
  };
/*
 * Having dealt with the characters that have special meanings at
 * the beginning of a character range expression, see if the
 * character matches any of the remaining characters of the range,
 * up until a terminating ']' character is seen.
 */
  while(!matched && *pptr && *pptr != ']') {
/*
 * Is this a range of characters signaled by the two end characters
 * separated by a hyphen?
 */
    if(*pptr == '-') {
      if(pptr[1] != ']') {
        if(c >= pptr[-1] && c <= pptr[1])
	  matched = 1;
	pptr += 2;
      };
/*
 * A normal character to be compared directly.
 */
    } else if(*pptr++ == c) {
      matched = 1;
    };
  };
/*
 * Find the terminating ']'.
 */
  while(*pptr && *pptr != ']')
    pptr++;
/*
 * Did we find a terminating ']'?
 */
  if(*pptr == ']') {
    *endp = pptr + 1;
    return matched ? !invert : invert;
  };
/*
 * If the pattern didn't end with a ']' then it doesn't match, regardless
 * of the value of the required sense of the match.
 */
  *endp = pptr;
  return 0;
}

/*.......................................................................
 * This is a qsort() comparison function used to sort strings.
 *
 * Input:
 *  v1, v2   void *  Pointers to the two strings to be compared.
 * Output:
 *  return    int    -1 -> v1 < v2.
 *                    0 -> v1 == v2
 *                    1 -> v1 > v2
 */
static int ef_cmp_strings(const void *v1, const void *v2)
{
  char * const *s1 = (char * const *) v1;
  char * const *s2 = (char * const *) v2;
  return strcmp(*s1, *s2);
}

/*.......................................................................
 * Preprocess a path, expanding ~/, ~user/ and $envvar references, using
 * ef->path as a work buffer, then copy the result into a cache entry,
 * and return a pointer to this copy.
 *
 * Input:
 *  ef    ExpandFile *  The resource object of the file matcher.
 *  pathlen      int    The length of the prefix of path[] to be expanded.
 * Output:
 *  return      char *  A pointer to a copy of the output path in the
 *                      cache. On error NULL is returned, and a description
 *                      of the error is left in ef->err.
 */
static char *ef_expand_special(ExpandFile *ef, const char *path, int pathlen)
{
  int spos;      /* The index of the start of the path segment that needs */
                 /*  to be copied from path[] to the output pathname. */
  int ppos;      /* The index of a character in path[] */
  char *pptr;    /* A pointer into the output path */
  int escaped;   /* True if the previous character was a '\' */
  int i;
/*
 * Clear the pathname buffer.
 */
  _pn_clear_path(ef->path);
/*
 * We need to perform two passes, one to expand environment variables
 * and a second to do tilde expansion. This caters for the case
 * where an initial dollar expansion yields a tilde expression.
 */
  escaped = 0;
  for(spos=ppos=0; ppos < pathlen; ppos++) {
    int c = path[ppos];
    if(escaped) {
      escaped = 0;
    } else if(c == '\\') {
      escaped = 1;
    } else if(c == '$') {
      int envlen;   /* The length of the environment variable */
      char *value;  /* The value of the environment variable */
/*
 * Record the preceding unrecorded part of the pathname.
 */
      if(spos < ppos && _pn_append_to_path(ef->path, path + spos, ppos-spos, 0)
	 == NULL) {
	_err_record_msg(ef->err, "Insufficient memory to expand path",
			END_ERR_MSG);
	return NULL;
      };
/*
 * Skip the dollar.
 */
      ppos++;
/*
 * Copy the environment variable name that follows the dollar into
 * ef->envnam[], stopping if a directory separator or end of string
 * is seen.
 */
      for(envlen=0; envlen<ENV_LEN && ppos < pathlen &&
	  strncmp(path + ppos, FS_DIR_SEP, FS_DIR_SEP_LEN); envlen++)
	ef->envnam[envlen] = path[ppos++];
/*
 * If the username overflowed the buffer, treat it as invalid (note that
 * on most unix systems only 8 characters are allowed in a username,
 * whereas our ENV_LEN is much bigger than that.
 */
      if(envlen >= ENV_LEN) {
	_err_record_msg(ef->err, "Environment variable name too long",
			END_ERR_MSG);
	return NULL;
      };
/*
 * Terminate the environment variable name.
 */
      ef->envnam[envlen] = '\0';
/*
 * Lookup the value of the environment variable.
 */
      value = getenv(ef->envnam);
      if(!value) {
	_err_record_msg(ef->err, "No expansion found for: $", ef->envnam,
			END_ERR_MSG);
	return NULL;
      };
/*
 * Copy the value of the environment variable into the output pathname.
 */
      if(_pn_append_to_path(ef->path, value, -1, 0) == NULL) {
	_err_record_msg(ef->err, "Insufficient memory to expand path",
			END_ERR_MSG);
	return NULL;
      };
/*
 * Record the start of the uncopied tail of the input pathname.
 */
      spos = ppos;
    };
  };
/*
 * Record the uncopied tail of the pathname.
 */
  if(spos < ppos && _pn_append_to_path(ef->path, path + spos, ppos-spos, 0)
     == NULL) {
    _err_record_msg(ef->err, "Insufficient memory to expand path", END_ERR_MSG);
    return NULL;
  };
/*
 * If the first character of the resulting pathname is a tilde,
 * then attempt to substitute the home directory of the specified user.
 */
  pptr = ef->path->name;
  if(*pptr == '~' && path[0] != '\\') {
    int usrlen;           /* The length of the username following the tilde */
    const char *homedir;  /* The home directory of the user */
    int homelen;          /* The length of the home directory string */
    int plen;             /* The current length of the path */
    int skip=0;           /* The number of characters to skip after the ~user */
/*
 * Get the current length of the output path.
 */
    plen = strlen(ef->path->name);
/*
 * Skip the tilde.
 */
    pptr++;
/*
 * Copy the optional username that follows the tilde into ef->usrnam[].
 */
    for(usrlen=0; usrlen<USR_LEN && *pptr &&
	strncmp(pptr, FS_DIR_SEP, FS_DIR_SEP_LEN); usrlen++)
      ef->usrnam[usrlen] = *pptr++;
/*
 * If the username overflowed the buffer, treat it as invalid (note that
 * on most unix systems only 8 characters are allowed in a username,
 * whereas our USR_LEN is much bigger than that.
 */
    if(usrlen >= USR_LEN) {
      _err_record_msg(ef->err, "Username too long", END_ERR_MSG);
      return NULL;
    };
/*
 * Terminate the username string.
 */
    ef->usrnam[usrlen] = '\0';
/*
 * Lookup the home directory of the user.
 */
    homedir = _hd_lookup_home_dir(ef->home, ef->usrnam);
    if(!homedir) {
      _err_record_msg(ef->err, _hd_last_home_dir_error(ef->home), END_ERR_MSG);
      return NULL;
    };
    homelen = strlen(homedir);
/*
 * ~user and ~ are usually followed by a directory separator to
 * separate them from the file contained in the home directory.
 * If the home directory is the root directory, then we don't want
 * to follow the home directory by a directory separator, so we must
 * erase it.
 */
    if(strcmp(homedir, FS_ROOT_DIR) == 0 &&
       strncmp(pptr, FS_DIR_SEP, FS_DIR_SEP_LEN) == 0) {
      skip = FS_DIR_SEP_LEN;
    };
/*
 * If needed, increase the size of the pathname buffer to allow it
 * to accomodate the home directory instead of the tilde expression.
 * Note that pptr may not be valid after this call.
 */
    if(_pn_resize_path(ef->path, plen - usrlen - 1 - skip + homelen)==NULL) {
      _err_record_msg(ef->err, "Insufficient memory to expand filename",
		      END_ERR_MSG);
      return NULL;
    };
/*
 * Move the part of the pathname that follows the tilde expression to
 * the end of where the home directory will need to be inserted.
 */
    memmove(ef->path->name + homelen,
	    ef->path->name + 1 + usrlen + skip, plen - usrlen - 1 - skip+1);
/*
 * Write the home directory at the beginning of the string.
 */
    for(i=0; i<homelen; i++)
      ef->path->name[i] = homedir[i];
  };
/*
 * Copy the result into the cache, and return a pointer to the copy.
 */
  return ef_cache_pathname(ef, ef->path->name, 0);
}

/*.......................................................................
 * Return a description of the last path-expansion error that occurred.
 *
 * Input:
 *  ef     ExpandFile *   The path-expansion resource object.
 * Output:
 *  return       char *   The description of the last error.
 */
const char *ef_last_error(ExpandFile *ef)
{
  return ef ? _err_get_msg(ef->err) : "NULL ExpandFile argument";
}

/*.......................................................................
 * Print out an array of matching files.
 *
 * Input:
 *  result  FileExpansion *   The container of the sorted array of
 *                            expansions.
 *  fp               FILE *   The output stream to write to.
 *  term_width        int     The width of the terminal.
 * Output:
 *  return            int     0 - OK.
 *                            1 - Error.
 */
int ef_list_expansions(FileExpansion *result, FILE *fp, int term_width)
{
  return _ef_output_expansions(result, _io_write_stdio, fp, term_width);
}

/*.......................................................................
 * Print out an array of matching files via a callback.
 *
 * Input:
 *  result  FileExpansion *  The container of the sorted array of
 *                           expansions.
 *  write_fn    GlWriteFn *  The function to call to write the
 *                           expansions or 0 to discard the output.
 *  data             void *  Anonymous data to pass to write_fn().
 *  term_width        int    The width of the terminal.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int _ef_output_expansions(FileExpansion *result, GlWriteFn *write_fn,
			  void *data, int term_width)
{
  EfListFormat fmt; /* List formatting information */
  int lnum;          /* The sequential number of the line to print next */
/*
 * Not enough space to list anything?
 */
  if(term_width < 1)
    return 0;
/*
 * Do we have a callback to write via, and any expansions to be listed?
 */
  if(write_fn && result && result->nfile>0) {
/*
 * Work out how to arrange the listing into fixed sized columns.
 */
    ef_plan_listing(result, term_width, &fmt);
/*
 * Print the listing to the specified stream.
 */
    for(lnum=0; lnum < fmt.nline; lnum++) {
      if(ef_format_line(result, &fmt, lnum, write_fn, data))
	return 1;
    };
  };
  return 0;
}

/*.......................................................................
 * Work out how to arrange a given array of completions into a listing
 * of one or more fixed size columns.
 *
 * Input:
 *  result   FileExpansion *   The set of completions to be listed.
 *  term_width         int     The width of the terminal. A lower limit of
 *                             zero is quietly enforced.
 * Input/Output:
 *  fmt       EfListFormat *   The formatting information will be assigned
 *                             to the members of *fmt.
 */
static void ef_plan_listing(FileExpansion *result, int term_width,
			    EfListFormat *fmt)
{
  int maxlen;    /* The length of the longest matching string */
  int i;
/*
 * Ensure that term_width >= 0.
 */
  if(term_width < 0)
    term_width = 0;
/*
 * Start by assuming the worst case, that either nothing will fit
 * on the screen, or that there are no matches to be listed.
 */
  fmt->term_width = term_width;
  fmt->column_width = 0;
  fmt->nline = fmt->ncol = 0;
/*
 * Work out the maximum length of the matching strings.
 */
  maxlen = 0;
  for(i=0; i<result->nfile; i++) {
    int len = strlen(result->files[i]);
    if(len > maxlen)
      maxlen = len;
  };
/*
 * Nothing to list?
 */
  if(maxlen == 0)
    return;
/*
 * Split the available terminal width into columns of
 * maxlen + EF_COL_SEP characters.
 */
  fmt->column_width = maxlen;
  fmt->ncol = fmt->term_width / (fmt->column_width + EF_COL_SEP);
/*
 * If the column width is greater than the terminal width, zero columns
 * will have been selected. Set a lower limit of one column. Leave it
 * up to the caller how to deal with completions who's widths exceed
 * the available terminal width.
 */
  if(fmt->ncol < 1)
    fmt->ncol = 1;
/*
 * How many lines of output will be needed?
 */
  fmt->nline = (result->nfile + fmt->ncol - 1) / fmt->ncol;
  return;
}

/*.......................................................................
 * Render one line of a multi-column listing of completions, using a
 * callback function to pass the output to an arbitrary destination.
 *
 * Input:
 *  result   FileExpansion *  The container of the sorted array of
 *                            completions.
 *  fmt       EfListFormat *  Formatting information.
 *  lnum               int    The index of the line to print, starting
 *                            from 0, and incrementing until the return
 *                            value indicates that there is nothing more
 *                            to be printed.
 *  write_fn     GlWriteFn *  The function to call to write the line, or
 *                            0 to discard the output.
 *  data              void *  Anonymous data to pass to write_fn().
 * Output:
 *  return             int    0 - Line printed ok.
 *                            1 - Nothing to print.
 */
static int ef_format_line(FileExpansion *result, EfListFormat *fmt, int lnum,
			  GlWriteFn *write_fn, void *data)
{
  int col;             /* The index of the list column being output */
/*
 * If the line index is out of bounds, there is nothing to be written.
 */
  if(lnum < 0 || lnum >= fmt->nline)
    return 1;
/*
 * If no output function has been provided, return as though the line
 * had been printed.
 */
  if(!write_fn)
    return 0;
/*
 * Print the matches in 'ncol' columns, sorted in line order within each
 * column.
 */
  for(col=0; col < fmt->ncol; col++) {
    int m = col*fmt->nline + lnum;
/*
 * Is there another match to be written? Note that in general
 * the last line of a listing will have fewer filled columns
 * than the initial lines.
 */
    if(m < result->nfile) {
      char *file = result->files[m];
/*
 * How long are the completion and type-suffix strings?
 */
      int flen = strlen(file);
/*
 * Write the completion string.
 */
      if(write_fn(data, file, flen) != flen)
	return 1;
/*
 * If another column follows the current one, pad to its start with spaces.
 */
      if(col+1 < fmt->ncol) {
/*
 * The following constant string of spaces is used to pad the output.
 */
	static const char spaces[] = "                    ";
	static const int nspace = sizeof(spaces) - 1;
/*
 * Pad to the next column, using as few sub-strings of the spaces[]
 * array as possible.
 */
	int npad = fmt->column_width + EF_COL_SEP - flen;
	while(npad>0) {
	  int n = npad > nspace ? nspace : npad;
	  if(write_fn(data, spaces + nspace - n, n) != n)
	    return 1;
	  npad -= n;
	};
      };
    };
  };
/*
 * Start a new line.
 */
  {
    char s[] = "\r\n";
    int n = strlen(s);
    if(write_fn(data, s, n) != n)
      return 1;
  };
  return 0;
}

#endif  /* ifndef WITHOUT_FILE_SYSTEM */
#ifndef expand_h
#define expand_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * This header is not for use by external applicatons. It contains
 * internal immplementation features of the libtecla library, which
 * may change incompatibly between releases.
 */

/*
 * Print a list of expansions via a callback function.
 */
int _ef_output_expansions(FileExpansion *result, GlWriteFn *write_fn,
			  void *data, int term_width);


#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>

#include "freelist.h"

typedef struct FreeListBlock FreeListBlock;
struct FreeListBlock {
  FreeListBlock *next;   /* The next block in the list */
  char *nodes;           /* The array of free-list nodes */
};

struct FreeList {
  size_t node_size;         /* The size of a free-list node */
  unsigned blocking_factor; /* The number of nodes per block */
  long nbusy;               /* The number of nodes that are in use */
  long ntotal;              /* The total number of nodes in the free list */
  FreeListBlock *block;     /* The head of the list of free-list blocks */
  void *free_list;          /* The free-list of nodes */
};

static FreeListBlock *_new_FreeListBlock(FreeList *fl);
static FreeListBlock *_del_FreeListBlock(FreeListBlock *fl);
static void _thread_FreeListBlock(FreeList *fl, FreeListBlock *block);

/*.......................................................................
 * Allocate a new free-list from blocks of 'blocking_factor' objects of size
 * node_size.
 *
 * Input:
 *  node_size         size_t    The size of the free-list nodes to be returned
 *                              by _new_FreeListNode(). Use sizeof() to
 *                              determine this.
 *  blocking_factor unsigned    The number of objects of size 'object_size'
 *                              to allocate per block.
 * Output:
 *  return          FreeList *  The new freelist, or NULL on error.
 */
FreeList *_new_FreeList(size_t node_size, unsigned blocking_factor)
{
  FreeList *fl;  /* The new free-list container */
/*
 * When a free-list node is on the free-list, it is used as a (void *)
 * link field. Roundup node_size to a mulitple of the size of a void
 * pointer. This, plus the fact that the array of nodes is obtained via
 * malloc, which returns memory suitably aligned for any object, will
 * ensure that the first sizeof(void *) bytes of each node will be
 * suitably aligned to use as a (void *) link pointer.
 */
  node_size = sizeof(void *) *
    ((node_size + sizeof(void *) - 1) / sizeof(void *));
/*
 * Enfore a minimum block size.
 */
  if(blocking_factor < 1)
    blocking_factor = 1;
/*
 * Allocate the container of the free list.
 */
  fl = (FreeList *) malloc(sizeof(FreeList));
  if(!fl) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to _del_FreeList().
 */
  fl->node_size = node_size;
  fl->blocking_factor = blocking_factor;
  fl->nbusy = 0;
  fl->ntotal = 0;
  fl->block = NULL;
  fl->free_list = NULL;
/*
 * Allocate the first block of memory.
 */
  fl->block = _new_FreeListBlock(fl);
  if(!fl->block) {
    errno = ENOMEM;
    return _del_FreeList(fl, 1);
  };
/*
 * Add the new list of nodes to the free-list.
 */
  fl->free_list = fl->block->nodes;
/*
 * Return the free-list for use.
 */
  return fl;
}

/*.......................................................................
 * Re-thread a freelist to reclaim all allocated nodes.
 * This function should not be called unless if it is known that none
 * of the currently allocated nodes are still being used.
 *
 * Input:
 *  fl          FreeList *  The free-list to be reset, or NULL.
 */
void _rst_FreeList(FreeList *fl)
{
  if(fl) {
    FreeListBlock *block;
/*
 * Re-thread the nodes of each block into individual free-lists.
 */
    for(block=fl->block; block; block=block->next)
      _thread_FreeListBlock(fl, block);
/*
 * Link all of the block freelists into one large freelist.
 */
    fl->free_list = NULL;
    for(block=fl->block; block; block=block->next) {
/*
 * Locate the last node of the current block.
 */
      char *last_node = block->nodes + fl->node_size *
	(fl->blocking_factor - 1);
/*
 * Make the link-field of the last node point to the first
 * node of the current freelist, then make the first node of the
 * new block the start of the freelist.
 */
      *(void **)last_node = fl->free_list;
      fl->free_list = block->nodes;
    };
/*
 * All allocated nodes have now been returned to the freelist.
 */
    fl->nbusy = 0;
  };
}

/*.......................................................................
 * Delete a free-list.
 *
 * Input:
 *  fl          FreeList *  The free-list to be deleted, or NULL.
 *  force            int    If force==0 then _del_FreeList() will complain
 *                           and refuse to delete the free-list if any
 *                           of nodes have not been returned to the free-list.
 *                          If force!=0 then _del_FreeList() will not check
 *                           whether any nodes are still in use and will
 *                           always delete the list.
 * Output:
 *  return      FreeList *  Always NULL (even if the list couldn't be
 *                          deleted).
 */
FreeList *_del_FreeList(FreeList *fl, int force)
{
  if(fl) {
/*
 * Check whether any nodes are in use.
 */
    if(!force && _busy_FreeListNodes(fl) != 0) {
      errno = EBUSY;
      return NULL;
    };
/*
 * Delete the list blocks.
 */
    {
      FreeListBlock *next = fl->block;
      while(next) {
	FreeListBlock *block = next;
	next = block->next;
	block = _del_FreeListBlock(block);
      };
    };
    fl->block = NULL;
    fl->free_list = NULL;
/*
 * Discard the container.
 */
    free(fl);
  };
  return NULL;
}

/*.......................................................................
 * Allocate a new object from a free-list.
 *
 * Input:
 *  fl        FreeList *  The free-list to return an object from.
 * Output:
 *  return        void *  A new object of the size that was specified via
 *                        the node_size argument of _new_FreeList() when
 *                        the free-list was created, or NULL if there
 *                        is insufficient memory, or 'fl' is NULL.
 */
void *_new_FreeListNode(FreeList *fl)
{
  void *node;  /* The node to be returned */
/*
 * Check arguments.
 */
  if(!fl)
    return NULL;
/*
 * If the free-list has been exhausted extend it by allocating
 * another block of nodes.
 */
  if(!fl->free_list) {
    FreeListBlock *block = _new_FreeListBlock(fl);
    if(!block)
      return NULL;
/*
 * Prepend the new block to the list of free-list blocks.
 */
    block->next = fl->block;
    fl->block = block;
/*
 * Add the new list of nodes to the free-list.
 */
    fl->free_list = fl->block->nodes;
  };
/*
 * Remove and return a node from the front of the free list.
 */
  node = fl->free_list;
  fl->free_list = *(void **)node;
/*
 * Record the loss of a node from the free-list.
 */
  fl->nbusy++;
/*
 * Return the node.
 */
  return node;
}

/*.......................................................................
 * Return an object to the free-list that it was allocated from.
 *
 * Input:
 *  fl        FreeList *  The free-list from which the object was taken.
 *  object        void *  The node to be returned.
 * Output:
 *  return        void *  Always NULL.
 */
void *_del_FreeListNode(FreeList *fl, void *object)
{
/*
 * Check arguments.
 */
  if(!fl)
    return NULL;
/*
 * Return the node to the head of the free list.
 */
  if(object) {
    *(void **)object = fl->free_list;
    fl->free_list = object;
/*
 * Record the return of the node to the free-list.
 */
    fl->nbusy--;
  };
  return NULL;
}

/*.......................................................................
 * Return a count of the number of nodes that are currently allocated.
 *
 * Input:
 *  fl      FreeList *  The list to count wrt, or NULL.
 * Output:
 *  return      long    The number of nodes (or 0 if fl==NULL).
 */
long _busy_FreeListNodes(FreeList *fl)
{
  return fl ? fl->nbusy : 0;
}

/*.......................................................................
 * Query the number of allocated nodes in the freelist which are
 * currently unused.
 *
 * Input:
 *  fl      FreeList *  The list to count wrt, or NULL.
 * Output:
 *  return      long    The number of unused nodes (or 0 if fl==NULL).
 */
long _idle_FreeListNodes(FreeList *fl)
{
  return fl ? (fl->ntotal - fl->nbusy) : 0;
}

/*.......................................................................
 * Allocate a new list of free-list nodes. On return the nodes will
 * be linked together as a list starting with the node at the lowest
 * address and ending with a NULL next pointer.
 *
 * Input:
 *  fl          FreeList *  The free-list to allocate the list for.
 * Output:
 *  return FreeListBlock *  The new linked block of free-list nodes,
 *                          or NULL on error.
 */
static FreeListBlock *_new_FreeListBlock(FreeList *fl)
{
  FreeListBlock *block;  /* The new block to be returned */
/*
 * Allocate the container.
 */
  block = (FreeListBlock *) malloc(sizeof(FreeListBlock));
  if(!block)
    return NULL;
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to _del_FreeListBlock().
 */
  block->next = NULL;
  block->nodes = NULL;
/*
 * Allocate the block of nodes.
 */
  block->nodes = (char *) malloc(fl->node_size * fl->blocking_factor);
  if(!block->nodes)
    return _del_FreeListBlock(block);
/*
 * Initialize the block as a linked list of FreeListNode's.
 */
  _thread_FreeListBlock(fl, block);
/*
 * Update the record of the number of nodes in the freelist.
 */
  fl->ntotal += fl->blocking_factor;
  return block;
}

/*.......................................................................
 * Link each node of a freelist block to the node that follows it.
 *
 * Input:
 *  fl         FreeList *   The freelist that contains the block.
 *  block FreeListBlock *   The block to be threaded.
 */
static void _thread_FreeListBlock(FreeList *fl, FreeListBlock *block)
{
  char *mem = block->nodes;
  int i;
  for(i=0; i<fl->blocking_factor - 1; i++, mem += fl->node_size)
    *(void **)mem = mem + fl->node_size;  /* Link to the next node */
  *(void **)mem = NULL;                   /* Terminate the list */
}

/*.......................................................................
 * Delete a free-list block.
 *
 * Input:
 *  fl      FreeListBlock *  The block to be deleted, or NULL.
 * Output:
 *  return  FreeListBlock *  Always NULL.
 */
static FreeListBlock *_del_FreeListBlock(FreeListBlock *fl)
{
  if(fl) {
    fl->next = NULL;
    if(fl->nodes)
      free(fl->nodes);
    fl->nodes = NULL;
    free(fl);
  };
  return NULL;
}
#ifndef freelist_h
#define freelist_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * This module provides a memory allocation scheme that helps to
 * prevent memory fragmentation by allocating large blocks of
 * fixed sized objects and forming them into a free-list for
 * subsequent allocations. The free-list is expanded as needed.
 */
typedef struct FreeList FreeList;

/*
 * Allocate a new free-list from blocks of 'blocking_factor' objects of size
 * node_size. The node_size argument should be determined by applying
 * the sizeof() operator to the object type that you intend to allocate from
 * the freelist.
 */
FreeList *_new_FreeList(size_t node_size, unsigned blocking_factor);

/*
 * If it is known that none of the nodes currently allocated from
 * a freelist are still in use, the following function can be called
 * to return all nodes to the freelist without the overhead of
 * having to call del_FreeListNode() for every allocated node. The
 * nodes of the freelist can then be reused by future callers to
 * new_FreeListNode().
 */
void _rst_FreeList(FreeList *fl);

/*
 * Delete a free-list.
 */
FreeList *_del_FreeList(FreeList *fl, int force);

/*
 * Determine the number of nodes that are currently in use.
 */
long _busy_FreeListNodes(FreeList *fl);

/*
 * Query the number of allocated nodes in the freelist which are
 * currently unused.
 */
long _idle_FreeListNodes(FreeList *fl);

/*
 * Allocate a new object from a free-list.
 */
void *_new_FreeListNode(FreeList *fl);

/*
 * Return an object to the free-list that it was allocated from.
 */
void *_del_FreeListNode(FreeList *fl, void *object);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 * Copyright (c) 2016 by Delphix. All rights reserved.
 */

/*
 * Standard headers.
 */
#include <stdio.h>
#include <stdlib.h>
#include <signal.h>
#include <string.h>
#include <errno.h>
#include <ctype.h>
#include <setjmp.h>
#include <stdarg.h>

/*
 * UNIX headers.
 */
#include <sys/ioctl.h>
#ifdef HAVE_SELECT
#ifdef HAVE_SYS_SELECT_H
#include <sys/select.h>
#endif
#include <sys/time.h>
#include <sys/types.h>
#endif

/*
 * Handle the different sources of terminal control string and size
 * information. Note that if no terminal information database is available,
 * ANSI VT100 control sequences are used.
 */
#if defined(USE_TERMINFO) || defined(USE_TERMCAP)
/*
 * Include curses.h or ncurses/curses.h depending on which is available.
 */
#ifdef HAVE_CURSES_H
#include <curses.h>
#elif defined(HAVE_NCURSES_CURSES_H)
#include <ncurses/curses.h>
#endif
/*
 * Include term.h where available.
 */
#if defined(HAVE_TERM_H)
#include <term.h>
#elif defined(HAVE_NCURSES_TERM_H)
#include <ncurses/term.h>
#endif
/*
 * When using termcap, include termcap.h on systems that have it.
 * Otherwise assume that all prototypes are provided by curses.h.
 */
#if defined(USE_TERMCAP) && defined(HAVE_TERMCAP_H)
#include <termcap.h>
#endif

/*
 * Under Solaris default Curses the output function that tputs takes is
 * declared to have a char argument. On all other systems and on Solaris
 * X/Open Curses (Issue 4, Version 2) it expects an int argument (using
 * c89 or options -I /usr/xpg4/include -L /usr/xpg4/lib -R /usr/xpg4/lib
 * selects XPG4v2 Curses on Solaris 2.6 and later).
 *
 * Similarly, under Mac OS X, the return value of the tputs output
 * function is declared as void, whereas it is declared as int on
 * other systems.
 */
#if defined __sun && defined __SVR4 && !defined _XOPEN_CURSES
typedef int TputsRetType;
typedef char TputsArgType;              /* int tputs(char c, FILE *fp) */
#define TPUTS_RETURNS_VALUE 1
#elif defined(__APPLE__) && defined(__MACH__)
typedef void TputsRetType;
typedef int TputsArgType;               /* void tputs(int c, FILE *fp) */
#define TPUTS_RETURNS_VALUE 0
#else
typedef int TputsRetType;
typedef int TputsArgType;               /* int tputs(int c, FILE *fp) */
#define TPUTS_RETURNS_VALUE 1
#endif

/*
 * Use the above specifications to prototype our tputs callback function.
 */
static TputsRetType gl_tputs_putchar(TputsArgType c);

#endif  /* defined(USE_TERMINFO) || defined(USE_TERMCAP) */

/*
 * If the library is being compiled without filesystem access facilities,
 * ensure that none of the action functions that normally do access the
 * filesystem are bound by default, and that it they do get bound, that
 * they don't do anything.
 */
#if WITHOUT_FILE_SYSTEM
#define HIDE_FILE_SYSTEM
#endif

/*
 * POSIX headers.
 */
#include <unistd.h>
#include <fcntl.h>
#include <termios.h>

/*
 * Provide typedefs for standard POSIX structures.
 */
typedef struct sigaction SigAction;
typedef struct termios Termios;

/*
 * Which flag is used to select non-blocking I/O with fcntl()?
 */
#undef NON_BLOCKING_FLAG
#if defined(O_NONBLOCK)
#define NON_BLOCKING_FLAG (O_NONBLOCK)
#elif defined(O_NDELAY)
#define NON_BLOCKING_FLAG (O_NDELAY)
#endif

/*
 * What value should we give errno if I/O blocks when it shouldn't.
 */
#undef BLOCKED_ERRNO
#if defined(EAGAIN)
#define BLOCKED_ERRNO (EAGAIN)
#elif defined(EWOULDBLOCK)
#define BLOCKED_ERRNO (EWOULDBLOCK)
#elif defined(EIO)
#define BLOCKED_ERRNO (EIO)
#else
#define BLOCKED_ERRNO 0
#endif

/*
 * Local headers.
 */
#ifndef WITHOUT_FILE_SYSTEM
#include "pathutil.h"
#endif
#include "libtecla.h"
#include "keytab.h"
#include "getline.h"
#include "ioutil.h"
#include "history.h"
#include "freelist.h"
#include "stringrp.h"
#include "chrqueue.h"
#include "cplmatch.h"
#ifndef WITHOUT_FILE_SYSTEM
#include "expand.h"
#endif
#include "errmsg.h"

/*
 * Enumerate the available editing styles.
 */
typedef enum {
  GL_EMACS_MODE,   /* Emacs style editing */
  GL_VI_MODE,      /* Vi style editing */
  GL_NO_EDITOR     /* Fall back to the basic OS-provided editing */
} GlEditor;

/*
 * Set the largest key-sequence that can be handled.
 */
#define GL_KEY_MAX 64

/*
 * In vi mode, the following datatype is used to implement the
 * undo command. It records a copy of the input line from before
 * the command-mode action which edited the input line.
 */
typedef struct {
  char *line;        /* A historical copy of the input line */
  int buff_curpos;   /* The historical location of the cursor in */
                     /*  line[] when the line was modified. */
  int ntotal;        /* The number of characters in line[] */
  int saved;         /* True once a line has been saved after the */
                     /*  last call to gl_interpret_char(). */
} ViUndo;

/*
 * In vi mode, the following datatype is used to record information
 * needed by the vi-repeat-change command.
 */
typedef struct {
  KtAction action;           /* The last action function that made a */
                             /*  change to the line. */
  int count;                 /* The repeat count that was passed to the */
                             /*  above command. */
  int input_curpos;          /* Whenever vi command mode is entered, the */
                             /*  the position at which it was first left */
                             /*  is recorded here. */
  int command_curpos;        /* Whenever vi command mode is entered, the */
                             /*  the location of the cursor is recorded */
                             /*  here. */
  char input_char;           /* Commands that call gl_read_terminal() */
                             /*  record the character here, so that it can */
                             /*  used on repeating the function. */
  int saved;                 /* True if a function has been saved since the */
                             /*  last call to gl_interpret_char(). */
  int active;                /* True while a function is being repeated. */
} ViRepeat;

/*
 * The following datatype is used to encapsulate information specific
 * to vi mode.
 */
typedef struct {
  ViUndo undo;               /* Information needed to implement the vi */
                             /*  undo command. */
  ViRepeat repeat;           /* Information needed to implement the vi */
                             /*  repeat command. */
  int command;               /* True in vi command-mode */
  int find_forward;          /* True if the last character search was in the */
                             /*  forward direction. */
  int find_onto;             /* True if the last character search left the */
                             /*  on top of the located character, as opposed */
                             /*  to just before or after it. */
  char find_char;            /* The last character sought, or '\0' if no */
                             /*  searches have been performed yet. */
} ViMode;

#ifdef HAVE_SELECT
/*
 * Define a type for recording a file-descriptor callback and its associated
 * data.
 */
typedef struct {
  GlFdEventFn *fn;   /* The callback function */
  void *data;        /* Anonymous data to pass to the callback function */
} GlFdHandler;

/*
 * A list of nodes of the following type is used to record file-activity
 * event handlers, but only on systems that have the select() system call.
 */
typedef struct GlFdNode GlFdNode;
struct GlFdNode {
  GlFdNode *next;    /* The next in the list of nodes */
  int fd;            /* The file descriptor being watched */
  GlFdHandler rd;    /* The callback to call when fd is readable */
  GlFdHandler wr;    /* The callback to call when fd is writable */
  GlFdHandler ur;    /* The callback to call when fd has urgent data */
};

/*
 * Set the number of the above structures to allocate every time that
 * the freelist of GlFdNode's becomes exhausted.
 */
#define GLFD_FREELIST_BLOCKING 10


static int gl_call_fd_handler(GetLine *gl, GlFdHandler *gfh, int fd,
			      GlFdEvent event);

static int gl_call_timeout_handler(GetLine *gl);

#endif

/*
 * Each signal that gl_get_line() traps is described by a list node
 * of the following type.
 */
typedef struct GlSignalNode GlSignalNode;
struct GlSignalNode {
  GlSignalNode *next;  /* The next signal in the list */
  int signo;           /* The number of the signal */
  sigset_t proc_mask;  /* A process mask which only includes signo */
  SigAction original;  /* The signal disposition of the calling program */
                       /*  for this signal. */
  unsigned flags;      /* A bitwise union of GlSignalFlags enumerators */
  GlAfterSignal after; /* What to do after the signal has been handled */
  int errno_value;     /* What to set errno to */
};

/*
 * Set the number of the above structures to allocate every time that
 * the freelist of GlSignalNode's becomes exhausted.
 */
#define GLS_FREELIST_BLOCKING 30

/*
 * Completion handlers and their callback data are recorded in
 * nodes of the following type.
 */
typedef struct GlCplCallback GlCplCallback;
struct GlCplCallback {
  CplMatchFn *fn;            /* The completion callback function */
  void *data;                /* Arbitrary callback data */
};

/*
 * The following function is used as the default completion handler when
 * the filesystem is to be hidden. It simply reports no completions.
 */
#ifdef HIDE_FILE_SYSTEM
static CPL_MATCH_FN(gl_no_completions);
#endif

/*
 * Specify how many GlCplCallback nodes are added to the GlCplCallback freelist
 * whenever it becomes exhausted.
 */
#define GL_CPL_FREELIST_BLOCKING 10

/*
 * External action functions and their callback data are recorded in
 * nodes of the following type.
 */
typedef struct GlExternalAction GlExternalAction;
struct GlExternalAction {
  GlActionFn *fn;          /* The function which implements the action */
  void *data;              /* Arbitrary callback data */
};

/*
 * Specify how many GlExternalAction nodes are added to the
 * GlExternalAction freelist whenever it becomes exhausted.
 */
#define GL_EXT_ACT_FREELIST_BLOCKING 10

/*
 * Define the contents of the GetLine object.
 * Note that the typedef for this object can be found in libtecla.h.
 */
struct GetLine {
  ErrMsg *err;               /* The error-reporting buffer */
  GlHistory *glh;            /* The line-history buffer */
  WordCompletion *cpl;       /* String completion resource object */
  GlCplCallback cplfn;       /* The completion callback */
#ifndef WITHOUT_FILE_SYSTEM
  ExpandFile *ef;            /* ~user/, $envvar and wildcard expansion */
                             /*  resource object. */
#endif
  StringGroup *capmem;       /* Memory for recording terminal capability */
                             /*  strings. */
  GlCharQueue *cq;           /* The terminal output character queue */
  int input_fd;              /* The file descriptor to read on */
  int output_fd;             /* The file descriptor to write to */
  FILE *input_fp;            /* A stream wrapper around input_fd */
  FILE *output_fp;           /* A stream wrapper around output_fd */
  FILE *file_fp;             /* When input is being temporarily taken from */
                             /*  a file, this is its file-pointer. Otherwise */
                             /*  it is NULL. */
  char *term;                /* The terminal type specified on the last call */
                             /*  to gl_change_terminal(). */
  int is_term;               /* True if stdin is a terminal */
  GlWriteFn *flush_fn;       /* The function to call to write to the terminal */
  GlIOMode io_mode;          /* The I/O mode established by gl_io_mode() */
  int raw_mode;              /* True while the terminal is in raw mode */
  GlPendingIO pending_io;    /* The type of I/O that is currently pending */
  GlReturnStatus rtn_status; /* The reason why gl_get_line() returned */
  int rtn_errno;             /* THe value of errno associated with rtn_status */
  size_t linelen;            /* The max number of characters per line */
  char *line;                /* A line-input buffer of allocated size */
                             /*  linelen+2. The extra 2 characters are */
                             /*  reserved for "\n\0". */
  char *cutbuf;              /* A cut-buffer of the same size as line[] */
  char *prompt;              /* The current prompt string */
  int prompt_len;            /* The length of the prompt string */
  int prompt_changed;        /* True after a callback changes the prompt */
  int prompt_style;          /* How the prompt string is displayed */
  FreeList *cpl_mem;         /* Memory for GlCplCallback objects */
  FreeList *ext_act_mem;     /* Memory for GlExternalAction objects */
  FreeList *sig_mem;         /* Memory for nodes of the signal list */
  GlSignalNode *sigs;        /* The head of the list of signals */
  int signals_masked;        /* True between calls to gl_mask_signals() and */
                             /*  gl_unmask_signals() */
  int signals_overriden;     /* True between calls to gl_override_signals() */
                             /*  and gl_restore_signals() */
  sigset_t all_signal_set;   /* The set of all signals that we are trapping */
  sigset_t old_signal_set;   /* The set of blocked signals on entry to */
                             /*  gl_get_line(). */
  sigset_t use_signal_set;   /* The subset of all_signal_set to unblock */
                             /*  while waiting for key-strokes */
  Termios oldattr;           /* Saved terminal attributes. */
  KeyTab *bindings;          /* A table of key-bindings */
  int ntotal;                /* The number of characters in gl->line[] */
  int buff_curpos;           /* The cursor position within gl->line[] */
  int term_curpos;           /* The cursor position on the terminal */
  int term_len;              /* The number of terminal characters used to */
                             /*  display the current input line. */
  int buff_mark;             /* A marker location in the buffer */
  int insert_curpos;         /* The cursor position at start of insert */
  int insert;                /* True in insert mode */
  int number;                /* If >= 0, a numeric argument is being read */
  int endline;               /* True to tell gl_get_input_line() to return */
                             /*  the current contents of gl->line[] */
  int displayed;             /* True if an input line is currently displayed */
  int redisplay;             /* If true, the input line will be redrawn */
                             /*  either after the current action function */
                             /*  returns, or when gl_get_input_line() */
                             /*  is next called. */
  int postpone;              /* _gl_normal_io() sets this flag, to */
                             /*  postpone any redisplays until */
                             /*  is next called, to resume line editing. */
  char keybuf[GL_KEY_MAX+1]; /* A buffer of currently unprocessed key presses */
  int nbuf;                  /* The number of characters in keybuf[] */
  int nread;                 /* The number of characters read from keybuf[] */
  KtAction current_action;   /* The action function that is being invoked */
  int current_count;         /* The repeat count passed to */
                             /*  current_acction.fn() */
  GlhLineID preload_id;      /* When not zero, this should be the ID of a */
                             /*  line in the history buffer for potential */
                             /*  recall. */
  int preload_history;       /* If true, preload the above history line when */
                             /*  gl_get_input_line() is next called. */
  long keyseq_count;         /* The number of key sequences entered by the */
                             /*  the user since new_GetLine() was called. */
  long last_search;          /* The value of keyseq_count during the last */
                             /*  history search operation. */
  GlEditor editor;           /* The style of editing, (eg. vi or emacs) */
  int silence_bell;          /* True if gl_ring_bell() should do nothing. */
  int automatic_history;     /* True to automatically archive entered lines */
                             /*  in the history list. */
  ViMode vi;                 /* Parameters used when editing in vi mode */
  const char *left;          /* The string that moves the cursor 1 character */
                             /*  left. */
  const char *right;         /* The string that moves the cursor 1 character */
                             /*  right. */
  const char *up;            /* The string that moves the cursor 1 character */
                             /*  up. */
  const char *down;          /* The string that moves the cursor 1 character */
                             /*  down. */
  const char *home;          /* The string that moves the cursor home */
  const char *bol;           /* Move cursor to beginning of line */
  const char *clear_eol;     /* The string that clears from the cursor to */
                             /*  the end of the line. */
  const char *clear_eod;     /* The string that clears from the cursor to */
                             /*  the end of the display. */
  const char *u_arrow;       /* The string returned by the up-arrow key */
  const char *d_arrow;       /* The string returned by the down-arrow key */
  const char *l_arrow;       /* The string returned by the left-arrow key */
  const char *r_arrow;       /* The string returned by the right-arrow key */
  const char *sound_bell;    /* The string needed to ring the terminal bell */
  const char *bold;          /* Switch to the bold font */
  const char *underline;     /* Underline subsequent characters */
  const char *standout;      /* Turn on standout mode */
  const char *dim;           /* Switch to a dim font */
  const char *reverse;       /* Turn on reverse video */
  const char *blink;         /* Switch to a blinking font */
  const char *text_attr_off; /* Turn off all text attributes */
  int nline;                 /* The height of the terminal in lines */
  int ncolumn;               /* The width of the terminal in columns */
#ifdef USE_TERMCAP
  char *tgetent_buf;         /* The buffer that is used by tgetent() to */
                             /*  store a terminal description. */
  char *tgetstr_buf;         /* The buffer that is used by tgetstr() to */
                             /*  store terminal capabilities. */
#endif
#ifdef USE_TERMINFO
  const char *left_n;        /* The parameter string that moves the cursor */
                             /*  n characters left. */
  const char *right_n;       /* The parameter string that moves the cursor */
                             /*  n characters right. */
#endif
  char *app_file;            /* The pathname of the application-specific */
                             /*  .teclarc configuration file, or NULL. */
  char *user_file;           /* The pathname of the user-specific */
                             /*  .teclarc configuration file, or NULL. */
  int configured;            /* True as soon as any teclarc configuration */
                             /*  file has been read. */
  int echo;                  /* True to display the line as it is being */
                             /*  entered. If 0, only the prompt will be */
                             /*  displayed, and the line will not be */
                             /*  archived in the history list. */
  int last_signal;           /* The last signal that was caught by */
                             /*  the last call to gl_get_line(), or -1 */
                             /*  if no signal has been caught yet. */
#ifdef HAVE_SELECT
  FreeList *fd_node_mem;     /* A freelist of GlFdNode structures */
  GlFdNode *fd_nodes;        /* The list of fd event descriptions */
  fd_set rfds;               /* The set of fds to watch for readability */
  fd_set wfds;               /* The set of fds to watch for writability */
  fd_set ufds;               /* The set of fds to watch for urgent data */
  int max_fd;                /* The maximum file-descriptor being watched */
  struct {                   /* Inactivity timeout related data */
    struct timeval dt;       /* The inactivity timeout when timer.fn() */
                             /*  isn't 0 */
    GlTimeoutFn *fn;         /* The application callback to call when */
                             /*  the inactivity timer expires, or 0 if */
                             /*  timeouts are not required. */
    void *data;              /* Application provided data to be passed to */
                             /*  timer.fn(). */
  } timer;
#endif
};

/*
 * Define the max amount of space needed to store a termcap terminal
 * description. Unfortunately this has to be done by guesswork, so
 * there is the potential for buffer overflows if we guess too small.
 * Fortunately termcap has been replaced by terminfo on most
 * platforms, and with terminfo this isn't an issue. The value that I
 * am using here is the conventional value, as recommended by certain
 * web references.
 */
#ifdef USE_TERMCAP
#define TERMCAP_BUF_SIZE 2048
#endif

/*
 * Set the size of the string segments used to store terminal capability
 * strings.
 */
#define CAPMEM_SEGMENT_SIZE 512

/*
 * If no terminal size information is available, substitute the
 * following vt100 default sizes.
 */
#define GL_DEF_NLINE 24
#define GL_DEF_NCOLUMN 80

/*
 * Enumerate the attributes needed to classify different types of
 * signals. These attributes reflect the standard default
 * characteristics of these signals (according to Richard Steven's
 * Advanced Programming in the UNIX Environment). Note that these values
 * are all powers of 2, so that they can be combined in a bitwise union.
 */
typedef enum {
  GLSA_TERM=1,   /* A signal that terminates processes */
  GLSA_SUSP=2,   /* A signal that suspends processes */
  GLSA_CONT=4,   /* A signal that is sent when suspended processes resume */
  GLSA_IGN=8,    /* A signal that is ignored */
  GLSA_CORE=16,  /* A signal that generates a core dump */
  GLSA_HARD=32,  /* A signal generated by a hardware exception */
  GLSA_SIZE=64   /* A signal indicating terminal size changes */
} GlSigAttr;

/*
 * List the signals that we need to catch. In general these are
 * those that by default terminate or suspend the process, since
 * in such cases we need to restore terminal settings.
 */
static const struct GlDefSignal {
  int signo;            /* The number of the signal */
  unsigned flags;       /* A bitwise union of GlSignalFlags enumerators */
  GlAfterSignal after;  /* What to do after the signal has been delivered */
  int attr;             /* The default attributes of this signal, expressed */
                        /* as a bitwise union of GlSigAttr enumerators */
  int errno_value;      /* What to set errno to */
} gl_signal_list[] = {
  {SIGABRT,   GLS_SUSPEND_INPUT,    GLS_ABORT, GLSA_TERM|GLSA_CORE, EINTR},
  {SIGALRM,   GLS_RESTORE_ENV,   GLS_CONTINUE, GLSA_TERM,           0},
  {SIGCONT,   GLS_RESTORE_ENV,   GLS_CONTINUE, GLSA_CONT|GLSA_IGN,  0},
#if defined(SIGHUP)
#ifdef ENOTTY
  {SIGHUP,    GLS_SUSPEND_INPUT,    GLS_ABORT, GLSA_TERM,           ENOTTY},
#else
  {SIGHUP,    GLS_SUSPEND_INPUT,    GLS_ABORT, GLSA_TERM,           EINTR},
#endif
#endif
  {SIGINT,    GLS_SUSPEND_INPUT,    GLS_ABORT, GLSA_TERM,           EINTR},
#if defined(SIGPIPE)
#ifdef EPIPE
  {SIGPIPE,   GLS_SUSPEND_INPUT,    GLS_ABORT, GLSA_TERM,           EPIPE},
#else
  {SIGPIPE,   GLS_SUSPEND_INPUT,    GLS_ABORT, GLSA_TERM,           EINTR},
#endif
#endif
#ifdef SIGPOLL
  {SIGPOLL,   GLS_SUSPEND_INPUT,    GLS_ABORT, GLSA_TERM,           EINTR},
#endif
#ifdef SIGPWR
  {SIGPWR,    GLS_RESTORE_ENV,   GLS_CONTINUE, GLSA_IGN,            0},
#endif
#ifdef SIGQUIT
  {SIGQUIT,   GLS_SUSPEND_INPUT,    GLS_ABORT, GLSA_TERM|GLSA_CORE, EINTR},
#endif
  {SIGTERM,   GLS_SUSPEND_INPUT,    GLS_ABORT, GLSA_TERM,           EINTR},
#ifdef SIGTSTP
  {SIGTSTP,   GLS_SUSPEND_INPUT, GLS_CONTINUE, GLSA_SUSP,           0},
#endif
#ifdef SIGTTIN
  {SIGTTIN,   GLS_SUSPEND_INPUT, GLS_CONTINUE, GLSA_SUSP,           0},
#endif
#ifdef SIGTTOU
  {SIGTTOU,   GLS_SUSPEND_INPUT, GLS_CONTINUE, GLSA_SUSP,           0},
#endif
#ifdef SIGUSR1
  {SIGUSR1,   GLS_RESTORE_ENV,   GLS_CONTINUE, GLSA_TERM,           0},
#endif
#ifdef SIGUSR2
  {SIGUSR2,   GLS_RESTORE_ENV,   GLS_CONTINUE, GLSA_TERM,           0},
#endif
#ifdef SIGVTALRM
  {SIGVTALRM, GLS_RESTORE_ENV,   GLS_CONTINUE, GLSA_TERM,           0},
#endif
#ifdef SIGWINCH
  {SIGWINCH,  GLS_RESTORE_ENV,   GLS_CONTINUE, GLSA_SIZE|GLSA_IGN,  0},
#endif
#ifdef SIGXCPU
  {SIGXCPU,   GLS_RESTORE_ENV,   GLS_CONTINUE, GLSA_TERM|GLSA_CORE, 0},
#endif
#ifdef SIGXFSZ
  {SIGXFSZ,   GLS_RESTORE_ENV,   GLS_CONTINUE, GLSA_TERM|GLSA_CORE, 0},
#endif
};

/*
 * Define file-scope variables for use in signal handlers.
 */
static volatile sig_atomic_t gl_pending_signal = -1;
static sigjmp_buf gl_setjmp_buffer;

static void gl_signal_handler(int signo);

static int gl_check_caught_signal(GetLine *gl);

/*
 * Respond to an externally caught process suspension or
 * termination signal.
 */
static void gl_suspend_process(int signo, GetLine *gl, int ngl);

/* Return the default attributes of a given signal */

static int gl_classify_signal(int signo);

/*
 * Unfortunately both terminfo and termcap require one to use the tputs()
 * function to output terminal control characters, and this function
 * doesn't allow one to specify a file stream. As a result, the following
 * file-scope variable is used to pass the current output file stream.
 * This is bad, but there doesn't seem to be any alternative.
 */
static GetLine *tputs_gl = NULL;

/*
 * Define a tab to be a string of 8 spaces.
 */
#define TAB_WIDTH 8

/*
 * Lookup the current size of the terminal.
 */
static void gl_query_size(GetLine *gl, int *ncolumn, int *nline);

/*
 * Getline calls this to temporarily override certain signal handlers
 * of the calling program.
 */
static int gl_override_signal_handlers(GetLine *gl);

/*
 * Getline calls this to restore the signal handlers of the calling
 * program.
 */
static int gl_restore_signal_handlers(GetLine *gl);

/*
 * Temporarily block the delivery of all signals that gl_get_line()
 * is currently configured to trap.
 */
static int gl_mask_signals(GetLine *gl, sigset_t *oldset);

/*
 * Restore the process signal mask that was overriden by a previous
 * call to gl_mask_signals().
 */
static int gl_unmask_signals(GetLine *gl, sigset_t *oldset);

/*
 * Unblock the signals that gl_get_line() has been configured to catch.
 */
static int gl_catch_signals(GetLine *gl);

/*
 * Return the set of all trappable signals.
 */
static void gl_list_trappable_signals(sigset_t *signals);

/*
 * Put the terminal into raw input mode, after saving the original
 * terminal attributes in gl->oldattr.
 */
static int gl_raw_terminal_mode(GetLine *gl);

/*
 * Restore the terminal attributes from gl->oldattr.
 */
static int gl_restore_terminal_attributes(GetLine *gl);

/*
 * Switch to non-blocking I/O if possible.
 */
static int gl_nonblocking_io(GetLine *gl, int fd);

/*
 * Switch to blocking I/O if possible.
 */
static int gl_blocking_io(GetLine *gl, int fd);

/*
 * Read a line from the user in raw mode.
 */
static int gl_get_input_line(GetLine *gl, const char *prompt,
			     const char *start_line, int start_pos);

/*
 * Query the user for a single character.
 */
static int gl_get_query_char(GetLine *gl, const char *prompt, int defchar);

/*
 * Read input from a non-interactive input stream.
 */
static int gl_read_stream_line(GetLine *gl);

/*
 * Read a single character from a non-interactive input stream.
 */
static int gl_read_stream_char(GetLine *gl);

/*
 * Prepare to edit a new line.
 */
static int gl_present_line(GetLine *gl, const char *prompt,
			   const char *start_line, int start_pos);

/*
 * Reset all line input parameters for a new input line.
 */
static void gl_reset_input_line(GetLine *gl);

/*
 * Handle the receipt of the potential start of a new key-sequence from
 * the user.
 */
static int gl_interpret_char(GetLine *gl, char c);

/*
 * Bind a single control or meta character to an action.
 */
static int gl_bind_control_char(GetLine *gl, KtBinder binder,
				char c, const char *action);

/*
 * Set up terminal-specific key bindings.
 */
static int gl_bind_terminal_keys(GetLine *gl);

/*
 * Lookup terminal control string and size information.
 */
static int gl_control_strings(GetLine *gl, const char *term);

/*
 * Wrappers around the terminfo and termcap functions that lookup
 * strings in the terminal information databases.
 */
#ifdef USE_TERMINFO
static const char *gl_tigetstr(GetLine *gl, const char *name);
#elif defined(USE_TERMCAP)
static const char *gl_tgetstr(GetLine *gl, const char *name, char **bufptr);
#endif

/*
 * Output a binary string directly to the terminal.
 */
static int gl_print_raw_string(GetLine *gl, int buffered,
			       const char *string, int n);

/*
 * Print an informational message, starting and finishing on new lines.
 * After the list of strings to be printed, the last argument MUST be
 * GL_END_INFO.
 */
static int gl_print_info(GetLine *gl, ...);
#define GL_END_INFO ((const char *)0)

/*
 * Start a newline and place the cursor at its start.
 */
static int gl_start_newline(GetLine *gl, int buffered);

/*
 * Output a terminal control sequence.
 */
static int gl_print_control_sequence(GetLine *gl, int nline,
				     const char *string);

/*
 * Output a character or string to the terminal after converting tabs
 * to spaces and control characters to a caret followed by the modified
 * character.
 */
static int gl_print_char(GetLine *gl, char c, char pad);
static int gl_print_string(GetLine *gl, const char *string, char pad);

/*
 * Delete nc characters starting from the one under the cursor.
 * Optionally copy the deleted characters to the cut buffer.
 */
static int gl_delete_chars(GetLine *gl, int nc, int cut);

/*
 * Add a character to the line buffer at the current cursor position,
 * inserting or overwriting according the current mode.
 */
static int gl_add_char_to_line(GetLine *gl, char c);

/*
 * Insert/append a string to the line buffer and terminal at the current
 * cursor position.
 */
static int gl_add_string_to_line(GetLine *gl, const char *s);

/*
 * Record a new character in the input-line buffer.
 */
static int gl_buffer_char(GetLine *gl, char c, int bufpos);

/*
 * Record a string in the input-line buffer.
 */
static int gl_buffer_string(GetLine *gl, const char *s, int n, int bufpos);

/*
 * Make way to insert a string in the input-line buffer.
 */
static int gl_make_gap_in_buffer(GetLine *gl, int start, int n);

/*
 * Remove characters from the input-line buffer, and move any characters
 * that followed them to the start of the vacated space.
 */
static void gl_remove_from_buffer(GetLine *gl, int start, int n);

/*
 * Terminate the input-line buffer after a specified number of characters.
 */
static int gl_truncate_buffer(GetLine *gl, int n);

/*
 * Delete the displayed part of the input line that follows the current
 * terminal cursor position.
 */
static int gl_truncate_display(GetLine *gl);

/*
 * Accomodate changes to the contents of the input line buffer
 * that weren't made by the above gl_*buffer functions.
 */
static void gl_update_buffer(GetLine *gl);

/*
 * Read a single character from the terminal.
 */
static int gl_read_terminal(GetLine *gl, int keep, char *c);

/*
 * Discard processed characters from the key-press lookahead buffer.
 */
static void gl_discard_chars(GetLine *gl, int nused);

/*
 * Move the terminal cursor n positions to the left or right.
 */
static int gl_terminal_move_cursor(GetLine *gl, int n);

/*
 * Move the terminal cursor to a given position.
 */
static int gl_set_term_curpos(GetLine *gl, int term_curpos);

/*
 * Set the position of the cursor both in the line input buffer and on the
 * terminal.
 */
static int gl_place_cursor(GetLine *gl, int buff_curpos);

/*
 * How many characters are needed to write a number as an octal string?
 */
static int gl_octal_width(unsigned num);

/*
 * Return the number of spaces needed to display a tab character at
 * a given location of the terminal.
 */
static int gl_displayed_tab_width(GetLine *gl, int term_curpos);

/*
 * Return the number of terminal characters needed to display a
 * given raw character.
 */
static int gl_displayed_char_width(GetLine *gl, char c, int term_curpos);

/*
 * Return the number of terminal characters needed to display a
 * given substring.
 */
static int gl_displayed_string_width(GetLine *gl, const char *string, int nc,
				     int term_curpos);

/*
 * Return non-zero if 'c' is to be considered part of a word.
 */
static int gl_is_word_char(int c);

/*
 * Read a tecla configuration file.
 */
static int _gl_read_config_file(GetLine *gl, const char *filename, KtBinder who);

/*
 * Read a tecla configuration string.
 */
static int _gl_read_config_string(GetLine *gl, const char *buffer, KtBinder who);

/*
 * Define the callback function used by _gl_parse_config_line() to
 * read the next character of a configuration stream.
 */
#define GLC_GETC_FN(fn) int (fn)(void *stream)
typedef GLC_GETC_FN(GlcGetcFn);

static GLC_GETC_FN(glc_file_getc);  /* Read from a file */
static GLC_GETC_FN(glc_buff_getc);  /* Read from a string */

/*
 * Parse a single configuration command line.
 */
static int _gl_parse_config_line(GetLine *gl, void *stream, GlcGetcFn *getc_fn,
				 const char *origin, KtBinder who, int *lineno);
static int gl_report_config_error(GetLine *gl, const char *origin, int lineno,
				  const char *errmsg);

/*
 * Bind the actual arrow key bindings to match those of the symbolic
 * arrow-key bindings.
 */
static int _gl_bind_arrow_keys(GetLine *gl);

/*
 * Copy the binding of the specified symbolic arrow-key binding to
 * the terminal specific, and default arrow-key key-sequences.
 */
static int _gl_rebind_arrow_key(GetLine *gl, const char *name,
				const char *term_seq,
				const char *def_seq1,
				const char *def_seq2);

/*
 * After the gl_read_from_file() action has been used to tell gl_get_line()
 * to temporarily read input from a file, gl_revert_input() arranges
 * for input to be reverted to the input stream last registered with
 * gl_change_terminal().
 */
static void gl_revert_input(GetLine *gl);

/*
 * Flush unwritten characters to the terminal.
 */
static int gl_flush_output(GetLine *gl);

/*
 * The callback through which all terminal output is routed.
 * This simply appends characters to a queue buffer, which is
 * subsequently flushed to the output channel by gl_flush_output().
 */
static GL_WRITE_FN(gl_write_fn);

/*
 * The callback function which the output character queue object
 * calls to transfer characters to the output channel.
 */
static GL_WRITE_FN(gl_flush_terminal);

/*
 * Enumerate the possible return statuses of gl_read_input().
 */
typedef enum {
  GL_READ_OK,      /* A character was read successfully */
  GL_READ_ERROR,   /* A read-error occurred */
  GL_READ_BLOCKED, /* The read would have blocked the caller */
  GL_READ_EOF      /* The end of the current input file was reached */
} GlReadStatus;

static GlReadStatus gl_read_input(GetLine *gl, char *c);
/*
 * Private functions of gl_read_input().
 */
static int gl_event_handler(GetLine *gl, int fd);
static int gl_read_unmasked(GetLine *gl, int fd, char *c);


/*
 * A private function of gl_tty_signals().
 */
static int gl_set_tty_signal(int signo, void (*handler)(int));

/*
 * Change the editor style being emulated.
 */
static int gl_change_editor(GetLine *gl, GlEditor editor);

/*
 * Searching in a given direction, return the index of a given (or
 * read) character in the input line, or the character that precedes
 * it in the specified search direction. Return -1 if not found.
 */
static int gl_find_char(GetLine *gl, int count, int forward, int onto, char c);

/*
 * Return the buffer index of the nth word ending after the cursor.
 */
static int gl_nth_word_end_forward(GetLine *gl, int n);

/*
 * Return the buffer index of the nth word start after the cursor.
 */
static int gl_nth_word_start_forward(GetLine *gl, int n);

/*
 * Return the buffer index of the nth word start before the cursor.
 */
static int gl_nth_word_start_backward(GetLine *gl, int n);

/*
 * When called when vi command mode is enabled, this function saves the
 * current line and cursor position for potential restoration later
 * by the vi undo command.
 */
static void gl_save_for_undo(GetLine *gl);

/*
 * If in vi mode, switch to vi command mode.
 */
static void gl_vi_command_mode(GetLine *gl);

/*
 * In vi mode this is used to delete up to or onto a given or read
 * character in the input line. Also switch to insert mode if requested
 * after the deletion.
 */
static int gl_delete_find(GetLine *gl, int count, char c, int forward,
			  int onto, int change);

/*
 * Copy the characters between the cursor and the count'th instance of
 * a specified (or read) character in the input line, into the cut buffer.
 */
static int gl_copy_find(GetLine *gl, int count, char c, int forward, int onto);

/*
 * Return the line index of the parenthesis that either matches the one under
 * the cursor, or not over a parenthesis character, the index of the next
 * close parenthesis. Return -1 if not found.
 */
static int gl_index_of_matching_paren(GetLine *gl);

/*
 * Replace a malloc'd string (or NULL), with another malloc'd copy of
 * a string (or NULL).
 */
static int gl_record_string(char **sptr, const char *string);

/*
 * Enumerate text display attributes as powers of two, suitable for
 * use in a bit-mask.
 */
typedef enum {
  GL_TXT_STANDOUT=1,   /* Display text highlighted */
  GL_TXT_UNDERLINE=2,  /* Display text underlined */
  GL_TXT_REVERSE=4,    /* Display text with reverse video */
  GL_TXT_BLINK=8,      /* Display blinking text */
  GL_TXT_DIM=16,       /* Display text in a dim font */
  GL_TXT_BOLD=32       /* Display text using a bold font */
} GlTextAttr;

/*
 * Display the prompt regardless of the current visibility mode.
 */
static int gl_display_prompt(GetLine *gl);

/*
 * Return the number of characters used by the prompt on the terminal.
 */
static int gl_displayed_prompt_width(GetLine *gl);

/*
 * Prepare to return the current input line to the caller of gl_get_line().
 */
static int gl_line_ended(GetLine *gl, int newline_char);

/*
 * Arrange for the input line to be redisplayed when the current contents
 * of the output queue have been flushed.
 */
static void gl_queue_redisplay(GetLine *gl);

/*
 * Erase the displayed representation of the input line, without
 * touching the buffered copy.
 */
static int gl_erase_line(GetLine *gl);

/*
 * This function is called whenever the input line has been erased.
 */
static void gl_line_erased(GetLine *gl);

/*
 * Arrange for the current input line to be discarded.
 */
void _gl_abandon_line(GetLine *gl);

/*
 * The following are private internally callable versions of pertinent
 * public functions. Unlike their public wrapper functions, they don't
 * block signals while running, and assume that their arguments are valid.
 * They are designed to be called from places where signals are already
 * blocked, and where simple sanity checks have already been applied to
 * their arguments.
 */
static char *_gl_get_line(GetLine *gl, const char *prompt,
			  const char *start_line, int start_pos);
static int _gl_query_char(GetLine *gl, const char *prompt, char defchar);
static int _gl_read_char(GetLine *gl);
static int _gl_update_size(GetLine *gl);
/*
 * Redraw the current input line to account for a change in the terminal
 * size. Also install the new size in gl.
 */
static int gl_handle_tty_resize(GetLine *gl, int ncolumn, int nline);

static int _gl_change_terminal(GetLine *gl, FILE *input_fp, FILE *output_fp,
			       const char *term);
static int _gl_configure_getline(GetLine *gl, const char *app_string,
				 const char *app_file, const char *user_file);
static int _gl_save_history(GetLine *gl, const char *filename,
			    const char *comment, int max_lines);
static int _gl_load_history(GetLine *gl, const char *filename,
			    const char *comment);
static int _gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,
			GlFdEventFn *callback, void *data);
static void _gl_terminal_size(GetLine *gl, int def_ncolumn, int def_nline,
			      GlTerminalSize *size);
static void _gl_replace_prompt(GetLine *gl, const char *prompt);
static int _gl_trap_signal(GetLine *gl, int signo, unsigned flags,
			   GlAfterSignal after, int errno_value);
static int _gl_raw_io(GetLine *gl, int redisplay);
static int _gl_normal_io(GetLine *gl);
static int _gl_completion_action(GetLine *gl, void *data, CplMatchFn *match_fn,
				 int list_only, const char *name,
				 const char *keyseq);
static int _gl_register_action(GetLine *gl, void *data, GlActionFn *fn,
			       const char *name, const char *keyseq);
static int _gl_io_mode(GetLine *gl, GlIOMode mode);
static int _gl_set_term_size(GetLine *gl, int ncolumn, int nline);
static int _gl_append_history(GetLine *gl, const char *line);

/*
 * Reset the completion status and associated errno value in
 * gl->rtn_status and gl->rtn_errno.
 */
static void gl_clear_status(GetLine *gl);

/*
 * Record a completion status, unless a previous abnormal completion
 * status has already been recorded for the current call.
 */
static void gl_record_status(GetLine *gl, GlReturnStatus rtn_status,
			     int rtn_errno);

/*
 * Set the maximum length of a line in a user's tecla configuration
 * file (not counting comments).
 */
#define GL_CONF_BUFLEN 100

/*
 * Set the maximum number of arguments supported by individual commands
 * in tecla configuration files.
 */
#define GL_CONF_MAXARG 10

/*
 * Prototype the available action functions.
 */
static KT_KEY_FN(gl_user_interrupt);
static KT_KEY_FN(gl_abort);
static KT_KEY_FN(gl_suspend);
static KT_KEY_FN(gl_stop_output);
static KT_KEY_FN(gl_start_output);
static KT_KEY_FN(gl_literal_next);
static KT_KEY_FN(gl_cursor_left);
static KT_KEY_FN(gl_cursor_right);
static KT_KEY_FN(gl_insert_mode);
static KT_KEY_FN(gl_beginning_of_line);
static KT_KEY_FN(gl_end_of_line);
static KT_KEY_FN(gl_delete_line);
static KT_KEY_FN(gl_kill_line);
static KT_KEY_FN(gl_forward_word);
static KT_KEY_FN(gl_backward_word);
static KT_KEY_FN(gl_forward_delete_char);
static KT_KEY_FN(gl_backward_delete_char);
static KT_KEY_FN(gl_forward_delete_word);
static KT_KEY_FN(gl_backward_delete_word);
static KT_KEY_FN(gl_delete_refind);
static KT_KEY_FN(gl_delete_invert_refind);
static KT_KEY_FN(gl_delete_to_column);
static KT_KEY_FN(gl_delete_to_parenthesis);
static KT_KEY_FN(gl_forward_delete_find);
static KT_KEY_FN(gl_backward_delete_find);
static KT_KEY_FN(gl_forward_delete_to);
static KT_KEY_FN(gl_backward_delete_to);
static KT_KEY_FN(gl_upcase_word);
static KT_KEY_FN(gl_downcase_word);
static KT_KEY_FN(gl_capitalize_word);
static KT_KEY_FN(gl_redisplay);
static KT_KEY_FN(gl_clear_screen);
static KT_KEY_FN(gl_transpose_chars);
static KT_KEY_FN(gl_set_mark);
static KT_KEY_FN(gl_exchange_point_and_mark);
static KT_KEY_FN(gl_kill_region);
static KT_KEY_FN(gl_copy_region_as_kill);
static KT_KEY_FN(gl_yank);
static KT_KEY_FN(gl_up_history);
static KT_KEY_FN(gl_down_history);
static KT_KEY_FN(gl_history_search_backward);
static KT_KEY_FN(gl_history_re_search_backward);
static KT_KEY_FN(gl_history_search_forward);
static KT_KEY_FN(gl_history_re_search_forward);
static KT_KEY_FN(gl_complete_word);
#ifndef HIDE_FILE_SYSTEM
static KT_KEY_FN(gl_expand_filename);
static KT_KEY_FN(gl_read_from_file);
static KT_KEY_FN(gl_read_init_files);
static KT_KEY_FN(gl_list_glob);
#endif
static KT_KEY_FN(gl_del_char_or_list_or_eof);
static KT_KEY_FN(gl_list_or_eof);
static KT_KEY_FN(gl_beginning_of_history);
static KT_KEY_FN(gl_end_of_history);
static KT_KEY_FN(gl_digit_argument);
static KT_KEY_FN(gl_newline);
static KT_KEY_FN(gl_repeat_history);
static KT_KEY_FN(gl_vi_insert);
static KT_KEY_FN(gl_vi_overwrite);
static KT_KEY_FN(gl_change_case);
static KT_KEY_FN(gl_vi_insert_at_bol);
static KT_KEY_FN(gl_vi_append_at_eol);
static KT_KEY_FN(gl_vi_append);
static KT_KEY_FN(gl_backward_kill_line);
static KT_KEY_FN(gl_goto_column);
static KT_KEY_FN(gl_forward_to_word);
static KT_KEY_FN(gl_vi_replace_char);
static KT_KEY_FN(gl_vi_change_rest_of_line);
static KT_KEY_FN(gl_vi_change_line);
static KT_KEY_FN(gl_vi_change_to_bol);
static KT_KEY_FN(gl_vi_change_refind);
static KT_KEY_FN(gl_vi_change_invert_refind);
static KT_KEY_FN(gl_vi_change_to_column);
static KT_KEY_FN(gl_vi_change_to_parenthesis);
static KT_KEY_FN(gl_vi_forward_change_word);
static KT_KEY_FN(gl_vi_backward_change_word);
static KT_KEY_FN(gl_vi_forward_change_find);
static KT_KEY_FN(gl_vi_backward_change_find);
static KT_KEY_FN(gl_vi_forward_change_to);
static KT_KEY_FN(gl_vi_backward_change_to);
static KT_KEY_FN(gl_vi_forward_change_char);
static KT_KEY_FN(gl_vi_backward_change_char);
static KT_KEY_FN(gl_forward_copy_char);
static KT_KEY_FN(gl_backward_copy_char);
static KT_KEY_FN(gl_forward_find_char);
static KT_KEY_FN(gl_backward_find_char);
static KT_KEY_FN(gl_forward_to_char);
static KT_KEY_FN(gl_backward_to_char);
static KT_KEY_FN(gl_repeat_find_char);
static KT_KEY_FN(gl_invert_refind_char);
static KT_KEY_FN(gl_append_yank);
static KT_KEY_FN(gl_backward_copy_word);
static KT_KEY_FN(gl_forward_copy_word);
static KT_KEY_FN(gl_copy_to_bol);
static KT_KEY_FN(gl_copy_refind);
static KT_KEY_FN(gl_copy_invert_refind);
static KT_KEY_FN(gl_copy_to_column);
static KT_KEY_FN(gl_copy_to_parenthesis);
static KT_KEY_FN(gl_copy_rest_of_line);
static KT_KEY_FN(gl_copy_line);
static KT_KEY_FN(gl_backward_copy_find);
static KT_KEY_FN(gl_forward_copy_find);
static KT_KEY_FN(gl_backward_copy_to);
static KT_KEY_FN(gl_forward_copy_to);
static KT_KEY_FN(gl_vi_undo);
static KT_KEY_FN(gl_emacs_editing_mode);
static KT_KEY_FN(gl_vi_editing_mode);
static KT_KEY_FN(gl_ring_bell);
static KT_KEY_FN(gl_vi_repeat_change);
static KT_KEY_FN(gl_find_parenthesis);
static KT_KEY_FN(gl_list_history);
static KT_KEY_FN(gl_list_completions);
static KT_KEY_FN(gl_run_external_action);

/*
 * Name the available action functions.
 */
static const struct {const char *name; KT_KEY_FN(*fn);} gl_actions[] = {
  {"user-interrupt",             gl_user_interrupt},
  {"abort",                      gl_abort},
  {"suspend",                    gl_suspend},
  {"stop-output",                gl_stop_output},
  {"start-output",               gl_start_output},
  {"literal-next",               gl_literal_next},
  {"cursor-right",               gl_cursor_right},
  {"cursor-left",                gl_cursor_left},
  {"insert-mode",                gl_insert_mode},
  {"beginning-of-line",          gl_beginning_of_line},
  {"end-of-line",                gl_end_of_line},
  {"delete-line",                gl_delete_line},
  {"kill-line",                  gl_kill_line},
  {"forward-word",               gl_forward_word},
  {"backward-word",              gl_backward_word},
  {"forward-delete-char",        gl_forward_delete_char},
  {"backward-delete-char",       gl_backward_delete_char},
  {"forward-delete-word",        gl_forward_delete_word},
  {"backward-delete-word",       gl_backward_delete_word},
  {"delete-refind",              gl_delete_refind},
  {"delete-invert-refind",       gl_delete_invert_refind},
  {"delete-to-column",           gl_delete_to_column},
  {"delete-to-parenthesis",      gl_delete_to_parenthesis},
  {"forward-delete-find",        gl_forward_delete_find},
  {"backward-delete-find",       gl_backward_delete_find},
  {"forward-delete-to",          gl_forward_delete_to},
  {"backward-delete-to",         gl_backward_delete_to},
  {"upcase-word",                gl_upcase_word},
  {"downcase-word",              gl_downcase_word},
  {"capitalize-word",            gl_capitalize_word},
  {"redisplay",                  gl_redisplay},
  {"clear-screen",               gl_clear_screen},
  {"transpose-chars",            gl_transpose_chars},
  {"set-mark",                   gl_set_mark},
  {"exchange-point-and-mark",    gl_exchange_point_and_mark},
  {"kill-region",                gl_kill_region},
  {"copy-region-as-kill",        gl_copy_region_as_kill},
  {"yank",                       gl_yank},
  {"up-history",                 gl_up_history},
  {"down-history",               gl_down_history},
  {"history-search-backward",    gl_history_search_backward},
  {"history-re-search-backward", gl_history_re_search_backward},
  {"history-search-forward",     gl_history_search_forward},
  {"history-re-search-forward",  gl_history_re_search_forward},
  {"complete-word",              gl_complete_word},
#ifndef HIDE_FILE_SYSTEM
  {"expand-filename",            gl_expand_filename},
  {"read-from-file",             gl_read_from_file},
  {"read-init-files",            gl_read_init_files},
  {"list-glob",                  gl_list_glob},
#endif
  {"del-char-or-list-or-eof",    gl_del_char_or_list_or_eof},
  {"beginning-of-history",       gl_beginning_of_history},
  {"end-of-history",             gl_end_of_history},
  {"digit-argument",             gl_digit_argument},
  {"newline",                    gl_newline},
  {"repeat-history",             gl_repeat_history},
  {"vi-insert",                  gl_vi_insert},
  {"vi-overwrite",               gl_vi_overwrite},
  {"vi-insert-at-bol",           gl_vi_insert_at_bol},
  {"vi-append-at-eol",           gl_vi_append_at_eol},
  {"vi-append",                  gl_vi_append},
  {"change-case",                gl_change_case},
  {"backward-kill-line",         gl_backward_kill_line},
  {"goto-column",                gl_goto_column},
  {"forward-to-word",            gl_forward_to_word},
  {"vi-replace-char",            gl_vi_replace_char},
  {"vi-change-rest-of-line",     gl_vi_change_rest_of_line},
  {"vi-change-line",             gl_vi_change_line},
  {"vi-change-to-bol",           gl_vi_change_to_bol},
  {"vi-change-refind",           gl_vi_change_refind},
  {"vi-change-invert-refind",    gl_vi_change_invert_refind},
  {"vi-change-to-column",        gl_vi_change_to_column},
  {"vi-change-to-parenthesis",   gl_vi_change_to_parenthesis},
  {"forward-copy-char",          gl_forward_copy_char},
  {"backward-copy-char",         gl_backward_copy_char},
  {"forward-find-char",          gl_forward_find_char},
  {"backward-find-char",         gl_backward_find_char},
  {"forward-to-char",            gl_forward_to_char},
  {"backward-to-char",           gl_backward_to_char},
  {"repeat-find-char",           gl_repeat_find_char},
  {"invert-refind-char",         gl_invert_refind_char},
  {"append-yank",                gl_append_yank},
  {"backward-copy-word",         gl_backward_copy_word},
  {"forward-copy-word",          gl_forward_copy_word},
  {"copy-to-bol",                gl_copy_to_bol},
  {"copy-refind",                gl_copy_refind},
  {"copy-invert-refind",         gl_copy_invert_refind},
  {"copy-to-column",             gl_copy_to_column},
  {"copy-to-parenthesis",        gl_copy_to_parenthesis},
  {"copy-rest-of-line",          gl_copy_rest_of_line},
  {"copy-line",                  gl_copy_line},
  {"backward-copy-find",         gl_backward_copy_find},
  {"forward-copy-find",          gl_forward_copy_find},
  {"backward-copy-to",           gl_backward_copy_to},
  {"forward-copy-to",            gl_forward_copy_to},
  {"list-or-eof",                gl_list_or_eof},
  {"vi-undo",                    gl_vi_undo},
  {"vi-backward-change-word",    gl_vi_backward_change_word},
  {"vi-forward-change-word",     gl_vi_forward_change_word},
  {"vi-backward-change-find",    gl_vi_backward_change_find},
  {"vi-forward-change-find",     gl_vi_forward_change_find},
  {"vi-backward-change-to",      gl_vi_backward_change_to},
  {"vi-forward-change-to",       gl_vi_forward_change_to},
  {"vi-backward-change-char",    gl_vi_backward_change_char},
  {"vi-forward-change-char",     gl_vi_forward_change_char},
  {"emacs-mode",                 gl_emacs_editing_mode},
  {"vi-mode",                    gl_vi_editing_mode},
  {"ring-bell",                  gl_ring_bell},
  {"vi-repeat-change",           gl_vi_repeat_change},
  {"find-parenthesis",           gl_find_parenthesis},
  {"list-history",               gl_list_history},
};

/*
 * Define the default key-bindings in emacs mode.
 */
static const KtKeyBinding gl_emacs_bindings[] = {
  {"right",        "cursor-right"},
  {"^F",           "cursor-right"},
  {"left",         "cursor-left"},
  {"^B",           "cursor-left"},
  {"M-i",          "insert-mode"},
  {"M-I",          "insert-mode"},
  {"^A",           "beginning-of-line"},
  {"^E",           "end-of-line"},
  {"^U",           "delete-line"},
  {"^K",           "kill-line"},
  {"M-f",          "forward-word"},
  {"M-F",          "forward-word"},
  {"M-b",          "backward-word"},
  {"M-B",          "backward-word"},
  {"^D",           "del-char-or-list-or-eof"},
  {"^H",           "backward-delete-char"},
  {"^?",           "backward-delete-char"},
  {"M-d",          "forward-delete-word"},
  {"M-D",          "forward-delete-word"},
  {"M-^H",         "backward-delete-word"},
  {"M-^?",         "backward-delete-word"},
  {"M-u",          "upcase-word"},
  {"M-U",          "upcase-word"},
  {"M-l",          "downcase-word"},
  {"M-L",          "downcase-word"},
  {"M-c",          "capitalize-word"},
  {"M-C",          "capitalize-word"},
  {"^R",           "redisplay"},
  {"^L",           "clear-screen"},
  {"^T",           "transpose-chars"},
  {"^@",           "set-mark"},
  {"^X^X",         "exchange-point-and-mark"},
  {"^W",           "kill-region"},
  {"M-w",          "copy-region-as-kill"},
  {"M-W",          "copy-region-as-kill"},
  {"^Y",           "yank"},
  {"^P",           "up-history"},
  {"up",           "up-history"},
  {"^N",           "down-history"},
  {"down",         "down-history"},
  {"M-p",          "history-search-backward"},
  {"M-P",          "history-search-backward"},
  {"M-n",          "history-search-forward"},
  {"M-N",          "history-search-forward"},
  {"\t",           "complete-word"},
#ifndef HIDE_FILE_SYSTEM
  {"^X*",          "expand-filename"},
  {"^X^F",         "read-from-file"},
  {"^X^R",         "read-init-files"},
  {"^Xg",          "list-glob"},
  {"^XG",          "list-glob"},
#endif
  {"^Xh",          "list-history"},
  {"^XH",          "list-history"},
  {"M-<",          "beginning-of-history"},
  {"M->",          "end-of-history"},
  {"M-0",          "digit-argument"},
  {"M-1",          "digit-argument"},
  {"M-2",          "digit-argument"},
  {"M-3",          "digit-argument"},
  {"M-4",          "digit-argument"},
  {"M-5",          "digit-argument"},
  {"M-6",          "digit-argument"},
  {"M-7",          "digit-argument"},
  {"M-8",          "digit-argument"},
  {"M-9",          "digit-argument"},
  {"\r",           "newline"},
  {"\n",           "newline"},
  {"M-o",          "repeat-history"},
  {"M-C-v",        "vi-mode"},
};

/*
 * Define the default key-bindings in vi mode. Note that in vi-mode
 * meta-key bindings are command-mode bindings. For example M-i first
 * switches to command mode if not already in that mode, then moves
 * the cursor one position right, as in vi.
 */
static const KtKeyBinding gl_vi_bindings[] = {
  {"^D",           "list-or-eof"},
#ifndef HIDE_FILE_SYSTEM
  {"^G",           "list-glob"},
#endif
  {"^H",           "backward-delete-char"},
  {"\t",           "complete-word"},
  {"\r",           "newline"},
  {"\n",           "newline"},
  {"^L",           "clear-screen"},
  {"^N",           "down-history"},
  {"^P",           "up-history"},
  {"^R",           "redisplay"},
  {"^U",           "backward-kill-line"},
  {"^W",           "backward-delete-word"},
#ifndef HIDE_FILE_SYSTEM
  {"^X^F",         "read-from-file"},
  {"^X^R",         "read-init-files"},
  {"^X*",          "expand-filename"},
#endif
  {"^?",           "backward-delete-char"},
  {"M- ",          "cursor-right"},
  {"M-$",          "end-of-line"},
#ifndef HIDE_FILE_SYSTEM
  {"M-*",          "expand-filename"},
#endif
  {"M-+",          "down-history"},
  {"M--",          "up-history"},
  {"M-<",          "beginning-of-history"},
  {"M->",          "end-of-history"},
  {"M-^",          "beginning-of-line"},
  {"M-;",          "repeat-find-char"},
  {"M-,",          "invert-refind-char"},
  {"M-|",          "goto-column"},
  {"M-~",          "change-case"},
  {"M-.",          "vi-repeat-change"},
  {"M-%",          "find-parenthesis"},
  {"M-0",          "digit-argument"},
  {"M-1",          "digit-argument"},
  {"M-2",          "digit-argument"},
  {"M-3",          "digit-argument"},
  {"M-4",          "digit-argument"},
  {"M-5",          "digit-argument"},
  {"M-6",          "digit-argument"},
  {"M-7",          "digit-argument"},
  {"M-8",          "digit-argument"},
  {"M-9",          "digit-argument"},
  {"M-a",          "vi-append"},
  {"M-A",          "vi-append-at-eol"},
  {"M-b",          "backward-word"},
  {"M-B",          "backward-word"},
  {"M-C",          "vi-change-rest-of-line"},
  {"M-cb",         "vi-backward-change-word"},
  {"M-cB",         "vi-backward-change-word"},
  {"M-cc",         "vi-change-line"},
  {"M-ce",         "vi-forward-change-word"},
  {"M-cE",         "vi-forward-change-word"},
  {"M-cw",         "vi-forward-change-word"},
  {"M-cW",         "vi-forward-change-word"},
  {"M-cF",         "vi-backward-change-find"},
  {"M-cf",         "vi-forward-change-find"},
  {"M-cT",         "vi-backward-change-to"},
  {"M-ct",         "vi-forward-change-to"},
  {"M-c;",         "vi-change-refind"},
  {"M-c,",         "vi-change-invert-refind"},
  {"M-ch",         "vi-backward-change-char"},
  {"M-c^H",        "vi-backward-change-char"},
  {"M-c^?",        "vi-backward-change-char"},
  {"M-cl",         "vi-forward-change-char"},
  {"M-c ",         "vi-forward-change-char"},
  {"M-c^",         "vi-change-to-bol"},
  {"M-c0",         "vi-change-to-bol"},
  {"M-c$",         "vi-change-rest-of-line"},
  {"M-c|",         "vi-change-to-column"},
  {"M-c%",         "vi-change-to-parenthesis"},
  {"M-dh",         "backward-delete-char"},
  {"M-d^H",        "backward-delete-char"},
  {"M-d^?",        "backward-delete-char"},
  {"M-dl",         "forward-delete-char"},
  {"M-d ",         "forward-delete-char"},
  {"M-dd",         "delete-line"},
  {"M-db",         "backward-delete-word"},
  {"M-dB",         "backward-delete-word"},
  {"M-de",         "forward-delete-word"},
  {"M-dE",         "forward-delete-word"},
  {"M-dw",         "forward-delete-word"},
  {"M-dW",         "forward-delete-word"},
  {"M-dF",         "backward-delete-find"},
  {"M-df",         "forward-delete-find"},
  {"M-dT",         "backward-delete-to"},
  {"M-dt",         "forward-delete-to"},
  {"M-d;",         "delete-refind"},
  {"M-d,",         "delete-invert-refind"},
  {"M-d^",         "backward-kill-line"},
  {"M-d0",         "backward-kill-line"},
  {"M-d$",         "kill-line"},
  {"M-D",          "kill-line"},
  {"M-d|",         "delete-to-column"},
  {"M-d%",         "delete-to-parenthesis"},
  {"M-e",          "forward-word"},
  {"M-E",          "forward-word"},
  {"M-f",          "forward-find-char"},
  {"M-F",          "backward-find-char"},
  {"M--",          "up-history"},
  {"M-h",          "cursor-left"},
  {"M-H",          "beginning-of-history"},
  {"M-i",          "vi-insert"},
  {"M-I",          "vi-insert-at-bol"},
  {"M-j",          "down-history"},
  {"M-J",          "history-search-forward"},
  {"M-k",          "up-history"},
  {"M-K",          "history-search-backward"},
  {"M-l",          "cursor-right"},
  {"M-L",          "end-of-history"},
  {"M-n",          "history-re-search-forward"},
  {"M-N",          "history-re-search-backward"},
  {"M-p",          "append-yank"},
  {"M-P",          "yank"},
  {"M-r",          "vi-replace-char"},
  {"M-R",          "vi-overwrite"},
  {"M-s",          "vi-forward-change-char"},
  {"M-S",          "vi-change-line"},
  {"M-t",          "forward-to-char"},
  {"M-T",          "backward-to-char"},
  {"M-u",          "vi-undo"},
  {"M-w",          "forward-to-word"},
  {"M-W",          "forward-to-word"},
  {"M-x",          "forward-delete-char"},
  {"M-X",          "backward-delete-char"},
  {"M-yh",         "backward-copy-char"},
  {"M-y^H",        "backward-copy-char"},
  {"M-y^?",        "backward-copy-char"},
  {"M-yl",         "forward-copy-char"},
  {"M-y ",         "forward-copy-char"},
  {"M-ye",         "forward-copy-word"},
  {"M-yE",         "forward-copy-word"},
  {"M-yw",         "forward-copy-word"},
  {"M-yW",         "forward-copy-word"},
  {"M-yb",         "backward-copy-word"},
  {"M-yB",         "backward-copy-word"},
  {"M-yf",         "forward-copy-find"},
  {"M-yF",         "backward-copy-find"},
  {"M-yt",         "forward-copy-to"},
  {"M-yT",         "backward-copy-to"},
  {"M-y;",         "copy-refind"},
  {"M-y,",         "copy-invert-refind"},
  {"M-y^",         "copy-to-bol"},
  {"M-y0",         "copy-to-bol"},
  {"M-y$",         "copy-rest-of-line"},
  {"M-yy",         "copy-line"},
  {"M-Y",          "copy-line"},
  {"M-y|",         "copy-to-column"},
  {"M-y%",         "copy-to-parenthesis"},
  {"M-^E",         "emacs-mode"},
  {"M-^H",         "cursor-left"},
  {"M-^?",         "cursor-left"},
  {"M-^L",         "clear-screen"},
  {"M-^N",         "down-history"},
  {"M-^P",         "up-history"},
  {"M-^R",         "redisplay"},
  {"M-^D",         "list-or-eof"},
  {"M-\r",         "newline"},
  {"M-\t",         "complete-word"},
  {"M-\n",         "newline"},
#ifndef HIDE_FILE_SYSTEM
  {"M-^X^R",       "read-init-files"},
#endif
  {"M-^Xh",        "list-history"},
  {"M-^XH",        "list-history"},
  {"down",         "down-history"},
  {"up",           "up-history"},
  {"left",         "cursor-left"},
  {"right",        "cursor-right"},
};

/*.......................................................................
 * Create a new GetLine object.
 *
 * Input:
 *  linelen  size_t    The maximum line length to allow for.
 *  histlen  size_t    The number of bytes to allocate for recording
 *                     a circular buffer of history lines.
 * Output:
 *  return  GetLine *  The new object, or NULL on error.
 */
GetLine *new_GetLine(size_t linelen, size_t histlen)
{
  GetLine *gl;  /* The object to be returned */
  int i;
/*
 * Check the arguments.
 */
  if(linelen < 10) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Allocate the container.
 */
  gl = (GetLine *) malloc(sizeof(GetLine));
  if(!gl) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_GetLine().
 */
  gl->err = NULL;
  gl->glh = NULL;
  gl->cpl = NULL;
#ifndef HIDE_FILE_SYSTEM
  gl->cplfn.fn = cpl_file_completions;
#else
  gl->cplfn.fn = gl_no_completions;
#endif
  gl->cplfn.data = NULL;
#ifndef WITHOUT_FILE_SYSTEM
  gl->ef = NULL;
#endif
  gl->capmem = NULL;
  gl->cq = NULL;
  gl->input_fd = -1;
  gl->output_fd = -1;
  gl->input_fp = NULL;
  gl->output_fp = NULL;
  gl->file_fp = NULL;
  gl->term = NULL;
  gl->is_term = 0;
  gl->flush_fn = gl_flush_terminal;
  gl->io_mode = GL_NORMAL_MODE;
  gl->raw_mode = 0;
  gl->pending_io = GLP_WRITE;  /* We will start by writing the prompt */
  gl_clear_status(gl);
  gl->linelen = linelen;
  gl->line = NULL;
  gl->cutbuf = NULL;
  gl->prompt = NULL;
  gl->prompt_len = 0;
  gl->prompt_changed = 0;
  gl->prompt_style = GL_LITERAL_PROMPT;
  gl->cpl_mem = NULL;
  gl->ext_act_mem = NULL;
  gl->sig_mem = NULL;
  gl->sigs = NULL;
  gl->signals_masked = 0;
  gl->signals_overriden = 0;
  sigemptyset(&gl->all_signal_set);
  sigemptyset(&gl->old_signal_set);
  sigemptyset(&gl->use_signal_set);
  gl->bindings = NULL;
  gl->ntotal = 0;
  gl->buff_curpos = 0;
  gl->term_curpos = 0;
  gl->term_len = 0;
  gl->buff_mark = 0;
  gl->insert_curpos = 0;
  gl->insert = 1;
  gl->number = -1;
  gl->endline = 1;
  gl->displayed = 0;
  gl->redisplay = 0;
  gl->postpone = 0;
  gl->keybuf[0]='\0';
  gl->nbuf = 0;
  gl->nread = 0;
  gl->current_action.fn = 0;
  gl->current_action.data = NULL;
  gl->current_count = 0;
  gl->preload_id = 0;
  gl->preload_history = 0;
  gl->keyseq_count = 0;
  gl->last_search = -1;
  gl->editor = GL_EMACS_MODE;
  gl->silence_bell = 0;
  gl->automatic_history = 1;
  gl->vi.undo.line = NULL;
  gl->vi.undo.buff_curpos = 0;
  gl->vi.undo.ntotal = 0;
  gl->vi.undo.saved = 0;
  gl->vi.repeat.action.fn = 0;
  gl->vi.repeat.action.data = 0;
  gl->vi.repeat.count = 0;
  gl->vi.repeat.input_curpos = 0;
  gl->vi.repeat.command_curpos = 0;
  gl->vi.repeat.input_char = '\0';
  gl->vi.repeat.saved = 0;
  gl->vi.repeat.active = 0;
  gl->vi.command = 0;
  gl->vi.find_forward = 0;
  gl->vi.find_onto = 0;
  gl->vi.find_char = '\0';
  gl->left = NULL;
  gl->right = NULL;
  gl->up = NULL;
  gl->down = NULL;
  gl->home = NULL;
  gl->bol = 0;
  gl->clear_eol = NULL;
  gl->clear_eod = NULL;
  gl->u_arrow = NULL;
  gl->d_arrow = NULL;
  gl->l_arrow = NULL;
  gl->r_arrow = NULL;
  gl->sound_bell = NULL;
  gl->bold = NULL;
  gl->underline = NULL;
  gl->standout = NULL;
  gl->dim = NULL;
  gl->reverse = NULL;
  gl->blink = NULL;
  gl->text_attr_off = NULL;
  gl->nline = 0;
  gl->ncolumn = 0;
#ifdef USE_TERMINFO
  gl->left_n = NULL;
  gl->right_n = NULL;
#elif defined(USE_TERMCAP)
  gl->tgetent_buf = NULL;
  gl->tgetstr_buf = NULL;
#endif
  gl->app_file = NULL;
  gl->user_file = NULL;
  gl->configured = 0;
  gl->echo = 1;
  gl->last_signal = -1;
#ifdef HAVE_SELECT
  gl->fd_node_mem = NULL;
  gl->fd_nodes = NULL;
  FD_ZERO(&gl->rfds);
  FD_ZERO(&gl->wfds);
  FD_ZERO(&gl->ufds);
  gl->max_fd = 0;
  gl->timer.dt.tv_sec = 0;
  gl->timer.dt.tv_usec = 0;
  gl->timer.fn = 0;
  gl->timer.data = NULL;
#endif
/*
 * Allocate an error reporting buffer.
 */
  gl->err = _new_ErrMsg();
  if(!gl->err)
    return del_GetLine(gl);
/*
 * Allocate the history buffer.
 */
  gl->glh = _new_GlHistory(histlen);
  if(!gl->glh)
    return del_GetLine(gl);
/*
 * Allocate the resource object for file-completion.
 */
  gl->cpl = new_WordCompletion();
  if(!gl->cpl)
    return del_GetLine(gl);
/*
 * Allocate the resource object for file-completion.
 */
#ifndef WITHOUT_FILE_SYSTEM
  gl->ef = new_ExpandFile();
  if(!gl->ef)
    return del_GetLine(gl);
#endif
/*
 * Allocate a string-segment memory allocator for use in storing terminal
 * capablity strings.
 */
  gl->capmem = _new_StringGroup(CAPMEM_SEGMENT_SIZE);
  if(!gl->capmem)
    return del_GetLine(gl);
/*
 * Allocate the character queue that is used to buffer terminal output.
 */
  gl->cq = _new_GlCharQueue();
  if(!gl->cq)
    return del_GetLine(gl);
/*
 * Allocate a line buffer, leaving 2 extra characters for the terminating
 * '\n' and '\0' characters
 */
  gl->line = (char *) malloc(linelen + 2);
  if(!gl->line) {
    errno = ENOMEM;
    return del_GetLine(gl);
  };
/*
 * Start with an empty input line.
 */
  gl_truncate_buffer(gl, 0);
/*
 * Allocate a cut buffer.
 */
  gl->cutbuf = (char *) malloc(linelen + 2);
  if(!gl->cutbuf) {
    errno = ENOMEM;
    return del_GetLine(gl);
  };
  gl->cutbuf[0] = '\0';
/*
 * Allocate an initial empty prompt.
 */
  _gl_replace_prompt(gl, NULL);
  if(!gl->prompt) {
    errno = ENOMEM;
    return del_GetLine(gl);
  };
/*
 * Allocate a vi undo buffer.
 */
  gl->vi.undo.line = (char *) malloc(linelen + 2);
  if(!gl->vi.undo.line) {
    errno = ENOMEM;
    return del_GetLine(gl);
  };
  gl->vi.undo.line[0] = '\0';
/*
 * Allocate a freelist from which to allocate nodes for the list
 * of completion functions.
 */
  gl->cpl_mem = _new_FreeList(sizeof(GlCplCallback), GL_CPL_FREELIST_BLOCKING);
  if(!gl->cpl_mem)
    return del_GetLine(gl);
/*
 * Allocate a freelist from which to allocate nodes for the list
 * of external action functions.
 */
  gl->ext_act_mem = _new_FreeList(sizeof(GlExternalAction),
				  GL_EXT_ACT_FREELIST_BLOCKING);
  if(!gl->ext_act_mem)
    return del_GetLine(gl);
/*
 * Allocate a freelist from which to allocate nodes for the list
 * of signals.
 */
  gl->sig_mem = _new_FreeList(sizeof(GlSignalNode), GLS_FREELIST_BLOCKING);
  if(!gl->sig_mem)
    return del_GetLine(gl);
/*
 * Install initial dispositions for the default list of signals that
 * gl_get_line() traps.
 */
  for(i=0; i<sizeof(gl_signal_list)/sizeof(gl_signal_list[0]); i++) {
    const struct GlDefSignal *sig = gl_signal_list + i;
    if(_gl_trap_signal(gl, sig->signo, sig->flags, sig->after,
		       sig->errno_value))
      return del_GetLine(gl);
  };
/*
 * Allocate an empty table of key bindings.
 */
  gl->bindings = _new_KeyTab();
  if(!gl->bindings)
    return del_GetLine(gl);
/*
 * Define the available actions that can be bound to key sequences.
 */
  for(i=0; i<sizeof(gl_actions)/sizeof(gl_actions[0]); i++) {
    if(_kt_set_action(gl->bindings, gl_actions[i].name, gl_actions[i].fn, NULL))
      return del_GetLine(gl);
  };
/*
 * Set up the default bindings.
 */
  if(gl_change_editor(gl, gl->editor))
    return del_GetLine(gl);
/*
 * Allocate termcap buffers.
 */
#ifdef USE_TERMCAP
  gl->tgetent_buf = (char *) malloc(TERMCAP_BUF_SIZE);
  gl->tgetstr_buf = (char *) malloc(TERMCAP_BUF_SIZE);
  if(!gl->tgetent_buf || !gl->tgetstr_buf) {
    errno = ENOMEM;
    return del_GetLine(gl);
  };
#endif
/*
 * Set up for I/O assuming stdin and stdout.
 */
  if(_gl_change_terminal(gl, stdin, stdout, getenv("TERM")))
    return del_GetLine(gl);
/*
 * Create a freelist for use in allocating GlFdNode list nodes.
 */
#ifdef HAVE_SELECT
  gl->fd_node_mem = _new_FreeList(sizeof(GlFdNode), GLFD_FREELIST_BLOCKING);
  if(!gl->fd_node_mem)
    return del_GetLine(gl);
#endif
/*
 * We are done for now.
 */
  return gl;
}

/*.......................................................................
 * Delete a GetLine object.
 *
 * Input:
 *  gl     GetLine *  The object to be deleted.
 * Output:
 *  return GetLine *  The deleted object (always NULL).
 */
GetLine *del_GetLine(GetLine *gl)
{
  if(gl) {
/*
 * If the terminal is in raw server mode, reset it.
 */
    _gl_normal_io(gl);
/*
 * Deallocate all objects contained by gl.
 */
    gl->err = _del_ErrMsg(gl->err);
    gl->glh = _del_GlHistory(gl->glh);
    gl->cpl = del_WordCompletion(gl->cpl);
#ifndef WITHOUT_FILE_SYSTEM
    gl->ef = del_ExpandFile(gl->ef);
#endif
    gl->capmem = _del_StringGroup(gl->capmem);
    gl->cq = _del_GlCharQueue(gl->cq);
    if(gl->file_fp)
      fclose(gl->file_fp);
    if(gl->term)
      free(gl->term);
    if(gl->line)
      free(gl->line);
    if(gl->cutbuf)
      free(gl->cutbuf);
    if(gl->prompt)
      free(gl->prompt);
    gl->cpl_mem = _del_FreeList(gl->cpl_mem, 1);
    gl->ext_act_mem = _del_FreeList(gl->ext_act_mem, 1);
    gl->sig_mem = _del_FreeList(gl->sig_mem, 1);
    gl->sigs = NULL;       /* Already freed by freeing sig_mem */
    gl->bindings = _del_KeyTab(gl->bindings);
    if(gl->vi.undo.line)
      free(gl->vi.undo.line);
#ifdef USE_TERMCAP
    if(gl->tgetent_buf)
      free(gl->tgetent_buf);
    if(gl->tgetstr_buf)
      free(gl->tgetstr_buf);
#endif
    if(gl->app_file)
      free(gl->app_file);
    if(gl->user_file)
      free(gl->user_file);
#ifdef HAVE_SELECT
    gl->fd_node_mem = _del_FreeList(gl->fd_node_mem, 1);
    gl->fd_nodes = NULL;  /* Already freed by freeing gl->fd_node_mem */
#endif
/*
 * Delete the now empty container.
 */
    free(gl);
  };
  return NULL;
}

/*.......................................................................
 * Bind a control or meta character to an action.
 *
 * Input:
 *  gl         GetLine *  The resource object of this program.
 *  binder    KtBinder    The source of the binding.
 *  c             char    The control or meta character.
 *                        If this is '\0', the call is ignored.
 *  action  const char *  The action name to bind the key to.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error.
 */
static int gl_bind_control_char(GetLine *gl, KtBinder binder, char c,
				const char *action)
{
  char keyseq[2];
/*
 * Quietly reject binding to the NUL control character, since this
 * is an ambiguous prefix of all bindings.
 */
  if(c == '\0')
    return 0;
/*
 * Making sure not to bind characters which aren't either control or
 * meta characters.
 */
  if(IS_CTRL_CHAR(c) || IS_META_CHAR(c)) {
    keyseq[0] = c;
    keyseq[1] = '\0';
  } else {
    return 0;
  };
/*
 * Install the binding.
 */
  if(_kt_set_keybinding(gl->bindings, binder, keyseq, action)) {
    _err_record_msg(gl->err, _kt_last_error(gl->bindings), END_ERR_MSG);
    return 1;
  };
  return 0;
}

/*.......................................................................
 * Read a line from the user.
 *
 * Input:
 *  gl       GetLine *  A resource object returned by new_GetLine().
 *  prompt      char *  The prompt to prefix the line with.
 *  start_line  char *  The initial contents of the input line, or NULL
 *                      if it should start out empty.
 *  start_pos    int    If start_line isn't NULL, this specifies the
 *                      index of the character over which the cursor
 *                      should initially be positioned within the line.
 *                      If you just want it to follow the last character
 *                      of the line, send -1.
 * Output:
 *  return      char *  An internal buffer containing the input line, or
 *                      NULL at the end of input. If the line fitted in
 *                      the buffer there will be a '\n' newline character
 *                      before the terminating '\0'. If it was truncated
 *                      there will be no newline character, and the remains
 *                      of the line should be retrieved via further calls
 *                      to this function.
 */
char *gl_get_line(GetLine *gl, const char *prompt,
		  const char *start_line, int start_pos)
{
  char *retval;   /* The return value of _gl_get_line() */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Temporarily block all of the signals that we have been asked to trap.
 */
  if(gl_mask_signals(gl, &gl->old_signal_set))
    return NULL;
/*
 * Perform the command-line editing task.
 */
  retval = _gl_get_line(gl, prompt, start_line, start_pos);
/*
 * Restore the process signal mask to how it was when this function was
 * first called.
 */
  gl_unmask_signals(gl, &gl->old_signal_set);
  return retval;
}


/*.......................................................................
 * This is the main body of the public function gl_get_line().
 */
static char *_gl_get_line(GetLine *gl, const char *prompt,
			  const char *start_line, int start_pos)
{
  int waserr = 0;    /* True if an error occurs */
/*
 * Assume that this call will successfully complete the input
 * line until proven otherwise.
 */
  gl_clear_status(gl);
/*
 * If this is the first call to this function since new_GetLine(),
 * complete any postponed configuration.
 */
  if(!gl->configured) {
    (void) _gl_configure_getline(gl, NULL, NULL, TECLA_CONFIG_FILE);
    gl->configured = 1;
  };
/*
 * Before installing our signal handler functions, record the fact
 * that there are no pending signals.
 */
  gl_pending_signal = -1;
/*
 * Temporarily override the signal handlers of the calling program,
 * so that we can intercept signals that would leave the terminal
 * in a bad state.
 */
  waserr = gl_override_signal_handlers(gl);
/*
 * After recording the current terminal settings, switch the terminal
 * into raw input mode.
 */
  waserr = waserr || _gl_raw_io(gl, 1);
/*
 * Attempt to read the line. This will require more than one attempt if
 * either a current temporary input file is opened by gl_get_input_line()
 * or the end of a temporary input file is reached by gl_read_stream_line().
 */
  while(!waserr) {
/*
 * Read a line from a non-interactive stream?
 */
    if(gl->file_fp || !gl->is_term) {
      if(gl_read_stream_line(gl)==0) {
	break;
      } else if(gl->file_fp) {
	gl_revert_input(gl);
	gl_record_status(gl, GLR_NEWLINE, 0);
      } else {
	waserr = 1;
	break;
      };
    };
/*
 * Read from the terminal? Note that the above if() block may have
 * changed gl->file_fp, so it is necessary to retest it here, rather
 * than using an else statement.
 */
    if(!gl->file_fp && gl->is_term) {
      if(gl_get_input_line(gl, prompt, start_line, start_pos))
	waserr = 1;
      else
	break;
    };
  };
/*
 * If an error occurred, but gl->rtn_status is still set to
 * GLR_NEWLINE, change the status to GLR_ERROR. Otherwise
 * leave it at whatever specific value was assigned by the function
 * that aborted input. This means that only functions that trap
 * non-generic errors have to remember to update gl->rtn_status
 * themselves.
 */
  if(waserr && gl->rtn_status == GLR_NEWLINE)
    gl_record_status(gl, GLR_ERROR, errno);
/*
 * Restore terminal settings.
 */
  if(gl->io_mode != GL_SERVER_MODE)
    _gl_normal_io(gl);
/*
 * Restore the signal handlers.
 */
  gl_restore_signal_handlers(gl);
/*
 * If gl_get_line() gets aborted early, the errno value associated
 * with the event that caused this to happen is recorded in
 * gl->rtn_errno. Since errno may have been overwritten by cleanup
 * functions after this, restore its value to the value that it had
 * when the error condition occured, so that the caller can examine it
 * to find out what happened.
 */
  errno = gl->rtn_errno;
/*
 * Check the completion status to see how to return.
 */
  switch(gl->rtn_status) {
  case GLR_NEWLINE:    /* Success */
    return gl->line;
  case GLR_BLOCKED:    /* These events abort the current input line, */
  case GLR_SIGNAL:     /*  when in normal blocking I/O mode, but only */
  case GLR_TIMEOUT:    /*  temporarily pause line editing when in */
  case GLR_FDABORT:    /*  non-blocking server I/O mode. */
    if(gl->io_mode != GL_SERVER_MODE)
      _gl_abandon_line(gl);
    return NULL;
  case GLR_ERROR:      /* Unrecoverable errors abort the input line, */
  case GLR_EOF:        /*  regardless of the I/O mode. */
  default:
    _gl_abandon_line(gl);
    return NULL;
  };
}

/*.......................................................................
 * Read a single character from the user.
 *
 * Input:
 *  gl       GetLine *  A resource object returned by new_GetLine().
 *  prompt      char *  The prompt to prefix the line with, or NULL if
 *                      no prompt is required.
 *  defchar     char    The character to substitute if the
 *                      user simply hits return, or '\n' if you don't
 *                      need to substitute anything.
 * Output:
 *  return       int    The character that was read, or EOF if the read
 *                      had to be aborted (in which case you can call
 *                      gl_return_status() to find out why).
 */
int gl_query_char(GetLine *gl, const char *prompt, char defchar)
{
  int retval;   /* The return value of _gl_query_char() */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return EOF;
  };
/*
 * Temporarily block all of the signals that we have been asked to trap.
 */
  if(gl_mask_signals(gl, &gl->old_signal_set))
    return EOF;
/*
 * Perform the character reading task.
 */
  retval = _gl_query_char(gl, prompt, defchar);
/*
 * Restore the process signal mask to how it was when this function was
 * first called.
 */
  gl_unmask_signals(gl, &gl->old_signal_set);
  return retval;
}

/*.......................................................................
 * This is the main body of the public function gl_query_char().
 */
static int _gl_query_char(GetLine *gl, const char *prompt, char defchar)
{
  int c = EOF;       /* The character to be returned */
  int waserr = 0;    /* True if an error occurs */
/*
 * Assume that this call will successfully complete the input operation
 * until proven otherwise.
 */
  gl_clear_status(gl);
/*
 * If this is the first call to this function or gl_get_line(),
 * since new_GetLine(), complete any postponed configuration.
 */
  if(!gl->configured) {
    (void) _gl_configure_getline(gl, NULL, NULL, TECLA_CONFIG_FILE);
    gl->configured = 1;
  };
/*
 * Before installing our signal handler functions, record the fact
 * that there are no pending signals.
 */
  gl_pending_signal = -1;
/*
 * Temporarily override the signal handlers of the calling program,
 * so that we can intercept signals that would leave the terminal
 * in a bad state.
 */
  waserr = gl_override_signal_handlers(gl);
/*
 * After recording the current terminal settings, switch the terminal
 * into raw input mode without redisplaying any partially entered
 * input line.
 */
  waserr = waserr || _gl_raw_io(gl, 0);
/*
 * Attempt to read the line. This will require more than one attempt if
 * either a current temporary input file is opened by gl_get_input_line()
 * or the end of a temporary input file is reached by gl_read_stream_line().
 */
  while(!waserr) {
/*
 * Read a line from a non-interactive stream?
 */
    if(gl->file_fp || !gl->is_term) {
      c = gl_read_stream_char(gl);
      if(c != EOF) {            /* Success? */
	if(c=='\n') c = defchar;
	break;
      } else if(gl->file_fp) {  /* End of temporary input file? */
	gl_revert_input(gl);
	gl_record_status(gl, GLR_NEWLINE, 0);
      } else {                  /* An error? */
	waserr = 1;
	break;
      };
    };
/*
 * Read from the terminal? Note that the above if() block may have
 * changed gl->file_fp, so it is necessary to retest it here, rather
 * than using an else statement.
 */
    if(!gl->file_fp && gl->is_term) {
      c = gl_get_query_char(gl, prompt, defchar);
      if(c==EOF)
	waserr = 1;
      else
	break;
    };
  };
/*
 * If an error occurred, but gl->rtn_status is still set to
 * GLR_NEWLINE, change the status to GLR_ERROR. Otherwise
 * leave it at whatever specific value was assigned by the function
 * that aborted input. This means that only functions that trap
 * non-generic errors have to remember to update gl->rtn_status
 * themselves.
 */
  if(waserr && gl->rtn_status == GLR_NEWLINE)
    gl_record_status(gl, GLR_ERROR, errno);
/*
 * Restore terminal settings.
 */
  if(gl->io_mode != GL_SERVER_MODE)
    _gl_normal_io(gl);
/*
 * Restore the signal handlers.
 */
  gl_restore_signal_handlers(gl);
/*
 * If this function gets aborted early, the errno value associated
 * with the event that caused this to happen is recorded in
 * gl->rtn_errno. Since errno may have been overwritten by cleanup
 * functions after this, restore its value to the value that it had
 * when the error condition occured, so that the caller can examine it
 * to find out what happened.
 */
  errno = gl->rtn_errno;
/*
 * Error conditions are signalled to the caller, by setting the returned
 * character to EOF.
 */
  if(gl->rtn_status != GLR_NEWLINE)
    c = EOF;
/*
 * In this mode, every character that is read is a completed
 * transaction, just like reading a completed input line, so prepare
 * for the next input line or character.
 */
  _gl_abandon_line(gl);
/*
 * Return the acquired character.
 */
  return c;
}

/*.......................................................................
 * Record of the signal handlers of the calling program, so that they
 * can be restored later.
 *
 * Input:
 *  gl    GetLine *   The resource object of this library.
 * Output:
 *  return    int     0 - OK.
 *                    1 - Error.
 */
static int gl_override_signal_handlers(GetLine *gl)
{
  GlSignalNode *sig;   /* A node in the list of signals to be caught */
/*
 * Set up our signal handler.
 */
  SigAction act;
  act.sa_handler = gl_signal_handler;
  memcpy(&act.sa_mask, &gl->all_signal_set, sizeof(sigset_t));
  act.sa_flags = 0;
/*
 * Get the subset of the signals that we are supposed to trap that
 * should actually be trapped.
 */
  sigemptyset(&gl->use_signal_set);
  for(sig=gl->sigs; sig; sig=sig->next) {
/*
 * Trap this signal? If it is blocked by the calling program and we
 * haven't been told to unblock it, don't arrange to trap this signal.
 */
    if(sig->flags & GLS_UNBLOCK_SIG ||
       !sigismember(&gl->old_signal_set, sig->signo)) {
      if(sigaddset(&gl->use_signal_set, sig->signo) == -1) {
	_err_record_msg(gl->err, "sigaddset error", END_ERR_MSG);
	return 1;
      };
    };
  };
/*
 * Override the actions of the signals that we are trapping.
 */
  for(sig=gl->sigs; sig; sig=sig->next) {
    if(sigismember(&gl->use_signal_set, sig->signo)) {
      sigdelset(&act.sa_mask, sig->signo);
      if(sigaction(sig->signo, &act, &sig->original)) {
	_err_record_msg(gl->err, "sigaction error", END_ERR_MSG);
	return 1;
      };
      sigaddset(&act.sa_mask, sig->signo);
    };
  };
/*
 * Record the fact that the application's signal handlers have now
 * been overriden.
 */
  gl->signals_overriden = 1;
/*
 * Just in case a SIGWINCH signal was sent to the process while our
 * SIGWINCH signal handler wasn't in place, check to see if the terminal
 * size needs updating.
 */
  if(_gl_update_size(gl))
    return 1;
  return 0;
}

/*.......................................................................
 * Restore the signal handlers of the calling program.
 *
 * Input:
 *  gl     GetLine *  The resource object of this library.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */
static int gl_restore_signal_handlers(GetLine *gl)
{
  GlSignalNode *sig;   /* A node in the list of signals to be caught */
/*
 * Restore application signal handlers that were overriden
 * by gl_override_signal_handlers().
 */
  for(sig=gl->sigs; sig; sig=sig->next) {
    if(sigismember(&gl->use_signal_set, sig->signo) &&
       sigaction(sig->signo, &sig->original, NULL)) {
      _err_record_msg(gl->err, "sigaction error", END_ERR_MSG);
      return 1;
    };
  };
/*
 * Record the fact that the application's signal handlers have now
 * been restored.
 */
  gl->signals_overriden = 0;
  return 0;
}

/*.......................................................................
 * This signal handler simply records the fact that a given signal was
 * caught in the file-scope gl_pending_signal variable.
 */
static void gl_signal_handler(int signo)
{
  gl_pending_signal = signo;
  siglongjmp(gl_setjmp_buffer, 1);
}

/*.......................................................................
 * Switch the terminal into raw mode after storing the previous terminal
 * settings in gl->attributes.
 *
 * Input:
 *  gl     GetLine *   The resource object of this program.
 * Output:
 *  return     int     0 - OK.
 *                     1 - Error.
 */
static int gl_raw_terminal_mode(GetLine *gl)
{
  Termios newattr;   /* The new terminal attributes */
/*
 * If the terminal is already in raw mode, do nothing.
 */
  if(gl->raw_mode)
    return 0;
/*
 * Record the current terminal attributes.
 */
  if(tcgetattr(gl->input_fd, &gl->oldattr)) {
    _err_record_msg(gl->err, "tcgetattr error", END_ERR_MSG);
    return 1;
  };
/*
 * This function shouldn't do anything but record the current terminal
 * attritubes if editing has been disabled.
 */
  if(gl->editor == GL_NO_EDITOR)
    return 0;
/*
 * Modify the existing attributes.
 */
  newattr = gl->oldattr;
/*
 * Turn off local echo, canonical input mode and extended input processing.
 */
  newattr.c_lflag &= ~(ECHO | ICANON | IEXTEN);
/*
 * Don't translate carriage return to newline, turn off input parity
 * checking, don't strip off 8th bit, turn off output flow control.
 */
  newattr.c_iflag &= ~(ICRNL | INPCK | ISTRIP);
/*
 * Clear size bits, turn off parity checking, and allow 8-bit characters.
 */
  newattr.c_cflag &= ~(CSIZE | PARENB);
  newattr.c_cflag |= CS8;
/*
 * Turn off output processing.
 */
  newattr.c_oflag &= ~(OPOST);
/*
 * Request one byte at a time, without waiting.
 */
  newattr.c_cc[VMIN] = gl->io_mode==GL_SERVER_MODE ? 0:1;
  newattr.c_cc[VTIME] = 0;
/*
 * Install the new terminal modes.
 */
  while(tcsetattr(gl->input_fd, TCSADRAIN, &newattr)) {
    if(errno != EINTR) {
      _err_record_msg(gl->err, "tcsetattr error", END_ERR_MSG);
      return 1;
    };
  };
/*
 * Record the new terminal mode.
 */
  gl->raw_mode = 1;
  return 0;
}

/*.......................................................................
 * Restore the terminal attributes recorded in gl->oldattr.
 *
 * Input:
 *  gl     GetLine *   The resource object of this library.
 * Output:
 *  return     int     0 - OK.
 *                     1 - Error.
 */
static int gl_restore_terminal_attributes(GetLine *gl)
{
  int waserr = 0;
/*
 * If not in raw mode, do nothing.
 */
  if(!gl->raw_mode)
    return 0;
/*
 * Before changing the terminal attributes, make sure that all output
 * has been passed to the terminal.
 */
  if(gl_flush_output(gl))
    waserr = 1;
/*
 * Reset the terminal attributes to the values that they had on
 * entry to gl_get_line().
 */
  while(tcsetattr(gl->input_fd, TCSADRAIN, &gl->oldattr)) {
    if(errno != EINTR) {
      _err_record_msg(gl->err, "tcsetattr error", END_ERR_MSG);
      waserr = 1;
      break;
    };
  };
/*
 * Record the new terminal mode.
 */
  gl->raw_mode = 0;
  return waserr;
}

/*.......................................................................
 * Switch the terminal file descriptor to use non-blocking I/O.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  fd             int    The file descriptor to make non-blocking.
 */
static int gl_nonblocking_io(GetLine *gl, int fd)
{
  int fcntl_flags;   /* The new file-descriptor control flags */
/*
 * Is non-blocking I/O supported on this system?  Note that even
 * without non-blocking I/O, the terminal will probably still act as
 * though it was non-blocking, because we also set the terminal
 * attributes to return immediately if no input is available and we
 * use select() to wait to be able to write. If select() also isn't
 * available, then input will probably remain fine, but output could
 * block, depending on the behaviour of the terminal driver.
 */
#if defined(NON_BLOCKING_FLAG)
/*
 * Query the current file-control flags, and add the
 * non-blocking I/O flag.
 */
  fcntl_flags = fcntl(fd, F_GETFL) | NON_BLOCKING_FLAG;
/*
 * Install the new control flags.
 */
  if(fcntl(fd, F_SETFL, fcntl_flags) == -1) {
    _err_record_msg(gl->err, "fcntl error", END_ERR_MSG);
    return 1;
  };
#endif
  return 0;
}

/*.......................................................................
 * Switch to blocking terminal I/O.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  fd             int    The file descriptor to make blocking.
 */
static int gl_blocking_io(GetLine *gl, int fd)
{
  int fcntl_flags;   /* The new file-descriptor control flags */
/*
 * Is non-blocking I/O implemented on this system?
 */
#if defined(NON_BLOCKING_FLAG)
/*
 * Query the current file control flags and remove the non-blocking
 * I/O flag.
 */
  fcntl_flags = fcntl(fd, F_GETFL) & ~NON_BLOCKING_FLAG;
/*
 * Install the modified control flags.
 */
  if(fcntl(fd, F_SETFL, fcntl_flags) == -1) {
    _err_record_msg(gl->err, "fcntl error", END_ERR_MSG);
    return 1;
  };
#endif
  return 0;
}

/*.......................................................................
 * Read a new input line from the user.
 *
 * Input:
 *  gl         GetLine *  The resource object of this library.
 *  prompt        char *  The prompt to prefix the line with, or NULL to
 *                        use the same prompt that was used by the previous
 *                        line.
 *  start_line    char *  The initial contents of the input line, or NULL
 *                        if it should start out empty.
 *  start_pos      int    If start_line isn't NULL, this specifies the
 *                        index of the character over which the cursor
 *                        should initially be positioned within the line.
 *                        If you just want it to follow the last character
 *                        of the line, send -1.
 * Output:
 *  return    int    0 - OK.
 *                   1 - Error.
 */
static int gl_get_input_line(GetLine *gl, const char *prompt,
			     const char *start_line, int start_pos)
{
  char c;               /* The character being read */
/*
 * Flush any pending output to the terminal.
 */
  if(_glq_char_count(gl->cq) > 0 && gl_flush_output(gl))
    return 1;
/*
 * Are we starting a new line?
 */
  if(gl->endline) {
/*
 * Delete any incompletely enterred line.
 */
    if(gl_erase_line(gl))
      return 1;
/*
 * Display the new line to be edited.
 */
    if(gl_present_line(gl, prompt, start_line, start_pos))
      return 1;
  };
/*
 * Read one character at a time.
 */
  while(gl_read_terminal(gl, 1, &c) == 0) {
/*
 * Increment the count of the number of key sequences entered.
 */
    gl->keyseq_count++;
/*
 * Interpret the character either as the start of a new key-sequence,
 * as a continuation of a repeat count, or as a printable character
 * to be added to the line.
 */
    if(gl_interpret_char(gl, c))
      break;
/*
 * If we just ran an action function which temporarily asked for
 * input to be taken from a file, abort this call.
 */
    if(gl->file_fp)
      return 0;
/*
 * Has the line been completed?
 */
    if(gl->endline)
      return gl_line_ended(gl, c);
  };
/*
 * To get here, gl_read_terminal() must have returned non-zero. See
 * whether a signal was caught that requested that the current line
 * be returned.
 */
  if(gl->endline)
    return gl_line_ended(gl, '\n');
/*
 * If I/O blocked while attempting to get the latest character
 * of the key sequence, rewind the key buffer to allow interpretation of
 * the current key sequence to be restarted on the next call to this
 * function.
 */
  if(gl->rtn_status == GLR_BLOCKED && gl->pending_io == GLP_READ)
    gl->nread = 0;
  return 1;
}

/*.......................................................................
 * This is the private function of gl_query_char() that handles
 * prompting the user, reading a character from the terminal, and
 * displaying what the user entered.
 *
 * Input:
 *  gl         GetLine *  The resource object of this library.
 *  prompt        char *  The prompt to prefix the line with.
 *  defchar       char    The character to substitute if the
 *                        user simply hits return, or '\n' if you don't
 *                        need to substitute anything.
 * Output:
 *  return         int    The character that was read, or EOF if something
 *                        prevented a character from being read.
 */
static int gl_get_query_char(GetLine *gl, const char *prompt, int defchar)
{
  char c;               /* The character being read */
  int retval;           /* The return value of this function */
/*
 * Flush any pending output to the terminal.
 */
  if(_glq_char_count(gl->cq) > 0 && gl_flush_output(gl))
    return EOF;
/*
 * Delete any incompletely entered line.
 */
  if(gl_erase_line(gl))
    return EOF;
/*
 * Reset the line input parameters and display the prompt, if any.
 */
  if(gl_present_line(gl, prompt, NULL, 0))
    return EOF;
/*
 * Read one character.
 */
  if(gl_read_terminal(gl, 1, &c) == 0) {
/*
 * In this mode, count each character as being a new key-sequence.
 */
    gl->keyseq_count++;
/*
 * Delete the character that was read, from the key-press buffer.
 */
    gl_discard_chars(gl, gl->nread);
/*
 * Convert carriage returns to newlines.
 */
    if(c == '\r')
      c = '\n';
/*
 * If the user just hit return, subsitute the default character.
 */
    if(c == '\n')
      c = defchar;
/*
 * Display the entered character to the right of the prompt.
 */
    if(c!='\n') {
      if(gl_end_of_line(gl, 1, NULL)==0)
	gl_print_char(gl, c, ' ');
    };
/*
 * Record the return character, and mark the call as successful.
 */
    retval = c;
    gl_record_status(gl, GLR_NEWLINE, 0);
/*
 * Was a signal caught whose disposition is to cause the current input
 * line to be returned? If so return a newline character.
 */
  } else if(gl->endline) {
    retval = '\n';
    gl_record_status(gl, GLR_NEWLINE, 0);
  } else {
    retval = EOF;
  };
/*
 * Start a new line.
 */
  if(gl_start_newline(gl, 1))
    return EOF;
/*
 * Attempt to flush any pending output.
 */
  (void) gl_flush_output(gl);
/*
 * Return either the character that was read, or EOF if an error occurred.
 */
  return retval;
}

/*.......................................................................
 * Add a character to the line buffer at the current cursor position,
 * inserting or overwriting according the current mode.
 *
 * Input:
 *  gl   GetLine *   The resource object of this library.
 *  c       char     The character to be added.
 * Output:
 *  return   int     0 - OK.
 *                   1 - Insufficient room.
 */
static int gl_add_char_to_line(GetLine *gl, char c)
{
/*
 * Keep a record of the current cursor position.
 */
  int buff_curpos = gl->buff_curpos;
  int term_curpos = gl->term_curpos;
/*
 * Work out the displayed width of the new character.
 */
  int width = gl_displayed_char_width(gl, c, term_curpos);
/*
 * If we are in insert mode, or at the end of the line,
 * check that we can accomodate a new character in the buffer.
 * If not, simply return, leaving it up to the calling program
 * to check for the absence of a newline character.
 */
  if((gl->insert || buff_curpos >= gl->ntotal) && gl->ntotal >= gl->linelen)
    return 0;
/*
 * Are we adding characters to the line (ie. inserting or appending)?
 */
  if(gl->insert || buff_curpos >= gl->ntotal) {
/*
 * If inserting, make room for the new character.
 */
    if(buff_curpos < gl->ntotal)
      gl_make_gap_in_buffer(gl, buff_curpos, 1);
/*
 * Copy the character into the buffer.
 */
    gl_buffer_char(gl, c, buff_curpos);
    gl->buff_curpos++;
/*
 * Redraw the line from the cursor position to the end of the line,
 * and move the cursor to just after the added character.
 */
    if(gl_print_string(gl, gl->line + buff_curpos, '\0') ||
       gl_set_term_curpos(gl, term_curpos + width))
      return 1;
/*
 * Are we overwriting an existing character?
 */
  } else {
/*
 * Get the width of the character being overwritten.
 */
    int old_width = gl_displayed_char_width(gl, gl->line[buff_curpos],
					    term_curpos);
/*
 * Overwrite the character in the buffer.
 */
    gl_buffer_char(gl, c, buff_curpos);
/*
 * If we are replacing with a narrower character, we need to
 * redraw the terminal string to the end of the line, then
 * overwrite the trailing old_width - width characters
 * with spaces.
 */
    if(old_width > width) {
      if(gl_print_string(gl, gl->line + buff_curpos, '\0'))
	return 1;
/*
 * Clear to the end of the terminal.
 */
      if(gl_truncate_display(gl))
	return 1;
/*
 * Move the cursor to the end of the new character.
 */
      if(gl_set_term_curpos(gl, term_curpos + width))
	return 1;
      gl->buff_curpos++;
/*
 * If we are replacing with a wider character, then we will be
 * inserting new characters, and thus extending the line.
 */
    } else if(width > old_width) {
/*
 * Redraw the line from the cursor position to the end of the line,
 * and move the cursor to just after the added character.
 */
      if(gl_print_string(gl, gl->line + buff_curpos, '\0') ||
	 gl_set_term_curpos(gl, term_curpos + width))
	return 1;
      gl->buff_curpos++;
/*
 * The original and replacement characters have the same width,
 * so simply overwrite.
 */
    } else {
/*
 * Copy the character into the buffer.
 */
      gl_buffer_char(gl, c, buff_curpos);
      gl->buff_curpos++;
/*
 * Overwrite the original character.
 */
      if(gl_print_char(gl, c, gl->line[gl->buff_curpos]))
	return 1;
    };
  };
  return 0;
}

/*.......................................................................
 * Insert/append a string to the line buffer and terminal at the current
 * cursor position.
 *
 * Input:
 *  gl   GetLine *   The resource object of this library.
 *  s       char *   The string to be added.
 * Output:
 *  return   int     0 - OK.
 *                   1 - Insufficient room.
 */
static int gl_add_string_to_line(GetLine *gl, const char *s)
{
  int buff_slen;   /* The length of the string being added to line[] */
  int term_slen;   /* The length of the string being written to the terminal */
  int buff_curpos; /* The original value of gl->buff_curpos */
  int term_curpos; /* The original value of gl->term_curpos */
/*
 * Keep a record of the current cursor position.
 */
  buff_curpos = gl->buff_curpos;
  term_curpos = gl->term_curpos;
/*
 * How long is the string to be added?
 */
  buff_slen = strlen(s);
  term_slen = gl_displayed_string_width(gl, s, buff_slen, term_curpos);
/*
 * Check that we can accomodate the string in the buffer.
 * If not, simply return, leaving it up to the calling program
 * to check for the absence of a newline character.
 */
  if(gl->ntotal + buff_slen > gl->linelen)
    return 0;
/*
 * Move the characters that follow the cursor in the buffer by
 * buff_slen characters to the right.
 */
  if(gl->ntotal > gl->buff_curpos)
    gl_make_gap_in_buffer(gl, gl->buff_curpos, buff_slen);
/*
 * Copy the string into the buffer.
 */
  gl_buffer_string(gl, s, buff_slen, gl->buff_curpos);
  gl->buff_curpos += buff_slen;
/*
 * Write the modified part of the line to the terminal, then move
 * the terminal cursor to the end of the displayed input string.
 */
  if(gl_print_string(gl, gl->line + buff_curpos, '\0') ||
     gl_set_term_curpos(gl, term_curpos + term_slen))
    return 1;
  return 0;
}

/*.......................................................................
 * Read a single character from the terminal.
 *
 * Input:
 *  gl    GetLine *   The resource object of this library.
 *  keep      int     If true, the returned character will be kept in
 *                    the input buffer, for potential replays. It should
 *                    subsequently be removed from the buffer when the
 *                    key sequence that it belongs to has been fully
 *                    processed, by calling gl_discard_chars().
 * Input/Output:
 *  c        char *   The character that is read, is assigned to *c.
 * Output:
 *  return    int     0 - OK.
 *                    1 - Either an I/O error occurred, or a signal was
 *                        caught who's disposition is to abort gl_get_line()
 *                        or to have gl_get_line() return the current line
 *                        as though the user had pressed return. In the
 *                        latter case gl->endline will be non-zero.
 */
static int gl_read_terminal(GetLine *gl, int keep, char *c)
{
/*
 * Before waiting for a new character to be input, flush unwritten
 * characters to the terminal.
 */
  if(gl_flush_output(gl))
    return 1;
/*
 * Record the fact that we are about to read from the terminal.
 */
  gl->pending_io = GLP_READ;
/*
 * If there is already an unread character in the buffer,
 * return it.
 */
  if(gl->nread < gl->nbuf) {
    *c = gl->keybuf[gl->nread];
/*
 * Retain the character in the key buffer, but mark it as having been read?
 */
    if(keep) {
      gl->nread++;
/*
 * Completely remove the character from the key buffer?
 */
    } else {
      memmove(gl->keybuf + gl->nread, gl->keybuf + gl->nread + 1,
	      gl->nbuf - gl->nread - 1);
    };
    return 0;
  };
/*
 * Make sure that there is space in the key buffer for one more character.
 * This should always be true if gl_interpret_char() is called for each
 * new character added, since it will clear the buffer once it has recognized
 * or rejected a key sequence.
 */
  if(gl->nbuf + 1 > GL_KEY_MAX) {
    gl_print_info(gl, "gl_read_terminal: Buffer overflow avoided.",
		  GL_END_INFO);
    errno = EIO;
    return 1;
  };
/*
 * Read one character from the terminal.
 */
  switch(gl_read_input(gl, c)) {
  case GL_READ_OK:
    break;
  case GL_READ_BLOCKED:
    gl_record_status(gl, GLR_BLOCKED, BLOCKED_ERRNO);
    return 1;
    break;
  default:
    return 1;
    break;
  };
/*
 * Append the character to the key buffer?
 */
  if(keep) {
    gl->keybuf[gl->nbuf] = *c;
    gl->nread = ++gl->nbuf;
  };
  return 0;
}

/*.......................................................................
 * Read one or more keypresses from the terminal of an input stream.
 *
 * Input:
 *  gl           GetLine *  The resource object of this module.
 *  c               char *  The character that was read is assigned to *c.
 * Output:
 *  return  GlReadStatus    The completion status of the read operation.
 */
static GlReadStatus gl_read_input(GetLine *gl, char *c)
{
/*
 * We may have to repeat the read if window change signals are received.
 */
  for(;;) {
/*
 * Which file descriptor should we read from? Mark this volatile, so
 * that siglongjmp() can't clobber it.
 */
    volatile int fd = gl->file_fp ? fileno(gl->file_fp) : gl->input_fd;
/*
 * If the endline flag becomes set, don't wait for another character.
 */
    if(gl->endline)
      return GL_READ_ERROR;
/*
 * Since the code in this function can block, trap signals.
 */
    if(sigsetjmp(gl_setjmp_buffer, 1)==0) {
/*
 * Handle the different I/O modes.
 */
      switch(gl->io_mode) {
/*
 * In normal I/O mode, we call the event handler before attempting
 * to read, since read() blocks.
 */
      case GL_NORMAL_MODE:
	if(gl_event_handler(gl, fd))
	  return GL_READ_ERROR;
	return gl_read_unmasked(gl, fd, c);  /* Read one character */
	break;
/*
 * In non-blocking server I/O mode, we attempt to read a character,
 * and only if this fails, call the event handler to wait for a any
 * user-configured timeout and any other user-configured events.  In
 * addition, we turn off the fcntl() non-blocking flag when reading
 * from the terminal, to work around a bug in Solaris. We can do this
 * without causing the read() to block, because when in non-blocking
 * server-I/O mode, gl_raw_io() sets the VMIN terminal attribute to 0,
 * which tells the terminal driver to return immediately if no
 * characters are available to be read.
 */
      case GL_SERVER_MODE:
	{
	  GlReadStatus status;        /* The return status */
	  if(isatty(fd))              /* If we reading from a terminal, */
	     gl_blocking_io(gl, fd);  /* switch to blocking I/O */
	  status = gl_read_unmasked(gl, fd, c); /* Try reading */
	  if(status == GL_READ_BLOCKED) {       /* Nothing readable yet */
	    if(gl_event_handler(gl, fd))        /* Wait for input */
	      status = GL_READ_ERROR;
	    else
	      status = gl_read_unmasked(gl, fd, c); /* Try reading again */
	  };
	  gl_nonblocking_io(gl, fd); /* Restore non-blocking I/O */
	  return status;
	};
	break;
      };
    };
/*
 * To get here, one of the signals that we are trapping must have
 * been received. Note that by using sigsetjmp() instead of setjmp()
 * the signal mask that was blocking these signals will have been
 * reinstated, so we can be sure that no more of these signals will
 * be received until we explicitly unblock them again.
 *
 * First, if non-blocking I/O was temporarily disabled, reinstate it.
 */
    if(gl->io_mode == GL_SERVER_MODE)
      gl_nonblocking_io(gl, fd);
/*
 * Now respond to the signal that was caught.
 */
    if(gl_check_caught_signal(gl))
      return GL_READ_ERROR;
  };
}

/*.......................................................................
 * This is a private function of gl_read_input(), which unblocks signals
 * temporarily while it reads a single character from the specified file
 * descriptor.
 *
 * Input:
 *  gl          GetLine *  The resource object of this module.
 *  fd              int    The file descriptor to read from.
 *  c              char *  The character that was read is assigned to *c.
 * Output:
 *  return GlReadStatus    The completion status of the read.
 */
static int gl_read_unmasked(GetLine *gl, int fd, char *c)
{
  int nread;  /* The return value of read() */
/*
 * Unblock the signals that we are trapping, while waiting for I/O.
 */
  gl_catch_signals(gl);
/*
 * Attempt to read one character from the terminal, restarting the read
 * if any signals that we aren't trapping, are received.
 */
  do {
    errno = 0;
    nread = read(fd, c, 1);
  } while(nread < 0 && errno==EINTR);
/*
 * Block all of the signals that we are trapping.
 */
  gl_mask_signals(gl, NULL);
/*
 * Check the completion status of the read.
 */
  switch(nread) {
  case 1:
    return GL_READ_OK;
  case 0:
    return (errno != 0 || isatty(fd)) ? GL_READ_BLOCKED : GL_READ_EOF;
  default:
    return GL_READ_ERROR;
  };
}

/*.......................................................................
 * Remove a specified number of characters from the start of the
 * key-press lookahead buffer, gl->keybuf[], and arrange for the next
 * read to start from the character at the start of the shifted buffer.
 *
 * Input:
 *  gl      GetLine *  The resource object of this module.
 *  nused       int    The number of characters to discard from the start
 *                     of the buffer.
 */
static void gl_discard_chars(GetLine *gl, int nused)
{
  int nkeep = gl->nbuf - nused;
  if(nkeep > 0) {
    memmove(gl->keybuf, gl->keybuf + nused, nkeep);
    gl->nbuf = nkeep;
    gl->nread = 0;
  } else {
    gl->nbuf = gl->nread = 0;
  };
}

/*.......................................................................
 * This function is called to handle signals caught between calls to
 * sigsetjmp() and siglongjmp().
 *
 * Input:
 *  gl      GetLine *   The resource object of this library.
 * Output:
 *  return      int     0 - Signal handled internally.
 *                      1 - Signal requires gl_get_line() to abort.
 */
static int gl_check_caught_signal(GetLine *gl)
{
  GlSignalNode *sig;      /* The signal disposition */
  SigAction keep_action;  /* The signal disposition of tecla signal handlers */
  unsigned flags;         /* The signal processing flags to use */
  int signo;              /* The signal to be handled */
/*
 * Was no signal caught?
 */
  if(gl_pending_signal == -1)
    return 0;
/*
 * Get the signal to be handled.
 */
  signo = gl_pending_signal;
/*
 * Mark the signal as handled. Note that at this point, all of
 * the signals that we are trapping are blocked from delivery.
 */
  gl_pending_signal = -1;
/*
 * Record the signal that was caught, so that the user can query it later.
 */
  gl->last_signal = signo;
/*
 * In non-blocking server mode, the application is responsible for
 * responding to terminal signals, and we don't want gl_get_line()s
 * normal signal handling to clash with this, so whenever a signal
 * is caught, we arrange for gl_get_line() to abort and requeue the
 * signal while signals are still blocked. If the application
 * had the signal unblocked when gl_get_line() was called, the signal
 * will be delivered again as soon as gl_get_line() restores the
 * process signal mask, just before returning to the application.
 * Note that the caller of this function should set gl->pending_io
 * to the appropriate choice of GLP_READ and GLP_WRITE, before returning.
 */
  if(gl->io_mode==GL_SERVER_MODE) {
    gl_record_status(gl, GLR_SIGNAL, EINTR);
    raise(signo);
    return 1;
  };
/*
 * Lookup the requested disposition of this signal.
 */
  for(sig=gl->sigs; sig && sig->signo != signo; sig=sig->next)
    ;
  if(!sig)
    return 0;
/*
 * Get the signal response flags for this signal.
 */
  flags = sig->flags;
/*
 * Did we receive a terminal size signal?
 */
#ifdef SIGWINCH
  if(signo == SIGWINCH && _gl_update_size(gl))
    return 1;
#endif
/*
 * Start a fresh line?
 */
  if(flags & GLS_RESTORE_LINE) {
    if(gl_start_newline(gl, 0))
      return 1;
  };
/*
 * Restore terminal settings to how they were before gl_get_line() was
 * called?
 */
  if(flags & GLS_RESTORE_TTY)
    gl_restore_terminal_attributes(gl);
/*
 * Restore signal handlers to how they were before gl_get_line() was
 * called? If this hasn't been requested, only reinstate the signal
 * handler of the signal that we are handling.
 */
  if(flags & GLS_RESTORE_SIG) {
    gl_restore_signal_handlers(gl);
    gl_unmask_signals(gl, &gl->old_signal_set);
  } else {
    (void) sigaction(sig->signo, &sig->original, &keep_action);
    (void) sigprocmask(SIG_UNBLOCK, &sig->proc_mask, NULL);
  };
/*
 * Forward the signal to the application's signal handler.
 */
  if(!(flags & GLS_DONT_FORWARD))
    raise(signo);
/*
 * Reinstate our signal handlers.
 */
  if(flags & GLS_RESTORE_SIG) {
    gl_mask_signals(gl, NULL);
    gl_override_signal_handlers(gl);
  } else {
    (void) sigaction(sig->signo, &keep_action, NULL);
    (void) sigprocmask(SIG_BLOCK, &sig->proc_mask, NULL);
  };
/*
 * Do we need to reinstate our terminal settings?
 */
  if(flags & GLS_RESTORE_TTY)
    gl_raw_terminal_mode(gl);
/*
 * Redraw the line?
 */
  if(flags & GLS_REDRAW_LINE)
    gl_queue_redisplay(gl);
/*
 * What next?
 */
  switch(sig->after) {
  case GLS_RETURN:
    gl_newline(gl, 1, NULL);
    return gl_flush_output(gl);
    break;
  case GLS_ABORT:
    gl_record_status(gl, GLR_SIGNAL, sig->errno_value);
    return 1;
    break;
  case GLS_CONTINUE:
    return gl_flush_output(gl);
    break;
  };
  return 0;
}

/*.......................................................................
 * Get pertinent terminal control strings and the initial terminal size.
 *
 * Input:
 *  gl     GetLine *  The resource object of this library.
 *  term      char *  The type of the terminal.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */
static int gl_control_strings(GetLine *gl, const char *term)
{
  int bad_term = 0;   /* True if term is unusable */
/*
 * Discard any existing control strings from a previous terminal.
 */
  gl->left = NULL;
  gl->right = NULL;
  gl->up = NULL;
  gl->down = NULL;
  gl->home = NULL;
  gl->bol = 0;
  gl->clear_eol = NULL;
  gl->clear_eod = NULL;
  gl->u_arrow = NULL;
  gl->d_arrow = NULL;
  gl->l_arrow = NULL;
  gl->r_arrow = NULL;
  gl->sound_bell = NULL;
  gl->bold = NULL;
  gl->underline = NULL;
  gl->standout = NULL;
  gl->dim = NULL;
  gl->reverse = NULL;
  gl->blink = NULL;
  gl->text_attr_off = NULL;
  gl->nline = 0;
  gl->ncolumn = 0;
#ifdef USE_TERMINFO
  gl->left_n = NULL;
  gl->right_n = NULL;
#endif
/*
 * If possible lookup the information in a terminal information
 * database.
 */
#ifdef USE_TERMINFO
  {
    int errret;
    if(!term || setupterm((char *)term, gl->input_fd, &errret) == ERR) {
      bad_term = 1;
    } else {
      _clr_StringGroup(gl->capmem);
      gl->left = gl_tigetstr(gl, "cub1");
      gl->right = gl_tigetstr(gl, "cuf1");
      gl->up = gl_tigetstr(gl, "cuu1");
      gl->down = gl_tigetstr(gl, "cud1");
      gl->home = gl_tigetstr(gl, "home");
      gl->clear_eol = gl_tigetstr(gl, "el");
      gl->clear_eod = gl_tigetstr(gl, "ed");
      gl->u_arrow = gl_tigetstr(gl, "kcuu1");
      gl->d_arrow = gl_tigetstr(gl, "kcud1");
      gl->l_arrow = gl_tigetstr(gl, "kcub1");
      gl->r_arrow = gl_tigetstr(gl, "kcuf1");
      gl->left_n = gl_tigetstr(gl, "cub");
      gl->right_n = gl_tigetstr(gl, "cuf");
      gl->sound_bell = gl_tigetstr(gl, "bel");
      gl->bold = gl_tigetstr(gl, "bold");
      gl->underline = gl_tigetstr(gl, "smul");
      gl->standout = gl_tigetstr(gl, "smso");
      gl->dim = gl_tigetstr(gl, "dim");
      gl->reverse = gl_tigetstr(gl, "rev");
      gl->blink = gl_tigetstr(gl, "blink");
      gl->text_attr_off = gl_tigetstr(gl, "sgr0");
    };
  };
#elif defined(USE_TERMCAP)
  if(!term || tgetent(gl->tgetent_buf, (char *)term) < 0) {
    bad_term = 1;
  } else {
    char *tgetstr_buf_ptr = gl->tgetstr_buf;
    _clr_StringGroup(gl->capmem);
    gl->left = gl_tgetstr(gl, "le", &tgetstr_buf_ptr);
    gl->right = gl_tgetstr(gl, "nd", &tgetstr_buf_ptr);
    gl->up = gl_tgetstr(gl, "up", &tgetstr_buf_ptr);
    gl->down = gl_tgetstr(gl, "do", &tgetstr_buf_ptr);
    gl->home = gl_tgetstr(gl, "ho", &tgetstr_buf_ptr);
    gl->clear_eol = gl_tgetstr(gl, "ce", &tgetstr_buf_ptr);
    gl->clear_eod = gl_tgetstr(gl, "cd", &tgetstr_buf_ptr);
    gl->u_arrow = gl_tgetstr(gl, "ku", &tgetstr_buf_ptr);
    gl->d_arrow = gl_tgetstr(gl, "kd", &tgetstr_buf_ptr);
    gl->l_arrow = gl_tgetstr(gl, "kl", &tgetstr_buf_ptr);
    gl->r_arrow = gl_tgetstr(gl, "kr", &tgetstr_buf_ptr);
    gl->sound_bell = gl_tgetstr(gl, "bl", &tgetstr_buf_ptr);
    gl->bold = gl_tgetstr(gl, "md", &tgetstr_buf_ptr);
    gl->underline = gl_tgetstr(gl, "us", &tgetstr_buf_ptr);
    gl->standout = gl_tgetstr(gl, "so", &tgetstr_buf_ptr);
    gl->dim = gl_tgetstr(gl, "mh", &tgetstr_buf_ptr);
    gl->reverse = gl_tgetstr(gl, "mr", &tgetstr_buf_ptr);
    gl->blink = gl_tgetstr(gl, "mb", &tgetstr_buf_ptr);
    gl->text_attr_off = gl_tgetstr(gl, "me", &tgetstr_buf_ptr);
  };
#endif
/*
 * Report term being unusable.
 */
  if(bad_term) {
    gl_print_info(gl, "Bad terminal type: \"", term ? term : "(null)",
		  "\". Will assume vt100.", GL_END_INFO);
  };
/*
 * Fill in missing information with ANSI VT100 strings.
 */
  if(!gl->left)
    gl->left = "\b";    /* ^H */
  if(!gl->right)
    gl->right = GL_ESC_STR "[C";
  if(!gl->up)
    gl->up = GL_ESC_STR "[A";
  if(!gl->down)
    gl->down = "\n";
  if(!gl->home)
    gl->home = GL_ESC_STR "[H";
  if(!gl->bol)
    gl->bol = "\r";
  if(!gl->clear_eol)
    gl->clear_eol = GL_ESC_STR "[K";
  if(!gl->clear_eod)
    gl->clear_eod = GL_ESC_STR "[J";
  if(!gl->u_arrow)
    gl->u_arrow = GL_ESC_STR "[A";
  if(!gl->d_arrow)
    gl->d_arrow = GL_ESC_STR "[B";
  if(!gl->l_arrow)
    gl->l_arrow = GL_ESC_STR "[D";
  if(!gl->r_arrow)
    gl->r_arrow = GL_ESC_STR "[C";
  if(!gl->sound_bell)
    gl->sound_bell = "\a";
  if(!gl->bold)
    gl->bold = GL_ESC_STR "[1m";
  if(!gl->underline)
    gl->underline = GL_ESC_STR "[4m";
  if(!gl->standout)
    gl->standout = GL_ESC_STR "[1;7m";
  if(!gl->dim)
    gl->dim = "";  /* Not available */
  if(!gl->reverse)
    gl->reverse = GL_ESC_STR "[7m";
  if(!gl->blink)
    gl->blink = GL_ESC_STR "[5m";
  if(!gl->text_attr_off)
    gl->text_attr_off = GL_ESC_STR "[m";
/*
 * Find out the current terminal size.
 */
  (void) _gl_terminal_size(gl, GL_DEF_NCOLUMN, GL_DEF_NLINE, NULL);
  return 0;
}

#ifdef USE_TERMINFO
/*.......................................................................
 * This is a private function of gl_control_strings() used to look up
 * a termninal capability string from the terminfo database and make
 * a private copy of it.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  name    const char *  The name of the terminfo string to look up.
 * Output:
 *  return  const char *  The local copy of the capability, or NULL
 *                        if not available.
 */
static const char *gl_tigetstr(GetLine *gl, const char *name)
{
  const char *value = tigetstr((char *)name);
  if(!value || value == (char *) -1)
    return NULL;
  return _sg_store_string(gl->capmem, value, 0);
}
#elif defined(USE_TERMCAP)
/*.......................................................................
 * This is a private function of gl_control_strings() used to look up
 * a termninal capability string from the termcap database and make
 * a private copy of it. Note that some emulations of tgetstr(), such
 * as that used by Solaris, ignores the buffer pointer that is past to
 * it, so we can't assume that a private copy has been made that won't
 * be trashed by another call to gl_control_strings() by another
 * GetLine object. So we make what may be a redundant private copy
 * of the string in gl->capmem.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  name    const char *  The name of the terminfo string to look up.
 * Input/Output:
 *  bufptr        char ** On input *bufptr points to the location in
 *                        gl->tgetstr_buf at which to record the
 *                        capability string. On output *bufptr is
 *                        incremented over the stored string.
 * Output:
 *  return  const char *  The local copy of the capability, or NULL
 *                        on error.
 */
static const char *gl_tgetstr(GetLine *gl, const char *name, char **bufptr)
{
  const char *value = tgetstr((char *)name, bufptr);
  if(!value || value == (char *) -1)
    return NULL;
  return _sg_store_string(gl->capmem, value, 0);
}
#endif

/*.......................................................................
 * This is an action function that implements a user interrupt (eg. ^C).
 */
static KT_KEY_FN(gl_user_interrupt)
{
  raise(SIGINT);
  return 1;
}

/*.......................................................................
 * This is an action function that implements the abort signal.
 */
static KT_KEY_FN(gl_abort)
{
  raise(SIGABRT);
  return 1;
}

/*.......................................................................
 * This is an action function that sends a suspend signal (eg. ^Z) to the
 * the parent process.
 */
static KT_KEY_FN(gl_suspend)
{
  raise(SIGTSTP);
  return 0;
}

/*.......................................................................
 * This is an action function that halts output to the terminal.
 */
static KT_KEY_FN(gl_stop_output)
{
  tcflow(gl->output_fd, TCOOFF);
  return 0;
}

/*.......................................................................
 * This is an action function that resumes halted terminal output.
 */
static KT_KEY_FN(gl_start_output)
{
  tcflow(gl->output_fd, TCOON);
  return 0;
}

/*.......................................................................
 * This is an action function that allows the next character to be accepted
 * without any interpretation as a special character.
 */
static KT_KEY_FN(gl_literal_next)
{
  char c;   /* The character to be added to the line */
  int i;
/*
 * Get the character to be inserted literally.
 */
  if(gl_read_terminal(gl, 1, &c))
    return 1;
/*
 * Add the character to the line 'count' times.
 */
  for(i=0; i<count; i++)
    gl_add_char_to_line(gl, c);
  return 0;
}

/*.......................................................................
 * Return the width of a tab character at a given position when
 * displayed at a given position on the terminal. This is needed
 * because the width of tab characters depends on where they are,
 * relative to the preceding tab stops.
 *
 * Input:
 *  gl       GetLine *  The resource object of this library.
 *  term_curpos  int    The destination terminal location of the character.
 * Output:
 *  return       int    The number of terminal charaters needed.
 */
static int gl_displayed_tab_width(GetLine *gl, int term_curpos)
{
  return TAB_WIDTH - ((term_curpos % gl->ncolumn) % TAB_WIDTH);
}

/*.......................................................................
 * Return the number of characters needed to display a given character
 * on the screen. Tab characters require eight spaces, and control
 * characters are represented by a caret followed by the modified
 * character.
 *
 * Input:
 *  gl       GetLine *  The resource object of this library.
 *  c           char    The character to be displayed.
 *  term_curpos  int    The destination terminal location of the character.
 *                      This is needed because the width of tab characters
 *                      depends on where they are, relative to the
 *                      preceding tab stops.
 * Output:
 *  return       int    The number of terminal charaters needed.
 */
static int gl_displayed_char_width(GetLine *gl, char c, int term_curpos)
{
  if(c=='\t')
    return gl_displayed_tab_width(gl, term_curpos);
  if(IS_CTRL_CHAR(c))
    return 2;
  if(!isprint((int)(unsigned char) c))
    return gl_octal_width((int)(unsigned char)c) + 1;
  return 1;
}


/*.......................................................................
 * Work out the length of given string of characters on the terminal.
 *
 * Input:
 *  gl       GetLine *  The resource object of this library.
 *  string      char *  The string to be measured.
 *  nc           int    The number of characters to be measured, or -1
 *                      to measure the whole string.
 *  term_curpos  int    The destination terminal location of the character.
 *                      This is needed because the width of tab characters
 *                      depends on where they are, relative to the
 *                      preceding tab stops.
 * Output:
 *  return       int    The number of displayed characters.
 */
static int gl_displayed_string_width(GetLine *gl, const char *string, int nc,
				     int term_curpos)
{
  int slen = 0;   /* The displayed number of characters */
  int i;
/*
 * How many characters are to be measured?
 */
  if(nc < 0)
    nc = strlen(string);
/*
 * Add up the length of the displayed string.
 */
  for(i=0; i<nc; i++)
    slen += gl_displayed_char_width(gl, string[i], term_curpos + slen);
  return slen;
}

/*.......................................................................
 * Write a string verbatim to the current terminal or output stream.
 *
 * Note that when async-signal safety is required, the 'buffered'
 * argument must be 0, and n must not be -1.
 *
 * Input:
 *  gl         GetLine *  The resource object of the gl_get_line().
 *  buffered       int    If true, used buffered I/O when writing to
 *                        the terminal. Otherwise use async-signal-safe
 *                        unbuffered I/O.
 *  string  const char *  The string to be written (this need not be
 *                        '\0' terminated unless n<0).
 *  n              int    The number of characters to write from the
 *                        prefix of string[], or -1 to request that
 *                        gl_print_raw_string() use strlen() to figure
 *                        out the length.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error.
 */
static int gl_print_raw_string(GetLine *gl, int buffered,
			       const char *string, int n)
{
  GlWriteFn *write_fn = buffered ? gl_write_fn : gl->flush_fn;
/*
 * Only display output when echoing is turned on.
 */
  if(gl->echo) {
    int ndone = 0;   /* The number of characters written so far */
/*
 * When using un-buffered I/O, flush pending output first.
 */
    if(!buffered) {
      if(gl_flush_output(gl))
	return 1;
    };
/*
 * If no length has been provided, measure the length of the string.
 */
    if(n < 0)
      n = strlen(string);
/*
 * Write the string.
 */
    if(write_fn(gl, string + ndone, n-ndone) != n)
      return 1;
  };
  return 0;
}

/*.......................................................................
 * Output a terminal control sequence. When using terminfo,
 * this must be a sequence returned by tgetstr() or tigetstr()
 * respectively.
 *
 * Input:
 *  gl     GetLine *   The resource object of this library.
 *  nline      int     The number of lines affected by the operation,
 *                     or 1 if not relevant.
 *  string    char *   The control sequence to be sent.
 * Output:
 *  return     int     0 - OK.
 *                     1 - Error.
 */
static int gl_print_control_sequence(GetLine *gl, int nline, const char *string)
{
  int waserr = 0;   /* True if an error occurs */
/*
 * Only write characters to the terminal when echoing is enabled.
 */
  if(gl->echo) {
#if defined(USE_TERMINFO) || defined(USE_TERMCAP)
    tputs_gl = gl;
    errno = 0;
    tputs((char *)string, nline, gl_tputs_putchar);
    waserr = errno != 0;
#else
    waserr = gl_print_raw_string(gl, 1, string, -1);
#endif
  };
  return waserr;
}

#if defined(USE_TERMINFO) || defined(USE_TERMCAP)
/*.......................................................................
 * The following callback function is called by tputs() to output a raw
 * control character to the terminal.
 */
static TputsRetType gl_tputs_putchar(TputsArgType c)
{
  char ch = c;
#if TPUTS_RETURNS_VALUE
  return gl_print_raw_string(tputs_gl, 1, &ch, 1);
#else
  (void) gl_print_raw_string(tputs_gl, 1, &ch, 1);
#endif
}
#endif

/*.......................................................................
 * Move the terminal cursor n characters to the left or right.
 *
 * Input:
 *  gl     GetLine *   The resource object of this program.
 *  n          int     number of positions to the right (> 0) or left (< 0).
 * Output:
 *  return     int     0 - OK.
 *                     1 - Error.
 */
static int gl_terminal_move_cursor(GetLine *gl, int n)
{
  int cur_row, cur_col; /* The current terminal row and column index of */
                        /*  the cursor wrt the start of the input line. */
  int new_row, new_col; /* The target terminal row and column index of */
                        /*  the cursor wrt the start of the input line. */
/*
 * Do nothing if the input line isn't currently displayed. In this
 * case, the cursor will be moved to the right place when the line
 * is next redisplayed.
 */
  if(!gl->displayed)
    return 0;
/*
 * How far can we move left?
 */
  if(gl->term_curpos + n < 0)
    n = gl->term_curpos;
/*
 * Break down the current and target cursor locations into rows and columns.
 */
  cur_row = gl->term_curpos / gl->ncolumn;
  cur_col = gl->term_curpos % gl->ncolumn;
  new_row = (gl->term_curpos + n) / gl->ncolumn;
  new_col = (gl->term_curpos + n) % gl->ncolumn;
/*
 * Move down to the next line.
 */
  for(; cur_row < new_row; cur_row++) {
    if(gl_print_control_sequence(gl, 1, gl->down))
      return 1;
  };
/*
 * Move up to the previous line.
 */
  for(; cur_row > new_row; cur_row--) {
    if(gl_print_control_sequence(gl, 1, gl->up))
      return 1;
  };
/*
 * Move to the right within the target line?
 */
  if(cur_col < new_col) {
#ifdef USE_TERMINFO
/*
 * Use a parameterized control sequence if it generates less control
 * characters (guess based on ANSI terminal termcap entry).
 */
    if(gl->right_n != NULL && new_col - cur_col > 1) {
      if(gl_print_control_sequence(gl, 1, tparm((char *)gl->right_n,
           (long)(new_col - cur_col), 0l, 0l, 0l, 0l, 0l, 0l, 0l, 0l)))
	return 1;
    } else
#endif
    {
      for(; cur_col < new_col; cur_col++) {
        if(gl_print_control_sequence(gl, 1, gl->right))
          return 1;
      };
    };
/*
 * Move to the left within the target line?
 */
  } else if(cur_col > new_col) {
#ifdef USE_TERMINFO
/*
 * Use a parameterized control sequence if it generates less control
 * characters (guess based on ANSI terminal termcap entry).
 */
    if(gl->left_n != NULL && cur_col - new_col > 3) {
      if(gl_print_control_sequence(gl, 1, tparm((char *)gl->left_n,
           (long)(cur_col - new_col), 0l, 0l, 0l, 0l, 0l, 0l, 0l, 0l)))
	return 1;
    } else
#endif
    {
      for(; cur_col > new_col; cur_col--) {
        if(gl_print_control_sequence(gl, 1, gl->left))
          return 1;
      };
    };
  }
/*
 * Update the recorded position of the terminal cursor.
 */
  gl->term_curpos += n;
  return 0;
}

/*.......................................................................
 * Write a character to the terminal after expanding tabs and control
 * characters to their multi-character representations.
 *
 * Input:
 *  gl    GetLine *   The resource object of this program.
 *  c        char     The character to be output.
 *  pad      char     Many terminals have the irritating feature that
 *                    when one writes a character in the last column of
 *                    of the terminal, the cursor isn't wrapped to the
 *                    start of the next line until one more character
 *                    is written. Some terminals don't do this, so
 *                    after such a write, we don't know where the
 *                    terminal is unless we output an extra character.
 *                    This argument specifies the character to write.
 *                    If at the end of the input line send '\0' or a
 *                    space, and a space will be written. Otherwise,
 *                    pass the next character in the input line
 *                    following the one being written.
 * Output:
 *  return    int     0 - OK.
 */
static int gl_print_char(GetLine *gl, char c, char pad)
{
  char string[TAB_WIDTH + 4]; /* A work area for composing compound strings */
  int nchar;                  /* The number of terminal characters */
  int i;
/*
 * Check for special characters.
 */
  if(c == '\t') {
/*
 * How many spaces do we need to represent a tab at the current terminal
 * column?
 */
    nchar = gl_displayed_tab_width(gl, gl->term_curpos);
/*
 * Compose the tab string.
 */
    for(i=0; i<nchar; i++)
      string[i] = ' ';
  } else if(IS_CTRL_CHAR(c)) {
    string[0] = '^';
    string[1] = CTRL_TO_CHAR(c);
    nchar = 2;
  } else if(!isprint((int)(unsigned char) c)) {
    snprintf(string, sizeof(string), "\\%o", (int)(unsigned char)c);
    nchar = strlen(string);
  } else {
    string[0] = c;
    nchar = 1;
  };
/*
 * Terminate the string.
 */
  string[nchar] = '\0';
/*
 * Write the string to the terminal.
 */
  if(gl_print_raw_string(gl, 1, string, -1))
    return 1;
/*
 * Except for one exception to be described in a moment, the cursor should
 * now have been positioned after the character that was just output.
 */
  gl->term_curpos += nchar;
/*
 * Keep a record of the number of characters in the terminal version
 * of the input line.
 */
  if(gl->term_curpos > gl->term_len)
    gl->term_len = gl->term_curpos;
/*
 * If the new character ended exactly at the end of a line,
 * most terminals won't move the cursor onto the next line until we
 * have written a character on the next line, so append an extra
 * space then move the cursor back.
 */
  if(gl->term_curpos % gl->ncolumn == 0) {
    int term_curpos = gl->term_curpos;
    if(gl_print_char(gl, pad ? pad : ' ', ' ') ||
       gl_set_term_curpos(gl, term_curpos))
      return 1;
  };
  return 0;
}

/*.......................................................................
 * Write a string to the terminal after expanding tabs and control
 * characters to their multi-character representations.
 *
 * Input:
 *  gl    GetLine *   The resource object of this program.
 *  string   char *   The string to be output.
 *  pad      char     Many terminals have the irritating feature that
 *                    when one writes a character in the last column of
 *                    of the terminal, the cursor isn't wrapped to the
 *                    start of the next line until one more character
 *                    is written. Some terminals don't do this, so
 *                    after such a write, we don't know where the
 *                    terminal is unless we output an extra character.
 *                    This argument specifies the character to write.
 *                    If at the end of the input line send '\0' or a
 *                    space, and a space will be written. Otherwise,
 *                    pass the next character in the input line
 *                    following the one being written.
 * Output:
 *  return    int     0 - OK.
 */
static int gl_print_string(GetLine *gl, const char *string, char pad)
{
  const char *cptr;   /* A pointer into string[] */
  for(cptr=string; *cptr; cptr++) {
    char nextc = cptr[1];
    if(gl_print_char(gl, *cptr, nextc ? nextc : pad))
      return 1;
  };
  return 0;
}

/*.......................................................................
 * Move the terminal cursor position.
 *
 * Input:
 *  gl      GetLine *  The resource object of this library.
 *  term_curpos int    The destination terminal cursor position.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
static int gl_set_term_curpos(GetLine *gl, int term_curpos)
{
  return gl_terminal_move_cursor(gl, term_curpos - gl->term_curpos);
}

/*.......................................................................
 * This is an action function that moves the buffer cursor one character
 * left, and updates the terminal cursor to match.
 */
static KT_KEY_FN(gl_cursor_left)
{
  return gl_place_cursor(gl, gl->buff_curpos - count);
}

/*.......................................................................
 * This is an action function that moves the buffer cursor one character
 * right, and updates the terminal cursor to match.
 */
static KT_KEY_FN(gl_cursor_right)
{
  return gl_place_cursor(gl, gl->buff_curpos + count);
}

/*.......................................................................
 * This is an action function that toggles between overwrite and insert
 * mode.
 */
static KT_KEY_FN(gl_insert_mode)
{
  gl->insert = !gl->insert;
  return 0;
}

/*.......................................................................
 * This is an action function which moves the cursor to the beginning of
 * the line.
 */
static KT_KEY_FN(gl_beginning_of_line)
{
  return gl_place_cursor(gl, 0);
}

/*.......................................................................
 * This is an action function which moves the cursor to the end of
 * the line.
 */
static KT_KEY_FN(gl_end_of_line)
{
  return gl_place_cursor(gl, gl->ntotal);
}

/*.......................................................................
 * This is an action function which deletes the entire contents of the
 * current line.
 */
static KT_KEY_FN(gl_delete_line)
{
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Copy the contents of the line to the cut buffer.
 */
  strlcpy(gl->cutbuf, gl->line, gl->linelen);
/*
 * Clear the buffer.
 */
  gl_truncate_buffer(gl, 0);
/*
 * Move the terminal cursor to just after the prompt.
 */
  if(gl_place_cursor(gl, 0))
    return 1;
/*
 * Clear from the end of the prompt to the end of the terminal.
 */
  if(gl_truncate_display(gl))
    return 1;
  return 0;
}

/*.......................................................................
 * This is an action function which deletes all characters between the
 * current cursor position and the end of the line.
 */
static KT_KEY_FN(gl_kill_line)
{
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Copy the part of the line that is about to be deleted to the cut buffer.
 */
  strlcpy(gl->cutbuf, gl->line + gl->buff_curpos, gl->linelen);
/*
 * Terminate the buffered line at the current cursor position.
 */
  gl_truncate_buffer(gl, gl->buff_curpos);
/*
 * Clear the part of the line that follows the cursor.
 */
  if(gl_truncate_display(gl))
    return 1;
/*
 * Explicitly reset the cursor position to allow vi command mode
 * constraints on its position to be set.
 */
  return gl_place_cursor(gl, gl->buff_curpos);
}

/*.......................................................................
 * This is an action function which deletes all characters between the
 * start of the line and the current cursor position.
 */
static KT_KEY_FN(gl_backward_kill_line)
{
/*
 * How many characters are to be deleted from before the cursor?
 */
  int nc = gl->buff_curpos - gl->insert_curpos;
  if (!nc)
    return 0;
/*
 * Move the cursor to the start of the line, or in vi input mode,
 * the start of the sub-line at which insertion started, and delete
 * up to the old cursor position.
 */
  return gl_place_cursor(gl, gl->insert_curpos) ||
         gl_delete_chars(gl, nc, gl->editor == GL_EMACS_MODE || gl->vi.command);
}

/*.......................................................................
 * This is an action function which moves the cursor forward by a word.
 */
static KT_KEY_FN(gl_forward_word)
{
  return gl_place_cursor(gl, gl_nth_word_end_forward(gl, count) +
			 (gl->editor==GL_EMACS_MODE));
}

/*.......................................................................
 * This is an action function which moves the cursor forward to the start
 * of the next word.
 */
static KT_KEY_FN(gl_forward_to_word)
{
  return gl_place_cursor(gl, gl_nth_word_start_forward(gl, count));
}

/*.......................................................................
 * This is an action function which moves the cursor backward by a word.
 */
static KT_KEY_FN(gl_backward_word)
{
  return gl_place_cursor(gl, gl_nth_word_start_backward(gl, count));
}

/*.......................................................................
 * Delete one or more characters, starting with the one under the cursor.
 *
 * Input:
 *  gl     GetLine *  The resource object of this library.
 *  nc         int    The number of characters to delete.
 *  cut        int    If true, copy the characters to the cut buffer.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */
static int gl_delete_chars(GetLine *gl, int nc, int cut)
{
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * If there are fewer than nc characters following the cursor, limit
 * nc to the number available.
 */
  if(gl->buff_curpos + nc > gl->ntotal)
    nc = gl->ntotal - gl->buff_curpos;
/*
 * Copy the about to be deleted region to the cut buffer.
 */
  if(cut) {
    memcpy(gl->cutbuf, gl->line + gl->buff_curpos, nc);
    gl->cutbuf[nc] = '\0';
  }
/*
 * Nothing to delete?
 */
  if(nc <= 0)
    return 0;
/*
 * In vi overwrite mode, restore any previously overwritten characters
 * from the undo buffer.
 */
  if(gl->editor == GL_VI_MODE && !gl->vi.command && !gl->insert) {
/*
 * How many of the characters being deleted can be restored from the
 * undo buffer?
 */
    int nrestore = gl->buff_curpos + nc <= gl->vi.undo.ntotal ?
      nc : gl->vi.undo.ntotal - gl->buff_curpos;
/*
 * Restore any available characters.
 */
    if(nrestore > 0) {
      gl_buffer_string(gl, gl->vi.undo.line + gl->buff_curpos, nrestore,
		       gl->buff_curpos);
    };
/*
 * If their were insufficient characters in the undo buffer, then this
 * implies that we are deleting from the end of the line, so we need
 * to terminate the line either where the undo buffer ran out, or if
 * we are deleting from beyond the end of the undo buffer, at the current
 * cursor position.
 */
    if(nc != nrestore) {
      gl_truncate_buffer(gl, (gl->vi.undo.ntotal > gl->buff_curpos) ?
			 gl->vi.undo.ntotal : gl->buff_curpos);
    };
  } else {
/*
 * Copy the remaining part of the line back over the deleted characters.
 */
    gl_remove_from_buffer(gl, gl->buff_curpos, nc);
  };
/*
 * Redraw the remaining characters following the cursor.
 */
  if(gl_print_string(gl, gl->line + gl->buff_curpos, '\0'))
    return 1;
/*
 * Clear to the end of the terminal.
 */
  if(gl_truncate_display(gl))
    return 1;
/*
 * Place the cursor at the start of where the deletion was performed.
 */
  return gl_place_cursor(gl, gl->buff_curpos);
}

/*.......................................................................
 * This is an action function which deletes character(s) under the
 * cursor without moving the cursor.
 */
static KT_KEY_FN(gl_forward_delete_char)
{
/*
 * Delete 'count' characters.
 */
  return gl_delete_chars(gl, count, gl->vi.command);
}

/*.......................................................................
 * This is an action function which deletes character(s) under the
 * cursor and moves the cursor back one character.
 */
static KT_KEY_FN(gl_backward_delete_char)
{
/*
 * Restrict the deletion count to the number of characters that
 * precede the insertion point.
 */
  if(count > gl->buff_curpos - gl->insert_curpos)
    count = gl->buff_curpos - gl->insert_curpos;
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
  return gl_cursor_left(gl, count, NULL) ||
    gl_delete_chars(gl, count, gl->vi.command);
}

/*.......................................................................
 * Starting from the cursor position delete to the specified column.
 */
static KT_KEY_FN(gl_delete_to_column)
{
  if (--count >= gl->buff_curpos)
    return gl_forward_delete_char(gl, count - gl->buff_curpos, NULL);
  else
    return gl_backward_delete_char(gl, gl->buff_curpos - count, NULL);
}

/*.......................................................................
 * Starting from the cursor position delete characters to a matching
 * parenthesis.
 */
static KT_KEY_FN(gl_delete_to_parenthesis)
{
  int curpos = gl_index_of_matching_paren(gl);
  if(curpos >= 0) {
    gl_save_for_undo(gl);
    if(curpos >= gl->buff_curpos)
      return gl_forward_delete_char(gl, curpos - gl->buff_curpos + 1, NULL);
    else
      return gl_backward_delete_char(gl, ++gl->buff_curpos - curpos + 1, NULL);
  };
  return 0;
}

/*.......................................................................
 * This is an action function which deletes from the cursor to the end
 * of the word that the cursor is either in or precedes.
 */
static KT_KEY_FN(gl_forward_delete_word)
{
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * In emacs mode delete to the end of the word. In vi mode delete to the
 * start of the net word.
 */
  if(gl->editor == GL_EMACS_MODE) {
    return gl_delete_chars(gl,
		gl_nth_word_end_forward(gl,count) - gl->buff_curpos + 1, 1);
  } else {
    return gl_delete_chars(gl,
		gl_nth_word_start_forward(gl,count) - gl->buff_curpos,
		gl->vi.command);
  };
}

/*.......................................................................
 * This is an action function which deletes the word that precedes the
 * cursor.
 */
static KT_KEY_FN(gl_backward_delete_word)
{
/*
 * Keep a record of the current cursor position.
 */
  int buff_curpos = gl->buff_curpos;
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Move back 'count' words.
 */
  if(gl_backward_word(gl, count, NULL))
    return 1;
/*
 * Delete from the new cursor position to the original one.
 */
  return gl_delete_chars(gl, buff_curpos - gl->buff_curpos,
  			 gl->editor == GL_EMACS_MODE || gl->vi.command);
}

/*.......................................................................
 * Searching in a given direction, delete to the count'th
 * instance of a specified or queried character, in the input line.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 *  count        int    The number of times to search.
 *  c           char    The character to be searched for, or '\0' if
 *                      the character should be read from the user.
 *  forward      int    True if searching forward.
 *  onto         int    True if the search should end on top of the
 *                      character, false if the search should stop
 *                      one character before the character in the
 *                      specified search direction.
 *  change       int    If true, this function is being called upon
 *                      to do a vi change command, in which case the
 *                      user will be left in insert mode after the
 *                      deletion.
 * Output:
 *  return       int    0 - OK.
 *                      1 - Error.
 */
static int gl_delete_find(GetLine *gl, int count, char c, int forward,
			  int onto, int change)
{
/*
 * Search for the character, and abort the deletion if not found.
 */
  int pos = gl_find_char(gl, count, forward, onto, c);
  if(pos < 0)
    return 0;
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Allow the cursor to be at the end of the line if this is a change
 * command.
 */
  if(change)
    gl->vi.command = 0;
/*
 * Delete the appropriate span of characters.
 */
  if(forward) {
    if(gl_delete_chars(gl, pos - gl->buff_curpos + 1, 1))
      return 1;
  } else {
    int buff_curpos = gl->buff_curpos;
    if(gl_place_cursor(gl, pos) ||
       gl_delete_chars(gl, buff_curpos - gl->buff_curpos, 1))
      return 1;
  };
/*
 * If this is a change operation, switch the insert mode.
 */
  if(change && gl_vi_insert(gl, 0, NULL))
    return 1;
  return 0;
}

/*.......................................................................
 * This is an action function which deletes forward from the cursor up to and
 * including a specified character.
 */
static KT_KEY_FN(gl_forward_delete_find)
{
  return gl_delete_find(gl, count, '\0', 1, 1, 0);
}

/*.......................................................................
 * This is an action function which deletes backward from the cursor back to
 * and including a specified character.
 */
static KT_KEY_FN(gl_backward_delete_find)
{
  return gl_delete_find(gl, count, '\0', 0, 1, 0);
}

/*.......................................................................
 * This is an action function which deletes forward from the cursor up to but
 * not including a specified character.
 */
static KT_KEY_FN(gl_forward_delete_to)
{
  return gl_delete_find(gl, count, '\0', 1, 0, 0);
}

/*.......................................................................
 * This is an action function which deletes backward from the cursor back to
 * but not including a specified character.
 */
static KT_KEY_FN(gl_backward_delete_to)
{
  return gl_delete_find(gl, count, '\0', 0, 0, 0);
}

/*.......................................................................
 * This is an action function which deletes to a character specified by a
 * previous search.
 */
static KT_KEY_FN(gl_delete_refind)
{
  return gl_delete_find(gl, count, gl->vi.find_char, gl->vi.find_forward,
			gl->vi.find_onto, 0);
}

/*.......................................................................
 * This is an action function which deletes to a character specified by a
 * previous search, but in the opposite direction.
 */
static KT_KEY_FN(gl_delete_invert_refind)
{
  return gl_delete_find(gl, count, gl->vi.find_char,
			!gl->vi.find_forward, gl->vi.find_onto, 0);
}

/*.......................................................................
 * This is an action function which converts the characters in the word
 * following the cursor to upper case.
 */
static KT_KEY_FN(gl_upcase_word)
{
/*
 * Locate the count'th word ending after the cursor.
 */
  int last = gl_nth_word_end_forward(gl, count);
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Upcase characters from the current cursor position to 'last'.
 */
  while(gl->buff_curpos <= last) {
    char *cptr = gl->line + gl->buff_curpos;
/*
 * Convert the character to upper case?
 */
    if(islower((int)(unsigned char) *cptr))
      gl_buffer_char(gl, toupper((int) *cptr), gl->buff_curpos);
    gl->buff_curpos++;
/*
 * Write the possibly modified character back. Note that for non-modified
 * characters we want to do this as well, so as to advance the cursor.
 */
    if(gl_print_char(gl, *cptr, cptr[1]))
      return 1;
  };
  return gl_place_cursor(gl, gl->buff_curpos);	/* bounds check */
}

/*.......................................................................
 * This is an action function which converts the characters in the word
 * following the cursor to lower case.
 */
static KT_KEY_FN(gl_downcase_word)
{
/*
 * Locate the count'th word ending after the cursor.
 */
  int last = gl_nth_word_end_forward(gl, count);
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Upcase characters from the current cursor position to 'last'.
 */
  while(gl->buff_curpos <= last) {
    char *cptr = gl->line + gl->buff_curpos;
/*
 * Convert the character to upper case?
 */
    if(isupper((int)(unsigned char) *cptr))
      gl_buffer_char(gl, tolower((int) *cptr), gl->buff_curpos);
    gl->buff_curpos++;
/*
 * Write the possibly modified character back. Note that for non-modified
 * characters we want to do this as well, so as to advance the cursor.
 */
    if(gl_print_char(gl, *cptr, cptr[1]))
      return 1;
  };
  return gl_place_cursor(gl, gl->buff_curpos);	/* bounds check */
}

/*.......................................................................
 * This is an action function which converts the first character of the
 * following word to upper case, in order to capitalize the word, and
 * leaves the cursor at the end of the word.
 */
static KT_KEY_FN(gl_capitalize_word)
{
  char *cptr;   /* &gl->line[gl->buff_curpos] */
  int first;    /* True for the first letter of the word */
  int i;
/*
 * Keep a record of the current insert mode and the cursor position.
 */
  int insert = gl->insert;
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * We want to overwrite the modified word.
 */
  gl->insert = 0;
/*
 * Capitalize 'count' words.
 */
  for(i=0; i<count && gl->buff_curpos < gl->ntotal; i++) {
    int pos = gl->buff_curpos;
/*
 * If we are not already within a word, skip to the start of the word.
 */
    for(cptr = gl->line + pos ; pos<gl->ntotal && !gl_is_word_char((int) *cptr);
	pos++, cptr++)
      ;
/*
 * Move the cursor to the new position.
 */
    if(gl_place_cursor(gl, pos))
      return 1;
/*
 * While searching for the end of the word, change lower case letters
 * to upper case.
 */
    for(first=1; gl->buff_curpos<gl->ntotal && gl_is_word_char((int) *cptr);
	gl->buff_curpos++, cptr++) {
/*
 * Convert the character to upper case?
 */
      if(first) {
	if(islower((int)(unsigned char) *cptr))
	  gl_buffer_char(gl, toupper((int) *cptr), cptr - gl->line);
      } else {
	if(isupper((int)(unsigned char) *cptr))
	  gl_buffer_char(gl, tolower((int) *cptr), cptr - gl->line);
      };
      first = 0;
/*
 * Write the possibly modified character back. Note that for non-modified
 * characters we want to do this as well, so as to advance the cursor.
 */
      if(gl_print_char(gl, *cptr, cptr[1]))
	return 1;
    };
  };
/*
 * Restore the insertion mode.
 */
  gl->insert = insert;
  return gl_place_cursor(gl, gl->buff_curpos);	/* bounds check */
}

/*.......................................................................
 * This is an action function which redraws the current line.
 */
static KT_KEY_FN(gl_redisplay)
{
/*
 * Keep a record of the current cursor position.
 */
  int buff_curpos = gl->buff_curpos;
/*
 * Do nothing if there is no line to be redisplayed.
 */
  if(gl->endline)
    return 0;
/*
 * Erase the current input line.
 */
  if(gl_erase_line(gl))
    return 1;
/*
 * Display the current prompt.
 */
  if(gl_display_prompt(gl))
    return 1;
/*
 * Render the part of the line that the user has typed in so far.
 */
  if(gl_print_string(gl, gl->line, '\0'))
    return 1;
/*
 * Restore the cursor position.
 */
  if(gl_place_cursor(gl, buff_curpos))
    return 1;
/*
 * Mark the redisplay operation as having been completed.
 */
  gl->redisplay = 0;
/*
 * Flush the redisplayed line to the terminal.
 */
  return gl_flush_output(gl);
}

/*.......................................................................
 * This is an action function which clears the display and redraws the
 * input line from the home position.
 */
static KT_KEY_FN(gl_clear_screen)
{
/*
 * Home the cursor and clear from there to the end of the display.
 */
  if(gl_print_control_sequence(gl, gl->nline, gl->home) ||
     gl_print_control_sequence(gl, gl->nline, gl->clear_eod))
    return 1;
/*
 * The input line is no longer displayed.
 */
  gl_line_erased(gl);
/*
 * Arrange for the input line to be redisplayed.
 */
  gl_queue_redisplay(gl);
  return 0;
}

/*.......................................................................
 * This is an action function which swaps the character under the cursor
 * with the character to the left of the cursor.
 */
static KT_KEY_FN(gl_transpose_chars)
{
  char from[3];     /* The original string of 2 characters */
  char swap[3];     /* The swapped string of two characters */
/*
 * If we are at the beginning or end of the line, there aren't two
 * characters to swap.
 */
  if(gl->buff_curpos < 1 || gl->buff_curpos >= gl->ntotal)
    return 0;
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Get the original and swapped strings of the two characters.
 */
  from[0] = gl->line[gl->buff_curpos - 1];
  from[1] = gl->line[gl->buff_curpos];
  from[2] = '\0';
  swap[0] = gl->line[gl->buff_curpos];
  swap[1] = gl->line[gl->buff_curpos - 1];
  swap[2] = '\0';
/*
 * Move the cursor to the start of the two characters.
 */
  if(gl_place_cursor(gl, gl->buff_curpos-1))
    return 1;
/*
 * Swap the two characters in the buffer.
 */
  gl_buffer_char(gl, swap[0], gl->buff_curpos);
  gl_buffer_char(gl, swap[1], gl->buff_curpos+1);
/*
 * If the sum of the displayed width of the two characters
 * in their current and final positions is the same, swapping can
 * be done by just overwriting with the two swapped characters.
 */
  if(gl_displayed_string_width(gl, from, -1, gl->term_curpos) ==
     gl_displayed_string_width(gl, swap, -1, gl->term_curpos)) {
    int insert = gl->insert;
    gl->insert = 0;
    if(gl_print_char(gl, swap[0], swap[1]) ||
       gl_print_char(gl, swap[1], gl->line[gl->buff_curpos+2]))
      return 1;
    gl->insert = insert;
/*
 * If the swapped substring has a different displayed size, we need to
 * redraw everything after the first of the characters.
 */
  } else {
    if(gl_print_string(gl, gl->line + gl->buff_curpos, '\0') ||
       gl_truncate_display(gl))
      return 1;
  };
/*
 * Advance the cursor to the character after the swapped pair.
 */
  return gl_place_cursor(gl, gl->buff_curpos + 2);
}

/*.......................................................................
 * This is an action function which sets a mark at the current cursor
 * location.
 */
static KT_KEY_FN(gl_set_mark)
{
  gl->buff_mark = gl->buff_curpos;
  return 0;
}

/*.......................................................................
 * This is an action function which swaps the mark location for the
 * cursor location.
 */
static KT_KEY_FN(gl_exchange_point_and_mark)
{
/*
 * Get the old mark position, and limit to the extent of the input
 * line.
 */
  int old_mark = gl->buff_mark <= gl->ntotal ? gl->buff_mark : gl->ntotal;
/*
 * Make the current cursor position the new mark.
 */
  gl->buff_mark = gl->buff_curpos;
/*
 * Move the cursor to the old mark position.
 */
  return gl_place_cursor(gl, old_mark);
}

/*.......................................................................
 * This is an action function which deletes the characters between the
 * mark and the cursor, recording them in gl->cutbuf for later pasting.
 */
static KT_KEY_FN(gl_kill_region)
{
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Limit the mark to be within the line.
 */
  if(gl->buff_mark > gl->ntotal)
    gl->buff_mark = gl->ntotal;
/*
 * If there are no characters between the cursor and the mark, simply clear
 * the cut buffer.
 */
  if(gl->buff_mark == gl->buff_curpos) {
    gl->cutbuf[0] = '\0';
    return 0;
  };
/*
 * If the mark is before the cursor, swap the cursor and the mark.
 */
  if(gl->buff_mark < gl->buff_curpos && gl_exchange_point_and_mark(gl,1,NULL))
    return 1;
/*
 * Delete the characters.
 */
  if(gl_delete_chars(gl, gl->buff_mark - gl->buff_curpos, 1))
    return 1;
/*
 * Make the mark the same as the cursor position.
 */
  gl->buff_mark = gl->buff_curpos;
  return 0;
}

/*.......................................................................
 * This is an action function which records the characters between the
 * mark and the cursor, in gl->cutbuf for later pasting.
 */
static KT_KEY_FN(gl_copy_region_as_kill)
{
  int ca, cb;  /* The indexes of the first and last characters in the region */
  int mark;    /* The position of the mark */
/*
 * Get the position of the mark, limiting it to lie within the line.
 */
  mark = gl->buff_mark > gl->ntotal ? gl->ntotal : gl->buff_mark;
/*
 * If there are no characters between the cursor and the mark, clear
 * the cut buffer.
 */
  if(mark == gl->buff_curpos) {
    gl->cutbuf[0] = '\0';
    return 0;
  };
/*
 * Get the line indexes of the first and last characters in the region.
 */
  if(mark < gl->buff_curpos) {
    ca = mark;
    cb = gl->buff_curpos - 1;
  } else {
    ca = gl->buff_curpos;
    cb = mark - 1;
  };
/*
 * Copy the region to the cut buffer.
 */
  memcpy(gl->cutbuf, gl->line + ca, cb + 1 - ca);
  gl->cutbuf[cb + 1 - ca] = '\0';
  return 0;
}

/*.......................................................................
 * This is an action function which inserts the contents of the cut
 * buffer at the current cursor location.
 */
static KT_KEY_FN(gl_yank)
{
  int i;
/*
 * Set the mark at the current location.
 */
  gl->buff_mark = gl->buff_curpos;
/*
 * Do nothing else if the cut buffer is empty.
 */
  if(gl->cutbuf[0] == '\0')
    return gl_ring_bell(gl, 1, NULL);
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Insert the string count times.
 */
  for(i=0; i<count; i++) {
    if(gl_add_string_to_line(gl, gl->cutbuf))
      return 1;
  };
/*
 * gl_add_string_to_line() leaves the cursor after the last character that
 * was pasted, whereas vi leaves the cursor over the last character pasted.
 */
  if(gl->editor == GL_VI_MODE && gl_cursor_left(gl, 1, NULL))
    return 1;
  return 0;
}

/*.......................................................................
 * This is an action function which inserts the contents of the cut
 * buffer one character beyond the current cursor location.
 */
static KT_KEY_FN(gl_append_yank)
{
  int was_command = gl->vi.command;
  int i;
/*
 * If the cut buffer is empty, ring the terminal bell.
 */
  if(gl->cutbuf[0] == '\0')
    return gl_ring_bell(gl, 1, NULL);
/*
 * Set the mark at the current location + 1.
 */
  gl->buff_mark = gl->buff_curpos + 1;
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Arrange to paste the text in insert mode after the current character.
 */
  if(gl_vi_append(gl, 0, NULL))
    return 1;
/*
 * Insert the string count times.
 */
  for(i=0; i<count; i++) {
    if(gl_add_string_to_line(gl, gl->cutbuf))
      return 1;
  };
/*
 * Switch back to command mode if necessary.
 */
  if(was_command)
    gl_vi_command_mode(gl);
  return 0;
}

/*.......................................................................
 * Attempt to ask the terminal for its current size. On systems that
 * don't support the TIOCWINSZ ioctl() for querying the terminal size,
 * the current values of gl->ncolumn and gl->nrow are returned.
 *
 * Input:
 *  gl     GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  ncolumn    int *  The number of columns will be assigned to *ncolumn.
 *  nline      int *  The number of lines will be assigned to *nline.
 */
static void gl_query_size(GetLine *gl, int *ncolumn, int *nline)
{
#ifdef TIOCGWINSZ
/*
 * Query the new terminal window size. Ignore invalid responses.
 */
  struct winsize size;
  if(ioctl(gl->output_fd, TIOCGWINSZ, &size) == 0 &&
     size.ws_row > 0 && size.ws_col > 0) {
    *ncolumn = size.ws_col;
    *nline = size.ws_row;
    return;
  };
#endif
/*
 * Return the existing values.
 */
  *ncolumn = gl->ncolumn;
  *nline = gl->nline;
  return;
}

/*.......................................................................
 * Query the size of the terminal, and if it has changed, redraw the
 * current input line accordingly.
 *
 * Input:
 *  gl     GetLine *  The resource object of gl_get_line().
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */
static int _gl_update_size(GetLine *gl)
{
  int ncolumn, nline;    /* The new size of the terminal */
/*
 * Query the new terminal window size.
 */
  gl_query_size(gl, &ncolumn, &nline);
/*
 * Update gl and the displayed line to fit the new dimensions.
 */
  return gl_handle_tty_resize(gl, ncolumn, nline);
}

/*.......................................................................
 * Redraw the current input line to account for a change in the terminal
 * size. Also install the new size in gl.
 *
 * Input:
 *  gl     GetLine *  The resource object of gl_get_line().
 *  ncolumn    int    The new number of columns.
 *  nline      int    The new number of lines.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */
static int gl_handle_tty_resize(GetLine *gl, int ncolumn, int nline)
{
/*
 * If the input device isn't a terminal, just record the new size.
 */
  if(!gl->is_term) {
    gl->nline = nline;
    gl->ncolumn = ncolumn;
/*
 * Has the size actually changed?
 */
  } else if(ncolumn != gl->ncolumn || nline != gl->nline) {
/*
 * If we are currently editing a line, erase it.
 */
    if(gl_erase_line(gl))
      return 1;
/*
 * Update the recorded window size.
 */
    gl->nline = nline;
    gl->ncolumn = ncolumn;
/*
 * Arrange for the input line to be redrawn before the next character
 * is read from the terminal.
 */
    gl_queue_redisplay(gl);
  };
  return 0;
}

/*.......................................................................
 * This is the action function that recalls the previous line in the
 * history buffer.
 */
static KT_KEY_FN(gl_up_history)
{
/*
 * In vi mode, switch to command mode, since the user is very
 * likely to want to move around newly recalled lines.
 */
  gl_vi_command_mode(gl);
/*
 * Forget any previous recall session.
 */
  gl->preload_id = 0;
/*
 * Record the key sequence number of this search action.
 */
  gl->last_search = gl->keyseq_count;
/*
 * We don't want a search prefix for this function.
 */
  if(_glh_search_prefix(gl->glh, gl->line, 0)) {
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
    return 1;
  };
/*
 * Recall the count'th next older line in the history list. If the first one
 * fails we can return since nothing has changed, otherwise we must continue
 * and update the line state.
 */
  if(_glh_find_backwards(gl->glh, gl->line, gl->linelen+1) == NULL)
    return 0;
  while(--count && _glh_find_backwards(gl->glh, gl->line, gl->linelen+1))
    ;
/*
 * Accomodate the new contents of gl->line[].
 */
  gl_update_buffer(gl);
/*
 * Arrange to have the cursor placed at the end of the new line.
 */
  gl->buff_curpos = gl->ntotal;
/*
 * Erase and display the new line.
 */
  gl_queue_redisplay(gl);
  return 0;
}

/*.......................................................................
 * This is the action function that recalls the next line in the
 * history buffer.
 */
static KT_KEY_FN(gl_down_history)
{
/*
 * In vi mode, switch to command mode, since the user is very
 * likely to want to move around newly recalled lines.
 */
  gl_vi_command_mode(gl);
/*
 * Record the key sequence number of this search action.
 */
  gl->last_search = gl->keyseq_count;
/*
 * If no search is currently in progress continue a previous recall
 * session from a previous entered line if possible.
 */
  if(_glh_line_id(gl->glh, 0) == 0 && gl->preload_id) {
    _glh_recall_line(gl->glh, gl->preload_id, gl->line, gl->linelen+1);
    gl->preload_id = 0;
  } else {
/*
 * We don't want a search prefix for this function.
 */
    if(_glh_search_prefix(gl->glh, gl->line, 0)) {
      _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
      return 1;
    };
/*
 * Recall the count'th next newer line in the history list. If the first one
 * fails we can return since nothing has changed otherwise we must continue
 * and update the line state.
 */
    if(_glh_find_forwards(gl->glh, gl->line, gl->linelen+1) == NULL)
      return 0;
    while(--count && _glh_find_forwards(gl->glh, gl->line, gl->linelen+1))
      ;
  };
/*
 * Accomodate the new contents of gl->line[].
 */
  gl_update_buffer(gl);
/*
 * Arrange to have the cursor placed at the end of the new line.
 */
  gl->buff_curpos = gl->ntotal;
/*
 * Erase and display the new line.
 */
  gl_queue_redisplay(gl);
  return 0;
}

/*.......................................................................
 * This is the action function that recalls the previous line in the
 * history buffer whos prefix matches the characters that currently
 * precede the cursor. By setting count=-1, this can be used internally
 * to force searching for the prefix used in the last search.
 */
static KT_KEY_FN(gl_history_search_backward)
{
/*
 * In vi mode, switch to command mode, since the user is very
 * likely to want to move around newly recalled lines.
 */
  gl_vi_command_mode(gl);
/*
 * Forget any previous recall session.
 */
  gl->preload_id = 0;
/*
 * Record the key sequence number of this search action.
 */
  gl->last_search = gl->keyseq_count;
/*
 * If a prefix search isn't already in progress, replace the search
 * prefix to the string that precedes the cursor. In vi command mode
 * include the character that is under the cursor in the string.  If
 * count<0 keep the previous search prefix regardless, so as to force
 * a repeat search even if the last command wasn't a history command.
 */
  if(count >= 0 && !_glh_search_active(gl->glh) &&
     _glh_search_prefix(gl->glh, gl->line, gl->buff_curpos +
			(gl->editor==GL_VI_MODE && gl->ntotal>0))) {
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
    return 1;
  };
/*
 * Search backwards for a match to the part of the line which precedes the
 * cursor.
 */
  if(_glh_find_backwards(gl->glh, gl->line, gl->linelen+1) == NULL)
    return 0;
/*
 * Accomodate the new contents of gl->line[].
 */
  gl_update_buffer(gl);
/*
 * Arrange to have the cursor placed at the end of the new line.
 */
  gl->buff_curpos = gl->ntotal;
/*
 * Erase and display the new line.
 */
  gl_queue_redisplay(gl);
  return 0;
}

/*.......................................................................
 * This is the action function that recalls the previous line in the
 * history buffer who's prefix matches that specified in an earlier call
 * to gl_history_search_backward() or gl_history_search_forward().
 */
static KT_KEY_FN(gl_history_re_search_backward)
{
  return gl_history_search_backward(gl, -1, NULL);
}

/*.......................................................................
 * This is the action function that recalls the next line in the
 * history buffer who's prefix matches that specified in the earlier call
 * to gl_history_search_backward) which started the history search.
 * By setting count=-1, this can be used internally to force searching
 * for the prefix used in the last search.
 */
static KT_KEY_FN(gl_history_search_forward)
{
/*
 * In vi mode, switch to command mode, since the user is very
 * likely to want to move around newly recalled lines.
 */
  gl_vi_command_mode(gl);
/*
 * Record the key sequence number of this search action.
 */
  gl->last_search = gl->keyseq_count;
/*
 * If a prefix search isn't already in progress, replace the search
 * prefix to the string that precedes the cursor. In vi command mode
 * include the character that is under the cursor in the string.  If
 * count<0 keep the previous search prefix regardless, so as to force
 * a repeat search even if the last command wasn't a history command.
 */
  if(count >= 0 && !_glh_search_active(gl->glh) &&
     _glh_search_prefix(gl->glh, gl->line, gl->buff_curpos +
			(gl->editor==GL_VI_MODE && gl->ntotal>0))) {
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
    return 1;
  };
/*
 * Search forwards for the next matching line.
 */
  if(_glh_find_forwards(gl->glh, gl->line, gl->linelen+1) == NULL)
    return 0;
/*
 * Accomodate the new contents of gl->line[].
 */
  gl_update_buffer(gl);
/*
 * Arrange for the cursor to be placed at the end of the new line.
 */
  gl->buff_curpos = gl->ntotal;
/*
 * Erase and display the new line.
 */
  gl_queue_redisplay(gl);
  return 0;
}

/*.......................................................................
 * This is the action function that recalls the next line in the
 * history buffer who's prefix matches that specified in an earlier call
 * to gl_history_search_backward() or gl_history_search_forward().
 */
static KT_KEY_FN(gl_history_re_search_forward)
{
  return gl_history_search_forward(gl, -1, NULL);
}

#ifdef HIDE_FILE_SYSTEM
/*.......................................................................
 * The following function is used as the default completion handler when
 * the filesystem is to be hidden. It simply reports no completions.
 */
static CPL_MATCH_FN(gl_no_completions)
{
  return 0;
}
#endif

/*.......................................................................
 * This is the tab completion function that completes the filename that
 * precedes the cursor position. Its callback data argument must be a
 * pointer to a GlCplCallback containing the completion callback function
 * and its callback data, or NULL to use the builtin filename completer.
 */
static KT_KEY_FN(gl_complete_word)
{
  CplMatches *matches;    /* The possible completions */
  int suffix_len;         /* The length of the completion extension */
  int cont_len;           /* The length of any continuation suffix */
  int nextra;             /* The number of characters being added to the */
                          /*  total length of the line. */
  int buff_pos;           /* The buffer index at which the completion is */
                          /*  to be inserted. */
  int waserr = 0;         /* True after errors */
/*
 * Get the container of the completion callback and its callback data.
 */
  GlCplCallback *cb = data ? (GlCplCallback *) data : &gl->cplfn;
/*
 * In vi command mode, switch to append mode so that the character under
 * the cursor is included in the completion (otherwise people can't
 * complete at the end of the line).
 */
  if(gl->vi.command && gl_vi_append(gl, 0, NULL))
    return 1;
/*
 * Get the cursor position at which the completion is to be inserted.
 */
  buff_pos = gl->buff_curpos;
/*
 * Perform the completion.
 */
  matches = cpl_complete_word(gl->cpl, gl->line, gl->buff_curpos, cb->data,
			      cb->fn);
/*
 * No matching completions?
 */
  if(!matches) {
    waserr = gl_print_info(gl, cpl_last_error(gl->cpl), GL_END_INFO);
/*
 * Are there any completions?
 */
  } else if(matches->nmatch >= 1) {
/*
 * If there any ambiguous matches, report them, starting on a new line.
 */
    if(matches->nmatch > 1 && gl->echo) {
      if(_gl_normal_io(gl) ||
	 _cpl_output_completions(matches, gl_write_fn, gl, gl->ncolumn))
	waserr = 1;
    };
/*
 * Get the length of the suffix and any continuation suffix to add to it.
 */
    suffix_len = strlen(matches->suffix);
    cont_len = strlen(matches->cont_suffix);
/*
 * If there is an unambiguous match, and the continuation suffix ends in
 * a newline, strip that newline and arrange to have getline return
 * after this action function returns.
 */
    if(matches->nmatch==1 && cont_len > 0 &&
       matches->cont_suffix[cont_len - 1] == '\n') {
      cont_len--;
      if(gl_newline(gl, 1, NULL))
	waserr = 1;
    };
/*
 * Work out the number of characters that are to be added.
 */
    nextra = suffix_len + cont_len;
/*
 * Is there anything to be added?
 */
    if(!waserr && nextra) {
/*
 * Will there be space for the expansion in the line buffer?
 */
      if(gl->ntotal + nextra < gl->linelen) {
/*
 * Make room to insert the filename extension.
 */
	gl_make_gap_in_buffer(gl, gl->buff_curpos, nextra);
/*
 * Insert the filename extension.
 */
	gl_buffer_string(gl, matches->suffix, suffix_len, gl->buff_curpos);
/*
 * Add the terminating characters.
 */
	gl_buffer_string(gl, matches->cont_suffix, cont_len,
			 gl->buff_curpos + suffix_len);
/*
 * Place the cursor position at the end of the completion.
 */
	gl->buff_curpos += nextra;
/*
 * If we don't have to redisplay the whole line, redisplay the part
 * of the line which follows the original cursor position, and place
 * the cursor at the end of the completion.
 */
	if(gl->displayed) {
	  if(gl_truncate_display(gl) ||
	     gl_print_string(gl, gl->line + buff_pos, '\0') ||
	     gl_place_cursor(gl, gl->buff_curpos))
	    waserr = 1;
	};
      } else {
	(void) gl_print_info(gl,
			     "Insufficient room in line for file completion.",
			     GL_END_INFO);
	waserr = 1;
      };
    };
  };
/*
 * If any output had to be written to the terminal, then editing will
 * have been suspended, make sure that we are back in raw line editing
 * mode before returning.
 */
  if(_gl_raw_io(gl, 1))
    waserr = 1;
  return 0;
}

#ifndef HIDE_FILE_SYSTEM
/*.......................................................................
 * This is the function that expands the filename that precedes the
 * cursor position. It expands ~user/ expressions, $envvar expressions,
 * and wildcards.
 */
static KT_KEY_FN(gl_expand_filename)
{
  char *start_path;      /* The pointer to the start of the pathname in */
                         /*  gl->line[]. */
  FileExpansion *result; /* The results of the filename expansion */
  int pathlen;           /* The length of the pathname being expanded */
  int length;            /* The number of characters needed to display the */
                         /*  expanded files. */
  int nextra;            /* The number of characters to be added */
  int i,j;
/*
 * In vi command mode, switch to append mode so that the character under
 * the cursor is included in the completion (otherwise people can't
 * complete at the end of the line).
 */
  if(gl->vi.command && gl_vi_append(gl, 0, NULL))
    return 1;
/*
 * Locate the start of the filename that precedes the cursor position.
 */
  start_path = _pu_start_of_path(gl->line, gl->buff_curpos);
  if(!start_path)
    return 1;
/*
 * Get the length of the string that is to be expanded.
 */
  pathlen = gl->buff_curpos - (start_path - gl->line);
/*
 * Attempt to expand it.
 */
  result = ef_expand_file(gl->ef, start_path, pathlen);
/*
 * If there was an error, report the error on a new line.
 */
  if(!result)
    return gl_print_info(gl, ef_last_error(gl->ef), GL_END_INFO);
/*
 * If no files matched, report this as well.
 */
  if(result->nfile == 0 || !result->exists)
    return gl_print_info(gl, "No files match.", GL_END_INFO);
/*
 * If in vi command mode, preserve the current line for potential use by
 * vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Work out how much space we will need to display all of the matching
 * filenames, taking account of the space that we need to place between
 * them, and the number of additional '\' characters needed to escape
 * spaces, tabs and backslash characters in the individual filenames.
 */
  length = 0;
  for(i=0; i<result->nfile; i++) {
    char *file = result->files[i];
    while(*file) {
      int c = *file++;
      switch(c) {
      case ' ': case '\t': case '\\': case '*': case '?': case '[':
	length++;  /* Count extra backslash characters */
      };
      length++;    /* Count the character itself */
    };
    length++;      /* Count the space that follows each filename */
  };
/*
 * Work out the number of characters that are to be added.
 */
  nextra = length - pathlen;
/*
 * Will there be space for the expansion in the line buffer?
 */
  if(gl->ntotal + nextra >= gl->linelen) {
    return gl_print_info(gl, "Insufficient room in line for file expansion.",
			 GL_END_INFO);
  } else {
/*
 * Do we need to move the part of the line that followed the unexpanded
 * filename?
 */
    if(nextra > 0) {
      gl_make_gap_in_buffer(gl, gl->buff_curpos, nextra);
    } else if(nextra < 0) {
      gl->buff_curpos += nextra;
      gl_remove_from_buffer(gl, gl->buff_curpos, -nextra);
    };
/*
 * Insert the filenames, separated by spaces, and with internal spaces,
 * tabs and backslashes escaped with backslashes.
 */
    for(i=0,j=start_path - gl->line; i<result->nfile; i++) {
      char *file = result->files[i];
      while(*file) {
	int c = *file++;
	switch(c) {
	case ' ': case '\t': case '\\': case '*': case '?': case '[':
	  gl_buffer_char(gl, '\\', j++);
	};
	gl_buffer_char(gl, c, j++);
      };
      gl_buffer_char(gl, ' ', j++);
    };
  };
/*
 * Redisplay the part of the line which follows the start of
 * the original filename.
 */
  if(gl_place_cursor(gl, start_path - gl->line) ||
     gl_truncate_display(gl) ||
     gl_print_string(gl, start_path, start_path[length]))
    return 1;
/*
 * Move the cursor to the end of the expansion.
 */
  return gl_place_cursor(gl, (start_path - gl->line) + length);
}
#endif

#ifndef HIDE_FILE_SYSTEM
/*.......................................................................
 * This is the action function that lists glob expansions of the
 * filename that precedes the cursor position. It expands ~user/
 * expressions, $envvar expressions, and wildcards.
 */
static KT_KEY_FN(gl_list_glob)
{
  char *start_path;      /* The pointer to the start of the pathname in */
                         /*  gl->line[]. */
  FileExpansion *result; /* The results of the filename expansion */
  int pathlen;           /* The length of the pathname being expanded */
/*
 * Locate the start of the filename that precedes the cursor position.
 */
  start_path = _pu_start_of_path(gl->line, gl->buff_curpos);
  if(!start_path)
    return 1;
/*
 * Get the length of the string that is to be expanded.
 */
  pathlen = gl->buff_curpos - (start_path - gl->line);
/*
 * Attempt to expand it.
 */
  result = ef_expand_file(gl->ef, start_path, pathlen);
/*
 * If there was an error, report it.
 */
  if(!result) {
    return gl_print_info(gl,  ef_last_error(gl->ef), GL_END_INFO);
/*
 * If no files matched, report this as well.
 */
  } else if(result->nfile == 0 || !result->exists) {
    return gl_print_info(gl, "No files match.", GL_END_INFO);
/*
 * List the matching expansions.
 */
  } else if(gl->echo) {
    if(gl_start_newline(gl, 1) ||
       _ef_output_expansions(result, gl_write_fn, gl, gl->ncolumn))
      return 1;
    gl_queue_redisplay(gl);
  };
  return 0;
}
#endif

/*.......................................................................
 * Return non-zero if a character should be considered a part of a word.
 *
 * Input:
 *  c       int  The character to be tested.
 * Output:
 *  return  int  True if the character should be considered part of a word.
 */
static int gl_is_word_char(int c)
{
  return isalnum((int)(unsigned char)c) || strchr(GL_WORD_CHARS, c) != NULL;
}

/*.......................................................................
 * Override the builtin file-completion callback that is bound to the
 * "complete_word" action function.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  data             void *  This is passed to match_fn() whenever it is
 *                           called. It could, for example, point to a
 *                           symbol table where match_fn() could look
 *                           for possible completions.
 *  match_fn   CplMatchFn *  The function that will identify the prefix
 *                           to be completed from the input line, and
 *                           report matching symbols.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_customize_completion(GetLine *gl, void *data, CplMatchFn *match_fn)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
/*
 * Check the arguments.
 */
  if(!gl || !match_fn) {
    if(gl)
      _err_record_msg(gl->err, "NULL argument", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Temporarily block all signals.
 */
  gl_mask_signals(gl, &oldset);
/*
 * Record the new completion function and its callback data.
 */
  gl->cplfn.fn = match_fn;
  gl->cplfn.data = data;
/*
 * Restore the process signal mask before returning.
 */
  gl_unmask_signals(gl, &oldset);
  return 0;
}

/*.......................................................................
 * Change the terminal (or stream) that getline interacts with.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  input_fp         FILE *  The stdio stream to read from.
 *  output_fp        FILE *  The stdio stream to write to.
 *  term             char *  The terminal type. This can be NULL if
 *                           either or both of input_fp and output_fp don't
 *                           refer to a terminal. Otherwise it should refer
 *                           to an entry in the terminal information database.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_change_terminal(GetLine *gl, FILE *input_fp, FILE *output_fp,
		       const char *term)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_change_terminal() */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Execute the private body of the function while signals are blocked.
 */
  status = _gl_change_terminal(gl, input_fp, output_fp, term);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the gl_change_terminal() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_change_terminal(GetLine *gl, FILE *input_fp, FILE *output_fp,
			       const char *term)
{
  int is_term = 0;   /* True if both input_fd and output_fd are associated */
                     /*  with a terminal. */
/*
 * Require that input_fp and output_fp both be valid.
 */
  if(!input_fp || !output_fp) {
    gl_print_info(gl, "Can't change terminal. Bad input/output stream(s).",
		  GL_END_INFO);
    return 1;
  };
/*
 * Are we displacing an existing terminal (as opposed to setting the
 * initial terminal)?
 */
  if(gl->input_fd >= 0) {
/*
 * Make sure to leave the previous terminal in a usable state.
 */
    if(_gl_normal_io(gl))
      return 1;
/*
 * Remove the displaced terminal from the list of fds to watch.
 */
#ifdef HAVE_SELECT
    FD_CLR(gl->input_fd, &gl->rfds);
#endif
  };
/*
 * Record the file descriptors and streams.
 */
  gl->input_fp = input_fp;
  gl->input_fd = fileno(input_fp);
  gl->output_fp = output_fp;
  gl->output_fd = fileno(output_fp);
/*
 * If needed, expand the record of the maximum file-descriptor that might
 * need to be monitored with select().
 */
#ifdef HAVE_SELECT
  if(gl->input_fd > gl->max_fd)
    gl->max_fd = gl->input_fd;
#endif
/*
 * Disable terminal interaction until we have enough info to interact
 * with the terminal.
 */
  gl->is_term = 0;
/*
 * For terminal editing, we need both output_fd and input_fd to refer to
 * a terminal. While we can't verify that they both point to the same
 * terminal, we can verify that they point to terminals.
 */
  is_term = isatty(gl->input_fd) && isatty(gl->output_fd);
/*
 * If we are interacting with a terminal and no terminal type has been
 * specified, treat it as a generic ANSI terminal.
 */
  if(is_term && !term)
    term = "ansi";
/*
 * Make a copy of the terminal type string.
 */
  if(term != gl->term) {
/*
 * Delete any old terminal type string.
 */
    if(gl->term) {
      free(gl->term);
      gl->term = NULL;
    };
/*
 * Make a copy of the new terminal-type string, if any.
 */
    if(term) {
      size_t termsz = strlen(term)+1;

      gl->term = (char *) malloc(termsz);
      if(gl->term)
	strlcpy(gl->term, term, termsz);
    };
  };
/*
 * Clear any terminal-specific key bindings that were taken from the
 * settings of the last terminal.
 */
  _kt_clear_bindings(gl->bindings, KTB_TERM);
/*
 * If we have a terminal install new bindings for it.
 */
  if(is_term) {
/*
 * Get the current settings of the terminal.
 */
    if(tcgetattr(gl->input_fd, &gl->oldattr)) {
      _err_record_msg(gl->err, "tcgetattr error", END_ERR_MSG);
      return 1;
    };
/*
 * If we don't set this now, gl_control_strings() won't know
 * that it is talking to a terminal.
 */
    gl->is_term = 1;
/*
 * Lookup the terminal control string and size information.
 */
    if(gl_control_strings(gl, term)) {
      gl->is_term = 0;
      return 1;
    };
/*
 * Bind terminal-specific keys.
 */
    if(gl_bind_terminal_keys(gl))
      return 1;
  };
/*
 * Assume that the caller has given us a terminal in a sane state.
 */
  gl->io_mode = GL_NORMAL_MODE;
/*
 * Switch into the currently configured I/O mode.
 */
  if(_gl_io_mode(gl, gl->io_mode))
    return 1;
  return 0;
}

/*.......................................................................
 * Set up terminal-specific key bindings.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
static int gl_bind_terminal_keys(GetLine *gl)
{
/*
 * Install key-bindings for the special terminal characters.
 */
  if(gl_bind_control_char(gl, KTB_TERM, gl->oldattr.c_cc[VINTR],
			  "user-interrupt") ||
     gl_bind_control_char(gl, KTB_TERM, gl->oldattr.c_cc[VQUIT], "abort") ||
     gl_bind_control_char(gl, KTB_TERM, gl->oldattr.c_cc[VSUSP], "suspend"))
    return 1;
/*
 * In vi-mode, arrange for the above characters to be seen in command
 * mode.
 */
  if(gl->editor == GL_VI_MODE) {
    if(gl_bind_control_char(gl, KTB_TERM, MAKE_META(gl->oldattr.c_cc[VINTR]),
			    "user-interrupt") ||
       gl_bind_control_char(gl, KTB_TERM, MAKE_META(gl->oldattr.c_cc[VQUIT]),
			    "abort") ||
       gl_bind_control_char(gl, KTB_TERM, MAKE_META(gl->oldattr.c_cc[VSUSP]),
			    "suspend"))
      return 1;
  };
/*
 * Non-universal special keys.
 */
#ifdef VLNEXT
  if(gl_bind_control_char(gl, KTB_TERM, gl->oldattr.c_cc[VLNEXT],
			  "literal-next"))
    return 1;
#else
  if(_kt_set_keybinding(gl->bindings, KTB_TERM, "^V", "literal-next")) {
    _err_record_msg(gl->err, _kt_last_error(gl->bindings), END_ERR_MSG);
    return 1;
  };
#endif
/*
 * Bind action functions to the terminal-specific arrow keys
 * looked up by gl_control_strings().
 */
  if(_gl_bind_arrow_keys(gl))
    return 1;
  return 0;
}

/*.......................................................................
 * This function is normally bound to control-D. When it is invoked within
 * a line it deletes the character which follows the cursor. When invoked
 * at the end of the line it lists possible file completions, and when
 * invoked on an empty line it causes gl_get_line() to return EOF. This
 * function emulates the one that is normally bound to control-D by tcsh.
 */
static KT_KEY_FN(gl_del_char_or_list_or_eof)
{
/*
 * If we have an empty line arrange to return EOF.
 */
  if(gl->ntotal < 1) {
    gl_record_status(gl, GLR_EOF, 0);
    return 1;
/*
 * If we are at the end of the line list possible completions.
 */
  } else if(gl->buff_curpos >= gl->ntotal) {
    return gl_list_completions(gl, 1, NULL);
/*
 * Within the line delete the character that follows the cursor.
 */
  } else {
/*
 * If in vi command mode, first preserve the current line for potential use
 * by vi-undo.
 */
    gl_save_for_undo(gl);
/*
 * Delete 'count' characters.
 */
    return gl_forward_delete_char(gl, count, NULL);
  };
}

/*.......................................................................
 * This function is normally bound to control-D in vi mode. When it is
 * invoked within a line it lists possible file completions, and when
 * invoked on an empty line it causes gl_get_line() to return EOF. This
 * function emulates the one that is normally bound to control-D by tcsh.
 */
static KT_KEY_FN(gl_list_or_eof)
{
/*
 * If we have an empty line arrange to return EOF.
 */
  if(gl->ntotal < 1) {
    gl_record_status(gl, GLR_EOF, 0);
    return 1;
/*
 * Otherwise list possible completions.
 */
  } else {
    return gl_list_completions(gl, 1, NULL);
  };
}

/*.......................................................................
 * List possible completions of the word that precedes the cursor. The
 * callback data argument must either be NULL to select the default
 * file completion callback, or be a GlCplCallback object containing the
 * completion callback function to call.
 */
static KT_KEY_FN(gl_list_completions)
{
  int waserr = 0;   /* True after errors */
/*
 * Get the container of the completion callback and its callback data.
 */
  GlCplCallback *cb = data ? (GlCplCallback *) data : &gl->cplfn;
/*
 * Get the list of possible completions.
 */
  CplMatches *matches = cpl_complete_word(gl->cpl, gl->line, gl->buff_curpos,
					  cb->data, cb->fn);
/*
 * No matching completions?
 */
  if(!matches) {
    waserr = gl_print_info(gl, cpl_last_error(gl->cpl), GL_END_INFO);
/*
 * List the matches.
 */
  } else if(matches->nmatch > 0 && gl->echo) {
    if(_gl_normal_io(gl) ||
       _cpl_output_completions(matches, gl_write_fn, gl, gl->ncolumn))
      waserr = 1;
  };
/*
 * If any output had to be written to the terminal, then editing will
 * have been suspended, make sure that we are back in raw line editing
 * mode before returning.
 */
  if(_gl_raw_io(gl, 1))
    waserr = 1;
  return waserr;
}

/*.......................................................................
 * Where the user has used the symbolic arrow-key names to specify
 * arrow key bindings, bind the specified action functions to the default
 * and terminal specific arrow key sequences.
 *
 * Input:
 *  gl     GetLine *   The getline resource object.
 * Output:
 *  return     int     0 - OK.
 *                     1 - Error.
 */
static int _gl_bind_arrow_keys(GetLine *gl)
{
/*
 * Process each of the arrow keys.
 */
  if(_gl_rebind_arrow_key(gl, "up", gl->u_arrow, "^[[A", "^[OA") ||
     _gl_rebind_arrow_key(gl, "down", gl->d_arrow, "^[[B", "^[OB") ||
     _gl_rebind_arrow_key(gl, "left", gl->l_arrow, "^[[D", "^[OD") ||
     _gl_rebind_arrow_key(gl, "right", gl->r_arrow, "^[[C", "^[OC"))
    return 1;
  return 0;
}

/*.......................................................................
 * Lookup the action function of a symbolic arrow-key binding, and bind
 * it to the terminal-specific and default arrow-key sequences. Note that
 * we don't trust the terminal-specified key sequences to be correct.
 * The main reason for this is that on some machines the xterm terminfo
 * entry is for hardware X-terminals, rather than xterm terminal emulators
 * and the two terminal types emit different character sequences when the
 * their cursor keys are pressed. As a result we also supply a couple
 * of default key sequences.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 *  name           char *   The symbolic name of the arrow key.
 *  term_seq       char *   The terminal-specific arrow-key sequence.
 *  def_seq1       char *   The first default arrow-key sequence.
 *  def_seq2       char *   The second arrow-key sequence.
 * Output:
 *  return          int     0 - OK.
 *                          1 - Error.
 */
static int _gl_rebind_arrow_key(GetLine *gl, const char *name,
				const char *term_seq, const char *def_seq1,
				const char *def_seq2)
{
  KeySym *keysym;  /* The binding-table entry matching the arrow-key name */
  int nsym;        /* The number of ambiguous matches */
/*
 * Lookup the key binding for the symbolic name of the arrow key. This
 * will either be the default action, or a user provided one.
 */
  if(_kt_lookup_keybinding(gl->bindings, name, strlen(name), &keysym, &nsym)
     == KT_EXACT_MATCH) {
/*
 * Get the action function.
 */
    KtAction *action = keysym->actions + keysym->binder;
    KtKeyFn *fn = action->fn;
    void *data = action->data;
/*
 * Bind this to each of the specified key sequences.
 */
    if((term_seq &&
	_kt_set_keyfn(gl->bindings, KTB_TERM, term_seq, fn, data)) ||
       (def_seq1 &&
	_kt_set_keyfn(gl->bindings, KTB_NORM, def_seq1, fn, data)) ||
       (def_seq2 &&
	_kt_set_keyfn(gl->bindings, KTB_NORM, def_seq2, fn, data))) {
      _err_record_msg(gl->err, _kt_last_error(gl->bindings), END_ERR_MSG);
      return 1;
    };
  };
  return 0;
}

/*.......................................................................
 * Read getline configuration information from a given file.
 *
 * Input:
 *  gl           GetLine *  The getline resource object.
 *  filename  const char *  The name of the file to read configuration
 *                          information from. The contents of this file
 *                          are as described in the gl_get_line(3) man
 *                          page for the default ~/.teclarc configuration
 *                          file.
 *  who         KtBinder    Who bindings are to be installed for.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Irrecoverable error.
 */
static int _gl_read_config_file(GetLine *gl, const char *filename, KtBinder who)
{
/*
 * If filesystem access is to be excluded, configuration files can't
 * be read.
 */
#ifdef WITHOUT_FILE_SYSTEM
  _err_record_msg(gl->err,
		  "Can't read configuration files without filesystem access",
		  END_ERR_MSG);
  errno = EINVAL;
  return 1;
#else
  FileExpansion *expansion; /* The expansion of the filename */
  FILE *fp;                 /* The opened file */
  int waserr = 0;           /* True if an error occurred while reading */
  int lineno = 1;           /* The line number being processed */
/*
 * Check the arguments.
 */
  if(!gl || !filename) {
    if(gl)
      _err_record_msg(gl->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Expand the filename.
 */
  expansion = ef_expand_file(gl->ef, filename, -1);
  if(!expansion) {
    gl_print_info(gl, "Unable to expand ", filename, " (",
		  ef_last_error(gl->ef), ").", GL_END_INFO);
    return 1;
  };
/*
 * Attempt to open the file.
 */
  fp = fopen(expansion->files[0], "r");
/*
 * It isn't an error for there to be no configuration file.
 */
  if(!fp)
    return 0;
/*
 * Parse the contents of the file.
 */
  while(!waserr && !feof(fp))
    waserr = _gl_parse_config_line(gl, fp, glc_file_getc, filename, who,
				   &lineno);
/*
 * Bind action functions to the terminal-specific arrow keys.
 */
  if(_gl_bind_arrow_keys(gl))
    return 1;
/*
 * Clean up.
 */
  (void) fclose(fp);
  return waserr;
#endif
}

/*.......................................................................
 * Read GetLine configuration information from a string. The contents of
 * the string are the same as those described in the gl_get_line(3)
 * man page for the contents of the ~/.teclarc configuration file.
 */
static int _gl_read_config_string(GetLine *gl, const char *buffer, KtBinder who)
{
  const char *bptr;         /* A pointer into buffer[] */
  int waserr = 0;           /* True if an error occurred while reading */
  int lineno = 1;           /* The line number being processed */
/*
 * Check the arguments.
 */
  if(!gl || !buffer) {
    if(gl)
      _err_record_msg(gl->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Get a pointer to the start of the buffer.
 */
  bptr = buffer;
/*
 * Parse the contents of the buffer.
 */
  while(!waserr && *bptr)
    waserr = _gl_parse_config_line(gl, &bptr, glc_buff_getc, "", who, &lineno);
/*
 * Bind action functions to the terminal-specific arrow keys.
 */
  if(_gl_bind_arrow_keys(gl))
    return 1;
  return waserr;
}

/*.......................................................................
 * Parse the next line of a getline configuration file.
 *
 * Input:
 *  gl         GetLine *  The getline resource object.
 *  stream        void *  The pointer representing the stream to be read
 *                        by getc_fn().
 *  getc_fn  GlcGetcFn *  A callback function which when called with
 *                       'stream' as its argument, returns the next
 *                        unread character from the stream.
 *  origin  const char *  The name of the entity being read (eg. a
 *                        file name).
 *  who       KtBinder    Who bindings are to be installed for.
 * Input/Output:
 *  lineno         int *  The line number being processed is to be
 *                        maintained in *lineno.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Irrecoverable error.
 */
static int _gl_parse_config_line(GetLine *gl, void *stream, GlcGetcFn *getc_fn,
				 const char *origin, KtBinder who, int *lineno)
{
  char buffer[GL_CONF_BUFLEN+1];  /* The input line buffer */
  char *argv[GL_CONF_MAXARG];     /* The argument list */
  int argc = 0;                   /* The number of arguments in argv[] */
  int c;                          /* A character from the file */
  int escaped = 0;                /* True if the next character is escaped */
  int i;
/*
 * Skip spaces and tabs.
 */
  do c = getc_fn(stream); while(c==' ' || c=='\t');
/*
 * Comments extend to the end of the line.
 */
  if(c=='#')
    do c = getc_fn(stream); while(c != '\n' && c != EOF);
/*
 * Ignore empty lines.
 */
  if(c=='\n' || c==EOF) {
    (*lineno)++;
    return 0;
  };
/*
 * Record the buffer location of the start of the first argument.
 */
  argv[argc] = buffer;
/*
 * Read the rest of the line, stopping early if a comment is seen, or
 * the buffer overflows, and replacing sequences of spaces with a
 * '\0', and recording the thus terminated string as an argument.
 */
  i = 0;
  while(i<GL_CONF_BUFLEN) {
/*
 * Did we hit the end of the latest argument?
 */
    if(c==EOF || (!escaped && (c==' ' || c=='\n' || c=='\t' || c=='#'))) {
/*
 * Terminate the argument.
 */
      buffer[i++] = '\0';
      argc++;
/*
 * Skip spaces and tabs.
 */
      while(c==' ' || c=='\t')
	c = getc_fn(stream);
/*
 * If we hit the end of the line, or the start of a comment, exit the loop.
 */
      if(c==EOF || c=='\n' || c=='#')
	break;
/*
 * Start recording the next argument.
 */
      if(argc >= GL_CONF_MAXARG) {
	gl_report_config_error(gl, origin, *lineno, "Too many arguments.");
	do c = getc_fn(stream); while(c!='\n' && c!=EOF);  /* Skip past eol */
	return 0;
      };
      argv[argc] = buffer + i;
/*
 * The next character was preceded by spaces, so it isn't escaped.
 */
      escaped = 0;
    } else {
/*
 * If we hit an unescaped backslash, this means that we should arrange
 * to treat the next character like a simple alphabetical character.
 */
      if(c=='\\' && !escaped) {
	escaped = 1;
/*
 * Splice lines where the newline is escaped.
 */
      } else if(c=='\n' && escaped) {
	(*lineno)++;
/*
 * Record a normal character, preserving any preceding backslash.
 */
      } else {
	if(escaped)
	  buffer[i++] = '\\';
	if(i>=GL_CONF_BUFLEN)
	  break;
	escaped = 0;
	buffer[i++] = c;
      };
/*
 * Get the next character.
 */
      c = getc_fn(stream);
    };
  };
/*
 * Did the buffer overflow?
 */
  if(i>=GL_CONF_BUFLEN) {
    gl_report_config_error(gl, origin, *lineno, "Line too long.");
    return 0;
  };
/*
 * The first argument should be a command name.
 */
  if(strcmp(argv[0], "bind") == 0) {
    const char *action = NULL; /* A NULL action removes a keybinding */
    const char *keyseq = NULL;
    switch(argc) {
    case 3:
      action = argv[2];
      /* FALLTHROUGH */
    case 2:              /* Note the intentional fallthrough */
      keyseq = argv[1];
/*
 * Attempt to record the new keybinding.
 */
      if(_kt_set_keybinding(gl->bindings, who, keyseq, action)) {
	gl_report_config_error(gl, origin, *lineno,
			       _kt_last_error(gl->bindings));
      };
      break;
    default:
      gl_report_config_error(gl, origin, *lineno, "Wrong number of arguments.");
    };
  } else if(strcmp(argv[0], "edit-mode") == 0) {
    if(argc == 2 && strcmp(argv[1], "emacs") == 0) {
      gl_change_editor(gl, GL_EMACS_MODE);
    } else if(argc == 2 && strcmp(argv[1], "vi") == 0) {
      gl_change_editor(gl, GL_VI_MODE);
    } else if(argc == 2 && strcmp(argv[1], "none") == 0) {
      gl_change_editor(gl, GL_NO_EDITOR);
    } else {
      gl_report_config_error(gl, origin, *lineno,
			     "The argument of editor should be vi or emacs.");
    };
  } else if(strcmp(argv[0], "nobeep") == 0) {
    gl->silence_bell = 1;
  } else {
    gl_report_config_error(gl, origin, *lineno, "Unknown command name.");
  };
/*
 * Skip any trailing comment.
 */
  while(c != '\n' && c != EOF)
    c = getc_fn(stream);
  (*lineno)++;
  return 0;
}

/*.......................................................................
 * This is a private function of _gl_parse_config_line() which prints
 * out an error message about the contents of the line, prefixed by the
 * name of the origin of the line and its line number.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  origin  const char *  The name of the entity being read (eg. a
 *                        file name).
 *  lineno         int    The line number at which the error occurred.
 *  errmsg  const char *  The error message.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error.
 */
static int gl_report_config_error(GetLine *gl, const char *origin, int lineno,
				  const char *errmsg)
{
  char lnum[20];   /* A buffer in which to render a single integer */
/*
 * Convert the line number into a string.
 */
  snprintf(lnum, sizeof(lnum), "%d", lineno);
/*
 * Have the string printed on the terminal.
 */
  return gl_print_info(gl, origin, ":", lnum, ": ", errmsg, GL_END_INFO);
}

/*.......................................................................
 * This is the _gl_parse_config_line() callback function which reads the
 * next character from a configuration file.
 */
static GLC_GETC_FN(glc_file_getc)
{
  return fgetc((FILE *) stream);
}

/*.......................................................................
 * This is the _gl_parse_config_line() callback function which reads the
 * next character from a buffer. Its stream argument is a pointer to a
 * variable which is, in turn, a pointer into the buffer being read from.
 */
static GLC_GETC_FN(glc_buff_getc)
{
  const char **lptr = (char const **) stream;
  return **lptr ? *(*lptr)++ : EOF;
}

#ifndef HIDE_FILE_SYSTEM
/*.......................................................................
 * When this action is triggered, it arranges to temporarily read command
 * lines from the regular file whos name precedes the cursor.
 * The current line is first discarded.
 */
static KT_KEY_FN(gl_read_from_file)
{
  char *start_path;       /* The pointer to the start of the pathname in */
                          /*  gl->line[]. */
  FileExpansion *result;  /* The results of the filename expansion */
  int pathlen;            /* The length of the pathname being expanded */
/*
 * Locate the start of the filename that precedes the cursor position.
 */
  start_path = _pu_start_of_path(gl->line, gl->buff_curpos);
  if(!start_path)
    return 1;
/*
 * Get the length of the pathname string.
 */
  pathlen = gl->buff_curpos - (start_path - gl->line);
/*
 * Attempt to expand the pathname.
 */
  result = ef_expand_file(gl->ef, start_path, pathlen);
/*
 * If there was an error, report the error on a new line.
 */
  if(!result) {
    return gl_print_info(gl, ef_last_error(gl->ef), GL_END_INFO);
/*
 * If no files matched, report this as well.
 */
  } else if(result->nfile == 0 || !result->exists) {
    return gl_print_info(gl, "No files match.", GL_END_INFO);
/*
 * Complain if more than one file matches.
 */
  } else if(result->nfile > 1) {
    return gl_print_info(gl, "More than one file matches.", GL_END_INFO);
/*
 * Disallow input from anything but normal files. In principle we could
 * also support input from named pipes. Terminal files would be a problem
 * since we wouldn't know the terminal type, and other types of files
 * might cause the library to lock up.
 */
  } else if(!_pu_path_is_file(result->files[0])) {
    return gl_print_info(gl, "Not a normal file.", GL_END_INFO);
  } else {
/*
 * Attempt to open and install the specified file for reading.
 */
    gl->file_fp = fopen(result->files[0], "r");
    if(!gl->file_fp) {
      return gl_print_info(gl, "Unable to open: ", result->files[0],
			   GL_END_INFO);
    };
/*
 * If needed, expand the record of the maximum file-descriptor that might
 * need to be monitored with select().
 */
#ifdef HAVE_SELECT
    if(fileno(gl->file_fp) > gl->max_fd)
      gl->max_fd = fileno(gl->file_fp);
#endif
/*
 * Is non-blocking I/O needed?
 */
    if(gl->raw_mode && gl->io_mode==GL_SERVER_MODE &&
       gl_nonblocking_io(gl, fileno(gl->file_fp))) {
      gl_revert_input(gl);
      return gl_print_info(gl, "Can't read file %s with non-blocking I/O",
			   result->files[0]);
    };
/*
 * Inform the user what is happening.
 */
    if(gl_print_info(gl, "<Taking input from ", result->files[0], ">",
		     GL_END_INFO))
      return 1;
  };
  return 0;
}
#endif

/*.......................................................................
 * Close any temporary file that is being used for input.
 *
 * Input:
 *  gl     GetLine *  The getline resource object.
 */
static void gl_revert_input(GetLine *gl)
{
  if(gl->file_fp)
    fclose(gl->file_fp);
  gl->file_fp = NULL;
  gl->endline = 1;
}

/*.......................................................................
 * This is the action function that recalls the oldest line in the
 * history buffer.
 */
static KT_KEY_FN(gl_beginning_of_history)
{
/*
 * In vi mode, switch to command mode, since the user is very
 * likely to want to move around newly recalled lines.
 */
  gl_vi_command_mode(gl);
/*
 * Forget any previous recall session.
 */
  gl->preload_id = 0;
/*
 * Record the key sequence number of this search action.
 */
  gl->last_search = gl->keyseq_count;
/*
 * Recall the next oldest line in the history list.
 */
  if(_glh_oldest_line(gl->glh, gl->line, gl->linelen+1) == NULL)
    return 0;
/*
 * Accomodate the new contents of gl->line[].
 */
  gl_update_buffer(gl);
/*
 * Arrange to have the cursor placed at the end of the new line.
 */
  gl->buff_curpos = gl->ntotal;
/*
 * Erase and display the new line.
 */
  gl_queue_redisplay(gl);
  return 0;
}

/*.......................................................................
 * If a history session is currently in progress, this action function
 * recalls the line that was being edited when the session started. If
 * no history session is in progress, it does nothing.
 */
static KT_KEY_FN(gl_end_of_history)
{
/*
 * In vi mode, switch to command mode, since the user is very
 * likely to want to move around newly recalled lines.
 */
  gl_vi_command_mode(gl);
/*
 * Forget any previous recall session.
 */
  gl->preload_id = 0;
/*
 * Record the key sequence number of this search action.
 */
  gl->last_search = gl->keyseq_count;
/*
 * Recall the next oldest line in the history list.
 */
  if(_glh_current_line(gl->glh, gl->line, gl->linelen+1) == NULL)
    return 0;
/*
 * Accomodate the new contents of gl->line[].
 */
  gl_update_buffer(gl);
/*
 * Arrange to have the cursor placed at the end of the new line.
 */
  gl->buff_curpos = gl->ntotal;
/*
 * Erase and display the new line.
 */
  gl_queue_redisplay(gl);
  return 0;
}

/*.......................................................................
 * This action function is treated specially, in that its count argument
 * is set to the end keystroke of the keysequence that activated it.
 * It accumulates a numeric argument, adding one digit on each call in
 * which the last keystroke was a numeric digit.
 */
static KT_KEY_FN(gl_digit_argument)
{
/*
 * Was the last keystroke a digit?
 */
  int is_digit = isdigit((int)(unsigned char) count);
/*
 * In vi command mode, a lone '0' means goto-start-of-line.
 */
  if(gl->vi.command && gl->number < 0 && count == '0')
    return gl_beginning_of_line(gl, count, NULL);
/*
 * Are we starting to accumulate a new number?
 */
  if(gl->number < 0 || !is_digit)
    gl->number = 0;
/*
 * Was the last keystroke a digit?
 */
  if(is_digit) {
/*
 * Read the numeric value of the digit, without assuming ASCII.
 */
    int n;
    char s[2]; s[0] = count; s[1] = '\0';
    n = atoi(s);
/*
 * Append the new digit.
 */
    gl->number = gl->number * 10 + n;
  };
  return 0;
}

/*.......................................................................
 * The newline action function sets gl->endline to tell
 * gl_get_input_line() that the line is now complete.
 */
static KT_KEY_FN(gl_newline)
{
  GlhLineID id;    /* The last history line recalled while entering this line */
/*
 * Flag the line as ended.
 */
  gl->endline = 1;
/*
 * Record the next position in the history buffer, for potential
 * recall by an action function on the next call to gl_get_line().
 */
  id = _glh_line_id(gl->glh, 1);
  if(id)
    gl->preload_id = id;
  return 0;
}

/*.......................................................................
 * The 'repeat' action function sets gl->endline to tell
 * gl_get_input_line() that the line is now complete, and records the
 * ID of the next history line in gl->preload_id so that the next call
 * to gl_get_input_line() will preload the line with that history line.
 */
static KT_KEY_FN(gl_repeat_history)
{
  gl->endline = 1;
  gl->preload_id = _glh_line_id(gl->glh, 1);
  gl->preload_history = 1;
  return 0;
}

/*.......................................................................
 * Flush unwritten characters to the terminal.
 *
 * Input:
 *  gl     GetLine *  The getline resource object.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Either an error occured, or the output
 *                        blocked and non-blocking I/O is being used.
 *                        See gl->rtn_status for details.
 */
static int gl_flush_output(GetLine *gl)
{
/*
 * Record the fact that we are about to write to the terminal.
 */
  gl->pending_io = GLP_WRITE;
/*
 * Attempt to flush the output to the terminal.
 */
  errno = 0;
  switch(_glq_flush_queue(gl->cq, gl->flush_fn, gl)) {
  case GLQ_FLUSH_DONE:
    return gl->redisplay && !gl->postpone && gl_redisplay(gl, 1, NULL);
    break;
  case GLQ_FLUSH_AGAIN:      /* Output blocked */
    gl_record_status(gl, GLR_BLOCKED, BLOCKED_ERRNO);
    return 1;
    break;
  default:                   /* Abort the line if an error occurs */
    gl_record_status(gl, errno==EINTR ? GLR_SIGNAL : GLR_ERROR, errno);
    return 1;
    break;
  };
}

/*.......................................................................
 * This is the callback which _glq_flush_queue() uses to write buffered
 * characters to the terminal.
 */
static GL_WRITE_FN(gl_flush_terminal)
{
  int ndone = 0;    /* The number of characters written so far */
/*
 * Get the line-editor resource object.
 */
  GetLine *gl = (GetLine *) data;
/*
 * Transfer the latest array of characters to stdio.
 */
  while(ndone < n) {
    int nnew = write(gl->output_fd, s, n-ndone);
/*
 * If the write was successful, add to the recorded number of bytes
 * that have now been written.
 */
    if(nnew > 0) {
      ndone += nnew;
/*
 * If a signal interrupted the call, restart the write(), since all of
 * the signals that gl_get_line() has been told to watch for are
 * currently blocked.
 */
    } else if(errno == EINTR) {
      continue;
/*
 * If we managed to write something before an I/O error occurred, or
 * output blocked before anything was written, report the number of
 * bytes that were successfully written before this happened.
 */
    } else if(ndone > 0
#if defined(EAGAIN)
	      || errno==EAGAIN
#endif
#if defined(EWOULDBLOCK)
	      || errno==EWOULDBLOCK
#endif
	      ) {
      return ndone;

/*
 * To get here, an error must have occurred before anything new could
 * be written.
 */
    } else {
      return -1;
    };
  };
/*
 * To get here, we must have successfully written the number of
 * bytes that was specified.
 */
  return n;
}

/*.......................................................................
 * Change the style of editing to emulate a given editor.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 *  editor  GlEditor    The type of editor to emulate.
 * Output:
 *  return       int    0 - OK.
 *                      1 - Error.
 */
static int gl_change_editor(GetLine *gl, GlEditor editor)
{
/*
 * Install the default key-bindings of the requested editor.
 */
  switch(editor) {
  case GL_EMACS_MODE:
    _kt_clear_bindings(gl->bindings, KTB_NORM);
    _kt_clear_bindings(gl->bindings, KTB_TERM);
    (void) _kt_add_bindings(gl->bindings, KTB_NORM, gl_emacs_bindings,
		   sizeof(gl_emacs_bindings)/sizeof(gl_emacs_bindings[0]));
    break;
  case GL_VI_MODE:
    _kt_clear_bindings(gl->bindings, KTB_NORM);
    _kt_clear_bindings(gl->bindings, KTB_TERM);
    (void) _kt_add_bindings(gl->bindings, KTB_NORM, gl_vi_bindings,
			    sizeof(gl_vi_bindings)/sizeof(gl_vi_bindings[0]));
    break;
  case GL_NO_EDITOR:
    break;
  default:
    _err_record_msg(gl->err, "Unknown editor", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Record the new editing mode.
 */
  gl->editor = editor;
  gl->vi.command = 0;     /* Start in input mode */
  gl->insert_curpos = 0;
/*
 * Reinstate terminal-specific bindings.
 */
  if(gl->editor != GL_NO_EDITOR && gl->input_fp)
    (void) gl_bind_terminal_keys(gl);
  return 0;
}

/*.......................................................................
 * This is an action function that switches to editing using emacs bindings
 */
static KT_KEY_FN(gl_emacs_editing_mode)
{
  return gl_change_editor(gl, GL_EMACS_MODE);
}

/*.......................................................................
 * This is an action function that switches to editing using vi bindings
 */
static KT_KEY_FN(gl_vi_editing_mode)
{
  return gl_change_editor(gl, GL_VI_MODE);
}

/*.......................................................................
 * This is the action function that switches to insert mode.
 */
static KT_KEY_FN(gl_vi_insert)
{
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Switch to vi insert mode.
 */
  gl->insert = 1;
  gl->vi.command = 0;
  gl->insert_curpos = gl->buff_curpos;
  return 0;
}

/*.......................................................................
 * This is an action function that switches to overwrite mode.
 */
static KT_KEY_FN(gl_vi_overwrite)
{
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * Switch to vi overwrite mode.
 */
  gl->insert = 0;
  gl->vi.command = 0;
  gl->insert_curpos = gl->buff_curpos;
  return 0;
}

/*.......................................................................
 * This action function toggles the case of the character under the
 * cursor.
 */
static KT_KEY_FN(gl_change_case)
{
  int i;
/*
 * Keep a record of the current insert mode and the cursor position.
 */
  int insert = gl->insert;
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
  gl_save_for_undo(gl);
/*
 * We want to overwrite the modified word.
 */
  gl->insert = 0;
/*
 * Toggle the case of 'count' characters.
 */
  for(i=0; i<count && gl->buff_curpos < gl->ntotal; i++) {
    char *cptr = gl->line + gl->buff_curpos++;
/*
 * Convert the character to upper case?
 */
    if(islower((int)(unsigned char) *cptr))
      gl_buffer_char(gl, toupper((int) *cptr), cptr - gl->line);
    else if(isupper((int)(unsigned char) *cptr))
      gl_buffer_char(gl, tolower((int) *cptr), cptr - gl->line);
/*
 * Write the possibly modified character back. Note that for non-modified
 * characters we want to do this as well, so as to advance the cursor.
 */
      if(gl_print_char(gl, *cptr, cptr[1]))
	return 1;
  };
/*
 * Restore the insertion mode.
 */
  gl->insert = insert;
  return gl_place_cursor(gl, gl->buff_curpos);	/* bounds check */
}

/*.......................................................................
 * This is the action function which implements the vi-style action which
 * moves the cursor to the start of the line, then switches to insert mode.
 */
static KT_KEY_FN(gl_vi_insert_at_bol)
{
  gl_save_for_undo(gl);
  return gl_beginning_of_line(gl, 0, NULL) ||
         gl_vi_insert(gl, 0, NULL);

}

/*.......................................................................
 * This is the action function which implements the vi-style action which
 * moves the cursor to the end of the line, then switches to insert mode
 * to allow text to be appended to the line.
 */
static KT_KEY_FN(gl_vi_append_at_eol)
{
  gl_save_for_undo(gl);
  gl->vi.command = 0;	/* Allow cursor at EOL */
  return gl_end_of_line(gl, 0, NULL) ||
         gl_vi_insert(gl, 0, NULL);
}

/*.......................................................................
 * This is the action function which implements the vi-style action which
 * moves the cursor to right one then switches to insert mode, thus
 * allowing text to be appended after the next character.
 */
static KT_KEY_FN(gl_vi_append)
{
  gl_save_for_undo(gl);
  gl->vi.command = 0;	/* Allow cursor at EOL */
  return gl_cursor_right(gl, 1, NULL) ||
         gl_vi_insert(gl, 0, NULL);
}

/*.......................................................................
 * This action function moves the cursor to the column specified by the
 * numeric argument. Column indexes start at 1.
 */
static KT_KEY_FN(gl_goto_column)
{
  return gl_place_cursor(gl, count - 1);
}

/*.......................................................................
 * Starting with the character under the cursor, replace 'count'
 * characters with the next character that the user types.
 */
static KT_KEY_FN(gl_vi_replace_char)
{
  char c;  /* The replacement character */
  int i;
/*
 * Keep a record of the current insert mode.
 */
  int insert = gl->insert;
/*
 * Get the replacement character.
 */
  if(gl->vi.repeat.active) {
    c = gl->vi.repeat.input_char;
  } else {
    if(gl_read_terminal(gl, 1, &c))
      return 1;
    gl->vi.repeat.input_char = c;
  };
/*
 * Are there 'count' characters to be replaced?
 */
  if(gl->ntotal - gl->buff_curpos >= count) {
/*
 * If in vi command mode, preserve the current line for potential
 * use by vi-undo.
 */
    gl_save_for_undo(gl);
/*
 * Temporarily switch to overwrite mode.
 */
    gl->insert = 0;
/*
 * Overwrite the current character plus count-1 subsequent characters
 * with the replacement character.
 */
    for(i=0; i<count; i++)
      gl_add_char_to_line(gl, c);
/*
 * Restore the original insert/overwrite mode.
 */
    gl->insert = insert;
  };
  return gl_place_cursor(gl, gl->buff_curpos);	/* bounds check */
}

/*.......................................................................
 * This is an action function which changes all characters between the
 * current cursor position and the end of the line.
 */
static KT_KEY_FN(gl_vi_change_rest_of_line)
{
  gl_save_for_undo(gl);
  gl->vi.command = 0;	/* Allow cursor at EOL */
  return gl_kill_line(gl, count, NULL) || gl_vi_insert(gl, 0, NULL);
}

/*.......................................................................
 * This is an action function which changes all characters between the
 * start of the line and the current cursor position.
 */
static KT_KEY_FN(gl_vi_change_to_bol)
{
  return gl_backward_kill_line(gl,count,NULL) || gl_vi_insert(gl,0,NULL);
}

/*.......................................................................
 * This is an action function which deletes the entire contents of the
 * current line and switches to insert mode.
 */
static KT_KEY_FN(gl_vi_change_line)
{
  return gl_delete_line(gl,count,NULL) || gl_vi_insert(gl,0,NULL);
}

/*.......................................................................
 * Starting from the cursor position and looking towards the end of the
 * line, copy 'count' characters to the cut buffer.
 */
static KT_KEY_FN(gl_forward_copy_char)
{
/*
 * Limit the count to the number of characters available.
 */
  if(gl->buff_curpos + count >= gl->ntotal)
    count = gl->ntotal - gl->buff_curpos;
  if(count < 0)
    count = 0;
/*
 * Copy the characters to the cut buffer.
 */
  memcpy(gl->cutbuf, gl->line + gl->buff_curpos, count);
  gl->cutbuf[count] = '\0';
  return 0;
}

/*.......................................................................
 * Starting from the character before the cursor position and looking
 * backwards towards the start of the line, copy 'count' characters to
 * the cut buffer.
 */
static KT_KEY_FN(gl_backward_copy_char)
{
/*
 * Limit the count to the number of characters available.
 */
  if(count > gl->buff_curpos)
    count = gl->buff_curpos;
  if(count < 0)
    count = 0;
  gl_place_cursor(gl, gl->buff_curpos - count);
/*
 * Copy the characters to the cut buffer.
 */
  memcpy(gl->cutbuf, gl->line + gl->buff_curpos, count);
  gl->cutbuf[count] = '\0';
  return 0;
}

/*.......................................................................
 * Starting from the cursor position copy to the specified column into the
 * cut buffer.
 */
static KT_KEY_FN(gl_copy_to_column)
{
  if (--count >= gl->buff_curpos)
    return gl_forward_copy_char(gl, count - gl->buff_curpos, NULL);
  else
    return gl_backward_copy_char(gl, gl->buff_curpos - count, NULL);
}

/*.......................................................................
 * Starting from the cursor position copy characters up to a matching
 * parenthesis into the cut buffer.
 */
static KT_KEY_FN(gl_copy_to_parenthesis)
{
  int curpos = gl_index_of_matching_paren(gl);
  if(curpos >= 0) {
    gl_save_for_undo(gl);
    if(curpos >= gl->buff_curpos)
      return gl_forward_copy_char(gl, curpos - gl->buff_curpos + 1, NULL);
    else
      return gl_backward_copy_char(gl, ++gl->buff_curpos - curpos + 1, NULL);
  };
  return 0;
}

/*.......................................................................
 * Starting from the cursor position copy the rest of the line into the
 * cut buffer.
 */
static KT_KEY_FN(gl_copy_rest_of_line)
{
/*
 * Copy the characters to the cut buffer.
 */
  memcpy(gl->cutbuf, gl->line + gl->buff_curpos, gl->ntotal - gl->buff_curpos);
  gl->cutbuf[gl->ntotal - gl->buff_curpos] = '\0';
  return 0;
}

/*.......................................................................
 * Copy from the beginning of the line to the cursor position into the
 * cut buffer.
 */
static KT_KEY_FN(gl_copy_to_bol)
{
/*
 * Copy the characters to the cut buffer.
 */
  memcpy(gl->cutbuf, gl->line, gl->buff_curpos);
  gl->cutbuf[gl->buff_curpos] = '\0';
  gl_place_cursor(gl, 0);
  return 0;
}

/*.......................................................................
 * Copy the entire line into the cut buffer.
 */
static KT_KEY_FN(gl_copy_line)
{
/*
 * Copy the characters to the cut buffer.
 */
  memcpy(gl->cutbuf, gl->line, gl->ntotal);
  gl->cutbuf[gl->ntotal] = '\0';
  return 0;
}

/*.......................................................................
 * Search forwards for the next character that the user enters.
 */
static KT_KEY_FN(gl_forward_find_char)
{
  int pos = gl_find_char(gl, count, 1, 1, '\0');
  return pos >= 0 && gl_place_cursor(gl, pos);
}

/*.......................................................................
 * Search backwards for the next character that the user enters.
 */
static KT_KEY_FN(gl_backward_find_char)
{
  int pos = gl_find_char(gl, count, 0, 1, '\0');
  return pos >= 0 && gl_place_cursor(gl, pos);
}

/*.......................................................................
 * Search forwards for the next character that the user enters. Move up to,
 * but not onto, the found character.
 */
static KT_KEY_FN(gl_forward_to_char)
{
  int pos = gl_find_char(gl, count, 1, 0, '\0');
  return pos >= 0 && gl_place_cursor(gl, pos);
}

/*.......................................................................
 * Search backwards for the next character that the user enters. Move back to,
 * but not onto, the found character.
 */
static KT_KEY_FN(gl_backward_to_char)
{
  int pos = gl_find_char(gl, count, 0, 0, '\0');
  return pos >= 0 && gl_place_cursor(gl, pos);
}

/*.......................................................................
 * Searching in a given direction, return the index of a given (or
 * read) character in the input line, or the character that precedes
 * it in the specified search direction. Return -1 if not found.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 *  count        int    The number of times to search.
 *  forward      int    True if searching forward.
 *  onto         int    True if the search should end on top of the
 *                      character, false if the search should stop
 *                      one character before the character in the
 *                      specified search direction.
 *  c           char    The character to be sought, or '\0' if the
 *                      character should be read from the user.
 * Output:
 *  return       int    The index of the character in gl->line[], or
 *                      -1 if not found.
 */
static int gl_find_char(GetLine *gl, int count, int forward, int onto, char c)
{
  int pos;     /* The index reached in searching the input line */
  int i;
/*
 * Get a character from the user?
 */
  if(!c) {
/*
 * If we are in the process of repeating a previous change command, substitute
 * the last find character.
 */
    if(gl->vi.repeat.active) {
      c = gl->vi.find_char;
    } else {
      if(gl_read_terminal(gl, 1, &c))
	return -1;
/*
 * Record the details of the new search, for use by repeat finds.
 */
      gl->vi.find_forward = forward;
      gl->vi.find_onto = onto;
      gl->vi.find_char = c;
    };
  };
/*
 * Which direction should we search?
 */
  if(forward) {
/*
 * Search forwards 'count' times for the character, starting with the
 * character that follows the cursor.
 */
    for(i=0, pos=gl->buff_curpos; i<count && pos < gl->ntotal; i++) {
/*
 * Advance past the last match (or past the current cursor position
 * on the first search).
 */
      pos++;
/*
 * Search for the next instance of c.
 */
      for( ; pos<gl->ntotal && c!=gl->line[pos]; pos++)
	;
    };
/*
 * If the character was found and we have been requested to return the
 * position of the character that precedes the desired character, then
 * we have gone one character too far.
 */
    if(!onto && pos<gl->ntotal)
      pos--;
  } else {
/*
 * Search backwards 'count' times for the character, starting with the
 * character that precedes the cursor.
 */
    for(i=0, pos=gl->buff_curpos; i<count && pos >= gl->insert_curpos; i++) {
/*
 * Step back one from the last match (or from the current cursor
 * position on the first search).
 */
      pos--;
/*
 * Search for the next instance of c.
 */
      for( ; pos>=gl->insert_curpos && c!=gl->line[pos]; pos--)
	;
    };
/*
 * If the character was found and we have been requested to return the
 * position of the character that precedes the desired character, then
 * we have gone one character too far.
 */
    if(!onto && pos>=gl->insert_curpos)
      pos++;
  };
/*
 * If found, return the cursor position of the count'th match.
 * Otherwise ring the terminal bell.
 */
  if(pos >= gl->insert_curpos && pos < gl->ntotal) {
    return pos;
  } else {
    (void) gl_ring_bell(gl, 1, NULL);
    return -1;
  }
}

/*.......................................................................
 * Repeat the last character search in the same direction as the last
 * search.
 */
static KT_KEY_FN(gl_repeat_find_char)
{
  int pos = gl->vi.find_char ?
    gl_find_char(gl, count, gl->vi.find_forward, gl->vi.find_onto,
		 gl->vi.find_char) : -1;
  return pos >= 0 && gl_place_cursor(gl, pos);
}

/*.......................................................................
 * Repeat the last character search in the opposite direction as the last
 * search.
 */
static KT_KEY_FN(gl_invert_refind_char)
{
  int pos = gl->vi.find_char ?
    gl_find_char(gl, count, !gl->vi.find_forward, gl->vi.find_onto,
		 gl->vi.find_char) : -1;
  return pos >= 0 && gl_place_cursor(gl, pos);
}

/*.......................................................................
 * Search forward from the current position of the cursor for 'count'
 * word endings, returning the index of the last one found, or the end of
 * the line if there were less than 'count' words.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 *  n            int    The number of word boundaries to search for.
 * Output:
 *  return       int    The buffer index of the located position.
 */
static int gl_nth_word_end_forward(GetLine *gl, int n)
{
  int bufpos;   /* The buffer index being checked. */
  int i;
/*
 * In order to guarantee forward motion to the next word ending,
 * we need to start from one position to the right of the cursor
 * position, since this may already be at the end of a word.
 */
  bufpos = gl->buff_curpos + 1;
/*
 * If we are at the end of the line, return the index of the last
 * real character on the line. Note that this will be -1 if the line
 * is empty.
 */
  if(bufpos >= gl->ntotal)
    return gl->ntotal - 1;
/*
 * Search 'n' times, unless the end of the input line is reached first.
 */
  for(i=0; i<n && bufpos<gl->ntotal; i++) {
/*
 * If we are not already within a word, skip to the start of the next word.
 */
    for( ; bufpos<gl->ntotal && !gl_is_word_char((int)gl->line[bufpos]);
	bufpos++)
      ;
/*
 * Find the end of the next word.
 */
    for( ; bufpos<gl->ntotal && gl_is_word_char((int)gl->line[bufpos]);
	bufpos++)
      ;
  };
/*
 * We will have overshot.
 */
  return bufpos > 0 ? bufpos-1 : bufpos;
}

/*.......................................................................
 * Search forward from the current position of the cursor for 'count'
 * word starts, returning the index of the last one found, or the end of
 * the line if there were less than 'count' words.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 *  n            int    The number of word boundaries to search for.
 * Output:
 *  return       int    The buffer index of the located position.
 */
static int gl_nth_word_start_forward(GetLine *gl, int n)
{
  int bufpos;   /* The buffer index being checked. */
  int i;
/*
 * Get the current cursor position.
 */
  bufpos = gl->buff_curpos;
/*
 * Search 'n' times, unless the end of the input line is reached first.
 */
  for(i=0; i<n && bufpos<gl->ntotal; i++) {
/*
 * Find the end of the current word.
 */
    for( ; bufpos<gl->ntotal && gl_is_word_char((int)gl->line[bufpos]);
	bufpos++)
      ;
/*
 * Skip to the start of the next word.
 */
    for( ; bufpos<gl->ntotal && !gl_is_word_char((int)gl->line[bufpos]);
	bufpos++)
      ;
  };
  return bufpos;
}

/*.......................................................................
 * Search backward from the current position of the cursor for 'count'
 * word starts, returning the index of the last one found, or the start
 * of the line if there were less than 'count' words.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 *  n            int    The number of word boundaries to search for.
 * Output:
 *  return       int    The buffer index of the located position.
 */
static int gl_nth_word_start_backward(GetLine *gl, int n)
{
  int bufpos;   /* The buffer index being checked. */
  int i;
/*
 * Get the current cursor position.
 */
  bufpos = gl->buff_curpos;
/*
 * Search 'n' times, unless the beginning of the input line (or vi insertion
 * point) is reached first.
 */
  for(i=0; i<n && bufpos > gl->insert_curpos; i++) {
/*
 * Starting one character back from the last search, so as not to keep
 * settling on the same word-start, search backwards until finding a
 * word character.
 */
    while(--bufpos >= gl->insert_curpos &&
          !gl_is_word_char((int)gl->line[bufpos]))
      ;
/*
 * Find the start of the word.
 */
    while(--bufpos >= gl->insert_curpos &&
          gl_is_word_char((int)gl->line[bufpos]))
      ;
/*
 * We will have gone one character too far.
 */
    bufpos++;
  };
  return bufpos >= gl->insert_curpos ? bufpos : gl->insert_curpos;
}

/*.......................................................................
 * Copy one or more words into the cut buffer without moving the cursor
 * or deleting text.
 */
static KT_KEY_FN(gl_forward_copy_word)
{
/*
 * Find the location of the count'th start or end of a word
 * after the cursor, depending on whether in emacs or vi mode.
 */
  int next = gl->editor == GL_EMACS_MODE ?
    gl_nth_word_end_forward(gl, count) :
    gl_nth_word_start_forward(gl, count);
/*
 * How many characters are to be copied into the cut buffer?
 */
  int n = next - gl->buff_curpos;
/*
 * Copy the specified segment and terminate the string.
 */
  memcpy(gl->cutbuf, gl->line + gl->buff_curpos, n);
  gl->cutbuf[n] = '\0';
  return 0;
}

/*.......................................................................
 * Copy one or more words preceding the cursor into the cut buffer,
 * without moving the cursor or deleting text.
 */
static KT_KEY_FN(gl_backward_copy_word)
{
/*
 * Find the location of the count'th start of word before the cursor.
 */
  int next = gl_nth_word_start_backward(gl, count);
/*
 * How many characters are to be copied into the cut buffer?
 */
  int n = gl->buff_curpos - next;
  gl_place_cursor(gl, next);
/*
 * Copy the specified segment and terminate the string.
 */
  memcpy(gl->cutbuf, gl->line + next, n);
  gl->cutbuf[n] = '\0';
  return 0;
}

/*.......................................................................
 * Copy the characters between the cursor and the count'th instance of
 * a specified character in the input line, into the cut buffer.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 *  count        int    The number of times to search.
 *  c           char    The character to be searched for, or '\0' if
 *                      the character should be read from the user.
 *  forward      int    True if searching forward.
 *  onto         int    True if the search should end on top of the
 *                      character, false if the search should stop
 *                      one character before the character in the
 *                      specified search direction.
 * Output:
 *  return       int    0 - OK.
 *                      1 - Error.
 *
 */
static int gl_copy_find(GetLine *gl, int count, char c, int forward, int onto)
{
  int n;  /* The number of characters in the cut buffer */
/*
 * Search for the character, and abort the operation if not found.
 */
  int pos = gl_find_char(gl, count, forward, onto, c);
  if(pos < 0)
    return 0;
/*
 * Copy the specified segment.
 */
  if(forward) {
    n = pos + 1 - gl->buff_curpos;
    memcpy(gl->cutbuf, gl->line + gl->buff_curpos, n);
  } else {
    n = gl->buff_curpos - pos;
    memcpy(gl->cutbuf, gl->line + pos, n);
    if(gl->editor == GL_VI_MODE)
      gl_place_cursor(gl, pos);
  }
/*
 * Terminate the copy.
 */
  gl->cutbuf[n] = '\0';
  return 0;
}

/*.......................................................................
 * Copy a section up to and including a specified character into the cut
 * buffer without moving the cursor or deleting text.
 */
static KT_KEY_FN(gl_forward_copy_find)
{
  return gl_copy_find(gl, count, '\0', 1, 1);
}

/*.......................................................................
 * Copy a section back to and including a specified character into the cut
 * buffer without moving the cursor or deleting text.
 */
static KT_KEY_FN(gl_backward_copy_find)
{
  return gl_copy_find(gl, count, '\0', 0, 1);
}

/*.......................................................................
 * Copy a section up to and not including a specified character into the cut
 * buffer without moving the cursor or deleting text.
 */
static KT_KEY_FN(gl_forward_copy_to)
{
  return gl_copy_find(gl, count, '\0', 1, 0);
}

/*.......................................................................
 * Copy a section back to and not including a specified character into the cut
 * buffer without moving the cursor or deleting text.
 */
static KT_KEY_FN(gl_backward_copy_to)
{
  return gl_copy_find(gl, count, '\0', 0, 0);
}

/*.......................................................................
 * Copy to a character specified in a previous search into the cut
 * buffer without moving the cursor or deleting text.
 */
static KT_KEY_FN(gl_copy_refind)
{
  return gl_copy_find(gl, count, gl->vi.find_char, gl->vi.find_forward,
		      gl->vi.find_onto);
}

/*.......................................................................
 * Copy to a character specified in a previous search, but in the opposite
 * direction, into the cut buffer without moving the cursor or deleting text.
 */
static KT_KEY_FN(gl_copy_invert_refind)
{
  return gl_copy_find(gl, count, gl->vi.find_char, !gl->vi.find_forward,
		      gl->vi.find_onto);
}

/*.......................................................................
 * Set the position of the cursor in the line input buffer and the
 * terminal.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 *  buff_curpos  int    The new buffer cursor position.
 * Output:
 *  return       int    0 - OK.
 *                      1 - Error.
 */
static int gl_place_cursor(GetLine *gl, int buff_curpos)
{
/*
 * Don't allow the cursor position to go out of the bounds of the input
 * line.
 */
  if(buff_curpos >= gl->ntotal)
    buff_curpos = gl->vi.command ? gl->ntotal-1 : gl->ntotal;
  if(buff_curpos < 0)
    buff_curpos = 0;
/*
 * Record the new buffer position.
 */
  gl->buff_curpos = buff_curpos;
/*
 * Move the terminal cursor to the corresponding character.
 */
  return gl_set_term_curpos(gl, gl->prompt_len +
    gl_displayed_string_width(gl, gl->line, buff_curpos, gl->prompt_len));
}

/*.......................................................................
 * In vi command mode, this function saves the current line to the
 * historical buffer needed by the undo command. In emacs mode it does
 * nothing. In order to allow action functions to call other action
 * functions, gl_interpret_char() sets gl->vi.undo.saved to 0 before
 * invoking an action, and thereafter once any call to this function
 * has set it to 1, further calls are ignored.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 */
static void gl_save_for_undo(GetLine *gl)
{
  if(gl->vi.command && !gl->vi.undo.saved) {
    strlcpy(gl->vi.undo.line, gl->line, gl->linelen);
    gl->vi.undo.buff_curpos = gl->buff_curpos;
    gl->vi.undo.ntotal = gl->ntotal;
    gl->vi.undo.saved = 1;
  };
  if(gl->vi.command && !gl->vi.repeat.saved &&
     gl->current_action.fn != gl_vi_repeat_change) {
    gl->vi.repeat.action = gl->current_action;
    gl->vi.repeat.count = gl->current_count;
    gl->vi.repeat.saved = 1;
  };
  return;
}

/*.......................................................................
 * In vi mode, restore the line to the way it was before the last command
 * mode operation, storing the current line in the buffer so that the
 * undo operation itself can subsequently be undone.
 */
static KT_KEY_FN(gl_vi_undo)
{
/*
 * Get pointers into the two lines.
 */
  char *undo_ptr = gl->vi.undo.line;
  char *line_ptr = gl->line;
/*
 * Swap the characters of the two buffers up to the length of the shortest
 * line.
 */
  while(*undo_ptr && *line_ptr) {
    char c = *undo_ptr;
    *undo_ptr++ = *line_ptr;
    *line_ptr++ = c;
  };
/*
 * Copy the rest directly.
 */
  if(gl->ntotal > gl->vi.undo.ntotal) {
    strlcpy(undo_ptr, line_ptr, gl->linelen);
    *line_ptr = '\0';
  } else {
    strlcpy(line_ptr, undo_ptr, gl->linelen);
    *undo_ptr = '\0';
  };
/*
 * Record the length of the stored string.
 */
  gl->vi.undo.ntotal = gl->ntotal;
/*
 * Accomodate the new contents of gl->line[].
 */
  gl_update_buffer(gl);
/*
 * Set both cursor positions to the leftmost of the saved and current
 * cursor positions to emulate what vi does.
 */
  if(gl->buff_curpos < gl->vi.undo.buff_curpos)
    gl->vi.undo.buff_curpos = gl->buff_curpos;
  else
    gl->buff_curpos = gl->vi.undo.buff_curpos;
/*
 * Since we have bipassed calling gl_save_for_undo(), record repeat
 * information inline.
 */
  gl->vi.repeat.action.fn = gl_vi_undo;
  gl->vi.repeat.action.data = NULL;
  gl->vi.repeat.count = 1;
/*
 * Display the restored line.
 */
  gl_queue_redisplay(gl);
  return 0;
}

/*.......................................................................
 * Delete the following word and leave the user in vi insert mode.
 */
static KT_KEY_FN(gl_vi_forward_change_word)
{
  gl_save_for_undo(gl);
  gl->vi.command = 0;	/* Allow cursor at EOL */
  return gl_forward_delete_word(gl, count, NULL) || gl_vi_insert(gl, 0, NULL);
}

/*.......................................................................
 * Delete the preceding word and leave the user in vi insert mode.
 */
static KT_KEY_FN(gl_vi_backward_change_word)
{
  return gl_backward_delete_word(gl, count, NULL) || gl_vi_insert(gl, 0, NULL);
}

/*.......................................................................
 * Delete the following section and leave the user in vi insert mode.
 */
static KT_KEY_FN(gl_vi_forward_change_find)
{
  return gl_delete_find(gl, count, '\0', 1, 1, 1);
}

/*.......................................................................
 * Delete the preceding section and leave the user in vi insert mode.
 */
static KT_KEY_FN(gl_vi_backward_change_find)
{
  return gl_delete_find(gl, count, '\0', 0, 1, 1);
}

/*.......................................................................
 * Delete the following section and leave the user in vi insert mode.
 */
static KT_KEY_FN(gl_vi_forward_change_to)
{
  return gl_delete_find(gl, count, '\0', 1, 0, 1);
}

/*.......................................................................
 * Delete the preceding section and leave the user in vi insert mode.
 */
static KT_KEY_FN(gl_vi_backward_change_to)
{
  return gl_delete_find(gl, count, '\0', 0, 0, 1);
}

/*.......................................................................
 * Delete to a character specified by a previous search and leave the user
 * in vi insert mode.
 */
static KT_KEY_FN(gl_vi_change_refind)
{
  return gl_delete_find(gl, count, gl->vi.find_char, gl->vi.find_forward,
			gl->vi.find_onto, 1);
}

/*.......................................................................
 * Delete to a character specified by a previous search, but in the opposite
 * direction, and leave the user in vi insert mode.
 */
static KT_KEY_FN(gl_vi_change_invert_refind)
{
  return gl_delete_find(gl, count, gl->vi.find_char, !gl->vi.find_forward,
			gl->vi.find_onto, 1);
}

/*.......................................................................
 * Delete the following character and leave the user in vi insert mode.
 */
static KT_KEY_FN(gl_vi_forward_change_char)
{
  gl_save_for_undo(gl);
  gl->vi.command = 0;	/* Allow cursor at EOL */
  return gl_delete_chars(gl, count, 1) || gl_vi_insert(gl, 0, NULL);
}

/*.......................................................................
 * Delete the preceding character and leave the user in vi insert mode.
 */
static KT_KEY_FN(gl_vi_backward_change_char)
{
  return gl_backward_delete_char(gl, count, NULL) || gl_vi_insert(gl, 0, NULL);
}

/*.......................................................................
 * Starting from the cursor position change characters to the specified column.
 */
static KT_KEY_FN(gl_vi_change_to_column)
{
  if (--count >= gl->buff_curpos)
    return gl_vi_forward_change_char(gl, count - gl->buff_curpos, NULL);
  else
    return gl_vi_backward_change_char(gl, gl->buff_curpos - count, NULL);
}

/*.......................................................................
 * Starting from the cursor position change characters to a matching
 * parenthesis.
 */
static KT_KEY_FN(gl_vi_change_to_parenthesis)
{
  int curpos = gl_index_of_matching_paren(gl);
  if(curpos >= 0) {
    gl_save_for_undo(gl);
    if(curpos >= gl->buff_curpos)
      return gl_vi_forward_change_char(gl, curpos - gl->buff_curpos + 1, NULL);
    else
      return gl_vi_backward_change_char(gl, ++gl->buff_curpos - curpos + 1,
					NULL);
  };
  return 0;
}

/*.......................................................................
 * If in vi mode, switch to vi command mode.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 */
static void gl_vi_command_mode(GetLine *gl)
{
  if(gl->editor == GL_VI_MODE && !gl->vi.command) {
    gl->insert = 1;
    gl->vi.command = 1;
    gl->vi.repeat.input_curpos = gl->insert_curpos;
    gl->vi.repeat.command_curpos = gl->buff_curpos;
    gl->insert_curpos = 0;	 /* unrestrict left motion boundary */
    gl_cursor_left(gl, 1, NULL); /* Vi moves 1 left on entering command mode */
  };
}

/*.......................................................................
 * This is an action function which rings the terminal bell.
 */
static KT_KEY_FN(gl_ring_bell)
{
  return gl->silence_bell ? 0 :
    gl_print_control_sequence(gl, 1, gl->sound_bell);
}

/*.......................................................................
 * This is the action function which implements the vi-repeat-change
 * action.
 */
static KT_KEY_FN(gl_vi_repeat_change)
{
  int status;   /* The return status of the repeated action function */
  int i;
/*
 * Nothing to repeat?
 */
  if(!gl->vi.repeat.action.fn)
    return gl_ring_bell(gl, 1, NULL);
/*
 * Provide a way for action functions to know whether they are being
 * called by us.
 */
  gl->vi.repeat.active = 1;
/*
 * Re-run the recorded function.
 */
  status = gl->vi.repeat.action.fn(gl, gl->vi.repeat.count,
				   gl->vi.repeat.action.data);
/*
 * Mark the repeat as completed.
 */
  gl->vi.repeat.active = 0;
/*
 * Is we are repeating a function that has just switched to input
 * mode to allow the user to type, re-enter the text that the user
 * previously entered.
 */
  if(status==0 && !gl->vi.command) {
/*
 * Make sure that the current line has been saved.
 */
    gl_save_for_undo(gl);
/*
 * Repeat a previous insertion or overwrite?
 */
    if(gl->vi.repeat.input_curpos >= 0 &&
       gl->vi.repeat.input_curpos <= gl->vi.repeat.command_curpos &&
       gl->vi.repeat.command_curpos <= gl->vi.undo.ntotal) {
/*
 * Using the current line which is saved in the undo buffer, plus
 * the range of characters therein, as recorded by gl_vi_command_mode(),
 * add the characters that the user previously entered, to the input
 * line.
 */
      for(i=gl->vi.repeat.input_curpos; i<gl->vi.repeat.command_curpos; i++) {
	if(gl_add_char_to_line(gl, gl->vi.undo.line[i]))
	  return 1;
      };
    };
/*
 * Switch back to command mode, now that the insertion has been repeated.
 */
    gl_vi_command_mode(gl);
  };
  return status;
}

/*.......................................................................
 * If the cursor is currently over a parenthesis character, return the
 * index of its matching parenthesis. If not currently over a parenthesis
 * character, return the next close parenthesis character to the right of
 * the cursor. If the respective parenthesis character isn't found,
 * ring the terminal bell and return -1.
 *
 * Input:
 *  gl       GetLine *  The getline resource object.
 * Output:
 *  return       int    Either the index of the matching parenthesis,
 *                      or -1 if not found.
 */
static int gl_index_of_matching_paren(GetLine *gl)
{
  int i;
/*
 * List the recognized parentheses, and their matches.
 */
  const char *o_paren = "([{";
  const char *c_paren = ")]}";
  const char *cptr;
/*
 * Get the character that is currently under the cursor.
 */
  char c = gl->line[gl->buff_curpos];
/*
 * If the character under the cursor is an open parenthesis, look forward
 * for the matching close parenthesis.
 */
  if((cptr=strchr(o_paren, c))) {
    char match = c_paren[cptr - o_paren];
    int matches_needed = 1;
    for(i=gl->buff_curpos+1; i<gl->ntotal; i++) {
      if(gl->line[i] == c)
	matches_needed++;
      else if(gl->line[i] == match && --matches_needed==0)
	return i;
    };
/*
 * If the character under the cursor is an close parenthesis, look forward
 * for the matching open parenthesis.
 */
  } else if((cptr=strchr(c_paren, c))) {
    char match = o_paren[cptr - c_paren];
    int matches_needed = 1;
    for(i=gl->buff_curpos-1; i>=0; i--) {
      if(gl->line[i] == c)
	matches_needed++;
      else if(gl->line[i] == match && --matches_needed==0)
	return i;
    };
/*
 * If not currently over a parenthesis character, search forwards for
 * the first close parenthesis (this is what the vi % binding does).
 */
  } else {
    for(i=gl->buff_curpos+1; i<gl->ntotal; i++)
      if(strchr(c_paren, gl->line[i]) != NULL)
	return i;
  };
/*
 * Not found.
 */
  (void) gl_ring_bell(gl, 1, NULL);
  return -1;
}

/*.......................................................................
 * If the cursor is currently over a parenthesis character, this action
 * function moves the cursor to its matching parenthesis.
 */
static KT_KEY_FN(gl_find_parenthesis)
{
  int curpos = gl_index_of_matching_paren(gl);
  if(curpos >= 0)
    return gl_place_cursor(gl, curpos);
  return 0;
}

/*.......................................................................
 * Handle the receipt of the potential start of a new key-sequence from
 * the user.
 *
 * Input:
 *  gl      GetLine *   The resource object of this library.
 *  first_char char     The first character of the sequence.
 * Output:
 *  return      int     0 - OK.
 *                      1 - Error.
 */
static int gl_interpret_char(GetLine *gl, char first_char)
{
  char keyseq[GL_KEY_MAX+1]; /* A special key sequence being read */
  int nkey=0;                /* The number of characters in the key sequence */
  int count;                 /* The repeat count of an action function */
  int ret;                   /* The return value of an action function */
  int i;
/*
 * Get the first character.
 */
  char c = first_char;
/*
 * If editing is disabled, just add newly entered characters to the
 * input line buffer, and watch for the end of the line.
 */
  if(gl->editor == GL_NO_EDITOR) {
    gl_discard_chars(gl, 1);
    if(gl->ntotal >= gl->linelen)
      return 0;
    if(c == '\n' || c == '\r')
      return gl_newline(gl, 1, NULL);
    gl_buffer_char(gl, c, gl->ntotal);
    return 0;
  };
/*
 * If the user is in the process of specifying a repeat count and the
 * new character is a digit, increment the repeat count accordingly.
 */
  if(gl->number >= 0 && isdigit((int)(unsigned char) c)) {
    gl_discard_chars(gl, 1);
    return gl_digit_argument(gl, c, NULL);
/*
 * In vi command mode, all key-sequences entered need to be
 * either implicitly or explicitly prefixed with an escape character.
 */
  } else if(gl->vi.command && c != GL_ESC_CHAR) {
    keyseq[nkey++] = GL_ESC_CHAR;
/*
 * If the first character of the sequence is a printable character,
 * then to avoid confusion with the special "up", "down", "left"
 * or "right" cursor key bindings, we need to prefix the
 * printable character with a backslash escape before looking it up.
 */
  } else if(!IS_META_CHAR(c) && !IS_CTRL_CHAR(c)) {
    keyseq[nkey++] = '\\';
  };
/*
 * Compose a potentially multiple key-sequence in gl->keyseq.
 */
  while(nkey < GL_KEY_MAX) {
    KtAction *action; /* An action function */
    KeySym *keysym;   /* The symbol-table entry of a key-sequence */
    int nsym;         /* The number of ambiguously matching key-sequences */
/*
 * If the character is an unprintable meta character, split it
 * into two characters, an escape character and the character
 * that was modified by the meta key.
 */
    if(IS_META_CHAR(c)) {
      keyseq[nkey++] = GL_ESC_CHAR;
      c = META_TO_CHAR(c);
      continue;
    };
/*
 * Append the latest character to the key sequence.
 */
    keyseq[nkey++] = c;
/*
 * When doing vi-style editing, an escape at the beginning of any binding
 * switches to command mode.
 */
    if(keyseq[0] == GL_ESC_CHAR && !gl->vi.command)
      gl_vi_command_mode(gl);
/*
 * Lookup the key sequence.
 */
    switch(_kt_lookup_keybinding(gl->bindings, keyseq, nkey, &keysym, &nsym)) {
    case KT_EXACT_MATCH:
/*
 * Get the matching action function.
 */
      action = keysym->actions + keysym->binder;
/*
 * Get the repeat count, passing the last keystroke if executing the
 * digit-argument action.
 */
      if(action->fn == gl_digit_argument) {
	count = c;
      } else {
	count = gl->number >= 0 ? gl->number : 1;
      };
/*
 * Record the function that is being invoked.
 */
      gl->current_action = *action;
      gl->current_count = count;
/*
 * Mark the current line as not yet preserved for use by the vi undo command.
 */
      gl->vi.undo.saved = 0;
      gl->vi.repeat.saved = 0;
/*
 * Execute the action function. Note the action function can tell
 * whether the provided repeat count was defaulted or specified
 * explicitly by looking at whether gl->number is -1 or not. If
 * it is negative, then no repeat count was specified by the user.
 */
      ret = action->fn(gl, count, action->data);
/*
 * In server mode, the action will return immediately if it tries to
 * read input from the terminal, and no input is currently available.
 * If this happens, abort. Note that gl_get_input_line() will rewind
 * the read-ahead buffer to allow the next call to redo the function
 * from scratch.
 */
      if(gl->rtn_status == GLR_BLOCKED && gl->pending_io==GLP_READ)
	return 1;
/*
 * Discard the now processed characters from the key sequence buffer.
 */
      gl_discard_chars(gl, gl->nread);
/*
 * If the latest action function wasn't a history action, cancel any
 * current history search.
 */
      if(gl->last_search != gl->keyseq_count)
	_glh_cancel_search(gl->glh);
/*
 * Reset the repeat count after running action functions.
 */
      if(action->fn != gl_digit_argument)
	gl->number = -1;
      return ret ? 1 : 0;
      break;
    case KT_AMBIG_MATCH:    /* Ambiguous match - so read the next character */
      if(gl_read_terminal(gl, 1, &c))
	return 1;
      break;
    case KT_NO_MATCH:
/*
 * If the first character looked like it might be a prefix of a key-sequence
 * but it turned out not to be, ring the bell to tell the user that it
 * wasn't recognised.
 */
      if(keyseq[0] != '\\' && keyseq[0] != '\t') {
	gl_ring_bell(gl, 1, NULL);
      } else {
/*
 * The user typed a single printable character that doesn't match
 * the start of any keysequence, so add it to the line in accordance
 * with the current repeat count.
 */
	count = gl->number >= 0 ? gl->number : 1;
	for(i=0; i<count; i++)
	  gl_add_char_to_line(gl, first_char);
	gl->number = -1;
      };
      gl_discard_chars(gl, 1);
      _glh_cancel_search(gl->glh);
      return 0;
      break;
    case KT_BAD_MATCH:
      gl_ring_bell(gl, 1, NULL);
      gl_discard_chars(gl, gl->nread);
      _glh_cancel_search(gl->glh);
      return 1;
      break;
    };
  };
/*
 * If the key sequence was too long to match, ring the bell, then
 * discard the first character, so that the next attempt to match a
 * key-sequence continues with the next key press. In practice this
 * shouldn't happen, since one isn't allowed to bind action functions
 * to keysequences that are longer than GL_KEY_MAX.
 */
  gl_ring_bell(gl, 1, NULL);
  gl_discard_chars(gl, 1);
  return 0;
}

/*.......................................................................
 * Configure the application and/or user-specific behavior of
 * gl_get_line().
 *
 * Note that calling this function between calling new_GetLine() and
 * the first call to gl_get_line(), disables the otherwise automatic
 * reading of ~/.teclarc on the first call to gl_get_line().
 *
 * Input:
 *  gl             GetLine *  The resource object of this library.
 *  app_string  const char *  Either NULL, or a string containing one
 *                            or more .teclarc command lines, separated
 *                            by newline characters. This can be used to
 *                            establish an application-specific
 *                            configuration, without the need for an external
 *                            file. This is particularly useful in embedded
 *                            environments where there is no filesystem.
 *  app_file    const char *  Either NULL, or the pathname of an
 *                            application-specific .teclarc file. The
 *                            contents of this file, if provided, are
 *                            read after the contents of app_string[].
 *  user_file   const char *  Either NULL, or the pathname of a
 *                            user-specific .teclarc file. Except in
 *                            embedded applications, this should
 *                            usually be "~/.teclarc".
 * Output:
 *  return             int    0 - OK.
 *                            1 - Bad argument(s).
 */
int gl_configure_getline(GetLine *gl, const char *app_string,
			 const char *app_file, const char *user_file)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_configure_getline() */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Execute the private body of the function while signals are blocked.
 */
  status = _gl_configure_getline(gl, app_string, app_file, user_file);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the gl_configure_getline() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_configure_getline(GetLine *gl, const char *app_string,
				 const char *app_file, const char *user_file)
{
/*
 * Mark getline as having been explicitly configured.
 */
  gl->configured = 1;
/*
 * Start by parsing the configuration string, if provided.
 */
  if(app_string)
    (void) _gl_read_config_string(gl, app_string, KTB_NORM);
/*
 * Now parse the application-specific configuration file, if provided.
 */
  if(app_file)
    (void) _gl_read_config_file(gl, app_file, KTB_NORM);
/*
 * Finally, parse the user-specific configuration file, if provided.
 */
  if(user_file)
    (void) _gl_read_config_file(gl, user_file, KTB_USER);
/*
 * Record the names of the configuration files to allow them to
 * be re-read if requested at a later time.
 */
  if(gl_record_string(&gl->app_file, app_file) ||
     gl_record_string(&gl->user_file, user_file)) {
    errno = ENOMEM;
    _err_record_msg(gl->err,
	   "Insufficient memory to record tecla configuration file names",
	   END_ERR_MSG);
    return 1;
  };
  return 0;
}

/*.......................................................................
 * Replace a malloc'd string (or NULL), with another malloc'd copy of
 * a string (or NULL).
 *
 * Input:
 *  sptr          char **  On input if *sptr!=NULL, *sptr will be
 *                         free'd and *sptr will be set to NULL. Then,
 *                         on output, if string!=NULL a malloc'd copy
 *                         of this string will be assigned to *sptr.
 *  string  const char *   The string to be copied, or NULL to simply
 *                         discard any existing string.
 * Output:
 *  return         int     0 - OK.
 *                         1 - Malloc failure (no error message is generated).
 */
static int gl_record_string(char **sptr, const char *string)
{
/*
 * If the original string is the same string, don't do anything.
 */
  if(*sptr == string || (*sptr && string && strcmp(*sptr, string)==0))
    return 0;
/*
 * Discard any existing cached string.
 */
  if(*sptr) {
    free(*sptr);
    *sptr = NULL;
  };
/*
 * Allocate memory for a copy of the specified string.
 */
  if(string) {
    size_t ssz = strlen(string) + 1;
    *sptr = (char *) malloc(ssz);
    if(!*sptr)
      return 1;
/*
 * Copy the string.
 */
    strlcpy(*sptr, string, ssz);
  };
  return 0;
}

#ifndef HIDE_FILE_SYSTEM
/*.......................................................................
 * Re-read any application-specific and user-specific files previously
 * specified via the gl_configure_getline() function.
 */
static KT_KEY_FN(gl_read_init_files)
{
  return _gl_configure_getline(gl, NULL, gl->app_file, gl->user_file);
}
#endif

/*.......................................................................
 * Save the contents of the history buffer to a given new file.
 *
 * Input:
 *  gl             GetLine *  The resource object of this library.
 *  filename    const char *  The name of the new file to write to.
 *  comment     const char *  Extra information such as timestamps will
 *                            be recorded on a line started with this
 *                            string, the idea being that the file can
 *                            double as a command file. Specify "" if
 *                            you don't care.
 *  max_lines          int    The maximum number of lines to save, or -1
 *                            to save all of the lines in the history
 *                            list.
 * Output:
 *  return             int     0 - OK.
 *                             1 - Error.
 */
int gl_save_history(GetLine *gl, const char *filename, const char *comment,
		    int max_lines)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_save_history() */
/*
 * Check the arguments.
 */
  if(!gl || !filename || !comment) {
    if(gl)
      _err_record_msg(gl->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Execute the private body of the function while signals are blocked.
 */
  status = _gl_save_history(gl, filename, comment, max_lines);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the gl_save_history() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_save_history(GetLine *gl, const char *filename,
			    const char *comment, int max_lines)
{
/*
 * If filesystem access is to be excluded, then history files can't
 * be written.
 */
#ifdef WITHOUT_FILE_SYSTEM
  _err_record_msg(gl->err, "Can't save history without filesystem access",
		  END_ERR_MSG);
  errno = EINVAL;
  return 1;
#else
  FileExpansion *expansion; /* The expansion of the filename */
/*
 * Expand the filename.
 */
  expansion = ef_expand_file(gl->ef, filename, -1);
  if(!expansion) {
    gl_print_info(gl, "Unable to expand ", filename, " (",
		  ef_last_error(gl->ef), ").", GL_END_INFO);
    return 1;
  };
/*
 * Attempt to save to the specified file.
 */
  if(_glh_save_history(gl->glh, expansion->files[0], comment, max_lines)) {
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
    return 1;
  };
  return 0;
#endif
}

/*.......................................................................
 * Restore the contents of the history buffer from a given new file.
 *
 * Input:
 *  gl             GetLine *  The resource object of this library.
 *  filename    const char *  The name of the new file to write to.
 *  comment     const char *  This must be the same string that was
 *                            passed to gl_save_history() when the file
 *                            was written.
 * Output:
 *  return             int     0 - OK.
 *                             1 - Error.
 */
int gl_load_history(GetLine *gl, const char *filename, const char *comment)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_load_history() */
/*
 * Check the arguments.
 */
  if(!gl || !filename || !comment) {
    if(gl)
      _err_record_msg(gl->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Execute the private body of the function while signals are blocked.
 */
  status = _gl_load_history(gl, filename, comment);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the gl_load_history() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_load_history(GetLine *gl, const char *filename,
			    const char *comment)
{
/*
 * If filesystem access is to be excluded, then history files can't
 * be read.
 */
#ifdef WITHOUT_FILE_SYSTEM
  _err_record_msg(gl->err, "Can't load history without filesystem access",
		  END_ERR_MSG);
  errno = EINVAL;
  return 1;
#else
  FileExpansion *expansion; /* The expansion of the filename */
/*
 * Expand the filename.
 */
  expansion = ef_expand_file(gl->ef, filename, -1);
  if(!expansion) {
    gl_print_info(gl, "Unable to expand ", filename, " (",
		  ef_last_error(gl->ef), ").", GL_END_INFO);
    return 1;
  };
/*
 * Attempt to load from the specified file.
 */
  if(_glh_load_history(gl->glh, expansion->files[0], comment,
		       gl->cutbuf, gl->linelen+1)) {
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
    gl->cutbuf[0] = '\0';
    return 1;
  };
  gl->cutbuf[0] = '\0';
  return 0;
#endif
}

/*.......................................................................
 * Where possible, register a function and associated data to be called
 * whenever a specified event is seen on a file descriptor.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  fd                int    The file descriptor to watch.
 *  event       GlFdEvent    The type of activity to watch for.
 *  callback  GlFdEventFn *  The function to call when the specified
 *                           event occurs. Setting this to 0 removes
 *                           any existing callback.
 *  data             void *  A pointer to arbitrary data to pass to the
 *                           callback function.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Either gl==NULL, or this facility isn't
 *                               available on the the host system
 *                               (ie. select() isn't available). No
 *                               error message is generated in the latter
 *                               case.
 */
int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,
		GlFdEventFn *callback, void *data)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_watch_fd() */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
  if(fd < 0) {
    _err_record_msg(gl->err, "Error: fd < 0", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Execute the private body of the function while signals are blocked.
 */
  status = _gl_watch_fd(gl, fd, event, callback, data);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the gl_watch_fd() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,
			GlFdEventFn *callback, void *data)
#if !defined(HAVE_SELECT)
{return 1;}               /* The facility isn't supported on this system */
#else
{
  GlFdNode *prev;  /* The node that precedes 'node' in gl->fd_nodes */
  GlFdNode *node;  /* The file-descriptor node being checked */
/*
 * Search the list of already registered fd activity nodes for the specified
 * file descriptor.
 */
  for(prev=NULL,node=gl->fd_nodes; node && node->fd != fd;
      prev=node, node=node->next)
    ;
/*
 * Hasn't a node been allocated for this fd yet?
 */
  if(!node) {
/*
 * If there is no callback to record, just ignore the call.
 */
    if(!callback)
      return 0;
/*
 * Allocate the new node.
 */
    node = (GlFdNode *) _new_FreeListNode(gl->fd_node_mem);
    if(!node) {
      errno = ENOMEM;
      _err_record_msg(gl->err, "Insufficient memory", END_ERR_MSG);
      return 1;
    };
/*
 * Prepend the node to the list.
 */
    node->next = gl->fd_nodes;
    gl->fd_nodes = node;
/*
 * Initialize the node.
 */
    node->fd = fd;
    node->rd.fn = 0;
    node->rd.data = NULL;
    node->ur = node->wr = node->rd;
  };
/*
 * Record the new callback.
 */
  switch(event) {
  case GLFD_READ:
    node->rd.fn = callback;
    node->rd.data = data;
    if(callback)
      FD_SET(fd, &gl->rfds);
    else
      FD_CLR(fd, &gl->rfds);
    break;
  case GLFD_WRITE:
    node->wr.fn = callback;
    node->wr.data = data;
    if(callback)
      FD_SET(fd, &gl->wfds);
    else
      FD_CLR(fd, &gl->wfds);
    break;
  case GLFD_URGENT:
    node->ur.fn = callback;
    node->ur.data = data;
    if(callback)
      FD_SET(fd, &gl->ufds);
    else
      FD_CLR(fd, &gl->ufds);
    break;
  };
/*
 * Keep a record of the largest file descriptor being watched.
 */
  if(fd > gl->max_fd)
    gl->max_fd = fd;
/*
 * If we are deleting an existing callback, also delete the parent
 * activity node if no callbacks are registered to the fd anymore.
 */
  if(!callback) {
    if(!node->rd.fn && !node->wr.fn && !node->ur.fn) {
      if(prev)
	prev->next = node->next;
      else
	gl->fd_nodes = node->next;
      node = (GlFdNode *) _del_FreeListNode(gl->fd_node_mem, node);
    };
  };
  return 0;
}
#endif

/*.......................................................................
 * On systems with the select() system call, the gl_inactivity_timeout()
 * function provides the option of setting (or cancelling) an
 * inactivity timeout. Inactivity, in this case, refers both to
 * terminal input received from the user, and to I/O on any file
 * descriptors registered by calls to gl_watch_fd(). If at any time,
 * no activity is seen for the requested time period, the specified
 * timeout callback function is called. On returning, this callback
 * returns a code which tells gl_get_line() what to do next. Note that
 * each call to gl_inactivity_timeout() replaces any previously installed
 * timeout callback, and that specifying a callback of 0, turns off
 * inactivity timing.
 *
 * Beware that although the timeout argument includes a nano-second
 * component, few computer clocks presently have resolutions finer
 * than a few milliseconds, so asking for less than a few milliseconds
 * is equivalent to zero on a lot of systems.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  callback  GlTimeoutFn *  The function to call when the inactivity
 *                           timeout is exceeded. To turn off
 *                           inactivity timeouts altogether, send 0.
 *  data             void *  A pointer to arbitrary data to pass to the
 *                           callback function.
 *  sec     unsigned long    The number of whole seconds in the timeout.
 *  nsec    unsigned long    The fractional number of seconds in the
 *                           timeout, expressed in nano-seconds (see
 *                           the caveat above).
 * Output:
 *  return            int    0 - OK.
 *                           1 - Either gl==NULL, or this facility isn't
 *                               available on the the host system
 *                               (ie. select() isn't available). No
 *                               error message is generated in the latter
 *                               case.
 */
int gl_inactivity_timeout(GetLine *gl, GlTimeoutFn *timeout_fn, void *data,
		   unsigned long sec, unsigned long nsec)
#if !defined(HAVE_SELECT)
{return 1;}               /* The facility isn't supported on this system */
#else
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Install a new timeout?
 */
  if(timeout_fn) {
    gl->timer.dt.tv_sec = sec;
    gl->timer.dt.tv_usec = nsec / 1000;
    gl->timer.fn = timeout_fn;
    gl->timer.data = data;
  } else {
    gl->timer.fn = 0;
    gl->timer.data = NULL;
  };
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return 0;
}
#endif

/*.......................................................................
 * When select() is available, this is a private function of
 * gl_read_input() which responds to file-descriptor events registered by
 * the caller. Note that it assumes that it is being called from within
 * gl_read_input()'s sigsetjump() clause.
 *
 * Input:
 *  gl    GetLine *  The resource object of this module.
 *  fd        int    The file descriptor to be watched for user input.
 * Output:
 *  return    int    0 - OK.
 *                   1 - An error occurred.
 */
static int gl_event_handler(GetLine *gl, int fd)
{
#if !defined(HAVE_SELECT)
  return 0;
#else
/*
 * Set up a zero-second timeout.
 */
  struct timeval zero;
  zero.tv_sec = zero.tv_usec = 0;
/*
 * If at any time no external callbacks remain, quit the loop return,
 * so that we can simply wait in read(). This is designed as an
 * optimization for when no callbacks have been registered on entry to
 * this function, but since callbacks can delete themselves, it can
 * also help later.
 */
  while(gl->fd_nodes || gl->timer.fn) {
    int nready;   /* The number of file descriptors that are ready for I/O */
/*
 * Get the set of descriptors to be watched.
 */
    fd_set rfds = gl->rfds;
    fd_set wfds = gl->wfds;
    fd_set ufds = gl->ufds;
/*
 * Get the appropriate timeout.
 */
    struct timeval dt = gl->timer.fn ? gl->timer.dt : zero;
/*
 * Add the specified user-input file descriptor to the set that is to
 * be watched.
 */
    FD_SET(fd, &rfds);
/*
 * Unblock the signals that we are watching, while select is blocked
 * waiting for I/O.
 */
    gl_catch_signals(gl);
/*
 * Wait for activity on any of the file descriptors.
 */
    nready = select(gl->max_fd+1, &rfds, &wfds, &ufds,
	    (gl->timer.fn || gl->io_mode==GL_SERVER_MODE) ? &dt : NULL);
/*
 * We don't want to do a longjmp in the middle of a callback that
 * might be modifying global or heap data, so block all the signals
 * that we are trapping before executing callback functions. Note that
 * the caller will unblock them again when it needs to, so there is
 * no need to undo this before returning.
 */
    gl_mask_signals(gl, NULL);
/*
 * If select() returns but none of the file descriptors are reported
 * to have activity, then select() timed out.
 */
    if(nready == 0) {
/*
 * Note that in non-blocking server mode, the inactivity timer is used
 * to allow I/O to block for a specified amount of time, so in this
 * mode we return the postponed blocked status when an abort is
 * requested.
 */
      if(gl_call_timeout_handler(gl)) {
	return 1;
      } else if(gl->io_mode == GL_SERVER_MODE) {
	gl_record_status(gl, GLR_BLOCKED, BLOCKED_ERRNO);
	return 1;
      };
/*
 * If nready < 0, this means an error occurred.
 */
    } else if(nready < 0) {
      if(errno != EINTR) {
	gl_record_status(gl, GLR_ERROR, errno);
	return 1;
      };
/*
 * If the user-input file descriptor has data available, return.
 */
    } else if(FD_ISSET(fd, &rfds)) {
      return 0;
/*
 * Check for activity on any of the file descriptors registered by the
 * calling application, and call the associated callback functions.
 */
    } else {
      GlFdNode *node;   /* The fd event node being checked */
/*
 * Search the list for the file descriptor that caused select() to return.
 */
      for(node=gl->fd_nodes; node; node=node->next) {
/*
 * Is there urgent out of band data waiting to be read on fd?
 */
	if(node->ur.fn && FD_ISSET(node->fd, &ufds)) {
	  if(gl_call_fd_handler(gl, &node->ur, node->fd, GLFD_URGENT))
	    return 1;
	  break;  /* The callback may have changed the list of nodes */
/*
 * Is the fd readable?
 */
	} else if(node->rd.fn && FD_ISSET(node->fd, &rfds)) {
	  if(gl_call_fd_handler(gl, &node->rd, node->fd, GLFD_READ))
	    return 1;
	  break;  /* The callback may have changed the list of nodes */
/*
 * Is the fd writable?
 */
	} else if(node->wr.fn && FD_ISSET(node->fd, &wfds)) {
	  if(gl_call_fd_handler(gl, &node->wr, node->fd, GLFD_WRITE))
	    return 1;
	  break;  /* The callback may have changed the list of nodes */
	};
      };
    };
/*
 * Just in case the above event handlers asked for the input line to
 * be redrawn, flush any pending output.
 */
    if(gl_flush_output(gl))
      return 1;
  };
  return 0;
}
#endif

#if defined(HAVE_SELECT)
/*.......................................................................
 * This is a private function of gl_event_handler(), used to call a
 * file-descriptor callback.
 *
 * Input:
 *  gl       GetLine *  The resource object of gl_get_line().
 *  gfh  GlFdHandler *  The I/O handler.
 *  fd           int    The file-descriptor being reported.
 *  event  GlFdEvent    The I/O event being reported.
 * Output:
 *  return       int    0 - OK.
 *                      1 - Error.
 */
static int gl_call_fd_handler(GetLine *gl, GlFdHandler *gfh, int fd,
			      GlFdEvent event)
{
  Termios attr;       /* The terminal attributes */
  int waserr = 0;     /* True after any error */
/*
 * Re-enable conversion of newline characters to carriage-return/linefeed,
 * so that the callback can write to the terminal without having to do
 * anything special.
 */
  if(tcgetattr(gl->input_fd, &attr)) {
    _err_record_msg(gl->err, "tcgetattr error", END_ERR_MSG);
    return 1;
  };
  attr.c_oflag |= OPOST;
  while(tcsetattr(gl->input_fd, TCSADRAIN, &attr)) {
    if(errno != EINTR) {
      _err_record_msg(gl->err, "tcsetattr error", END_ERR_MSG);
      return 1;
    };
  };
/*
 * Invoke the application's callback function.
 */
  switch(gfh->fn(gl, gfh->data, fd, event)) {
  default:
  case GLFD_ABORT:
    gl_record_status(gl, GLR_FDABORT, 0);
    waserr = 1;
    break;
  case GLFD_REFRESH:
    gl_queue_redisplay(gl);
    break;
  case GLFD_CONTINUE:
    break;
  };
/*
 * Disable conversion of newline characters to carriage-return/linefeed.
 */
  attr.c_oflag &= ~(OPOST);
  while(tcsetattr(gl->input_fd, TCSADRAIN, &attr)) {
    if(errno != EINTR) {
      _err_record_msg(gl->err, "tcsetattr error", END_ERR_MSG);
      return 1;
    };
  };
  return waserr;
}

/*.......................................................................
 * This is a private function of gl_event_handler(), used to call a
 * inactivity timer callbacks.
 *
 * Input:
 *  gl       GetLine *  The resource object of gl_get_line().
 * Output:
 *  return       int    0 - OK.
 *                      1 - Error.
 */
static int gl_call_timeout_handler(GetLine *gl)
{
  Termios attr;       /* The terminal attributes */
  int waserr = 0;     /* True after any error */
/*
 * Make sure that there is an inactivity timeout callback.
 */
  if(!gl->timer.fn)
    return 0;
/*
 * Re-enable conversion of newline characters to carriage-return/linefeed,
 * so that the callback can write to the terminal without having to do
 * anything special.
 */
  if(tcgetattr(gl->input_fd, &attr)) {
    _err_record_msg(gl->err, "tcgetattr error", END_ERR_MSG);
    return 1;
  };
  attr.c_oflag |= OPOST;
  while(tcsetattr(gl->input_fd, TCSADRAIN, &attr)) {
    if(errno != EINTR) {
      _err_record_msg(gl->err, "tcsetattr error", END_ERR_MSG);
      return 1;
    };
  };
/*
 * Invoke the application's callback function.
 */
  switch(gl->timer.fn(gl, gl->timer.data)) {
  default:
  case GLTO_ABORT:
    gl_record_status(gl, GLR_TIMEOUT, 0);
    waserr = 1;
    break;
  case GLTO_REFRESH:
    gl_queue_redisplay(gl);
    break;
  case GLTO_CONTINUE:
    break;
  };
/*
 * Disable conversion of newline characters to carriage-return/linefeed.
 */
  attr.c_oflag &= ~(OPOST);
  while(tcsetattr(gl->input_fd, TCSADRAIN, &attr)) {
    if(errno != EINTR) {
      _err_record_msg(gl->err, "tcsetattr error", END_ERR_MSG);
      return 1;
    };
  };
  return waserr;
}
#endif  /* HAVE_SELECT */

/*.......................................................................
 * Switch history groups. History groups represent separate history
 * lists recorded within a single history buffer. Different groups
 * are distinguished by integer identifiers chosen by the calling
 * appplicaton. Initially new_GetLine() sets the group identifier to
 * 0. Whenever a new line is appended to the history list, the current
 * group identifier is recorded with it, and history lookups only
 * consider lines marked with the current group identifier.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  id     unsigned    The new history group identifier.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
int gl_group_history(GetLine *gl, unsigned id)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of this function */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals while we install the new configuration.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * If the group isn't being changed, do nothing.
 */
  if(_glh_get_group(gl->glh) == id) {
    status = 0;
/*
 * Establish the new group.
 */
  } else if(_glh_set_group(gl->glh, id)) {
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
    status = 1;
/*
 * Prevent history information from the previous group being
 * inappropriately used by the next call to gl_get_line().
 */
  } else {
    gl->preload_history = 0;
    gl->last_search = -1;
    status = 0;
  };
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * Display the contents of the history list.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  fp         FILE *  The stdio output stream to write to.
 *  fmt  const char *  A format string. This containing characters to be
 *                     written verbatim, plus any of the following
 *                     format directives:
 *                       %D  -  The date, formatted like 2001-11-20
 *                       %T  -  The time of day, formatted like 23:59:59
 *                       %N  -  The sequential entry number of the
 *                              line in the history buffer.
 *                       %G  -  The number of the history group that
 *                              the line belongs to.
 *                       %%  -  A literal % character.
 *                       %H  -  The history line itself.
 *                     Note that a '\n' newline character is not
 *                     appended by default.
 *  all_groups  int    If true, display history lines from all
 *                     history groups. Otherwise only display
 *                     those of the current history group.
 *  max_lines   int    If max_lines is < 0, all available lines
 *                     are displayed. Otherwise only the most
 *                     recent max_lines lines will be displayed.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
int gl_show_history(GetLine *gl, FILE *fp, const char *fmt, int all_groups,
		    int max_lines)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of this function */
/*
 * Check the arguments.
 */
  if(!gl || !fp || !fmt) {
    if(gl)
      _err_record_msg(gl->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Display the specified history group(s) while signals are blocked.
 */
  status = _glh_show_history(gl->glh, _io_write_stdio, fp, fmt, all_groups,
			     max_lines) || fflush(fp)==EOF;
  if(!status)
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * Update if necessary, and return the current size of the terminal.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  def_ncolumn       int    If the number of columns in the terminal
 *                           can't be determined, substitute this number.
 *  def_nline         int    If the number of lines in the terminal can't
 *                           be determined, substitute this number.
 * Output:
 *  return GlTerminalSize    The current terminal size.
 */
GlTerminalSize gl_terminal_size(GetLine *gl, int def_ncolumn, int def_nline)
{
  GlTerminalSize size;  /* The object to be returned */
  sigset_t oldset;      /* The signals that were blocked on entry */
                        /*  to this function */
/*
 * Block all signals while accessing gl.
 */
  gl_mask_signals(gl, &oldset);
/*
 * Lookup/configure the terminal size.
 */
  _gl_terminal_size(gl, def_ncolumn, def_nline, &size);
/*
 * Restore the process signal mask before returning.
 */
  gl_unmask_signals(gl, &oldset);
  return size;
}

/*.......................................................................
 * This is the private body of the gl_terminal_size() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static void _gl_terminal_size(GetLine *gl, int def_ncolumn, int def_nline,
			      GlTerminalSize *size)
{
  const char *env;      /* The value of an environment variable */
  int n;                /* A number read from env[] */
/*
 * Set the number of lines and columns to non-sensical values so that
 * we know later if they have been set.
 */
  gl->nline = 0;
  gl->ncolumn = 0;
/*
 * Are we reading from a terminal?
 */
  if(gl->is_term) {
/*
 * Ask the terminal directly if possible.
 */
    (void) _gl_update_size(gl);
/*
 * If gl_update_size() couldn't ask the terminal, it will have
 * left gl->nrow and gl->ncolumn unchanged. If these values haven't
 * been changed from their initial values of zero, we need to find
 * a different method to get the terminal size.
 *
 * If the number of lines isn't known yet, first see if the
 * LINES environment ariable exists and specifies a believable number.
 * If this doesn't work, look up the default size in the terminal
 * information database.
 */
    if(gl->nline < 1) {
      if((env = getenv("LINES")) && (n=atoi(env)) > 0)
	gl->nline = n;
#ifdef USE_TERMINFO
      else
	gl->nline = tigetnum((char *)"lines");
#elif defined(USE_TERMCAP)
      else
        gl->nline = tgetnum("li");
#endif
    };
/*
 * If the number of lines isn't known yet, first see if the COLUMNS
 * environment ariable exists and specifies a believable number.  If
 * this doesn't work, look up the default size in the terminal
 * information database.
 */
    if(gl->ncolumn < 1) {
      if((env = getenv("COLUMNS")) && (n=atoi(env)) > 0)
	gl->ncolumn = n;
#ifdef USE_TERMINFO
      else
	gl->ncolumn = tigetnum((char *)"cols");
#elif defined(USE_TERMCAP)
      else
	gl->ncolumn = tgetnum("co");
#endif
    };
  };
/*
 * If we still haven't been able to acquire reasonable values, substitute
 * the default values specified by the caller.
 */
  if(gl->nline <= 0)
    gl->nline = def_nline;
  if(gl->ncolumn <= 0)
    gl->ncolumn = def_ncolumn;
/*
 * Copy the new size into the return value.
 */
  if(size) {
    size->nline = gl->nline;
    size->ncolumn = gl->ncolumn;
  };
  return;
}

/*.......................................................................
 * Resize or delete the history buffer.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  bufsize  size_t    The number of bytes in the history buffer, or 0
 *                     to delete the buffer completely.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Insufficient memory (the previous buffer
 *                         will have been retained). No error message
 *                         will be displayed.
 */
int gl_resize_history(GetLine *gl, size_t bufsize)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of this function */
/*
 * Check the arguments.
 */
  if(!gl)
    return 1;
/*
 * Block all signals while modifying the contents of gl.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Perform the resize while signals are blocked.
 */
  status = _glh_resize_history(gl->glh, bufsize);
  if(status)
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
/*
 * Restore the process signal mask before returning.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * Set an upper limit to the number of lines that can be recorded in the
 * history list, or remove a previously specified limit.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  max_lines   int    The maximum number of lines to allow, or -1 to
 *                     cancel a previous limit and allow as many lines
 *                     as will fit in the current history buffer size.
 */
void gl_limit_history(GetLine *gl, int max_lines)
{
  if(gl) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Apply the limit while signals are blocked.
 */
    _glh_limit_history(gl->glh, max_lines);
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
}

/*.......................................................................
 * Discard either all historical lines, or just those associated with the
 * current history group.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  all_groups  int    If true, clear all of the history. If false,
 *                     clear only the stored lines associated with the
 *                     currently selected history group.
 */
void gl_clear_history(GetLine *gl, int all_groups)
{
  if(gl) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Clear the history buffer while signals are blocked.
 */
    _glh_clear_history(gl->glh, all_groups);
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
}

/*.......................................................................
 * Temporarily enable or disable the gl_get_line() history mechanism.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  enable      int    If true, turn on the history mechanism. If
 *                     false, disable it.
 */
void gl_toggle_history(GetLine *gl, int enable)
{
  if(gl) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Change the history recording mode while signals are blocked.
 */
    _glh_toggle_history(gl->glh, enable);
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
}

/*.......................................................................
 * Lookup a history line by its sequential number of entry in the
 * history buffer.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  id      unsigned long    The identification number of the line to
 *                           be returned, where 0 denotes the first line
 *                           that was entered in the history list, and
 *                           each subsequently added line has a number
 *                           one greater than the previous one. For
 *                           the range of lines currently in the list,
 *                           see the gl_range_of_history() function.
 * Input/Output:
 *  line    GlHistoryLine *  A pointer to the variable in which to
 *                           return the details of the line.
 * Output:
 *  return            int    0 - The line is no longer in the history
 *                               list, and *line has not been changed.
 *                           1 - The requested line can be found in
 *                               *line. Note that line->line is part
 *                               of the history buffer, so a
 *                               private copy should be made if you
 *                               wish to use it after subsequent calls
 *                               to any functions that take *gl as an
 *                               argument.
 */
int gl_lookup_history(GetLine *gl, unsigned long id, GlHistoryLine *line)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of this function */
/*
 * Check the arguments.
 */
  if(!gl)
    return 0;
/*
 * Block all signals while modifying the contents of gl.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Perform the lookup while signals are blocked.
 */
  status = _glh_lookup_history(gl->glh, (GlhLineID) id, &line->line,
			       &line->group, &line->timestamp);
  if(status)
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
/*
 * Restore the process signal mask before returning.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * Query the state of the history list. Note that any of the input/output
 * pointers can be specified as NULL.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  state  GlHistoryState *  A pointer to the variable in which to record
 *                           the return values.
 */
void gl_state_of_history(GetLine *gl, GlHistoryState *state)
{
  if(gl && state) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Lookup the status while signals are blocked.
 */
    _glh_state_of_history(gl->glh, &state->enabled, &state->group,
			  &state->max_lines);
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
}

/*.......................................................................
 * Query the number and range of lines in the history buffer.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  range  GlHistoryRange *  A pointer to the variable in which to record
 *                           the return values. If range->nline=0, the
 *                           range of lines will be given as 0-0.
 */
void gl_range_of_history(GetLine *gl, GlHistoryRange *range)
{
  if(gl && range) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Lookup the information while signals are blocked.
 */
    _glh_range_of_history(gl->glh, &range->oldest, &range->newest,
			  &range->nlines);
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
}

/*.......................................................................
 * Return the size of the history buffer and the amount of the
 * buffer that is currently in use.
 *
 * Input:
 *  gl         GetLine *  The gl_get_line() resource object.
 * Input/Output:
 *  GlHistorySize size *  A pointer to the variable in which to return
 *                        the results.
 */
void gl_size_of_history(GetLine *gl, GlHistorySize *size)
{
  if(gl && size) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Lookup the information while signals are blocked.
 */
    _glh_size_of_history(gl->glh, &size->size, &size->used);
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
}

/*.......................................................................
 * This is the action function that lists the contents of the history
 * list.
 */
static KT_KEY_FN(gl_list_history)
{
/*
 * Start a new line.
 */
  if(gl_start_newline(gl, 1))
    return 1;
/*
 * List history lines that belong to the current group.
 */
  _glh_show_history(gl->glh, gl_write_fn, gl, "%N  %T   %H\r\n", 0,
		    count<=1 ? -1 : count);
/*
 * Arrange for the input line to be redisplayed.
 */
  gl_queue_redisplay(gl);
  return 0;
}

/*.......................................................................
 * Specify whether text that users type should be displayed or hidden.
 * In the latter case, only the prompt is displayed, and the final
 * input line is not archived in the history list.
 *
 * Input:
 *  gl         GetLine *  The gl_get_line() resource object.
 *  enable         int     0 - Disable echoing.
 *                         1 - Enable echoing.
 *                        -1 - Just query the mode without changing it.
 * Output:
 *  return         int    The echoing disposition that was in effect
 *                        before this function was called:
 *                         0 - Echoing was disabled.
 *                         1 - Echoing was enabled.
 */
int gl_echo_mode(GetLine *gl, int enable)
{
  if(gl) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
    int was_echoing; /* The echoing disposition on entry to this function */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Install the new disposition while signals are blocked.
 */
    was_echoing = gl->echo;
    if(enable >= 0)
      gl->echo = enable;
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
/*
 * Return the original echoing disposition.
 */
    return was_echoing;
  };
  return 1;
}

/*.......................................................................
 * Display the prompt.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error.
 */
static int gl_display_prompt(GetLine *gl)
{
  const char *pptr;       /* A pointer into gl->prompt[] */
  unsigned old_attr=0;    /* The current text display attributes */
  unsigned new_attr=0;    /* The requested text display attributes */
/*
 * Temporarily switch to echoing output characters.
 */
  int kept_echo = gl->echo;
  gl->echo = 1;
/*
 * In case the screen got messed up, send a carriage return to
 * put the cursor at the beginning of the current terminal line.
 */
  if(gl_print_control_sequence(gl, 1, gl->bol))
    return 1;
/*
 * Mark the line as partially displayed.
 */
  gl->displayed = 1;
/*
 * Write the prompt, using the currently selected prompt style.
 */
  switch(gl->prompt_style) {
  case GL_LITERAL_PROMPT:
    if(gl_print_string(gl, gl->prompt, '\0'))
      return 1;
    break;
  case GL_FORMAT_PROMPT:
    for(pptr=gl->prompt; *pptr; pptr++) {
/*
 * Does the latest character appear to be the start of a directive?
 */
      if(*pptr == '%') {
/*
 * Check for and act on attribute changing directives.
 */
	switch(pptr[1]) {
/*
 * Add or remove a text attribute from the new set of attributes.
 */
	case 'B': case 'U': case 'S': case 'P': case 'F': case 'V':
	case 'b': case 'u': case 's': case 'p': case 'f': case 'v':
	  switch(*++pptr) {
	  case 'B':           /* Switch to a bold font */
	    new_attr |= GL_TXT_BOLD;
	    break;
	  case 'b':           /* Switch to a non-bold font */
	    new_attr &= ~GL_TXT_BOLD;
	    break;
	  case 'U':           /* Start underlining */
	    new_attr |= GL_TXT_UNDERLINE;
	    break;
	  case 'u':           /* Stop underlining */
	    new_attr &= ~GL_TXT_UNDERLINE;
	    break;
	  case 'S':           /* Start highlighting */
	    new_attr |= GL_TXT_STANDOUT;
	    break;
	  case 's':           /* Stop highlighting */
	    new_attr &= ~GL_TXT_STANDOUT;
	    break;
	  case 'P':           /* Switch to a pale font */
	    new_attr |= GL_TXT_DIM;
	    break;
	  case 'p':           /* Switch to a non-pale font */
	    new_attr &= ~GL_TXT_DIM;
	    break;
	  case 'F':           /* Switch to a flashing font */
	    new_attr |= GL_TXT_BLINK;
	    break;
	  case 'f':           /* Switch to a steady font */
	    new_attr &= ~GL_TXT_BLINK;
	    break;
	  case 'V':           /* Switch to reverse video */
	    new_attr |= GL_TXT_REVERSE;
	    break;
	  case 'v':           /* Switch out of reverse video */
	    new_attr &= ~GL_TXT_REVERSE;
	    break;
	  };
	  continue;
/*
 * A literal % is represented by %%. Skip the leading %.
 */
	case '%':
	  pptr++;
	  break;
	};
      };
/*
 * Many terminals, when asked to turn off a single text attribute, turn
 * them all off, so the portable way to turn one off individually is to
 * explicitly turn them all off, then specify those that we want from
 * scratch.
 */
      if(old_attr & ~new_attr) {
	if(gl_print_control_sequence(gl, 1, gl->text_attr_off))
	  return 1;
	old_attr = 0;
      };
/*
 * Install new text attributes?
 */
      if(new_attr != old_attr) {
	if(new_attr & GL_TXT_BOLD && !(old_attr & GL_TXT_BOLD) &&
	   gl_print_control_sequence(gl, 1, gl->bold))
	  return 1;
	if(new_attr & GL_TXT_UNDERLINE && !(old_attr & GL_TXT_UNDERLINE) &&
	   gl_print_control_sequence(gl, 1, gl->underline))
	  return 1;
	if(new_attr & GL_TXT_STANDOUT && !(old_attr & GL_TXT_STANDOUT) &&
	   gl_print_control_sequence(gl, 1, gl->standout))
	  return 1;
	if(new_attr & GL_TXT_DIM && !(old_attr & GL_TXT_DIM) &&
	   gl_print_control_sequence(gl, 1, gl->dim))
	  return 1;
	if(new_attr & GL_TXT_REVERSE && !(old_attr & GL_TXT_REVERSE) &&
	   gl_print_control_sequence(gl, 1, gl->reverse))
	  return 1;
	if(new_attr & GL_TXT_BLINK && !(old_attr & GL_TXT_BLINK) &&
	   gl_print_control_sequence(gl, 1, gl->blink))
	  return 1;
	old_attr = new_attr;
      };
/*
 * Display the latest character.
 */
      if(gl_print_char(gl, *pptr, pptr[1]))
	return 1;
    };
/*
 * Turn off all text attributes now that we have finished drawing
 * the prompt.
 */
    if(gl_print_control_sequence(gl, 1, gl->text_attr_off))
      return 1;
    break;
  };
/*
 * Restore the original echo mode.
 */
  gl->echo = kept_echo;
/*
 * The prompt has now been displayed at least once.
 */
  gl->prompt_changed = 0;
  return 0;
}

/*.......................................................................
 * This function can be called from gl_get_line() callbacks to have
 * the prompt changed when they return. It has no effect if gl_get_line()
 * is not currently being invoked.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  prompt  const char *  The new prompt.
 */
void gl_replace_prompt(GetLine *gl, const char *prompt)
{
  if(gl) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Replace the prompt.
 */
    _gl_replace_prompt(gl, prompt);
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
}

/*.......................................................................
 * This is the private body of the gl_replace_prompt() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static void _gl_replace_prompt(GetLine *gl, const char *prompt)
{
  size_t size;

/*
 * Substitute an empty prompt?
 */
  if(!prompt)
    prompt = "";
/*
 * Gaurd against aliasing between prompt and gl->prompt.
 */
  if(gl->prompt != prompt) {
/*
 * Get the length of the new prompt string.
 */
    size_t slen = strlen(prompt);
/*
 * If needed, allocate a new buffer for the prompt string.
 */
    size = sizeof(char) * (slen + 1);
    if(!gl->prompt || slen > strlen(gl->prompt)) {
      char *new_prompt = gl->prompt ? realloc(gl->prompt, size) : malloc(size);
      if(!new_prompt)
	return;
      gl->prompt = new_prompt;
    };
/*
 * Make a copy of the new prompt.
 */
    strlcpy(gl->prompt, prompt, size);
  };
/*
 * Record the statistics of the new prompt.
 */
  gl->prompt_len = gl_displayed_prompt_width(gl);
  gl->prompt_changed = 1;
  gl_queue_redisplay(gl);
  return;
}

/*.......................................................................
 * Work out the length of the current prompt on the terminal, according
 * to the current prompt formatting style.
 *
 * Input:
 *  gl       GetLine *  The resource object of this library.
 * Output:
 *  return       int    The number of displayed characters.
 */
static int gl_displayed_prompt_width(GetLine *gl)
{
  int slen=0;         /* The displayed number of characters */
  const char *pptr;   /* A pointer into prompt[] */
/*
 * The length differs according to the prompt display style.
 */
  switch(gl->prompt_style) {
  case GL_LITERAL_PROMPT:
    return gl_displayed_string_width(gl, gl->prompt, -1, 0);
    break;
  case GL_FORMAT_PROMPT:
/*
 * Add up the length of the displayed string, while filtering out
 * attribute directives.
 */
    for(pptr=gl->prompt; *pptr; pptr++) {
/*
 * Does the latest character appear to be the start of a directive?
 */
      if(*pptr == '%') {
/*
 * Check for and skip attribute changing directives.
 */
	switch(pptr[1]) {
	case 'B': case 'b': case 'U': case 'u': case 'S': case 's':
	  pptr++;
	  continue;
/*
 * A literal % is represented by %%. Skip the leading %.
 */
	case '%':
	  pptr++;
	  break;
	};
      };
      slen += gl_displayed_char_width(gl, *pptr, slen);
    };
    break;
  };
  return slen;
}

/*.......................................................................
 * Specify whether to heed text attribute directives within prompt
 * strings.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  style  GlPromptStyle    The style of prompt (see the definition of
 *                          GlPromptStyle in libtecla.h for details).
 */
void gl_prompt_style(GetLine *gl, GlPromptStyle style)
{
  if(gl) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Install the new style in gl while signals are blocked.
 */
    if(style != gl->prompt_style) {
      gl->prompt_style = style;
      gl->prompt_len = gl_displayed_prompt_width(gl);
      gl->prompt_changed = 1;
      gl_queue_redisplay(gl);
    };
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
}

/*.......................................................................
 * Tell gl_get_line() how to respond to a given signal. This can be used
 * both to override the default responses to signals that gl_get_line()
 * normally catches and to add new signals to the list that are to be
 * caught.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  signo            int    The number of the signal to be caught.
 *  flags       unsigned    A bitwise union of GlSignalFlags enumerators.
 *  after  GlAfterSignal    What to do after the application's signal
 *                          handler has been called.
 *  errno_value      int    The value to set errno to.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
int gl_trap_signal(GetLine *gl, int signo, unsigned flags,
		   GlAfterSignal after, int errno_value)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of this function */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals while modifying the contents of gl.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Perform the modification while signals are blocked.
 */
  status = _gl_trap_signal(gl, signo, flags, after, errno_value);
/*
 * Restore the process signal mask before returning.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the gl_trap_signal() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_trap_signal(GetLine *gl, int signo, unsigned flags,
			   GlAfterSignal after, int errno_value)
{
  GlSignalNode *sig;
/*
 * Complain if an attempt is made to trap untrappable signals.
 * These would otherwise cause errors later in gl_mask_signals().
 */
  if(0
#ifdef SIGKILL
     || signo==SIGKILL
#endif
#ifdef SIGBLOCK
     || signo==SIGBLOCK
#endif
     ) {
    return 1;
  };
/*
 * See if the signal has already been registered.
 */
  for(sig=gl->sigs; sig && sig->signo != signo; sig = sig->next)
    ;
/*
 * If the signal hasn't already been registered, allocate a node for
 * it.
 */
  if(!sig) {
    sig = (GlSignalNode *) _new_FreeListNode(gl->sig_mem);
    if(!sig)
      return 1;
/*
 * Add the new node to the head of the list.
 */
    sig->next = gl->sigs;
    gl->sigs = sig;
/*
 * Record the signal number.
 */
    sig->signo = signo;
/*
 * Create a signal set that includes just this signal.
 */
    sigemptyset(&sig->proc_mask);
    if(sigaddset(&sig->proc_mask, signo) == -1) {
      _err_record_msg(gl->err, "sigaddset error", END_ERR_MSG);
      sig = (GlSignalNode *) _del_FreeListNode(gl->sig_mem, sig);
      return 1;
    };
/*
 * Add the signal to the bit-mask of signals being trapped.
 */
    sigaddset(&gl->all_signal_set, signo);
  };
/*
 * Record the new signal attributes.
 */
  sig->flags = flags;
  sig->after = after;
  sig->errno_value = errno_value;
  return 0;
}

/*.......................................................................
 * Remove a signal from the list of signals that gl_get_line() traps.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  signo            int    The number of the signal to be ignored.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
int gl_ignore_signal(GetLine *gl, int signo)
{
  GlSignalNode *sig;  /* The gl->sigs list node of the specified signal */
  GlSignalNode *prev; /* The node that precedes sig in the list */
  sigset_t oldset;    /* The signals that were blocked on entry to this */
                      /*  function. */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals while modifying the contents of gl.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Find the node of the gl->sigs list which records the disposition
 * of the specified signal.
 */
  for(prev=NULL,sig=gl->sigs; sig && sig->signo != signo;
      prev=sig,sig=sig->next)
    ;
  if(sig) {
/*
 * Remove the node from the list.
 */
    if(prev)
      prev->next = sig->next;
    else
      gl->sigs = sig->next;
/*
 * Return the node to the freelist.
 */
    sig = (GlSignalNode *) _del_FreeListNode(gl->sig_mem, sig);
/*
 * Remove the signal from the bit-mask union of signals being trapped.
 */
    sigdelset(&gl->all_signal_set, signo);
  };
/*
 * Restore the process signal mask before returning.
 */
  gl_unmask_signals(gl, &oldset);
  return 0;
}

/*.......................................................................
 * This function is called when an input line has been completed. It
 * appends the specified newline character, terminates the line,
 * records the line in the history buffer if appropriate, and positions
 * the terminal cursor at the start of the next line.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  newline_char     int    The newline character to add to the end
 *                          of the line.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
static int gl_line_ended(GetLine *gl, int newline_char)
{
/*
 * If the newline character is printable, display it at the end of
 * the line, and add it to the input line buffer.
 */
  if(isprint((int)(unsigned char) newline_char)) {
    if(gl_end_of_line(gl, 1, NULL) || gl_add_char_to_line(gl, newline_char))
      return 1;
  } else {
/*
 * Otherwise just append a newline character to the input line buffer.
 */
    newline_char = '\n';
    gl_buffer_char(gl, newline_char, gl->ntotal);
  };
/*
 * Add the line to the history buffer if it was entered with a
 * newline character.
 */
  if(gl->echo && gl->automatic_history && newline_char=='\n')
    (void) _gl_append_history(gl, gl->line);
/*
 * Except when depending on the system-provided line editing, start a new
 * line after the end of the line that has just been entered.
 */
  if(gl->editor != GL_NO_EDITOR && gl_start_newline(gl, 1))
    return 1;
/*
 * Record the successful return status.
 */
  gl_record_status(gl, GLR_NEWLINE, 0);
/*
 * Attempt to flush any pending output.
 */
  (void) gl_flush_output(gl);
/*
 * The next call to gl_get_line() will write the prompt for a new line
 * (or continue the above flush if incomplete), so if we manage to
 * flush the terminal now, report that we are waiting to write to the
 * terminal.
 */
  gl->pending_io = GLP_WRITE;
  return 0;
}

/*.......................................................................
 * Return the last signal that was caught by the most recent call to
 * gl_get_line(), or -1 if no signals were caught. This is useful if
 * gl_get_line() returns errno=EINTR and you need to find out what signal
 * caused it to abort.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 * Output:
 *  return           int    The last signal caught by the most recent
 *                          call to gl_get_line(), or -1 if no signals
 *                          were caught.
 */
int gl_last_signal(GetLine *gl)
{
  int signo = -1;   /* The requested signal number */
  if(gl) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Access gl now that signals are blocked.
 */
    signo = gl->last_signal;
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
  return signo;
}

/*.......................................................................
 * Prepare to edit a new line.
 *
 * Input:
 *  gl         GetLine *  The resource object of this library.
 *  prompt        char *  The prompt to prefix the line with, or NULL to
 *                        use the same prompt that was used by the previous
 *                        line.
 *  start_line    char *  The initial contents of the input line, or NULL
 *                        if it should start out empty.
 *  start_pos      int    If start_line isn't NULL, this specifies the
 *                        index of the character over which the cursor
 *                        should initially be positioned within the line.
 *                        If you just want it to follow the last character
 *                        of the line, send -1.
 * Output:
 *  return    int    0 - OK.
 *                   1 - Error.
 */
static int gl_present_line(GetLine *gl, const char *prompt,
			   const char *start_line, int start_pos)
{
/*
 * Reset the properties of the line.
 */
  gl_reset_input_line(gl);
/*
 * Record the new prompt and its displayed width.
 */
  if(prompt)
    _gl_replace_prompt(gl, prompt);
/*
 * Reset the history search pointers.
 */
  if(_glh_cancel_search(gl->glh)) {
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
    return 1;
  };
/*
 * If the previous line was entered via the repeat-history action,
 * preload the specified history line.
 */
  if(gl->preload_history) {
    gl->preload_history = 0;
    if(gl->preload_id) {
      if(_glh_recall_line(gl->glh, gl->preload_id, gl->line, gl->linelen+1)) {
	gl_update_buffer(gl);          /* Compute gl->ntotal etc.. */
	gl->buff_curpos = gl->ntotal;
      } else {
	gl_truncate_buffer(gl, 0);
      };
      gl->preload_id = 0;
    };
/*
 * Present a specified initial line?
 */
  } else if(start_line) {
    char *cptr;      /* A pointer into gl->line[] */
/*
 * Measure the length of the starting line.
 */
    int start_len = strlen(start_line);
/*
 * If the length of the line is greater than the available space,
 * truncate it.
 */
    if(start_len > gl->linelen)
      start_len = gl->linelen;
/*
 * Load the line into the buffer.
 */
    if(start_line != gl->line)
      gl_buffer_string(gl, start_line, start_len, 0);
/*
 * Strip off any trailing newline and carriage return characters.
 */
    for(cptr=gl->line + gl->ntotal - 1; cptr >= gl->line &&
	(*cptr=='\n' || *cptr=='\r'); cptr--,gl->ntotal--)
      ;
    gl_truncate_buffer(gl, gl->ntotal < 0 ? 0 : gl->ntotal);
/*
 * Where should the cursor be placed within the line?
 */
    if(start_pos < 0 || start_pos > gl->ntotal) {
      if(gl_place_cursor(gl, gl->ntotal))
	return 1;
    } else {
      if(gl_place_cursor(gl, start_pos))
	return 1;
    };
/*
 * Clear the input line?
 */
  } else {
    gl_truncate_buffer(gl, 0);
  };
/*
 * Arrange for the line to be displayed by gl_flush_output().
 */
  gl_queue_redisplay(gl);
/*
 * Update the display.
 */
  return gl_flush_output(gl);
}

/*.......................................................................
 * Reset all line input parameters for a new input line.
 *
 * Input:
 *  gl      GetLine *  The line editor resource object.
 */
static void gl_reset_input_line(GetLine *gl)
{
  gl->ntotal = 0;
  gl->line[0] = '\0';
  gl->buff_curpos = 0;
  gl->term_curpos = 0;
  gl->term_len = 0;
  gl->insert_curpos = 0;
  gl->number = -1;
  gl->displayed = 0;
  gl->endline = 0;
  gl->redisplay = 0;
  gl->postpone = 0;
  gl->nbuf = 0;
  gl->nread = 0;
  gl->vi.command = 0;
  gl->vi.undo.line[0] = '\0';
  gl->vi.undo.ntotal = 0;
  gl->vi.undo.buff_curpos = 0;
  gl->vi.repeat.action.fn = 0;
  gl->vi.repeat.action.data = 0;
  gl->last_signal = -1;
}

/*.......................................................................
 * Print an informational message to the terminal, after starting a new
 * line.
 *
 * Input:
 *  gl      GetLine *  The line editor resource object.
 *  ...  const char *  Zero or more strings to be printed.
 *  ...        void *  The last argument must always be GL_END_INFO.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
static int gl_print_info(GetLine *gl, ...)
{
  va_list ap;     /* The variable argument list */
  const char *s;  /* The string being printed */
  int waserr = 0; /* True after an error */
/*
 * Only display output when echoing is on.
 */
  if(gl->echo) {
/*
 * Skip to the start of the next empty line before displaying the message.
 */
    if(gl_start_newline(gl, 1))
      return 1;
/*
 * Display the list of provided messages.
 */
    va_start(ap, gl);
    while(!waserr && (s = va_arg(ap, const char *)) != GL_END_INFO)
      waserr = gl_print_raw_string(gl, 1, s, -1);
    va_end(ap);
/*
 * Start a newline.
 */
    waserr = waserr || gl_print_raw_string(gl, 1, "\n\r", -1);
/*
 * Arrange for the input line to be redrawn.
 */
    gl_queue_redisplay(gl);
  };
  return waserr;
}

/*.......................................................................
 * Go to the start of the next empty line, ready to output miscellaneous
 * text to the screen.
 *
 * Note that when async-signal safety is required, the 'buffered'
 * argument must be 0.
 *
 * Input:
 *  gl          GetLine *  The line editor resource object.
 *  buffered        int    If true, used buffered I/O when writing to
 *                         the terminal. Otherwise use async-signal-safe
 *                         unbuffered I/O.
 * Output:
 *  return          int    0 - OK.
 *                         1 - Error.
 */
static int gl_start_newline(GetLine *gl, int buffered)
{
  int waserr = 0;  /* True after any I/O error */
/*
 * Move the cursor to the start of the terminal line that follows the
 * last line of the partially enterred line. In order that this
 * function remain async-signal safe when write_fn is signal safe, we
 * can't call our normal output functions, since they call tputs(),
 * who's signal saftey isn't defined. Fortunately, we can simply use
 * \r and \n to move the cursor to the right place.
 */
  if(gl->displayed) {   /* Is an input line currently displayed? */
/*
 * On which terminal lines are the cursor and the last character of the
 * input line?
 */
    int curs_line = gl->term_curpos / gl->ncolumn;
    int last_line = gl->term_len / gl->ncolumn;
/*
 * Move the cursor to the start of the line that follows the last
 * terminal line that is occupied by the input line.
 */
    for( ; curs_line < last_line + 1; curs_line++)
      waserr = waserr || gl_print_raw_string(gl, buffered, "\n", 1);
    waserr = waserr || gl_print_raw_string(gl, buffered, "\r", 1);
/*
 * Mark the line as no longer displayed.
 */
    gl_line_erased(gl);
  };
  return waserr;
}

/*.......................................................................
 * The callback through which all terminal output is routed.
 * This simply appends characters to a queue buffer, which is
 * subsequently flushed to the output channel by gl_flush_output().
 *
 * Input:
 *  data     void *  The pointer to a GetLine line editor resource object
 *                   cast to (void *).
 *  s  const char *  The string to be written.
 *  n         int    The number of characters to write from s[].
 * Output:
 *  return    int    The number of characters written. This will always
 *                   be equal to 'n' unless an error occurs.
 */
static GL_WRITE_FN(gl_write_fn)
{
  GetLine *gl = (GetLine *) data;
  int ndone = _glq_append_chars(gl->cq, s, n, gl->flush_fn, gl);
  if(ndone != n)
    _err_record_msg(gl->err, _glq_last_error(gl->cq), END_ERR_MSG);
  return ndone;
}

/*.......................................................................
 * Ask gl_get_line() what caused it to return.
 *
 * Input:
 *  gl             GetLine *  The line editor resource object.
 * Output:
 *  return  GlReturnStatus    The return status of the last call to
 *                            gl_get_line().
 */
GlReturnStatus gl_return_status(GetLine *gl)
{
  GlReturnStatus rtn_status = GLR_ERROR;   /* The requested status */
  if(gl) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Access gl while signals are blocked.
 */
    rtn_status = gl->rtn_status;
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
  return rtn_status;
}

/*.......................................................................
 * In non-blocking server-I/O mode, this function should be called
 * from the application's external event loop to see what type of
 * terminal I/O is being waited for by gl_get_line(), and thus what
 * direction of I/O to wait for with select() or poll().
 *
 * Input:
 *  gl          GetLine *  The resource object of gl_get_line().
 * Output:
 *  return  GlPendingIO    The type of pending I/O being waited for.
 */
GlPendingIO gl_pending_io(GetLine *gl)
{
  GlPendingIO pending_io = GLP_WRITE;   /* The requested information */
  if(gl) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Access gl while signals are blocked.
 */
    pending_io = gl->pending_io;
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  };
  return pending_io;
}

/*.......................................................................
 * In server mode, this function configures the terminal for non-blocking
 * raw terminal I/O. In normal I/O mode it does nothing.
 *
 * Callers of this function must be careful to trap all signals that
 * terminate or suspend the program, and call gl_normal_io()
 * from the corresponding signal handlers in order to restore the
 * terminal to its original settings before the program is terminated
 * or suspended. They should also trap the SIGCONT signal to detect
 * when the program resumes, and ensure that its signal handler
 * call gl_raw_io() to redisplay the line and resume editing.
 *
 * This function is async signal safe.
 *
 * Input:
 *  gl      GetLine *  The line editor resource object.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
int gl_raw_io(GetLine *gl)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_raw_io() */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Don't allow applications to switch into raw mode unless in server mode.
 */
  if(gl->io_mode != GL_SERVER_MODE) {
    _err_record_msg(gl->err, "Can't switch to raw I/O unless in server mode",
		    END_ERR_MSG);
    errno = EPERM;
    status = 1;
  } else {
/*
 * Execute the private body of the function while signals are blocked.
 */
    status = _gl_raw_io(gl, 1);
  };
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the public function, gl_raw_io().
 * It assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 *
 * This function is async signal safe.
 */
static int _gl_raw_io(GetLine *gl, int redisplay)
{
/*
 * If we are already in the correct mode, do nothing.
 */
  if(gl->raw_mode)
    return 0;
/*
 * Switch the terminal to raw mode.
 */
  if(gl->is_term && gl_raw_terminal_mode(gl))
    return 1;
/*
 * Switch to non-blocking I/O mode?
 */
  if(gl->io_mode==GL_SERVER_MODE &&
     (gl_nonblocking_io(gl, gl->input_fd) ||
      gl_nonblocking_io(gl, gl->output_fd) ||
      (gl->file_fp && gl_nonblocking_io(gl, fileno(gl->file_fp))))) {
    if(gl->is_term)
      gl_restore_terminal_attributes(gl);
    return 1;
  };
/*
 * If an input line is being entered, arrange for it to be
 * displayed.
 */
  if(redisplay) {
    gl->postpone = 0;
    gl_queue_redisplay(gl);
  };
  return 0;
}

/*.......................................................................
 * Restore the terminal to the state that it had when
 * gl_raw_io() was last called. After calling
 * gl_raw_io(), this function must be called before
 * terminating or suspending the program, and before attempting other
 * uses of the terminal from within the program. See gl_raw_io()
 * for more details.
 *
 * Input:
 *  gl      GetLine *  The line editor resource object.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
int gl_normal_io(GetLine *gl)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_normal_io() */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Execute the private body of the function while signals are blocked.
 */
  status = _gl_normal_io(gl);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the public function, gl_normal_io().
 * It assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_normal_io(GetLine *gl)
{
/*
 * If we are already in normal mode, do nothing.
 */
  if(!gl->raw_mode)
    return 0;
/*
 * Postpone subsequent redisplays until after _gl_raw_io(gl, 1)
 * is next called.
 */
  gl->postpone = 1;
/*
 * Switch back to blocking I/O. Note that this is essential to do
 * here, because when using non-blocking I/O, the terminal output
 * buffering code can't always make room for new output without calling
 * malloc(), and a call to malloc() would mean that this function
 * couldn't safely be called from signal handlers.
 */
  if(gl->io_mode==GL_SERVER_MODE &&
     (gl_blocking_io(gl, gl->input_fd) ||
      gl_blocking_io(gl, gl->output_fd) ||
      (gl->file_fp && gl_blocking_io(gl, fileno(gl->file_fp)))))
    return 1;
/*
 * Move the cursor to the next empty terminal line. Note that
 * unbuffered I/O is requested, to ensure that gl_start_newline() be
 * async-signal-safe.
 */
  if(gl->is_term && gl_start_newline(gl, 0))
    return 1;
/*
 * Switch the terminal to normal mode.
 */
  if(gl->is_term && gl_restore_terminal_attributes(gl)) {
/*
 * On error, revert to non-blocking I/O if needed, so that on failure
 * we remain in raw mode.
 */
    if(gl->io_mode==GL_SERVER_MODE) {
      gl_nonblocking_io(gl, gl->input_fd);
      gl_nonblocking_io(gl, gl->output_fd);
      if(gl->file_fp)
	gl_nonblocking_io(gl, fileno(gl->file_fp));
    };
    return 1;
  };
  return 0;
}

/*.......................................................................
 * This function allows you to install an additional completion
 * action, or to change the completion function of an existing
 * one. This should be called before the first call to gl_get_line()
 * so that the name of the action be defined before the user's
 * configuration file is read.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  data             void *  This is passed to match_fn() whenever it is
 *                           called. It could, for example, point to a
 *                           symbol table that match_fn() would look up
 *                           matches in.
 *  match_fn   CplMatchFn *  The function that will identify the prefix
 *                           to be completed from the input line, and
 *                           report matching symbols.
 *  list_only         int    If non-zero, install an action that only lists
 *                           possible completions, rather than attempting
 *                           to perform the completion.
 *  name       const char *  The name with which users can refer to the
 *                           binding in tecla configuration files.
 *  keyseq     const char *  Either NULL, or a key sequence with which
 *                           to invoke the binding. This should be
 *                           specified in the same manner as key-sequences
 *                           in tecla configuration files (eg. "M-^I").
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_completion_action(GetLine *gl, void *data, CplMatchFn *match_fn,
			 int list_only, const char *name, const char *keyseq)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_completion_action() */
/*
 * Check the arguments.
 */
  if(!gl || !name || !match_fn) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Install the new action while signals are blocked.
 */
  status = _gl_completion_action(gl, data, match_fn, list_only, name, keyseq);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the public function, gl_completion_action().
 * It assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_completion_action(GetLine *gl, void *data, CplMatchFn *match_fn,
				 int list_only, const char *name,
				 const char *keyseq)
{
  KtKeyFn *current_fn;      /* An existing action function */
  void *current_data;       /* The action-function callback data */
/*
 * Which action function is desired?
 */
  KtKeyFn *action_fn = list_only ? gl_list_completions : gl_complete_word;
/*
 * Is there already an action of the specified name?
 */
  if(_kt_lookup_action(gl->bindings, name, &current_fn, &current_data) == 0) {
/*
 * If the action has the same type as the one being requested,
 * simply change the contents of its GlCplCallback callback data.
 */
    if(current_fn == action_fn) {
      GlCplCallback *cb = (GlCplCallback *) current_data;
      cb->fn = match_fn;
      cb->data = data;
    } else {
      errno = EINVAL;
      _err_record_msg(gl->err,
        "Illegal attempt to change the type of an existing completion action",
        END_ERR_MSG);
      return 1;
    };
/*
 * No existing action has the specified name.
 */
  } else {
/*
 * Allocate a new GlCplCallback callback object.
 */
    GlCplCallback *cb = (GlCplCallback *) _new_FreeListNode(gl->cpl_mem);
    if(!cb) {
      errno = ENOMEM;
      _err_record_msg(gl->err, "Insufficient memory to add completion action",
		      END_ERR_MSG);
      return 1;
    };
/*
 * Record the completion callback data.
 */
    cb->fn = match_fn;
    cb->data = data;
/*
 * Attempt to register the new action.
 */
    if(_kt_set_action(gl->bindings, name, action_fn, cb)) {
      _err_record_msg(gl->err, _kt_last_error(gl->bindings), END_ERR_MSG);
      _del_FreeListNode(gl->cpl_mem, (void *) cb);
      return 1;
    };
  };
/*
 * Bind the action to a given key-sequence?
 */
  if(keyseq && _kt_set_keybinding(gl->bindings, KTB_NORM, keyseq, name)) {
    _err_record_msg(gl->err, _kt_last_error(gl->bindings), END_ERR_MSG);
    return 1;
  };
  return 0;
}

/*.......................................................................
 * Register an application-provided function as an action function.
 * This should preferably be called before the first call to gl_get_line()
 * so that the name of the action becomes defined before the user's
 * configuration file is read.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  data             void *  Arbitrary application-specific callback
 *                           data to be passed to the callback
 *                           function, fn().
 *  fn         GlActionFn *  The application-specific function that
 *                           implements the action. This will be invoked
 *                           whenever the user presses any
 *                           key-sequence which is bound to this action.
 *  name       const char *  The name with which users can refer to the
 *                           binding in tecla configuration files.
 *  keyseq     const char *  The key sequence with which to invoke
 *                           the binding. This should be specified in the
 *                           same manner as key-sequences in tecla
 *                           configuration files (eg. "M-^I").
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_register_action(GetLine *gl, void *data, GlActionFn *fn,
                       const char *name, const char *keyseq)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_register_action() */
/*
 * Check the arguments.
 */
  if(!gl || !name || !fn) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Install the new action while signals are blocked.
 */
  status = _gl_register_action(gl, data, fn, name, keyseq);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the public function, gl_register_action().
 * It assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_register_action(GetLine *gl, void *data, GlActionFn *fn,
			       const char *name, const char *keyseq)
{
  KtKeyFn *current_fn;      /* An existing action function */
  void *current_data;       /* The action-function callback data */
/*
 * Get the action function which actually runs the application-provided
 * function.
 */
  KtKeyFn *action_fn = gl_run_external_action;
/*
 * Is there already an action of the specified name?
 */
  if(_kt_lookup_action(gl->bindings, name, &current_fn, &current_data) == 0) {
/*
 * If the action has the same type as the one being requested,
 * simply change the contents of its GlCplCallback callback data.
 */
    if(current_fn == action_fn) {
      GlExternalAction *a = (GlExternalAction *) current_data;
      a->fn = fn;
      a->data = data;
    } else {
      errno = EINVAL;
      _err_record_msg(gl->err,
        "Illegal attempt to change the type of an existing action",
		      END_ERR_MSG);
      return 1;
    };
/*
 * No existing action has the specified name.
 */
  } else {
/*
 * Allocate a new GlCplCallback callback object.
 */
    GlExternalAction *a =
      (GlExternalAction *) _new_FreeListNode(gl->ext_act_mem);
    if(!a) {
      errno = ENOMEM;
      _err_record_msg(gl->err, "Insufficient memory to add completion action",
		      END_ERR_MSG);
      return 1;
    };
/*
 * Record the completion callback data.
 */
    a->fn = fn;
    a->data = data;
/*
 * Attempt to register the new action.
 */
    if(_kt_set_action(gl->bindings, name, action_fn, a)) {
      _err_record_msg(gl->err, _kt_last_error(gl->bindings), END_ERR_MSG);
      _del_FreeListNode(gl->cpl_mem, (void *) a);
      return 1;
    };
  };
/*
 * Bind the action to a given key-sequence?
 */
  if(keyseq && _kt_set_keybinding(gl->bindings, KTB_NORM, keyseq, name)) {
    _err_record_msg(gl->err, _kt_last_error(gl->bindings), END_ERR_MSG);
    return 1;
  };
  return 0;
}

/*.......................................................................
 * Invoke an action function previously registered by a call to
 * gl_register_action().
 */
static KT_KEY_FN(gl_run_external_action)
{
  GlAfterAction status;  /* The return value of the action function */
/*
 * Get the container of the action function and associated callback data.
 */
  GlExternalAction *a = (GlExternalAction *) data;
/*
 * Invoke the action function.
 */
  status = a->fn(gl, a->data, count, gl->buff_curpos, gl->line);
/*
 * If the callback took us out of raw (possibly non-blocking) input
 * mode, restore this mode, and queue a redisplay of the input line.
 */
  if(_gl_raw_io(gl, 1))
    return 1;
/*
 * Finally, check to see what the action function wants us to do next.
 */
  switch(status) {
  default:
  case GLA_ABORT:
    gl_record_status(gl, GLR_ERROR, errno);
    return 1;
    break;
  case GLA_RETURN:
    return gl_newline(gl, 1, NULL);
    break;
  case GLA_CONTINUE:
    break;
  };
  return 0;
}

/*.......................................................................
 * In server-I/O mode the terminal is left in raw mode between calls
 * to gl_get_line(), so it is necessary for the application to install
 * terminal restoring signal handlers for signals that could terminate
 * or suspend the process, plus a terminal reconfiguration handler to
 * be called when a process resumption signal is received, and finally
 * a handler to be called when a terminal-resize signal is received.
 *
 * Since there are many signals that by default terminate or suspend
 * processes, and different systems support different sub-sets of
 * these signals, this function provides a convenient wrapper around
 * sigaction() for assigning the specified handlers to all appropriate
 * signals. It also arranges that when any one of these signals is
 * being handled, all other catchable signals are blocked. This is
 * necessary so that the specified signal handlers can safely call
 * gl_raw_io(), gl_normal_io() and gl_update_size() without
 * reentrancy issues.
 *
 * Input:
 *  term_handler  void (*)(int)  The signal handler to invoke when
 *                               a process terminating signal is
 *                               received.
 *  susp_handler  void (*)(int)  The signal handler to invoke when
 *                               a process suspending signal is
 *                               received.
 *  cont_handler  void (*)(int)  The signal handler to invoke when
 *                               a process resumption signal is
 *                               received (ie. SIGCONT).
 *  size_handler  void (*)(int)  The signal handler to invoke when
 *                               a terminal-resize signal (ie. SIGWINCH)
 *                               is received.
 * Output:
 *  return                  int  0 - OK.
 *                               1 - Error.
 */
int gl_tty_signals(void (*term_handler)(int), void (*susp_handler)(int),
		   void (*cont_handler)(int), void (*size_handler)(int))
{
  int i;
/*
 * Search for signals of the specified classes, and assign the
 * associated signal handler to them.
 */
  for(i=0; i<sizeof(gl_signal_list)/sizeof(gl_signal_list[0]); i++) {
    const struct GlDefSignal *sig = gl_signal_list + i;
    if(sig->attr & GLSA_SUSP) {
      if(gl_set_tty_signal(sig->signo, term_handler))
	return 1;
    } else if(sig->attr & GLSA_TERM) {
      if(gl_set_tty_signal(sig->signo, susp_handler))
	return 1;
    } else if(sig->attr & GLSA_CONT) {
      if(gl_set_tty_signal(sig->signo, cont_handler))
	return 1;
    } else if(sig->attr & GLSA_SIZE) {
      if(gl_set_tty_signal(sig->signo, size_handler))
	return 1;
    };
  };
  return 0;
}

/*.......................................................................
 * This is a private function of gl_tty_signals(). It installs a given
 * signal handler, and arranges that when that signal handler is being
 * invoked other signals are blocked. The latter is important to allow
 * functions like gl_normal_io(), gl_raw_io() and gl_update_size()
 * to be called from signal handlers.
 *
 * Input:
 *  signo     int           The signal to be trapped.
 *  handler  void (*)(int)  The signal handler to assign to the signal.
 */
static int gl_set_tty_signal(int signo, void (*handler)(int))
{
  SigAction act;   /* The signal handler configuation */
/*
 * Arrange to block all trappable signals except the one that is being
 * assigned (the trapped signal will be blocked automatically by the
 * system).
 */
  gl_list_trappable_signals(&act.sa_mask);
  sigdelset(&act.sa_mask, signo);
/*
 * Assign the signal handler.
 */
  act.sa_handler = handler;
/*
 * There is only one portable signal handling flag, and it isn't
 * relevant to us, so don't specify any flags.
 */
  act.sa_flags = 0;
/*
 * Register the signal handler.
 */
  if(sigaction(signo, &act, NULL))
    return 1;
  return 0;
}

/*.......................................................................
 * Display a left-justified string over multiple terminal lines,
 * taking account of the current width of the terminal. Optional
 * indentation and an optional prefix string can be specified to be
 * displayed at the start of each new terminal line used. Similarly,
 * an optional suffix can be specified to be displayed at the end of
 * each terminal line.  If needed, a single paragraph can be broken
 * across multiple calls.  Note that literal newlines in the input
 * string can be used to force a newline at any point and that you
 * should use this feature to explicitly end all paragraphs, including
 * at the end of the last string that you write. Note that when a new
 * line is started between two words that are separated by spaces,
 * those spaces are not output, whereas when a new line is started
 * because a newline character was found in the string, only the
 * spaces before the newline character are discarded.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  indentation    int    The number of spaces of indentation to write
 *                        at the beginning of each new terminal line.
 *  prefix  const char *  An optional prefix string to write after the
 *                        indentation margin at the start of each new
 *                        terminal line. You can specify NULL if no
 *                        prefix is required.
 *  suffix  const char *  An optional suffix string to draw at the end
 *                        of the terminal line. Spaces will be added
 *                        where necessary to ensure that the suffix ends
 *                        in the last column of the terminal line. If
 *                        no suffix is desired, specify NULL.
 *  fill_char      int    The padding character to use when indenting
 *                        the line or padding up to the suffix.
 *  def_width      int    If the terminal width isn't known, such as when
 *                        writing to a pipe or redirecting to a file,
 *                        this number specifies what width to assume.
 *  start          int    The number of characters already written to
 *                        the start of the current terminal line. This
 *                        is primarily used to allow individual
 *                        paragraphs to be written over multiple calls
 *                        to this function, but can also be used to
 *                        allow you to start the first line of a
 *                        paragraph with a different prefix or
 *                        indentation than those specified above.
 *  string  const char *  The string to be written.
 * Output:
 *  return         int    On error -1 is returned. Otherwise the
 *                        return value is the terminal column index at
 *                        which the cursor was left after writing the
 *                        final word in the string. Successful return
 *                        values can thus be passed verbatim to the
 *                        'start' arguments of subsequent calls to
 *                        gl_display_text() to allow the printing of a
 *                        paragraph to be broken across multiple calls
 *                        to gl_display_text().
 */
int gl_display_text(GetLine *gl, int indentation, const char *prefix,
		    const char *suffix, int fill_char,
		    int def_width, int start, const char *string)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_completion_action() */
/*
 * Check the arguments?
 */
  if(!gl || !string) {
    errno = EINVAL;
    return -1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return -1;
/*
 * Display the text while signals are blocked.
 */
  status = _io_display_text(_io_write_stdio, gl->output_fp, indentation,
			    prefix, suffix, fill_char,
			    gl->ncolumn > 0 ? gl->ncolumn : def_width,
			    start, string);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * Block all of the signals that we are currently trapping.
 *
 * Input:
 *  gl       GetLine *   The resource object of gl_get_line().
 * Input/Output:
 *  oldset   sigset_t *   The superseded process signal mask
 *                        will be return in *oldset unless oldset is
 *                        NULL.
 * Output:
 *  return        int     0 - OK.
 *                        1 - Error.
 */
static int gl_mask_signals(GetLine *gl, sigset_t *oldset)
{
/*
 * Block all signals in all_signal_set, along with any others that are
 * already blocked by the application.
 */
  if(sigprocmask(SIG_BLOCK, &gl->all_signal_set, oldset) >= 0) {
    gl->signals_masked = 1;
    return 0;
  };
/*
 * On error attempt to query the current process signal mask, so
 * that oldset be the correct process signal mask to restore later
 * if the caller of this function ignores the error return value.
 */
  if(oldset)
    (void) sigprocmask(SIG_SETMASK, NULL, oldset);
  gl->signals_masked = 0;
  return 1;
}

/*.......................................................................
 * Restore a process signal mask that was previously returned via the
 * oldset argument of gl_mask_signals().
 *
 * Input:
 *  gl        GetLine *   The resource object of gl_get_line().
 * Input/Output:
 *  oldset   sigset_t *   The process signal mask to be restored.
 * Output:
 *  return        int     0 - OK.
 *                        1 - Error.
 */
static int gl_unmask_signals(GetLine *gl, sigset_t *oldset)
{
  gl->signals_masked = 0;
  return sigprocmask(SIG_SETMASK, oldset, NULL) < 0;
}

/*.......................................................................
 * Arrange to temporarily catch the signals marked in gl->use_signal_set.
 *
 * Input:
 *  gl        GetLine *   The resource object of gl_get_line().
 * Output:
 *  return        int     0 - OK.
 *                        1 - Error.
 */
static int gl_catch_signals(GetLine *gl)
{
  return sigprocmask(SIG_UNBLOCK, &gl->use_signal_set, NULL) < 0;
}

/*.......................................................................
 * Select the I/O mode to be used by gl_get_line().
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  mode      GlIOMode    The I/O mode to establish.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error.
 */
int gl_io_mode(GetLine *gl, GlIOMode mode)
{
  sigset_t oldset; /* The signals that were blocked on entry to this function */
  int status;      /* The return status of _gl_io_mode() */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Check that the requested mode is known.
 */
  switch(mode) {
  case GL_NORMAL_MODE:
  case GL_SERVER_MODE:
    break;
  default:
    errno = EINVAL;
    _err_record_msg(gl->err, "Unknown gl_get_line() I/O mode requested.",
		    END_ERR_MSG);
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Invoke the private body of this function.
 */
  status = _gl_io_mode(gl, mode);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the public function, gl_io_mode().
 * It assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_io_mode(GetLine *gl, GlIOMode mode)
{
/*
 * Are we already in the specified mode?
 */
  if(mode == gl->io_mode)
    return 0;
/*
 * First revert to normal I/O in the current I/O mode.
 */
  _gl_normal_io(gl);
/*
 * Record the new mode.
 */
  gl->io_mode = mode;
/*
 * Perform any actions needed by the new mode.
 */
  if(mode==GL_SERVER_MODE) {
    if(_gl_raw_io(gl, 1))
      return 1;
  };
  return 0;
}

/*.......................................................................
 * Return extra information (ie. in addition to that provided by errno)
 * about the last error to occur in either gl_get_line() or its
 * associated public functions.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  buff          char *  An optional output buffer. Note that if the
 *                        calling application calls any gl_*()
 *                        functions from signal handlers, it should
 *                        provide a buffer here, so that a copy of
 *                        the latest error message can safely be made
 *                        while signals are blocked.
 *  n           size_t    The allocated size of buff[].
 * Output:
 *  return  const char *  A pointer to the error message. This will
 *                        be the buff argument, unless buff==NULL, in
 *                        which case it will be a pointer to an
 *                        internal error buffer. In the latter case,
 *                        note that the contents of the returned buffer
 *                        will change on subsequent calls to any gl_*()
 *                        functions.
 */
const char *gl_error_message(GetLine *gl, char *buff, size_t n)
{
  if(!gl) {
    static const char *msg = "NULL GetLine argument";
    if(buff) {
      strncpy(buff, msg, n);
      buff[n-1] = '\0';
    } else {
      return msg;
    };
  } else if(buff) {
    sigset_t oldset; /* The signals that were blocked on entry to this block */
/*
 * Temporarily block all signals.
 */
    gl_mask_signals(gl, &oldset);
/*
 * Copy the error message into the specified buffer.
 */
    if(buff && n > 0) {
      strncpy(buff, _err_get_msg(gl->err), n);
      buff[n-1] = '\0';
    };
/*
 * Restore the process signal mask before returning.
 */
    gl_unmask_signals(gl, &oldset);
  } else {
    return _err_get_msg(gl->err);
  };
  return buff;
}

/*.......................................................................
 * Return the signal mask used by gl_get_line(). This is the set of
 * signals that gl_get_line() is currently configured to trap.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  set       sigset_t *  The set of signals will be returned in *set,
 *                        in the form of a signal process mask, as
 *                        used by sigaction(), sigprocmask(),
 *                        sigpending(), sigsuspend(), sigsetjmp() and
 *                        other standard POSIX signal-aware
 *                        functions.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error (examine errno for reason).
 */
int gl_list_signals(GetLine *gl, sigset_t *set)
{
/*
 * Check the arguments.
 */
  if(!gl || !set) {
    if(gl)
      _err_record_msg(gl->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Copy the signal mask into *set.
 */
  memcpy(set, &gl->all_signal_set, sizeof(*set));
  return 0;
}

/*.......................................................................
 * By default, gl_get_line() doesn't trap signals that are blocked
 * when it is called. This default can be changed either on a
 * per-signal basis by calling gl_trap_signal(), or on a global basis
 * by calling this function. What this function does is add the
 * GLS_UNBLOCK_SIG flag to all signals that are currently configured
 * to be trapped by gl_get_line(), such that when subsequent calls to
 * gl_get_line() wait for I/O, these signals are temporarily
 * unblocked. This behavior is useful in non-blocking server-I/O mode,
 * where it is used to avoid race conditions related to handling these
 * signals externally to gl_get_line(). See the demonstration code in
 * demo3.c, or the gl_handle_signal() man page for further
 * information.
 *
 * Input:
 *  gl         GetLine *   The resource object of gl_get_line().
 */
void gl_catch_blocked(GetLine *gl)
{
  sigset_t oldset;    /* The process signal mask to restore */
  GlSignalNode *sig;  /* A signal node in gl->sigs */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return;
  };
/*
 * Temporarily block all signals while we modify the contents of gl.
 */
  gl_mask_signals(gl, &oldset);
/*
 * Add the GLS_UNBLOCK_SIG flag to all configured signals.
 */
  for(sig=gl->sigs; sig; sig=sig->next)
    sig->flags |= GLS_UNBLOCK_SIG;
/*
 * Restore the process signal mask that was superseded by the call
 * to gl_mask_signals().
 */
  gl_unmask_signals(gl, &oldset);
  return;
}

/*.......................................................................
 * Respond to signals who's default effects have important
 * consequences to gl_get_line(). This is intended for use in
 * non-blocking server mode, where the external event loop is
 * responsible for catching signals. Signals that are handled include
 * those that by default terminate or suspend the process, and the
 * signal that indicates that the terminal size has changed. Note that
 * this function is not signal safe and should thus not be called from
 * a signal handler itself. See the gl_io_mode() man page for how it
 * should be used.
 *
 * In the case of signals that by default terminate or suspend
 * processes, command-line editing will be suspended, the terminal
 * returned to a usable state, then the default disposition of the
 * signal restored and the signal resent, in order to suspend or
 * terminate the process.  If the process subsequently resumes,
 * command-line editing is resumed.
 *
 * In the case of signals that indicate that the terminal has been
 * resized, the new size will be queried, and any input line that is
 * being edited will be redrawn to fit the new dimensions of the
 * terminal.
 *
 * Input:
 *  signo    int    The number of the signal to respond to.
 *  gl   GetLine *  The first element of an array of 'ngl' GetLine
 *                  objects.
 *  ngl      int    The number of elements in the gl[] array. Normally
 *                  this will be one.
 */
void gl_handle_signal(int signo, GetLine *gl, int ngl)
{
  int attr;             /* The attributes of the specified signal */
  sigset_t all_signals; /* The set of trappable signals */
  sigset_t oldset;      /* The process signal mask to restore */
  int i;
/*
 * NULL operation?
 */
  if(ngl < 1 || !gl)
    return;
/*
 * Look up the default attributes of the specified signal.
 */
  attr = gl_classify_signal(signo);
/*
 * If the signal isn't known, we are done.
 */
  if(!attr)
    return;
/*
 * Temporarily block all signals while we modify the gl objects.
 */
  gl_list_trappable_signals(&all_signals);
  sigprocmask(SIG_BLOCK, &all_signals, &oldset);
/*
 * Suspend or terminate the process?
 */
  if(attr & (GLSA_SUSP | GLSA_TERM)) {
    gl_suspend_process(signo, gl, ngl);
/*
 * Resize the terminal? Note that ioctl() isn't defined as being
 * signal safe, so we can't call gl_update_size() here. However,
 * gl_get_line() checks for resizes on each call, so simply arrange
 * for the application's event loop to call gl_get_line() as soon as
 * it becomes possible to write to the terminal. Note that if the
 * caller is calling select() or poll when this happens, these functions
 * get interrupted, since a signal has been caught.
 */
  } else if(attr & GLSA_SIZE) {
    for(i=0; i<ngl; i++)
      gl[i].pending_io = GLP_WRITE;
  };
/*
 * Restore the process signal mask that was superseded by the call
 * to gl_mask_signals().
 */
  sigprocmask(SIG_SETMASK, &oldset, NULL);
  return;
}

/*.......................................................................
 * Respond to an externally caught process suspension or
 * termination signal.
 *
 * After restoring the terminal to a usable state, suspend or
 * terminate the calling process, using the original signal with its
 * default disposition restored to do so. If the process subsequently
 * resumes, resume editing any input lines that were being entered.
 *
 * Input:
 *  signo    int    The signal number to suspend the process with. Note
 *                  that the default disposition of this signal will be
 *                  restored before the signal is sent, so provided
 *                  that the default disposition of this signal is to
 *                  either suspend or terminate the application,
 *                  that is what wil happen, regardless of what signal
 *                  handler is currently assigned to this signal.
 *  gl   GetLine *  The first element of an array of 'ngl' GetLine objects
 *                  whose terminals should be restored to a sane state
 *                  while the application is suspended.
 *  ngl      int    The number of elements in the gl[] array.
 */
static void gl_suspend_process(int signo, GetLine *gl, int ngl)
{
  sigset_t only_signo;          /* A signal set containing just signo */
  sigset_t oldset;              /* The signal mask on entry to this function */
  sigset_t all_signals;         /* A signal set containing all signals */
  struct sigaction old_action;  /* The current signal handler */
  struct sigaction def_action;  /* The default signal handler */
  int i;
/*
 * Create a signal mask containing the signal that was trapped.
 */
  sigemptyset(&only_signo);
  sigaddset(&only_signo, signo);
/*
 * Temporarily block all signals.
 */
  gl_list_trappable_signals(&all_signals);
  sigprocmask(SIG_BLOCK, &all_signals, &oldset);
/*
 * Restore the terminal to a usable state.
 */
  for(i=0; i<ngl; i++) {
    GetLine *obj = gl + i;
    if(obj->raw_mode) {
      _gl_normal_io(obj);
      if(!obj->raw_mode)        /* Check that gl_normal_io() succeded */
	obj->raw_mode = -1;     /* Flag raw mode as needing to be restored */
    };
  };
/*
 * Restore the system default disposition of the signal that we
 * caught.  Note that this signal is currently blocked. Note that we
 * don't use memcpy() to copy signal sets here, because the signal safety
 * of memcpy() is undefined.
 */
  def_action.sa_handler = SIG_DFL;
  {
    char *orig = (char *) &all_signals;
    char *dest = (char *) &def_action.sa_mask;
    for(i=0; i<sizeof(sigset_t); i++)
      *dest++ = *orig++;
  };
  sigaction(signo, &def_action, &old_action);
/*
 * Resend the signal, and unblock it so that it gets delivered to
 * the application. This will invoke the default action of this signal.
 */
  raise(signo);
  sigprocmask(SIG_UNBLOCK, &only_signo, NULL);
/*
 * If the process resumes again, it will resume here.
 * Block the signal again, then restore our signal handler.
 */
  sigprocmask(SIG_BLOCK, &only_signo, NULL);
  sigaction(signo, &old_action, NULL);
/*
 * Resume command-line editing.
 */
  for(i=0; i<ngl; i++) {
    GetLine *obj = gl + i;
    if(obj->raw_mode == -1) { /* Did we flag the need to restore raw mode? */
      obj->raw_mode = 0;      /* gl_raw_io() does nothing unless raw_mode==0 */
      _gl_raw_io(obj, 1);
    };
  };
/*
 * Restore the process signal mask to the way it was when this function
 * was called.
 */
  sigprocmask(SIG_SETMASK, &oldset, NULL);
  return;
}

/*.......................................................................
 * Return the information about the default attributes of a given signal.
 * The attributes that are returned are as defined by the standards that
 * created them, including POSIX, SVR4 and 4.3+BSD, and are taken from a
 * table in Richard Steven's book, "Advanced programming in the UNIX
 * environment".
 *
 * Input:
 *  signo        int   The signal to be characterized.
 * Output:
 *  return       int   A bitwise union of GlSigAttr enumerators, or 0
 *                     if the signal isn't known.
 */
static int gl_classify_signal(int signo)
{
  int i;
/*
 * Search for the specified signal in the gl_signal_list[] table.
 */
  for(i=0; i<sizeof(gl_signal_list)/sizeof(gl_signal_list[0]); i++) {
    const struct GlDefSignal *sig = gl_signal_list + i;
    if(sig->signo == signo)
      return sig->attr;
  };
/*
 * Signal not known.
 */
  return 0;
}

/*.......................................................................
 * When in non-blocking server mode, this function can be used to abandon
 * the current incompletely entered input line, and prepare to start
 * editing a new line on the next call to gl_get_line().
 *
 * Input:
 *  gl      GetLine *  The line editor resource object.
 */
void gl_abandon_line(GetLine *gl)
{
  sigset_t oldset;    /* The process signal mask to restore */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return;
  };
/*
 * Temporarily block all signals while we modify the contents of gl.
 */
  gl_mask_signals(gl, &oldset);
/*
 * Mark the input line as discarded.
 */
  _gl_abandon_line(gl);
/*
 * Restore the process signal mask that was superseded by the call
 * to gl_mask_signals().
 */
  gl_unmask_signals(gl, &oldset);
  return;
}

/*.......................................................................
 * This is the private body of the gl_abandon_line() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
void _gl_abandon_line(GetLine *gl)
{
  gl->endline = 1;
  gl->pending_io = GLP_WRITE;
}

/*.......................................................................
 * How many characters are needed to write a number as an octal string?
 *
 * Input:
 *  num   unsigned   The to be measured.
 * Output:
 *  return     int   The number of characters needed.
 */
static int gl_octal_width(unsigned num)
{
  int n;    /* The number of characters needed to render the number */
  for(n=1; num /= 8; n++)
    ;
  return n;
}

/*.......................................................................
 * Tell gl_get_line() the current terminal size. Note that this is only
 * necessary on systems where changes in terminal size aren't reported
 * via SIGWINCH.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  ncolumn           int    The number of columns in the terminal.
 *  nline             int    The number of lines in the terminal.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_set_term_size(GetLine *gl, int ncolumn, int nline)
{
  sigset_t oldset;      /* The signals that were blocked on entry */
                        /*  to this function */
  int status;           /* The return status */
/*
 * Block all signals while accessing gl.
 */
  gl_mask_signals(gl, &oldset);
/*
 * Install the new terminal size.
 */
  status = _gl_set_term_size(gl, ncolumn, nline);
/*
 * Restore the process signal mask before returning.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the gl_set_term_size() function. It
 * assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_set_term_size(GetLine *gl, int ncolumn, int nline)
{
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Reject non-sensical dimensions.
 */
  if(ncolumn <= 0 || nline <= 0) {
    _err_record_msg(gl->err, "Invalid terminal size", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Install the new dimensions in the terminal driver if possible, so
 * that future calls to gl_query_size() get the new value.
 */
#ifdef TIOCSWINSZ
  if(gl->is_term) {
    struct winsize size;
    size.ws_row = nline;
    size.ws_col = ncolumn;
    size.ws_xpixel = 0;
    size.ws_ypixel = 0;
    if(ioctl(gl->output_fd, TIOCSWINSZ, &size) == -1) {
      _err_record_msg(gl->err, "Can't change terminal size", END_ERR_MSG);
      return 1;
    };
  };
#endif
/*
 * If an input line is in the process of being edited, redisplay it to
 * accomodate the new dimensions, and record the new dimensions in
 * gl->nline and gl->ncolumn.
 */
  return gl_handle_tty_resize(gl, ncolumn, nline);
}

/*.......................................................................
 * Record a character in the input line buffer at a given position.
 *
 * Input:
 *  gl    GetLine *   The resource object of gl_get_line().
 *  c        char     The character to be recorded.
 *  bufpos    int     The index in the buffer at which to record the
 *                    character.
 * Output:
 *  return    int     0 - OK.
 *                    1 - Insufficient room.
 */
static int gl_buffer_char(GetLine *gl, char c, int bufpos)
{
/*
 * Guard against buffer overruns.
 */
  if(bufpos >= gl->linelen)
    return 1;
/*
 * Record the new character.
 */
  gl->line[bufpos] = c;
/*
 * If the new character was placed beyond the end of the current input
 * line, update gl->ntotal to reflect the increased number of characters
 * that are in gl->line, and terminate the string.
 */
  if(bufpos >= gl->ntotal) {
    gl->ntotal = bufpos+1;
    gl->line[gl->ntotal] = '\0';
  };
  return 0;
}

/*.......................................................................
 * Copy a given string into the input buffer, overwriting the current
 * contents.
 *
 * Input:
 *  gl    GetLine *   The resource object of gl_get_line().
 *  s  const char *   The string to be recorded.
 *  n         int     The number of characters to be copied from the
 *                    string.
 *  bufpos    int     The index in the buffer at which to place the
 *                    the first character of the string.
 * Output:
 *  return    int     0 - OK.
 *                    1 - String truncated to fit.
 */
static int gl_buffer_string(GetLine *gl, const char *s, int n, int bufpos)
{
  int nnew;  /* The number of characters actually recorded */
  int i;
/*
 * How many of the characters will fit within the buffer?
 */
  nnew = bufpos + n <= gl->linelen ? n : (gl->linelen - bufpos);
/*
 * Record the first nnew characters of s[] in the buffer.
 */
  for(i=0; i<nnew; i++)
    gl_buffer_char(gl, s[i], bufpos + i);
/*
 * Was the string truncated?
 */
  return nnew < n;
}

/*.......................................................................
 * Make room in the input buffer for a string to be inserted. This
 * involves moving the characters that follow a specified point, towards
 * the end of the buffer.
 *
 * Input:
 *  gl    GetLine *   The resource object of gl_get_line().
 *  start     int     The index of the first character to be moved.
 *  n         int     The width of the gap.
 * Output:
 *  return    int     0 - OK.
 *                    1 - Insufficient room.
 */
static int gl_make_gap_in_buffer(GetLine *gl, int start, int n)
{
/*
 * Ensure that the buffer has sufficient space.
 */
  if(gl->ntotal + n > gl->linelen)
    return 1;
/*
 * Move everything including and beyond the character at 'start'
 * towards the end of the string.
 */
  memmove(gl->line + start + n, gl->line + start, gl->ntotal - start + 1);
/*
 * Update the recorded size of the line.
 */
  gl->ntotal += n;
  return 1;
}

/*.......................................................................
 * Remove a given number of characters from the input buffer. This
 * involves moving the characters that follow the removed characters to
 * where the removed sub-string started in the input buffer.
 *
 * Input:
 *  gl    GetLine *   The resource object of gl_get_line().
 *  start     int     The first character to be removed.
 *  n         int     The number of characters to remove.
 */
static void gl_remove_from_buffer(GetLine *gl, int start, int n)
{
  memmove(gl->line + start, gl->line + start + n, gl->ntotal - start - n + 1);
/*
 * Update the recorded size of the line.
 */
  gl->ntotal -= n;
}

/*.......................................................................
 * Truncate the string in the input line buffer after a given number of
 * characters.
 *
 * Input:
 *  gl       GetLine *   The resource object of gl_get_line().
 *  n            int     The new length of the line.
 * Output:
 *  return       int     0 - OK.
 *                       1 - n > gl->linelen.
 */
static int gl_truncate_buffer(GetLine *gl, int n)
{
  if(n > gl->linelen)
    return 1;
  gl->line[n] = '\0';
  gl->ntotal = n;
  return 0;
}

/*.......................................................................
 * When the contents of gl->line[] are changed without calling any of the
 * gl_ buffer manipulation functions, this function must be called to
 * compute the length of this string, and ancillary information.
 *
 * Input:
 *  gl      GetLine *   The resource object of gl_get_line().
 */
static void gl_update_buffer(GetLine *gl)
{
  int len;  /* The length of the line */
/*
 * Measure the length of the input line.
 */
  for(len=0; len <= gl->linelen && gl->line[len]; len++)
    ;
/*
 * Just in case the string wasn't correctly terminated, do so here.
 */
  gl->line[len] = '\0';
/*
 * Record the number of characters that are now in gl->line[].
 */
  gl->ntotal = len;
/*
 * Ensure that the cursor stays within the bounds of the modified
 * input line.
 */
  if(gl->buff_curpos > gl->ntotal)
    gl->buff_curpos = gl->ntotal;
/*
 * Arrange for the input line to be redrawn.
 */
  gl_queue_redisplay(gl);
  return;
}

/*.......................................................................
 * Erase the displayed input line, including its prompt, and leave the
 * cursor where the erased line started. Note that to allow this
 * function to be used when responding to a terminal resize, this
 * function is designed to work even if the horizontal cursor position
 * doesn't match the internally recorded position.
 *
 * Input:
 *  gl      GetLine *   The resource object of gl_get_line().
 * Output:
 *  return      int     0 - OK.
 *                      1 - Error.
 */
static int gl_erase_line(GetLine *gl)
{
/*
 * Is a line currently displayed?
 */
  if(gl->displayed) {
/*
 * Relative the the start of the input line, which terminal line of
 * the current input line is the cursor currently on?
 */
    int cursor_line = gl->term_curpos / gl->ncolumn;
/*
 * Move the cursor to the start of the line.
 */
    for( ; cursor_line > 0; cursor_line--) {
      if(gl_print_control_sequence(gl, 1, gl->up))
	return 1;
    };
    if(gl_print_control_sequence(gl, 1, gl->bol))
      return 1;
/*
 * Clear from the start of the line to the end of the terminal.
 */
    if(gl_print_control_sequence(gl, gl->nline, gl->clear_eod))
      return 1;
/*
 * Mark the line as no longer displayed.
 */
    gl_line_erased(gl);
  };
  return 0;
}

/*.......................................................................
 * Arrange for the input line to be redisplayed by gl_flush_output(),
 * as soon as the output queue becomes empty.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 */
static void gl_queue_redisplay(GetLine *gl)
{
  gl->redisplay = 1;
  gl->pending_io = GLP_WRITE;
}

/*.......................................................................
 * Truncate the displayed input line starting from the current
 * terminal cursor position, and leave the cursor at the end of the
 * truncated line. The input-line buffer is not affected.
 *
 * Input:
 *  gl     GetLine *   The resource object of gl_get_line().
 * Output:
 *  return     int     0 - OK.
 *                     1 - Error.
 */
static int gl_truncate_display(GetLine *gl)
{
/*
 * Keep a record of the current terminal cursor position.
 */
  int term_curpos = gl->term_curpos;
/*
 * First clear from the cursor to the end of the current input line.
 */
  if(gl_print_control_sequence(gl, 1, gl->clear_eol))
    return 1;
/*
 * If there is more than one line displayed, go to the start of the
 * next line and clear from there to the end of the display. Note that
 * we can't use clear_eod to do the whole job of clearing from the
 * current cursor position to the end of the terminal because
 * clear_eod is only defined when used at the start of a terminal line
 * (eg. with gnome terminals, clear_eod clears from the start of the
 * current terminal line, rather than from the current cursor
 * position).
 */
  if(gl->term_len / gl->ncolumn > gl->term_curpos / gl->ncolumn) {
    if(gl_print_control_sequence(gl, 1, gl->down) ||
       gl_print_control_sequence(gl, 1, gl->bol) ||
       gl_print_control_sequence(gl, gl->nline, gl->clear_eod))
      return 1;
/*
 * Where is the cursor now?
 */
    gl->term_curpos = gl->ncolumn * (term_curpos / gl->ncolumn + 1);
/*
 * Restore the cursor position.
 */
    gl_set_term_curpos(gl, term_curpos);
  };
/*
 * Update the recorded position of the final character.
 */
  gl->term_len = gl->term_curpos;
  return 0;
}

/*.......................................................................
 * Return the set of all trappable signals.
 *
 * Input:
 *  signals   sigset_t *  The set of signals will be recorded in
 *                        *signals.
 */
static void gl_list_trappable_signals(sigset_t *signals)
{
/*
 * Start with the set of all signals.
 */
  sigfillset(signals);
/*
 * Remove un-trappable signals from this set.
 */
#ifdef SIGKILL
  sigdelset(signals, SIGKILL);
#endif
#ifdef SIGSTOP
  sigdelset(signals, SIGSTOP);
#endif
}

/*.......................................................................
 * Read an input line from a non-interactive input stream.
 *
 * Input:
 *  gl     GetLine *   The resource object of gl_get_line().
 * Output:
 *  return     int     0 - OK
 *                     1 - Error.
 */
static int gl_read_stream_line(GetLine *gl)
{
  char c = '\0'; /* The latest character read from fp */
/*
 * Record the fact that we are about to read input.
 */
  gl->pending_io = GLP_READ;
/*
 * If we are starting a new line, reset the line-input parameters.
 */
  if(gl->endline)
    gl_reset_input_line(gl);
/*
 * Read one character at a time.
 */
  while(gl->ntotal < gl->linelen && c != '\n') {
/*
 * Attempt to read one more character.
 */
    switch(gl_read_input(gl, &c)) {
    case GL_READ_OK:
      break;
    case GL_READ_EOF:        /* Reached end-of-file? */
/*
 * If any characters were read before the end-of-file condition,
 * interpolate a newline character, so that the caller sees a
 * properly terminated line. Otherwise return an end-of-file
 * condition.
 */
      if(gl->ntotal > 0) {
	c = '\n';
      } else {
	gl_record_status(gl, GLR_EOF, 0);
	return 1;
      };
      break;
    case GL_READ_BLOCKED:    /* Input blocked? */
      gl_record_status(gl, GLR_BLOCKED, BLOCKED_ERRNO);
      return 1;
      break;
    case GL_READ_ERROR:     /* I/O error? */
      return 1;
      break;
    };
/*
 * Append the character to the line buffer.
 */
    if(gl_buffer_char(gl, c, gl->ntotal))
      return 1;
  };
/*
 * Was the end of the input line reached before running out of buffer space?
 */
  gl->endline = (c == '\n');
  return 0;
}

/*.......................................................................
 * Read a single character from a non-interactive input stream.
 *
 * Input:
 *  gl     GetLine *   The resource object of gl_get_line().
 * Output:
 *  return     int     The character, or EOF on error.
 */
static int gl_read_stream_char(GetLine *gl)
{
  char c = '\0';    /* The latest character read from fp */
  int retval = EOF; /* The return value of this function */
/*
 * Arrange to discard any incomplete input line.
 */
  _gl_abandon_line(gl);
/*
 * Record the fact that we are about to read input.
 */
  gl->pending_io = GLP_READ;
/*
 * Attempt to read one more character.
 */
  switch(gl_read_input(gl, &c)) {
  case GL_READ_OK:      /* Success */
    retval = c;
    break;
  case GL_READ_BLOCKED: /* The read blocked */
    gl_record_status(gl, GLR_BLOCKED, BLOCKED_ERRNO);
    retval = EOF;  /* Failure */
    break;
  case GL_READ_EOF:     /* End of file reached */
    gl_record_status(gl, GLR_EOF, 0);
    retval = EOF;  /* Failure */
    break;
  case GL_READ_ERROR:
    retval = EOF;  /* Failure */
    break;
  };
  return retval;
}

/*.......................................................................
 * Bind a key sequence to a given action.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 *  origin  GlKeyOrigin     The originator of the key binding.
 *  key      const char *   The key-sequence to be bound (or unbound).
 *  action   const char *   The name of the action to bind the key to,
 *                          or either NULL or "" to unbind the
 *                          key-sequence.
 * Output:
 *  return          int     0 - OK
 *                          1 - Error.
 */
int gl_bind_keyseq(GetLine *gl, GlKeyOrigin origin, const char *keyseq,
		   const char *action)
{
  KtBinder binder;  /* The private internal equivalent of 'origin' */
/*
 * Check the arguments.
 */
  if(!gl || !keyseq) {
    errno = EINVAL;
    if(gl)
      _err_record_msg(gl->err, "NULL argument(s)", END_ERR_MSG);
    return 1;
  };
/*
 * An empty action string requests that the key-sequence be unbound.
 * This is indicated to _kt_set_keybinding() by passing a NULL action
 * string, so convert an empty string to a NULL action pointer.
 */
  if(action && *action=='\0')
    action = NULL;
/*
 * Translate the public originator enumeration to the private equivalent.
 */
  binder = origin==GL_USER_KEY ? KTB_USER : KTB_NORM;
/*
 * Bind the action to a given key-sequence?
 */
  if(keyseq && _kt_set_keybinding(gl->bindings, binder, keyseq, action)) {
    _err_record_msg(gl->err, _kt_last_error(gl->bindings), END_ERR_MSG);
    return 1;
  };
  return 0;
}

/*.......................................................................
 * This is the public wrapper around the gl_clear_termina() function.
 * It clears the terminal and leaves the cursor at the home position.
 * In server I/O mode, the next call to gl_get_line() will also
 * redisplay the current input line.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 * Output:
 *  return          int     0 - OK.
 *                          1 - Error.
 */
int gl_erase_terminal(GetLine *gl)
{
  sigset_t oldset;      /* The signals that were blocked on entry */
                        /*  to this function */
  int status;           /* The return status */
/*
 * Block all signals while accessing gl.
 */
  gl_mask_signals(gl, &oldset);
/*
 * Clear the terminal.
 */
  status = gl_clear_screen(gl, 1, NULL);
/*
 * Attempt to flush the clear-screen control codes to the terminal.
 * If this doesn't complete the job, the next call to gl_get_line()
 * will.
 */
  (void) gl_flush_output(gl);
/*
 * Restore the process signal mask before returning.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This function must be called by any function that erases the input
 * line.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 */
static void gl_line_erased(GetLine *gl)
{
  gl->displayed = 0;
  gl->term_curpos = 0;
  gl->term_len = 0;
}

/*.......................................................................
 * Append a specified line to the history list.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 *  line     const char *   The line to be added.
 * Output:
 *  return          int     0 - OK.
 *                          1 - Error.
 */
int gl_append_history(GetLine *gl, const char *line)
{
  sigset_t oldset;      /* The signals that were blocked on entry */
                        /*  to this function */
  int status;           /* The return status */
/*
 * Check the arguments.
 */
  if(!gl || !line) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Execute the private body of the function while signals are blocked.
 */
  status = _gl_append_history(gl, line);
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return status;
}

/*.......................................................................
 * This is the private body of the public function, gl_append_history().
 * It assumes that the caller has checked its arguments and blocked the
 * delivery of signals.
 */
static int _gl_append_history(GetLine *gl, const char *line)
{
  int status =_glh_add_history(gl->glh, line, 0);
  if(status)
    _err_record_msg(gl->err, _glh_last_error(gl->glh), END_ERR_MSG);
  return status;
}

/*.......................................................................
 * Enable or disable the automatic addition of newly entered lines to the
 * history list.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 *  enable          int     If true, subsequently entered lines will
 *                          automatically be added to the history list
 *                          before they are returned to the caller of
 *                          gl_get_line(). If 0, the choice of how and
 *                          when to archive lines in the history list,
 *                          is left up to the calling application, which
 *                          can do so via calls to gl_append_history().
 * Output:
 *  return          int     0 - OK.
 *                          1 - Error.
 */
int gl_automatic_history(GetLine *gl, int enable)
{
  sigset_t oldset;      /* The signals that were blocked on entry */
                        /*  to this function */
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return 1;
  };
/*
 * Block all signals.
 */
  if(gl_mask_signals(gl, &oldset))
    return 1;
/*
 * Execute the private body of the function while signals are blocked.
 */
  gl->automatic_history = enable;
/*
 * Restore the process signal mask.
 */
  gl_unmask_signals(gl, &oldset);
  return 0;
}

/*.......................................................................
 * This is a public function that reads a single uninterpretted
 * character from the user, without displaying anything.
 *
 * Input:
 *  gl     GetLine *  A resource object previously returned by
 *                    new_GetLine().
 * Output:
 *  return     int    The character that was read, or EOF if the read
 *                    had to be aborted (in which case you can call
 *                    gl_return_status() to find out why).
 */
int gl_read_char(GetLine *gl)
{
  int retval;   /* The return value of _gl_read_char() */
/*
 * This function can be called from application callback functions,
 * so check whether signals have already been masked, so that we don't
 * do it again, and overwrite gl->old_signal_set.
 */
  int was_masked = gl->signals_masked;
/*
 * Check the arguments.
 */
  if(!gl) {
    errno = EINVAL;
    return EOF;
  };
/*
 * Temporarily block all of the signals that we have been asked to trap.
 */
  if(!was_masked && gl_mask_signals(gl, &gl->old_signal_set))
    return EOF;
/*
 * Perform the character reading task.
 */
  retval = _gl_read_char(gl);
/*
 * Restore the process signal mask to how it was when this function was
 * first called.
 */
  if(!was_masked)
    gl_unmask_signals(gl, &gl->old_signal_set);
  return retval;
}

/*.......................................................................
 * This is the main body of the public function gl_read_char().
 */
static int _gl_read_char(GetLine *gl)
{
  int retval = EOF;  /* The return value */
  int waserr = 0;    /* True if an error occurs */
  char c;            /* The character read */
/*
 * This function can be called from application callback functions,
 * so check whether signals have already been overriden, so that we don't
 * overwrite the preserved signal handlers with gl_get_line()s. Also
 * record whether we are currently in raw I/O mode or not, so that this
 * can be left in the same state on leaving this function.
 */
  int was_overriden = gl->signals_overriden;
  int was_raw = gl->raw_mode;
/*
 * Also keep a record of the direction of any I/O that gl_get_line()
 * is awaiting, so that we can restore this status on return.
 */
  GlPendingIO old_pending_io = gl->pending_io;
/*
 * Assume that this call will successfully complete the input operation
 * until proven otherwise.
 */
  gl_clear_status(gl);
/*
 * If this is the first call to this function or gl_get_line(),
 * since new_GetLine(), complete any postponed configuration.
 */
  if(!gl->configured) {
    (void) _gl_configure_getline(gl, NULL, NULL, TECLA_CONFIG_FILE);
    gl->configured = 1;
  };
/*
 * Before installing our signal handler functions, record the fact
 * that there are no pending signals.
 */
  gl_pending_signal = -1;
/*
 * Temporarily override the signal handlers of the calling program,
 * so that we can intercept signals that would leave the terminal
 * in a bad state.
 */
  if(!was_overriden)
    waserr = gl_override_signal_handlers(gl);
/*
 * After recording the current terminal settings, switch the terminal
 * into raw input mode, without redisplaying any partially entered input
 * line.
 */
  if(!was_raw)
    waserr = waserr || _gl_raw_io(gl, 0);
/*
 * Attempt to read the line. This will require more than one attempt if
 * either a current temporary input file is opened by gl_get_input_line()
 * or the end of a temporary input file is reached by gl_read_stream_line().
 */
  while(!waserr) {
/*
 * Read a line from a non-interactive stream?
 */
    if(gl->file_fp || !gl->is_term) {
      retval = gl_read_stream_char(gl);
      if(retval != EOF) {            /* Success? */
	break;
      } else if(gl->file_fp) {  /* End of temporary input file? */
	gl_revert_input(gl);
	gl_record_status(gl, GLR_NEWLINE, 0);
      } else {                  /* An error? */
	waserr = 1;
	break;
      };
    };
/*
 * Read from the terminal? Note that the above if() block may have
 * changed gl->file_fp, so it is necessary to retest it here, rather
 * than using an else statement.
 */
    if(!gl->file_fp && gl->is_term) {
/*
 * Flush any pending output to the terminal before waiting
 * for the user to type a character.
 */
      if(_glq_char_count(gl->cq) > 0 && gl_flush_output(gl)) {
	retval = EOF;
/*
 * Read one character. Don't append it to the key buffer, since
 * this would subseuqnely appear as bogus input to the line editor.
 */
      } else if(gl_read_terminal(gl, 0, &c) == 0) {
/*
 * Record the character for return.
 */
	retval = c;
/*
 * In this mode, count each character as being a new key-sequence.
 */
	gl->keyseq_count++;
/*
 * Delete the character that was read, from the key-press buffer.
 */
	gl_discard_chars(gl, 1);
      };
      if(retval==EOF)
	waserr = 1;
      else
	break;
    };
  };
/*
 * If an error occurred, but gl->rtn_status is still set to
 * GLR_NEWLINE, change the status to GLR_ERROR. Otherwise
 * leave it at whatever specific value was assigned by the function
 * that aborted input. This means that only functions that trap
 * non-generic errors have to remember to update gl->rtn_status
 * themselves.
 */
  if(waserr && gl->rtn_status == GLR_NEWLINE)
    gl_record_status(gl, GLR_ERROR, errno);
/*
 * Restore terminal settings, if they were changed by this function.
 */
  if(!was_raw && gl->io_mode != GL_SERVER_MODE)
    _gl_normal_io(gl);
/*
 * Restore the signal handlers, if they were overriden by this function.
 */
  if(!was_overriden)
    gl_restore_signal_handlers(gl);
/*
 * If this function gets aborted early, the errno value associated
 * with the event that caused this to happen is recorded in
 * gl->rtn_errno. Since errno may have been overwritten by cleanup
 * functions after this, restore its value to the value that it had
 * when the error condition occured, so that the caller can examine it
 * to find out what happened.
 */
  errno = gl->rtn_errno;
/*
 * Error conditions are signalled to the caller, by setting the returned
 * character to EOF.
 */
  if(gl->rtn_status != GLR_NEWLINE)
    retval = EOF;
/*
 * Restore the indication of what direction of I/O gl_get_line()
 * was awaiting before this call.
 */
  gl->pending_io = old_pending_io;
/*
 * Return the acquired character.
 */
  return retval;
}

/*.......................................................................
 * Reset the GetLine completion status. This function should be called
 * at the start of gl_get_line(), gl_read_char() and gl_query_char()
 * to discard the completion status and non-zero errno value of any
 * preceding calls to these functions.
 *
 * Input:
 *  gl       GetLine *  The resource object of this module.
 */
static void gl_clear_status(GetLine *gl)
{
  gl_record_status(gl, GLR_NEWLINE, 0);
}

/*.......................................................................
 * When an error or other event causes gl_get_line() to return, this
 * function should be called to record information about what
 * happened, including the value of errno and the value that
 * gl_return_status() should return.
 *
 * Input:
 *  gl                GetLine *  The resource object of this module.
 *  rtn_status GlReturnStatus    The completion status. To clear a
 *                               previous abnormal completion status,
 *                               specify GLR_NEWLINE (this is what
 *                               gl_clear_status() does).
 *  rtn_errno             int    The associated value of errno.
 */
static void gl_record_status(GetLine *gl, GlReturnStatus rtn_status,
			     int rtn_errno)
{
/*
 * If rtn_status==GLR_NEWLINE, then this resets the completion status, so we
 * should always heed this. Otherwise, only record the first abnormal
 * condition that occurs after such a reset.
 */
  if(rtn_status == GLR_NEWLINE || gl->rtn_status == GLR_NEWLINE) {
    gl->rtn_status = rtn_status;
    gl->rtn_errno = rtn_errno;
  };
}

#ifndef getline_h
#define getline_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Set the name of the getline configuration file.
 */
#define TECLA_CONFIG_FILE "~/.teclarc"

/*
 * The following macro returns non-zero if a character is
 * a control character.
 */
#define IS_CTRL_CHAR(c) ((unsigned char)(c) < ' ' || (unsigned char)(c)=='\177')

/*
 * The following macro returns non-zero if a character is
 * a meta character.
 */
#define IS_META_CHAR(c) (((unsigned char)(c) & 0x80) && !isprint((int)(unsigned char)(c)))

/*
 * Return the character that would be produced by pressing the
 * specified key plus the control key.
 */
#define MAKE_CTRL(c) ((c)=='?' ? '\177' : ((unsigned char)toupper(c) & ~0x40))

/*
 * Return the character that would be produced by pressing the
 * specified key plus the meta key.
 */
#define MAKE_META(c) ((unsigned char)(c) | 0x80)

/*
 * Given a binary control character, return the character that
 * had to be pressed at the same time as the control key.
 */
#define CTRL_TO_CHAR(c) (toupper((unsigned char)(c) | 0x40))

/*
 * Given a meta character, return the character that was pressed
 * at the same time as the meta key.
 */
#define META_TO_CHAR(c) ((unsigned char)(c) & ~0x80)

/*
 * Specify the string of characters other than the alphanumeric characters,
 * that are to be considered parts of words.
 */
#define GL_WORD_CHARS "_*\?\\[]"

/*
 * Define the escape character, both as a string and as a character.
 */
#define GL_ESC_STR "\033"
#define GL_ESC_CHAR '\033'

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <errno.h>

#include "hash.h"
#include "strngmem.h"
#include "freelist.h"

/*
 * The following container object contains free-lists to be used
 * for allocation of HashTable containers and nodes.
 */
struct HashMemory {
  FreeList *hash_memory;    /* HashTable free-list */
  FreeList *node_memory;    /* HashNode free-list */
  StringMem *string_memory; /* Memory used to allocate hash strings */
};

/*
 * Define a hash symbol-table entry.
 * See symbol.h for the definition of the Symbol container type.
 */
typedef struct HashNode HashNode;
struct HashNode {
  Symbol symbol;       /* The symbol stored in the hash-entry */
  HashNode *next;      /* The next hash-table entry in a bucket list */
};

/*
 * Each hash-table bucket contains a linked list of entries that
 * hash to the same bucket.
 */
typedef struct {
  HashNode *head;   /* The head of the bucket hash-node list */
  int count;        /* The number of entries in the list */
} HashBucket;

/*
 * A hash-table consists of 'size' hash buckets.
 * Note that the HashTable typedef for this struct is contained in hash.h.
 */
struct HashTable {
  HashMemory *mem;         /* HashTable free-list */
  int internal_mem;        /* True if 'mem' was allocated by _new_HashTable() */
  int case_sensitive;      /* True if case is significant in lookup keys */
  int size;                /* The number of hash buckets */
  HashBucket *bucket;      /* An array of 'size' hash buckets */
  int (*keycmp)(const char *, const char *); /* Key comparison function */
  void *app_data;          /* Application-provided data */
  HASH_DEL_FN(*del_fn);    /* Application-provided 'app_data' destructor */
};

static HashNode *_del_HashNode(HashTable *hash, HashNode *node);
static HashNode *_new_HashNode(HashTable *hash, const char *name, int code,
		      void (*fn)(void), void *data, SYM_DEL_FN(*del_fn));
static HashNode *_find_HashNode(HashTable *hash, HashBucket *bucket,
				const char *name, HashNode **prev);
static HashBucket *_find_HashBucket(HashTable *hash, const char *name);
static int _ht_lower_strcmp(const char *node_key, const char *look_key);
static int _ht_strcmp(const char *node_key, const char *look_key);

/*.......................................................................
 * Allocate a free-list for use in allocating hash tables and their nodes.
 *
 * Input:
 *  list_count    int    The number of HashTable containers per free-list
 *                       block.
 *  node_count    int    The number of HashTable nodes per free-list block.
 * Output:
 *  return HashMemory *  The new free-list for use in allocating hash tables
 *                       and their nodes.
 */
HashMemory *_new_HashMemory(int hash_count, int node_count)
{
  HashMemory *mem;
/*
 * Allocate the free-list container.
 */
  mem = (HashMemory *) malloc(sizeof(HashMemory));
  if(!mem) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Initialize the container at least up to the point at which it can
 * safely be passed to _del_HashMemory().
 */
  mem->hash_memory = NULL;
  mem->node_memory = NULL;
  mem->string_memory = NULL;
/*
 * Allocate the two free-lists.
 */
  mem->hash_memory = _new_FreeList(sizeof(HashTable), hash_count);
  if(!mem->hash_memory)
    return _del_HashMemory(mem, 1);
  mem->node_memory = _new_FreeList(sizeof(HashNode), node_count);
  if(!mem->node_memory)
    return _del_HashMemory(mem, 1);
  mem->string_memory = _new_StringMem(64);
  if(!mem->string_memory)
    return _del_HashMemory(mem, 1);
/*
 * Return the free-list container.
 */
  return mem;
}

/*.......................................................................
 * Delete a HashTable free-list. An error will be displayed if the list is
 * still in use and the deletion will be aborted.
 *
 * Input:
 *  mem    HashMemory *  The free-list container to be deleted.
 *  force         int    If force==0 then _del_HashMemory() will complain
 *                        and refuse to delete the free-list if any
 *                        of nodes have not been returned to the free-list.
 *                       If force!=0 then _del_HashMemory() will not check
 *                        whether any nodes are still in use and will
 *                        always delete the list.
 * Output:
 *  return HashMemory *  Always NULL (even if the memory could not be
 *                       deleted).
 */
HashMemory *_del_HashMemory(HashMemory *mem, int force)
{
  if(mem) {
    if(!force && (_busy_FreeListNodes(mem->hash_memory) > 0 ||
		  _busy_FreeListNodes(mem->node_memory) > 0)) {
      errno = EBUSY;
      return NULL;
    };
    mem->hash_memory = _del_FreeList(mem->hash_memory, force);
    mem->node_memory = _del_FreeList(mem->node_memory, force);
    mem->string_memory = _del_StringMem(mem->string_memory, force);
    free(mem);
  };
  return NULL;
}

/*.......................................................................
 * Create a new hash table.
 *
 * Input:
 *  mem       HashMemory *  An optional free-list for use in allocating
 *                          HashTable containers and nodes. See explanation
 *                          in hash.h. If you are going to allocate more
 *                          than one hash table, then it will be more
 *                          efficient to allocate a single free-list for
 *                          all of them than to force each hash table
 *                          to allocate its own private free-list.
 *  size             int    The size of the hash table. Best performance
 *                          will be acheived if this is a prime number.
 *  hcase       HashCase    Specify how symbol case is considered when
 *                          looking up symbols, from:
 *                           IGNORE_CASE - Upper and lower case versions
 *                                         of a letter are treated as
 *                                         being identical.
 *                           HONOUR_CASE - Upper and lower case versions
 *                                         of a letter are treated as
 *                                         being distinct.
 *                          characters in a lookup name is significant.
 *  app_data        void *  Optional application data to be registered
 *                          to the table. This is presented to user
 *                          provided SYM_DEL_FN() symbol destructors along
 *                          with the symbol data.
 *  del_fn() HASH_DEL_FN(*) If you want app_data to be free'd when the
 *                          hash-table is destroyed, register a suitable
 *                          destructor function here.
 * Output:
 *  return HashTable *  The new hash table, or NULL on error.
 */
HashTable *_new_HashTable(HashMemory *mem, int size, HashCase hcase,
			 void *app_data, HASH_DEL_FN(*del_fn))
{
  HashTable *hash;         /* The table to be returned */
  int allocate_mem = !mem; /* True if mem should be internally allocated */
  int i;
/*
 * Check arguments.
 */
  if(size <= 0) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Allocate an internal free-list?
 */
  if(allocate_mem) {
    mem = _new_HashMemory(1, 100);
    if(!mem)
      return NULL;
  };
/*
 * Allocate the container.
 */
  hash = (HashTable *) _new_FreeListNode(mem->hash_memory);
  if(!hash) {
    errno = ENOMEM;
    if(allocate_mem)
      mem = _del_HashMemory(mem, 1);
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize
 * the container at least up to the point at which it can safely
 * be passed to _del_HashTable().
 */
  hash->mem = mem;
  hash->internal_mem = allocate_mem;
  hash->case_sensitive = hcase==HONOUR_CASE;
  hash->size = size;
  hash->bucket = NULL;
  hash->keycmp = hash->case_sensitive ? _ht_strcmp : _ht_lower_strcmp;
  hash->app_data = app_data;
  hash->del_fn = del_fn;
/*
 * Allocate the array of 'size' hash buckets.
 */
  hash->bucket = (HashBucket *) malloc(sizeof(HashBucket) * size);
  if(!hash->bucket) {
    errno = ENOMEM;
    return _del_HashTable(hash);
  };
/*
 * Initialize the bucket array.
 */
  for(i=0; i<size; i++) {
    HashBucket *b = hash->bucket + i;
    b->head = NULL;
    b->count = 0;
  };
/*
 * The table is ready for use - albeit currently empty.
 */
  return hash;
}

/*.......................................................................
 * Delete a hash-table.
 *
 * Input:
 *  hash   HashTable *  The hash table to be deleted.
 * Output:
 *  return HashTable *  The deleted hash table (always NULL).
 */
HashTable *_del_HashTable(HashTable *hash)
{
  if(hash) {
/*
 * Clear and delete the bucket array.
 */
    if(hash->bucket) {
      _clear_HashTable(hash);
      free(hash->bucket);
      hash->bucket = NULL;
    };
/*
 * Delete application data.
 */
    if(hash->del_fn)
      hash->del_fn(hash->app_data);
/*
 * If the hash table was allocated from an internal free-list, delete
 * it and the hash table by deleting the free-list. Otherwise just
 * return the hash-table to the external free-list.
 */
    if(hash->internal_mem)
      _del_HashMemory(hash->mem, 1);
    else
      hash = (HashTable *) _del_FreeListNode(hash->mem->hash_memory, hash);
  };
  return NULL;
}

/*.......................................................................
 * Create and install a new entry in a hash table. If an entry with the
 * same name already exists, replace its contents with the new data.
 *
 * Input:
 *  hash   HashTable *  The hash table to insert the symbol into.
 *  name  const char *  The name to tag the entry with.
 *  code         int    An application-specific code to be stored in
 *                      the entry.
 *  fn  void (*)(void)  An application-specific function to be stored
 *                      in the entry.
 *  data        void *  An application-specific pointer to data to be
 *                      associated with the entry, or NULL if not
 *                      relevant.
 *  del_fn SYM_DEL_FN(*) An optional destructor function. When the
 *                      symbol is deleted this function will be called
 *                      with the 'code' and 'data' arguments given
 *                      above. Any application data that was registered
 *                      to the table via the app_data argument of
 *                      _new_HashTable() will also be passed.
 * Output:
 *  return  HashNode *  The new entry, or NULL if there was insufficient
 *                      memory or the arguments were invalid.
 */
Symbol *_new_HashSymbol(HashTable *hash, const char *name, int code,
			void (*fn)(void), void *data, SYM_DEL_FN(*del_fn))
{
  HashBucket *bucket;  /* The hash-bucket associated with the name */
  HashNode *node;      /* The new node */
/*
 * Check arguments.
 */
  if(!hash || !name) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Get the hash bucket of the specified name.
 */
  bucket = _find_HashBucket(hash, name);
/*
 * See if a node with the same name already exists.
 */
  node = _find_HashNode(hash, bucket, name, NULL);
/*
 * If found, delete its contents by calling the user-supplied
 * destructor function, if provided.
 */
  if(node) {
    if(node->symbol.data && node->symbol.del_fn) {
      node->symbol.data = node->symbol.del_fn(hash->app_data, node->symbol.code,
					      node->symbol.data);
    };
/*
 * Allocate a new node if necessary.
 */
  } else {
    node = _new_HashNode(hash, name, code, fn, data, del_fn);
    if(!node)
      return NULL;
  };
/*
 * Install the node at the head of the hash-bucket list.
 */
  node->next = bucket->head;
  bucket->head = node;
  bucket->count++;
  return &node->symbol;
}

/*.......................................................................
 * Remove and delete a given hash-table entry.
 *
 * Input:
 *  hash   HashTable *  The hash table to find the symbol in.
 *  name  const char *  The name of the entry.
 * Output:
 *  return  HashNode *  The deleted hash node (always NULL).
 */
Symbol *_del_HashSymbol(HashTable *hash, const char *name)
{
  if(hash && name) {
    HashBucket *bucket = _find_HashBucket(hash, name);
    HashNode *prev;   /* The node preceding the located node */
    HashNode *node = _find_HashNode(hash, bucket, name, &prev);
/*
 * Node found?
 */
    if(node) {
/*
 * Remove the node from the bucket list.
 */
      if(prev) {
	prev->next = node->next;
      } else {
	bucket->head = node->next;
      };
/*
 * Record the loss of a node.
 */
      bucket->count--;
/*
 * Delete the node.
 */
      (void) _del_HashNode(hash, node);
    };
  };
  return NULL;
}

/*.......................................................................
 * Look up a symbol in the hash table.
 *
 * Input:
 *  hash   HashTable *   The table to look up the string in.
 *  name  const char *   The name of the symbol to look up.
 * Output:
 *  return    Symbol *   The located hash-table symbol, or NULL if not
 *                       found.
 */
Symbol *_find_HashSymbol(HashTable *hash, const char *name)
{
  HashBucket *bucket;  /* The hash-table bucket associated with name[] */
  HashNode *node;      /* The hash-table node of the requested symbol */
/*
 * Check arguments.
 */
  if(!hash)
    return NULL;
/*
 * Nothing to lookup?
 */
  if(!name)
    return NULL;
/*
 * Hash the name to a hash-table bucket.
 */
  bucket = _find_HashBucket(hash, name);
/*
 * Find the bucket entry that exactly matches the name.
 */
  node = _find_HashNode(hash, bucket, name, NULL);
  if(!node)
    return NULL;
  return &node->symbol;
}

/*.......................................................................
 * Private function used to allocate a hash-table node.
 * The caller is responsible for checking that the specified symbol
 * is unique and for installing the returned entry in the table.
 *
 * Input:
 *  hash     HashTable *  The table to allocate the node for.
 *  name    const char *  The name of the new entry.
 *  code           int    A user-supplied context code.
 *  fn  void (*)(void)    A user-supplied function pointer.
 *  data          void *  A user-supplied data pointer.
 *  del_fn  SYM_DEL_FN(*) An optional 'data' destructor function.
 * Output:
 *  return    HashNode *  The new node, or NULL on error.
 */
static HashNode *_new_HashNode(HashTable *hash, const char *name, int code,
			      void (*fn)(void), void *data, SYM_DEL_FN(*del_fn))
{
  HashNode *node;  /* The new node */
  size_t len;
/*
 * Allocate the new node from the free list.
 */
  node = (HashNode *) _new_FreeListNode(hash->mem->node_memory);
  if(!node)
    return NULL;
/*
 * Before attempting any operation that might fail, initialize the
 * contents of 'node' at least up to the point at which it can be
 * safely passed to _del_HashNode().
 */
  node->symbol.name = NULL;
  node->symbol.code = code;
  node->symbol.fn = fn;
  node->symbol.data = data;
  node->symbol.del_fn = del_fn;
  node->next = NULL;
/*
 * Allocate a copy of 'name'.
 */
  len = strlen(name) + 1;
  node->symbol.name = _new_StringMemString(hash->mem->string_memory, len);
  if(!node->symbol.name)
    return _del_HashNode(hash, node);
/*
 * If character-case is insignificant in the current table, convert the
 * name to lower case while copying it.
 */
  if(hash->case_sensitive) {
    strlcpy(node->symbol.name, name, len);
  } else {
    const char *src = name;
    char *dst = node->symbol.name;
    for( ; *src; src++,dst++)
      *dst = tolower(*src);
    *dst = '\0';
  };
  return node;
}

/*.......................................................................
 * Private function used to delete a hash-table node.
 * The node must have been removed from its list before calling this
 * function.
 *
 * Input:
 *  hash   HashTable *  The table for which the node was originally
 *                      allocated.
 *  node    HashNode *  The node to be deleted.
 * Output:
 *  return  HashNode *  The deleted node (always NULL).
 */
static HashNode *_del_HashNode(HashTable *hash, HashNode *node)
{
  if(node) {
    node->symbol.name = _del_StringMemString(hash->mem->string_memory,
					    node->symbol.name);
/*
 * Call the user-supplied data-destructor if provided.
 */
    if(node->symbol.data && node->symbol.del_fn)
      node->symbol.data = node->symbol.del_fn(hash->app_data,
					      node->symbol.code,
					      node->symbol.data);
/*
 * Return the node to the free-list.
 */
    node->next = NULL;
    node = (HashNode *) _del_FreeListNode(hash->mem->node_memory, node);
  };
  return NULL;
}

/*.......................................................................
 * Private function to locate the hash bucket associated with a given
 * name.
 *
 * This uses a hash-function described in the dragon-book
 * ("Compilers - Principles, Techniques and Tools", by Aho, Sethi and
 *  Ullman; pub. Adison Wesley) page 435.
 *
 * Input:
 *  hash    HashTable *   The table to look up the string in.
 *  name   const char *   The name of the symbol to look up.
 * Output:
 *  return HashBucket *   The located hash-bucket.
 */
static HashBucket *_find_HashBucket(HashTable *hash, const char *name)
{
  unsigned const char *kp;
  unsigned long h = 0L;
  if(hash->case_sensitive) {
    for(kp=(unsigned const char *) name; *kp; kp++)
      h = 65599UL * h + *kp;  /* 65599 is a prime close to 2^16 */
  } else {
    for(kp=(unsigned const char *) name; *kp; kp++)
      h = 65599UL * h + tolower((int)*kp);  /* 65599 is a prime close to 2^16 */
  };
  return hash->bucket + (h % hash->size);
}

/*.......................................................................
 * Search for a given name in the entries of a given bucket.
 *
 * Input:
 *  hash     HashTable *  The hash-table being searched.
 *  bucket  HashBucket *  The bucket to search (use _find_HashBucket()).
 *  name    const char *  The name to search for.
 * Output:
 *  prev      HashNode ** If prev!=NULL then the pointer to the node
 *                        preceding the located node in the list will
 *                        be recorded in *prev. This will be NULL either
 *                        if the name is not found or the located node is
 *                        at the head of the list of entries.
 * return     HashNode *  The located hash-table node, or NULL if not
 *                        found.
 */
static HashNode *_find_HashNode(HashTable *hash, HashBucket *bucket,
			       const char *name, HashNode **prev)
{
  HashNode *last;  /* The previously searched node */
  HashNode *node;  /* The node that is being searched */
/*
 * Search the list for a node containing the specified name.
 */
  for(last=NULL, node=bucket->head;
      node && hash->keycmp(node->symbol.name, name)!=0;
      last = node, node=node->next)
    ;
  if(prev)
    *prev = node ? last : NULL;
  return node;
}

/*.......................................................................
 * When hash->case_sensitive is zero this function is called
 * in place of strcmp(). In such cases the hash-table names are stored
 * as lower-case versions of the original strings so this function
 * performs the comparison against lower-case copies of the characters
 * of the string being compared.
 *
 * Input:
 *  node_key   const char *  The lower-case hash-node key being compared
 *                           against.
 *  look_key   const char *  The lookup key.
 * Output:
 *  return            int    <0 if node_key < look_key.
 *                            0 if node_key == look_key.
 *                           >0 if node_key > look_key.
 */
static int _ht_lower_strcmp(const char *node_key, const char *look_key)
{
  int cn;  /* The latest character from node_key[] */
  int cl;  /* The latest character from look_key[] */
  do {
    cn = *node_key++;
    cl = *look_key++;
  } while(cn && cn==tolower(cl));
  return cn - tolower(cl);
}

/*.......................................................................
 * This is a wrapper around strcmp for comparing hash-keys in a case
 * sensitive manner. The reason for having this wrapper, instead of using
 * strcmp() directly, is to make some C++ compilers happy. The problem
 * is that when the library is compiled with a C++ compiler, the
 * declaration of the comparison function is a C++ declaration, whereas
 * strcmp() is a pure C function and thus although it appears to have the
 * same declaration, the compiler disagrees.
 *
 * Input:
 *  node_key   char *  The lower-case hash-node key being compared against.
 *  look_key   char *  The lookup key.
 * Output:
 *  return      int    <0 if node_key < look_key.
 *                      0 if node_key == look_key.
 *                     >0 if node_key > look_key.
 */
static int _ht_strcmp(const char *node_key, const char *look_key)
{
  return strcmp(node_key, look_key);
}

/*.......................................................................
 * Empty a hash-table by deleting all of its entries.
 *
 * Input:
 *  hash    HashTable *  The hash table to clear.
 * Output:
 *  return        int    0 - OK.
 *                       1 - Invalid arguments.
 */
int _clear_HashTable(HashTable *hash)
{
  int i;
/*
 * Check the arguments.
 */
  if(!hash)
    return 1;
/*
 * Clear the contents of the bucket array.
 */
  for(i=0; i<hash->size; i++) {
    HashBucket *bucket = hash->bucket + i;
/*
 * Delete the list of active hash nodes from the bucket.
 */
    HashNode *node = bucket->head;
    while(node) {
      HashNode *next = node->next;
      (void) _del_HashNode(hash, node);
      node = next;
    };
/*
 * Mark the bucket as empty.
 */
    bucket->head = NULL;
    bucket->count = 0;
  };
  return 0;
}

/*.......................................................................
 * Execute a given function on each entry of a hash table, returning
 * before completion if the the specified function returns non-zero.
 *
 * Input:
 *  hash       HashTable *    The table to traverse.
 *  scan_fn HASH_SCAN_FN(*)   The function to call.
 *  context         void *    Optional caller-specific context data
 *                            to be passed to scan_fn().
 * Output:
 *  return           int      0 - OK.
 *                            1 - Either the arguments were invalid, or
 *                                scan_fn() returned non-zero at some
 *                                point.
 */
int _scan_HashTable(HashTable *hash, HASH_SCAN_FN(*scan_fn), void *context)
{
  int i;
/*
 * Check the arguments.
 */
  if(!hash || !scan_fn)
    return 1;
/*
 * Iterate through the buckets of the table.
 */
  for(i=0; i<hash->size; i++) {
    HashBucket *bucket = hash->bucket + i;
    HashNode *node;
/*
 * Iterate through the list of symbols that fall into bucket i,
 * passing each one to the caller-specified function.
 */
    for(node=bucket->head; node; node=node->next) {
      if(scan_fn(&node->symbol, context))
	return 1;
    };
  };
  return 0;
}
#ifndef hash_h
#define hash_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * The following macro can be used to prototype or define a
 * function that deletes the data of a symbol-table entry.
 *
 * Input:
 *  app_data void *  The _new_HashTable() app_data argument.
 *  code      int    The Symbol::code argument.
 *  sym_data void *  The Symbol::data argument to be deleted.
 * Output:
 *  return  void * The deleted data (always return NULL).
 */
#define SYM_DEL_FN(fn) void *(fn)(void *app_data, int code, void *sym_data)

/*
 * The following macro can be used to prototype or define a
 * function that deletes the application-data of a hash-table.
 *
 * Input:
 *  data    void * The _new_HashTable() 'app_data' argument to be
 *                 deleted.
 * Output:
 *  return  void * The deleted data (always return NULL).
 */
#define HASH_DEL_FN(fn) void *(fn)(void *app_data)

/*
 * The following is a container for recording the context
 * of a symbol in a manner that is independant of the particular
 * symbol-table implementation. Each hash-table entry contains
 * the following user supplied parameters:
 *
 * 1. An optional integral parameter 'code'. This is useful for
 *    enumerating a symbol or for describing what type of data
 *    or function is stored in the symbol.
 *
 * 2. An optional generic function pointer. This is useful for
 *    associating functions with names. The user is responsible
 *    for casting between the generic function type and the
 *    actual function type. The code field could be used to
 *    enumerate what type of function to cast to.
 *
 * 3. An optional generic pointer to a static or heap-allocated
 *    object. It is up to the user to cast this back to the
 *    appropriate object type. Again, the code field could be used
 *    to describe what type of object is stored there.
 *    If the object is dynamically allocated and should be discarded
 *    when the symbol is deleted from the symbol table, send a
 *    destructor function to have it deleted automatically.
 */
typedef struct {
  char *name;           /* The name of the symbol */
  int code;             /* Application supplied integral code */
  void (*fn)(void);     /* Application supplied generic function */
  void *data;           /* Application supplied context data */
  SYM_DEL_FN(*del_fn);  /* Data destructor function */
} Symbol;

/*
 * HashNode's and HashTable's are small objects. Separately allocating
 * many such objects would normally cause memory fragmentation. To
 * counter this, HashMemory objects are used. These contain
 * dedicated free-lists formed from large dynamically allocated arrays
 * of objects. One HashMemory object can be shared between multiple hash
 * tables (within a single thread).
 */
typedef struct HashMemory HashMemory;

  /* Create a free-list for allocation of hash tables and their nodes */

HashMemory *_new_HashMemory(int hash_count, int node_count);

  /* Delete a redundant free-list if not being used */

HashMemory *_del_HashMemory(HashMemory *mem, int force);

/*
 * Declare an alias for the private HashTable structure defined in
 * hash.c.
 */
typedef struct HashTable HashTable;

/*
 * Enumerate case-sensitivity options.
 */
typedef enum {
  IGNORE_CASE,     /* Ignore case when looking up symbols */
  HONOUR_CASE      /* Honor case when looking up symbols */
} HashCase;

  /* Create a new hash-table */

HashTable *_new_HashTable(HashMemory *mem, int size, HashCase hcase,
			  void *app_data, HASH_DEL_FN(*del_fn));

  /* Delete a reference to a hash-table */

HashTable *_del_HashTable(HashTable *hash);

  /* Add an entry to a hash table */

Symbol *_new_HashSymbol(HashTable *hash, const char *key, int code,
			void (*fn)(void), void *data, SYM_DEL_FN(*del_fn));

  /* Remove and delete all the entries in a given hash table */

int _clear_HashTable(HashTable *hash);

  /* Remove and delete a given hash-table entry */

Symbol *_del_HashSymbol(HashTable *hash, const char *key);

  /* Lookup a given hash-table entry */

Symbol *_find_HashSymbol(HashTable *hash, const char *key);

  /* Execute a given function on each entry of a hash table, returning */
  /*  before completion if the specified function returns non-zero. */

#define HASH_SCAN_FN(fn)  int (fn)(Symbol *sym, void *context)

int _scan_HashTable(HashTable *hash, HASH_SCAN_FN(*scan_fn), void *context);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <time.h>
#include <errno.h>

#include "ioutil.h"
#include "history.h"
#include "freelist.h"
#include "errmsg.h"

/*
 * History lines are split into sub-strings of GLH_SEG_SIZE
 * characters.  To avoid wasting space in the GlhLineSeg structure,
 * this should be a multiple of the size of a pointer.
 */
#define GLH_SEG_SIZE 16

/*
 * GlhLineSeg structures contain fixed sized segments of a larger
 * string. These are linked into lists to record strings, with all but
 * the last segment having GLH_SEG_SIZE characters. The last segment
 * of a string is terminated within the GLH_SEG_SIZE characters with a
 * '\0'.
 */
typedef struct GlhLineSeg GlhLineSeg;
struct GlhLineSeg {
  GlhLineSeg *next;     /* The next sub-string of the history line */
  char s[GLH_SEG_SIZE]; /* The sub-string. Beware that only the final */
                        /*  substring of a line, as indicated by 'next' */
                        /*  being NULL, is '\0' terminated. */
};

/*
 * History lines are recorded in a hash table, such that repeated
 * lines are stored just once.
 *
 * Start by defining the size of the hash table. This should be a
 * prime number.
 */
#define GLH_HASH_SIZE 113

typedef struct GlhHashBucket GlhHashBucket;

/*
 * Each history line will be represented in the hash table by a
 * structure of the following type.
 */
typedef struct GlhHashNode GlhHashNode;
struct GlhHashNode {
  GlhHashBucket *bucket; /* The parent hash-table bucket of this node */
  GlhHashNode *next;     /* The next in the list of nodes within the */
                         /*  parent hash-table bucket. */
  GlhLineSeg *head;      /* The list of sub-strings which make up a line */
  int len;               /* The length of the line, excluding any '\0' */
  int used;              /* The number of times this string is pointed to by */
                         /*  the time-ordered list of history lines. */
  int reported;          /* A flag that is used when searching to ensure that */
                         /*  a line isn't reported redundantly. */
};

/*
 * How many new GlhHashNode elements should be allocated at a time?
 */
#define GLH_HASH_INCR 50

static int _glh_is_line(GlhHashNode *hash, const char *line, size_t n);
static int _glh_line_matches_prefix(GlhHashNode *line, GlhHashNode *prefix);
static void _glh_return_line(GlhHashNode *hash, char *line, size_t dim);

/*
 * All history lines which hash to a given bucket in the hash table, are
 * recorded in a structure of the following type.
 */
struct GlhHashBucket {
  GlhHashNode *lines;  /* The list of history lines which fall in this bucket */
};

static GlhHashBucket *glh_find_bucket(GlHistory *glh, const char *line,
				      size_t n);
static GlhHashNode *glh_find_hash_node(GlhHashBucket *bucket, const char *line,
				       size_t n);

typedef struct {
  FreeList *node_mem;  /* A free-list of GlhHashNode structures */
  GlhHashBucket bucket[GLH_HASH_SIZE]; /* The buckets of the hash table */
} GlhLineHash;

/*
 * GlhLineNode's are used to record history lines in time order.
 */
typedef struct GlhLineNode GlhLineNode;
struct GlhLineNode {
  long id;             /* The unique identifier of this history line */
  time_t timestamp;    /* The time at which the line was archived */
  unsigned group;      /* The identifier of the history group to which the */
                       /*  the line belongs. */
  GlhLineNode *next;   /* The next youngest line in the list */
  GlhLineNode *prev;   /* The next oldest line in the list */
  GlhHashNode *line;   /* The hash-table entry of the history line */
};

/*
 * The number of GlhLineNode elements per freelist block.
 */
#define GLH_LINE_INCR 100

/*
 * Encapsulate the time-ordered list of historical lines.
 */
typedef struct {
  FreeList *node_mem;  /* A freelist of GlhLineNode objects */
  GlhLineNode *head;   /* The oldest line in the list */
  GlhLineNode *tail;   /* The newest line in the list */
} GlhLineList;

/*
 * The _glh_lookup_history() returns copies of history lines in a
 * dynamically allocated array. This array is initially allocated
 * GLH_LOOKUP_SIZE bytes. If subsequently this size turns out to be
 * too small, realloc() is used to increase its size to the required
 * size plus GLH_LOOKUP_MARGIN. The idea of the later parameter is to
 * reduce the number of realloc() operations needed.
 */
#define GLH_LBUF_SIZE 300
#define GLH_LBUF_MARGIN 100

/*
 * Encapsulate all of the resources needed to store historical input lines.
 */
struct GlHistory {
  ErrMsg *err;         /* The error-reporting buffer */
  GlhLineSeg *buffer;  /* An array of sub-line nodes to be partitioned */
                       /* into lists of sub-strings recording input lines. */
  int nbuff;           /* The allocated dimension of buffer[] */
  GlhLineSeg *unused;  /* The list of free nodes in buffer[] */
  GlhLineList list;    /* A time ordered list of history lines */
  GlhLineNode *recall; /* The last line recalled, or NULL if no recall */
                       /*  session is currently active. */
  GlhLineNode *id_node;/* The node at which the last ID search terminated */
  GlhLineHash hash;    /* A hash-table of reference-counted history lines */
  GlhHashNode *prefix; /* A pointer to a line containing the prefix that */
                       /*  is being searched for. Note that if prefix==NULL */
                       /*  and prefix_len>0, this means that no line in */
                       /*  the buffer starts with the requested prefix. */
  int prefix_len;      /* The length of the prefix being searched for. */
  char *lbuf;          /* The array in which _glh_lookup_history() returns */
                       /*  history lines */
  int lbuf_dim;        /* The allocated size of lbuf[] */
  int nbusy;           /* The number of line segments in buffer[] that are */
                       /*  currently being used to record sub-lines */
  int nfree;           /* The number of line segments in buffer that are */
                       /*  not currently being used to record sub-lines */
  unsigned long seq;   /* The next ID to assign to a line node */
  unsigned group;      /* The identifier of the current history group */
  int nline;           /* The number of lines currently in the history list */
  int max_lines;       /* Either -1 or a ceiling on the number of lines */
  int enable;          /* If false, ignore history additions and lookups */
};

#ifndef WITHOUT_FILE_SYSTEM
static int _glh_cant_load_history(GlHistory *glh, const char *filename,
				  int lineno, const char *message, FILE *fp);
static int _glh_cant_save_history(GlHistory *glh, const char *message,
				  const char *filename, FILE *fp);
static int _glh_write_timestamp(FILE *fp, time_t timestamp);
static int _glh_decode_timestamp(char *string, char **endp, time_t *timestamp);
#endif
static void _glh_discard_line(GlHistory *glh, GlhLineNode *node);
static GlhLineNode *_glh_find_id(GlHistory *glh, GlhLineID id);
static GlhHashNode *_glh_acquire_copy(GlHistory *glh, const char *line,
				      size_t n);
static GlhHashNode *_glh_discard_copy(GlHistory *glh, GlhHashNode *hnode);
static int _glh_prepare_for_recall(GlHistory *glh, char *line);

/*
 * The following structure and functions are used to iterate through
 * the characters of a segmented history line.
 */
typedef struct {
  GlhLineSeg *seg;  /* The line segment that the next character will */
                    /*  be returned from. */
  int posn;         /* The index in the above line segment, containing */
                    /*  the next unread character. */
  char c;           /* The current character in the input line */
} GlhLineStream;
static void glh_init_stream(GlhLineStream *str, GlhHashNode *line);
static void glh_step_stream(GlhLineStream *str);

/*
 * See if search prefix contains any globbing characters.
 */
static int glh_contains_glob(GlhHashNode *prefix);
/*
 * Match a line against a search pattern.
 */
static int glh_line_matches_glob(GlhLineStream *lstr, GlhLineStream *pstr);
static int glh_matches_range(char c, GlhLineStream *pstr);

/*.......................................................................
 * Create a line history maintenance object.
 *
 * Input:
 *  buflen     size_t    The number of bytes to allocate to the
 *                       buffer that is used to record all of the
 *                       most recent lines of user input that will fit.
 *                       If buflen==0, no buffer will be allocated.
 * Output:
 *  return  GlHistory *  The new object, or NULL on error.
 */
GlHistory *_new_GlHistory(size_t buflen)
{
  GlHistory *glh;  /* The object to be returned */
  int i;
/*
 * Allocate the container.
 */
  glh = (GlHistory *) malloc(sizeof(GlHistory));
  if(!glh) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to _del_GlHistory().
 */
  glh->err = NULL;
  glh->buffer = NULL;
  glh->nbuff = (buflen+GLH_SEG_SIZE-1) / GLH_SEG_SIZE;
  glh->unused = NULL;
  glh->list.node_mem = NULL;
  glh->list.head = glh->list.tail = NULL;
  glh->recall = NULL;
  glh->id_node = NULL;
  glh->hash.node_mem = NULL;
  for(i=0; i<GLH_HASH_SIZE; i++)
    glh->hash.bucket[i].lines = NULL;
  glh->prefix = NULL;
  glh->lbuf = NULL;
  glh->lbuf_dim = 0;
  glh->nbusy = 0;
  glh->nfree = glh->nbuff;
  glh->seq = 0;
  glh->group = 0;
  glh->nline = 0;
  glh->max_lines = -1;
  glh->enable = 1;
/*
 * Allocate a place to record error messages.
 */
  glh->err = _new_ErrMsg();
  if(!glh->err)
    return _del_GlHistory(glh);
/*
 * Allocate the buffer, if required.
 */
  if(glh->nbuff > 0) {
    glh->nbuff = glh->nfree;
    glh->buffer = (GlhLineSeg *) malloc(sizeof(GlhLineSeg) * glh->nbuff);
    if(!glh->buffer) {
      errno = ENOMEM;
      return _del_GlHistory(glh);
    };
/*
 * All nodes of the buffer are currently unused, so link them all into
 * a list and make glh->unused point to the head of this list.
 */
    glh->unused = glh->buffer;
    for(i=0; i<glh->nbuff-1; i++) {
      GlhLineSeg *seg = glh->unused + i;
      seg->next = seg + 1;
    };
    glh->unused[i].next = NULL;
  };
/*
 * Allocate the GlhLineNode freelist.
 */
  glh->list.node_mem = _new_FreeList(sizeof(GlhLineNode), GLH_LINE_INCR);
  if(!glh->list.node_mem)
    return _del_GlHistory(glh);
/*
 * Allocate the GlhHashNode freelist.
 */
  glh->hash.node_mem = _new_FreeList(sizeof(GlhLineNode), GLH_HASH_INCR);
  if(!glh->hash.node_mem)
    return _del_GlHistory(glh);
/*
 * Allocate the array that _glh_lookup_history() uses to return a
 * copy of a given history line. This will be resized when necessary.
 */
  glh->lbuf_dim = GLH_LBUF_SIZE;
  glh->lbuf = (char *) malloc(glh->lbuf_dim);
  if(!glh->lbuf) {
    errno = ENOMEM;
    return _del_GlHistory(glh);
  };
  return glh;
}

/*.......................................................................
 * Delete a GlHistory object.
 *
 * Input:
 *  glh    GlHistory *  The object to be deleted.
 * Output:
 *  return GlHistory *  The deleted object (always NULL).
 */
GlHistory *_del_GlHistory(GlHistory *glh)
{
  if(glh) {
/*
 * Delete the error-message buffer.
 */
    glh->err = _del_ErrMsg(glh->err);
/*
 * Delete the buffer.
 */
    if(glh->buffer) {
      free(glh->buffer);
      glh->buffer = NULL;
      glh->unused = NULL;
    };
/*
 * Delete the freelist of GlhLineNode's.
 */
    glh->list.node_mem = _del_FreeList(glh->list.node_mem, 1);
/*
 * The contents of the list were deleted by deleting the freelist.
 */
    glh->list.head = NULL;
    glh->list.tail = NULL;
/*
 * Delete the freelist of GlhHashNode's.
 */
    glh->hash.node_mem = _del_FreeList(glh->hash.node_mem, 1);
/*
 * Delete the lookup buffer.
 */
    if(glh->lbuf)
      free(glh->lbuf);
/*
 * Delete the container.
 */
    free(glh);
  };
  return NULL;
}

/*.......................................................................
 * Append a new line to the history list, deleting old lines to make
 * room, if needed.
 *
 * Input:
 *  glh  GlHistory *  The input-line history maintenance object.
 *  line      char *  The line to be archived.
 *  force      int    Unless this flag is non-zero, empty lines aren't
 *                    archived. This flag requests that the line be
 *                    archived regardless.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */
int _glh_add_history(GlHistory *glh, const char *line, int force)
{
  int slen;         /* The length of the line to be recorded (minus the '\0') */
  int empty;          /* True if the string is empty */
  const char *nlptr;  /* A pointer to a newline character in line[] */
  GlhHashNode *hnode; /* The hash-table node of the line */
  GlhLineNode *lnode; /* A node in the time-ordered list of lines */
  int i;
/*
 * Check the arguments.
 */
  if(!glh || !line) {
    errno = EINVAL;
    return 1;
  };
/*
 * Is history enabled?
 */
  if(!glh->enable || !glh->buffer || glh->max_lines == 0)
    return 0;
/*
 * Cancel any ongoing search.
 */
  if(_glh_cancel_search(glh))
    return 1;
/*
 * How long is the string to be recorded, being careful not to include
 * any terminating '\n' character.
 */
  nlptr = strchr(line, '\n');
  if(nlptr)
    slen = (nlptr - line);
  else
    slen = strlen(line);
/*
 * Is the line empty?
 */
  empty = 1;
  for(i=0; i<slen && empty; i++)
    empty = isspace((int)(unsigned char) line[i]);
/*
 * If the line is empty, don't add it to the buffer unless explicitly
 * told to.
 */
  if(empty && !force)
    return 0;
/*
 * Has an upper limit to the number of lines in the history list been
 * specified?
 */
  if(glh->max_lines >= 0) {
/*
 * If necessary, remove old lines until there is room to add one new
 * line without exceeding the specified line limit.
 */
    while(glh->nline > 0 && glh->nline >= glh->max_lines)
      _glh_discard_line(glh, glh->list.head);
/*
 * We can't archive the line if the maximum number of lines allowed is
 * zero.
 */
    if(glh->max_lines == 0)
      return 0;
  };
/*
 * Unless already stored, store a copy of the line in the history buffer,
 * then return a reference-counted hash-node pointer to this copy.
 */
  hnode = _glh_acquire_copy(glh, line, slen);
  if(!hnode) {
    _err_record_msg(glh->err, "No room to store history line", END_ERR_MSG);
    errno = ENOMEM;
    return 1;
  };
/*
 * Allocate a new node in the time-ordered list of lines.
 */
  lnode = (GlhLineNode *) _new_FreeListNode(glh->list.node_mem);
/*
 * If a new line-node couldn't be allocated, discard our copy of the
 * stored line before reporting the error.
 */
  if(!lnode) {
    hnode = _glh_discard_copy(glh, hnode);
    _err_record_msg(glh->err, "No room to store history line", END_ERR_MSG);
    errno = ENOMEM;
    return 1;
  };
/*
 * Record a pointer to the hash-table record of the line in the new
 * list node.
 */
  lnode->id = glh->seq++;
  lnode->timestamp = time(NULL);
  lnode->group = glh->group;
  lnode->line = hnode;
/*
 * Append the new node to the end of the time-ordered list.
 */
  if(glh->list.head)
    glh->list.tail->next = lnode;
  else
    glh->list.head = lnode;
  lnode->next = NULL;
  lnode->prev = glh->list.tail;
  glh->list.tail = lnode;
/*
 * Record the addition of a line to the list.
 */
  glh->nline++;
  return 0;
}

/*.......................................................................
 * Recall the next oldest line that has the search prefix last recorded
 * by _glh_search_prefix().
 *
 * Input:
 *  glh  GlHistory *  The input-line history maintenance object.
 *  line      char *  The input line buffer. On input this should contain
 *                    the current input line, and on output, if anything
 *                    was found, its contents will have been replaced
 *                    with the matching line.
 *  dim     size_t    The allocated dimension of the line buffer.
 * Output:
 *  return    char *  A pointer to line[0], or NULL if not found.
 */
char *_glh_find_backwards(GlHistory *glh, char *line, size_t dim)
{
  GlhLineNode *node;     /* The line location node being checked */
  GlhHashNode *old_line; /* The previous recalled line */
/*
 * Check the arguments.
 */
  if(!glh || !line) {
    if(glh)
      _err_record_msg(glh->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return NULL;
  };
/*
 * Is history enabled?
 */
  if(!glh->enable || !glh->buffer || glh->max_lines == 0)
    return NULL;
/*
 * Check the line dimensions.
 */
  if(dim < strlen(line) + 1) {
    _err_record_msg(glh->err, "'dim' argument inconsistent with strlen(line)",
		    END_ERR_MSG);
    errno = EINVAL;
    return NULL;
  };
/*
 * Preserve the input line if needed.
 */
  if(_glh_prepare_for_recall(glh, line))
    return NULL;
/*
 * From where should we start the search?
 */
  if(glh->recall) {
    node = glh->recall->prev;
    old_line = glh->recall->line;
  } else {
    node = glh->list.tail;
    old_line = NULL;
  };
/*
 * Search backwards through the list for the first match with the
 * prefix string that differs from the last line that was recalled.
 */
  while(node && (node->group != glh->group || node->line == old_line ||
	  !_glh_line_matches_prefix(node->line, glh->prefix)))
    node = node->prev;
/*
 * Was a matching line found?
 */
  if(node) {
/*
 * Recall the found node as the starting point for subsequent
 * searches.
 */
    glh->recall = node;
/*
 * Copy the matching line into the provided line buffer.
 */
    _glh_return_line(node->line, line, dim);
/*
 * Return it.
 */
    return line;
  };
/*
 * No match was found.
 */
  return NULL;
}

/*.......................................................................
 * Recall the next newest line that has the search prefix last recorded
 * by _glh_search_prefix().
 *
 * Input:
 *  glh  GlHistory *  The input-line history maintenance object.
 *  line      char *  The input line buffer. On input this should contain
 *                    the current input line, and on output, if anything
 *                    was found, its contents will have been replaced
 *                    with the matching line.
 *  dim     size_t    The allocated dimensions of the line buffer.
 * Output:
 *  return    char *  The line requested, or NULL if no matching line
 *                    was found.
 */
char *_glh_find_forwards(GlHistory *glh, char *line, size_t dim)
{
  GlhLineNode *node;     /* The line location node being checked */
  GlhHashNode *old_line; /* The previous recalled line */
/*
 * Check the arguments.
 */
  if(!glh || !line) {
    if(glh)
      _err_record_msg(glh->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return NULL;
  };
/*
 * Is history enabled?
 */
  if(!glh->enable || !glh->buffer || glh->max_lines == 0)
    return NULL;
/*
 * Check the line dimensions.
 */
  if(dim < strlen(line) + 1) {
    _err_record_msg(glh->err, "'dim' argument inconsistent with strlen(line)",
		    END_ERR_MSG);
    errno = EINVAL;
    return NULL;
  };
/*
 * From where should we start the search?
 */
  if(glh->recall) {
    node = glh->recall->next;
    old_line = glh->recall->line;
  } else {
    return NULL;
  };
/*
 * Search forwards through the list for the first match with the
 * prefix string.
 */
  while(node && (node->group != glh->group || node->line == old_line ||
	  !_glh_line_matches_prefix(node->line, glh->prefix)))
    node = node->next;
/*
 * Was a matching line found?
 */
  if(node) {
/*
 * Copy the matching line into the provided line buffer.
 */
    _glh_return_line(node->line, line, dim);
/*
 * Record the starting point of the next search.
 */
    glh->recall = node;
/*
 * If we just returned the line that was being entered when the search
 * session first started, cancel the search.
 */
    if(node == glh->list.tail)
      _glh_cancel_search(glh);
/*
 * Return the matching line to the user.
 */
    return line;
  };
/*
 * No match was found.
 */
  return NULL;
}

/*.......................................................................
 * If a search is in progress, cancel it.
 *
 * This involves discarding the line that was temporarily saved by
 * _glh_find_backwards() when the search was originally started,
 * and reseting the search iteration pointer to NULL.
 *
 * Input:
 *  glh  GlHistory *  The input-line history maintenance object.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */
int _glh_cancel_search(GlHistory *glh)
{
/*
 * Check the arguments.
 */
  if(!glh) {
    errno = EINVAL;
    return 1;
  };
/*
 * If there wasn't a search in progress, do nothing.
 */
  if(!glh->recall)
    return 0;
/*
 * Reset the search pointers. Note that it is essential to set
 * glh->recall to NULL before calling _glh_discard_line(), to avoid an
 * infinite recursion.
 */
  glh->recall = NULL;
/*
 * Delete the node of the preserved line.
 */
  _glh_discard_line(glh, glh->list.tail);
  return 0;
}

/*.......................................................................
 * Set the prefix of subsequent history searches.
 *
 * Input:
 *  glh    GlHistory *  The input-line history maintenance object.
 *  line  const char *  The command line who's prefix is to be used.
 *  prefix_len   int    The length of the prefix.
 * Output:
 *  return       int    0 - OK.
 *                      1 - Error.
 */
int _glh_search_prefix(GlHistory *glh, const char *line, int prefix_len)
{
/*
 * Check the arguments.
 */
  if(!glh) {
    errno = EINVAL;
    return 1;
  };
/*
 * Is history enabled?
 */
  if(!glh->enable || !glh->buffer || glh->max_lines == 0)
    return 0;
/*
 * Discard any existing prefix.
 */
  glh->prefix = _glh_discard_copy(glh, glh->prefix);
/*
 * Only store a copy of the prefix string if it isn't a zero-length string.
 */
  if(prefix_len > 0) {
/*
 * Get a reference-counted copy of the prefix from the history cache buffer.
 */
    glh->prefix = _glh_acquire_copy(glh, line, prefix_len);
/*
 * Was there insufficient buffer space?
 */
    if(!glh->prefix) {
      _err_record_msg(glh->err, "The search prefix is too long to store",
		      END_ERR_MSG);
      errno = ENOMEM;
      return 1;
    };
  };
  return 0;
}

/*.......................................................................
 * Recall the oldest recorded line.
 *
 * Input:
 *  glh  GlHistory *  The input-line history maintenance object.
 *  line      char *  The input line buffer. On input this should contain
 *                    the current input line, and on output, its contents
 *                    will have been replaced with the oldest line.
 *  dim     size_t    The allocated dimensions of the line buffer.
 * Output:
 *  return    char *  A pointer to line[0], or NULL if not found.
 */
char *_glh_oldest_line(GlHistory *glh, char *line, size_t dim)
{
  GlhLineNode *node; /* The line location node being checked */
/*
 * Check the arguments.
 */
  if(!glh || !line) {
    if(glh)
      _err_record_msg(glh->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return NULL;
  };
/*
 * Is history enabled?
 */
  if(!glh->enable || !glh->buffer || glh->max_lines == 0)
    return NULL;
/*
 * Check the line dimensions.
 */
  if(dim < strlen(line) + 1) {
    _err_record_msg(glh->err, "'dim' argument inconsistent with strlen(line)",
		    END_ERR_MSG);
    errno = EINVAL;
    return NULL;
  };
/*
 * Preserve the input line if needed.
 */
  if(_glh_prepare_for_recall(glh, line))
    return NULL;
/*
 * Locate the oldest line that belongs to the current group.
 */
  for(node=glh->list.head; node && node->group != glh->group;
      node = node->next)
    ;
/*
 * No line found?
 */
  if(!node)
    return NULL;
/*
 * Record the above node as the starting point for subsequent
 * searches.
 */
  glh->recall = node;
/*
 * Copy the recalled line into the provided line buffer.
 */
  _glh_return_line(node->line, line, dim);
/*
 * If we just returned the line that was being entered when the search
 * session first started, cancel the search.
 */
  if(node == glh->list.tail)
    _glh_cancel_search(glh);
  return line;
}

/*.......................................................................
 * Recall the line that was being entered when the search started.
 *
 * Input:
 *  glh  GlHistory *  The input-line history maintenance object.
 *  line      char *  The input line buffer. On input this should contain
 *                    the current input line, and on output, its contents
 *                    will have been replaced with the line that was
 *                    being entered when the search was started.
 *  dim     size_t    The allocated dimensions of the line buffer.
 * Output:
 *  return    char *  A pointer to line[0], or NULL if not found.
 */
char *_glh_current_line(GlHistory *glh, char *line, size_t dim)
{
/*
 * Check the arguments.
 */
  if(!glh || !line) {
    if(glh)
      _err_record_msg(glh->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return NULL;
  };
/*
 * If history isn't enabled, or no history search has yet been started,
 * ignore the call.
 */
  if(!glh->enable || !glh->buffer || glh->max_lines == 0 || !glh->recall)
    return NULL;
/*
 * Check the line dimensions.
 */
  if(dim < strlen(line) + 1) {
    _err_record_msg(glh->err, "'dim' argument inconsistent with strlen(line)",
		    END_ERR_MSG);
    errno = EINVAL;
    return NULL;
  };
/*
 * Copy the recalled line into the provided line buffer.
 */
  _glh_return_line(glh->list.tail->line, line, dim);
/*
 * Since we have returned to the starting point of the search, cancel it.
 */
  _glh_cancel_search(glh);
  return line;
}

/*.......................................................................
 * Query the id of a history line offset by a given number of lines from
 * the one that is currently being recalled. If a recall session isn't
 * in progress, or the offset points outside the history list, 0 is
 * returned.
 *
 * Input:
 *  glh    GlHistory *  The input-line history maintenance object.
 *  offset       int    The line offset (0 for the current line, < 0
 *                      for an older line, > 0 for a newer line.
 * Output:
 *  return GlhLineID    The identifier of the line that is currently
 *                      being recalled, or 0 if no recall session is
 *                      currently in progress.
 */
GlhLineID _glh_line_id(GlHistory *glh, int offset)
{
  GlhLineNode *node; /* The line location node being checked */
/*
 * Is history enabled?
 */
  if(!glh->enable || !glh->buffer || glh->max_lines == 0)
    return 0;
/*
 * Search forward 'offset' lines to find the required line.
 */
  if(offset >= 0) {
    for(node=glh->recall; node && offset != 0; node=node->next) {
      if(node->group == glh->group)
	offset--;
    };
  } else {
    for(node=glh->recall; node && offset != 0; node=node->prev) {
      if(node->group == glh->group)
	offset++;
    };
  };
  return node ? node->id : 0;
}

/*.......................................................................
 * Recall a line by its history buffer ID. If the line is no longer
 * in the buffer, or the id is zero, NULL is returned.
 *
 * Input:
 *  glh  GlHistory *  The input-line history maintenance object.
 *  id   GlhLineID    The ID of the line to be returned.
 *  line      char *  The input line buffer. On input this should contain
 *                    the current input line, and on output, its contents
 *                    will have been replaced with the saved line.
 *  dim     size_t    The allocated dimensions of the line buffer.
 * Output:
 *  return    char *  A pointer to line[0], or NULL if not found.
 */
char *_glh_recall_line(GlHistory *glh, GlhLineID id, char *line, size_t dim)
{
  GlhLineNode *node; /* The line location node being checked */
/*
 * Is history enabled?
 */
  if(!glh->enable || !glh->buffer || glh->max_lines == 0)
    return NULL;
/*
 * Preserve the input line if needed.
 */
  if(_glh_prepare_for_recall(glh, line))
    return NULL;
/*
 * Search for the specified line.
 */
  node = _glh_find_id(glh, id);
/*
 * Not found?
 */
  if(!node || node->group != glh->group)
    return NULL;
/*
 * Record the node of the matching line as the starting point
 * for subsequent searches.
 */
  glh->recall = node;
/*
 * Copy the recalled line into the provided line buffer.
 */
  _glh_return_line(node->line, line, dim);
  return line;
}

/*.......................................................................
 * Save the current history in a specified file.
 *
 * Input:
 *  glh        GlHistory *  The input-line history maintenance object.
 *  filename  const char *  The name of the new file to record the
 *                          history in.
 *  comment   const char *  Extra information such as timestamps will
 *                          be recorded on a line started with this
 *                          string, the idea being that the file can
 *                          double as a command file. Specify "" if
 *                          you don't care.
 *  max_lines        int    The maximum number of lines to save, or -1
 *                          to save all of the lines in the history
 *                          list.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
int _glh_save_history(GlHistory *glh, const char *filename, const char *comment,
		      int max_lines)
{
#ifdef WITHOUT_FILE_SYSTEM
  _err_record_msg(glh->err, "Can't save history without filesystem access",
		  END_ERR_MSG);
  errno = EINVAL;
  return 1;
#else
  FILE *fp;          /* The output file */
  GlhLineNode *node; /* The line being saved */
  GlhLineNode *head; /* The head of the list of lines to be saved */
  GlhLineSeg *seg;   /* One segment of a line being saved */
/*
 * Check the arguments.
 */
  if(!glh || !filename || !comment) {
    if(glh)
      _err_record_msg(glh->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Attempt to open the specified file.
 */
  fp = fopen(filename, "w");
  if(!fp)
    return _glh_cant_save_history(glh, "Can't open", filename, NULL);
/*
 * If a ceiling on the number of lines to save was specified, count
 * that number of lines backwards, to find the first line to be saved.
 */
  head = NULL;
  if(max_lines >= 0) {
    for(head=glh->list.tail; head && --max_lines > 0; head=head->prev)
      ;
  };
  if(!head)
    head = glh->list.head;
/*
 * Write the contents of the history buffer to the history file, writing
 * associated data such as timestamps, to a line starting with the
 * specified comment string.
 */
  for(node=head; node; node=node->next) {
/*
 * Write peripheral information associated with the line, as a comment.
 */
    if(fprintf(fp, "%s ", comment) < 0 ||
       _glh_write_timestamp(fp, node->timestamp) ||
       fprintf(fp, " %u\n", node->group) < 0) {
      return _glh_cant_save_history(glh, "Error writing", filename, fp);
    };
/*
 * Write the history line.
 */
    for(seg=node->line->head; seg; seg=seg->next) {
      size_t slen = seg->next ? GLH_SEG_SIZE : strlen(seg->s);
      if(fwrite(seg->s, sizeof(char), slen, fp) != slen)
	return _glh_cant_save_history(glh, "Error writing", filename, fp);
    };
    fputc('\n', fp);
  };
/*
 * Close the history file.
 */
  if(fclose(fp) == EOF)
    return _glh_cant_save_history(glh, "Error writing", filename, NULL);
  return 0;
#endif
}

#ifndef WITHOUT_FILE_SYSTEM
/*.......................................................................
 * This is a private error return function of _glh_save_history(). It
 * composes an error report in the error buffer, composed using
 * sprintf("%s %s (%s)", message, filename, strerror(errno)). It then
 * closes fp and returns the error return code of _glh_save_history().
 *
 * Input:
 *  glh        GlHistory *  The input-line history maintenance object.
 *  message   const char *  A message to be followed by the filename.
 *  filename  const char *  The name of the offending output file.
 *  fp              FILE *  The stream to be closed (send NULL if not
 *                          open).
 * Output:
 *  return           int    Always 1.
 */
static int _glh_cant_save_history(GlHistory *glh, const char *message,
				  const char *filename, FILE *fp)
{
  _err_record_msg(glh->err, message, filename, " (",
		     strerror(errno), ")", END_ERR_MSG);
  if(fp)
    (void) fclose(fp);
  return 1;
}

/*.......................................................................
 * Write a timestamp to a given stdio stream, in the format
 * yyyymmddhhmmss
 *
 * Input:
 *  fp             FILE *  The stream to write to.
 *  timestamp    time_t    The timestamp to be written.
 * Output:
 *  return          int    0 - OK.
 *                         1 - Error.
 */
static int _glh_write_timestamp(FILE *fp, time_t timestamp)
{
  struct tm *t;  /* THe broken-down calendar time */
/*
 * Get the calendar components corresponding to the given timestamp.
 */
  if(timestamp < 0 || (t = localtime(&timestamp)) == NULL) {
    if(fprintf(fp, "?") < 0)
      return 1;
    return 0;
  };
/*
 * Write the calendar time as yyyymmddhhmmss.
 */
  if(fprintf(fp, "%04d%02d%02d%02d%02d%02d", t->tm_year + 1900, t->tm_mon + 1,
	     t->tm_mday, t->tm_hour, t->tm_min, t->tm_sec) < 0)
    return 1;
  return 0;
}

#endif

/*.......................................................................
 * Restore previous history lines from a given file.
 *
 * Input:
 *  glh        GlHistory *  The input-line history maintenance object.
 *  filename  const char *  The name of the file to read from.
 *  comment   const char *  The same comment string that was passed to
 *                          _glh_save_history() when this file was
 *                          written.
 *  line            char *  A buffer into which lines can be read.
 *  dim            size_t   The allocated dimension of line[].
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
int _glh_load_history(GlHistory *glh, const char *filename, const char *comment,
		      char *line, size_t dim)
{
#ifdef WITHOUT_FILE_SYSTEM
  _err_record_msg(glh->err, "Can't load history without filesystem access",
		  END_ERR_MSG);
  errno = EINVAL;
  return 1;
#else
  FILE *fp;            /* The output file */
  size_t comment_len;  /* The length of the comment string */
  time_t timestamp;    /* The timestamp of the history line */
  unsigned group;      /* The identifier of the history group to which */
                       /*  the line belongs. */
  int lineno;          /* The line number being read */
/*
 * Check the arguments.
 */
  if(!glh || !filename || !comment || !line) {
    if(glh)
      _err_record_msg(glh->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Measure the length of the comment string.
 */
  comment_len = strlen(comment);
/*
 * Clear the history list.
 */
  _glh_clear_history(glh, 1);
/*
 * Attempt to open the specified file. Don't treat it as an error
 * if the file doesn't exist.
 */
  fp = fopen(filename, "r");
  if(!fp)
    return 0;
/*
 * Attempt to read each line and preceding peripheral info, and add these
 * to the history list.
 */
  for(lineno=1; fgets(line, dim, fp) != NULL; lineno++) {
    char *lptr;          /* A pointer into the input line */
/*
 * Check that the line starts with the comment string.
 */
    if(strncmp(line, comment, comment_len) != 0) {
      return _glh_cant_load_history(glh, filename, lineno,
				    "Corrupt history parameter line", fp);
    };
/*
 * Skip spaces and tabs after the comment.
 */
    for(lptr=line+comment_len; *lptr && (*lptr==' ' || *lptr=='\t'); lptr++)
      ;
/*
 * The next word must be a timestamp.
 */
    if(_glh_decode_timestamp(lptr, &lptr, &timestamp)) {
      return _glh_cant_load_history(glh, filename, lineno,
				    "Corrupt timestamp", fp);
    };
/*
 * Skip spaces and tabs.
 */
    while(*lptr==' ' || *lptr=='\t')
      lptr++;
/*
 * The next word must be an unsigned integer group number.
 */
    group = (int) strtoul(lptr, &lptr, 10);
    if(*lptr != ' ' && *lptr != '\n') {
      return _glh_cant_load_history(glh, filename, lineno,
				    "Corrupt group id", fp);
    };
/*
 * Skip spaces and tabs.
 */
    while(*lptr==' ' || *lptr=='\t')
      lptr++;
/*
 * There shouldn't be anything left on the line.
 */
    if(*lptr != '\n') {
      return _glh_cant_load_history(glh, filename, lineno,
				    "Corrupt parameter line", fp);
    };
/*
 * Now read the history line itself.
 */
    lineno++;
    if(fgets(line, dim, fp) == NULL)
      return _glh_cant_load_history(glh, filename, lineno, "Read error", fp);
/*
 * Append the line to the history buffer.
 */
    if(_glh_add_history(glh, line, 1)) {
      return _glh_cant_load_history(glh, filename, lineno,
				    "Insufficient memory to record line", fp);
    };
/*
 * Record the group and timestamp information along with the line.
 */
    if(glh->list.tail) {
      glh->list.tail->timestamp = timestamp;
      glh->list.tail->group = group;
    };
  };
/*
 * Close the file.
 */
  (void) fclose(fp);
  return 0;
#endif
}

#ifndef WITHOUT_FILE_SYSTEM
/*.......................................................................
 * This is a private error return function of _glh_load_history().
 */
static int _glh_cant_load_history(GlHistory *glh, const char *filename,
				  int lineno, const char *message, FILE *fp)
{
  char lnum[20];
/*
 * Convert the line number to a string.
 */
  snprintf(lnum, sizeof(lnum), "%d", lineno);
/*
 * Render an error message.
 */
  _err_record_msg(glh->err, filename, ":", lnum, ":", message, END_ERR_MSG);
/*
 * Close the file.
 */
  if(fp)
    (void) fclose(fp);
  return 1;
}

/*.......................................................................
 * Read a timestamp from a string.
 *
 * Input:
 *  string    char *  The string to read from.
 * Input/Output:
 *  endp        char ** On output *endp will point to the next unprocessed
 *                      character in string[].
 *  timestamp time_t *  The timestamp will be assigned to *t.
 * Output:
 *  return       int    0 - OK.
 *                      1 - Error.
 */
static int _glh_decode_timestamp(char *string, char **endp, time_t *timestamp)
{
  unsigned year,month,day,hour,min,sec;  /* Calendar time components */
  struct tm t;
/*
 * There are 14 characters in the date format yyyymmddhhmmss.
 */
  enum {TSLEN=14};
  char timestr[TSLEN+1];   /* The timestamp part of the string */
/*
 * If the time wasn't available at the time that the line was recorded
 * it will have been written as "?". Check for this before trying
 * to read the timestamp.
 */
  if(string[0] == '\?') {
    *endp = string+1;
    *timestamp = -1;
    return 0;
  };
/*
 * The timestamp is expected to be written in the form yyyymmddhhmmss.
 */
  if(strlen(string) < TSLEN) {
    *endp = string;
    return 1;
  };
/*
 * Copy the timestamp out of the string.
 */
  strncpy(timestr, string, TSLEN);
  timestr[TSLEN] = '\0';
/*
 * Decode the timestamp.
 */
  if(sscanf(timestr, "%4u%2u%2u%2u%2u%2u", &year, &month, &day, &hour, &min,
	    &sec) != 6) {
    *endp = string;
    return 1;
  };
/*
 * Advance the string pointer over the successfully read timestamp.
 */
  *endp = string + TSLEN;
/*
 * Copy the read values into a struct tm.
 */
  t.tm_sec = sec;
  t.tm_min = min;
  t.tm_hour = hour;
  t.tm_mday = day;
  t.tm_wday = 0;
  t.tm_yday = 0;
  t.tm_mon = month - 1;
  t.tm_year = year - 1900;
  t.tm_isdst = -1;
/*
 * Convert the contents of the struct tm to a time_t.
 */
  *timestamp = mktime(&t);
  return 0;
}
#endif

/*.......................................................................
 * Switch history groups.
 *
 * Input:
 *  glh        GlHistory *  The input-line history maintenance object.
 *  group       unsigned    The new group identifier. This will be recorded
 *                          with subsequent history lines, and subsequent
 *                          history searches will only return lines with
 *                          this group identifier. This allows multiple
 *                          separate history lists to exist within
 *                          a single GlHistory object. Note that the
 *                          default group identifier is 0.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
int _glh_set_group(GlHistory *glh, unsigned group)
{
/*
 * Check the arguments.
 */
  if(!glh) {
    if(glh)
      _err_record_msg(glh->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Is the group being changed?
 */
  if(group != glh->group) {
/*
 * Cancel any ongoing search.
 */
    if(_glh_cancel_search(glh))
      return 1;
/*
 * Record the new group.
 */
    glh->group = group;
  };
  return 0;
}

/*.......................................................................
 * Query the current history group.
 *
 * Input:
 *  glh        GlHistory *  The input-line history maintenance object.
 * Output:
 *  return      unsigned    The group identifier.
 */
int _glh_get_group(GlHistory *glh)
{
  return glh ? glh->group : 0;
}

/*.......................................................................
 * Display the contents of the history list.
 *
 * Input:
 *  glh       GlHistory *  The input-line history maintenance object.
 *  write_fn  GlWriteFn *  The function to call to write the line, or
 *                         0 to discard the output.
 *  data           void *  Anonymous data to pass to write_fn().
 *  fmt      const char *  A format string. This can contain arbitrary
 *                         characters, which are written verbatim, plus
 *                         any of the following format directives:
 *                          %D  -  The date, like 2001-11-20
 *                          %T  -  The time of day, like 23:59:59
 *                          %N  -  The sequential entry number of the
 *                                 line in the history buffer.
 *                          %G  -  The history group number of the line.
 *                          %%  -  A literal % character.
 *                          %H  -  The history line.
 *  all_groups      int    If true, display history lines from all
 *                         history groups. Otherwise only display
 *                         those of the current history group.
 *  max_lines       int    If max_lines is < 0, all available lines
 *                         are displayed. Otherwise only the most
 *                         recent max_lines lines will be displayed.
 * Output:
 *  return          int    0 - OK.
 *                         1 - Error.
 */
int _glh_show_history(GlHistory *glh, GlWriteFn *write_fn, void *data,
		      const char *fmt, int all_groups, int max_lines)
{
  GlhLineNode *node;     /* The line being displayed */
  GlhLineNode *oldest;   /* The oldest line to display */
  GlhLineSeg *seg;       /* One segment of a line being displayed */
  enum {TSMAX=32};       /* The maximum length of the date and time string */
  char buffer[TSMAX+1];  /* The buffer in which to write the date and time */
  int idlen;             /* The length of displayed ID strings */
  unsigned grpmax;       /* The maximum group number in the buffer */
  int grplen;            /* The number of characters needed to print grpmax */
  int len;               /* The length of a string to be written */
/*
 * Check the arguments.
 */
  if(!glh || !write_fn || !fmt) {
    if(glh)
      _err_record_msg(glh->err, "NULL argument(s)", END_ERR_MSG);
    errno = EINVAL;
    return 1;
  };
/*
 * Is history enabled?
 */
  if(!glh->enable || !glh->list.head)
    return 0;
/*
 * Work out the length to display ID numbers, choosing the length of
 * the biggest number in the buffer. Smaller numbers will be padded
 * with leading zeroes if needed.
 */
  snprintf(buffer, sizeof(buffer), "%lu", (unsigned long) glh->list.tail->id);
  idlen = strlen(buffer);
/*
 * Find the largest group number.
 */
  grpmax = 0;
  for(node=glh->list.head; node; node=node->next) {
    if(node->group > grpmax)
      grpmax = node->group;
  };
/*
 * Find out how many characters are needed to display the group number.
 */
  snprintf(buffer, sizeof(buffer), "%u", (unsigned) grpmax);
  grplen = strlen(buffer);
/*
 * Find the node that follows the oldest line to be displayed.
 */
  if(max_lines < 0) {
    oldest = glh->list.head;
  } else if(max_lines==0) {
    return 0;
  } else {
    for(oldest=glh->list.tail; oldest; oldest=oldest->prev) {
      if((all_groups || oldest->group == glh->group) && --max_lines <= 0)
	break;
    };
/*
 * If the number of lines in the buffer doesn't exceed the specified
 * maximum, start from the oldest line in the buffer.
 */
    if(!oldest)
      oldest = glh->list.head;
  };
/*
 * List the history lines in increasing time order.
 */
  for(node=oldest; node; node=node->next) {
/*
 * Only display lines from the current history group, unless
 * told otherwise.
 */
    if(all_groups || node->group == glh->group) {
      const char *fptr;      /* A pointer into the format string */
      struct tm *t = NULL;   /* The broken time version of the timestamp */
/*
 * Work out the calendar representation of the node timestamp.
 */
      if(node->timestamp != (time_t) -1)
	t = localtime(&node->timestamp);
/*
 * Parse the format string.
 */
      fptr = fmt;
      while(*fptr) {
/*
 * Search for the start of the next format directive or the end of the string.
 */
	const char *start = fptr;
	while(*fptr && *fptr != '%')
	  fptr++;
/*
 * Display any literal characters that precede the located directive.
 */
	if(fptr > start) {
	  len = (int) (fptr - start);
	  if(write_fn(data, start, len) != len)
	    return 1;
	};
/*
 * Did we hit a new directive before the end of the line?
 */
	if(*fptr) {
/*
 * Obey the directive. Ignore unknown directives.
 */
	  switch(*++fptr) {
	  case 'D':          /* Display the date */
	    if(t && strftime(buffer, TSMAX, "%Y-%m-%d", t) != 0) {
	      len = strlen(buffer);
	      if(write_fn(data, buffer, len) != len)
		return 1;
	    };
	    break;
	  case 'T':          /* Display the time of day */
	    if(t && strftime(buffer, TSMAX, "%H:%M:%S", t) != 0) {
	      len = strlen(buffer);
	      if(write_fn(data, buffer, len) != len)
		return 1;
	    };
	    break;
	  case 'N':          /* Display the sequential entry number */
	    snprintf(buffer, sizeof(buffer), "%*lu", idlen, (unsigned long) node->id);
	    len = strlen(buffer);
	    if(write_fn(data, buffer, len) != len)
	      return 1;
	    break;
	  case 'G':
	    snprintf(buffer, sizeof(buffer), "%*u", grplen, (unsigned) node->group);
	    len = strlen(buffer);
	    if(write_fn(data, buffer, len) != len)
	      return 1;
	    break;
	  case 'H':          /* Display the history line */
	    for(seg=node->line->head; seg; seg=seg->next) {
	      len = seg->next ? GLH_SEG_SIZE : strlen(seg->s);
	      if(write_fn(data, seg->s, len) != len)
		return 1;
	    };
	    break;
	  case '%':          /* A literal % symbol */
	    if(write_fn(data, "%", 1) != 1)
	      return 1;
	    break;
	  };
/*
 * Skip the directive.
 */
	  if(*fptr)
	    fptr++;
	};
      };
    };
  };
  return 0;
}

/*.......................................................................
 * Change the size of the history buffer.
 *
 * Input:
 *  glh    GlHistory *  The input-line history maintenance object.
 *  bufsize   size_t    The number of bytes in the history buffer, or 0
 *                      to delete the buffer completely.
 * Output:
 *  return       int    0 - OK.
 *                      1 - Insufficient memory (the previous buffer
 *                          will have been retained). No error message
 *                          will be displayed.
 */
int _glh_resize_history(GlHistory *glh, size_t bufsize)
{
  int nbuff;     /* The number of segments in the new buffer */
  int i;
/*
 * Check the arguments.
 */
  if(!glh) {
    errno = EINVAL;
    return 1;
  };
/*
 * How many buffer segments does the requested buffer size correspond
 * to?
 */
  nbuff = (bufsize+GLH_SEG_SIZE-1) / GLH_SEG_SIZE;
/*
 * Has a different size than the current size been requested?
 */
  if(glh->nbuff != nbuff) {
/*
 * Cancel any ongoing search.
 */
    (void) _glh_cancel_search(glh);
/*
 * Create a wholly new buffer?
 */
    if(glh->nbuff == 0 && nbuff>0) {
      glh->buffer = (GlhLineSeg *) malloc(sizeof(GlhLineSeg) * nbuff);
      if(!glh->buffer)
	return 1;
      glh->nbuff = nbuff;
      glh->nfree = glh->nbuff;
      glh->nbusy = 0;
      glh->nline = 0;
/*
 * Link the currently unused nodes of the buffer into a list.
 */
      glh->unused = glh->buffer;
      for(i=0; i<glh->nbuff-1; i++) {
	GlhLineSeg *seg = glh->unused + i;
	seg->next = seg + 1;
      };
      glh->unused[i].next = NULL;
/*
 * Delete an existing buffer?
 */
    } else if(nbuff == 0) {
      _glh_clear_history(glh, 1);
      free(glh->buffer);
      glh->buffer = NULL;
      glh->unused = NULL;
      glh->nbuff = 0;
      glh->nfree = 0;
      glh->nbusy = 0;
      glh->nline = 0;
/*
 * Change from one finite buffer size to another?
 */
    } else {
      GlhLineSeg *buffer; /* The resized buffer */
      int nbusy;      /* The number of used line segments in the new buffer */
/*
 * Starting from the oldest line in the buffer, discard lines until
 * the buffer contains at most 'nbuff' used line segments.
 */
      while(glh->list.head && glh->nbusy > nbuff)
	_glh_discard_line(glh, glh->list.head);
/*
 * Attempt to allocate a new buffer.
 */
      buffer = (GlhLineSeg *) malloc(nbuff * sizeof(GlhLineSeg));
      if(!buffer) {
	errno = ENOMEM;
	return 1;
      };
/*
 * Copy the used segments of the old buffer to the start of the new buffer.
 */
      nbusy = 0;
      for(i=0; i<GLH_HASH_SIZE; i++) {
	GlhHashBucket *b = glh->hash.bucket + i;
	GlhHashNode *hnode;
	for(hnode=b->lines; hnode; hnode=hnode->next) {
	  GlhLineSeg *seg = hnode->head;
	  hnode->head = buffer + nbusy;
	  for( ; seg; seg=seg->next) {
	    buffer[nbusy] = *seg;
	    buffer[nbusy].next = seg->next ? &buffer[nbusy+1] : NULL;
	    nbusy++;
	  };
	};
      };
/*
 * Make a list of the new buffer's unused segments.
 */
      for(i=nbusy; i<nbuff-1; i++)
	buffer[i].next = &buffer[i+1];
      if(i < nbuff)
	buffer[i].next = NULL;
/*
 * Discard the old buffer.
 */
      free(glh->buffer);
/*
 * Install the new buffer.
 */
      glh->buffer = buffer;
      glh->nbuff = nbuff;
      glh->nbusy = nbusy;
      glh->nfree = nbuff - nbusy;
      glh->unused = glh->nfree > 0 ? (buffer + nbusy) : NULL;
    };
  };
  return 0;
}

/*.......................................................................
 * Set an upper limit to the number of lines that can be recorded in the
 * history list, or remove a previously specified limit.
 *
 * Input:
 *  glh    GlHistory *  The input-line history maintenance object.
 *  max_lines    int    The maximum number of lines to allow, or -1 to
 *                      cancel a previous limit and allow as many lines
 *                      as will fit in the current history buffer size.
 */
void _glh_limit_history(GlHistory *glh, int max_lines)
{
  if(!glh)
    return;
/*
 * Apply a new limit?
 */
  if(max_lines >= 0 && max_lines != glh->max_lines) {
/*
 * Count successively older lines until we reach the start of the
 * list, or until we have seen max_lines lines (at which point 'node'
 * will be line number max_lines+1).
 */
    int nline = 0;
    GlhLineNode *node;
    for(node=glh->list.tail; node && ++nline <= max_lines; node=node->prev)
      ;
/*
 * Discard any lines that exceed the limit.
 */
    if(node) {
      GlhLineNode *oldest = node->next;  /* The oldest line to be kept */
/*
 * Delete nodes from the head of the list until we reach the node that
 * is to be kept.
 */
      while(glh->list.head && glh->list.head != oldest)
	_glh_discard_line(glh, glh->list.head);
    };
  };
/*
 * Record the new limit.
 */
  glh->max_lines = max_lines;
  return;
}

/*.......................................................................
 * Discard either all history, or the history associated with the current
 * history group.
 *
 * Input:
 *  glh    GlHistory *  The input-line history maintenance object.
 *  all_groups   int    If true, clear all of the history. If false,
 *                      clear only the stored lines associated with the
 *                      currently selected history group.
 */
void _glh_clear_history(GlHistory *glh, int all_groups)
{
  int i;
/*
 * Check the arguments.
 */
  if(!glh)
    return;
/*
 * Cancel any ongoing search.
 */
  (void) _glh_cancel_search(glh);
/*
 * Delete all history lines regardless of group?
 */
  if(all_groups) {
/*
 * Claer the time-ordered list of lines.
 */
    _rst_FreeList(glh->list.node_mem);
    glh->list.head = glh->list.tail = NULL;
    glh->nline = 0;
    glh->id_node = NULL;
/*
 * Clear the hash table.
 */
    for(i=0; i<GLH_HASH_SIZE; i++)
      glh->hash.bucket[i].lines = NULL;
    _rst_FreeList(glh->hash.node_mem);
/*
 * Move all line segment nodes back onto the list of unused segments.
 */
    if(glh->buffer) {
      glh->unused = glh->buffer;
      for(i=0; i<glh->nbuff-1; i++) {
	GlhLineSeg *seg = glh->unused + i;
	seg->next = seg + 1;
      };
      glh->unused[i].next = NULL;
      glh->nfree = glh->nbuff;
      glh->nbusy = 0;
    } else {
      glh->unused = NULL;
      glh->nbusy = glh->nfree = 0;
    };
/*
 * Just delete lines of the current group?
 */
  } else {
    GlhLineNode *node;  /* The line node being checked */
    GlhLineNode *next;  /* The line node that follows 'node' */
/*
 * Search out and delete the line nodes of the current group.
 */
    for(node=glh->list.head; node; node=next) {
/*
 * Keep a record of the following node before we delete the current
 * node.
 */
      next = node->next;
/*
 * Discard this node?
 */
      if(node->group == glh->group)
	_glh_discard_line(glh, node);
    };
  };
  return;
}

/*.......................................................................
 * Temporarily enable or disable the history list.
 *
 * Input:
 *  glh    GlHistory *  The input-line history maintenance object.
 *  enable       int    If true, turn on the history mechanism. If
 *                      false, disable it.
 */
void _glh_toggle_history(GlHistory *glh, int enable)
{
  if(glh)
    glh->enable = enable;
}

/*.......................................................................
 * Discard a given archived input line.
 *
 * Input:
 *  glh      GlHistory *  The history container object.
 *  node   GlhLineNode *  The line to be discarded, specified via its
 *                        entry in the time-ordered list of historical
 *                        input lines.
 */
static void _glh_discard_line(GlHistory *glh, GlhLineNode *node)
{
/*
 * Remove the node from the linked list.
 */
  if(node->prev)
    node->prev->next = node->next;
  else
    glh->list.head = node->next;
  if(node->next)
    node->next->prev = node->prev;
  else
    glh->list.tail = node->prev;
/*
 * If we are deleting the node that is marked as the start point of the
 * last ID search, remove the cached starting point.
 */
  if(node == glh->id_node)
    glh->id_node = NULL;
/*
 * If we are deleting the node that is marked as the start point of the
 * next prefix search, cancel the search.
 */
  if(node == glh->recall)
    _glh_cancel_search(glh);
/*
 * Delete our copy of the line.
 */
  node->line = _glh_discard_copy(glh, node->line);
/*
 * Return the node to the freelist.
 */
  (void) _del_FreeListNode(glh->list.node_mem, node);
/*
 * Record the removal of a line from the list.
 */
  glh->nline--;
  return;
}

/*.......................................................................
 * Lookup the details of a given history line, given its id.
 *
 * Input:
 *  glh      GlHistory *  The input-line history maintenance object.
 *  id        GlLineID    The sequential number of the line.
 * Input/Output:
 *  line    const char ** A pointer to a copy of the history line will be
 *                        assigned to *line. Beware that this pointer may
 *                        be invalidated by the next call to any public
 *                        history function.
 *  group     unsigned *  The group membership of the line will be assigned
 *                        to *group.
 *  timestamp   time_t *  The timestamp of the line will be assigned to
 *                        *timestamp.
 * Output:
 *  return         int    0 - The requested line wasn't found.
 *                        1 - The line was found.
 */
int _glh_lookup_history(GlHistory *glh, GlhLineID id, const char **line,
			unsigned *group, time_t *timestamp)
{
  GlhLineNode *node; /* The located line location node */
/*
 * Check the arguments.
 */
  if(!glh)
    return 0;
/*
 * Search for the line that has the specified ID.
 */
  node = _glh_find_id(glh, id);
/*
 * Not found?
 */
  if(!node)
    return 0;
/*
 * Has the history line been requested?
 */
  if(line) {
/*
 * If necessary, reallocate the lookup buffer to accomodate the size of
 * a copy of the located line.
 */
    if(node->line->len + 1 > glh->lbuf_dim) {
      int lbuf_dim = node->line->len + 1;
      char *lbuf = realloc(glh->lbuf, lbuf_dim);
      if(!lbuf) {
	errno = ENOMEM;
	return 0;
      };
      glh->lbuf_dim = lbuf_dim;
      glh->lbuf = lbuf;
    };
/*
 * Copy the history line into the lookup buffer.
 */
    _glh_return_line(node->line, glh->lbuf, glh->lbuf_dim);
/*
 * Assign the lookup buffer as the returned line pointer.
 */
    *line = glh->lbuf;
  };
/*
 * Does the caller want to know the group of the line?
 */
  if(group)
    *group = node->group;
/*
 * Does the caller want to know the timestamp of the line?
 */
  if(timestamp)
    *timestamp = node->timestamp;
  return 1;
}

/*.......................................................................
 * Lookup a node in the history list by its ID.
 *
 * Input:
 *  glh       GlHistory *  The input-line history maintenance object.
 *  id        GlhLineID    The ID of the line to be returned.
 * Output:
 *  return  GlhLIneNode *  The located node, or NULL if not found.
 */
static GlhLineNode *_glh_find_id(GlHistory *glh, GlhLineID id)
{
  GlhLineNode *node;  /* The node being checked */
/*
 * Is history enabled?
 */
  if(!glh->enable || !glh->list.head)
    return NULL;
/*
 * If possible, start at the end point of the last ID search.
 * Otherwise start from the head of the list.
 */
  node = glh->id_node;
  if(!node)
    node = glh->list.head;
/*
 * Search forwards from 'node'?
 */
  if(node->id < id) {
    while(node && node->id != id)
      node = node->next;
    glh->id_node = node ? node : glh->list.tail;
/*
 * Search backwards from 'node'?
 */
  } else {
    while(node && node->id != id)
      node = node->prev;
    glh->id_node = node ? node : glh->list.head;
  };
/*
 * Return the located node (this will be NULL if the ID wasn't found).
 */
  return node;
}

/*.......................................................................
 * Query the state of the history list. Note that any of the input/output
 * pointers can be specified as NULL.
 *
 * Input:
 *  glh         GlHistory *  The input-line history maintenance object.
 * Input/Output:
 *  enabled           int *  If history is enabled, *enabled will be
 *                           set to 1. Otherwise it will be assigned 0.
 *  group        unsigned *  The current history group ID will be assigned
 *                           to *group.
 *  max_lines         int *  The currently requested limit on the number
 *                           of history lines in the list, or -1 if
 *                           unlimited.
 */
void _glh_state_of_history(GlHistory *glh, int *enabled, unsigned *group,
			   int *max_lines)
{
  if(glh) {
    if(enabled)
     *enabled = glh->enable;
    if(group)
     *group = glh->group;
    if(max_lines)
     *max_lines = glh->max_lines;
  };
}

/*.......................................................................
 * Get the range of lines in the history buffer.
 *
 * Input:
 *  glh         GlHistory *  The input-line history maintenance object.
 * Input/Output:
 *  oldest  unsigned long *  The sequential entry number of the oldest
 *                           line in the history list will be assigned
 *                           to *oldest, unless there are no lines, in
 *                           which case 0 will be assigned.
 *  newest  unsigned long *  The sequential entry number of the newest
 *                           line in the history list will be assigned
 *                           to *newest, unless there are no lines, in
 *                           which case 0 will be assigned.
 *  nlines            int *  The number of lines currently in the history
 *                           list.
 */
void _glh_range_of_history(GlHistory *glh, unsigned long *oldest,
			   unsigned long *newest, int *nlines)
{
  if(glh) {
    if(oldest)
      *oldest = glh->list.head ? glh->list.head->id : 0;
    if(newest)
      *newest = glh->list.tail ? glh->list.tail->id : 0;
    if(nlines)
      *nlines = glh->nline;
  };
}

/*.......................................................................
 * Return the size of the history buffer and the amount of the
 * buffer that is currently in use.
 *
 * Input:
 *  glh      GlHistory *  The input-line history maintenance object.
 * Input/Output:
 *  buff_size   size_t *  The size of the history buffer (bytes).
 *  buff_used   size_t *  The amount of the history buffer that
 *                        is currently occupied (bytes).
 */
void _glh_size_of_history(GlHistory *glh, size_t *buff_size, size_t *buff_used)
{
  if(glh) {
    if(buff_size)
      *buff_size = (glh->nbusy + glh->nfree) * GLH_SEG_SIZE;
/*
 * Determine the amount of buffer space that is currently occupied.
 */
    if(buff_used)
      *buff_used = glh->nbusy * GLH_SEG_SIZE;
  };
}

/*.......................................................................
 * Return extra information (ie. in addition to that provided by errno)
 * about the last error to occur in any of the public functions of this
 * module.
 *
 * Input:
 *  glh      GlHistory *  The container of the history list.
 * Output:
 *  return  const char *  A pointer to the internal buffer in which
 *                        the error message is temporarily stored.
 */
const char *_glh_last_error(GlHistory *glh)
{
  return glh ? _err_get_msg(glh->err) : "NULL GlHistory argument";
}

/*.......................................................................
 * Unless already stored, store a copy of the line in the history buffer,
 * then return a reference-counted hash-node pointer to this copy.
 *
 * Input:
 *  glh       GlHistory *   The history maintenance buffer.
 *  line     const char *   The history line to be recorded.
 *  n            size_t     The length of the string, excluding any '\0'
 *                          terminator.
 * Output:
 *  return  GlhHashNode *   The hash-node containing the stored line, or
 *                          NULL on error.
 */
static GlhHashNode *_glh_acquire_copy(GlHistory *glh, const char *line,
				      size_t n)
{
  GlhHashBucket *bucket;   /* The hash-table bucket of the line */
  GlhHashNode *hnode;      /* The hash-table node of the line */
  int i;
/*
 * In which bucket should the line be recorded?
 */
  bucket = glh_find_bucket(glh, line, n);
/*
 * Is the line already recorded there?
 */
  hnode = glh_find_hash_node(bucket, line, n);
/*
 * If the line isn't recorded in the buffer yet, make room for it.
 */
  if(!hnode) {
    GlhLineSeg *seg;   /* A line segment */
    int offset;        /* An offset into line[] */
/*
 * How many string segments will be needed to record the new line,
 * including space for a '\0' terminator?
 */
    int nseg = ((n+1) + GLH_SEG_SIZE-1) /  GLH_SEG_SIZE;
/*
 * Discard the oldest history lines in the buffer until at least
 * 'nseg' segments have been freed up, or until we run out of buffer
 * space.
 */
    while(glh->nfree < nseg && glh->nbusy > 0)
      _glh_discard_line(glh, glh->list.head);
/*
 * If the buffer is smaller than the new line, don't attempt to truncate
 * it to fit. Simply don't archive it.
 */
    if(glh->nfree < nseg)
      return NULL;
/*
 * Record the line in the first 'nseg' segments of the list of unused segments.
 */
    offset = 0;
    for(i=0,seg=glh->unused; i<nseg-1; i++,seg=seg->next, offset+=GLH_SEG_SIZE)
      memcpy(seg->s, line + offset, GLH_SEG_SIZE);
    memcpy(seg->s, line + offset, n-offset);
    seg->s[n-offset] = '\0';
/*
 * Create a new hash-node for the line.
 */
    hnode = (GlhHashNode *) _new_FreeListNode(glh->hash.node_mem);
    if(!hnode)
      return NULL;
/*
 * Move the copy of the line from the list of unused segments to
 * the hash node.
 */
    hnode->head = glh->unused;
    glh->unused = seg->next;
    seg->next = NULL;
    glh->nbusy += nseg;
    glh->nfree -= nseg;
/*
 * Prepend the new hash node to the list within the associated bucket.
 */
    hnode->next = bucket->lines;
    bucket->lines = hnode;
/*
 * Initialize the rest of the members of the hash node.
 */
    hnode->len = n;
    hnode->reported = 0;
    hnode->used = 0;
    hnode->bucket = bucket;
  };
/*
 * Increment the reference count of the line.
 */
  hnode->used++;
  return hnode;
}

/*.......................................................................
 * Decrement the reference count of the history line of a given hash-node,
 * and if the count reaches zero, delete both the hash-node and the
 * buffered copy of the line.
 *
 * Input:
 *  glh      GlHistory *  The history container object.
 *  hnode  GlhHashNode *  The node to be removed.
 * Output:
 *  return GlhHashNode *  The deleted hash-node (ie. NULL).
 */
static GlhHashNode *_glh_discard_copy(GlHistory *glh, GlhHashNode *hnode)
{
  if(hnode) {
    GlhHashBucket *bucket = hnode->bucket;
/*
 * If decrementing the reference count of the hash-node doesn't reduce
 * the reference count to zero, then the line is still in use in another
 * object, so don't delete it yet. Return NULL to indicate that the caller's
 * access to the hash-node copy has been deleted.
 */
    if(--hnode->used >= 1)
      return NULL;
/*
 * Remove the hash-node from the list in its parent bucket.
 */
    if(bucket->lines == hnode) {
      bucket->lines = hnode->next;
    } else {
      GlhHashNode *prev;    /* The node which precedes hnode in the bucket */
      for(prev=bucket->lines; prev && prev->next != hnode; prev=prev->next)
	;
      if(prev)
	prev->next = hnode->next;
    };
    hnode->next = NULL;
/*
 * Return the line segments of the hash-node to the list of unused segments.
 */
    if(hnode->head) {
      GlhLineSeg *tail; /* The last node in the list of line segments */
      int nseg;         /* The number of segments being discarded */
/*
 * Get the last node of the list of line segments referenced in the hash-node,
 * while counting the number of line segments used.
 */
      for(nseg=1,tail=hnode->head; tail->next; nseg++,tail=tail->next)
	;
/*
 * Prepend the list of line segments used by the hash node to the
 * list of unused line segments.
 */
      tail->next = glh->unused;
      glh->unused = hnode->head;
      glh->nbusy -= nseg;
      glh->nfree += nseg;
    };
/*
 * Return the container of the hash-node to the freelist.
 */
    hnode = (GlhHashNode *) _del_FreeListNode(glh->hash.node_mem, hnode);
  };
  return NULL;
}

/*.......................................................................
 * Private function to locate the hash bucket associated with a given
 * history line.
 *
 * This uses a hash-function described in the dragon-book
 * ("Compilers - Principles, Techniques and Tools", by Aho, Sethi and
 *  Ullman; pub. Adison Wesley) page 435.
 *
 * Input:
 *  glh        GlHistory *   The history container object.
 *  line      const char *   The historical line to look up.
 *  n             size_t     The length of the line in line[], excluding
 *                           any '\0' terminator.
 * Output:
 *  return GlhHashBucket *   The located hash-bucket.
 */
static GlhHashBucket *glh_find_bucket(GlHistory *glh, const char *line,
				      size_t n)
{
  unsigned long h = 0L;
  int i;
  for(i=0; i<n; i++) {
    unsigned char c = line[i];
    h = 65599UL * h + c;  /* 65599 is a prime close to 2^16 */
  };
  return glh->hash.bucket + (h % GLH_HASH_SIZE);
}

/*.......................................................................
 * Find a given history line within a given hash-table bucket.
 *
 * Input:
 *  bucket  GlhHashBucket *  The hash-table bucket in which to search.
 *  line       const char *  The historical line to lookup.
 *  n             size_t     The length of the line in line[], excluding
 *                           any '\0' terminator.
 * Output:
 *  return    GlhHashNode *  The hash-table entry of the line, or NULL
 *                           if not found.
 */
static GlhHashNode *glh_find_hash_node(GlhHashBucket *bucket, const char *line,
				       size_t n)
{
  GlhHashNode *node;  /* A node in the list of lines in the bucket */
/*
 * Compare each of the lines in the list of lines, against 'line'.
 */
  for(node=bucket->lines; node; node=node->next) {
    if(_glh_is_line(node, line, n))
      return node;
  };
  return NULL;
}

/*.......................................................................
 * Return non-zero if a given string is equal to a given segmented line
 * node.
 *
 * Input:
 *  hash   GlhHashNode *   The hash-table entry of the line.
 *  line    const char *   The string to be compared to the segmented
 *                         line.
 *  n           size_t     The length of the line in line[], excluding
 *                         any '\0' terminator.
 * Output:
 *  return         int     0 - The lines differ.
 *                         1 - The lines are the same.
 */
static int _glh_is_line(GlhHashNode *hash, const char *line, size_t n)
{
  GlhLineSeg *seg;   /* A node in the list of line segments */
  int i;
/*
 * Do the two lines have the same length?
 */
  if(n != hash->len)
    return 0;
/*
 * Compare the characters of the segmented and unsegmented versions
 * of the line.
 */
  for(seg=hash->head; n>0 && seg; seg=seg->next) {
    const char *s = seg->s;
    for(i=0; n>0 && i<GLH_SEG_SIZE; i++,n--) {
      if(*line++ != *s++)
	return 0;
    };
  };
  return 1;
}

/*.......................................................................
 * Return non-zero if a given line has the specified segmented search
 * prefix.
 *
 * Input:
 *  line   GlhHashNode *   The line to be compared against the prefix.
 *  prefix GlhHashNode *   The search prefix, or NULL to match any string.
 * Output:
 *  return         int     0 - The line doesn't have the specified prefix.
 *                         1 - The line has the specified prefix.
 */
static int _glh_line_matches_prefix(GlhHashNode *line, GlhHashNode *prefix)
{
  GlhLineStream lstr; /* The stream that is used to traverse 'line' */
  GlhLineStream pstr; /* The stream that is used to traverse 'prefix' */
/*
 * When prefix==NULL, this means that the nul string
 * is to be matched, and this matches all lines.
 */
  if(!prefix)
    return 1;
/*
 * Wrap the two history lines that are to be compared in iterator
 * stream objects.
 */
  glh_init_stream(&lstr, line);
  glh_init_stream(&pstr, prefix);
/*
 * If the prefix contains a glob pattern, match the prefix as a glob
 * pattern.
 */
  if(glh_contains_glob(prefix))
    return glh_line_matches_glob(&lstr, &pstr);
/*
 * Is the prefix longer than the line being compared against it?
 */
  if(prefix->len > line->len)
    return 0;
/*
 * Compare the line to the prefix.
 */
  while(pstr.c != '\0' && pstr.c == lstr.c) {
    glh_step_stream(&lstr);
    glh_step_stream(&pstr);
  };
/*
 * Did we reach the end of the prefix string before finding
 * any differences?
 */
  return pstr.c == '\0';
}

/*.......................................................................
 * Copy a given history line into a specified output string.
 *
 * Input:
 *  hash  GlhHashNode    The hash-table entry of the history line to
 *                       be copied.
 *  line         char *  A copy of the history line.
 *  dim        size_t    The allocated dimension of the line buffer.
 */
static void _glh_return_line(GlhHashNode *hash, char *line, size_t dim)
{
  GlhLineSeg *seg;   /* A node in the list of line segments */
  int i;
  for(seg=hash->head; dim>0 && seg; seg=seg->next) {
    const char *s = seg->s;
    for(i=0; dim>0 && i<GLH_SEG_SIZE; i++,dim--)
      *line++ = *s++;
  };
/*
 * If the line wouldn't fit in the output buffer, replace the last character
 * with a '\0' terminator.
 */
  if(dim==0)
    line[-1] = '\0';
}

/*.......................................................................
 * This function should be called whenever a new line recall is
 * attempted.  It preserves a copy of the current input line in the
 * history list while other lines in the history list are being
 * returned.
 *
 * Input:
 *  glh  GlHistory *  The input-line history maintenance object.
 *  line      char *  The current contents of the input line buffer.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */
static int _glh_prepare_for_recall(GlHistory *glh, char *line)
{
/*
 * If a recall session has already been started, but we have returned
 * to the preserved copy of the input line, if the user has changed
 * this line, we should replace the preserved copy of the original
 * input line with the new one. To do this simply cancel the session,
 * so that a new session is started below.
 */
  if(glh->recall && glh->recall == glh->list.tail &&
     !_glh_is_line(glh->recall->line, line, strlen(line))) {
    _glh_cancel_search(glh);
  };
/*
 * If this is the first line recall of a new recall session, save the
 * current line for potential recall later, and mark it as the last
 * line recalled.
 */
  if(!glh->recall) {
    if(_glh_add_history(glh, line, 1))
      return 1;
    glh->recall = glh->list.tail;
/*
 * The above call to _glh_add_history() will have incremented the line
 * sequence number, after adding the line. Since we only want this to
 * to be incremented for permanently entered lines, decrement it again.
 */
    glh->seq--;
  };
  return 0;
}

/*.......................................................................
 * Return non-zero if a history search session is currently in progress.
 *
 * Input:
 *  glh  GlHistory *  The input-line history maintenance object.
 * Output:
 *  return     int    0 - No search is currently in progress.
 *                    1 - A search is in progress.
 */
int _glh_search_active(GlHistory *glh)
{
  return glh && glh->recall;
}

/*.......................................................................
 * Initialize a character iterator object to point to the start of a
 * given history line. The first character of the line will be placed
 * in str->c, and subsequent characters can be placed there by calling
 * glh_strep_stream().
 *
 * Input:
 *  str  GlhLineStream *  The iterator object to be initialized.
 *  line   GlhHashNode *  The history line to be iterated over (a
 *                        NULL value here, is interpretted as an
 *                        empty string by glh_step_stream()).
 */
static void glh_init_stream(GlhLineStream *str, GlhHashNode *line)
{
  str->seg = line ? line->head : NULL;
  str->posn = 0;
  str->c = str->seg ? str->seg->s[0] : '\0';
}

/*.......................................................................
 * Copy the next unread character in the line being iterated, in str->c.
 * Once the end of the history line has been reached, all futher calls
 * set str->c to '\0'.
 *
 * Input:
 *  str   GlhLineStream *  The history-line iterator to read from.
 */
static void glh_step_stream(GlhLineStream *str)
{
/*
 * Get the character from the current iterator position within the line.
 */
  str->c = str->seg ? str->seg->s[str->posn] : '\0';
/*
 * Unless we have reached the end of the string, move the iterator
 * to the position of the next character in the line.
 */
  if(str->c != '\0' && ++str->posn >= GLH_SEG_SIZE) {
    str->posn = 0;
    str->seg = str->seg->next;
  };
}

/*.......................................................................
 * Return non-zero if the specified search prefix contains any glob
 * wildcard characters.
 *
 * Input:
 *  prefix   GlhHashNode *  The search prefix.
 * Output:
 *  return           int    0 - The prefix doesn't contain any globbing
 *                              characters.
 *                          1 - The prefix contains at least one
 *                              globbing character.
 */
static int glh_contains_glob(GlhHashNode *prefix)
{
  GlhLineStream pstr; /* The stream that is used to traverse 'prefix' */
/*
 * Wrap a stream iterator around the prefix, so that we can traverse it
 * without worrying about line-segmentation.
 */
  glh_init_stream(&pstr, prefix);
/*
 * Search for unescaped wildcard characters.
 */
  while(pstr.c != '\0') {
    switch(pstr.c) {
    case '\\':                      /* Skip escaped characters */
      glh_step_stream(&pstr);
      break;
    case '*': case '?': case '[':   /* A wildcard character? */
      return 1;
      break;
    };
    glh_step_stream(&pstr);
  };
/*
 * No wildcard characters were found.
 */
  return 0;
}

/*.......................................................................
 * Return non-zero if the history line matches a search prefix containing
 * a glob pattern.
 *
 * Input:
 *  lstr  GlhLineStream *  The iterator stream being used to traverse
 *                         the history line that is being matched.
 *  pstr  GlhLineStream *  The iterator stream being used to traverse
 *                         the pattern.
 * Output:
 *  return    int          0 - Doesn't match.
 *                         1 - The line matches the pattern.
 */
static int glh_line_matches_glob(GlhLineStream *lstr, GlhLineStream *pstr)
{
/*
 * Match each character of the pattern until we reach the end of the
 * pattern.
 */
  while(pstr->c != '\0') {
/*
 * Handle the next character of the pattern.
 */
    switch(pstr->c) {
/*
 * A match zero-or-more characters wildcard operator.
 */
    case '*':
/*
 * Skip the '*' character in the pattern.
 */
      glh_step_stream(pstr);
/*
 * If the pattern ends with the '*' wildcard, then the
 * rest of the line matches this.
 */
      if(pstr->c == '\0')
	return 1;
/*
 * Using the wildcard to match successively longer sections of
 * the remaining characters of the line, attempt to match
 * the tail of the line against the tail of the pattern.
 */
      while(lstr->c) {
	GlhLineStream old_lstr = *lstr;
	GlhLineStream old_pstr = *pstr;
	if(glh_line_matches_glob(lstr, pstr))
	  return 1;
/*
 * Restore the line and pattern iterators for a new try.
 */
	*lstr = old_lstr;
	*pstr = old_pstr;
/*
 * Prepare to try again, one character further into the line.
 */
	glh_step_stream(lstr);
      };
      return 0; /* The pattern following the '*' didn't match */
      break;
/*
 * A match-one-character wildcard operator.
 */
    case '?':
/*
 * If there is a character to be matched, skip it and advance the
 * pattern pointer.
 */
      if(lstr->c) {
	glh_step_stream(lstr);
	glh_step_stream(pstr);
/*
 * If we hit the end of the line, there is no character
 * matching the operator, so the pattern doesn't match.
 */
      } else {
        return 0;
      };
      break;
/*
 * A character range operator, with the character ranges enclosed
 * in matching square brackets.
 */
    case '[':
      glh_step_stream(pstr);  /* Skip the '[' character */
      if(!lstr->c || !glh_matches_range(lstr->c, pstr))
        return 0;
      glh_step_stream(lstr);  /* Skip the character that matched */
      break;
/*
 * A backslash in the pattern prevents the following character as
 * being seen as a special character.
 */
    case '\\':
      glh_step_stream(pstr);  /* Skip the backslash */
      /* Note fallthrough to default */
/*
 * A normal character to be matched explicitly.
 */
      /* FALLTHROUGH */
    default:
      if(lstr->c == pstr->c) {
	glh_step_stream(lstr);
	glh_step_stream(pstr);
      } else {
        return 0;
      };
      break;
    };
  };
/*
 * To get here, pattern must have been exhausted. The line only
 * matches the pattern if the line as also been exhausted.
 */
  return pstr->c == '\0' && lstr->c == '\0';
}

/*.......................................................................
 * Match a character range expression terminated by an unescaped close
 * square bracket.
 *
 * Input:
 *  c              char    The character to be matched with the range
 *                         pattern.
 *  pstr  GlhLineStream *  The iterator stream being used to traverse
 *                         the pattern.
 * Output:
 *  return          int    0 - Doesn't match.
 *                         1 - The character matched.
 */
static int glh_matches_range(char c, GlhLineStream *pstr)
{
  int invert = 0;              /* True to invert the sense of the match */
  int matched = 0;             /* True if the character matched the pattern */
  char lastc = '\0';           /* The previous character in the pattern */
/*
 * If the first character is a caret, the sense of the match is
 * inverted and only if the character isn't one of those in the
 * range, do we say that it matches.
 */
  if(pstr->c == '^') {
    glh_step_stream(pstr);
    invert = 1;
  };
/*
 * The hyphen is only a special character when it follows the first
 * character of the range (not including the caret).
 */
  if(pstr->c == '-') {
    glh_step_stream(pstr);
    if(c == '-')
      matched = 1;
/*
 * Skip other leading '-' characters since they make no sense.
 */
    while(pstr->c == '-')
      glh_step_stream(pstr);
  };
/*
 * The hyphen is only a special character when it follows the first
 * character of the range (not including the caret or a hyphen).
 */
  if(pstr->c == ']') {
    glh_step_stream(pstr);
    if(c == ']')
      matched = 1;
  };
/*
 * Having dealt with the characters that have special meanings at
 * the beginning of a character range expression, see if the
 * character matches any of the remaining characters of the range,
 * up until a terminating ']' character is seen.
 */
  while(!matched && pstr->c && pstr->c != ']') {
/*
 * Is this a range of characters signaled by the two end characters
 * separated by a hyphen?
 */
    if(pstr->c == '-') {
      glh_step_stream(pstr);  /* Skip the hyphen */
      if(pstr->c != ']') {
        if(c >= lastc && c <= pstr->c)
	  matched = 1;
      };
/*
 * A normal character to be compared directly.
 */
    } else if(pstr->c == c) {
      matched = 1;
    };
/*
 * Record and skip the character that we just processed.
 */
    lastc = pstr->c;
    if(pstr->c != ']')
      glh_step_stream(pstr);
  };
/*
 * Find the terminating ']'.
 */
  while(pstr->c && pstr->c != ']')
    glh_step_stream(pstr);
/*
 * Did we find a terminating ']'?
 */
  if(pstr->c == ']') {
/*
 * Skip the terminating ']'.
 */
    glh_step_stream(pstr);
/*
 * If the pattern started with a caret, invert the sense of the match.
 */
    if(invert)
      matched = !matched;
/*
 * If the pattern didn't end with a ']', then it doesn't match,
 * regardless of the value of the required sense of the match.
 */
  } else {
    matched = 0;
  };
  return matched;
}

#ifndef history_h
#define history_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#include <stdio.h>    /* FILE * */

/*-----------------------------------------------------------------------
 * This module is used to record and traverse historical lines of user input.
 */

typedef struct GlHistory GlHistory;

/*
 * Create a new history maintenance object.
 */
GlHistory *_new_GlHistory(size_t buflen);

/*
 * Delete a history maintenance object.
 */
GlHistory *_del_GlHistory(GlHistory *glh);

int _glh_add_history(GlHistory *glh, const char *line, int force);

int _glh_search_prefix(GlHistory *glh, const char *line, int prefix_len);

char *_glh_find_backwards(GlHistory *glh, char *line, size_t dim);
char *_glh_find_forwards(GlHistory *glh, char *line, size_t dim);

int _glh_cancel_search(GlHistory *glh);

char *_glh_oldest_line(GlHistory *glh, char *line, size_t dim);
char *_glh_current_line(GlHistory *glh, char *line, size_t dim);

/*
 * Whenever a new line is added to the history buffer, it is given
 * a unique ID, recorded in an object of the following type.
 */
typedef unsigned long GlhLineID;

/*
 * Query the id of a history line offset by a given number of lines from
 * the one that is currently being recalled. If a recall session isn't
 * in progress, or the offset points outside the history list, 0 is
 * returned.
 */
GlhLineID _glh_line_id(GlHistory *glh, int offset);

/*
 * Recall a line by its history buffer ID. If the line is no longer
 * in the buffer, or the specified id is zero, NULL is returned.
 */
char *_glh_recall_line(GlHistory *glh, GlhLineID id, char *line, size_t dim);

/*
 * Write the contents of the history buffer to a given file. Note that
 * ~ and $ expansion are not performed on the filename.
 */
int _glh_save_history(GlHistory *glh, const char *filename,
		      const char *comment, int max_lines);

/*
 * Restore the contents of the history buffer from a given file.
 * Note that ~ and $ expansion are not performed on the filename.
 */
int _glh_load_history(GlHistory *glh, const char *filename, const char *comment,
		      char *line, size_t dim);

/*
 * Set and query the current history group.
 */
int _glh_set_group(GlHistory *glh, unsigned group);
int _glh_get_group(GlHistory *glh);

/*
 * Display the contents of the history list to the specified stdio
 * output group.
 */
int _glh_show_history(GlHistory *glh, GlWriteFn *write_fn, void *data,
		      const char *fmt, int all_groups, int max_lines);

/*
 * Change the size of the history buffer.
 */
int _glh_resize_history(GlHistory *glh, size_t bufsize);

/*
 * Set an upper limit to the number of lines that can be recorded in the
 * history list, or remove a previously specified limit.
 */
void _glh_limit_history(GlHistory *glh, int max_lines);

/*
 * Discard either all history, or the history associated with the current
 * history group.
 */
void _glh_clear_history(GlHistory *glh, int all_groups);

/*
 * Temporarily enable or disable the history facility.
 */
void _glh_toggle_history(GlHistory *glh, int enable);

/*
 * Lookup a history line by its sequential number of entry in the
 * history buffer.
 */
int _glh_lookup_history(GlHistory *glh, GlhLineID id, const char **line,
			unsigned *group, time_t *timestamp);

/*
 * Query the state of the history list.
 */
void _glh_state_of_history(GlHistory *glh, int *enabled, unsigned *group,
			   int *max_lines);

/*
 * Get the range of lines in the history buffer.
 */
void _glh_range_of_history(GlHistory *glh, unsigned long *oldest,
			   unsigned long *newest, int *nlines);

/*
 * Return the size of the history buffer and the amount of the
 * buffer that is currently in use.
 */
void _glh_size_of_history(GlHistory *glh, size_t *buff_size, size_t *buff_used);

/*
 * Get information about the last error in this module.
 */
const char *_glh_last_error(GlHistory *glh);

/*
 * Return non-zero if a history search session is currently in progress.
 */
int _glh_search_active(GlHistory *glh);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

/*
 * If file-system access is to be excluded, this module has no function,
 * so all of its code should be excluded.
 */
#ifndef WITHOUT_FILE_SYSTEM

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>

#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <pwd.h>

#include "pathutil.h"
#include "homedir.h"
#include "errmsg.h"

/*
 * Use the reentrant POSIX threads versions of the password lookup functions?
 */
#if defined(PREFER_REENTRANT) && defined(_POSIX_C_SOURCE) && _POSIX_C_SOURCE >= 199506L
#define THREAD_COMPATIBLE 1
/*
 * Under Solaris we can use thr_main() to determine whether
 * threads are actually running, and thus when it is necessary
 * to avoid non-reentrant features.
 */
#if defined __sun && defined __SVR4
#include <thread.h>                      /* Solaris thr_main() */
#endif
#endif

/*
 * Provide a password buffer size fallback in case the max size reported
 * by sysconf() is said to be indeterminate.
 */
#define DEF_GETPW_R_SIZE_MAX 1024

/*
 * The resources needed to lookup and record a home directory are
 * maintained in objects of the following type.
 */
struct HomeDir {
  ErrMsg *err;             /* The error message report buffer */
  char *buffer;            /* A buffer for reading password entries and */
                           /*  directory paths. */
  int buflen;              /* The allocated size of buffer[] */
#ifdef THREAD_COMPATIBLE
  struct passwd pwd;       /* The password entry of a user */
#endif
};

static const char *hd_getpwd(HomeDir *home);

/*.......................................................................
 * Create a new HomeDir object.
 *
 * Output:
 *  return  HomeDir *  The new object, or NULL on error.
 */
HomeDir *_new_HomeDir(void)
{
  HomeDir *home;  /* The object to be returned */
  size_t pathlen; /* The estimated maximum size of a pathname */
/*
 * Allocate the container.
 */
  home = (HomeDir *) malloc(sizeof(HomeDir));
  if(!home) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to _del_HomeDir().
 */
  home->err = NULL;
  home->buffer = NULL;
  home->buflen = 0;
/*
 * Allocate a place to record error messages.
 */
  home->err = _new_ErrMsg();
  if(!home->err)
    return _del_HomeDir(home);
/*
 * Allocate the buffer that is used by the reentrant POSIX password-entry
 * lookup functions.
 */
#ifdef THREAD_COMPATIBLE
/*
 * Get the length of the buffer needed by the reentrant version
 * of getpwnam().
 */
#ifndef _SC_GETPW_R_SIZE_MAX
  home->buflen = DEF_GETPW_R_SIZE_MAX;
#else
  errno = 0;
  home->buflen = sysconf(_SC_GETPW_R_SIZE_MAX);
/*
 * If the limit isn't available, substitute a suitably large fallback value.
 */
  if(home->buflen < 0 || errno)
    home->buflen = DEF_GETPW_R_SIZE_MAX;
#endif
#endif
/*
 * If the existing buffer length requirement is too restrictive to record
 * a pathname, increase its length.
 */
  pathlen = _pu_pathname_dim();
  if(pathlen > home->buflen)
    home->buflen = pathlen;
/*
 * Allocate a work buffer.
 */
  home->buffer = (char *) malloc(home->buflen);
  if(!home->buffer) {
    errno = ENOMEM;
    return _del_HomeDir(home);
  };
  return home;
}

/*.......................................................................
 * Delete a HomeDir object.
 *
 * Input:
 *  home   HomeDir *  The object to be deleted.
 * Output:
 *  return HomeDir *  The deleted object (always NULL).
 */
HomeDir *_del_HomeDir(HomeDir *home)
{
  if(home) {
    home->err = _del_ErrMsg(home->err);
    if(home->buffer)
      free(home->buffer);
    free(home);
  };
  return NULL;
}

/*.......................................................................
 * Lookup the home directory of a given user in the password file.
 *
 * Input:
 *  home      HomeDir *   The resources needed to lookup the home directory.
 *  user   const char *   The name of the user to lookup, or "" to lookup
 *                        the home directory of the person running the
 *                        program.
 * Output:
 *  return const char *   The home directory. If the library was compiled
 *                        with threads, this string is part of the HomeDir
 *                        object and will change on subsequent calls. If
 *                        the library wasn't compiled to be reentrant,
 *                        then the string is a pointer into a static string
 *                        in the C library and will change not only on
 *                        subsequent calls to this function, but also if
 *                        any calls are made to the C library password
 *                        file lookup functions. Thus to be safe, you should
 *                        make a copy of this string before calling any
 *                        other function that might do a password file
 *                        lookup.
 *
 *                        On error, NULL is returned and a description
 *                        of the error can be acquired by calling
 *                        _hd_last_home_dir_error().
 */
const char *_hd_lookup_home_dir(HomeDir *home, const char *user)
{
  const char *home_dir;   /* A pointer to the home directory of the user */
/*
 * If no username has been specified, arrange to lookup the current
 * user.
 */
  int login_user = !user || *user=='\0';
/*
 * Check the arguments.
 */
  if(!home) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Handle the ksh "~+". This expands to the absolute path of the
 * current working directory.
 */
  if(!login_user && strcmp(user, "+") == 0) {
    home_dir = hd_getpwd(home);
    if(!home_dir) {
      _err_record_msg(home->err, "Can't determine current directory",
		      END_ERR_MSG);
      return NULL;
    }
    return home_dir;
  };
/*
 * When looking up the home directory of the current user, see if the
 * HOME environment variable is set, and if so, return its value.
 */
  if(login_user) {
    home_dir = getenv("HOME");
    if(home_dir)
      return home_dir;
  };
/*
 * Look up the password entry of the user.
 * First the POSIX threads version - this is painful!
 */
#ifdef THREAD_COMPATIBLE
  {
    struct passwd *ret; /* The returned pointer to pwd */
    int status;         /* The return value of getpwnam_r() */
/*
 * Look up the password entry of the specified user.
 */
    if(login_user)
      status = getpwuid_r(geteuid(), &home->pwd, home->buffer, home->buflen,
			  &ret);
    else
      status = getpwnam_r(user, &home->pwd, home->buffer, home->buflen, &ret);
    if(status || !ret) {
      _err_record_msg(home->err, "User '", user, "' doesn't exist.",
		      END_ERR_MSG);
      return NULL;
    };
/*
 * Get a pointer to the string that holds the home directory.
 */
    home_dir = home->pwd.pw_dir;
  };
/*
 * Now the classic unix version.
 */
#else
  {
    struct passwd *pwd = login_user ? getpwuid(geteuid()) : getpwnam(user);
    if(!pwd) {
      _err_record_msg(home->err, "User '", user, "' doesn't exist.",
		      END_ERR_MSG);
      return NULL;
    };
/*
 * Get a pointer to the home directory.
 */
    home_dir = pwd->pw_dir;
  };
#endif
  return home_dir;
}

/*.......................................................................
 * Return a description of the last error that caused _hd_lookup_home_dir()
 * to return NULL.
 *
 * Input:
 *  home   HomeDir *  The resources needed to record the home directory.
 * Output:
 *  return    char *  The description of the last error.
 */
const char *_hd_last_home_dir_error(HomeDir *home)
{
  return home ? _err_get_msg(home->err) : "NULL HomeDir argument";
}

/*.......................................................................
 * The _hd_scan_user_home_dirs() function calls a user-provided function
 * for each username known by the system, passing the function both
 * the name and the home directory of the user.
 *
 * Input:
 *  home             HomeDir *  The resource object for reading home
 *                              directories.
 *  prefix        const char *  Only information for usernames that
 *                              start with this prefix will be
 *                              returned. Note that the empty
 &                              string "", matches all usernames.
 *  data                void *  Anonymous data to be passed to the
 *                              callback function.
 *  callback_fn  HOME_DIR_FN(*) The function to call for each user.
 * Output:
 *  return               int    0 - Successful completion.
 *                              1 - An error occurred. A description
 *                                  of the error can be obtained by
 *                                  calling _hd_last_home_dir_error().
 */
int _hd_scan_user_home_dirs(HomeDir *home, const char *prefix,
			    void *data, HOME_DIR_FN(*callback_fn))
{
  int waserr = 0;       /* True after errors */
  int prefix_len;       /* The length of prefix[] */
/*
 * Check the arguments.
 */
  if(!home || !prefix || !callback_fn) {
    if(home) {
      _err_record_msg(home->err,
		      "_hd_scan_user_home_dirs: Missing callback function",
		      END_ERR_MSG);
    };
    return 1;
  };
/*
 * Get the length of the username prefix.
 */
  prefix_len = strlen(prefix);
/*
 * There are no reentrant versions of getpwent() etc for scanning
 * the password file, so disable username completion when the
 * library is compiled to be reentrant.
 */
#if defined(PREFER_REENTRANT) && defined(_POSIX_C_SOURCE) && _POSIX_C_SOURCE >= 199506L
#if defined __sun && defined __SVR4
  if(0)
#else
  if(1)
#endif
  {
    struct passwd pwd_buffer;  /* A returned password entry */
    struct passwd *pwd;        /* A pointer to pwd_buffer */
    char buffer[512];          /* The buffer in which the string members of */
                               /* pwd_buffer are stored. */
/*
 * See if the prefix that is being completed is a complete username.
 */
    if(!waserr && getpwnam_r(prefix, &pwd_buffer, buffer, sizeof(buffer),
			     &pwd) == 0 && pwd != NULL) {
      waserr = callback_fn(data, pwd->pw_name, pwd->pw_dir,
			   _err_get_msg(home->err), ERR_MSG_LEN);
    };
/*
 * See if the username of the current user minimally matches the prefix.
 */
    if(!waserr && getpwuid_r(getuid(), &pwd_buffer, buffer, sizeof(buffer),
			     &pwd) == 0 && pwd != NULL &&
                             strncmp(prefix, pwd->pw_name, prefix_len)==0) {
      waserr = callback_fn(data, pwd->pw_name, pwd->pw_dir,
			   _err_get_msg(home->err), ERR_MSG_LEN);
    };
/*
 * Reentrancy not required?
 */
  } else
#endif
  {
    struct passwd pwd_buffer;  /* A returned password entry */
    struct passwd *pwd;   /* The pointer to the latest password entry */
/*
 * Open the password file.
 */
    setpwent();
/*
 * Read the contents of the password file, looking for usernames
 * that start with the specified prefix, and adding them to the
 * list of matches.
 */
#if defined __sun && defined __SVR4
    while((pwd = getpwent_r(&pwd_buffer, home->buffer, home->buflen)) != NULL && !waserr) {
#else
    while((pwd = getpwent()) != NULL && !waserr) {
#endif
      if(strncmp(prefix, pwd->pw_name, prefix_len) == 0) {
	waserr = callback_fn(data, pwd->pw_name, pwd->pw_dir,
			     _err_get_msg(home->err), ERR_MSG_LEN);
      };
    };
/*
 * Close the password file.
 */
    endpwent();
  };
/*
 * Under ksh ~+ stands for the absolute pathname of the current working
 * directory.
 */
  if(!waserr && strncmp(prefix, "+", prefix_len) == 0) {
    const char *pwd = hd_getpwd(home);
    if(pwd) {
      waserr = callback_fn(data, "+", pwd, _err_get_msg(home->err),ERR_MSG_LEN);
    } else {
      waserr = 1;
      _err_record_msg(home->err, "Can't determine current directory.",
		      END_ERR_MSG);
    };
  };
  return waserr;
}

/*.......................................................................
 * Return the value of getenv("PWD") if this points to the current
 * directory, or the return value of getcwd() otherwise. The reason for
 * prefering PWD over getcwd() is that the former preserves the history
 * of symbolic links that have been traversed to reach the current
 * directory. This function is designed to provide the equivalent
 * expansion of the ksh ~+ directive, which normally returns its value
 * of PWD.
 *
 * Input:
 *  home      HomeDir *  The resource object for reading home directories.
 * Output:
 *  return const char *  A pointer to either home->buffer, where the
 *                       pathname is recorded, the string returned by
 *                       getenv("PWD"), or NULL on error.
 */
static const char *hd_getpwd(HomeDir *home)
{
/*
 * Get the absolute path of the current working directory.
 */
  char *cwd = getcwd(home->buffer, home->buflen);
/*
 * Some shells set PWD with the path of the current working directory.
 * This will differ from cwd in that it won't have had symbolic links
 * expanded.
 */
  const char *pwd = getenv("PWD");
/*
 * If PWD was set, and it points to the same directory as cwd, return
 * its value. Note that it won't be the same if the current shell or
 * the current program has changed directories, after inheriting PWD
 * from a parent shell.
 */
  struct stat cwdstat, pwdstat;
  if(pwd && cwd && stat(cwd, &cwdstat)==0 && stat(pwd, &pwdstat)==0 &&
     cwdstat.st_dev == pwdstat.st_dev && cwdstat.st_ino == pwdstat.st_ino)
    return pwd;
/*
 * Also return pwd if getcwd() failed, since it represents the best
 * information that we have access to.
 */
  if(!cwd)
    return pwd;
/*
 * In the absence of a valid PWD, return cwd.
 */
  return cwd;
}

#endif  /* ifndef WITHOUT_FILE_SYSTEM */
#ifndef homedir_h
#define homedir_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

typedef struct HomeDir HomeDir;

/*
 * The following constructor and destructor functions create and
 * delete the resources needed to look up home directories.
 */
HomeDir *_new_HomeDir(void);
HomeDir *_del_HomeDir(HomeDir *home);

/*
 * Return the home directory of a specified user, or NULL if unknown.
 */
const char *_hd_lookup_home_dir(HomeDir *home, const char *user);

/*
 * Get the description of the that occured when _hd_lookup_home_dir() was
 * last called.
 */
const char *_hd_last_home_dir_error(HomeDir *home);

/*
 * The _hd_scan_user_home_dirs() function calls a user-provided function
 * for each username known by the system, passing the function both
 * the name and the home directory of the user.
 *
 * The following macro can be used to declare both pointers and
 * prototypes for the callback functions. The 'data' argument is
 * a copy of the 'data' argument passed to _hd_scan_user_home_dirs()
 * and is intended for the user of _hd_scan_user_home_dirs() to use
 * to pass anonymous context data to the callback function.
 * The username and home directories are passed to the callback function
 * in the *usrnam and *homedir arguments respectively.
 * To abort the scan, and have _hd_scan_user_home_dirs() return 1, the
 * callback function can return 1. A description of up to maxerr
 * characters before the terminating '\0', can be written to errmsg[].
 * This can then be examined by calling _hd_last_home_dir_error().
 * To indicate success and continue the scan, the callback function
 * should return 0. _hd_scan_user_home_dirs() returns 0 on successful
 * completion of the scan, or 1 if an error occurred or a call to the
 * callback function returned 1.
 */
#define HOME_DIR_FN(fn) int (fn)(void *data, const char *usrnam, const char *homedir, char *errmsg, int maxerr)

int _hd_scan_user_home_dirs(HomeDir *home, const char *prefix, void *data,
			    HOME_DIR_FN(*callback_fn));

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <errno.h>

#include "ioutil.h"

static int _io_pad_line(GlWriteFn *write_fn, void *data, int c, int n);

/*.......................................................................
 * Display a left-justified string over multiple terminal lines,
 * taking account of the specified width of the terminal. Optional
 * indentation and an option prefix string can be specified to be
 * displayed at the start of each new terminal line used, and if
 * needed, a single paragraph can be broken across multiple calls.
 * Note that literal newlines in the input string can be used to force
 * a newline at any point, and that in order to allow individual
 * paragraphs to be written using multiple calls to this function,
 * unless an explicit newline character is specified at the end of the
 * string, a newline will not be started at the end of the last word
 * in the string. Note that when a new line is started between two
 * words that are separated by spaces, those spaces are not output,
 * whereas when a new line is started because a newline character was
 * found in the string, only the spaces before the newline character
 * are discarded.
 *
 * Input:
 *  write_fn  GlWriteFn *  The callback function to use to write the
 *                         output.
 *  data           void *  A pointer to arbitrary data to be passed to
 *                         write_fn() whenever it is called.
 *  fp             FILE *  The stdio stream to write to.
 *  indentation     int    The number of fill characters to use to
 *                        indent the start of each new terminal line.
 *  prefix   const char *  An optional prefix string to write after the
 *                         indentation margin at the start of each new
 *                         terminal line. You can specify NULL if no
 *                         prefix is required.
 *  suffix   const char *  An optional suffix string to draw at the end
 *                         of the terminal line. The line will be padded
 *                         where necessary to ensure that the suffix ends
 *                         in the last column of the terminal line. If
 *                         no suffix is desired, specify NULL.
 *  fill_char       int    The padding character to use when indenting
 *                         and filling up to the suffix.
 *  term_width      int    The width of the terminal being written to.
 *  start           int    The number of characters already written to
 *                         the start of the current terminal line. This
 *                         is primarily used to allow individual
 *                         paragraphs to be written over multiple calls
 *                         to this function, but can also be used to
 *                         allow you to start the first line of a
 *                         paragraph with a different prefix or
 *                         indentation than those specified above.
 *  string   const char *  The string to be written.
 * Output:
 *  return          int    On error -1 is returned. Otherwise the
 *                         return value is the terminal column index at
 *                         which the cursor was left after writing the
 *                         final word in the string. Successful return
 *                         values can thus be passed verbatim to the
 *                         'start' arguments of subsequent calls to
 *                         _io_display_text() to allow the printing of a
 *                         paragraph to be broken across multiple calls
 *                         to _io_display_text().
 */
int _io_display_text(GlWriteFn *write_fn, void *data, int indentation,
		     const char *prefix, const char *suffix, int fill_char,
		     int term_width, int start, const char *string)
{
  int ndone;        /* The number of characters written from string[] */
  int nnew;         /* The number of characters to be displayed next */
  int was_space;    /* True if the previous character was a space or tab */
  int last = start; /* The column number of the last character written */
  int prefix_len;   /* The length of the optional line prefix string */
  int suffix_len;   /* The length of the optional line prefix string */
  int margin_width; /* The total number of columns used by the indentation */
                    /*  margin and the prefix string. */
  int i;
/*
 * Check the arguments?
 */
  if(!string || !write_fn) {
    errno = EINVAL;
    return -1;
  };
/*
 * Enforce sensible values on the arguments.
 */
  if(term_width < 0)
    term_width = 0;
  if(indentation > term_width)
    indentation = term_width;
  else if(indentation < 0)
    indentation = 0;
  if(start > term_width)
    start = term_width;
  else if(start < 0)
    start = 0;
/*
 * Get the length of the prefix string.
 */
  prefix_len = prefix ? strlen(prefix) : 0;
/*
 * Get the length of the suffix string.
 */
  suffix_len = suffix ? strlen(suffix) : 0;
/*
 * How many characters are devoted to indenting and prefixing each line?
 */
  margin_width = indentation + prefix_len;
/*
 * Write as many terminal lines as are needed to display the whole string.
 */
  for(ndone=0; string[ndone]; start=0) {
    last = start;
/*
 * Write spaces from the current position in the terminal line to the
 * width of the requested indentation margin.
 */
    if(indentation > 0 && last < indentation) {
      if(_io_pad_line(write_fn, data, fill_char, indentation - last))
	return -1;
      last = indentation;
    };
/*
 * If a prefix string has been specified, display it unless we have
 * passed where it should end in the terminal output line.
 */
    if(prefix_len > 0 && last < margin_width) {
      int pstart = last - indentation;
      int plen = prefix_len - pstart;
      if(write_fn(data, prefix+pstart, plen) != plen)
	return -1;
      last = margin_width;
    };
/*
 * Locate the end of the last complete word in the string before
 * (term_width - start) characters have been seen. To handle the case
 * where a single word is wider than the available space after the
 * indentation and prefix margins, always make sure that at least one
 * word is printed after the margin, regardless of whether it won't
 * fit on the line. The two exceptions to this rule are if an embedded
 * newline is found in the string or the end of the string is reached
 * before any word has been seen.
 */
    nnew = 0;
    was_space = 0;
    for(i=ndone; string[i] && (last+i-ndone < term_width - suffix_len ||
			   (nnew==0 && last==margin_width)); i++) {
      if(string[i] == '\n') {
	if(!was_space)
	  nnew = i-ndone;
	break;
      } else if(isspace((int) string[i])) {
	if(!was_space) {
	  nnew = i-ndone+1;
	  was_space = 1;
	};
      } else {
	was_space = 0;
      };
    };
/*
 * Does the end of the string delimit the last word that will fit on the
 * output line?
 */
    if(nnew==0 && string[i] == '\0')
      nnew = i-ndone;
/*
 * Write the new line.
 */
    if(write_fn(data, string+ndone, nnew) != nnew)
      return -1;
    ndone += nnew;
    last += nnew;
/*
 * Start a newline unless we have reached the end of the input string.
 * In the latter case, in order to give the caller the chance to
 * concatenate multiple calls to _io_display_text(), omit the newline,
 * leaving it up to the caller to write this.
 */
    if(string[ndone] != '\0') {
/*
 * If a suffix has been provided, pad out the end of the line with spaces
 * such that the suffix will end in the right-most terminal column.
 */
      if(suffix_len > 0) {
	int npad = term_width - suffix_len - last;
	if(npad > 0 && _io_pad_line(write_fn, data, fill_char, npad))
	  return -1;
	last += npad;
	if(write_fn(data, suffix, suffix_len) != suffix_len)
	  return -1;
	last += suffix_len;
      };
/*
 * Start a new line.
 */
      if(write_fn(data, "\n",  1) != 1)
	return -1;
/*
 * Skip any spaces and tabs that follow the last word that was written.
 */
      while(string[ndone] && isspace((int)string[ndone]) &&
	    string[ndone] != '\n')
	ndone++;
/*
 * If the terminating character was a literal newline character,
 * skip it in the input string, since we just wrote it.
 */
      if(string[ndone] == '\n')
	ndone++;
      last = 0;
    };
  };
/*
 * Return the column number of the last character printed.
 */
  return last;
}

/*.......................................................................
 * Write a given number of spaces to the specified stdio output string.
 *
 * Input:
 *  write_fn  GlWriteFn *  The callback function to use to write the
 *                         output.
 *  data           void *  A pointer to arbitrary data to be passed to
 *                         write_fn() whenever it is called.
 *  c               int    The padding character.
 *  n               int    The number of spaces to be written.
 * Output:
 *  return          int    0 - OK.
 *                         1 - Error.
 */
static int _io_pad_line(GlWriteFn *write_fn, void *data, int c, int n)
{
  enum {FILL_SIZE=20};
  char fill[FILL_SIZE+1];
/*
 * Fill the buffer with the specified padding character.
 */
  memset(fill, c, FILL_SIZE);
  fill[FILL_SIZE] = '\0';
/*
 * Write the spaces using the above literal string of spaces as
 * many times as needed to output the requested number of spaces.
 */
  while(n > 0) {
    int nnew = n <= FILL_SIZE ? n : FILL_SIZE;
    if(write_fn(data, fill, nnew) != nnew)
      return 1;
    n -= nnew;
  };
  return 0;
}

/*.......................................................................
 * The following is an output callback function which uses fwrite()
 * to write to the stdio stream specified via its callback data argument.
 *
 * Input:
 *  data     void *  The stdio stream to write to, specified via a
 *                   (FILE *) pointer cast to (void *).
 *  s  const char *  The string to be written.
 *  n         int    The length of the prefix of s[] to attempt to
 *                   write.
 * Output:
 *  return    int    The number of characters written from s[]. This
 *                   should normally be a number in the range 0 to n.
 *                   To signal that an I/O error occurred, return -1.
 */
GL_WRITE_FN(_io_write_stdio)
{
  int ndone;   /* The total number of characters written */
  int nnew;    /* The number of characters written in the latest write */
/*
 * The callback data is the stdio stream to write to.
 */
  FILE *fp = (FILE *) data;
/*
 * Because of signals we may need to do more than one write to output
 * the whole string.
 */
  for(ndone=0; ndone<n; ndone += nnew) {
    int nmore = n - ndone;
    nnew = fwrite(s, sizeof(char), nmore, fp);
    if(nnew < nmore) {
      if(errno == EINTR)
	clearerr(fp);
      else
	return ferror(fp) ? -1 : ndone + nnew;
    };
  };
  return ndone;
}

#ifndef ioutil_h
#define ioutil_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*.......................................................................
 * Callback functions of the following type can be registered to write
 * to a terminal, when the default blocking writes to a local terminal
 * aren't appropriate. In particular, if you don't want gl_get_line()
 * to block, then this function should return before writing the
 * specified number of characters if doing otherwise would involve
 * waiting.
 *
 * Input:
 *  data     void *  The anonymous data pointer that was registered with
 *                   this callback function.
 *  s  const char *  The string to be written. Beware that this string
 *                   may not have a terminating '\0' character.
 *  n         int    The length of the prefix of s[] to attempt to
 *                   write.
 * Output:
 *  return    int    The number of characters written from s[]. This
 *                   should normally be a number in the range 0 to n.
 *                   To signal that an I/O error occurred, return -1.
 */
#define GL_WRITE_FN(fn) int (fn)(void *data, const char *s, int n)
typedef GL_WRITE_FN(GlWriteFn);

/*
 * The following output callback function requires a (FILE *) callback
 * data argument, and writes to this stream using the fwrite stdio
 * function.
 */
GL_WRITE_FN(_io_write_stdio);

/*
 * Left justify text within the bounds of the terminal adding optional
 * indentation, prefixes and suffixes to each line if requested.
 */
int _io_display_text(GlWriteFn *write_fn, void *data, int indentation,
		     const char *prefix, const char *suffix, int fill_char,
		     int term_width, int start, const char *string);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <errno.h>

#include "keytab.h"
#include "strngmem.h"
#include "getline.h"
#include "errmsg.h"
#include "hash.h"

/*
 * When allocating or reallocating the key-binding table, how
 * many entries should be added?
 */
#define KT_TABLE_INC 100

/*
 * Define the size of the hash table that is used to associate action
 * names with action functions. This should be a prime number.
 */
#define KT_HASH_SIZE 113

/*
 * Define a binary-symbol-table object.
 */
struct KeyTab {
  ErrMsg *err;            /* Information about the last error */
  int size;               /* The allocated dimension of table[] */
  int nkey;               /* The current number of members in the table */
  KeySym *table;          /* The table of lexically sorted key sequences */
  HashTable *actions;     /* The hash table of actions */
  StringMem *smem;        /* Memory for allocating strings */
};

static int _kt_extend_table(KeyTab *kt);
static int _kt_parse_keybinding_string(const char *keyseq,
				       char *binary, int *nc);
static int _kt_compare_strings(const char *s1, int n1, const char *s2, int n2);
static void _kt_assign_action(KeySym *sym, KtBinder binder, KtKeyFn *keyfn,
			      void *data);
static char _kt_backslash_escape(const char *string, const char **endp);
static int _kt_is_emacs_meta(const char *string);
static int _kt_is_emacs_ctrl(const char *string);
static KtKeyMatch _kt_locate_keybinding(KeyTab *kt, const char *binary_keyseq,
					int nc, int *first, int *last);

/*.......................................................................
 * Create a new key-binding symbol table.
 *
 * Output:
 *  return  KeyTab *  The new object, or NULL on error.
 */
KeyTab *_new_KeyTab(void)
{
  KeyTab *kt;  /* The object to be returned */
/*
 * Allocate the container.
 */
  kt = (KeyTab *) malloc(sizeof(KeyTab));
  if(!kt) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_KeyTab().
 */
  kt->err = NULL;
  kt->size = KT_TABLE_INC;
  kt->nkey = 0;
  kt->table = NULL;
  kt->actions = NULL;
  kt->smem = NULL;
/*
 * Allocate a place to record error messages.
 */
  kt->err = _new_ErrMsg();
  if(!kt->err)
    return _del_KeyTab(kt);
/*
 * Allocate the table.
 */
  kt->table = (KeySym *) malloc(sizeof(kt->table[0]) * kt->size);
  if(!kt->table) {
    errno = ENOMEM;
    return _del_KeyTab(kt);
  };
/*
 * Allocate a hash table of actions.
 */
  kt->actions = _new_HashTable(NULL, KT_HASH_SIZE, IGNORE_CASE, NULL, 0);
  if(!kt->actions)
    return _del_KeyTab(kt);
/*
 * Allocate a string allocation object. This allows allocation of
 * small strings without fragmenting the heap.
 */
  kt->smem = _new_StringMem(KT_TABLE_INC);
  if(!kt->smem)
    return _del_KeyTab(kt);
  return kt;
}

/*.......................................................................
 * Delete a KeyTab object.
 *
 * Input:
 *  kt   KeyTab *  The object to be deleted.
 * Output:
 *  return KeyTab *  The deleted object (always NULL).
 */
KeyTab *_del_KeyTab(KeyTab *kt)
{
  if(kt) {
    if(kt->table)
      free(kt->table);
    kt->actions = _del_HashTable(kt->actions);
    kt->smem = _del_StringMem(kt->smem, 1);
    kt->err = _del_ErrMsg(kt->err);
    free(kt);
  };
  return NULL;
}

/*.......................................................................
 * Increase the size of the table to accomodate more keys.
 *
 * Input:
 *  kt       KeyTab *  The table to be extended.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
static int _kt_extend_table(KeyTab *kt)
{
/*
 * Attempt to increase the size of the table.
 */
  KeySym *newtab = (KeySym *) realloc(kt->table, sizeof(kt->table[0]) *
				      (kt->size + KT_TABLE_INC));
/*
 * Failed?
 */
  if(!newtab) {
    _err_record_msg(kt->err, "Can't extend keybinding table", END_ERR_MSG);
    errno = ENOMEM;
    return 1;
  };
/*
 * Install the resized table.
 */
  kt->table = newtab;
  kt->size += KT_TABLE_INC;
  return 0;
}

/*.......................................................................
 * Add, update or remove a keybinding to the table.
 *
 * Input:
 *  kt           KeyTab *  The table to add the binding to.
 *  binder     KtBinder    The source of the binding.
 *  keyseq   const char *  The key-sequence to bind.
 *  action         char *  The action to associate with the key sequence, or
 *                         NULL to remove the action associated with the
 *                         key sequence.
 * Output:
 *  return          int    0 - OK.
 *                         1 - Error.
 */
int _kt_set_keybinding(KeyTab *kt, KtBinder binder, const char *keyseq,
		       const char *action)
{
  KtKeyFn *keyfn; /* The action function */
  void *data;     /* The callback data of the action function */
/*
 * Check arguments.
 */
  if(kt==NULL || !keyseq) {
    errno = EINVAL;
    if(kt)
      _err_record_msg(kt->err, "NULL argument(s)", END_ERR_MSG);
    return 1;
  };
/*
 * Lookup the function that implements the specified action.
 */
  if(!action) {
    keyfn = 0;
    data = NULL;
  } else {
    Symbol *sym = _find_HashSymbol(kt->actions, action);
    if(!sym) {
      _err_record_msg(kt->err, "Unknown key-binding action: ", action,
		      END_ERR_MSG);
      errno = EINVAL;
      return 1;
    };
    keyfn = (KtKeyFn *) sym->fn;
    data = sym->data;
  };
/*
 * Record the action in the table.
 */
  return _kt_set_keyfn(kt, binder, keyseq, keyfn, data);
}

/*.......................................................................
 * Add, update or remove a keybinding to the table, specifying an action
 * function directly.
 *
 * Input:
 *  kt       KeyTab *  The table to add the binding to.
 *  binder KtBinder    The source of the binding.
 *  keyseq     char *  The key-sequence to bind.
 *  keyfn   KtKeyFn *  The action function, or NULL to remove any existing
 *                     action function.
 *  data       void *  A pointer to anonymous data to be passed to keyfn
 *                     whenever it is called.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */
int _kt_set_keyfn(KeyTab *kt, KtBinder binder, const char *keyseq,
		  KtKeyFn *keyfn, void *data)
{
  const char *kptr;  /* A pointer into keyseq[] */
  char *binary;      /* The binary version of keyseq[] */
  int nc;            /* The number of characters in binary[] */
  int first,last;    /* The first and last entries in the table which */
                     /*  minimally match. */
  int size;          /* The size to allocate for the binary string */
  int i;
/*
 * Check arguments.
 */
  if(kt==NULL || !keyseq) {
    errno = EINVAL;
    if(kt)
      _err_record_msg(kt->err, "NULL argument(s)", END_ERR_MSG);
    return 1;
  };
/*
 * Work out a pessimistic estimate of how much space will be needed
 * for the binary copy of the string, noting that binary meta characters
 * embedded in the input string get split into two characters.
 */
  for(size=0,kptr = keyseq; *kptr; kptr++)
    size += IS_META_CHAR(*kptr) ? 2 : 1;
/*
 * Allocate a string that has the length of keyseq[].
 */
  binary = _new_StringMemString(kt->smem, size + 1);
  if(!binary) {
    errno = ENOMEM;
    _err_record_msg(kt->err, "Insufficient memory to record key sequence",
		    END_ERR_MSG);
    return 1;
  };
/*
 * Convert control and octal character specifications to binary characters.
 */
  if(_kt_parse_keybinding_string(keyseq, binary, &nc)) {
    binary = _del_StringMemString(kt->smem, binary);
    return 1;
  };
/*
 * Lookup the position in the table at which to insert the binding.
 */
  switch(_kt_locate_keybinding(kt, binary, nc, &first, &last)) {
/*
 * If an exact match for the key-sequence is already in the table,
 * simply replace its binding function (or delete the entry if
 * the new binding is 0).
 */
  case KT_EXACT_MATCH:
    if(keyfn) {
      _kt_assign_action(kt->table + first, binder, keyfn, data);
    } else {
      _del_StringMemString(kt->smem, kt->table[first].keyseq);
      memmove(kt->table + first, kt->table + first + 1,
	      (kt->nkey - first - 1) * sizeof(kt->table[0]));
      kt->nkey--;
    };
    binary = _del_StringMemString(kt->smem, binary);
    break;
/*
 * If an ambiguous match has been found and we are installing a
 * callback, then our new key-sequence would hide all of the ambiguous
 * matches, so we shouldn't allow it.
 */
  case KT_AMBIG_MATCH:
    if(keyfn) {
      _err_record_msg(kt->err, "Can't bind \"", keyseq,
		      "\", because it is a prefix of another binding",
		      END_ERR_MSG);
      binary = _del_StringMemString(kt->smem, binary);
      errno = EPERM;
      return 1;
    };
    break;
/*
 * If the entry doesn't exist, create it.
 */
  case KT_NO_MATCH:
/*
 * Add a new binding?
 */
    if(keyfn) {
      KeySym *sym;
/*
 * We will need a new entry, extend the table if needed.
 */
      if(kt->nkey + 1 > kt->size) {
	if(_kt_extend_table(kt)) {
	  binary = _del_StringMemString(kt->smem, binary);
	  return 1;
	};
      };
/*
 * Make space to insert the new key-sequence before 'last'.
 */
      if(last < kt->nkey) {
	memmove(kt->table + last + 1, kt->table + last,
		(kt->nkey - last) * sizeof(kt->table[0]));
      };
/*
 * Insert the new binding in the vacated position.
 */
      sym = kt->table + last;
      sym->keyseq = binary;
      sym->nc = nc;
      for(i=0; i<KTB_NBIND; i++) {
	KtAction *action = sym->actions + i;
	action->fn = 0;
	action->data = NULL;
      };
      sym->binder = -1;
      _kt_assign_action(sym, binder, keyfn, data);
      kt->nkey++;
    };
    break;
  case KT_BAD_MATCH:
    binary = _del_StringMemString(kt->smem, binary);
    return 1;
    break;
  };
  return 0;
}

/*.......................................................................
 * Perform a min-match lookup of a key-binding.
 *
 * Input:
 *  kt          KeyTab *   The keybinding table to lookup in.
 *  binary_keyseq char *   The binary key-sequence to lookup.
 *  nc             int     the number of characters in keyseq[].
 * Input/Output:
 *  first,last     int *   If there is an ambiguous or exact match, the indexes
 *                         of the first and last symbols that minimally match
 *                         will be assigned to *first and *last respectively.
 *                         If there is no match, then first and last will
 *                         bracket the location where the symbol should be
 *                         inserted.
 * Output:
 *  return  KtKeyMatch     One of the following enumerators:
 *                          KT_EXACT_MATCH - An exact match was found.
 *                          KT_AMBIG_MATCH - An ambiguous match was found.
 *                          KT_NO_MATCH    - No match was found.
 *                          KT_BAD_MATCH   - An error occurred while searching.
 */
static KtKeyMatch _kt_locate_keybinding(KeyTab *kt, const char *binary_keyseq,
					int nc, int *first, int *last)
{
  int mid;     /* The index at which to bisect the table */
  int bot;     /* The lowest index of the table not searched yet */
  int top;     /* The highest index of the table not searched yet */
  int test;    /* The return value of strcmp() */
/*
 * Perform a binary search for the key-sequence.
 */
  bot = 0;
  top = kt->nkey - 1;
  while(top >= bot) {
    mid = (top + bot)/2;
    test = _kt_compare_strings(kt->table[mid].keyseq, kt->table[mid].nc,
			   binary_keyseq, nc);
    if(test > 0)
      top = mid - 1;
    else if(test < 0)
      bot = mid + 1;
    else {
      *first = *last = mid;
      return KT_EXACT_MATCH;
    };
  };
/*
 * An exact match wasn't found, but top is the index just below the
 * index where a match would be found, and bot is the index just above
 * where the match ought to be found.
 */
  *first = top;
  *last = bot;
/*
 * See if any ambiguous matches exist, and if so make *first and *last
 * refer to the first and last matches.
 */
  if(*last < kt->nkey && kt->table[*last].nc > nc &&
     _kt_compare_strings(kt->table[*last].keyseq, nc, binary_keyseq, nc)==0) {
    *first = *last;
    while(*last+1 < kt->nkey && kt->table[*last+1].nc > nc &&
	  _kt_compare_strings(kt->table[*last+1].keyseq, nc, binary_keyseq, nc)==0)
      (*last)++;
    return KT_AMBIG_MATCH;
  };
/*
 * No match.
 */
  return KT_NO_MATCH;
}

/*.......................................................................
 * Lookup the sub-array of key-bindings who's key-sequences minimally
 * match a given key-sequence.
 *
 * Input:
 *  kt          KeyTab *   The keybinding table to lookup in.
 *  binary_keyseq char *   The binary key-sequence to lookup.
 *  nc             int     the number of characters in keyseq[].
 * Input/Output:
 *  matches     KeySym **  The array of minimally matching symbols
 *                         can be found in (*matches)[0..nmatch-1], unless
 *                         no match was found, in which case *matches will
 *                         be set to NULL.
 *  nmatch         int     The number of ambiguously matching symbols. This
 *                         will be 0 if there is no match, 1 for an exact
 *                         match, and a number greater than 1 for an ambiguous
 *                         match.
 * Output:
 *  return  KtKeyMatch     One of the following enumerators:
 *                          KT_EXACT_MATCH - An exact match was found.
 *                          KT_AMBIG_MATCH - An ambiguous match was found.
 *                          KT_NO_MATCH    - No match was found.
 *                          KT_BAD_MATCH   - An error occurred while searching.
 */
KtKeyMatch _kt_lookup_keybinding(KeyTab *kt, const char *binary_keyseq,
				 int nc, KeySym **matches, int *nmatch)
{
  KtKeyMatch status;  /* The return status */
  int first,last;     /* The indexes of the first and last matching entry */
                      /* in the symbol table. */
/*
 * Check the arguments.
 */
  if(!kt || !binary_keyseq || !matches || !nmatch || nc < 0) {
    errno = EINVAL;
    if(kt)
      _err_record_msg(kt->err, "NULL argument(s)", END_ERR_MSG);
    return KT_BAD_MATCH;
  };
/*
 * Lookup the indexes of the binding-table entries that bracket the
 * target key-sequence.
 */
  status = _kt_locate_keybinding(kt, binary_keyseq, nc, &first, &last);
/*
 * Translate the indexes into the corresponding subarray of matching
 * table entries.
 */
  switch(status) {
  case KT_EXACT_MATCH:
  case KT_AMBIG_MATCH:
    *matches = kt->table + first;
    *nmatch = last - first + 1;
    break;
  default:
    *matches = NULL;
    *nmatch = 0;
    break;
  };
  return status;
}

/*.......................................................................
 * Convert a keybinding string into a uniq binary representation.
 *
 * Control characters can be given directly in their binary form,
 * expressed as either ^ or C-, followed by the character, expressed in
 * octal, like \129 or via C-style backslash escapes, with the addition
 * of '\E' to denote the escape key. Similarly, meta characters can be
 * given directly in binary or expressed as M- followed by the character.
 * Meta characters are recorded as two characters in the binary output
 * string, the first being the escape key, and the second being the key
 * that was modified by the meta key. This means that binding to
 * \EA or ^[A or M-A are all equivalent.
 *
 * Input:
 *  keyseq   char *  The key sequence being added.
 * Input/Output:
 *  binary   char *  The binary version of the key sequence will be
 *                   assigned to binary[], which must have at least
 *                   as many characters as keyseq[] plus the number
 *                   of embedded binary meta characters.
 *  nc        int *  The number of characters assigned to binary[]
 *                   will be recorded in *nc.
 * Output:
 *  return    int    0 - OK.
 *                   1 - Error.
 */
static int _kt_parse_keybinding_string(const char *keyseq, char *binary,
				       int *nc)
{
  const char *iptr = keyseq;   /* Pointer into keyseq[] */
  char *optr = binary;         /* Pointer into binary[] */
  char c;                      /* An intermediate character */
/*
 * Parse the input characters until they are exhausted or the
 * output string becomes full.
 */
  while(*iptr) {
/*
 * Check for special characters.
 */
    switch(*iptr) {
    case '^':        /* A control character specification */
/*
 * Convert the caret expression into the corresponding control
 * character unless no character follows the caret, in which case
 * record a literal caret.
 */
      if(iptr[1]) {
/*
 * Get the next, possibly escaped, character.
 */
	if(iptr[1] == '\\') {
	  c = _kt_backslash_escape(iptr+2, &iptr);
	} else {
	  c = iptr[1];
	  iptr += 2;
	};
/*
 * Convert the character to a control character.
 */
	*optr++ = MAKE_CTRL(c);
      } else {
	*optr++ = *iptr++;
      };
      break;
/*
 * A backslash-escaped character?
 */
    case '\\':
/*
 * Convert the escape sequence to a binary character.
 */
      *optr++ = _kt_backslash_escape(iptr+1, &iptr);
      break;
/*
 * Possibly an emacs-style meta character?
 */
    case 'M':
      if(_kt_is_emacs_meta(iptr)) {
	*optr++ = GL_ESC_CHAR;
	iptr += 2;
      } else {
	*optr++ = *iptr++;
      };
      break;
/*
 * Possibly an emacs-style control character specification?
 */
    case 'C':
      if(_kt_is_emacs_ctrl(iptr)) {
	*optr++ = MAKE_CTRL(iptr[2]);
	iptr += 3;
      } else {
	*optr++ = *iptr++;
      };
      break;
    default:

/*
 * Convert embedded meta characters into an escape character followed
 * by the meta-unmodified character.
 */
      if(IS_META_CHAR(*iptr)) {
	*optr++ = GL_ESC_CHAR;
	*optr++ = META_TO_CHAR(*iptr);
	iptr++;
/*
 * To allow keysequences that start with printable characters to
 * be distinguished from the cursor-key keywords, prepend a backslash
 * to the former. This same operation is performed in gl_interpret_char()
 * before looking up a keysequence that starts with a printable character.
 */
      } else if(iptr==keyseq && !IS_CTRL_CHAR(*iptr) &&
		strcmp(keyseq, "up") != 0 && strcmp(keyseq, "down") != 0 &&
		strcmp(keyseq, "left") != 0 && strcmp(keyseq, "right") != 0) {
	*optr++ = '\\';
	*optr++ = *iptr++;
      } else {
	*optr++ = *iptr++;
      };
    };
  };
/*
 * How many characters were placed in the output array?
 */
  *nc = optr - binary;
  return 0;
}

/*.......................................................................
 * Add, remove or modify an action.
 *
 * Input:
 *  kt     KeyTab *  The key-binding table.
 *  action   char *  The name of the action.
 *  fn    KtKeyFn *  The function that implements the action, or NULL
 *                   to remove an existing action.
 *  data     void *  A pointer to arbitrary callback data to pass to the
 *                   action function whenever it is called.
 * Output:
 *  return    int    0 - OK.
 *                   1 - Error.
 */
int _kt_set_action(KeyTab *kt, const char *action, KtKeyFn *fn, void *data)
{
  Symbol *sym;   /* The symbol table entry of the action */
/*
 * Check the arguments.
 */
  if(!kt || !action) {
    errno = EINVAL;
    if(kt)
      _err_record_msg(kt->err, "NULL argument(s)", END_ERR_MSG);
    return 1;
  };
/*
 * If no function was provided, delete an existing action.
 */
  if(!fn) {
    sym = _del_HashSymbol(kt->actions, action);
    return 0;
  };
/*
 * If the action already exists, replace its action function.
 */
  sym = _find_HashSymbol(kt->actions, action);
  if(sym) {
    sym->fn = (void (*)(void))fn;
    sym->data = data;
    return 0;
  };
/*
 * Add a new action.
 */
  if(!_new_HashSymbol(kt->actions, action, 0, (void (*)(void))fn, data, 0)) {
    _err_record_msg(kt->err, "Insufficient memory to record key-binding action",
		    END_ERR_MSG);
    return 1;
  };
  return 0;
}

/*.......................................................................
 * Compare two strings of specified length which may contain embedded
 * ascii NUL's.
 *
 * Input:
 *  s1       char *  The first of the strings to be compared.
 *  n1        int    The length of the string in s1.
 *  s2       char *  The second of the strings to be compared.
 *  n2        int    The length of the string in s2.
 * Output:
 *  return    int    < 0 if(s1 < s2)
 *                     0 if(s1 == s2)
 *                   > 0 if(s1 > s2)
 */
static int _kt_compare_strings(const char *s1, int n1, const char *s2, int n2)
{
  int i;
/*
 * Find the first character where the two strings differ.
 */
  for(i=0; i<n1 && i<n2 && s1[i]==s2[i]; i++)
    ;
/*
 * Did we hit the end of either string before finding a difference?
 */
  if(i==n1 || i==n2) {
    if(n1 == n2)
      return 0;
    else if(n1==i)
      return -1;
    else
      return 1;
  };
/*
 * Compare the two characters that differed to determine which
 * string is greatest.
 */
  return s1[i] - s2[i];
}

/*.......................................................................
 * Assign a given action function to a binding table entry.
 *
 * Input:
 *  sym       KeySym *  The binding table entry to be modified.
 *  binder  KtBinder    The source of the binding.
 *  keyfn    KtKeyFn *  The action function.
 *  data        void *  A pointer to arbitrary callback data to pass to
 *                      the action function whenever it is called.
 */
static void _kt_assign_action(KeySym *sym, KtBinder binder, KtKeyFn *keyfn,
			      void *data)
{
  KtAction *action;   /* An action function/data pair */
  int i;
/*
 * Unknown binding source?
 */
  if(binder < 0 || binder >= KTB_NBIND)
    return;
/*
 * Record the action according to its source.
 */
  action = sym->actions + binder;
  action->fn = keyfn;
  action->data = data;
/*
 * Find the highest priority binding source that has supplied an
 * action. Note that the actions[] array is ordered in order of
 * descreasing priority, so the first entry that contains a function
 * is the one to use.
 */
  for(i=0; i<KTB_NBIND && !sym->actions[i].fn; i++)
    ;
/*
 * Record the index of this action for use during lookups.
 */
  sym->binder = i < KTB_NBIND ? i : -1;
  return;
}

/*.......................................................................
 * Remove all key bindings that came from a specified source.
 *
 * Input:
 *  kt        KeyTab *  The table of key bindings.
 *  binder  KtBinder    The source of the bindings to be cleared.
 */
void _kt_clear_bindings(KeyTab *kt, KtBinder binder)
{
  int oldkey;   /* The index of a key in the original binding table */
  int newkey;   /* The index of a key in the updated binding table */
/*
 * If there is no table, then no bindings exist to be deleted.
 */
  if(!kt)
    return;
/*
 * Clear bindings of the given source.
 */
  for(oldkey=0; oldkey<kt->nkey; oldkey++)
    _kt_assign_action(kt->table + oldkey, binder, 0, NULL);
/*
 * Delete entries that now don't have a binding from any source.
 */
  newkey = 0;
  for(oldkey=0; oldkey<kt->nkey; oldkey++) {
    KeySym *sym = kt->table + oldkey;
    if(sym->binder < 0) {
      _del_StringMemString(kt->smem, sym->keyseq);
    } else {
      if(oldkey != newkey)
	kt->table[newkey] = *sym;
      newkey++;
    };
  };
/*
 * Record the number of keys that were kept.
 */
  kt->nkey = newkey;
  return;
}

/*.......................................................................
 * Translate a backslash escape sequence to a binary character.
 *
 * Input:
 *  string  const char *   The characters that follow the backslash.
 * Input/Output:
 *  endp    const char **  If endp!=NULL, on return *endp will be made to
 *                         point to the character in string[] which follows
 *                         the escape sequence.
 * Output:
 *  return        char     The binary character.
 */
static char _kt_backslash_escape(const char *string, const char **endp)
{
  char c;  /* The output character */
/*
 * Is the backslash followed by one or more octal digits?
 */
  switch(*string) {
  case '0': case '1': case '2': case '3':
  case '4': case '5': case '6': case '7':
    c = strtol(string, (char **)&string, 8);
    break;
  case 'a':
    c = '\a';
    string++;
    break;
  case 'b':
    c = '\b';
    string++;
    break;
  case 'e': case 'E': /* Escape */
    c = GL_ESC_CHAR;
    string++;
    break;
  case 'f':
    c = '\f';
    string++;
    break;
  case 'n':
    c = '\n';
    string++;
    break;
  case 'r':
    c = '\r';
    string++;
    break;
  case 't':
    c = '\t';
    string++;
    break;
  case 'v':
    c = '\v';
    string++;
    break;
  case '\0':
    c = '\\';
    break;
  default:
    c = *string++;
    break;
  };
/*
 * Report the character which follows the escape sequence.
 */
  if(endp)
    *endp = string;
  return c;
}

/*.......................................................................
 * Return non-zero if the next two characters are M- and a third character
 * follows. Otherwise return 0.
 *
 * Input:
 *  string   const char *  The sub-string to scan.
 * Output:
 *  return          int    1 - The next two characters are M- and these
 *                             are followed by at least one character.
 *                         0 - The next two characters aren't M- or no
 *                             character follows a M- pair.
 */
static int _kt_is_emacs_meta(const char *string)
{
  return *string++ == 'M' && *string++ == '-' && *string;
}

/*.......................................................................
 * Return non-zero if the next two characters are C- and a third character
 * follows. Otherwise return 0.
 *
 * Input:
 *  string   const char *  The sub-string to scan.
 * Output:
 *  return          int    1 - The next two characters are C- and these
 *                             are followed by at least one character.
 *                         0 - The next two characters aren't C- or no
 *                             character follows a C- pair.
 */
static int _kt_is_emacs_ctrl(const char *string)
{
  return *string++ == 'C' && *string++ == '-' && *string;
}

/*.......................................................................
 * Merge an array of bindings with existing bindings.
 *
 * Input:
 *  kt                    KeyTab *  The table of key bindings.
 *  binder              KtBinder    The source of the bindings.
 *  bindings  const KtKeyBinding *  The array of bindings.
 *  n                        int    The number of bindings in bindings[].
 * Output:
 *  return                   int    0 - OK.
 *                                  1 - Error.
 */
int _kt_add_bindings(KeyTab *kt, KtBinder binder, const KtKeyBinding *bindings,
		     unsigned n)
{
  int i;
/*
 * Check the arguments.
 */
  if(!kt || !bindings) {
    errno = EINVAL;
    if(kt)
      _err_record_msg(kt->err, "NULL argument(s)", END_ERR_MSG);
    return 1;
  };
/*
 * Install the array of bindings.
 */
  for(i=0; i<n; i++) {
    if(_kt_set_keybinding(kt, binder, bindings[i].keyseq, bindings[i].action))
      return 1;
  };
  return 0;
}

/*.......................................................................
 * Lookup the function that implements a given action.
 *
 * Input:
 *  kt          KeyTab *  The table of key bindings.
 *  action  const char *  The name of the action to look up.
 * Input/Output:
 *  fn         KtKeyFn ** If the action is found, the function that
 *                        implements it will be assigned to *fn. Note
 *                        that fn can be NULL.
 *  data          void ** If the action is found, the callback data
 *                        associated with the action function, will be
 *                        assigned to *data. Note that data can be NULL.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Action not found.
 */
int _kt_lookup_action(KeyTab *kt, const char *action,
		      KtKeyFn **fn, void **data)
{
  Symbol *sym;   /* The symbol table entry of the action */
/*
 * Check the arguments.
 */
  if(!kt || !action) {
    errno = EINVAL;
    if(kt)
      _err_record_msg(kt->err, "NULL argument(s)", END_ERR_MSG);
    return 1;
  };
/*
 * Lookup the symbol table entry of the action.
 */
  sym = _find_HashSymbol(kt->actions, action);
  if(!sym)
    return 1;
/*
 * Return the function and ccallback data associated with the action.
 */
  if(fn)
    *fn = (KtKeyFn *) sym->fn;
  if(data)
    *data = sym->data;
  return 0;
}

/*.......................................................................
 * Return extra information (ie. in addition to that provided by errno)
 * about the last error to occur in any of the public functions of this
 * module.
 *
 * Input:
 *  kt          KeyTab *  The table of key bindings.
 * Output:
 *  return  const char *  A pointer to the internal buffer in which
 *                        the error message is temporarily stored.
 */
const char *_kt_last_error(KeyTab *kt)
{
  return kt ? _err_get_msg(kt->err) : "NULL KeyTab argument";
}
#ifndef keytab_h
#define keytab_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#include "libtecla.h"

/*-----------------------------------------------------------------------*
 * This module defines a binary-search symbol table of key-bindings.     *
 *-----------------------------------------------------------------------*/

/*
 * All key-binding functions are defined as follows.
 *
 * Input:
 *  gl    GetLine *  The resource object of this library.
 *  count     int    A positive repeat count specified by the user,
 *                   or 1. Action functions should ignore this if
 *                   repeating the action multiple times isn't
 *                   appropriate.
 *  data     void *  A pointer to action-specific data,
 *                   cast to (void *).
 * Output:
 *  return    int    0 - OK.
 *                   1 - Error.
 */
#define KT_KEY_FN(fn) int (fn)(GetLine *gl, int count, void *data)

typedef KT_KEY_FN(KtKeyFn);

/*
 * Allow the association of arbitrary callback data with each action
 * function.
 */
typedef struct {
  KtKeyFn *fn;          /* The acion function */
  void *data;           /* A pointer to arbitrary data to be passed to */
                        /*  fn() whenever it is called. */
} KtAction;

/*
 * Enumerate the possible sources of key-bindings in order of decreasing
 * priority.
 */
typedef enum {
  KTB_USER,         /* This is a binding being set by the user */
  KTB_NORM,         /* This is the default binding set by the library */
  KTB_TERM,         /* This is a binding taken from the terminal settings */
/* The following entry must always be last */
  KTB_NBIND         /* The number of binding sources listed above */
} KtBinder;

/*
 * Define an entry of a key-binding binary symbol table.
 */
typedef struct {
  char *keyseq;                /* The key sequence that triggers the macro */
  int nc;                      /* The number of characters in keyseq[] */
  KtAction actions[KTB_NBIND]; /* Bindings from different sources */
  int binder;                  /* The index of the highest priority element */
                               /*  of actions[] that has been assigned an */
                               /*  action function, or -1 if none have. */
} KeySym;

/*
 * Provide an opaque type alias to the symbol table container.
 */
typedef struct KeyTab KeyTab;

/*
 * Create a new symbol table.
 */
KeyTab *_new_KeyTab(void);

/*
 * Delete the symbol table.
 */
KeyTab *_del_KeyTab(KeyTab *kt);

int _kt_set_keybinding(KeyTab *kt, KtBinder binder,
		       const char *keyseq, const char *action);
int _kt_set_keyfn(KeyTab *kt, KtBinder binder, const char *keyseq,
		  KtKeyFn *fn, void *data);

int _kt_set_action(KeyTab *kt, const char *action, KtKeyFn *fn, void *data);

/*
 * Lookup the function that implements a given action.
 */
int _kt_lookup_action(KeyTab *kt, const char *action,
		      KtKeyFn **fn, void **data);

typedef enum {
  KT_EXACT_MATCH,   /* An exact match was found */
  KT_AMBIG_MATCH,   /* An ambiguous match was found */
  KT_NO_MATCH,      /* No match was found */
  KT_BAD_MATCH      /* An error occurred while searching */
} KtKeyMatch;

KtKeyMatch _kt_lookup_keybinding(KeyTab *kt, const char *binary_keyseq,
				 int nc, KeySym **matches, int *nmatch);

/*
 * Remove all key bindings that came from a specified source.
 */
void _kt_clear_bindings(KeyTab *kt, KtBinder binder);

/*
 * When installing an array of keybings each binding is defined by
 * an element of the following type:
 */
typedef struct {
  const char *keyseq;   /* The sequence of keys that trigger this binding */
  const char *action;   /* The name of the action function that is triggered */
} KtKeyBinding;

/*
 * Merge an array of bindings with existing bindings.
 */
int _kt_add_bindings(KeyTab *kt, KtBinder binder, const KtKeyBinding *bindings,
		     unsigned n);

/*
 * Get information about the last error in this module.
 */
const char *_kt_last_error(KeyTab *kt);

#endif
#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#
#
# Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved.
#

#
# MAPFILE HEADER START
#
# WARNING:  STOP NOW.  DO NOT MODIFY THIS FILE.
# Object versioning must comply with the rules detailed in
#
#	usr/src/lib/README.mapfiles
#
# You should not be making modifications here until you've read the most current
# copy of that file. If you need help, contact a gatekeeper for guidance.
#
# MAPFILE HEADER END
#

$mapfile_version 2

#
# The instances of "tecla_l.5" below (note "l" vs "1") are by design;
# quoting the author:
#
# Unfortunately the tecla_l.5 version string is by now embedded in any
# executable that linked with libtecla versions 1.5 ..., so I can't fix
# the typo without preventing those programs from linking against 1.6.
# Thus I now have to derive tecla_1.6 from tecla_l.5, in the map file.
#

SYMBOL_VERSION tecla_1.6 {
    global:
	gl_append_history;
	gl_automatic_history;
	gl_query_char;
	gl_read_char;
} tecla_l.5;

SYMBOL_VERSION tecla_l.5 {
    global:
	cpl_recall_matches;
	gl_abandon_line;
	gl_bind_keyseq;
	gl_catch_blocked;
	gl_completion_action;
	gl_display_text;
	gl_erase_terminal;
	gl_error_message;
	gl_handle_signal;
	gl_inactivity_timeout;
	gl_io_mode;
	gl_list_signals;
	gl_normal_io;
	gl_pending_io;
	gl_raw_io;
	gl_register_action;
	gl_return_status;
	gl_set_term_size;
	gl_tty_signals;
} tecla_1.4;

SYMBOL_VERSION tecla_1.4 {
    global:
	gl_clear_history;
	gl_configure_getline;
	gl_echo_mode;
	gl_group_history;
	gl_ignore_signal;
	gl_last_signal;
	gl_limit_history;
	gl_load_history;
	gl_lookup_history;
	gl_prompt_style;
	gl_range_of_history;
	gl_replace_prompt;
	gl_resize_history;
	gl_save_history;
	gl_show_history;
	gl_size_of_history;
	gl_state_of_history;
	gl_terminal_size;
	gl_toggle_history;
	gl_trap_signal;
	gl_watch_fd;
	libtecla_version;
} tecla_1.3;

SYMBOL_VERSION tecla_1.3 {
    global:
	ef_list_expansions;
} tecla_1.2;

SYMBOL_VERSION tecla_1.2 {
    global:
	cfc_file_start;
	cfc_literal_escapes;
	cfc_set_check_fn;
	cpl_add_completion;
	cpl_check_exe;
	cpl_complete_word;
	cpl_file_completions;
	cpl_init_FileArgs;
	cpl_last_error;
	cpl_list_completions;
	cpl_record_error;
	del_CplFileConf;
	del_ExpandFile;
	del_GetLine;
	del_PathCache;
	del_PcaPathConf;
	del_WordCompletion;
	ef_expand_file;
	ef_last_error;
	gl_change_terminal;
	gl_customize_completion;
	gl_get_line;
	new_CplFileConf;
	new_ExpandFile;
	new_GetLine;
	new_PathCache;
	new_PcaPathConf;
	new_WordCompletion;
	pca_last_error;
	pca_lookup_file;
	pca_path_completions;
	pca_scan_path;
	pca_set_check_fn;
	ppc_file_start;
	ppc_literal_escapes;
    local:
	*;
};
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * If file-system access is to be excluded, this module has no function,
 * so all of its code should be excluded.
 */
#ifndef WITHOUT_FILE_SYSTEM

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <string.h>
#include <ctype.h>
#include <limits.h>

#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>

#include "pathutil.h"

/*.......................................................................
 * Create a new PathName object.
 *
 * Output:
 *  return  PathName *  The new object, or NULL on error.
 */
PathName *_new_PathName(void)
{
  PathName *path;  /* The object to be returned */
/*
 * Allocate the container.
 */
  path = (PathName *) malloc(sizeof(PathName));
  if(!path) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to _del_PathName().
 */
  path->name = NULL;
  path->dim = 0;
/*
 * Figure out the maximum length of an expanded pathname.
 */
  path->dim = _pu_pathname_dim();
  if(path->dim == 0)
    return _del_PathName(path);
/*
 * Allocate the pathname buffer.
 */
  path->name = (char *)malloc(path->dim * sizeof(char));
  if(!path->name) {
    errno = ENOMEM;
    return _del_PathName(path);
  };
  return path;
}

/*.......................................................................
 * Delete a PathName object.
 *
 * Input:
 *  path   PathName *  The object to be deleted.
 * Output:
 *  return PathName *  The deleted object (always NULL).
 */
PathName *_del_PathName(PathName *path)
{
  if(path) {
    if(path->name)
      free(path->name);
    free(path);
  };
  return NULL;
}

/*.......................................................................
 * Return the pathname to a zero-length string.
 *
 * Input:
 *  path     PathName *  The pathname container.
 * Output:
 *  return       char *  The cleared pathname buffer, or NULL on error.
 */
char *_pn_clear_path(PathName *path)
{
/*
 * Check the arguments.
 */
  if(!path) {
    errno = EINVAL;
    return NULL;
  };
  path->name[0] = '\0';
  return path->name;
}

/*.......................................................................
 * Append a string to a pathname, increasing the size of the pathname
 * buffer if needed.
 *
 * Input:
 *  path        PathName *  The pathname container.
 *  string    const char *  The string to be appended to the pathname.
 *                          Note that regardless of the slen argument,
 *                          this should be a '\0' terminated string.
 *  slen             int    The maximum number of characters to append
 *                          from string[], or -1 to append the whole
 *                          string.
 *  remove_escapes   int    If true, remove the backslashes that escape
 *                          spaces, tabs, backslashes etc..
 * Output:
 *  return          char *  The pathname string path->name[], which may
 *                          have been reallocated, or NULL if there was
 *                          insufficient memory to extend the pathname.
 */
char *_pn_append_to_path(PathName *path, const char *string, int slen,
			int remove_escapes)
{
  int pathlen;     /* The length of the pathname */
  int i;
/*
 * Check the arguments.
 */
  if(!path || !string) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Get the current length of the pathname.
 */
  pathlen = strlen(path->name);
/*
 * How many characters should be appended?
 */
  if(slen < 0 || slen > strlen(string))
    slen = strlen(string);
/*
 * Resize the pathname if needed.
 */
  if(!_pn_resize_path(path, pathlen + slen))
    return NULL;
/*
 * Append the string to the output pathname, removing any escape
 * characters found therein.
 */
  if(remove_escapes) {
    int is_escape = 0;
    for(i=0; i<slen; i++) {
      is_escape = !is_escape && string[i] == '\\';
      if(!is_escape)
	path->name[pathlen++] = string[i];
    };
/*
 * Terminate the string.
 */
    path->name[pathlen] = '\0';
  } else {
/*
 * Append the string directly to the pathname.
 */
    memcpy(path->name + pathlen, string, slen);
    path->name[pathlen + slen] = '\0';
  };
  return path->name;
}

/*.......................................................................
 * Prepend a string to a pathname, increasing the size of the pathname
 * buffer if needed.
 *
 * Input:
 *  path        PathName *  The pathname container.
 *  string    const char *  The string to be prepended to the pathname.
 *                          Note that regardless of the slen argument,
 *                          this should be a '\0' terminated string.
 *  slen             int    The maximum number of characters to prepend
 *                          from string[], or -1 to append the whole
 *                          string.
 *  remove_escapes   int    If true, remove the backslashes that escape
 *                          spaces, tabs, backslashes etc..
 * Output:
 *  return          char *  The pathname string path->name[], which may
 *                          have been reallocated, or NULL if there was
 *                          insufficient memory to extend the pathname.
 */
char *_pn_prepend_to_path(PathName *path, const char *string, int slen,
			  int remove_escapes)
{
  int pathlen;     /* The length of the pathname */
  int shift;       /* The number of characters to shift the suffix by */
  int i,j;
/*
 * Check the arguments.
 */
  if(!path || !string) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Get the current length of the pathname.
 */
  pathlen = strlen(path->name);
/*
 * How many characters should be appended?
 */
  if(slen < 0 || slen > strlen(string))
    slen = strlen(string);
/*
 * Work out how far we need to shift the original path string to make
 * way for the new prefix. When removing escape characters, we need
 * final length of the new prefix, after unescaped backslashes have
 * been removed.
 */
  if(remove_escapes) {
    int is_escape = 0;
    for(shift=0,i=0; i<slen; i++) {
      is_escape = !is_escape && string[i] == '\\';
      if(!is_escape)
	shift++;
    };
  } else {
    shift = slen;
  };
/*
 * Resize the pathname if needed.
 */
  if(!_pn_resize_path(path, pathlen + shift))
    return NULL;
/*
 * Make room for the prefix at the beginning of the string.
 */
  memmove(path->name + shift, path->name, pathlen+1);
/*
 * Copy the new prefix into the vacated space at the beginning of the
 * output pathname, removing any escape characters if needed.
 */
  if(remove_escapes) {
    int is_escape = 0;
    for(i=j=0; i<slen; i++) {
      is_escape = !is_escape && string[i] == '\\';
      if(!is_escape)
	path->name[j++] = string[i];
    };
  } else {
    memcpy(path->name, string, slen);
  };
  return path->name;
}

/*.......................................................................
 * If needed reallocate a given pathname buffer to allow a string of
 * a given length to be stored in it.
 *
 * Input:
 *  path     PathName *  The pathname container object.
 *  length     size_t    The required length of the pathname buffer,
 *                       not including the terminating '\0'.
 * Output:
 *  return       char *  The pathname buffer, or NULL if there was
 *                       insufficient memory.
 */
char *_pn_resize_path(PathName *path, size_t length)
{
/*
 * Check the arguments.
 */
  if(!path) {
    errno = EINVAL;
    return NULL;
  };
/*
 * If the pathname buffer isn't large enough to accomodate a string
 * of the specified length, attempt to reallocate it with the new
 * size, plus space for a terminating '\0'. Also add a bit of
 * head room to prevent too many reallocations if the initial length
 * turned out to be very optimistic.
 */
  if(length + 1 > path->dim) {
    size_t dim =  length + 1 + PN_PATHNAME_INC;
    char *name = (char *) realloc(path->name, dim);
    if(!name)
      return NULL;
    path->name = name;
    path->dim = dim;
  };
  return path->name;
}

/*.......................................................................
 * Estimate the largest amount of space needed to store a pathname.
 *
 * Output:
 *  return size_t   The number of bytes needed, including space for the
 *                  terminating '\0'.
 */
size_t _pu_pathname_dim(void)
{
  int maxlen;   /* The return value excluding space for the '\0' */
/*
 * If the POSIX PATH_MAX macro is defined in limits.h, use it.
 */
#ifdef PATH_MAX
  maxlen = PATH_MAX;
/*
 * If we have pathconf, use it.
 */
#elif defined(_PC_PATH_MAX)
  errno = 0;
  maxlen = pathconf(FS_ROOT_DIR, _PC_PATH_MAX);
  if(maxlen <= 0 || errno)
    maxlen = MAX_PATHLEN_FALLBACK;
/*
 * None of the above approaches worked, so substitute our fallback
 * guess.
 */
#else
    maxlen = MAX_PATHLEN_FALLBACK;
#endif
/*
 * Return the amount of space needed to accomodate a pathname plus
 * a terminating '\0'.
 */
  return maxlen + 1;
}

/*.......................................................................
 * Return non-zero if the specified path name refers to a directory.
 *
 * Input:
 *  pathname  const char *  The path to test.
 * Output:
 *  return           int    0 - Not a directory.
 *                          1 - pathname[] refers to a directory.
 */
int _pu_path_is_dir(const char *pathname)
{
  struct stat statbuf;    /* The file-statistics return buffer */
/*
 * Look up the file attributes.
 */
  if(stat(pathname, &statbuf) < 0)
    return 0;
/*
 * Is the file a directory?
 */
  return S_ISDIR(statbuf.st_mode) != 0;
}

/*.......................................................................
 * Return non-zero if the specified path name refers to a regular file.
 *
 * Input:
 *  pathname  const char *  The path to test.
 * Output:
 *  return           int    0 - Not a regular file.
 *                          1 - pathname[] refers to a regular file.
 */
int _pu_path_is_file(const char *pathname)
{
  struct stat statbuf;    /* The file-statistics return buffer */
/*
 * Look up the file attributes.
 */
  if(stat(pathname, &statbuf) < 0)
    return 0;
/*
 * Is the file a regular file?
 */
  return S_ISREG(statbuf.st_mode) != 0;
}

/*.......................................................................
 * Return non-zero if the specified path name refers to an executable.
 *
 * Input:
 *  pathname  const char *  The path to test.
 * Output:
 *  return           int    0 - Not an executable file.
 *                          1 - pathname[] refers to an executable file.
 */
int _pu_path_is_exe(const char *pathname)
{
  struct stat statbuf;    /* The file-statistics return buffer */
/*
 * Look up the file attributes.
 */
  if(stat(pathname, &statbuf) < 0)
    return 0;
/*
 * Is the file a regular file which is executable by the current user.
 */
  return S_ISREG(statbuf.st_mode) != 0 &&
    (statbuf.st_mode & (S_IXOTH | S_IXGRP | S_IXUSR)) &&
    access(pathname, X_OK) == 0;
}

/*.......................................................................
 * Search backwards for the potential start of a filename. This
 * looks backwards from the specified index in a given string,
 * stopping at the first unescaped space or the start of the line.
 *
 * Input:
 *  string  const char *  The string to search backwards in.
 *  back_from      int    The index of the first character in string[]
 *                        that follows the pathname.
 * Output:
 *  return        char *  The pointer to the first character of
 *                        the potential pathname, or NULL on error.
 */
char *_pu_start_of_path(const char *string, int back_from)
{
  int i, j;
/*
 * Check the arguments.
 */
  if(!string || back_from < 0) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Search backwards from the specified index.
 */
  for(i=back_from-1; i>=0; i--) {
    int c = string[i];
/*
 * Stop on unescaped spaces.
 */
    if(isspace((int)(unsigned char)c)) {
/*
 * The space can't be escaped if we are at the start of the line.
 */
      if(i==0)
        break;
/*
 * Find the extent of the escape characters which precedes the space.
 */
      for(j=i-1; j>=0 && string[j]=='\\'; j--)
	;
/*
 * If there isn't an odd number of escape characters before the space,
 * then the space isn't escaped.
 */
      if((i - 1 - j) % 2 == 0)
	break;
    };
  };
  return (char *)string + i + 1;
}

/*.......................................................................
 * Find the length of a potential filename starting from a given
 * point. This looks forwards from the specified index in a given string,
 * stopping at the first unescaped space or the end of the line.
 *
 * Input:
 *  string   const char *  The string to search backwards in.
 *  start_from      int    The index of the first character of the pathname
 *                         in string[].
 * Output:
 *  return         char *  The pointer to the character that follows
 *                         the potential pathname, or NULL on error.
 */
char *_pu_end_of_path(const char *string, int start_from)
{
  int c;             /* The character being examined */
  int escaped = 0;   /* True when the next character is escaped */
  int i;
/*
 * Check the arguments.
 */
  if(!string || start_from < 0) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Search forwards from the specified index.
 */
  for(i=start_from; (c=string[i]) != '\0'; i++) {
    if(escaped) {
      escaped = 0;
    } else if(isspace(c)) {
      break;
    } else if(c == '\\') {
      escaped = 1;
    };
  };
  return (char *)string + i;
}

/*.......................................................................
 * Return non-zero if the specified path name refers to an existing file.
 *
 * Input:
 *  pathname   const char *  The path to test.
 * Output:
 *  return            int    0 - The file doesn't exist.
 *                           1 - The file does exist.
 */
int _pu_file_exists(const char *pathname)
{
  struct stat statbuf;
  return stat(pathname, &statbuf) == 0;
}

#endif  /* ifndef WITHOUT_FILE_SYSTEM */
#ifndef pathutil_h
#define pathutil_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * The following object encapsulates a buffer designed to be used to
 * store pathnames. The pathname member of the object is initially
 * allocated with the size that _pu_pathname_dim() returns, and then
 * if this turns out to be pessimistic, the pathname can be reallocated
 * via calls to pb_append_to_path() and/or pb_resize_path().
 */
typedef struct {
  char *name;         /* The path buffer */
  size_t dim;         /* The current allocated size of buffer[] */
} PathName;

PathName *_new_PathName(void);
PathName *_del_PathName(PathName *path);

char *_pn_clear_path(PathName *path);
char *_pn_append_to_path(PathName *path, const char *string, int slen,
			int remove_escapes);
char *_pn_prepend_to_path(PathName *path, const char *string, int slen,
			  int remove_escapes);
char *_pn_resize_path(PathName *path, size_t length);

/*
 * Search backwards for the potential start of a filename. This
 * looks backwards from the specified index in a given string,
 * stopping at the first unescaped space or the start of the line.
 */
char *_pu_start_of_path(const char *string, int back_from);

/*
 * Find the end of a potential filename, starting from a given index
 * in the string. This looks forwards from the specified index in a
 * given string, stopping at the first unescaped space or the end
 * of the line.
 */
char *_pu_end_of_path(const char *string, int start_from);


/*
 * Return an estimate of the the length of the longest pathname
 * on the local system.
 */
size_t _pu_pathname_dim(void);

/*
 * Return non-zero if the specified path name refers to a directory.
 */
int _pu_path_is_dir(const char *pathname);

/*
 * Return non-zero if the specified path name refers to a regular file.
 */
int _pu_path_is_file(const char *pathname);

/*
 * Return non-zero if the specified path name refers to an executable.
 */
int _pu_path_is_exe(const char *pathname);

/*
 * Return non-zero if a file exists with the specified pathname.
 */
int _pu_file_exists(const char *pathname);

/*
 * If neither the POSIX PATH_MAX macro nor the pathconf() function
 * can be used to find out the maximum pathlength on the target
 * system, the following fallback maximum length is used.
 */
#define MAX_PATHLEN_FALLBACK 1024

/*
 * If the pathname buffer turns out to be too small, it will be extended
 * in chunks of the following amount (plus whatever is needed at the time).
 */
#define PN_PATHNAME_INC 100

/*
 * Define the special character-sequences of the filesystem.
 */
#define FS_ROOT_DIR "/"     /* The root directory */
#define FS_ROOT_DIR_LEN (sizeof(FS_ROOT_DIR) - 1)
#define FS_PWD "."          /* The current working directory */
#define FS_PWD_LEN (sizeof(FS_PWD_LEN) - 1)
#define FS_DIR_SEP "/"      /* The directory separator string */
#define FS_DIR_SEP_LEN (sizeof(FS_DIR_SEP) - 1)

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

/*
 * If file-system access is to be excluded, this module has no function,
 * so all of its code should be excluded.
 */
#ifndef WITHOUT_FILE_SYSTEM

#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <errno.h>

#include "libtecla.h"
#include "pathutil.h"
#include "homedir.h"
#include "freelist.h"
#include "direader.h"
#include "stringrp.h"
#include "errmsg.h"

/*
 * The new_PcaPathConf() constructor sets the integer first member of
 * the returned object to the following magic number. This is then
 * checked for by pca_path_completions() as a sanity check.
 */
#define PPC_ID_CODE 4567

/*
 * A pointer to a structure of the following type can be passed to
 * the builtin path-completion callback function to modify its behavior.
 */
struct PcaPathConf {
  int id;          /* This is set to PPC_ID_CODE by new_PcaPathConf() */
  PathCache *pc;   /* The path-list cache in which to look up the executables */
  int escaped;     /* If non-zero, backslashes in the input line are */
                   /*  interpreted as escaping special characters and */
                   /*  spaces, and any special characters and spaces in */
                   /*  the listed completions will also be escaped with */
                   /*  added backslashes. This is the default behaviour. */
                   /* If zero, backslashes are interpreted as being */
                   /*  literal parts of the file name, and none are added */
                   /*  to the completion suffixes. */
  int file_start;  /* The index in the input line of the first character */
                   /*  of the file name. If you specify -1 here, */
                   /*  pca_path_completions() identifies the */
                   /*  the start of the file by looking backwards for */
                   /*  an unescaped space, or the beginning of the line. */
};

/*
 * Prepended to each chached filename is a character which contains
 * one of the following status codes. When a given filename (minus
 * this byte) is passed to the application's check_fn(), the result
 * is recorded in this byte, such that the next time it is looked
 * up, we don't have to call check_fn() again. These codes are cleared
 * whenever the path is scanned and whenever the check_fn() callback
 * is changed.
 */
typedef enum {
  PCA_F_ENIGMA='?', /* The file remains to be checked */
  PCA_F_WANTED='+', /* The file has been selected by the caller's callback */
  PCA_F_IGNORE='-'  /* The file has been rejected by the caller's callback */
} PcaFileStatus;

/*
 * Encapsulate the memory management objects which supply memoy for
 * the arrays of filenames.
 */
typedef struct {
  StringGroup *sg;       /* The memory used to record the names of files */
  size_t files_dim;      /* The allocated size of files[] */
  char **files;          /* Memory for 'files_dim' pointers to files */
  size_t nfiles;         /* The number of filenames currently in files[] */
} CacheMem;

static CacheMem *new_CacheMem(void);
static CacheMem *del_CacheMem(CacheMem *cm);
static void rst_CacheMem(CacheMem *cm);

/*
 * Lists of nodes of the following type are used to record the
 * names and contents of individual directories.
 */
typedef struct PathNode PathNode;
struct PathNode {
  PathNode *next;   /* The next directory in the path */
  int relative;     /* True if the directory is a relative pathname */
  CacheMem *mem;    /* The memory used to store dir[] and files[] */
  char *dir;        /* The directory pathname (stored in pc->sg) */
  int nfile;        /* The number of filenames stored in 'files' */
  char **files;     /* Files of interest in the current directory, */
                    /*  or NULL if dir[] is a relative pathname */
                    /*  who's contents can't be cached. This array */
                    /*  and its contents are taken from pc->abs_mem */
                    /*  or pc->rel_mem */
};

/*
 * Append a new node to the list of directories in the path.
 */
static int add_PathNode(PathCache *pc, const char *dirname);

/*
 * Set the maximum length allowed for usernames.
 * names.
 */
#define USR_LEN 100

/*
 * PathCache objects encapsulate the resources needed to record
 * files of interest from comma-separated lists of directories.
 */
struct PathCache {
  ErrMsg *err;           /* The error reporting buffer */
  FreeList *node_mem;    /* A free-list of PathNode objects */
  CacheMem *abs_mem;     /* Memory for the filenames of absolute paths */
  CacheMem *rel_mem;     /* Memory for the filenames of relative paths */
  PathNode *head;        /* The head of the list of directories in the */
                         /*  path, or NULL if no path has been scanned yet. */
  PathNode *tail;        /* The tail of the list of directories in the */
                         /*  path, or NULL if no path has been scanned yet. */
  PathName *path;        /* The fully qualified name of a file */
  HomeDir *home;         /* Home-directory lookup object */
  DirReader *dr;         /* A portable directory reader */
  CplFileConf *cfc;      /* Configuration parameters to pass to */
                         /*  cpl_file_completions() */
  CplCheckFn *check_fn;  /* The callback used to determine if a given */
                         /*  filename should be recorded in the cache. */
  void *data;            /* Annonymous data to be passed to pc->check_fn() */
  char usrnam[USR_LEN+1];/* The buffer used when reading the names of */
                         /*  users. */
};

/*
 * Empty the cache.
 */
static void pca_clear_cache(PathCache *pc);

/*
 * Read a username from string[] and record it in pc->usrnam[].
 */
static int pca_read_username(PathCache *pc, const char *string, int slen,
			     int literal, const char **nextp);

/*
 * Extract the next component of a colon separated list of directory
 * paths.
 */
static int pca_extract_dir(PathCache *pc, const char *path,
			   const char **nextp);

/*
 * Scan absolute directories for files of interest, recording their names
 * in mem->sg and recording pointers to these names in mem->files[].
 */
static int pca_scan_dir(PathCache *pc, const char *dirname, CacheMem *mem);

/*
 * A qsort() comparison function for comparing the cached filename
 * strings pointed to by two (char **) array elements. Note that
 * this ignores the initial cache-status byte of each filename.
 */
static int pca_cmp_matches(const void *v1, const void *v2);

/*
 * A qsort() comparison function for comparing a filename
 * against an element of an array of pointers to filename cache
 * entries.
 */
static int pca_cmp_file(const void *v1, const void *v2);

/*
 * Initialize a PcaPathConf configuration objects with the default
 * options.
 */
static int pca_init_PcaPathConf(PcaPathConf *ppc, PathCache *pc);

/*
 * Make a copy of a completion suffix, suitable for passing to
 * cpl_add_completion().
 */
static int pca_prepare_suffix(PathCache *pc, const char *suffix,
			      int add_escapes);

/*
 * Return non-zero if the specified string appears to start with a pathname.
 */
static int cpa_cmd_contains_path(const char *prefix, int prefix_len);

/*
 * Return a given prefix with escapes optionally removed.
 */
static const char *pca_prepare_prefix(PathCache *pc, const char *prefix,
				      size_t prefix_len, int escaped);

/*
 * If there is a tilde expression at the beginning of the specified path,
 * place the corresponding home directory into pc->path. Otherwise
 * just clear pc->path.
 */
static int pca_expand_tilde(PathCache *pc, const char *path, int pathlen,
			    int literal, const char **endp);

/*
 * Clear the filename status codes that are recorded before each filename
 * in the cache.
 */
static void pca_remove_marks(PathCache *pc);

/*
 * Specify how many PathNode's to allocate at a time.
 */
#define PATH_NODE_BLK 30

/*
 * Specify the amount by which the files[] arrays are to be extended
 * whenever they are found to be too small.
 */
#define FILES_BLK_FACT 256

/*.......................................................................
 * Create a new object who's function is to maintain a cache of
 * filenames found within a list of directories, and provide quick
 * lookup and completion of selected files in this cache.
 *
 * Output:
 *  return     PathCache *  The new, initially empty cache, or NULL
 *                          on error.
 */
PathCache *new_PathCache(void)
{
  PathCache *pc;  /* The object to be returned */
/*
 * Allocate the container.
 */
  pc = (PathCache *)malloc(sizeof(PathCache));
  if(!pc) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_PathCache().
 */
  pc->err = NULL;
  pc->node_mem = NULL;
  pc->abs_mem = NULL;
  pc->rel_mem = NULL;
  pc->head = NULL;
  pc->tail = NULL;
  pc->path = NULL;
  pc->home = NULL;
  pc->dr = NULL;
  pc->cfc = NULL;
  pc->check_fn = 0;
  pc->data = NULL;
  pc->usrnam[0] = '\0';
/*
 * Allocate a place to record error messages.
 */
  pc->err = _new_ErrMsg();
  if(!pc->err)
    return del_PathCache(pc);
/*
 * Allocate the freelist of directory list nodes.
 */
  pc->node_mem = _new_FreeList(sizeof(PathNode), PATH_NODE_BLK);
  if(!pc->node_mem)
    return del_PathCache(pc);
/*
 * Allocate memory for recording names of files in absolute paths.
 */
  pc->abs_mem = new_CacheMem();
  if(!pc->abs_mem)
    return del_PathCache(pc);
/*
 * Allocate memory for recording names of files in relative paths.
 */
  pc->rel_mem = new_CacheMem();
  if(!pc->rel_mem)
    return del_PathCache(pc);
/*
 * Allocate a pathname buffer.
 */
  pc->path = _new_PathName();
  if(!pc->path)
    return del_PathCache(pc);
/*
 * Allocate an object for looking up home-directories.
 */
  pc->home = _new_HomeDir();
  if(!pc->home)
    return del_PathCache(pc);
/*
 * Allocate an object for reading directories.
 */
  pc->dr = _new_DirReader();
  if(!pc->dr)
    return del_PathCache(pc);
/*
 * Allocate a cpl_file_completions() configuration object.
 */
  pc->cfc = new_CplFileConf();
  if(!pc->cfc)
    return del_PathCache(pc);
/*
 * Configure cpl_file_completions() to use check_fn() to select
 * files of interest.
 */
  cfc_set_check_fn(pc->cfc, pc->check_fn, pc->data);
/*
 * Return the cache, ready for use.
 */
  return pc;
}

/*.......................................................................
 * Delete a given cache of files, returning the resources that it
 * was using to the system.
 *
 * Input:
 *  pc      PathCache *  The cache to be deleted (can be NULL).
 * Output:
 *  return  PathCache *  The deleted object (ie. allways NULL).
 */
PathCache *del_PathCache(PathCache *pc)
{
  if(pc) {
/*
 * Delete the error message buffer.
 */
    pc->err = _del_ErrMsg(pc->err);
/*
 * Delete the memory of the list of path nodes.
 */
    pc->node_mem = _del_FreeList(pc->node_mem, 1);
/*
 * Delete the memory used to record filenames.
 */
    pc->abs_mem = del_CacheMem(pc->abs_mem);
    pc->rel_mem = del_CacheMem(pc->rel_mem);
/*
 * The list of PathNode's was already deleted when node_mem was
 * deleted.
 */
    pc->head = NULL;
    pc->tail = NULL;
/*
 * Delete the pathname buffer.
 */
    pc->path = _del_PathName(pc->path);
/*
 * Delete the home-directory lookup object.
 */
    pc->home = _del_HomeDir(pc->home);
/*
 * Delete the directory reader.
 */
    pc->dr = _del_DirReader(pc->dr);
/*
 * Delete the cpl_file_completions() config object.
 */
    pc->cfc = del_CplFileConf(pc->cfc);
/*
 * Delete the container.
 */
    free(pc);
  };
  return NULL;
}

/*.......................................................................
 * If you want subsequent calls to pca_lookup_file() and
 * pca_path_completions() to only return the filenames of certain
 * types of files, for example executables, or filenames ending in
 * ".ps", call this function to register a file-selection callback
 * function. This callback function takes the full pathname of a file,
 * plus application-specific data, and returns 1 if the file is of
 * interest, and zero otherwise.
 *
 * Input:
 *  pc         PathCache *  The filename cache.
 *  check_fn  CplCheckFn *  The function to call to see if the name of
 *                          a given file should be included in the
 *                          cache. This determines what type of files
 *                          will reside in the cache. To revert to
 *                          selecting all files, regardless of type,
 *                          pass 0 here.
 *  data            void *  You can pass a pointer to anything you
 *                          like here, including NULL. It will be
 *                          passed to your check_fn() callback
 *                          function, for its private use.
 */
void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, void *data)
{
  if(pc) {
/*
 * If the callback or its data pointer have changed, clear the cached
 * statuses of files that were accepted or rejected by the previous
 * calback.
 */
    if(check_fn != pc->check_fn || data != pc->data)
      pca_remove_marks(pc);
/*
 * Record the new callback locally.
 */
    pc->check_fn = check_fn;
    pc->data = data;
/*
 * Configure cpl_file_completions() to use the same callback to
 * select files of interest.
 */
    cfc_set_check_fn(pc->cfc, check_fn, data);
  };
  return;
}

/*.......................................................................
 * Return a description of the last path-caching error that occurred.
 *
 * Input:
 *  pc     PathCache *   The filename cache that suffered the error.
 * Output:
 *  return      char *   The description of the last error.
 */
const char *pca_last_error(PathCache *pc)
{
  return pc ? _err_get_msg(pc->err) : "NULL PathCache argument";
}

/*.......................................................................
 * Discard all cached filenames.
 *
 * Input:
 *  pc   PathCache *  The cache to be cleared.
 */
static void pca_clear_cache(PathCache *pc)
{
  if(pc) {
/*
 * Return all path-nodes to the freelist.
 */
    _rst_FreeList(pc->node_mem);
    pc->head = pc->tail = NULL;
/*
 * Delete all filename strings.
 */
    rst_CacheMem(pc->abs_mem);
    rst_CacheMem(pc->rel_mem);
  };
  return;
}

/*.......................................................................
 * Build the list of files of interest contained in a given
 * colon-separated list of directories.
 *
 * Input:
 *  pc         PathCache *  The cache in which to store the names of
 *                          the files that are found in the list of
 *                          directories.
 *  path      const char *  A colon-separated list of directory
 *                          paths. Under UNIX, when searching for
 *                          executables, this should be the return
 *                          value of getenv("PATH").
 * Output:
 *  return           int    0 - OK.
 *                          1 - An error occurred. A description of
 *                              the error can be acquired by calling
 *                              pca_last_error(pc).
 */
int pca_scan_path(PathCache *pc, const char *path)
{
  const char *pptr; /* A pointer to the next unprocessed character in path[] */
  PathNode *node;   /* A node in the list of directory paths */
  char **fptr;      /* A pointer into pc->abs_mem->files[] */
/*
 * Check the arguments.
 */
  if(!pc)
    return 1;
/*
 * Clear the outdated contents of the cache.
 */
  pca_clear_cache(pc);
/*
 * If no path list was provided, there is nothing to be added to the
 * cache.
 */
  if(!path)
    return 0;
/*
 * Extract directories from the path list, expanding tilde expressions
 * on the fly into pc->pathname, then add them to the list of path
 * nodes, along with a sorted list of the filenames of interest that
 * the directories hold.
 */
  pptr = path;
  while(*pptr) {
/*
 * Extract the next pathname component into pc->path->name.
 */
    if(pca_extract_dir(pc, pptr, &pptr))
      return 1;
/*
 * Add a new node to the list of paths, containing both the
 * directory name and, if not a relative pathname, the list of
 * files of interest in the directory.
 */
    if(add_PathNode(pc, pc->path->name))
      return 1;
  };
/*
 * The file arrays in each absolute directory node are sections of
 * pc->abs_mem->files[]. Record pointers to the starts of each
 * of these sections in each directory node. Note that this couldn't
 * be done in add_PathNode(), because pc->abs_mem->files[] may
 * get reallocated in subsequent calls to add_PathNode(), thus
 * invalidating any pointers to it.
 */
  fptr = pc->abs_mem->files;
  for(node=pc->head; node; node=node->next) {
    node->files = fptr;
    fptr += node->nfile;
  };
  return 0;
}

/*.......................................................................
 * Extract the next directory path from a colon-separated list of
 * directories, expanding tilde home-directory expressions where needed.
 *
 * Input:
 *  pc      PathCache *   The cache of filenames.
 *  path   const char *   A pointer to the start of the next component
 *                        in the path list.
 * Input/Output:
 *  nextp  const char **  A pointer to the next unprocessed character
 *                        in path[] will be assigned to *nextp.
 * Output:
 *  return        int     0 - OK. The extracted path is in pc->path->name.
 *                        1 - Error. A description of the error will
 *                            have been left in pc->err.
 */
static int pca_extract_dir(PathCache *pc, const char *path, const char **nextp)
{
  const char *pptr;         /* A pointer into path[] */
  const char *sptr;         /* The path following tilde expansion */
  int escaped = 0;          /* True if the last character was a backslash */
/*
 * If there is a tilde expression at the beginning of the specified path,
 * place the corresponding home directory into pc->path. Otherwise
 * just clear pc->path.
 */
  if(pca_expand_tilde(pc, path, strlen(path), 0, &pptr))
    return 1;
/*
 * Keep a record of the current location in the path.
 */
  sptr = pptr;
/*
 * Locate the end of the directory name in the pathname string, stopping
 * when either the end of the string is reached, or an un-escaped colon
 * separator is seen.
 */
  while(*pptr && (escaped || *pptr != ':'))
    escaped = !escaped && *pptr++ == '\\';
/*
 * Append the rest of the directory path to the pathname buffer.
 */
  if(_pn_append_to_path(pc->path, sptr, pptr - sptr, 1) == NULL) {
    _err_record_msg(pc->err, "Insufficient memory to record directory name",
		    END_ERR_MSG);
    return 1;
  };
/*
 * To facilitate subsequently appending filenames to the directory
 * path name, make sure that the recorded directory name ends in a
 * directory separator.
 */
  {
    int dirlen = strlen(pc->path->name);
    if(dirlen < FS_DIR_SEP_LEN ||
       strncmp(pc->path->name + dirlen - FS_DIR_SEP_LEN, FS_DIR_SEP,
	       FS_DIR_SEP_LEN) != 0) {
      if(_pn_append_to_path(pc->path, FS_DIR_SEP, FS_DIR_SEP_LEN, 0) == NULL) {
	_err_record_msg(pc->err, "Insufficient memory to record directory name",
			END_ERR_MSG);
	return 1;
      };
    };
  };
/*
 * Skip the separator unless we have reached the end of the path.
 */
  if(*pptr==':')
    pptr++;
/*
 * Return the unprocessed tail of the path-list string.
 */
  *nextp = pptr;
  return 0;
}

/*.......................................................................
 * Read a username, stopping when a directory separator is seen, a colon
 * separator is seen, the end of the string is reached, or the username
 * buffer overflows.
 *
 * Input:
 *  pc   PathCache *   The cache of filenames.
 *  string    char *   The string who's prefix contains the name.
 *  slen       int     The max number of characters to read from string[].
 *  literal    int     If true, treat backslashes as literal characters
 *                     instead of escapes.
 * Input/Output:
 *  nextp     char **  A pointer to the next unprocessed character
 *                     in string[] will be assigned to *nextp.
 * Output:
 *  return     int     0 - OK. The username can be found in pc->usrnam.
 *                     1 - Error. A description of the error message
 *                         can be found in pc->err.
 */
static int pca_read_username(PathCache *pc, const char *string, int slen,
			     int literal, const char **nextp)
{
  int usrlen;         /* The number of characters in pc->usrnam[] */
  const char *sptr;   /* A pointer into string[] */
  int escaped = 0;    /* True if the last character was a backslash */
/*
 * Extract the username.
 */
  for(sptr=string,usrlen=0; usrlen < USR_LEN && (sptr-string) < slen; sptr++) {
/*
 * Stop if the end of the string is reached, or a directory separator
 * or un-escaped colon separator is seen.
 */
    if(!*sptr || strncmp(sptr, FS_DIR_SEP, FS_DIR_SEP_LEN)==0 ||
       (!escaped && *sptr == ':'))
      break;
/*
 * Escape the next character?
 */
    if(!literal && !escaped && *sptr == '\\') {
      escaped = 1;
    } else {
      escaped = 0;
      pc->usrnam[usrlen++] = *sptr;
    };
  };
/*
 * Did the username overflow the buffer?
 */
  if(usrlen >= USR_LEN) {
    _err_record_msg(pc->err, "Username too long", END_ERR_MSG);
    return 1;
  };
/*
 * Terminate the string.
 */
  pc->usrnam[usrlen] = '\0';
/*
 * Indicate where processing of the input string should continue.
 */
  *nextp = sptr;
  return 0;
}


/*.......................................................................
 * Create a new CacheMem object.
 *
 * Output:
 *  return  CacheMem *  The new object, or NULL on error.
 */
static CacheMem *new_CacheMem(void)
{
  CacheMem *cm;  /* The object to be returned */
/*
 * Allocate the container.
 */
  cm = (CacheMem *)malloc(sizeof(CacheMem));
  if(!cm) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_CacheMem().
 */
  cm->sg = NULL;
  cm->files_dim = 0;
  cm->files = NULL;
  cm->nfiles = 0;
/*
 * Allocate a list of string segments for storing filenames.
 */
  cm->sg = _new_StringGroup(_pu_pathname_dim());
  if(!cm->sg)
    return del_CacheMem(cm);
/*
 * Allocate an array of pointers to filenames.
 * This will be extended later if needed.
 */
  cm->files_dim = FILES_BLK_FACT;
  cm->files = (char **) malloc(sizeof(*cm->files) * cm->files_dim);
  if(!cm->files) {
    errno = ENOMEM;
    return del_CacheMem(cm);
  };
  return cm;
}

/*.......................................................................
 * Delete a CacheMem object.
 *
 * Input:
 *  cm   CacheMem *  The object to be deleted.
 * Output:
 *  return CacheMem *  The deleted object (always NULL).
 */
static CacheMem *del_CacheMem(CacheMem *cm)
{
  if(cm) {
/*
 * Delete the memory that was used to record filename strings.
 */
    cm->sg = _del_StringGroup(cm->sg);
/*
 * Delete the array of pointers to filenames.
 */
    cm->files_dim = 0;
    if(cm->files) {
      free(cm->files);
      cm->files = NULL;
    };
/*
 * Delete the container.
 */
    free(cm);
  };
  return NULL;
}

/*.......................................................................
 * Re-initialize the memory used to allocate filename strings.
 *
 * Input:
 *  cm     CacheMem *  The memory cache to be cleared.
 */
static void rst_CacheMem(CacheMem *cm)
{
  _clr_StringGroup(cm->sg);
  cm->nfiles = 0;
  return;
}

/*.......................................................................
 * Append a new directory node to the list of directories read from the
 * path.
 *
 * Input:
 *  pc        PathCache *  The filename cache.
 *  dirname  const char *  The name of the new directory.
 * Output:
 *  return          int    0 - OK.
 *                         1 - Error.
 */
static int add_PathNode(PathCache *pc, const char *dirname)
{
  PathNode *node;  /* The new directory list node */
  int relative;    /* True if dirname[] is a relative pathname */
/*
 * Have we been passed a relative pathname or an absolute pathname?
 */
  relative = strncmp(dirname, FS_ROOT_DIR, FS_ROOT_DIR_LEN) != 0;
/*
 * If it's an absolute pathname, ignore it if the corresponding
 * directory doesn't exist.
 */
  if(!relative && !_pu_path_is_dir(dirname))
    return 0;
/*
 * Allocate a new list node to record the specifics of the new directory.
 */
  node = (PathNode *) _new_FreeListNode(pc->node_mem);
  if(!node) {
    _err_record_msg(pc->err, "Insufficient memory to cache new directory.",
		    END_ERR_MSG);
    return 1;
  };
/*
 * Initialize the node.
 */
  node->next = NULL;
  node->relative = relative;
  node->mem = relative ? pc->rel_mem : pc->abs_mem;
  node->dir = NULL;
  node->nfile = 0;
  node->files = NULL;
/*
 * Make a copy of the directory pathname.
 */
  node->dir = _sg_store_string(pc->abs_mem->sg, dirname, 0);
  if(!node->dir) {
    _err_record_msg(pc->err, "Insufficient memory to store directory name.",
		    END_ERR_MSG);
    return 1;
  };
/*
 * Scan absolute directories for files of interest, recording their names
 * in node->mem->sg and appending pointers to these names to the
 * node->mem->files[] array.
 */
  if(!node->relative) {
    int nfile = node->nfile = pca_scan_dir(pc, node->dir, node->mem);
    if(nfile < 1) {  /* No files matched or an error occurred */
      node = (PathNode *) _del_FreeListNode(pc->node_mem, node);
      return nfile < 0;
    };
  };
/*
 * Append the new node to the list.
 */
  if(pc->head) {
    pc->tail->next = node;
    pc->tail = node;
  } else {
    pc->head = pc->tail = node;
  };
  return 0;
}

/*.......................................................................
 * Scan a given directory for files of interest, record their names
 * in mem->sg and append pointers to them to the mem->files[] array.
 *
 * Input:
 *  pc        PathCache *  The filename cache.
 *  dirname  const char *  The pathname of the directory to be scanned.
 *  mem        CacheMem *  The memory in which to store filenames of
 *                         interest.
 * Output:
 *  return          int    The number of files recorded, or -1 if a
 *                         memory error occurs. Note that the
 *                         inability to read the contents of the
 *                         directory is not counted as an error.
 */
static int pca_scan_dir(PathCache *pc, const char *dirname, CacheMem *mem)
{
  int nfile = 0;        /* The number of filenames recorded */
  const char *filename; /* The name of the file being looked at */
/*
 * Attempt to open the directory. If the directory can't be read then
 * there are no accessible files of interest in the directory.
 */
  if(_dr_open_dir(pc->dr, dirname, NULL))
    return 0;
/*
 * Record the names of all files in the directory in the cache.
 */
  while((filename = _dr_next_file(pc->dr))) {
    char *copy;        /* A copy of the filename */
/*
 * Make a temporary copy of the filename with an extra byte prepended.
 */
    _pn_clear_path(pc->path);
    if(_pn_append_to_path(pc->path, " ", 1, 0) == NULL ||
       _pn_append_to_path(pc->path, filename, -1, 1) == NULL) {
      _err_record_msg(pc->err, "Insufficient memory to record filename",
		      END_ERR_MSG);
      return -1;
    };
/*
 * Store the filename.
 */
    copy = _sg_store_string(mem->sg, pc->path->name, 0);
    if(!copy) {
      _err_record_msg(pc->err, "Insufficient memory to cache file name.",
		      END_ERR_MSG);
      return -1;
    };
/*
 * Mark the filename as unchecked.
 */
    copy[0] = PCA_F_ENIGMA;
/*
 * Make room to store a pointer to the copy in mem->files[].
 */
    if(mem->nfiles + 1 > mem->files_dim) {
      int needed = mem->files_dim + FILES_BLK_FACT;
      char **files = (char **) realloc(mem->files, sizeof(*mem->files)*needed);
      if(!files) {
	_err_record_msg(pc->err,
			"Insufficient memory to extend filename cache.",
			END_ERR_MSG);
	return 1;
      };
      mem->files = files;
      mem->files_dim = needed;
    };
/*
 * Record a pointer to the copy of the filename at the end of the files[]
 * array.
 */
    mem->files[mem->nfiles++] = copy;
/*
 * Keep a record of the number of files matched so far.
 */
    nfile++;
  };
/*
 * Sort the list of files into lexical order.
 */
  qsort(mem->files + mem->nfiles - nfile, nfile, sizeof(*mem->files),
	pca_cmp_matches);
/*
 * Return the number of files recorded in mem->files[].
 */
  return nfile;
}

/*.......................................................................
 * A qsort() comparison function for comparing the cached filename
 * strings pointed to by two (char **) array elements. Note that
 * this ignores the initial cache-status byte of each filename.
 *
 * Input:
 *  v1, v2   void *  Pointers to the pointers of two strings to be compared.
 * Output:
 *  return    int    -1 -> v1 < v2.
 *                    0 -> v1 == v2
 *                    1 -> v1 > v2
 */
static int pca_cmp_matches(const void *v1, const void *v2)
{
  const char **s1 = (const char **) v1;
  const char **s2 = (const char **) v2;
  return strcmp(*s1+1, *s2+1);
}

/*.......................................................................
 * Given the simple name of a file, search the cached list of files
 * in the order in which they where found in the list of directories
 * previously presented to pca_scan_path(), and return the pathname
 * of the first file which has this name. If a pathname to a file is
 * given instead of a simple filename, this is returned without being
 * looked up in the cache, but with any initial ~username expression
 * expanded, and optionally, unescaped backslashes removed.
 *
 * Input:
 *  pc     PathCache *  The cached list of files.
 *  name  const char *  The name of the file to lookup.
 *  name_len     int    The length of the filename string at the
 *                      beginning of name[], or -1 to indicate that
 *                      the filename occupies the whole of the
 *                      string.
 *  literal      int    If this argument is zero, lone backslashes
 *                      in name[] are ignored during comparison
 *                      with filenames in the cache, under the
 *                      assumption that they were in the input line
 *                      soley to escape the special significance of
 *                      characters like spaces. To have them treated
 *                      as normal characters, give this argument a
 *                      non-zero value, such as 1.
 * Output:
 *  return      char *  The pathname of the first matching file,
 *                      or NULL if not found. Note that the returned
 *                      pointer points to memory owned by *pc, and
 *                      will become invalid on the next call to any
 *                      function in the PathCache module.
 */
char *pca_lookup_file(PathCache *pc, const char *name, int name_len,
		      int literal)
{
  PathNode *node;   /* A node in the list of directories in the path */
  char **match;     /* A pointer to a matching filename string in the cache */
/*
 * Check the arguments.
 */
  if(!pc || !name || name_len==0)
    return NULL;
/*
 * If no length was specified, determine the length of the string to
 * be looked up.
 */
  if(name_len < 0)
    name_len = strlen(name);
/*
 * If the word starts with a ~username expression, the root directory,
 * of it contains any directory separators, then treat it isn't a simple
 * filename that can be looked up in the cache, but rather appears to
 * be the pathname of a file. If so, return a copy of this pathname with
 * escapes removed, if requested, and any initial ~username expression
 * expanded.
 */
  if(cpa_cmd_contains_path(name, name_len)) {
    const char *nptr;
    if(pca_expand_tilde(pc, name, name_len, literal, &nptr) ||
       _pn_append_to_path(pc->path, nptr, name_len - (nptr-name),
			  !literal) == NULL)
      return NULL;
    return pc->path->name;
  };
/*
 * Look up the specified filename in each of the directories of the path,
 * in the same order that they were listed in the path, and stop as soon
 * as an instance of the file is found.
 */
  for(node=pc->head; node; node=node->next) {
/*
 * If the directory of the latest node is a relative pathname,
 * scan it for files of interest.
 */
    if(node->relative) {
      rst_CacheMem(node->mem);
      if(pca_scan_dir(pc, node->dir, node->mem) < 1)
	continue;
      node->files = node->mem->files;
      node->nfile = node->mem->nfiles;
    };
/*
 * Copy the filename into a temporary buffer, while interpretting
 * escape characters if needed.
 */
    _pn_clear_path(pc->path);
    if(_pn_append_to_path(pc->path, name, name_len, !literal) == NULL)
      return NULL;
/*
 * Perform a binary search for the requested filename.
 */
    match = (char **)bsearch(pc->path->name, node->files, node->nfile,
		             sizeof(*node->files), pca_cmp_file);
    if(match) {
/*
 * Prepend the pathname in which the directory was found, which we have
 * guaranteed to end in a directory separator, to the located filename.
 */
      if(_pn_prepend_to_path(pc->path, node->dir, -1, 0) == NULL)
	return NULL;
/*
 * Return the matching pathname unless it is rejected by the application.
 */
      if(!pc->check_fn || (*match)[0] == PCA_F_WANTED ||
	 ((*match)[0]==PCA_F_ENIGMA && pc->check_fn(pc->data, pc->path->name))){
	(*match)[0] = PCA_F_WANTED;
	return pc->path->name;
      } else {
	*(match)[0] = PCA_F_IGNORE;
      };
    };
  };
/*
 * File not found.
 */
  return NULL;
}

/*.......................................................................
 * A qsort() comparison function for comparing a filename string to
 * a cached filename string pointed to by a (char **) array element.
 * This ignores the initial code byte at the start of the cached filename
 * string.
 *
 * Input:
 *  v1, v2   void *  Pointers to the pointers of two strings to be compared.
 * Output:
 *  return    int    -1 -> v1 < v2.
 *                    0 -> v1 == v2
 *                    1 -> v1 > v2
 */
static int pca_cmp_file(const void *v1, const void *v2)
{
  const char *file_name = (const char *) v1;
  const char **cache_name = (const char **) v2;
  return strcmp(file_name, *cache_name + 1);
}

/*.......................................................................
 * The PcaPathConf structure may have options added to it in the future.
 * To allow your application to be linked against a shared version of the
 * tecla library, without these additions causing your application to
 * crash, you should use new_PcaPathConf() to allocate such structures.
 * This will set all of the configuration options to their default values,
 * which you can then change before passing the structure to
 * pca_path_completions().
 *
 * Input:
 *  pc         PathCache *  The filename cache in which to look for
 *                          file name completions.
 * Output:
 *  return   PcaPathConf *  The new configuration structure, or NULL
 *                          on error. A descripition of the error
 *                          can be found by calling pca_last_error(pc).
 */
PcaPathConf *new_PcaPathConf(PathCache *pc)
{
  PcaPathConf *ppc;  /* The object to be returned */
/*
 * Check the arguments.
 */
  if(!pc)
    return NULL;
/*
 * Allocate the container.
 */
  ppc = (PcaPathConf *)malloc(sizeof(PcaPathConf));
  if(!ppc) {
    _err_record_msg(pc->err, "Insufficient memory.", END_ERR_MSG);
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to del_PcaPathConf().
 */
  if(pca_init_PcaPathConf(ppc, pc))
    return del_PcaPathConf(ppc);
  return ppc;
}

/*.......................................................................
 * Initialize a PcaPathConf configuration structure with defaults.
 *
 * Input:
 *  ppc   PcaPathConf *  The structre to be initialized.
 *  pc      PathCache *  The cache in which completions will be looked up.
 * Output:
 *  return        int    0 - OK.
 *                       1 - Error. A description of the error can be
 *                           obtained by calling pca_last_error(pc).
 */
static int pca_init_PcaPathConf(PcaPathConf *ppc, PathCache *pc)
{
/*
 * Check the arguments.
 */
  if(!pc)
    return 1;
/*
 * Set the default options.
 */
  ppc->id = PPC_ID_CODE;
  ppc->pc = pc;
  ppc->escaped = 1;
  ppc->file_start = -1;
  return 0;
}

/*.......................................................................
 * Delete a PcaPathConf object.
 *
 * Input:
 *  ppc    PcaPathConf *  The object to be deleted.
 * Output:
 *  return PcaPathConf *  The deleted object (always NULL).
 */
PcaPathConf *del_PcaPathConf(PcaPathConf *ppc)
{
  if(ppc) {
    ppc->pc = NULL;  /* It is up to the caller to delete the cache */
/*
 * Delete the container.
 */
    free(ppc);
  };
  return NULL;
}

/*.......................................................................
 * pca_path_completions() is a completion callback function for use
 * directly with cpl_complete_word() or gl_customize_completions(), or
 * indirectly from your own completion callback function. It requires
 * that a CpaPathArgs object be passed via its 'void *data' argument.
 */
CPL_MATCH_FN(pca_path_completions)
{
  PcaPathConf *ppc;       /* The configuration arguments */
  PathCache *pc;          /* The cache in which to look for completions */
  PathNode *node;         /* A node in the list of directories in the path */
  const char *filename;   /* The name of the file being looked at */
  const char *start_path; /* The pointer to the start of the pathname */
                          /*  in line[]. */
  int word_start;         /* The index in line[] corresponding to start_path */
  const char *prefix;     /* The file-name prefix being searched for */
  size_t prefix_len;      /* The length of the prefix being completed */
  int bot;                /* The lowest index of the array not searched yet */
  int top;                /* The highest index of the array not searched yet */
/*
 * Check the arguments.
 */
  if(!cpl)
    return 1;
  if(!line || word_end < 0 || !data) {
    cpl_record_error(cpl, "pca_path_completions: Invalid arguments.");
    return 1;
  };
/*
 * Get the configuration arguments.
 */
  ppc = (PcaPathConf *) data;
/*
 * Check that the callback data is a PcaPathConf structure returned
 * by new_PcaPathConf().
 */
  if(ppc->id != PPC_ID_CODE) {
    cpl_record_error(cpl,
		     "Invalid callback data passed to pca_path_completions()");
    return 1;
  };
/*
 * Get the filename cache.
 */
  pc = ppc->pc;
/*
 * Get the start of the file name. If not specified by the caller,
 * identify it by searching backwards in the input line for an
 * unescaped space or the start of the line.
 */
  if(ppc->file_start < 0) {
    start_path = _pu_start_of_path(line, word_end);
    if(!start_path) {
      cpl_record_error(cpl, "Unable to find the start of the file name.");
      return 1;
    };
  } else {
    start_path = line + ppc->file_start;
  };
/*
 * Get the index of the start of the word being completed.
 */
  word_start = start_path - line;
/*
 * Work out the length of the prefix that is bein completed.
 */
  prefix_len = word_end - word_start;
/*
 * If the word starts with a ~username expression or the root directory,
 * of it contains any directory separators, then completion must be
 * delegated to cpl_file_completions().
 */
  if(cpa_cmd_contains_path(start_path, prefix_len)) {
    cfc_file_start(pc->cfc, word_start);
    return cpl_file_completions(cpl, pc->cfc, line, word_end);
  };
/*
 * Look up the specified file name in each of the directories of the path,
 * in the same order that they were listed in the path, and stop as soon
 * as an instance of the file is found.
 */
  for(node=pc->head; node; node=node->next) {
/*
 * If the directory of the latest node is a relative pathname,
 * scan it for files of interest.
 */
    if(node->relative) {
      rst_CacheMem(node->mem);
      if(pca_scan_dir(pc, node->dir, node->mem) < 1)
	continue;
      node->files = node->mem->files;
      node->nfile = node->mem->nfiles;
    };
/*
 * If needed, make a copy of the file-name being matched, with
 * escapes removed. Note that we need to do this anew every loop
 * iteration, because the above call to pca_scan_dir() uses
 * pc->path.
 */
    prefix = pca_prepare_prefix(pc, start_path, prefix_len, ppc->escaped);
    if(!prefix)
      return 1;
/*
 * The directory entries are sorted, so we can perform a binary
 * search for an instance of the prefix being searched for.
 */
    bot = 0;
    top = node->nfile - 1;
    while(top >= bot) {
      int mid = (top + bot)/2;
      int test = strncmp(node->files[mid]+1, prefix, prefix_len);
      if(test > 0)
	top = mid - 1;
      else if(test < 0)
	bot = mid + 1;
      else {
	top = bot = mid;
	break;
      };
    };
/*
 * If we found a match, look to see if any of its neigbors also match.
 */
    if(top == bot) {
      while(--bot >= 0 && strncmp(node->files[bot]+1, prefix, prefix_len) == 0)
	;
      while(++top < node->nfile &&
	    strncmp(node->files[top]+1, prefix, prefix_len) == 0)
	;
/*
 * We will have gone one too far in each direction.
 */
      bot++;
      top--;
/*
 * Add the completions to the list after checking them against the
 * callers requirements.
 */
      for( ; bot<=top; bot++) {
	char *match = node->files[bot];
/*
 * Form the full pathname of the file.
 */
	_pn_clear_path(pc->path);
	if(_pn_append_to_path(pc->path, node->dir, -1, 0) == NULL ||
	   _pn_append_to_path(pc->path, match+1, -1, 0) == NULL) {
	  _err_record_msg(pc->err, "Insufficient memory to complete file name",
			  END_ERR_MSG);
	  return 1;
	};
/*
 * Should the file be included in the list of completions?
 */
	if(!pc->check_fn || match[0] == PCA_F_WANTED ||
	   (match[0]==PCA_F_ENIGMA && pc->check_fn(pc->data, pc->path->name))) {
	  match[0] = PCA_F_WANTED;
/*
 * Copy the completion suffix into the work pathname pc->path->name,
 * adding backslash escapes if needed.
 */
	  if(pca_prepare_suffix(pc, match + 1 + prefix_len,
				ppc->escaped))
	    return 1;
/*
 * Record the completion.
 */
	  if(cpl_add_completion(cpl, line, word_start, word_end, pc->path->name,
				"", " "))
	    return 1;
/*
 * The file was rejected by the application.
 */
	} else {
	  match[0] = PCA_F_IGNORE;
	};
      };
    };
  };
/*
 * We now need to search for subdirectories of the current directory which
 * have matching prefixes. First, if needed, make a copy of the word being
 * matched, with escapes removed.
 */
  prefix = pca_prepare_prefix(pc, start_path, prefix_len, ppc->escaped);
  if(!prefix)
    return 1;
/*
 * Now open the current directory.
 */
  if(_dr_open_dir(pc->dr, FS_PWD, NULL))
    return 0;
/*
 * Scan the current directory for sub-directories whos names start with
 * the prefix that we are completing.
 */
  while((filename = _dr_next_file(pc->dr))) {
/*
 * Does the latest filename match the prefix, and is it a directory?
 */
    if(strncmp(filename, prefix, prefix_len) == 0 && _pu_path_is_dir(filename)){
/*
 * Record the completion.
 */
      if(pca_prepare_suffix(pc, filename + prefix_len, ppc->escaped) ||
	 cpl_add_completion(cpl, line, word_start, word_end, pc->path->name,
			    FS_DIR_SEP, FS_DIR_SEP))
	return 1;
/*
 * The prefix in pc->path->name will have been overwritten by
 * pca_prepare_suffix(). Restore it here.
 */
      prefix = pca_prepare_prefix(pc, start_path, prefix_len, ppc->escaped);
      if(!prefix)
	return 1;
    };
  };
  _dr_close_dir(pc->dr);
  return 0;
}

/*.......................................................................
 * Using the work buffer pc->path, make a suitably escaped copy of a
 * given completion suffix, ready to be passed to cpl_add_completion().
 *
 * Input:
 *  pc      PathCache *  The filename cache resource object.
 *  suffix       char *  The suffix to be copied.
 *  add_escapes   int    If true, escape special characters.
 * Output:
 *  return        int    0 - OK.
 *                       1 - Error.
 */
static int pca_prepare_suffix(PathCache *pc, const char *suffix,
			      int add_escapes)
{
  const char *sptr; /* A pointer into suffix[] */
  int nbsl;         /* The number of backslashes to add to the suffix */
  int i;
/*
 * How long is the suffix?
 */
  int suffix_len = strlen(suffix);
/*
 * Clear the work buffer.
 */
  _pn_clear_path(pc->path);
/*
 * Count the number of backslashes that will have to be added to
 * escape spaces, tabs, backslashes and wildcard characters.
 */
  nbsl = 0;
  if(add_escapes) {
    for(sptr = suffix; *sptr; sptr++) {
      switch(*sptr) {
      case ' ': case '\t': case '\\': case '*': case '?': case '[':
	nbsl++;
	break;
      };
    };
  };
/*
 * Arrange for the output path buffer to have sufficient room for the
 * both the suffix and any backslashes that have to be inserted.
 */
  if(_pn_resize_path(pc->path, suffix_len + nbsl) == NULL) {
    _err_record_msg(pc->err, "Insufficient memory to complete file name",
		    END_ERR_MSG);
    return 1;
  };
/*
 * If the suffix doesn't need any escapes, copy it directly into the
 * work buffer.
 */
  if(nbsl==0) {
    strlcpy(pc->path->name, suffix, pc->path->dim);
  } else {
/*
 * Make a copy with special characters escaped?
 */
    if(nbsl > 0) {
      const char *src = suffix;
      char *dst = pc->path->name;
      for(i=0; i<suffix_len; i++) {
	switch(*src) {
	case ' ': case '\t': case '\\': case '*': case '?': case '[':
	  *dst++ = '\\';
	};
	*dst++ = *src++;
      };
      *dst = '\0';
    };
  };
  return 0;
}

/*.......................................................................
 * Return non-zero if the specified string appears to start with a pathname.
 *
 * Input:
 *  prefix  const char *  The filename prefix to check.
 *  prefix_len     int    The length of the prefix.
 * Output:
 *  return         int    0 - Doesn't start with a path name.
 *                        1 - Does start with a path name.
 */
static int cpa_cmd_contains_path(const char *prefix, int prefix_len)
{
  int i;
/*
 * If the filename starts with a ~, then this implies a ~username
 * expression, which constitutes a pathname.
 */
  if(*prefix == '~')
    return 1;
/*
 * If the filename starts with the root directory, then it obviously
 * starts with a pathname.
 */
  if(prefix_len >= FS_ROOT_DIR_LEN &&
     strncmp(prefix, FS_ROOT_DIR, FS_ROOT_DIR_LEN) == 0)
    return 1;
/*
 * Search the prefix for directory separators, returning as soon as
 * any are found, since their presence indicates that the filename
 * starts with a pathname specification (valid or otherwise).
 */
  for(i=0; i<prefix_len; i++) {
    if(prefix_len - i >= FS_DIR_SEP_LEN &&
       strncmp(prefix + i, FS_DIR_SEP, FS_DIR_SEP_LEN) == 0)
      return 1;
  };
/*
 * The file name doesn't appear to start with a pathname specification.
 */
  return 0;
}

/*.......................................................................
 * If needed make a new copy of the prefix being matched, in pc->path->name,
 * but with escapes removed. If no escapes are to be removed, simply return
 * the original prefix string.
 *
 * Input:
 *  pc      PathCache *   The cache being searched.
 *  prefix const char *   The prefix to be processed.
 *  prefix_len size_t     The length of the prefix.
 *  escaped       int     If true, return a copy with escapes removed.
 * Output:
 *  return const char *   The prepared prefix, or NULL on error, in
 *                        which case an error message will have been
 *                        left in pc->err.
 */
static const char *pca_prepare_prefix(PathCache *pc, const char *prefix,
				      size_t prefix_len, int escaped)
{
/*
 * Make a copy with escapes removed?
 */
  if(escaped) {
    _pn_clear_path(pc->path);
    if(_pn_append_to_path(pc->path, prefix, prefix_len, 1) == NULL) {
      _err_record_msg(pc->err, "Insufficient memory to complete filename",
		      END_ERR_MSG);
      return NULL;
    };
    return pc->path->name;
  };
  return prefix;
}

/*.......................................................................
 * If backslashes in the filename should be treated as literal
 * characters, call the following function with literal=1. Otherwise
 * the default is to treat them as escape characters, used for escaping
 * spaces etc..
 *
 * Input:
 *  ppc    PcaPathConf *  The pca_path_completions() configuration object
 *                        to be configured.
 *  literal        int    Pass non-zero here to enable literal interpretation
 *                        of backslashes. Pass 0 to turn off literal
 *                        interpretation.
 */
void ppc_literal_escapes(PcaPathConf *ppc, int literal)
{
  if(ppc)
    ppc->escaped = !literal;
}

/*.......................................................................
 * Call this function if you know where the index at which the
 * filename prefix starts in the input line. Otherwise by default,
 * or if you specify start_index to be -1, the filename is taken
 * to start after the first unescaped space preceding the cursor,
 * or the start of the line, which ever comes first.
 *
 * Input:
 *  ppc    PcaPathConf *  The pca_path_completions() configuration object
 *                        to be configured.
 *  start_index    int    The index of the start of the filename in
 *                        the input line, or -1 to select the default.
 */
void ppc_file_start(PcaPathConf *ppc, int start_index)
{
  if(ppc)
    ppc->file_start = start_index;
}

/*.......................................................................
 * Expand any ~user expression found at the start of a path, leaving
 * either an empty string in pc->path if there is no ~user expression,
 * or the corresponding home directory.
 *
 * Input:
 *  pc     PathCache *  The filename cache.
 *  path  const char *  The path to expand.
 *  pathlen      int    The max number of characters to look at in path[].
 *  literal      int    If true, treat backslashes as literal characters
 *                      instead of escapes.
 * Input/Output:
 *  endp  const char *  A pointer to the next unprocessed character in
 *                      path[] will be assigned to *endp.
 * Output:
 *  return       int    0 - OK
 *                      1 - Error (a description will have been placed
 *                                 in pc->err).
 */
static int pca_expand_tilde(PathCache *pc, const char *path, int pathlen,
			    int literal, const char **endp)
{
  const char *pptr = path;  /* A pointer into path[] */
  const char *homedir=NULL; /* A home directory */
/*
 * Clear the pathname buffer.
 */
  _pn_clear_path(pc->path);
/*
 * If the first character is a tilde, then perform home-directory
 * interpolation.
 */
  if(*pptr == '~') {
/*
 * Skip the tilde character and attempt to read the username that follows
 * it, into pc->usrnam[].
 */
    if(pca_read_username(pc, ++pptr, pathlen-1, literal, &pptr))
      return 1;
/*
 * Attempt to lookup the home directory of the user.
 */
    homedir = _hd_lookup_home_dir(pc->home, pc->usrnam);
    if(!homedir) {
      _err_record_msg(pc->err, _hd_last_home_dir_error(pc->home), END_ERR_MSG);
      return 1;
    };
/*
 * Append the home directory to the pathname string.
 */
    if(_pn_append_to_path(pc->path, homedir, -1, 0) == NULL) {
      _err_record_msg(pc->err,
		      "Insufficient memory for home directory expansion",
		      END_ERR_MSG);
      return 1;
    };
  };
/*
 * ~user and ~ are usually followed by a directory separator to
 * separate them from the file contained in the home directory.
 * If the home directory is the root directory, then we don't want
 * to follow the home directory by a directory separator, so we should
 * skip over it so that it doesn't get copied into the output pathname
 */
  if(homedir && strcmp(homedir, FS_ROOT_DIR) == 0 &&
     (pptr-path) + FS_DIR_SEP_LEN < pathlen &&
     strncmp(pptr, FS_DIR_SEP, FS_DIR_SEP_LEN) == 0) {
    pptr += FS_DIR_SEP_LEN;
  };
/*
 * Return a pointer to the next unprocessed character.
 */
  *endp = pptr;
  return 0;
}

/*.......................................................................
 * Clear the filename status codes that are recorded before each filename
 * in the cache.
 *
 * Input:
 *  pc     PathCache *  The filename cache.
 */
static void pca_remove_marks(PathCache *pc)
{
  PathNode *node;         /* A node in the list of directories in the path */
  int i;
/*
 * Traverse the absolute directories of the path, clearing the
 * filename status marks that precede each filename.
 */
  for(node=pc->head; node; node=node->next) {
    if(!node->relative) {
      for(i=0; i<node->nfile; i++)
	*node->files[i] = PCA_F_ENIGMA;
    };
  };
  return;
}

#endif  /* ifndef WITHOUT_FILE_SYSTEM */
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <errno.h>

#include "freelist.h"
#include "stringrp.h"

/*
 * StringSegment objects store lots of small strings in larger
 * character arrays. Since the total length of all of the strings can't
 * be known in advance, an extensible list of large character arrays,
 * called string-segments are used.
 */
typedef struct StringSegment StringSegment;
struct StringSegment {
  StringSegment *next; /* A pointer to the next segment in the list */
  char *block;         /* An array of characters to be shared between strings */
  int unused;          /* The amount of unused space at the end of block[] */
};

/*
 * StringGroup is typedef'd in stringrp.h.
 */
struct StringGroup {
  FreeList *node_mem;  /* The StringSegment free-list */
  int block_size;      /* The dimension of each character array block */
  StringSegment *head; /* The list of character arrays */
};

/*
 * Specify how many StringSegment's to allocate at a time.
 */
#define STR_SEG_BLK 20

/*.......................................................................
 * Create a new StringGroup object.
 *
 * Input:
 *  segment_size    int    The length of each of the large character
 *                         arrays in which multiple strings will be
 *                         stored. This sets the length of longest
 *                         string that can be stored, and for efficiency
 *                         should be at least 10 times as large as
 *                         the average string that will be stored.
 * Output:
 *  return  StringGroup *  The new object, or NULL on error.
 */
StringGroup *_new_StringGroup(int segment_size)
{
  StringGroup *sg;    /* The object to be returned */
/*
 * Check the arguments.
 */
  if(segment_size < 1) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Allocate the container.
 */
  sg = (StringGroup *) malloc(sizeof(StringGroup));
  if(!sg) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize the
 * container at least up to the point at which it can safely be passed
 * to _del_StringGroup().
 */
  sg->node_mem = NULL;
  sg->head = NULL;
  sg->block_size = segment_size;
/*
 * Allocate the free list that is used to allocate list nodes.
 */
  sg->node_mem = _new_FreeList(sizeof(StringSegment), STR_SEG_BLK);
  if(!sg->node_mem)
    return _del_StringGroup(sg);
  return sg;
}

/*.......................................................................
 * Delete a StringGroup object.
 *
 * Input:
 *  sg     StringGroup *  The object to be deleted.
 * Output:
 *  return StringGroup *  The deleted object (always NULL).
 */
StringGroup *_del_StringGroup(StringGroup *sg)
{
  if(sg) {
    StringSegment *node;
/*
 * Delete the character arrays.
 */
    for(node=sg->head; node; node=node->next) {
      if(node->block)
	free(node->block);
      node->block = NULL;
    };
/*
 * Delete the list nodes that contained the string segments.
 */
    sg->node_mem = _del_FreeList(sg->node_mem, 1);
    sg->head = NULL; /* Already deleted by deleting sg->node_mem */
/*
 * Delete the container.
 */
    free(sg);
  };
  return NULL;
}

/*.......................................................................
 * Make a copy of a string in the specified string group, and return
 * a pointer to the copy.
 *
 * Input:
 *  sg      StringGroup *  The group to store the string in.
 *  string   const char *  The string to be recorded.
 *  remove_escapes  int    If true, omit backslashes which escape
 *                         other characters when making the copy.
 * Output:
 *  return         char *  The pointer to the copy of the string,
 *                         or NULL if there was insufficient memory.
 */
char *_sg_store_string(StringGroup *sg, const char *string, int remove_escapes)
{
  char *copy;           /* The recorded copy of string[] */
  size_t len;
/*
 * Check the arguments.
 */
  if(!sg || !string)
    return NULL;
/*
 * Get memory for the string.
 */
  len = strlen(string);
  copy = _sg_alloc_string(sg, len);
  if(copy) {
/*
 * If needed, remove backslash escapes while copying the input string
 * into the cache string.
 */
    if(remove_escapes) {
      int escaped = 0;             /* True if the next character should be */
                                   /*  escaped. */
      const char *src = string;    /* A pointer into the input string */
      char *dst = copy;            /* A pointer into the cached copy of the */
                                   /*  string. */
      while(*src) {
	if(!escaped && *src == '\\') {
	  escaped = 1;
	  src++;
	} else {
	  escaped = 0;
	  *dst++ = *src++;
	};
      };
      *dst = '\0';
/*
 * If escapes have already been removed, copy the input string directly
 * into the cache.
 */
    } else {
      strlcpy(copy, string, len + 1);
    };
  };
/*
 * Return a pointer to the copy of the string (or NULL if the allocation
 * failed).
 */
  return copy;
}

/*.......................................................................
 * Allocate memory for a string of a given length.
 *
 * Input:
 *  sg      StringGroup *  The group to store the string in.
 *  length          int    The required length of the string.
 * Output:
 *  return         char *  The pointer to the copy of the string,
 *                         or NULL if there was insufficient memory.
 */
char *_sg_alloc_string(StringGroup *sg, int length)
{
  StringSegment *node;  /* A node of the list of string segments */
  char *copy;           /* The allocated string */
/*
 * If the string is longer than block_size, then we can't record it.
 */
  if(length > sg->block_size || length < 0)
    return NULL;
/*
 * See if there is room to record the string in one of the existing
 * string segments. Do this by advancing the node pointer until we find
 * a node with length+1 bytes unused, or we get to the end of the list.
 */
  for(node=sg->head; node && node->unused <= length; node=node->next)
    ;
/*
 * If there wasn't room, allocate a new string segment.
 */
  if(!node) {
    node = (StringSegment *) _new_FreeListNode(sg->node_mem);
    if(!node)
      return NULL;
/*
 * Initialize the segment.
 */
    node->next = NULL;
    node->block = NULL;
    node->unused = sg->block_size;
/*
 * Attempt to allocate the string segment character array.
 */
    node->block = (char *) malloc(sg->block_size);
    if(!node->block)
      return NULL;
/*
 * Prepend the node to the list.
 */
    node->next = sg->head;
    sg->head = node;
  };
/*
 * Get memory for the string.
 */
  copy = node->block + sg->block_size - node->unused;
  node->unused -= length + 1;
/*
 * Return a pointer to the string memory.
 */
  return copy;
}

/*.......................................................................
 * Delete all of the strings that are currently stored by a specified
 * StringGroup object.
 *
 * Input:
 *  sg   StringGroup *   The group of strings to clear.
 */
void _clr_StringGroup(StringGroup *sg)
{
  StringSegment *node;   /* A node in the list of string segments */
/*
 * Mark all of the string segments as unoccupied.
 */
  for(node=sg->head; node; node=node->next)
    node->unused = sg->block_size;
  return;
}
#ifndef stringrp_h
#define stringrp_h
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

/*
 * StringGroup objects provide memory for modules that need to
 * allocate lots of small strings without needing to free any of them
 * individually, but rather is happy to free them all at the same
 * time. Taking advantage of these properties, StringGroup objects
 * avoid the heap fragmentation that tends to occur when lots of small
 * strings are allocated directly from the heap and later free'd. They
 * do this by allocating a list of large character arrays in each of
 * which multiple strings are stored. Thus instead of allocating lots
 * of small strings, a few large character arrays are allocated. When
 * the strings are free'd on mass, this list of character arrays is
 * maintained, ready for subsequent use in recording another set of
 * strings.
 */
typedef struct StringGroup StringGroup;

/*
 * The following constructor allocates a string-allocation object.
 * The segment_size argument specifies how long each string segment
 * array should be. This should be at least 10 times the length of
 * the average string to be recorded in the string group, and
 * sets the length of the longest string that can be stored.
 */
StringGroup *_new_StringGroup(int segment_size);

/*
 * Delete all of the strings that are currently stored by a specified
 * StringGroup object.
 */
void _clr_StringGroup(StringGroup *sg);

/*
 * Make a copy of the specified string, returning a pointer to
 * the copy, or NULL if there was insufficient memory. If the
 * remove_escapes argument is non-zero, backslashes that escape
 * other characters will be removed.
 */
char *_sg_store_string(StringGroup *sg, const char *string, int remove_escapes);

/*
 * Allocate memory for a string of a given length.
 */
char *_sg_alloc_string(StringGroup *sg, int length);

/*
 * Delete a StringGroup object (and all of the strings that it
 * contains).
 */
StringGroup *_del_StringGroup(StringGroup *sg);

#endif
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#include <stdlib.h>
#include <stdio.h>
#include <errno.h>

#include "strngmem.h"
#include "freelist.h"

struct StringMem {
  unsigned long nmalloc;  /* The number of strings allocated with malloc */
  FreeList *fl;           /* The free-list */
};

/*.......................................................................
 * Create a string free-list container and the first block of its free-list.
 *
 * Input:
 *  blocking_factor   int    The blocking_factor argument specifies how
 *                           many strings of length SM_STRLEN
 *                           bytes (see stringmem.h) are allocated in each
 *                           free-list block.
 *                           For example if blocking_factor=64 and
 *                           SM_STRLEN=16, then each new
 *                           free-list block will take 1K of memory.
 * Output:
 *  return      StringMem *  The new free-list container, or NULL on
 *                           error.
 */
StringMem *_new_StringMem(unsigned blocking_factor)
{
  StringMem *sm;    /* The container to be returned. */
/*
 * Check arguments.
 */
  if(blocking_factor < 1) {
    errno = EINVAL;
    return NULL;
  };
/*
 * Allocate the container.
 */
  sm = (StringMem *) malloc(sizeof(StringMem));
  if(!sm) {
    errno = ENOMEM;
    return NULL;
  };
/*
 * Before attempting any operation that might fail, initialize
 * the container at least up to the point at which it can safely
 * be passed to _del_StringMem().
 */
  sm->nmalloc = 0;
  sm->fl = NULL;
/*
 * Allocate the free-list.
 */
  sm->fl = _new_FreeList(SM_STRLEN, blocking_factor);
  if(!sm->fl)
    return _del_StringMem(sm, 1);
/*
 * Return the free-list container.
 */
  return sm;
}

/*.......................................................................
 * Delete a string free-list.
 *
 * Input:
 *  sm       StringMem *  The string free-list to be deleted, or NULL.
 *  force          int    If force==0 then _del_StringMem() will complain
 *                         and refuse to delete the free-list if any
 *                         of nodes have not been returned to the free-list.
 *                        If force!=0 then _del_StringMem() will not check
 *                         whether any nodes are still in use and will
 *                         always delete the list.
 * Output:
 *  return   StringMem *  Always NULL (even if the list couldn't be
 *                        deleted).
 */
StringMem *_del_StringMem(StringMem *sm, int force)
{
  if(sm) {
/*
 * Check whether any strings have not been returned to the free-list.
 */
    if(!force && (sm->nmalloc > 0 || _busy_FreeListNodes(sm->fl) > 0)) {
      errno = EBUSY;
      return NULL;
    };
/*
 * Delete the free-list.
 */
    sm->fl = _del_FreeList(sm->fl, force);
/*
 * Delete the container.
 */
    free(sm);
  };
  return NULL;
}

/*.......................................................................
 * Allocate an array of 'length' chars.
 *
 * Input:
 *  sm      StringMem *  The string free-list to allocate from.
 *  length     size_t    The length of the new string (including '\0').
 * Output:
 *  return       char *  The new string or NULL on error.
 */
char *_new_StringMemString(StringMem *sm, size_t length)
{
  char *string;   /* The string to be returned */
  int was_malloc; /* True if malloc was used to allocate the string */
/*
 * Check arguments.
 */
  if(!sm)
    return NULL;
  if(length < 1)
    length = 1;
/*
 * Allocate the new node from the free list if possible.
 */
  if(length < SM_STRLEN) {
    string = (char *)_new_FreeListNode(sm->fl);
    if(!string)
      return NULL;
    was_malloc = 0;
  } else {
    string = (char *) malloc(length+1); /* Leave room for the flag byte */
    if(!string)
      return NULL;
/*
 * Count malloc allocations.
 */
    was_malloc = 1;
    sm->nmalloc++;
  };
/*
 * Use the first byte of the string to record whether the string was
 * allocated with malloc or from the free-list. Then return the rest
 * of the string for use by the user.
 */
  string[0] = (char) was_malloc;
  return string + 1;
}

/*.......................................................................
 * Free a string that was previously returned by _new_StringMemString().
 *
 * Input:
 *  sm      StringMem *  The free-list from which the string was originally
 *                       allocated.
 *  s            char *  The string to be returned to the free-list, or NULL.
 * Output:
 *  return       char *  Always NULL.
 */
char *_del_StringMemString(StringMem *sm, char *s)
{
  int was_malloc;  /* True if the string originally came from malloc() */
/*
 * Is there anything to be deleted?
 */
  if(s && sm) {
/*
 * Retrieve the true string pointer. This is one less than the one
 * returned by _new_StringMemString() because the first byte of the
 * allocated memory is reserved by _new_StringMemString as a flag byte
 * to say whether the memory was allocated from the free-list or directly
 * from malloc().
 */
    s--;
/*
 * Get the origination flag.
 */
    was_malloc = s[0];
    if(was_malloc) {
      free(s);
      s = NULL;
      sm->nmalloc--;
    } else {
      s = (char *) _del_FreeListNode(sm->fl, s);
    };
  };
  return NULL;
}
#ifndef stringmem_h
#define stringmem_h
/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

typedef struct StringMem StringMem;

/*
 * Applications that dynamically allocate lots of small strings
 * run the risk of significantly fragmenting the heap. This module
 * aims to reduce this risk by allocating large arrays of small fixed
 * length strings, arranging them as a free-list and allowing
 * callers to allocate from the list. Strings that are too long
 * to be allocated from the free-list are allocated from the heap.
 * Since typical implementations of malloc() eat up a minimum of
 * 16 bytes per call to malloc() [because of alignment and space
 * management constraints] it makes sense to set the free-list
 * string size to 16 bytes. Note that unlike malloc() which typically
 * keeps 8 bytes per allocation for its own use, our allocator will
 * return all but one of the 16 bytes for use. One hidden byte of overhead
 * is reserved for flagging whether the string was allocated directly
 * from malloc or from the free-list.
 */

/*
 * Set the length of each free-list string. The longest string that
 * will be returned without calling malloc() will be one less than
 * this number.
 */
#define SM_STRLEN 16

/*
 * Create a string free-list container and the first block of its free-list.
 */
StringMem *_new_StringMem(unsigned blocking_factor);

/*
 * Delete a string free-list.
 */
StringMem *_del_StringMem(StringMem *sm, int force);

/*
 * Allocate an array of 'length' chars.
 */
char *_new_StringMemString(StringMem *sm, size_t size);

/*
 * Free a string that was previously returned by _new_StringMemString().
 */
char *_del_StringMemString(StringMem *sm, char *s);

#endif
#include "libtecla.h"

/*.......................................................................
 * Return the version number of the tecla library.
 *
 * Input:
 *  major    int *   The major version number of the library
 *                   will be assigned to *major. This number is
 *                   only incremented when a change to the library is
 *                   made that breaks binary (shared library) and/or
 *                   compilation backwards compatibility.
 *  minor    int *   The minor version number of the library
 *                   will be assigned to *minor. This number is
 *                   incremented whenever new functions are added to
 *                   the public API.
 *  micro    int *   The micro version number of the library will be
 *                   assigned to *micro. This number is incremented
 *                   whenever internal changes are made that don't
 *                   change the public API, such as bug fixes and
 *                   performance enhancements.
 */
void libtecla_version(int *major, int *minor, int *micro)
{
  if(major)
    *major = TECLA_MAJOR_VER;
  if(minor)
    *minor = TECLA_MINOR_VER;
  if(micro)
    *micro = TECLA_MICRO_VER;
}
#ifndef libtecla_h
#define libtecla_h

/*
 * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
 *
 * All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, and/or sell copies of the Software, and to permit persons
 * to whom the Software is furnished to do so, provided that the above
 * copyright notice(s) and this permission notice appear in all copies of
 * the Software and that both the above copyright notice(s) and this
 * permission notice appear in supporting documentation.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
 * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
 * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Except as contained in this notice, the name of a copyright holder
 * shall not be used in advertising or otherwise to promote the sale, use
 * or other dealings in this Software without prior written authorization
 * of the copyright holder.
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <stdio.h>   /* FILE * */
#include <stdlib.h>  /* size_t */
#include <time.h>    /* time_t */
#include <signal.h>  /* struct sigaction */

/*
 * The following are the three components of the libtecla version number.
 * Note that it is better to use the libtecla_version() function than these
 * macros since the macros only tell you which version of the library your
 * code was compiled against, whereas the libtecla_version() function
 * tells you which version of the shared tecla library your program is
 * actually linked to.
 */
#define TECLA_MAJOR_VER 1
#define TECLA_MINOR_VER 6
#define TECLA_MICRO_VER 0

/*.......................................................................
 * Query the version number of the tecla library.
 *
 * Input:
 *  major    int *   The major version number of the library
 *                   will be assigned to *major. This number is
 *                   only incremented when a change to the library is
 *                   made that breaks binary (shared library) and/or
 *                   compilation backwards compatibility.
 *  minor    int *   The minor version number of the library
 *                   will be assigned to *minor. This number is
 *                   incremented whenever new functions are added to
 *                   the public API.
 *  micro    int *   The micro version number of the library will be
 *                   assigned to *micro. This number is incremented
 *                   whenever internal changes are made that don't
 *                   change the public API, such as bug fixes and
 *                   performance enhancements.
 */
void libtecla_version(int *major, int *minor, int *micro);

/*-----------------------------------------------------------------------
 * The getline module provides interactive command-line input, recall and
 * editing by users at terminals. See the gl_get_line(3TECLA) man page for
 * more details.
 *-----------------------------------------------------------------------*/

/*
 * Provide an opaque handle for the resource object that is defined in
 * getline.h.
 */
typedef struct GetLine GetLine;

/*
 * The following two functions are used to create and delete the
 * resource objects that are used by the gl_get_line() function.
 */
GetLine *new_GetLine(size_t linelen, size_t histlen);
GetLine *del_GetLine(GetLine *gl);

/*
 * Read a line into an internal buffer of gl.
 */
char *gl_get_line(GetLine *gl, const char *prompt, const char *start_line,
		  int start_pos);

/*.......................................................................
 * Prompt the user for a single-character reply.
 *
 * Input:
 *  gl       GetLine *  A resource object returned by new_GetLine().
 *  prompt      char *  The prompt to prefix the query with, or NULL
 *                      to reuse the previous prompt.
 *  defchar     char    The character to substitute if the
 *                      user simply hits return, or '\n' if you don't
 *                      need to substitute anything.
 * Output:
 *  return       int    The character that was read, or EOF if the read
 *                      had to be aborted (in which case you can call
 *                      gl_return_status() to find out why).
 */
int gl_query_char(GetLine *gl, const char *prompt, char defchar);

/*.......................................................................
 * Read a single uninterpretted character from the user, without
 * displaying anything.
 *
 * Input:
 *  gl     GetLine *  A resource object previously returned by
 *                    new_GetLine().
 * Output:
 *  return     int    The character that was read, or EOF if the read
 *                    had to be aborted (in which case you can call
 *                    gl_return_status() to find out why).
 */
int gl_read_char(GetLine *gl);

/*
 * Configure the application specific and/or user-specific behavior of
 * gl_get_line().
 */
int gl_configure_getline(GetLine *gl, const char *app_string,
			 const char *app_file, const char *user_file);

/*
 * The following enumerators specify the origin of a key binding, and
 * are listed in order of decreasing priority, such that user-specified
 * key-bindings take precedence over application default bindings.
 */
typedef enum {
  GL_USER_KEY,  /* A key-binding specified by the user */
  GL_APP_KEY    /* A key-binding specified by the application */
} GlKeyOrigin;

/*
 * Bind a key sequence to a given action. If action==NULL, unbind the
 * key-sequence.
 */
int gl_bind_keyseq(GetLine *gl, GlKeyOrigin origin, const char *keyseq,
		   const char *action);

/*-----------------------------------------------------------------------
 * The file-expansion module provides facilities for expanding ~user/ and
 * $envvar expressions, and for expanding glob-style wildcards.
 * See the ef_expand_file(3) man page for more details.
 *-----------------------------------------------------------------------*/

/*
 * ExpandFile objects contain the resources needed to expand pathnames.
 */
typedef struct ExpandFile ExpandFile;

/*
 * The following functions are used to create and delete the resource
 * objects that are used by the ef_expand_file() function.
 */
ExpandFile *new_ExpandFile(void);
ExpandFile *del_ExpandFile(ExpandFile *ef);

/*
 * A container of the following type is returned by ef_expand_file().
 */
typedef struct {
  int exists;       /* True if the files in files[] currently exist. */
                    /*  This only time that this may not be true is if */
                    /*  the input filename didn't contain any wildcards */
                    /*  and thus wasn't matched against existing files. */
                    /*  In this case the single entry in 'nfile' may not */
                    /*  refer to an existing file. */
  int nfile;        /* The number of files in files[] */
  char **files;     /* An array of 'nfile' filenames. */
} FileExpansion;

/*
 * The ef_expand_file() function expands a specified pathname, converting
 * ~user/ and ~/ patterns at the start of the pathname to the
 * corresponding home directories, replacing $envvar with the value of
 * the corresponding environment variable, and then, if there are any
 * wildcards, matching these against existing filenames.
 *
 * If no errors occur, a container is returned containing the array of
 * files that resulted from the expansion. If there were no wildcards
 * in the input pathname, this will contain just the original pathname
 * after expansion of ~ and $ expressions. If there were any wildcards,
 * then the array will contain the files that matched them. Note that
 * if there were any wildcards but no existing files match them, this
 * is counted as an error and NULL is returned.
 *
 * The supported wildcards and their meanings are:
 *  *        -  Match any sequence of zero or more characters.
 *  ?        -  Match any single character.
 *  [chars]  -  Match any single character that appears in 'chars'.
 *              If 'chars' contains an expression of the form a-b,
 *              then any character between a and b, including a and b,
 *              matches. The '-' character looses its special meaning
 *              as a range specifier when it appears at the start
 *              of the sequence of characters.
 *  [^chars] -  The same as [chars] except that it matches any single
 *              character that doesn't appear in 'chars'.
 *
 * Wildcard expressions are applied to individual filename components.
 * They don't match across directory separators. A '.' character at
 * the beginning of a filename component must also be matched
 * explicitly by a '.' character in the input pathname, since these
 * are UNIX's hidden files.
 *
 * Input:
 *  fe         ExpandFile *  The pathname expansion resource object.
 *  path       const char *  The path name to be expanded.
 *  pathlen           int    The length of the suffix of path[] that
 *                           constitutes the filename to be expanded,
 *                           or -1 to specify that the whole of the
 *                           path string should be used.
 * Output:
 *  return  FileExpansion *  A pointer to a results container within the
 *                           given ExpandFile object. This contains an
 *                           array of the pathnames that resulted from
 *                           expanding ~ and $ expressions and from
 *                           matching any wildcards, sorted into lexical
 *                           order.
 *
 *                           This container and its contents will be
 *                           recycled on subsequent calls, so if you need
 *                           to keep the results of two successive runs,
 *                           you will either have to allocate a private
 *                           copy of the array, or use two ExpandFile
 *                           objects.
 *
 *                           On error, NULL is returned. A description
 *                           of the error can be acquired by calling the
 *                           ef_last_error() function.
 */
FileExpansion *ef_expand_file(ExpandFile *ef, const char *path, int pathlen);

/*.......................................................................
 * Print out an array of matching files.
 *
 * Input:
 *  result  FileExpansion *   The container of the sorted array of
 *                            expansions.
 *  fp               FILE *   The output stream to write to.
 *  term_width        int     The width of the terminal.
 * Output:
 *  return            int     0 - OK.
 *                            1 - Error.
 */
int ef_list_expansions(FileExpansion *result, FILE *fp, int term_width);

/*
 * The ef_last_error() function returns a description of the last error
 * that occurred in a call ef_expand_file(). Note that this message is
 * contained in an array which is allocated as part of *ef, and its
 * contents thus potentially change on every call to ef_expand_file().
 */
const char *ef_last_error(ExpandFile *ef);

/*-----------------------------------------------------------------------
 * The WordCompletion module is used for completing incomplete words, such
 * as filenames. Programs can use functions within this module to register
 * their own customized completion functions.
 *-----------------------------------------------------------------------*/

/*
 * Ambiguous completion matches are recorded in objects of the
 * following type.
 */
typedef struct WordCompletion WordCompletion;

/*
 * Create a new completion object.
 */
WordCompletion *new_WordCompletion(void);

/*
 * Delete a redundant completion object.
 */
WordCompletion *del_WordCompletion(WordCompletion *cpl);

/*.......................................................................
 * Callback functions declared and prototyped using the following macro
 * are called upon to return an array of possible completion suffixes
 * for the token that precedes a specified location in the given
 * input line. It is up to this function to figure out where the token
 * starts, and to call cpl_add_completion() to register each possible
 * completion before returning.
 *
 * Input:
 *  cpl  WordCompletion *  An opaque pointer to the object that will
 *                         contain the matches. This should be filled
 *                         via zero or more calls to cpl_add_completion().
 *  data           void *  The anonymous 'data' argument that was
 *                         passed to cpl_complete_word() or
 *                         gl_customize_completion()).
 *  line     const char *  The current input line.
 *  word_end        int    The index of the character in line[] which
 *                         follows the end of the token that is being
 *                         completed.
 * Output
 *  return          int    0 - OK.
 *                         1 - Error.
 */
#define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, void *data, \
                                  const char *line, int word_end)
typedef CPL_MATCH_FN(CplMatchFn);

/*.......................................................................
 * Optional callback functions declared and prototyped using the
 * following macro are called upon to return non-zero if a given
 * file, specified by its pathname, is to be included in a list of
 * completions.
 *
 * Input:
 *  data            void *  The application specified pointer which
 *                          was specified when this callback function
 *                          was registered. This can be used to have
 *                          anything you like passed to your callback.
 *  pathname  const char *  The pathname of the file to be checked to
 *                          see if it should be included in the list
 *                          of completions.
 * Output
 *  return           int    0 - Ignore this file.
 *                          1 - Do include this file in the list
 *                              of completions.
 */
#define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
typedef CPL_CHECK_FN(CplCheckFn);

/*
 * You can use the following CplCheckFn callback function to only
 * have executables included in a list of completions.
 */
CPL_CHECK_FN(cpl_check_exe);

/*
 * cpl_file_completions() is the builtin filename completion callback
 * function. This can also be called by your own custom CPL_MATCH_FN()
 * callback functions. To do this pass on all of the arguments of your
 * custom callback function to cpl_file_completions(), with the exception
 * of the (void *data) argument. The data argument should either be passed
 * NULL to request the default behaviour of the file-completion function,
 * or be passed a pointer to a CplFileConf structure (see below). In the
 * latter case the contents of the structure modify the behavior of the
 * file-completer.
 */
CPL_MATCH_FN(cpl_file_completions);

/*
 * Objects of the following type can be used to change the default
 * behavior of the cpl_file_completions() callback function.
 */
typedef struct CplFileConf CplFileConf;

/*
 * If you want to change the behavior of the cpl_file_completions()
 * callback function, call the following function to allocate a
 * configuration object, then call one or more of the subsequent
 * functions to change any of the default configuration parameters
 * that you don't want. This function returns NULL when there is
 * insufficient memory.
 */
CplFileConf *new_CplFileConf(void);

/*
 * If backslashes in the prefix being passed to cpl_file_completions()
 * should be treated as literal characters, call the following function
 * with literal=1. Otherwise the default is to treat them as escape
 * characters which remove the special meanings of spaces etc..
 */
void cfc_literal_escapes(CplFileConf *cfc, int literal);

/*
 * Before calling cpl_file_completions(), call this function if you
 * know the index at which the filename prefix starts in the input line.
 * Otherwise by default, or if you specify start_index to be -1, the
 * filename is taken to start after the first unescaped space preceding
 * the cursor, or the start of the line, which ever comes first.
 */
void cfc_file_start(CplFileConf *cfc, int start_index);

/*
 * If you only want certain types of files to be included in the
 * list of completions, use the following function to specify a
 * callback function which will be called to ask whether a given file
 * should be included. The chk_data argument is will be passed to the
 * callback function whenever it is called and can be anything you want.
 */
void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, void *chk_data);

/*
 * The following function deletes a CplFileConf objects previously
 * returned by new_CplFileConf(). It always returns NULL.
 */
CplFileConf *del_CplFileConf(CplFileConf *cfc);

/*
 * The following configuration structure is deprecated. Do not change
 * its contents, since this will break any programs that still use it,
 * and don't use it in new programs. Instead use opaque CplFileConf
 * objects as described above. cpl_file_completions() figures out
 * what type of structure you pass it, by virtue of a magic int code
 * placed at the start of CplFileConf object by new_CplFileConf().
 */
typedef struct {
  int escaped;     /* Opposite to the argument of cfc_literal_escapes() */
  int file_start;  /* Equivalent to the argument of cfc_file_start() */
} CplFileArgs;
/*
 * This initializes the deprecated CplFileArgs structures.
 */
void cpl_init_FileArgs(CplFileArgs *cfa);

/*.......................................................................
 * When an error occurs while performing a completion, custom completion
 * callback functions should register a terse description of the error
 * by calling cpl_record_error(). This message will then be returned on
 * the next call to cpl_last_error() and used by getline to display an
 * error message to the user.
 *
 * Input:
 *  cpl  WordCompletion *  The string-completion resource object that was
 *                         originally passed to the callback.
 *  errmsg   const char *  The description of the error.
 */
void cpl_record_error(WordCompletion *cpl, const char *errmsg);

/*.......................................................................
 * This function can be used to replace the builtin filename-completion
 * function with one of the user's choice. The user's completion function
 * has the option of calling the builtin filename-completion function
 * if it believes that the token that it has been presented with is a
 * filename (see cpl_file_completions() above).
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  data             void *  This is passed to match_fn() whenever it is
 *                           called. It could, for example, point to a
 *                           symbol table that match_fn() would look up
 *                           matches in.
 *  match_fn   CplMatchFn *  The function that will identify the prefix
 *                           to be completed from the input line, and
 *                           report matching symbols.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_customize_completion(GetLine *gl, void *data, CplMatchFn *match_fn);

/*.......................................................................
 * This function allows you to install alternate completion action
 * functions or completion listing functions, or to change the
 * completion function of an existing action of the same type. This
 * should preferably be called before the first call to gl_get_line()
 * so that the name of the action becomes defined before the user's
 * configuration file is read.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  data             void *  This is passed to match_fn() whenever it is
 *                           called. It could, for example, point to a
 *                           symbol table that match_fn() would look up
 *                           matches in.
 *  match_fn   CplMatchFn *  The function that will identify the prefix
 *                           to be completed from the input line, and
 *                           report matching symbols.
 *  list_only         int    If non-zero, install an action that only lists
 *                           possible completions, rather than attempting
 *                           to perform the completion.
 *  name       const char *  The name with which users can refer to the
 *                           binding in tecla configuration files.
 *  keyseq     const char *  The key sequence with which to invoke
 *                           the binding. This should be specified in the
 *                           same manner as key-sequences in tecla
 *                           configuration files (eg. "M-^I").
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_completion_action(GetLine *gl, void *data, CplMatchFn *match_fn,
			 int list_only, const char *name, const char *keyseq);

/*.......................................................................
 * Change the terminal (or stream) that getline interacts with.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  input_fp         FILE *  The stdio stream to read from.
 *  output_fp        FILE *  The stdio stream to write to.
 *  term       const char *  The terminal type. This can be NULL if
 *                           either or both of input_fp and output_fp don't
 *                           refer to a terminal. Otherwise it should refer
 *                           to an entry in the terminal information database.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_change_terminal(GetLine *gl, FILE *input_fp, FILE *output_fp,
		       const char *term);

/*.......................................................................
 * The following functions can be used to save and restore the contents
 * of the history buffer.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  filename   const char *  The name of the new file to write to.
 *  comment    const char *  Extra information such as timestamps will
 *                           be recorded on a line started with this
 *                           string, the idea being that the file can
 *                           double as a command file. Specify "" if
 *                           you don't care. Be sure to specify the
 *                           same string to both functions.
 *  max_lines         int    The maximum number of lines to save, or -1
 *                           to save all of the lines in the history
 *                           list.
 * Output:
 *  return            int     0 - OK.
 *                            1 - Error.
 */
int gl_save_history(GetLine *gl, const char *filename, const char *comment,
		    int max_lines);
int gl_load_history(GetLine *gl, const char *filename, const char *comment);

/*
 * Enumerate file-descriptor events that can be waited for.
 */
typedef enum {
  GLFD_READ,   /* Watch for data waiting to be read from a file descriptor */
  GLFD_WRITE,  /* Watch for ability to write to a file descriptor */
  GLFD_URGENT  /* Watch for urgent out-of-band data on the file descriptor */
} GlFdEvent;

/*
 * The following enumeration is used for the return status of file
 * descriptor event callbacks.
 */
typedef enum {
  GLFD_ABORT,    /* Cause gl_get_line() to abort with an error */
  GLFD_REFRESH,  /* Redraw the input line and continue waiting for input */
  GLFD_CONTINUE  /* Continue to wait for input, without redrawing the line */
} GlFdStatus;

/*.......................................................................
 * On systems that have the select() system call, while gl_get_line()
 * is waiting for terminal input, it can also be asked to listen for
 * activity on arbitrary file descriptors.  Callback functions of the
 * following type can be registered to be called when activity is
 * seen. If your callback needs to write to the terminal or use
 * signals, please see the gl_get_line(3) man page.
 *
 * Input:
 *  gl       GetLine *  The gl_get_line() resource object. You can use
 *                      this safely to call gl_watch_fd() or
 *                      gl_inactivity_timeout(). The effect of calling other
 *                      functions that take a gl argument is undefined,
 *                      and must be avoided.
 *  data        void *  A pointer to arbitrary callback data, as originally
 *                      registered with gl_watch_fd().
 *  fd           int    The file descriptor that has activity.
 *  event  GlFdEvent    The activity seen on the file descriptor. The
 *                      inclusion of this argument allows the same
 *                      callback to be registered for multiple events.
 * Output:
 *  return GlFdStatus   GLFD_ABORT    - Cause gl_get_line() to abort with
 *                                      an error (set errno if you need it).
 *                      GLFD_REFRESH  - Redraw the input line and continue
 *                                      waiting for input. Use this if you
 *                                      wrote something to the terminal.
 *                      GLFD_CONTINUE - Continue to wait for input, without
 *                                      redrawing the line.
 */
#define GL_FD_EVENT_FN(fn) GlFdStatus (fn)(GetLine *gl, void *data, int fd, \
					   GlFdEvent event)
typedef GL_FD_EVENT_FN(GlFdEventFn);

/*.......................................................................
 * Where possible, register a function and associated data to be called
 * whenever a specified event is seen on a file descriptor.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  fd                int    The file descriptor to watch.
 *  event       GlFdEvent    The type of activity to watch for.
 *  callback  GlFdEventFn *  The function to call when the specified
 *                           event occurs. Setting this to 0 removes
 *                           any existing callback.
 *  data             void *  A pointer to arbitrary data to pass to the
 *                           callback function.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Either gl==NULL, or this facility isn't
 *                               available on the the host system
 *                               (ie. select() isn't available). No
 *                               error message is generated in the latter
 *                               case.
 */
int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,
		GlFdEventFn *callback, void *data);

/*
 * Enumerators from the following list are returned by activity
 * timeout callbacks registered by gl_inactivity_timeout(). They tell
 * gl_get_line() whether and how to procede.
 */
typedef enum {
  GLTO_ABORT,    /* Cause gl_get_line() to abort with an error */
  GLTO_REFRESH,  /* Redraw the input line and continue waiting for input */
  GLTO_CONTINUE  /* Continue to wait for input, without redrawing the line */
} GlAfterTimeout;

/*.......................................................................
 * On systems that have the select() system call, the application has
 * the option of providing a callback function of the following type,
 * which is called whenever no terminal input or other I/O activity is
 * seen for the timeout duration specified in the last call to
 * gl_inactivity_timeout().
 *
 * Input:
 *  gl            GetLine *  The gl_get_line() resource object. You can use
 *                           this safely to call gl_watch_fd() or
 *                           gl_inactivity_timeout(). The effect of calling other
 *                           functions that take a gl argument is undefined,
 *                           and must be avoided.
 *  data             void *  A pointer to arbitrary callback data, as
 *                           originally registered with gl_inactivity_timeout().
 * Output:
 *  return GlAfterTimeout    GLTO_ABORT    - Cause gl_get_line() to
 *                                           abort with an error (set
 *                                           errno if you need it).
 *                           GLTO_REFRESH  - Redraw the input line and
 *                                           continue waiting for
 *                                           input. Use this if you
 *                                           wrote something to the
 *                                           terminal.
 *                           GLTO_CONTINUE - Continue to wait for
 *                                           input, without redrawing
 *                                           the line.
 */
#define GL_TIMEOUT_FN(fn) GlAfterTimeout (fn)(GetLine *gl, void *data)
typedef GL_TIMEOUT_FN(GlTimeoutFn);

/*.......................................................................
 * On systems with the select() system call, the gl_inactivity_timeout()
 * function provides the option of setting (or cancelling) an
 * inactivity timeout. Inactivity, in this case, refers both to
 * terminal input received from the user, and to I/O on any file
 * descriptors registered by calls to gl_watch_fd(). If at any time,
 * no activity is seen for the requested time period, the specified
 * timeout callback function is called. On returning, this callback
 * returns a code which tells gl_get_line() what to do next. Note that
 * each call to gl_inactivity_timeout() replaces any previously installed
 * timeout callback, and that specifying a callback of 0, turns off
 * inactivity timing.
 *
 * Beware that although the timeout argument includes a nano-second
 * component, few computer clocks presently have resolutions finer
 * than a few milliseconds, so asking for less than a few milliseconds
 * is equivalent to zero on a lot of systems.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  callback  GlTimeoutFn *  The function to call when the inactivity
 *                           timeout is exceeded. To turn off
 *                           inactivity timeouts altogether, send 0.
 *  data             void *  A pointer to arbitrary data to pass to the
 *                           callback function.
 *  sec     unsigned long    The number of whole seconds in the timeout.
 *  nsec    unsigned long    The fractional number of seconds in the
 *                           timeout, expressed in nano-seconds (see
 *                           the caveat above).
 * Output:
 *  return            int    0 - OK.
 *                           1 - Either gl==NULL, or this facility isn't
 *                               available on the the host system
 *                               (ie. select() isn't available). No
 *                               error message is generated in the latter
 *                               case.
 */
int gl_inactivity_timeout(GetLine *gl, GlTimeoutFn *timeout_fn, void *data,
		   unsigned long sec, unsigned long nsec);

/*.......................................................................
 * Switch history streams. History streams represent separate history
 * lists recorded within a single history buffer. Different streams
 * are distinguished by integer identifiers chosen by the calling
 * appplicaton. Initially new_GetLine() sets the stream identifier to
 * 0. Whenever a new line is appended to the history list, the current
 * stream identifier is recorded with it, and history lookups only
 * consider lines marked with the current stream identifier.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  id     unsigned    The new history stream identifier.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
int gl_group_history(GetLine *gl, unsigned id);

/*.......................................................................
 * Display the contents of the history list.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  fp         FILE *  The stdio output stream to write to.
 *  fmt  const char *  A format string. This containing characters to be
 *                     written verbatim, plus any of the following
 *                     format directives:
 *                       %D  -  The date, formatted like 2001-11-20
 *                       %T  -  The time of day, formatted like 23:59:59
 *                       %N  -  The sequential entry number of the
 *                              line in the history buffer.
 *                       %G  -  The number of the history group that
 *                              the line belongs to.
 *                       %%  -  A literal % character.
 *                       %H  -  The history line itself.
 *                     Note that a '\n' newline character is not
 *                     appended by default.
 *  all_groups  int    If true, display history lines from all
 *                     history groups. Otherwise only display
 *                     those of the current history group.
 *  max_lines   int    If max_lines is < 0, all available lines
 *                     are displayed. Otherwise only the most
 *                     recent max_lines lines will be displayed.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
int gl_show_history(GetLine *gl, FILE *fp, const char *fmt, int all_groups,
		    int max_lines);

/*.......................................................................
 * Resize or delete the history buffer.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  bufsize  size_t    The number of bytes in the history buffer, or 0
 *                     to delete the buffer completely.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Insufficient memory (the previous buffer
 *                         will have been retained). No error message
 *                         will be displayed.
 */
int gl_resize_history(GetLine *gl, size_t bufsize);

/*.......................................................................
 * Set an upper limit to the number of lines that can be recorded in the
 * history list, or remove a previously specified limit.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  max_lines   int    The maximum number of lines to allow, or -1 to
 *                     cancel a previous limit and allow as many lines
 *                     as will fit in the current history buffer size.
 */
void gl_limit_history(GetLine *gl, int max_lines);

/*.......................................................................
 * Discard either all historical lines, or just those associated with the
 * current history group.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  all_groups  int    If true, clear all of the history. If false,
 *                     clear only the stored lines associated with the
 *                     currently selected history group.
 */
void gl_clear_history(GetLine *gl, int all_groups);

/*.......................................................................
 * Temporarily enable or disable the gl_get_line() history mechanism.
 *
 * Input:
 *  gl      GetLine *  The resource object of gl_get_line().
 *  enable      int    If true, turn on the history mechanism. If
 *                     false, disable it.
 */
void gl_toggle_history(GetLine *gl, int enable);

/*
 * Objects of the following type are returned by gl_terminal_size().
 */
typedef struct {
  int nline;        /* The terminal has nline lines */
  int ncolumn;      /* The terminal has ncolumn columns */
} GlTerminalSize;

/*.......................................................................
 * Update if necessary, and return the current size of the terminal.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  def_ncolumn       int    If the number of columns in the terminal
 *                           can't be determined, substitute this number.
 *  def_nline         int    If the number of lines in the terminal can't
 *                           be determined, substitute this number.
 * Output:
 *  return GlTerminalSize    The current terminal size.
 */
GlTerminalSize gl_terminal_size(GetLine *gl, int def_ncolumn, int def_nline);

/*.......................................................................
 * Tell gl_get_line() the current terminal size. Note that this is only
 * necessary on systems where changes in terminal size aren't reported
 * via SIGWINCH.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  ncolumn           int    The number of columns in the terminal.
 *  nline             int    The number of rows in the terminal.
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_set_term_size(GetLine *gl, int ncolumn, int nline);

/*
 * The gl_lookup_history() function returns information in an
 * argument of the following type.
 */
typedef struct {
  const char *line;    /* The requested history line */
  unsigned group;      /* The history group to which the */
                       /*  line belongs. */
  time_t timestamp;    /* The date and time at which the */
                       /*  line was originally entered. */
} GlHistoryLine;

/*.......................................................................
 * Lookup a history line by its sequential number of entry in the
 * history buffer.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  id      unsigned long    The identification number of the line to
 *                           be returned, where 0 denotes the first line
 *                           that was entered in the history list, and
 *                           each subsequently added line has a number
 *                           one greater than the previous one. For
 *                           the range of lines currently in the list,
 *                           see the gl_range_of_history() function.
 * Input/Output:
 *  line    GlHistoryLine *  A pointer to the variable in which to
 *                           return the details of the line.
 * Output:
 *  return            int    0 - The line is no longer in the history
 *                               list, and *line has not been changed.
 *                           1 - The requested line can be found in
 *                               *line. Note that the string in
 *                               line->line is part of the history
 *                               buffer and will change, so a private
 *                               copy should be made if you wish to
 *                               use it after subsequent calls to any
 *                               functions that take gl as an argument.
 */
int gl_lookup_history(GetLine *gl, unsigned long id, GlHistoryLine *line);

/*
 * The gl_state_of_history() function returns information in an argument
 * of the following type.
 */
typedef struct {
  int enabled;     /* True if history is enabled */
  unsigned group;  /* The current history group */
  int max_lines;   /* The current upper limit on the number of lines */
                   /*  in the history list, or -1 if unlimited. */
} GlHistoryState;

/*.......................................................................
 * Query the state of the history list. Note that any of the input/output
 * pointers can be specified as NULL.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  state  GlHistoryState *  A pointer to the variable in which to record
 *                           the return values.
 */
void gl_state_of_history(GetLine *gl, GlHistoryState *state);

/*
 * The gl_range_of_history() function returns information in an argument
 * of the following type.
 */
typedef struct {
  unsigned long oldest;  /* The sequential entry number of the oldest */
                         /*  line in the history list. */
  unsigned long newest;  /* The sequential entry number of the newest */
                         /*  line in the history list. */
  int nlines;            /* The number of lines in the history list */
} GlHistoryRange;

/*.......................................................................
 * Query the number and range of lines in the history buffer.
 *
 * Input:
 *  gl            GetLine *  The resource object of gl_get_line().
 *  range  GlHistoryRange *  A pointer to the variable in which to record
 *                           the return values. If range->nline=0, the
 *                           range of lines will be given as 0-0.
 */
void gl_range_of_history(GetLine *gl, GlHistoryRange *range);

/*
 * The gl_size_of_history() function returns information in an argument
 * of the following type.
 */
typedef struct {
  size_t size;      /* The size of the history buffer (bytes) */
  size_t used;      /* The number of bytes of the history buffer */
                    /*  that are currently occupied. */
} GlHistorySize;

/*.......................................................................
 * Return the size of the history buffer and the amount of the
 * buffer that is currently in use.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  GlHistorySize size *  A pointer to the variable in which to return
 *                        the results.
 */
void gl_size_of_history(GetLine *gl, GlHistorySize *size);

/*.......................................................................
 * Enable or disable the automatic addition of newly entered lines to the
 * history list.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 *  enable          int     If true, subsequently entered lines will
 *                          automatically be added to the history list
 *                          before they are returned to the caller of
 *                          gl_get_line(). If 0, the choice of how and
 *                          when to archive lines in the history list,
 *                          is left up to the calling application, which
 *                          can do so via calls to gl_append_history().
 * Output:
 *  return          int     0 - OK.
 *                          1 - Error.
 */
int gl_automatic_history(GetLine *gl, int enable);

/*.......................................................................
 * Append a specified line to the history list.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 *  line     const char *   The line to be added.
 * Output:
 *  return          int     0 - OK.
 *                          1 - Error.
 */
int gl_append_history(GetLine *gl, const char *line);

/*.......................................................................
 * Specify whether text that users type should be displayed or hidden.
 * In the latter case, only the prompt is displayed, and the final
 * input line is not archived in the history list.
 *
 * Input:
 *  gl         GetLine *  The input-line history maintenance object.
 *  enable         int     0 - Disable echoing.
 *                         1 - Enable echoing.
 *                        -1 - Just query the mode without changing it.
 * Output:
 *  return         int    The echoing disposition that was in effect
 *                        before this function was called:
 *                         0 - Echoing was disabled.
 *                         1 - Echoing was enabled.
 */
int gl_echo_mode(GetLine *gl, int enable);

/*.......................................................................
 * This function can be called from gl_get_line() callbacks to have
 * the prompt changed when they return. It has no effect if gl_get_line()
 * is not currently being invoked.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  prompt  const char *  The new prompt.
 */
void gl_replace_prompt(GetLine *gl, const char *prompt);

/*
 * Enumerate the available prompt formatting styles.
 */
typedef enum {
  GL_LITERAL_PROMPT,   /* Display the prompt string literally */
  GL_FORMAT_PROMPT     /* The prompt string can contain any of the */
                       /* following formatting directives: */
                       /*   %B  -  Display subsequent characters */
                       /*          with a bold font. */
                       /*   %b  -  Stop displaying characters */
                       /*          with the bold font. */
                       /*   %U  -  Underline subsequent characters. */
                       /*   %u  -  Stop underlining characters. */
                       /*   %S  -  Highlight subsequent characters */
                       /*          (also known as standout mode). */
                       /*   %s  -  Stop highlighting characters */
                       /*   %%  -  Display a single % character. */
} GlPromptStyle;

/*.......................................................................
 * Specify whether to heed text attribute directives within prompt
 * strings.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  style  GlPromptStyle    The style of prompt (see the definition of
 *                          GlPromptStyle in libtecla.h for details).
 */
void gl_prompt_style(GetLine *gl, GlPromptStyle style);

/*.......................................................................
 * Remove a signal from the list of signals that gl_get_line() traps.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  signo            int    The number of the signal to be ignored.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */
int gl_ignore_signal(GetLine *gl, int signo);

/*
 * A bitwise union of the following enumerators is passed to
 * gl_trap_signal() to specify the environment in which the
 * application's signal handler is to be called.
 */
typedef enum {
  GLS_RESTORE_SIG=1,  /* Restore the caller's signal environment */
                      /* while handling the signal. */
  GLS_RESTORE_TTY=2,  /* Restore the caller's terminal settings */
                      /* while handling the signal. */
  GLS_RESTORE_LINE=4, /* Move the cursor to the start of the next line */
  GLS_REDRAW_LINE=8,  /* Redraw the input line when the signal handler */
                      /*  returns. */
  GLS_UNBLOCK_SIG=16, /* Normally a signal who's delivery is found to */
                      /*  be blocked by the calling application is not */
                      /*  trapped by gl_get_line(). Including this flag */
                      /*  causes it to be temporarily unblocked and */
                      /*  trapped while gl_get_line() is executing. */
  GLS_DONT_FORWARD=32,/* Don't forward the signal to the signal handler */
                      /*  of the calling program. */
  GLS_RESTORE_ENV = GLS_RESTORE_SIG | GLS_RESTORE_TTY | GLS_REDRAW_LINE,
  GLS_SUSPEND_INPUT = GLS_RESTORE_ENV | GLS_RESTORE_LINE
} GlSignalFlags;

/*
 * The following enumerators are passed to gl_trap_signal() to tell
 * it what to do after the application's signal handler has been called.
 */
typedef enum {
  GLS_RETURN,      /* Return the line as though the user had pressed the */
                   /*  return key. */
  GLS_ABORT,       /* Cause gl_get_line() to return NULL */
  GLS_CONTINUE     /* After handling the signal, resume command line editing */
} GlAfterSignal;

/*.......................................................................
 * Tell gl_get_line() how to respond to a given signal. This can be used
 * both to override the default responses to signals that gl_get_line()
 * normally catches and to add new signals to the list that are to be
 * caught.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 *  signo            int    The number of the signal to be caught.
 *  flags       unsigned    A bitwise union of GlSignalFlags enumerators.
 *  after  GlAfterSignal    What to do after the application's signal
 *                          handler has been called.
 *  errno_value      int    The value to set errno to.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Insufficient memory to record the
 *                              new signal disposition.
 */
int gl_trap_signal(GetLine *gl, int signo, unsigned flags,
		   GlAfterSignal after, int errno_value);

/*.......................................................................
 * By default, gl_get_line() doesn't trap signals that are blocked
 * when it is called. This default can be changed either on a
 * per-signal basis by calling gl_trap_signal(), or on a global basis
 * by calling this function. What this function does is add the
 * GLS_UNBLOCK_SIG flag to all signals that are currently configured
 * to be trapped by gl_get_line(), such that when subsequent calls to
 * gl_get_line() wait for I/O, these signals are temporarily
 * unblocked. This behavior is useful in non-blocking server-I/O mode,
 * where it is used to avoid race conditions related to handling these
 * signals externally to gl_get_line(). See the demonstration code in
 * demo3.c, or the gl_handle_signal() man page for further
 * information.
 *
 * Input:
 *  gl         GetLine *   The resource object of gl_get_line().
 */
void gl_catch_blocked(GetLine *gl);

/*.......................................................................
 * In server-I/O mode the terminal is left in raw mode between calls
 * to gl_get_line(), so it is necessary for the application to install
 * terminal restoring signal handlers for signals that could terminate
 * or suspend the process, plus a terminal reconfiguration handler to
 * be called when a process resumption signal is received, and finally
 * a handler to be called when a terminal-resize signal is received.
 *
 * Since there are many signals that by default terminate or suspend
 * processes, and different systems support different sub-sets of
 * these signals, this function provides a convenient wrapper around
 * sigaction() for assigning the specified handlers to all appropriate
 * signals. It also arranges that when any one of these signals is
 * being handled, all other catchable signals are blocked. This is
 * necessary so that the specified signal handlers can safely call
 * gl_raw_io(), gl_normal_io() and gl_update_size() without reentrancy
 * issues.
 *
 * Input:
 *  term_handler  void (*)(int)  The signal handler to invoke when
 *                               a process terminating signal is
 *                               received.
 *  susp_handler  void (*)(int)  The signal handler to invoke when
 *                               a process suspending signal is
 *                               received.
 *  cont_handler  void (*)(int)  The signal handler to invoke when
 *                               a process resumption signal is
 *                               received (ie. SIGCONT).
 *  size_handler  void (*)(int)  The signal handler to invoke when
 *                               a terminal-resize signal (ie. SIGWINCH)
 *                               is received.
 * Output:
 *  return                  int  0 - OK.
 *                               1 - Error.
 */
int gl_tty_signals(void (*term_handler)(int), void (*susp_handler)(int),
		   void (*cont_handler)(int), void (*size_handler)(int));

/*.......................................................................
 * Return the last signal that was caught by the most recent call to
 * gl_get_line(), or -1 if no signals were caught. This is useful if
 * gl_get_line() returns errno=EINTR and you need to find out what signal
 * caused it to abort.
 *
 * Input:
 *  gl           GetLine *  The resource object of gl_get_line().
 * Output:
 *  return           int    The last signal caught by the most recent
 *                          call to gl_get_line(), or -1 if no signals
 *                          were caught.
 */
int gl_last_signal(GetLine *gl);

/*.......................................................................
 * Return the signal mask used by gl_get_line(). This is the set of
 * signals that gl_get_line() is currently configured to trap.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  set       sigset_t *  The set of signals will be returned in *set,
 *                        in the form of a signal process mask, as
 *                        used by sigaction(), sigprocmask(),
 *                        sigpending(), sigsuspend(), sigsetjmp() and
 *                        other standard POSIX signal-aware
 *                        functions.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error (examine errno for reason).
 */
int gl_list_signals(GetLine *gl, sigset_t *set);

/*.......................................................................
 * Respond to signals who's default effects have important
 * consequences to gl_get_line(). This is intended for use in
 * non-blocking server mode, where the external event loop is
 * responsible for catching signals. Signals that are handled include
 * those that by default terminate or suspend the process, and the
 * signal that indicates that the terminal size has changed. Note that
 * this function is not signal safe and should thus not be called from
 * a signal handler itself. See the gl_io_mode() man page for how it
 * should be used.
 *
 * In the case of signals that by default terminate or suspend
 * processes, command-line editing will be suspended, the terminal
 * returned to a usable state, then the default disposition of the
 * signal restored and the signal resent, in order to suspend or
 * terminate the process.  If the process subsequently resumes,
 * command-line editing is resumed.
 *
 * In the case of signals that indicate that the terminal has been
 * resized, the new size will be queried, and any input line that is
 * being edited will be redrawn to fit the new dimensions of the
 * terminal.
 *
 * Input:
 *  signo    int    The number of the signal to respond to.
 *  gl   GetLine *  The first element of an array of 'ngl' GetLine
 *                  objects.
 *  ngl      int    The number of elements in the gl[] array. Normally
 *                  this will be one.
 */
void gl_handle_signal(int signo, GetLine *gl, int ngl);

/*.......................................................................
 * Return extra information (ie. in addition to that provided by errno)
 * about the last error to occur in either gl_get_line() or its
 * associated public functions.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 * Input/Output:
 *  buff          char *  An optional output buffer. Note that if the
 *                        calling application calls any gl_*()
 *                        functions from signal handlers, it should
 *                        provide a buffer here, so that a copy of
 *                        the latest error message can safely be made
 *                        while signals are blocked.
 *  n           size_t    The allocated size of buff[].
 * Output:
 *  return  const char *  A pointer to the error message. This will
 *                        be the buff argument, unless buff==NULL, in
 *                        which case it will be a pointer to an
 *                        internal error buffer. In the latter case,
 *                        note that the contents of the returned buffer
 *                        will change on subsequent calls to any gl_*()
 *                        functions.
 */
const char *gl_error_message(GetLine *gl, char *buff, size_t n);

/*.......................................................................
 * Clear the terminal and leave the cursor at the home position.  In
 * server I/O mode, arrange for the input line to be redrawn from scratch
 * when gl_get_line() is next called.
 *
 * Input:
 *  gl          GetLine *   The resource object of gl_get_line().
 * Output:
 *  return          int     0 - OK.
 *                          1 - Error.
 */
int gl_erase_terminal(GetLine *gl);

/*.......................................................................
 * Display a left-justified string over multiple terminal lines,
 * taking account of the current width of the terminal. Optional
 * indentation and an optional prefix string can be specified to be
 * displayed at the start of each new terminal line used. Similarly,
 * an optional suffix can be specified to be displayed at the end of
 * each terminal line.  If needed, a single paragraph can be broken
 * across multiple calls.  Note that literal newlines in the input
 * string can be used to force a newline at any point and that you
 * should use this feature to explicitly end all paragraphs, including
 * at the end of the last string that you write. Note that when a new
 * line is started between two words that are separated by spaces,
 * those spaces are not output, whereas when a new line is started
 * because a newline character was found in the string, only the
 * spaces before the newline character are discarded.
 *
 * Input:
 *  gl         GetLine *  The resource object of gl_get_line().
 *  indentation    int    The number of spaces of indentation to write
 *                        at the beginning of each new terminal line.
 *  prefix  const char *  An optional prefix string to write after the
 *                        indentation margin at the start of each new
 *                        terminal line. You can specify NULL if no
 *                        prefix is required.
 *  suffix  const char *  An optional suffix string to draw at the end
 *                        of the terminal line. Spaces will be added
 *                        where necessary to ensure that the suffix ends
 *                        in the last column of the terminal line. If
 *                        no suffix is desired, specify NULL.
 *  fill_char      int    The padding character to use when indenting
 *                        the line or padding up to the suffix.
 *  def_width      int    If the terminal width isn't known, such as when
 *                        writing to a pipe or redirecting to a file,
 *                        this number specifies what width to assume.
 *  start          int    The number of characters already written to
 *                        the start of the current terminal line. This
 *                        is primarily used to allow individual
 *                        paragraphs to be written over multiple calls
 *                        to this function, but can also be used to
 *                        allow you to start the first line of a
 *                        paragraph with a different prefix or
 *                        indentation than those specified above.
 *  string  const char *  The string to be written.
 * Output:
 *  return         int    On error -1 is returned. Otherwise the
 *                        return value is the terminal column index at
 *                        which the cursor was left after writing the
 *                        final word in the string. Successful return
 *                        values can thus be passed verbatim to the
 *                        'start' arguments of subsequent calls to
 *                        gl_display_text() to allow the printing of a
 *                        paragraph to be broken across multiple calls
 *                        to gl_display_text().
 */
int gl_display_text(GetLine *gl, int indentation, const char *prefix,
		    const char *suffix, int fill_char, int def_width,
		    int start, const char *string);


/*
 * Enumerate the I/O modes supported by gl_get_line().
 */
typedef enum {
  GL_NORMAL_MODE,    /* Normal line-at-a-time mode using gl_get_line()'s */
                     /*  internal event loop. */
  GL_SERVER_MODE     /* Non-blocking server mode, driven by an external */
                     /*  event loop. */
} GlIOMode;

/*.......................................................................
 * Select the I/O mode to be used by gl_get_line().
 *
 * Input:
 *  gl         GetLine *         The resource object of gl_get_line().
 *  mode      GlIOMode           The I/O mode to establish. Note that
 *                               when server mode, the terminal is placed
 *                               in raw mode, as though gl_raw_io() had
 *                               been called.
 * Output:
 *  return                  int  0 - OK.
 *                               1 - Error.
 */
int gl_io_mode(GetLine *gl, GlIOMode mode);

/*.......................................................................
 * In server mode, this function configures the terminal for non-blocking
 * raw terminal I/O. In normal I/O mode it does nothing.
 *
 * Callers of this function must be careful to trap all signals that
 * terminate or suspend the program, and call gl_normal_io()
 * from the corresponding signal handlers in order to restore the
 * terminal to its original settings before the program is terminated
 * or suspended. They should also trap the SIGCONT signal to detect
 * when the program resumes, and ensure that its signal handler
 * call gl_raw_io() to redisplay the line and resume editing.
 *
 * Input:
 *  gl      GetLine *  The line editor resource object.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
int gl_raw_io(GetLine *gl);

/*.......................................................................
 * Restore the terminal to the state that it had when gl_raw_io() was
 * last called. After calling gl_raw_io(), this function must be called
 * before terminating or suspending the program, and before attempting
 * other uses of the terminal from within the program. See gl_raw_io()
 * for more details.
 *
 * Input:
 *  gl      GetLine *  The line editor resource object.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
int gl_normal_io(GetLine *gl);

/*.......................................................................
 * When in non-blocking server mode, this function can be used to abandon
 * the current incompletely entered input line, and prepare to start
 * editing a new line on the next call to gl_get_line().
 *
 * Input:
 *  gl      GetLine *  The line editor resource object.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */
void gl_abandon_line(GetLine *gl);

/*
 * Enumerators of the following type are used to report why
 * gl_get_line() returned. This is most useful in non-blocking
 * server mode, since in that mode a NULL return value can mean
 * either that an error occurred, or that I/O blocked.
 */
typedef enum {
  GLR_NEWLINE,  /* A new input line was returned */
  GLR_BLOCKED,  /* The terminal was in non-blocking mode, and input */
                /* or output would have blocked. */
  GLR_SIGNAL,   /* A signal caused gl_get_line() to return. */
  GLR_TIMEOUT,  /* An application timeout callback returned GLTO_ABORT */
  GLR_FDABORT,  /* An application I/O callack returned GLFD_ABORT */
  GLR_EOF,      /* End of file reached */
  GLR_ERROR     /* An unexpected error caused gl_get_line() to abort */
} GlReturnStatus;

/*.......................................................................
 * Ask gl_get_line() what caused it to return.
 *
 * Input:
 *  gl             GetLine *  The line editor resource object.
 * Output:
 *  return  GlReturnStatus    The return status of the last call to
 *                            gl_get_line().
 */
GlReturnStatus gl_return_status(GetLine *gl);

/*
 * Enumerate the types of I/O that gl_get_line() can be waiting for
 * in non-blocking sedrver I/O mode.
 */
typedef enum {
  GLP_READ,   /* gl_get_line() is waiting to write to the terminal */
  GLP_WRITE   /* gl_get_line() is waiting to read from the terminal */
} GlPendingIO;

/*.......................................................................
 * In non-blocking server-I/O mode, this function should be called
 * from the application's external event loop to see what type of
 * terminal I/O is being waited for by gl_get_line(), and thus what
 * direction of I/O to wait for with select() or poll().
 *
 * Input:
 *  gl          GetLine *  The resource object of gl_get_line().
 * Output:
 *  return  GlPendingIO    The type of pending I/O being waited for.
 */
GlPendingIO gl_pending_io(GetLine *gl);

/*
 * The following enumerators are returned by externally defined action
 * functions to tell gl_get_line() how to procede after the action
 * function returns.
 */
typedef enum {
  GLA_ABORT,     /* Cause gl_get_line() to return NULL */
  GLA_RETURN,    /* Return the line as though the user had pressed the */
                 /*  return key. */
  GLA_CONTINUE   /* Resume command-line editing */
} GlAfterAction;

/*.......................................................................
 * Functions of the following form implement external
 * application-specific action functions, which can then be bound to
 * sequences of terminal keys.
 *
 * Input:
 *  gl            GetLine *  The line editor resource object.
 *  data             void *  The anonymous 'data' argument that was
 *                           passed to gl_external_action() when the
 *                           callback function was registered.
 *  count             int    A positive repeat count specified by the user,
 *                           or 1 if not specified. Action functions should
 *                           ignore this if repeating the action multiple
 *                           times isn't appropriate. Alternatively they
 *                           can interpret it as a general numeric
 *                           argument.
 *  curpos         size_t    The position of the cursor within the input
 *                           line, expressed as the index of the
 *                           corresponding character within the line[]
 *                           array.
 *  line       const char *  A read-only copy of the current input line.
 * Output
 *  return  GlAfterAction    What should gl_get_line() do when the action
 *                           function returns?
 *                            GLA_ABORT    - Cause gl_get_line() to
 *                                           abort with an error (set
 *                                           errno if you need it).
 *                            GLA_RETURN   - Return the input line as
 *                                           though the user had typed
 *                                           the return key.
 *                            GLA_CONTINUE - Resume waiting for keyboard
 *                                           input.
 */
#define GL_ACTION_FN(fn) GlAfterAction (fn)(GetLine *gl, void *data, \
	      int count, size_t curpos, const char *line)

typedef GL_ACTION_FN(GlActionFn);

/*.......................................................................
 * Register an application-provided function as an action function.
 * This should preferably be called before the first call to gl_get_line()
 * so that the name of the action becomes defined before the user's
 * configuration file is read.
 *
 * Input:
 *  gl            GetLine *  The resource object of the command-line input
 *                           module.
 *  data             void *  Arbitrary application-specific callback
 *                           data to be passed to the callback
 *                           function, fn().
 *  fn         GlActionFn *  The application-specific function that
 *                           implements the action. This will be invoked
 *                           whenever the user presses any
 *                           key-sequence which is bound to this action.
 *  name       const char *  The name with which users can refer to the
 *                           binding in tecla configuration files.
 *  keyseq     const char *  The key sequence with which to invoke
 *                           the binding. This should be specified in the
 *                           same manner as key-sequences in tecla
 *                           configuration files (eg. "M-^I").
 * Output:
 *  return            int    0 - OK.
 *                           1 - Error.
 */
int gl_register_action(GetLine *gl, void *data, GlActionFn *fn,
                       const char *name, const char *keyseq);

/*.......................................................................
 * This function is designed to be called by CPL_MATCH_FN() callback
 * functions. It adds one possible completion of the token that is being
 * completed to an array of completions. If the completion needs any
 * special quoting to be valid when displayed in the input line, this
 * quoting must be included in the string.
 *
 * Input:
 *  cpl      WordCompletion *  The argument of the same name that was passed
 *                             to the calling CPL_MATCH_FN() callback function.
 *  line         const char *  The input line, as received by the callback
 *                             function.
 *  word_start          int    The index within line[] of the start of the
 *                             word that is being completed. If an empty
 *                             string is being completed, set this to be
 *                             the same as word_end.
 *  word_end            int    The index within line[] of the character which
 *                             follows the incomplete word, as received by the
 *                             callback function.
 *  suffix       const char *  The appropriately quoted string that could
 *                             be appended to the incomplete token to complete
 *                             it. A copy of this string will be allocated
 *                             internally.
 *  type_suffix  const char *  When listing multiple completions, gl_get_line()
 *                             appends this string to the completion to indicate
 *                             its type to the user. If not pertinent pass "".
 *                             Otherwise pass a literal or static string.
 *  cont_suffix  const char *  If this turns out to be the only completion,
 *                             gl_get_line() will append this string as
 *                             a continuation. For example, the builtin
 *                             file-completion callback registers a directory
 *                             separator here for directory matches, and a
 *                             space otherwise. If the match were a function
 *                             name you might want to append an open
 *                             parenthesis, etc.. If not relevant pass "".
 *                             Otherwise pass a literal or static string.
 * Output:
 *  return              int    0 - OK.
 *                             1 - Error.
 */
int cpl_add_completion(WordCompletion *cpl, const char *line,
		       int word_start, int word_end, const char *suffix,
		       const char *type_suffix, const char *cont_suffix);

/*
 * Each possible completion string is recorded in an array element of
 * the following type.
 */
typedef struct {
  char *completion;        /* The matching completion string */
  char *suffix;            /* The pointer into completion[] at which the */
                           /*  string was extended. */
  const char *type_suffix; /* A suffix to be added when listing completions */
                           /*  to indicate the type of the completion. */
} CplMatch;

/*
 * Completions are returned in a container of the following form.
 */
typedef struct {
  char *suffix;            /* The common initial part of all of the */
                           /*  completion suffixes. */
  const char *cont_suffix; /* Optional continuation string to be appended to */
                           /*  the sole completion when nmatch==1. */
  CplMatch *matches;       /* The array of possible completion strings, */
                           /*  sorted into lexical order. */
  int nmatch;              /* The number of elements in matches[] */
} CplMatches;

/*.......................................................................
 * Given an input line and the point at which completion is to be
 * attempted, return an array of possible completions.
 *
 * Input:
 *  cpl    WordCompletion *  The word-completion resource object.
 *  line       const char *  The current input line.
 *  word_end          int    The index of the character in line[] which
 *                           follows the end of the token that is being
 *                           completed.
 *  data             void *  Anonymous 'data' to be passed to match_fn().
 *  match_fn   CplMatchFn *  The function that will identify the prefix
 *                           to be completed from the input line, and
 *                           record completion suffixes.
 * Output:
 *  return     CplMatches *  The container of the array of possible
 *                           completions. The returned pointer refers
 *                           to a container owned by the parent Completion
 *                           object, and its contents thus potentially
 *                           change on every call to cpl_complete_word().
 */
CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
			      int word_end, void *data,
			      CplMatchFn *match_fn);

/*.......................................................................
 * Recall the return value of the last call to cpl_complete_word().
 *
 * Input:
 *  cpl    WordCompletion *  The completion resource object.
 * Output:
 *  return     CplMatches *  The container of the array of possible
 *                           completions, as returned by the last call to
 *                           cpl_complete_word(). The returned pointer refers
 *                           to a container owned by the parent WordCompletion
 *                           object, and its contents thus potentially
 *                           change on every call to cpl_complete_word().
 *                           On error, either in the execution of this
 *                           function, or in the last call to
 *                           cpl_complete_word(), NULL is returned, and a
 *                           description of the error can be acquired by
 *                           calling cpl_last_error(cpl).
 */
CplMatches *cpl_recall_matches(WordCompletion *cpl);

/*.......................................................................
 * Print out an array of matching completions.
 *
 * Input:
 *  result  CplMatches *   The container of the sorted array of
 *                         completions.
 *  fp            FILE *   The output stream to write to.
 *  term_width     int     The width of the terminal.
 * Output:
 *  return         int     0 - OK.
 *                         1 - Error.
 */
int cpl_list_completions(CplMatches *result, FILE *fp, int term_width);

/*.......................................................................
 * Return a description of the error that occurred on the last call to
 * cpl_complete_word() or cpl_add_completion().
 *
 * Input:
 *  cpl   WordCompletion *  The string-completion resource object.
 * Output:
 *  return    const char *  The description of the last error.
 */
const char *cpl_last_error(WordCompletion *cpl);

/*
 * PathCache objects encapsulate the resources needed to record
 * files of interest from comma-separated lists of directories.
 */
typedef struct PathCache PathCache;

/*.......................................................................
 * Create an object who's function is to maintain a cache of filenames
 * found within a list of directories, and provide quick lookup and
 * completion of selected files in this cache.
 *
 * Output:
 *  return     PathCache *  The new, initially empty cache, or NULL
 *                          on error.
 */
PathCache *new_PathCache(void);

/*.......................................................................
 * Delete a given cache of files, returning the resources that it
 * was using to the system.
 *
 * Input:
 *  pc      PathCache *  The cache to be deleted (can be NULL).
 * Output:
 *  return  PathCache *  The deleted object (ie. allways NULL).
 */
PathCache *del_PathCache(PathCache *pc);

/*.......................................................................
 * Return a description of the last path-caching error that occurred.
 *
 * Input:
 *  pc     PathCache *   The filename cache that suffered the error.
 * Output:
 *  return      char *   The description of the last error.
 */
const char *pca_last_error(PathCache *pc);

/*.......................................................................
 * Build the list of files of interest contained in a given
 * colon-separated list of directories.
 *
 * Input:
 *  pc         PathCache *  The cache in which to store the names of
 *                          the files that are found in the list of
 *                          directories.
 *  path      const char *  A colon-separated list of directory
 *                          paths. Under UNIX, when searching for
 *                          executables, this should be the return
 *                          value of getenv("PATH").
 * Output:
 *  return           int    0 - OK.
 *                          1 - An error occurred.
 */
int pca_scan_path(PathCache *pc, const char *path);

/*.......................................................................
 * If you want subsequent calls to pca_lookup_file() and
 * pca_path_completions() to only return the filenames of certain
 * types of files, for example executables, or filenames ending in
 * ".ps", call this function to register a file-selection callback
 * function. This callback function takes the full pathname of a file,
 * plus application-specific data, and returns 1 if the file is of
 * interest, and zero otherwise.
 *
 * Input:
 *  pc         PathCache *  The filename cache.
 *  check_fn  CplCheckFn *  The function to call to see if the name of
 *                          a given file should be included in the
 *                          cache. This determines what type of files
 *                          will reside in the cache. To revert to
 *                          selecting all files, regardless of type,
 *                          pass 0 here.
 *  data            void *  You can pass a pointer to anything you
 *                          like here, including NULL. It will be
 *                          passed to your check_fn() callback
 *                          function, for its private use.
 */
void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, void *data);

/*.......................................................................
 * Given the simple name of a file, search the cached list of files
 * in the order in which they where found in the list of directories
 * previously presented to pca_scan_path(), and return the pathname
 * of the first file which has this name.
 *
 * Input:
 *  pc     PathCache *  The cached list of files.
 *  name  const char *  The name of the file to lookup.
 *  name_len     int    The length of the filename substring at the
 *                      beginning of name[], or -1 to assume that the
 *                      filename occupies the whole of the string.
 *  literal      int    If this argument is zero, lone backslashes
 *                      in name[] are ignored during comparison
 *                      with filenames in the cache, under the
 *                      assumption that they were in the input line
 *                      soley to escape the special significance of
 *                      characters like spaces. To have them treated
 *                      as normal characters, give this argument a
 *                      non-zero value, such as 1.
 * Output:
 *  return      char *  The pathname of the first matching file,
 *                      or NULL if not found. Note that the returned
 *                      pointer points to memory owned by *pc, and
 *                      will become invalid on the next call.
 */
char *pca_lookup_file(PathCache *pc, const char *name, int name_len,
		      int literal);

/*
 * Objects of the following type can be used to change the default
 * behavior of the pca_path_completions() callback function.
 */
typedef struct PcaPathConf PcaPathConf;

/*
 * pca_path_completions() is a completion callback function for use directly
 * with cpl_complete_word() or gl_customize_completions(), or indirectly
 * from your own completion callback function. It requires that a PcaPathConf
 * object be passed via its 'void *data' argument (see below).
 */
CPL_MATCH_FN(pca_path_completions);

/*.......................................................................
 * Allocate and initialize a pca_path_completions() configuration object.
 *
 * Input:
 *  pc         PathCache *  The filename cache in which to look for
 *                          file name completions.
 * Output:
 *  return   PcaPathConf *  The new configuration structure, or NULL
 *                          on error.
 */
PcaPathConf *new_PcaPathConf(PathCache *pc);

/*.......................................................................
 * Deallocate memory, previously allocated by new_PcaPathConf().
 *
 * Input:
 *  ppc     PcaPathConf *  Any pointer previously returned by
 *                         new_PcaPathConf() [NULL is allowed].
 * Output:
 *  return  PcaPathConf *  The deleted structure (always NULL).
 */
PcaPathConf *del_PcaPathConf(PcaPathConf *ppc);

/*
 * If backslashes in the prefix being passed to pca_path_completions()
 * should be treated as literal characters, call the following function
 * with literal=1. Otherwise the default is to treat them as escape
 * characters which remove the special meanings of spaces etc..
 */
void ppc_literal_escapes(PcaPathConf *ppc, int literal);

/*
 * Before calling pca_path_completions, call this function if you know
 * the index at which the filename prefix starts in the input line.
 * Otherwise by default, or if you specify start_index to be -1, the
 * filename is taken to start after the first unescaped space preceding
 * the cursor, or the start of the line, whichever comes first.
 */
void ppc_file_start(PcaPathConf *ppc, int start_index);

#ifdef __cplusplus
}
#endif

#endif