usr/src/lib/libtecla/common/history.h

   1 #ifndef history_h
   2 #define history_h
   3
   4 /*
   5  * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
   6  *
   7  * All rights reserved.
   8  *
   9  * Permission is hereby granted, free of charge, to any person obtaining a
  10  * copy of this software and associated documentation files (the
  11  * "Software"), to deal in the Software without restriction, including
  12  * without limitation the rights to use, copy, modify, merge, publish,
  13  * distribute, and/or sell copies of the Software, and to permit persons
  14  * to whom the Software is furnished to do so, provided that the above
  15  * copyright notice(s) and this permission notice appear in all copies of
  16  * the Software and that both the above copyright notice(s) and this
  17  * permission notice appear in supporting documentation.
  18  *
  19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  20  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  21  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
  22  * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
  23  * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
  24  * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
  25  * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  26  * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  27  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  28  *
  29  * Except as contained in this notice, the name of a copyright holder
  30  * shall not be used in advertising or otherwise to promote the sale, use
  31  * or other dealings in this Software without prior written authorization
  32  * of the copyright holder.
  33  */
  34
  35 #pragma ident   "%Z%%M% %I%     %E% SMI"
  36
  37 #include <stdio.h>    /* FILE * */
  38
  39 /*-----------------------------------------------------------------------
  40  * This module is used to record and traverse historical lines of user input.
  41  */
  42
  43 typedef struct GlHistory GlHistory;
  44
  45 /*
  46  * Create a new history maintenance object.
  47  */
  48 GlHistory *_new_GlHistory(size_t buflen);
  49
  50 /*
  51  * Delete a history maintenance object.
  52  */
  53 GlHistory *_del_GlHistory(GlHistory *glh);
  54
  55 int _glh_add_history(GlHistory *glh, const char *line, int force);
  56
  57 int _glh_search_prefix(GlHistory *glh, const char *line, int prefix_len);
  58
  59 char *_glh_find_backwards(GlHistory *glh, char *line, size_t dim);
  60 char *_glh_find_forwards(GlHistory *glh, char *line, size_t dim);
  61
  62 int _glh_cancel_search(GlHistory *glh);
  63
  64 char *_glh_oldest_line(GlHistory *glh, char *line, size_t dim);
  65 char *_glh_current_line(GlHistory *glh, char *line, size_t dim);
  66
  67 /*
  68  * Whenever a new line is added to the history buffer, it is given
  69  * a unique ID, recorded in an object of the following type.
  70  */
  71 typedef unsigned long GlhLineID;
  72
  73 /*
  74  * Query the id of a history line offset by a given number of lines from
  75  * the one that is currently being recalled. If a recall session isn't
  76  * in progress, or the offset points outside the history list, 0 is
  77  * returned.
  78  */
  79 GlhLineID _glh_line_id(GlHistory *glh, int offset);
  80
  81 /*
  82  * Recall a line by its history buffer ID. If the line is no longer
  83  * in the buffer, or the specified id is zero, NULL is returned.
  84  */
  85 char *_glh_recall_line(GlHistory *glh, GlhLineID id, char *line, size_t dim);
  86
  87 /*
  88  * Write the contents of the history buffer to a given file. Note that
  89  * ~ and $ expansion are not performed on the filename.
  90  */
  91 int _glh_save_history(GlHistory *glh, const char *filename,
  92                       const char *comment, int max_lines);
  93
  94 /*
  95  * Restore the contents of the history buffer from a given file.
  96  * Note that ~ and $ expansion are not performed on the filename.
  97  */
  98 int _glh_load_history(GlHistory *glh, const char *filename, const char *comment,
  99                       char *line, size_t dim);
 100
 101 /*
 102  * Set and query the current history group.
 103  */
 104 int _glh_set_group(GlHistory *glh, unsigned group);
 105 int _glh_get_group(GlHistory *glh);
 106
 107 /*
 108  * Display the contents of the history list to the specified stdio
 109  * output group.
 110  */
 111 int _glh_show_history(GlHistory *glh, GlWriteFn *write_fn, void *data,
 112                       const char *fmt, int all_groups, int max_lines);
 113
 114 /*
 115  * Change the size of the history buffer.
 116  */
 117 int _glh_resize_history(GlHistory *glh, size_t bufsize);
 118
 119 /*
 120  * Set an upper limit to the number of lines that can be recorded in the
 121  * history list, or remove a previously specified limit.
 122  */
 123 void _glh_limit_history(GlHistory *glh, int max_lines);
 124
 125 /*
 126  * Discard either all history, or the history associated with the current
 127  * history group.
 128  */
 129 void _glh_clear_history(GlHistory *glh, int all_groups);
 130
 131 /*
 132  * Temporarily enable or disable the history facility.
 133  */
 134 void _glh_toggle_history(GlHistory *glh, int enable);
 135
 136 /*
 137  * Lookup a history line by its sequential number of entry in the
 138  * history buffer.
 139  */
 140 int _glh_lookup_history(GlHistory *glh, GlhLineID id, const char **line,
 141                         unsigned *group, time_t *timestamp);
 142
 143 /*
 144  * Query the state of the history list.
 145  */
 146 void _glh_state_of_history(GlHistory *glh, int *enabled, unsigned *group,
 147                            int *max_lines);
 148
 149 /*
 150  * Get the range of lines in the history buffer.
 151  */
 152 void _glh_range_of_history(GlHistory *glh, unsigned long *oldest,
 153                            unsigned long *newest, int *nlines);
 154
 155 /*
 156  * Return the size of the history buffer and the amount of the
 157  * buffer that is currently in use.
 158  */
 159 void _glh_size_of_history(GlHistory *glh, size_t *buff_size, size_t *buff_used);
 160
 161 /*
 162  * Get information about the last error in this module.
 163  */
 164 const char *_glh_last_error(GlHistory *glh);
 165
 166 /*
 167  * Return non-zero if a history search session is currently in progress.
 168  */
 169 int _glh_search_active(GlHistory *glh);
 170
 171 #endif