A Hacker's Guide to NCURSES                                   Contents     * Abstract     * Objective of the Package          + Why System V Curses?          + How to Design Extensions     * Portability and Configuration     * Documentation Conventions     * How to Report Bugs     * A Tour of the Ncurses Library          + Library Overview          + The Engine Room          + Keyboard Input          + Mouse Events          + Output and Screen Updating     * The Forms and Menu Libraries     * A Tour of the Terminfo Compiler          + Translation of Non-use Capabilities          + Use Capability Resolution          + Source-Form Translation     * Other Utilities     * Style Tips for Developers     * Porting Hints                                   Abstract   This document is a hacker's tour of the ncurses library and utilities.   It  discusses  design  philosophy,  implementation  methods,  and  the   conventions  used  for  coding  and  documentation.  It is recommended   reading  for  anyone  who  is  interested  in  porting,  extending  or   improving the package.                           Objective of the Package   The objective of the ncurses package is to provide a free software API   for character-cell terminals and terminal emulators with the following   characteristics:     * Source-compatible    with    historical   curses   implementations       (including the original BSD curses and System V curses.     * Conformant  with the XSI Curses standard issued as part of XPG4 by       X/Open.     * High-quality  --  stable and reliable code, wide portability, good       packaging, superior documentation.     * Featureful  --  should  eliminate  as  much  of  the drudgery of C       interface programming as possible, freeing programmers to think at       a higher level of design.   These  objectives  are  in  priority  order.  So,  for example, source   compatibility  with  older  version  must  trump  featurefulness -- we   cannot  add  features  if  it  means  breaking  the portion of the API   corresponding to historical curses versions.Why System V Curses?   We  used System V curses as a model, reverse-engineering their API, in   order to fulfill the first two objectives.   System  V  curses implementations can support BSD curses programs with   just a recompilation, so by capturing the System V API we also capture   BSD's.   More  importantly  for  the  future, the XSI Curses standard issued by   X/Open  is  explicitly and closely modeled on System V. So conformance   with System V took us most of the way to base-level XSI conformance.How to Design Extensions   The  third  objective (standards conformance) requires that it be easy   to  condition  source  code  using  ncurses  so  that  the  absence of   nonstandard extensions does not break the code.   Accordingly,  we  have  a  policy of associating with each nonstandard   extension  a  feature  macro, so that ncurses client code can use this   macro  to  condition  in  or  out  the  code that requires the ncurses   extension.   For  example,  there is a macro NCURSES_MOUSE_VERSION which XSI Curses   does  not  define, but which is defined in the ncurses library header.   You can use this to condition the calls to the mouse API calls.                         Portability and Configuration   Code  written  for  ncurses may assume an ANSI-standard C compiler and   POSIX-compatible  OS  interface.  It may also assume the presence of a   System-V-compatible select(2) call.   We encourage (but do not require) developers to make the code friendly   to less-capable UNIX environments wherever possible.   We  encourage  developers  to  support  OS-specific  optimizations and   methods not available under POSIX/ANSI, provided only that:     * All  such  code  is properly conditioned so the build process does       not attempt to compile it under a plain ANSI/POSIX environment.     * Adding    such   implementation   methods   does   not   introduce       incompatibilities in the ncurses API between platforms.   We  use GNU autoconf(1) as a tool to deal with portability issues. The   right way to leverage an OS-specific feature is to modify the autoconf   specification  files  (configure.in  and  aclocal.m4)  to set up a new   feature macro, which you then use to condition your code.                           Documentation Conventions   There  are  three kinds of documentation associated with this package.   Each has a different preferred format:     * Package-internal files (README, INSTALL, TO-DO etc.)     * Manual pages.     * Everything else (i.e., narrative documentation).   Our conventions are simple:    1. Maintain package-internal files in plain text. The expected viewer       for  them  more(1)  or  an  editor  window;  there's  no  point in       elaborate mark-up.    2. Mark  up manual pages in the man macros. These have to be viewable       through traditional man(1) programs.    3. Write everything else in HTML.   When  in  doubt,  HTMLize  a  master and use lynx(1) to generate plain   ASCII (as we do for the announcement document).   The reason for choosing HTML is that it's (a) well-adapted for on-line   browsing through viewers that are everywhere; (b) more easily readable   as  plain  text  than most other mark-ups, if you don't have a viewer;   and   (c)   carries   enough  information  that  you  can  generate  a   nice-looking  printed  version  from  it.  Also,  of  course,  it make   exporting things like the announcement document to WWW pretty trivial.                              How to Report Bugs   The  reporting  address  for  bugs  is  bug-ncurses@gnu.org. This is a   majordomo  list;  to join, write to bug-ncurses-request@gnu.org with a   message containing the line:             subscribe <name>@<host.domain>   The  ncurses  code is maintained by a small group of volunteers. While   we  try  our  best to fix bugs promptly, we simply don't have a lot of   hours  to  spend  on  elementary  hand-holding. We rely on intelligent   cooperation  from  our  users.  If  you  think you have found a bug in   ncurses,  there  are some steps you can take before contacting us that   will help get the bug fixed quickly.   In  order  to  use  our bug-fixing time efficiently, we put people who   show us they've taken these steps at the head of our queue. This means   that  if you don't, you'll probably end up at the tail end and have to   wait a while.    1. Develop a recipe to reproduce the bug.       Bugs  we  can reproduce are likely to be fixed very quickly, often       within  days.  The most effective single thing you can do to get a       quick  fix  is  develop a way we can duplicate the bad behavior --       ideally,  by  giving  us source for a small, portable test program       that  breaks the library. (Even better is a keystroke recipe using       one of the test programs provided with the distribution.)    2. Try to reproduce the bug on a different terminal type.       In  our experience, most of the behaviors people report as library       bugs are actually due to subtle problems in terminal descriptions.       This is especially likely to be true if you're using a traditional       asynchronous  terminal  or PC-based terminal emulator, rather than       xterm or a UNIX console entry.       It's therefore extremely helpful if you can tell us whether or not       your  problem  reproduces  on other terminal types. Usually you'll       have  both  a  console  type  and  xterm available; please tell us       whether or not your bug reproduces on both.       If  you  have  xterm  available,  it is also good to collect xterm       reports for different window sizes. This is especially true if you       normally  use  an unusual xterm window size -- a surprising number       of the bugs we've seen are either triggered or masked by these.    3. Generate and examine a trace file for the broken behavior.       Recompile   your  program  with  the  debugging  versions  of  the       libraries.  Insert  a  trace()  call  with  the  argument  set  to       TRACE_UPDATE.  (See "Writing Programs with NCURSES" for details on       trace  levels.) Reproduce your bug, then look at the trace file to       see what the library was actually doing.       Another  frequent  cause  of  apparent  bugs is application coding       errors  that  cause  the  wrong  things  to  be put on the virtual       screen. Looking at the virtual-screen dumps in the trace file will       tell  you  immediately if this is happening, and save you from the       possible  embarrassment of being told that the bug is in your code       and is your problem rather than ours.       If  the  virtual-screen  dumps  look correct but the bug persists,       it's  possible  to  crank up the trace level to give more and more       information  about  the  library's  update actions and the control       sequences  it  issues  to  perform them. The test directory of the       distribution contains a tool for digesting these logs to make them       less tedious to wade through.       Often you'll find terminfo problems at this stage by noticing that       the  escape  sequences put out for various capabilities are wrong.       If  not,  you're likely to learn enough to be able to characterize       any bug in the screen-update logic quite exactly.    4. Report details and symptoms, not just interpretations.       If  you  do the preceding two steps, it is very likely that you'll       discover the nature of the problem yourself and be able to send us       a  fix.  This  will  create happy feelings all around and earn you       good  karma for the first time you run into a bug you really can't       characterize and fix yourself.       If  you're  still  stuck,  at  least  you'll know what to tell us.       Remember,  we  need  details.  If  you guess about what is safe to       leave out, you are too likely to be wrong.       If  your  bug  produces a bad update, include a trace file. Try to       make  the  trace  at the least voluminous level that pins down the       bug.  Logs  that  have  been through tracemunch are OK, it doesn't       throw   away   any   information  (actually  they're  better  than       un-munched ones because they're easier to read).       If  your bug produces a core-dump, please include a symbolic stack       trace generated by gdb(1) or your local equivalent.       Tell us about every terminal on which you've reproduced the bug --       and  every  terminal on which you can't. Ideally, sent us terminfo       sources for all of these (yours might differ from ours).       Include  your ncurses version and your OS/machine type, of course!       You can find your ncurses version in the curses.h file.   If  your  problem  smells  like a logic error or in cursor movement or   scrolling  or a bad capability, there are a couple of tiny test frames   for  the  library  algorithms in the progs directory that may help you   isolate  it. These are not part of the normal build, but do have their   own make productions.   The   most  important  of  these  is  mvcur,  a  test  frame  for  the   cursor-movement  optimization  code.  With  this  program, you can see   directly  what  control sequences will be emitted for any given cursor   movement or scroll/insert/delete operations. If you think you've got a   bad  capability  identified,  you  can  disable it and test again. The   program is command-driven and has on-line help.   If  you think the vertical-scroll optimization is broken, or just want   to  understand  how it works better, build hashmap and read the header   comments  of hardscroll.c and hashmap.c; then try it out. You can also   test the hardware-scrolling optimization separately with hardscroll.