📄 hackguide.html
字号:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN"><!-- $Id: hackguide.html,v 1.26 2003/10/04 22:34:02 tom Exp $--><HTML><HEAD><TITLE>A Hacker's Guide to Ncurses Internals</TITLE><link rev="made" href="mailto:bugs-ncurses@gnu.org"><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><!--This document is self-contained, *except* that there is one relative link tothe ncurses-intro.html document, expected to be in the same directory withthis one.--></HEAD><BODY><H1>A Hacker's Guide to NCURSES</H1><H1>Contents</H1><UL><LI><A HREF="#abstract">Abstract</A><LI><A HREF="#objective">Objective of the Package</A><UL><LI><A HREF="#whysvr4">Why System V Curses?</A><LI><A HREF="#extensions">How to Design Extensions</A></UL><LI><A HREF="#portability">Portability and Configuration</A><LI><A HREF="#documentation">Documentation Conventions</A><LI><A HREF="#bugtrack">How to Report Bugs</A><LI><A HREF="#ncurslib">A Tour of the Ncurses Library</A><UL><LI><A HREF="#loverview">Library Overview</A><LI><A HREF="#engine">The Engine Room</A><LI><A HREF="#input">Keyboard Input</A><LI><A HREF="#mouse">Mouse Events</A><LI><A HREF="#output">Output and Screen Updating</A></UL><LI><A HREF="#fmnote">The Forms and Menu Libraries</A><LI><A HREF="#tic">A Tour of the Terminfo Compiler</A><UL><LI><A HREF="#nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A><LI><A HREF="#uses">Use Capability Resolution</A><LI><A HREF="#translation">Source-Form Translation</A></UL><LI><A HREF="#utils">Other Utilities</A><LI><A HREF="#style">Style Tips for Developers</A><LI><A HREF="#port">Porting Hints</A></UL><H1><A NAME="abstract">Abstract</A></H1>This document is a hacker's tour of the <STRONG>ncurses</STRONG> library and utilities.It discusses design philosophy, implementation methods, and theconventions used for coding and documentation. It is recommendedreading for anyone who is interested in porting, extending or improving thepackage.<H1><A NAME="objective">Objective of the Package</A></H1>The objective of the <STRONG>ncurses</STRONG> package is to provide a free software API forcharacter-cell terminals and terminal emulators with the followingcharacteristics:<UL><LI>Source-compatible with historical curses implementations (including the original BSD curses and System V curses.<LI>Conformant with the XSI Curses standard issued as part of XPG4 by X/Open.<LI>High-quality -- stable and reliable code, wide portability, good packaging, superior documentation.<LI>Featureful -- should eliminate as much of the drudgery of C interface programming as possible, freeing programmers to think at a higher level of design.</UL>These objectives are in priority order. So, for example, sourcecompatibility with older version must trump featurefulness -- we cannotadd features if it means breaking the portion of the API correspondingto historical curses versions.<H2><A NAME="whysvr4">Why System V Curses?</A></H2>We used System V curses as a model, reverse-engineering their API, inorder to fulfill the first two objectives. <P>System V curses implementations can support BSD curses programs withjust a recompilation, so by capturing the System V API we alsocapture BSD's. <P>More importantly for the future, the XSI Curses standard issued by X/Openis explicitly and closely modeled on System V. So conformance withSystem V took us most of the way to base-level XSI conformance.<H2><A NAME="extensions">How to Design Extensions</A></H2>The third objective (standards conformance) requires that it be easy tocondition source code using <STRONG>ncurses</STRONG> so that the absence of nonstandardextensions does not break the code. <P>Accordingly, we have a policy of associating with each nonstandard extensiona feature macro, so that ncurses client code can use this macro to conditionin or out the code that requires the <STRONG>ncurses</STRONG> extension. <P>For example, there is a macro <CODE>NCURSES_MOUSE_VERSION</CODE> which XSI Cursesdoes not define, but which is defined in the <STRONG>ncurses</STRONG> library header.You can use this to condition the calls to the mouse API calls.<H1><A NAME="portability">Portability and Configuration</A></H1>Code written for <STRONG>ncurses</STRONG> may assume an ANSI-standard C compiler andPOSIX-compatible OS interface. It may also assume the presence of aSystem-V-compatible <EM>select(2)</EM> call. <P>We encourage (but do not require) developers to make the code friendlyto less-capable UNIX environments wherever possible. <P>We encourage developers to support OS-specific optimizations and methodsnot available under POSIX/ANSI, provided only that: <UL><LI>All such code is properly conditioned so the build process does not attempt to compile it under a plain ANSI/POSIX environment.<LI>Adding such implementation methods does not introduce incompatibilities in the <STRONG>ncurses</STRONG> API between platforms.</UL>We use GNU <CODE>autoconf(1)</CODE> as a tool to deal with portability issues.The right way to leverage an OS-specific feature is to modify the autoconfspecification files (configure.in and aclocal.m4) to set up a new featuremacro, which you then use to condition your code.<H1><A NAME="documentation">Documentation Conventions</A></H1>There are three kinds of documentation associated with this package. Eachhas a different preferred format:<UL><LI>Package-internal files (README, INSTALL, TO-DO etc.)<LI>Manual pages.<LI>Everything else (i.e., narrative documentation).</UL>Our conventions are simple:<OL><LI><STRONG>Maintain package-internal files in plain text.</STRONG> The expected viewer for them <EM>more(1)</EM> or an editor window; there's no point in elaborate mark-up.<LI><STRONG>Mark up manual pages in the man macros.</STRONG> These have to be viewable through traditional <EM>man(1)</EM> programs.<LI><STRONG>Write everything else in HTML.</STRONG></OL>When in doubt, HTMLize a master and use <EM>lynx(1)</EM> to generateplain ASCII (as we do for the announcement document). <P>The reason for choosing HTML is that it's (a) well-adapted for on-linebrowsing through viewers that are everywhere; (b) more easily readableas 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 printedversion from it. Also, of course, it make exporting things like theannouncement document to WWW pretty trivial.<H1><A NAME="bugtrack">How to Report Bugs</A></H1>The <A NAME="bugreport">reporting address for bugs</A> is<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>.This is a majordomo list; to join, writeto <CODE>bug-ncurses-request@gnu.org</CODE> with a message containing the line:<PRE> subscribe <name>@<host.domain></PRE>The <CODE>ncurses</CODE> code is maintained by a small group ofvolunteers. While we try our best to fix bugs promptly, we simplydon't have a lot of hours to spend on elementary hand-holding. We relyon intelligent cooperation from our users. If you think you havefound a bug in <CODE>ncurses</CODE>, there are some steps you can takebefore contacting us that will help get the bug fixed quickly. <P>In order to use our bug-fixing time efficiently, we put people whoshow us they've taken these steps at the head of our queue. Thismeans that if you don't, you'll probably end up at the tail end andhave to wait a while.<OL><LI>Develop a recipe to reproduce the bug.<p>Bugs we can reproduce are likely to be fixed very quickly, oftenwithin days. The most effective single thing you can do to get aquick fix is develop a way we can duplicate the bad behavior --ideally, by giving us source for a small, portable test program thatbreaks the library. (Even better is a keystroke recipe using one ofthe test programs provided with the distribution.)<LI>Try to reproduce the bug on a different terminal type. <P>In our experience, most of the behaviors people report as library bugsare actually due to subtle problems in terminal descriptions. This isespecially likely to be true if you're using a traditionalasynchronous terminal or PC-based terminal emulator, rather than xtermor a UNIX console entry. <P>It's therefore extremely helpful if you can tell us whether or not yourproblem reproduces on other terminal types. Usually you'll have botha console type and xterm available; please tell us whether or not yourbug reproduces on both. <P>If you have xterm available, it is also good to collect xterm reports fordifferent window sizes. This is especially true if you normally use anunusual xterm window size -- a surprising number of the bugs we've seenare either triggered or masked by these. <LI>Generate and examine a trace file for the broken behavior. <P>Recompile your program with the debugging versions of the libraries.Insert a <CODE>trace()</CODE> call with the argument set to <CODE>TRACE_UPDATE</CODE>.(See <A HREF="ncurses-intro.html#debugging">"Writing Programs withNCURSES"</A> for details on trace levels.)Reproduce your bug, then look at the trace file to see what the librarywas actually doing. <P>Another frequent cause of apparent bugs is application coding errorsthat cause the wrong things to be put on the virtual screen. Lookingat the virtual-screen dumps in the trace file will tell you immediately ifthis is happening, and save you from the possible embarrassment of beingtold that the bug is in your code and is your problem rather than ours. <P>If the virtual-screen dumps look correct but the bug persists, it'spossible to crank up the trace level to give more and more informationabout the library's update actions and the control sequences it issuesto perform them. The test directory of the distribution contains atool for digesting these logs to make them less tedious to wadethrough. <P>Often you'll find terminfo problems at this stage by noticing that theescape sequences put out for various capabilities are wrong. If not,you're likely to learn enough to be able to characterize any bug inthe screen-update logic quite exactly.<LI>Report details and symptoms, not just interpretations. <P>If you do the preceding two steps, it is very likely that you'll discoverthe nature of the problem yourself and be able to send us a fix. Thiswill create happy feelings all around and earn you good karma for the firsttime you run into a bug you really can't characterize and fix yourself. <P>If you're still stuck, at least you'll know what to tell us. Remember, weneed details. If you guess about what is safe to leave out, you are toolikely to be wrong. <P>If your bug produces a bad update, include a trace file. Try to makethe trace at the <EM>least</EM> voluminous level that pins down thebug. Logs that have been through tracemunch are OK, it doesn't throwaway any information (actually they're better than un-munched ones becausethey're easier to read). <P>If your bug produces a core-dump, please include a symbolic stack tracegenerated by gdb(1) or your local equivalent. <P>Tell us about every terminal on which you've reproduced the bug -- andevery terminal on which you can't. Ideally, sent us terminfo sourcesfor all of these (yours might differ from ours). <P>Include your ncurses version and your OS/machine type, of course! You canfind your ncurses version in the <CODE>curses.h</CODE> file.</OL>If your problem smells like a logic error or in cursor movement orscrolling or a bad capability, there are a couple of tiny test framesfor the library algorithms in the progs directory that may help youisolate it. These are not part of the normal build, but do have theirown make productions. <P>The most important of these is <CODE>mvcur</CODE>, a test frame for thecursor-movement optimization code. With this program, you can seedirectly what control sequences will be emitted for any given cursormovement or scroll/insert/delete operations. If you think you've gota bad capability identified, you can disable it and test again. Theprogram is command-driven and has on-line help. <P>If you think the vertical-scroll optimization is broken, or just want tounderstand how it works better, build <CODE>hashmap</CODE> and read theheader comments of <CODE>hardscroll.c</CODE> and <CODE>hashmap.c</CODE>; then tryit out. You can also test the hardware-scrolling optimization separatelywith <CODE>hardscroll</CODE>. <P>There's one other interactive tester, <CODE>tctest</CODE>, that exercisestranslation between termcap and terminfo formats. If you have a seriousneed to run this, you probably belong on our development team!<H1><A NAME="ncurslib">A Tour of the Ncurses Library</A></H1><H2><A NAME="loverview">Library Overview</A></H2>Most of the library is superstructure -- fairly trivial convenience⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -