115589c42SPeter Wemm<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> 215589c42SPeter Wemm<!-- 3*4a1a9510SRong-En Fan $Id: hackguide.html,v 1.29 2013/05/17 23:29:18 tom Exp $ 4*4a1a9510SRong-En Fan **************************************************************************** 5*4a1a9510SRong-En Fan * Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. * 6*4a1a9510SRong-En Fan * * 7*4a1a9510SRong-En Fan * Permission is hereby granted, free of charge, to any person obtaining a * 8*4a1a9510SRong-En Fan * copy of this software and associated documentation files (the * 9*4a1a9510SRong-En Fan * "Software"), to deal in the Software without restriction, including * 10*4a1a9510SRong-En Fan * without limitation the rights to use, copy, modify, merge, publish, * 11*4a1a9510SRong-En Fan * distribute, distribute with modifications, sublicense, and/or sell * 12*4a1a9510SRong-En Fan * copies of the Software, and to permit persons to whom the Software is * 13*4a1a9510SRong-En Fan * furnished to do so, subject to the following conditions: * 14*4a1a9510SRong-En Fan * * 15*4a1a9510SRong-En Fan * The above copyright notice and this permission notice shall be included * 16*4a1a9510SRong-En Fan * in all copies or substantial portions of the Software. * 17*4a1a9510SRong-En Fan * * 18*4a1a9510SRong-En Fan * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * 19*4a1a9510SRong-En Fan * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * 20*4a1a9510SRong-En Fan * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * 21*4a1a9510SRong-En Fan * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * 22*4a1a9510SRong-En Fan * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * 23*4a1a9510SRong-En Fan * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * 24*4a1a9510SRong-En Fan * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * 25*4a1a9510SRong-En Fan * * 26*4a1a9510SRong-En Fan * Except as contained in this notice, the name(s) of the above copyright * 27*4a1a9510SRong-En Fan * holders shall not be used in advertising or otherwise to promote the * 28*4a1a9510SRong-En Fan * sale, use or other dealings in this Software without prior written * 29*4a1a9510SRong-En Fan * authorization. * 30*4a1a9510SRong-En Fan **************************************************************************** 3115589c42SPeter Wemm--> 3215589c42SPeter Wemm<HTML> 3315589c42SPeter Wemm<HEAD> 3415589c42SPeter Wemm<TITLE>A Hacker's Guide to Ncurses Internals</TITLE> 3515589c42SPeter Wemm<link rev="made" href="mailto:[email protected]"> 36*4a1a9510SRong-En Fan<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 3715589c42SPeter Wemm<!-- 3815589c42SPeter WemmThis document is self-contained, *except* that there is one relative link to 3915589c42SPeter Wemmthe ncurses-intro.html document, expected to be in the same directory with 4015589c42SPeter Wemmthis one. 4115589c42SPeter Wemm--> 4215589c42SPeter Wemm</HEAD> 4315589c42SPeter Wemm<BODY> 4415589c42SPeter Wemm 4515589c42SPeter Wemm<H1>A Hacker's Guide to NCURSES</H1> 4615589c42SPeter Wemm 4715589c42SPeter Wemm<H1>Contents</H1> 4815589c42SPeter Wemm<UL> 4915589c42SPeter Wemm<LI><A HREF="#abstract">Abstract</A> 5015589c42SPeter Wemm<LI><A HREF="#objective">Objective of the Package</A> 5115589c42SPeter Wemm<UL> 5215589c42SPeter Wemm<LI><A HREF="#whysvr4">Why System V Curses?</A> 5315589c42SPeter Wemm<LI><A HREF="#extensions">How to Design Extensions</A> 5415589c42SPeter Wemm</UL> 5515589c42SPeter Wemm<LI><A HREF="#portability">Portability and Configuration</A> 5615589c42SPeter Wemm<LI><A HREF="#documentation">Documentation Conventions</A> 5715589c42SPeter Wemm<LI><A HREF="#bugtrack">How to Report Bugs</A> 5815589c42SPeter Wemm<LI><A HREF="#ncurslib">A Tour of the Ncurses Library</A> 5915589c42SPeter Wemm<UL> 6015589c42SPeter Wemm<LI><A HREF="#loverview">Library Overview</A> 6115589c42SPeter Wemm<LI><A HREF="#engine">The Engine Room</A> 6215589c42SPeter Wemm<LI><A HREF="#input">Keyboard Input</A> 6315589c42SPeter Wemm<LI><A HREF="#mouse">Mouse Events</A> 6415589c42SPeter Wemm<LI><A HREF="#output">Output and Screen Updating</A> 6515589c42SPeter Wemm</UL> 6615589c42SPeter Wemm<LI><A HREF="#fmnote">The Forms and Menu Libraries</A> 6715589c42SPeter Wemm<LI><A HREF="#tic">A Tour of the Terminfo Compiler</A> 6815589c42SPeter Wemm<UL> 6915589c42SPeter Wemm<LI><A HREF="#nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A> 7015589c42SPeter Wemm<LI><A HREF="#uses">Use Capability Resolution</A> 7115589c42SPeter Wemm<LI><A HREF="#translation">Source-Form Translation</A> 7215589c42SPeter Wemm</UL> 7315589c42SPeter Wemm<LI><A HREF="#utils">Other Utilities</A> 7415589c42SPeter Wemm<LI><A HREF="#style">Style Tips for Developers</A> 7515589c42SPeter Wemm<LI><A HREF="#port">Porting Hints</A> 7615589c42SPeter Wemm</UL> 7715589c42SPeter Wemm 7815589c42SPeter Wemm<H1><A NAME="abstract">Abstract</A></H1> 7915589c42SPeter Wemm 8015589c42SPeter WemmThis document is a hacker's tour of the <STRONG>ncurses</STRONG> library and utilities. 8115589c42SPeter WemmIt discusses design philosophy, implementation methods, and the 8215589c42SPeter Wemmconventions used for coding and documentation. It is recommended 8315589c42SPeter Wemmreading for anyone who is interested in porting, extending or improving the 8415589c42SPeter Wemmpackage. 8515589c42SPeter Wemm 8615589c42SPeter Wemm<H1><A NAME="objective">Objective of the Package</A></H1> 8715589c42SPeter Wemm 8815589c42SPeter WemmThe objective of the <STRONG>ncurses</STRONG> package is to provide a free software API for 8915589c42SPeter Wemmcharacter-cell terminals and terminal emulators with the following 9015589c42SPeter Wemmcharacteristics: 9115589c42SPeter Wemm 9215589c42SPeter Wemm<UL> 9315589c42SPeter Wemm<LI>Source-compatible with historical curses implementations (including 9415589c42SPeter Wemm the original BSD curses and System V curses. 9515589c42SPeter Wemm<LI>Conformant with the XSI Curses standard issued as part of XPG4 by 9615589c42SPeter Wemm X/Open. 9715589c42SPeter Wemm<LI>High-quality -- stable and reliable code, wide portability, good 9815589c42SPeter Wemm packaging, superior documentation. 9915589c42SPeter Wemm<LI>Featureful -- should eliminate as much of the drudgery of C interface 10015589c42SPeter Wemm programming as possible, freeing programmers to think at a higher 10115589c42SPeter Wemm level of design. 10215589c42SPeter Wemm</UL> 10315589c42SPeter Wemm 10415589c42SPeter WemmThese objectives are in priority order. So, for example, source 10515589c42SPeter Wemmcompatibility with older version must trump featurefulness -- we cannot 10615589c42SPeter Wemmadd features if it means breaking the portion of the API corresponding 10715589c42SPeter Wemmto historical curses versions. 10815589c42SPeter Wemm 10915589c42SPeter Wemm<H2><A NAME="whysvr4">Why System V Curses?</A></H2> 11015589c42SPeter Wemm 11115589c42SPeter WemmWe used System V curses as a model, reverse-engineering their API, in 11215589c42SPeter Wemmorder to fulfill the first two objectives. <P> 11315589c42SPeter Wemm 11415589c42SPeter WemmSystem V curses implementations can support BSD curses programs with 11515589c42SPeter Wemmjust a recompilation, so by capturing the System V API we also 11615589c42SPeter Wemmcapture BSD's. <P> 11715589c42SPeter Wemm 11815589c42SPeter WemmMore importantly for the future, the XSI Curses standard issued by X/Open 11915589c42SPeter Wemmis explicitly and closely modeled on System V. So conformance with 12015589c42SPeter WemmSystem V took us most of the way to base-level XSI conformance. 12115589c42SPeter Wemm 12215589c42SPeter Wemm<H2><A NAME="extensions">How to Design Extensions</A></H2> 12315589c42SPeter Wemm 12415589c42SPeter WemmThe third objective (standards conformance) requires that it be easy to 12515589c42SPeter Wemmcondition source code using <STRONG>ncurses</STRONG> so that the absence of nonstandard 12615589c42SPeter Wemmextensions does not break the code. <P> 12715589c42SPeter Wemm 12815589c42SPeter WemmAccordingly, we have a policy of associating with each nonstandard extension 12915589c42SPeter Wemma feature macro, so that ncurses client code can use this macro to condition 13015589c42SPeter Wemmin or out the code that requires the <STRONG>ncurses</STRONG> extension. <P> 13115589c42SPeter Wemm 13215589c42SPeter WemmFor example, there is a macro <CODE>NCURSES_MOUSE_VERSION</CODE> which XSI Curses 13315589c42SPeter Wemmdoes not define, but which is defined in the <STRONG>ncurses</STRONG> library header. 13415589c42SPeter WemmYou can use this to condition the calls to the mouse API calls. 13515589c42SPeter Wemm 13615589c42SPeter Wemm<H1><A NAME="portability">Portability and Configuration</A></H1> 13715589c42SPeter Wemm 13815589c42SPeter WemmCode written for <STRONG>ncurses</STRONG> may assume an ANSI-standard C compiler and 13915589c42SPeter WemmPOSIX-compatible OS interface. It may also assume the presence of a 14015589c42SPeter WemmSystem-V-compatible <EM>select(2)</EM> call. <P> 14115589c42SPeter Wemm 14215589c42SPeter WemmWe encourage (but do not require) developers to make the code friendly 14315589c42SPeter Wemmto less-capable UNIX environments wherever possible. <P> 14415589c42SPeter Wemm 14515589c42SPeter WemmWe encourage developers to support OS-specific optimizations and methods 14615589c42SPeter Wemmnot available under POSIX/ANSI, provided only that: 14715589c42SPeter Wemm 14815589c42SPeter Wemm<UL> 14915589c42SPeter Wemm<LI>All such code is properly conditioned so the build process does not 15015589c42SPeter Wemm attempt to compile it under a plain ANSI/POSIX environment. 15115589c42SPeter Wemm<LI>Adding such implementation methods does not introduce incompatibilities 15215589c42SPeter Wemm in the <STRONG>ncurses</STRONG> API between platforms. 15315589c42SPeter Wemm</UL> 15415589c42SPeter Wemm 15515589c42SPeter WemmWe use GNU <CODE>autoconf(1)</CODE> as a tool to deal with portability issues. 15615589c42SPeter WemmThe right way to leverage an OS-specific feature is to modify the autoconf 15715589c42SPeter Wemmspecification files (configure.in and aclocal.m4) to set up a new feature 15815589c42SPeter Wemmmacro, which you then use to condition your code. 15915589c42SPeter Wemm 16015589c42SPeter Wemm<H1><A NAME="documentation">Documentation Conventions</A></H1> 16115589c42SPeter Wemm 16215589c42SPeter WemmThere are three kinds of documentation associated with this package. Each 16315589c42SPeter Wemmhas a different preferred format: 16415589c42SPeter Wemm 16515589c42SPeter Wemm<UL> 16615589c42SPeter Wemm<LI>Package-internal files (README, INSTALL, TO-DO etc.) 16715589c42SPeter Wemm<LI>Manual pages. 16815589c42SPeter Wemm<LI>Everything else (i.e., narrative documentation). 16915589c42SPeter Wemm</UL> 17015589c42SPeter Wemm 17115589c42SPeter WemmOur conventions are simple: 17215589c42SPeter Wemm<OL> 17315589c42SPeter Wemm<LI><STRONG>Maintain package-internal files in plain text.</STRONG> 17415589c42SPeter Wemm The expected viewer for them <EM>more(1)</EM> or an editor window; there's 17515589c42SPeter Wemm no point in elaborate mark-up. 17615589c42SPeter Wemm 17715589c42SPeter Wemm<LI><STRONG>Mark up manual pages in the man macros.</STRONG> These have to be viewable 17815589c42SPeter Wemm through traditional <EM>man(1)</EM> programs. 17915589c42SPeter Wemm 18015589c42SPeter Wemm<LI><STRONG>Write everything else in HTML.</STRONG> 18115589c42SPeter Wemm</OL> 18215589c42SPeter Wemm 18315589c42SPeter WemmWhen in doubt, HTMLize a master and use <EM>lynx(1)</EM> to generate 18415589c42SPeter Wemmplain ASCII (as we do for the announcement document). <P> 18515589c42SPeter Wemm 18615589c42SPeter WemmThe reason for choosing HTML is that it's (a) well-adapted for on-line 18715589c42SPeter Wemmbrowsing through viewers that are everywhere; (b) more easily readable 18815589c42SPeter Wemmas plain text than most other mark-ups, if you don't have a viewer; and (c) 18915589c42SPeter Wemmcarries enough information that you can generate a nice-looking printed 19015589c42SPeter Wemmversion from it. Also, of course, it make exporting things like the 19115589c42SPeter Wemmannouncement document to WWW pretty trivial. 19215589c42SPeter Wemm 19315589c42SPeter Wemm<H1><A NAME="bugtrack">How to Report Bugs</A></H1> 19415589c42SPeter Wemm 19515589c42SPeter WemmThe <A NAME="bugreport">reporting address for bugs</A> is 19615589c42SPeter Wemm<A HREF="mailto:[email protected]">[email protected]</A>. 19715589c42SPeter WemmThis is a majordomo list; to join, write 19815589c42SPeter Wemmto <CODE>[email protected]</CODE> with a message containing the line: 19915589c42SPeter Wemm<PRE> 20015589c42SPeter Wemm subscribe <name>@<host.domain> 20115589c42SPeter Wemm</PRE> 20215589c42SPeter Wemm 20315589c42SPeter WemmThe <CODE>ncurses</CODE> code is maintained by a small group of 20415589c42SPeter Wemmvolunteers. While we try our best to fix bugs promptly, we simply 20515589c42SPeter Wemmdon't have a lot of hours to spend on elementary hand-holding. We rely 20615589c42SPeter Wemmon intelligent cooperation from our users. If you think you have 20715589c42SPeter Wemmfound a bug in <CODE>ncurses</CODE>, there are some steps you can take 20815589c42SPeter Wemmbefore contacting us that will help get the bug fixed quickly. <P> 20915589c42SPeter Wemm 21015589c42SPeter WemmIn order to use our bug-fixing time efficiently, we put people who 21115589c42SPeter Wemmshow us they've taken these steps at the head of our queue. This 21215589c42SPeter Wemmmeans that if you don't, you'll probably end up at the tail end and 21315589c42SPeter Wemmhave to wait a while. 21415589c42SPeter Wemm 21515589c42SPeter Wemm<OL> 21615589c42SPeter Wemm<LI>Develop a recipe to reproduce the bug. 21715589c42SPeter Wemm<p> 21815589c42SPeter WemmBugs we can reproduce are likely to be fixed very quickly, often 21915589c42SPeter Wemmwithin days. The most effective single thing you can do to get a 22015589c42SPeter Wemmquick fix is develop a way we can duplicate the bad behavior -- 22115589c42SPeter Wemmideally, by giving us source for a small, portable test program that 22215589c42SPeter Wemmbreaks the library. (Even better is a keystroke recipe using one of 22315589c42SPeter Wemmthe test programs provided with the distribution.) 22415589c42SPeter Wemm 22515589c42SPeter Wemm<LI>Try to reproduce the bug on a different terminal type. <P> 22615589c42SPeter Wemm 22715589c42SPeter WemmIn our experience, most of the behaviors people report as library bugs 22815589c42SPeter Wemmare actually due to subtle problems in terminal descriptions. This is 22915589c42SPeter Wemmespecially likely to be true if you're using a traditional 23015589c42SPeter Wemmasynchronous terminal or PC-based terminal emulator, rather than xterm 23115589c42SPeter Wemmor a UNIX console entry. <P> 23215589c42SPeter Wemm 23315589c42SPeter WemmIt's therefore extremely helpful if you can tell us whether or not your 23415589c42SPeter Wemmproblem reproduces on other terminal types. Usually you'll have both 23515589c42SPeter Wemma console type and xterm available; please tell us whether or not your 23615589c42SPeter Wemmbug reproduces on both. <P> 23715589c42SPeter Wemm 23815589c42SPeter WemmIf you have xterm available, it is also good to collect xterm reports for 23915589c42SPeter Wemmdifferent window sizes. This is especially true if you normally use an 24015589c42SPeter Wemmunusual xterm window size -- a surprising number of the bugs we've seen 24115589c42SPeter Wemmare either triggered or masked by these. 24215589c42SPeter Wemm 24315589c42SPeter Wemm<LI>Generate and examine a trace file for the broken behavior. <P> 24415589c42SPeter Wemm 24515589c42SPeter WemmRecompile your program with the debugging versions of the libraries. 24615589c42SPeter WemmInsert a <CODE>trace()</CODE> call with the argument set to <CODE>TRACE_UPDATE</CODE>. 24715589c42SPeter Wemm(See <A HREF="ncurses-intro.html#debugging">"Writing Programs with 24815589c42SPeter WemmNCURSES"</A> for details on trace levels.) 24915589c42SPeter WemmReproduce your bug, then look at the trace file to see what the library 25015589c42SPeter Wemmwas actually doing. <P> 25115589c42SPeter Wemm 25215589c42SPeter WemmAnother frequent cause of apparent bugs is application coding errors 25315589c42SPeter Wemmthat cause the wrong things to be put on the virtual screen. Looking 25415589c42SPeter Wemmat the virtual-screen dumps in the trace file will tell you immediately if 25515589c42SPeter Wemmthis is happening, and save you from the possible embarrassment of being 25615589c42SPeter Wemmtold that the bug is in your code and is your problem rather than ours. <P> 25715589c42SPeter Wemm 25815589c42SPeter WemmIf the virtual-screen dumps look correct but the bug persists, it's 25915589c42SPeter Wemmpossible to crank up the trace level to give more and more information 26015589c42SPeter Wemmabout the library's update actions and the control sequences it issues 26115589c42SPeter Wemmto perform them. The test directory of the distribution contains a 26215589c42SPeter Wemmtool for digesting these logs to make them less tedious to wade 26315589c42SPeter Wemmthrough. <P> 26415589c42SPeter Wemm 26515589c42SPeter WemmOften you'll find terminfo problems at this stage by noticing that the 26615589c42SPeter Wemmescape sequences put out for various capabilities are wrong. If not, 26715589c42SPeter Wemmyou're likely to learn enough to be able to characterize any bug in 26815589c42SPeter Wemmthe screen-update logic quite exactly. 26915589c42SPeter Wemm 27015589c42SPeter Wemm<LI>Report details and symptoms, not just interpretations. <P> 27115589c42SPeter Wemm 27215589c42SPeter WemmIf you do the preceding two steps, it is very likely that you'll discover 27315589c42SPeter Wemmthe nature of the problem yourself and be able to send us a fix. This 27415589c42SPeter Wemmwill create happy feelings all around and earn you good karma for the first 27515589c42SPeter Wemmtime you run into a bug you really can't characterize and fix yourself. <P> 27615589c42SPeter Wemm 27715589c42SPeter WemmIf you're still stuck, at least you'll know what to tell us. Remember, we 27815589c42SPeter Wemmneed details. If you guess about what is safe to leave out, you are too 27915589c42SPeter Wemmlikely to be wrong. <P> 28015589c42SPeter Wemm 28115589c42SPeter WemmIf your bug produces a bad update, include a trace file. Try to make 28215589c42SPeter Wemmthe trace at the <EM>least</EM> voluminous level that pins down the 28315589c42SPeter Wemmbug. Logs that have been through tracemunch are OK, it doesn't throw 28415589c42SPeter Wemmaway any information (actually they're better than un-munched ones because 28515589c42SPeter Wemmthey're easier to read). <P> 28615589c42SPeter Wemm 28715589c42SPeter WemmIf your bug produces a core-dump, please include a symbolic stack trace 28815589c42SPeter Wemmgenerated by gdb(1) or your local equivalent. <P> 28915589c42SPeter Wemm 29015589c42SPeter WemmTell us about every terminal on which you've reproduced the bug -- and 29115589c42SPeter Wemmevery terminal on which you can't. Ideally, sent us terminfo sources 29215589c42SPeter Wemmfor all of these (yours might differ from ours). <P> 29315589c42SPeter Wemm 29415589c42SPeter WemmInclude your ncurses version and your OS/machine type, of course! You can 29515589c42SPeter Wemmfind your ncurses version in the <CODE>curses.h</CODE> file. 29615589c42SPeter Wemm</OL> 29715589c42SPeter Wemm 29815589c42SPeter WemmIf your problem smells like a logic error or in cursor movement or 29915589c42SPeter Wemmscrolling or a bad capability, there are a couple of tiny test frames 30015589c42SPeter Wemmfor the library algorithms in the progs directory that may help you 30115589c42SPeter Wemmisolate it. These are not part of the normal build, but do have their 30215589c42SPeter Wemmown make productions. <P> 30315589c42SPeter Wemm 30415589c42SPeter WemmThe most important of these is <CODE>mvcur</CODE>, a test frame for the 30515589c42SPeter Wemmcursor-movement optimization code. With this program, you can see 30615589c42SPeter Wemmdirectly what control sequences will be emitted for any given cursor 30715589c42SPeter Wemmmovement or scroll/insert/delete operations. If you think you've got 30815589c42SPeter Wemma bad capability identified, you can disable it and test again. The 30915589c42SPeter Wemmprogram is command-driven and has on-line help. <P> 31015589c42SPeter Wemm 31115589c42SPeter WemmIf you think the vertical-scroll optimization is broken, or just want to 31215589c42SPeter Wemmunderstand how it works better, build <CODE>hashmap</CODE> and read the 31315589c42SPeter Wemmheader comments of <CODE>hardscroll.c</CODE> and <CODE>hashmap.c</CODE>; then try 31415589c42SPeter Wemmit out. You can also test the hardware-scrolling optimization separately 31515589c42SPeter Wemmwith <CODE>hardscroll</CODE>. <P> 31615589c42SPeter Wemm 31715589c42SPeter Wemm<H1><A NAME="ncurslib">A Tour of the Ncurses Library</A></H1> 31815589c42SPeter Wemm 31915589c42SPeter Wemm<H2><A NAME="loverview">Library Overview</A></H2> 32015589c42SPeter Wemm 32115589c42SPeter WemmMost of the library is superstructure -- fairly trivial convenience 32215589c42SPeter Wemminterfaces to a small set of basic functions and data structures used 32315589c42SPeter Wemmto manipulate the virtual screen (in particular, none of this code 32415589c42SPeter Wemmdoes any I/O except through calls to more fundamental modules 32515589c42SPeter Wemmdescribed below). The files 32615589c42SPeter Wemm<blockquote> 32715589c42SPeter Wemm<CODE> 32815589c42SPeter Wemmlib_addch.c 32915589c42SPeter Wemmlib_bkgd.c 33015589c42SPeter Wemmlib_box.c 33115589c42SPeter Wemmlib_chgat.c 33215589c42SPeter Wemmlib_clear.c 33315589c42SPeter Wemmlib_clearok.c 33415589c42SPeter Wemmlib_clrbot.c 33515589c42SPeter Wemmlib_clreol.c 33615589c42SPeter Wemmlib_colorset.c 33715589c42SPeter Wemmlib_data.c 33815589c42SPeter Wemmlib_delch.c 33915589c42SPeter Wemmlib_delwin.c 34015589c42SPeter Wemmlib_echo.c 34115589c42SPeter Wemmlib_erase.c 34215589c42SPeter Wemmlib_gen.c 34315589c42SPeter Wemmlib_getstr.c 34415589c42SPeter Wemmlib_hline.c 34515589c42SPeter Wemmlib_immedok.c 34615589c42SPeter Wemmlib_inchstr.c 34715589c42SPeter Wemmlib_insch.c 34815589c42SPeter Wemmlib_insdel.c 34915589c42SPeter Wemmlib_insstr.c 35015589c42SPeter Wemmlib_instr.c 35115589c42SPeter Wemmlib_isendwin.c 35215589c42SPeter Wemmlib_keyname.c 35315589c42SPeter Wemmlib_leaveok.c 35415589c42SPeter Wemmlib_move.c 35515589c42SPeter Wemmlib_mvwin.c 35615589c42SPeter Wemmlib_overlay.c 35715589c42SPeter Wemmlib_pad.c 35815589c42SPeter Wemmlib_printw.c 35915589c42SPeter Wemmlib_redrawln.c 36015589c42SPeter Wemmlib_scanw.c 36115589c42SPeter Wemmlib_screen.c 36215589c42SPeter Wemmlib_scroll.c 36315589c42SPeter Wemmlib_scrollok.c 36415589c42SPeter Wemmlib_scrreg.c 36515589c42SPeter Wemmlib_set_term.c 36615589c42SPeter Wemmlib_slk.c 36715589c42SPeter Wemmlib_slkatr_set.c 36815589c42SPeter Wemmlib_slkatrof.c 36915589c42SPeter Wemmlib_slkatron.c 37015589c42SPeter Wemmlib_slkatrset.c 37115589c42SPeter Wemmlib_slkattr.c 37215589c42SPeter Wemmlib_slkclear.c 37315589c42SPeter Wemmlib_slkcolor.c 37415589c42SPeter Wemmlib_slkinit.c 37515589c42SPeter Wemmlib_slklab.c 37615589c42SPeter Wemmlib_slkrefr.c 37715589c42SPeter Wemmlib_slkset.c 37815589c42SPeter Wemmlib_slktouch.c 37915589c42SPeter Wemmlib_touch.c 38015589c42SPeter Wemmlib_unctrl.c 38115589c42SPeter Wemmlib_vline.c 38215589c42SPeter Wemmlib_wattroff.c 38315589c42SPeter Wemmlib_wattron.c 38415589c42SPeter Wemmlib_window.c 38515589c42SPeter Wemm</CODE> 38615589c42SPeter Wemm</blockquote> 38715589c42SPeter Wemmare all in this category. They are very 38815589c42SPeter Wemmunlikely to need change, barring bugs or some fundamental 38915589c42SPeter Wemmreorganization in the underlying data structures. <P> 39015589c42SPeter Wemm 39115589c42SPeter WemmThese files are used only for debugging support: 39215589c42SPeter Wemm<blockquote> 39315589c42SPeter Wemm<code> 39415589c42SPeter Wemmlib_trace.c 39515589c42SPeter Wemmlib_traceatr.c 39615589c42SPeter Wemmlib_tracebits.c 39715589c42SPeter Wemmlib_tracechr.c 39815589c42SPeter Wemmlib_tracedmp.c 39915589c42SPeter Wemmlib_tracemse.c 40015589c42SPeter Wemmtrace_buf.c 40115589c42SPeter Wemm</code> 40215589c42SPeter Wemm</blockquote> 40315589c42SPeter WemmIt is rather unlikely you will ever need to change these, unless 404*4a1a9510SRong-En Fanyou want to introduce a new debug trace level for some reason.<P> 40515589c42SPeter Wemm 40615589c42SPeter WemmThere is another group of files that do direct I/O via <EM>tputs()</EM>, 40715589c42SPeter Wemmcomputations on the terminal capabilities, or queries to the OS 40815589c42SPeter Wemmenvironment, but nevertheless have only fairly low complexity. These 40915589c42SPeter Wemminclude: 41015589c42SPeter Wemm<blockquote> 41115589c42SPeter Wemm<code> 41215589c42SPeter Wemmlib_acs.c 41315589c42SPeter Wemmlib_beep.c 41415589c42SPeter Wemmlib_color.c 41515589c42SPeter Wemmlib_endwin.c 41615589c42SPeter Wemmlib_initscr.c 41715589c42SPeter Wemmlib_longname.c 41815589c42SPeter Wemmlib_newterm.c 41915589c42SPeter Wemmlib_options.c 42015589c42SPeter Wemmlib_termcap.c 42115589c42SPeter Wemmlib_ti.c 42215589c42SPeter Wemmlib_tparm.c 42315589c42SPeter Wemmlib_tputs.c 42415589c42SPeter Wemmlib_vidattr.c 42515589c42SPeter Wemmread_entry.c. 42615589c42SPeter Wemm</code> 42715589c42SPeter Wemm</blockquote> 42815589c42SPeter WemmThey are likely to need revision only if 42915589c42SPeter Wemmncurses is being ported to an environment without an underlying 43015589c42SPeter Wemmterminfo capability representation. <P> 43115589c42SPeter Wemm 43215589c42SPeter WemmThese files 43315589c42SPeter Wemmhave serious hooks into 43415589c42SPeter Wemmthe tty driver and signal facilities: 43515589c42SPeter Wemm<blockquote> 43615589c42SPeter Wemm<code> 43715589c42SPeter Wemmlib_kernel.c 43815589c42SPeter Wemmlib_baudrate.c 43915589c42SPeter Wemmlib_raw.c 44015589c42SPeter Wemmlib_tstp.c 44115589c42SPeter Wemmlib_twait.c 44215589c42SPeter Wemm</code> 44315589c42SPeter Wemm</blockquote> 44415589c42SPeter WemmIf you run into porting snafus 44515589c42SPeter Wemmmoving the package to another UNIX, the problem is likely to be in one 44615589c42SPeter Wemmof these files. 44715589c42SPeter WemmThe file <CODE>lib_print.c</CODE> uses sleep(2) and also 44815589c42SPeter Wemmfalls in this category.<P> 44915589c42SPeter Wemm 45015589c42SPeter WemmAlmost all of the real work is done in the files 45115589c42SPeter Wemm<blockquote> 45215589c42SPeter Wemm<code> 45315589c42SPeter Wemmhardscroll.c 45415589c42SPeter Wemmhashmap.c 45515589c42SPeter Wemmlib_addch.c 45615589c42SPeter Wemmlib_doupdate.c 45715589c42SPeter Wemmlib_getch.c 45815589c42SPeter Wemmlib_mouse.c 45915589c42SPeter Wemmlib_mvcur.c 46015589c42SPeter Wemmlib_refresh.c 46115589c42SPeter Wemmlib_setup.c 46215589c42SPeter Wemmlib_vidattr.c 46315589c42SPeter Wemm</code> 46415589c42SPeter Wemm</blockquote> 46515589c42SPeter WemmMost of the algorithmic complexity in the 46615589c42SPeter Wemmlibrary lives in these files. 46715589c42SPeter WemmIf there is a real bug in <STRONG>ncurses</STRONG> itself, it's probably here. 46815589c42SPeter WemmWe'll tour some of these files in detail 46915589c42SPeter Wemmbelow (see <A HREF="#engine">The Engine Room</A>). <P> 47015589c42SPeter Wemm 47115589c42SPeter WemmFinally, there is a group of files that is actually most of the 47215589c42SPeter Wemmterminfo compiler. The reason this code lives in the <STRONG>ncurses</STRONG> 47315589c42SPeter Wemmlibrary is to support fallback to /etc/termcap. These files include 47415589c42SPeter Wemm<blockquote> 47515589c42SPeter Wemm<code> 47615589c42SPeter Wemmalloc_entry.c 47715589c42SPeter Wemmcaptoinfo.c 47815589c42SPeter Wemmcomp_captab.c 47915589c42SPeter Wemmcomp_error.c 48015589c42SPeter Wemmcomp_hash.c 48115589c42SPeter Wemmcomp_parse.c 48215589c42SPeter Wemmcomp_scan.c 48315589c42SPeter Wemmparse_entry.c 48415589c42SPeter Wemmread_termcap.c 48515589c42SPeter Wemmwrite_entry.c 48615589c42SPeter Wemm</code> 48715589c42SPeter Wemm</blockquote> 48815589c42SPeter WemmWe'll discuss these in the compiler tour. 48915589c42SPeter Wemm 49015589c42SPeter Wemm<H2><A NAME="engine">The Engine Room</A></H2> 49115589c42SPeter Wemm 49215589c42SPeter Wemm<H3><A NAME="input">Keyboard Input</A></H3> 49315589c42SPeter Wemm 49415589c42SPeter WemmAll <CODE>ncurses</CODE> input funnels through the function 49515589c42SPeter Wemm<CODE>wgetch()</CODE>, defined in <CODE>lib_getch.c</CODE>. This function is 49615589c42SPeter Wemmtricky; it has to poll for keyboard and mouse events and do a running 49715589c42SPeter Wemmmatch of incoming input against the set of defined special keys. <P> 49815589c42SPeter Wemm 49915589c42SPeter WemmThe central data structure in this module is a FIFO queue, used to 50015589c42SPeter Wemmmatch multiple-character input sequences against special-key 50115589c42SPeter Wemmcapabilities; also to implement pushback via <CODE>ungetch()</CODE>. <P> 50215589c42SPeter Wemm 50315589c42SPeter WemmThe <CODE>wgetch()</CODE> code distinguishes between function key 50415589c42SPeter Wemmsequences and the same sequences typed manually by doing a timed wait 50515589c42SPeter Wemmafter each input character that could lead a function key sequence. 50615589c42SPeter WemmIf the entire sequence takes less than 1 second, it is assumed to have 50715589c42SPeter Wemmbeen generated by a function key press. <P> 50815589c42SPeter Wemm 50915589c42SPeter WemmHackers bruised by previous encounters with variant <CODE>select(2)</CODE> 51015589c42SPeter Wemmcalls may find the code in <CODE>lib_twait.c</CODE> interesting. It deals 51115589c42SPeter Wemmwith the problem that some BSD selects don't return a reliable 51215589c42SPeter Wemmtime-left value. The function <CODE>timed_wait()</CODE> effectively 51315589c42SPeter Wemmsimulates a System V select. 51415589c42SPeter Wemm 51515589c42SPeter Wemm<H3><A NAME="mouse">Mouse Events</A></H3> 51615589c42SPeter Wemm 51715589c42SPeter WemmIf the mouse interface is active, <CODE>wgetch()</CODE> polls for mouse 51815589c42SPeter Wemmevents each call, before it goes to the keyboard for input. It is 51915589c42SPeter Wemmup to <CODE>lib_mouse.c</CODE> how the polling is accomplished; it may vary 52015589c42SPeter Wemmfor different devices. <P> 52115589c42SPeter Wemm 52215589c42SPeter WemmUnder xterm, however, mouse event notifications come in via the keyboard 52315589c42SPeter Wemminput stream. They are recognized by having the <STRONG>kmous</STRONG> capability 52415589c42SPeter Wemmas a prefix. This is kind of klugey, but trying to wire in recognition of 52515589c42SPeter Wemma mouse key prefix without going through the function-key machinery would 52615589c42SPeter Wemmbe just too painful, and this turns out to imply having the prefix somewhere 52715589c42SPeter Wemmin the function-key capabilities at terminal-type initialization. <P> 52815589c42SPeter Wemm 52915589c42SPeter WemmThis kluge only works because <STRONG>kmous</STRONG> isn't actually used by any 53015589c42SPeter Wemmhistoric terminal type or curses implementation we know of. Best 53115589c42SPeter Wemmguess is it's a relic of some forgotten experiment in-house at Bell 53215589c42SPeter WemmLabs that didn't leave any traces in the publicly-distributed System V 53315589c42SPeter Wemmterminfo files. If System V or XPG4 ever gets serious about using it 53415589c42SPeter Wemmagain, this kluge may have to change. <P> 53515589c42SPeter Wemm 53615589c42SPeter WemmHere are some more details about mouse event handling: <P> 53715589c42SPeter Wemm 53815589c42SPeter WemmThe <CODE>lib_mouse()</CODE>code is logically split into a lower level that 53915589c42SPeter Wemmaccepts event reports in a device-dependent format and an upper level that 54015589c42SPeter Wemmparses mouse gestures and filters events. The mediating data structure is a 54115589c42SPeter Wemmcircular queue of event structures. <P> 54215589c42SPeter Wemm 54315589c42SPeter WemmFunctionally, the lower level's job is to pick up primitive events and 54415589c42SPeter Wemmput them on the circular queue. This can happen in one of two ways: 54515589c42SPeter Wemmeither (a) <CODE>_nc_mouse_event()</CODE> detects a series of incoming 54615589c42SPeter Wemmmouse reports and queues them, or (b) code in <CODE>lib_getch.c</CODE> detects the 54715589c42SPeter Wemm<STRONG>kmous</STRONG> prefix in the keyboard input stream and calls _nc_mouse_inline 54815589c42SPeter Wemmto queue up a series of adjacent mouse reports. <P> 54915589c42SPeter Wemm 55015589c42SPeter WemmIn either case, <CODE>_nc_mouse_parse()</CODE> should be called after the 55115589c42SPeter Wemmseries is accepted to parse the digested mouse reports (low-level 55215589c42SPeter Wemmevents) into a gesture (a high-level or composite event). 55315589c42SPeter Wemm 55415589c42SPeter Wemm<H3><A NAME="output">Output and Screen Updating</A></H3> 55515589c42SPeter Wemm 55615589c42SPeter WemmWith the single exception of character echoes during a <CODE>wgetnstr()</CODE> 55715589c42SPeter Wemmcall (which simulates cooked-mode line editing in an ncurses window), 55815589c42SPeter Wemmthe library normally does all its output at refresh time. <P> 55915589c42SPeter Wemm 56015589c42SPeter WemmThe main job is to go from the current state of the screen (as represented 56115589c42SPeter Wemmin the <CODE>curscr</CODE> window structure) to the desired new state (as 56215589c42SPeter Wemmrepresented in the <CODE>newscr</CODE> window structure), while doing as 56315589c42SPeter Wemmlittle I/O as possible. <P> 56415589c42SPeter Wemm 56515589c42SPeter WemmThe brains of this operation are the modules <CODE>hashmap.c</CODE>, 56615589c42SPeter Wemm<CODE>hardscroll.c</CODE> and <CODE>lib_doupdate.c</CODE>; the latter two use 56715589c42SPeter Wemm<CODE>lib_mvcur.c</CODE>. Essentially, what happens looks like this: <P> 56815589c42SPeter Wemm 56915589c42SPeter WemmThe <CODE>hashmap.c</CODE> module tries to detect vertical motion 57015589c42SPeter Wemmchanges between the real and virtual screens. This information 57115589c42SPeter Wemmis represented by the oldindex members in the newscr structure. 57215589c42SPeter WemmThese are modified by vertical-motion and clear operations, and both are 57315589c42SPeter Wemmre-initialized after each update. To this change-journalling 57415589c42SPeter Wemminformation, the hashmap code adds deductions made using a modified Heckel 57515589c42SPeter Wemmalgorithm on hash values generated from the line contents. <P> 57615589c42SPeter Wemm 57715589c42SPeter WemmThe <CODE>hardscroll.c</CODE> module computes an optimum set of scroll, 57815589c42SPeter Wemminsertion, and deletion operations to make the indices match. It calls 57915589c42SPeter Wemm<CODE>_nc_mvcur_scrolln()</CODE> in <CODE>lib_mvcur.c</CODE> to do those motions. <P> 58015589c42SPeter Wemm 58115589c42SPeter WemmThen <CODE>lib_doupdate.c</CODE> goes to work. Its job is to do line-by-line 58215589c42SPeter Wemmtransformations of <CODE>curscr</CODE> lines to <CODE>newscr</CODE> lines. Its main 58315589c42SPeter Wemmtool is the routine <CODE>mvcur()</CODE> in <CODE>lib_mvcur.c</CODE>. This routine 58415589c42SPeter Wemmdoes cursor-movement optimization, attempting to get from given screen 585*4a1a9510SRong-En Fanlocation A to given location B in the fewest output characters possible. <P> 58615589c42SPeter Wemm 58715589c42SPeter WemmIf you want to work on screen optimizations, you should use the fact 58815589c42SPeter Wemmthat (in the trace-enabled version of the library) enabling the 58915589c42SPeter Wemm<CODE>TRACE_TIMES</CODE> trace level causes a report to be emitted after 59015589c42SPeter Wemmeach screen update giving the elapsed time and a count of characters 59115589c42SPeter Wemmemitted during the update. You can use this to tell when an update 59215589c42SPeter Wemmoptimization improves efficiency. <P> 59315589c42SPeter Wemm 59415589c42SPeter WemmIn the trace-enabled version of the library, it is also possible to disable 59515589c42SPeter Wemmand re-enable various optimizations at runtime by tweaking the variable 59615589c42SPeter Wemm<CODE>_nc_optimize_enable</CODE>. See the file <CODE>include/curses.h.in</CODE> 59715589c42SPeter Wemmfor mask values, near the end. 59815589c42SPeter Wemm 59915589c42SPeter Wemm<H1><A NAME="fmnote">The Forms and Menu Libraries</A></H1> 60015589c42SPeter Wemm 60115589c42SPeter WemmThe forms and menu libraries should work reliably in any environment you 60215589c42SPeter Wemmcan port ncurses to. The only portability issue anywhere in them is what 60315589c42SPeter Wemmflavor of regular expressions the built-in form field type TYPE_REGEXP 60415589c42SPeter Wemmwill recognize. <P> 60515589c42SPeter Wemm 60615589c42SPeter WemmThe configuration code prefers the POSIX regex facility, modeled on 60715589c42SPeter WemmSystem V's, but will settle for BSD regexps if the former isn't available. <P> 60815589c42SPeter Wemm 60915589c42SPeter WemmHistorical note: the panels code was written primarily to assist in 61015589c42SPeter Wemmporting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking 61115589c42SPeter Wemmpanels support; u386mon 2.10 and beyond use it. This version has been 61215589c42SPeter Wemmslightly cleaned up for <CODE>ncurses</CODE>. 61315589c42SPeter Wemm 61415589c42SPeter Wemm<H1><A NAME="tic">A Tour of the Terminfo Compiler</A></H1> 61515589c42SPeter Wemm 61615589c42SPeter WemmThe <STRONG>ncurses</STRONG> implementation of <STRONG>tic</STRONG> is rather complex 61715589c42SPeter Wemminternally; it has to do a trying combination of missions. This starts 61815589c42SPeter Wemmwith the fact that, in addition to its normal duty of compiling 61915589c42SPeter Wemmterminfo sources into loadable terminfo binaries, it has to be able to 62015589c42SPeter Wemmhandle termcap syntax and compile that too into terminfo entries. <P> 62115589c42SPeter Wemm 62215589c42SPeter WemmThe implementation therefore starts with a table-driven, dual-mode 62315589c42SPeter Wemmlexical analyzer (in <CODE>comp_scan.c</CODE>). The lexer chooses its 62415589c42SPeter Wemmmode (termcap or terminfo) based on the first `,' or `:' it finds in 62515589c42SPeter Wemmeach entry. The lexer does all the work of recognizing capability 62615589c42SPeter Wemmnames and values; the grammar above it is trivial, just "parse entries 62715589c42SPeter Wemmtill you run out of file". 62815589c42SPeter Wemm 62915589c42SPeter Wemm<H2><A NAME="nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A></H2> 63015589c42SPeter Wemm 63115589c42SPeter WemmTranslation of most things besides <STRONG>use</STRONG> capabilities is pretty 63215589c42SPeter Wemmstraightforward. The lexical analyzer's tokenizer hands each capability 63315589c42SPeter Wemmname to a hash function, which drives a table lookup. The table entry 63415589c42SPeter Wemmyields an index which is used to look up the token type in another table, 63515589c42SPeter Wemmand controls interpretation of the value. <P> 63615589c42SPeter Wemm 63715589c42SPeter WemmOne possibly interesting aspect of the implementation is the way the 63815589c42SPeter Wemmcompiler tables are initialized. All the tables are generated by various 63915589c42SPeter Wemmawk/sed/sh scripts from a master table <CODE>include/Caps</CODE>; these 64015589c42SPeter Wemmscripts actually write C initializers which are linked to the compiler. 64115589c42SPeter WemmFurthermore, the hash table is generated in the same way, so it doesn't 64215589c42SPeter Wemmhave to be generated at compiler startup time (another benefit of this 64315589c42SPeter Wemmorganization is that the hash table can be in shareable text space). <P> 64415589c42SPeter Wemm 64515589c42SPeter WemmThus, adding a new capability is usually pretty trivial, just a matter 64615589c42SPeter Wemmof adding one line to the <CODE>include/Caps</CODE> file. We'll have more 64715589c42SPeter Wemmto say about this in the section on <A HREF="#translation">Source-Form 64815589c42SPeter WemmTranslation</A>. 64915589c42SPeter Wemm 65015589c42SPeter Wemm<H2><A NAME="uses">Use Capability Resolution</A></H2> 65115589c42SPeter Wemm 65215589c42SPeter WemmThe background problem that makes <STRONG>tic</STRONG> tricky isn't the capability 65315589c42SPeter Wemmtranslation itself, it's the resolution of <STRONG>use</STRONG> capabilities. Older 65415589c42SPeter Wemmversions would not handle forward <STRONG>use</STRONG> references for this reason 65515589c42SPeter Wemm(that is, a using terminal always had to follow its use target in the 65615589c42SPeter Wemmsource file). By doing this, they got away with a simple implementation 65715589c42SPeter Wemmtactic; compile everything as it blows by, then resolve uses from compiled 65815589c42SPeter Wemmentries. <P> 65915589c42SPeter Wemm 66015589c42SPeter WemmThis won't do for <STRONG>ncurses</STRONG>. The problem is that that the whole 66115589c42SPeter Wemmcompilation process has to be embeddable in the <STRONG>ncurses</STRONG> library 66215589c42SPeter Wemmso that it can be called by the startup code to translate termcap 66315589c42SPeter Wemmentries on the fly. The embedded version can't go promiscuously writing 66415589c42SPeter Wemmeverything it translates out to disk -- for one thing, it will typically 66515589c42SPeter Wemmbe running with non-root permissions. <P> 66615589c42SPeter Wemm 66715589c42SPeter WemmSo our <STRONG>tic</STRONG> is designed to parse an entire terminfo file into a 66815589c42SPeter Wemmdoubly-linked circular list of entry structures in-core, and then do 66915589c42SPeter Wemm<STRONG>use</STRONG> resolution in-memory before writing everything out. This 67015589c42SPeter Wemmdesign has other advantages: it makes forward and back use-references 67115589c42SPeter Wemmequally easy (so we get the latter for free), and it makes checking for 67215589c42SPeter Wemmname collisions before they're written out easy to do. <P> 67315589c42SPeter Wemm 67415589c42SPeter WemmAnd this is exactly how the embedded version works. But the stand-alone 67515589c42SPeter Wemmuser-accessible version of <STRONG>tic</STRONG> partly reverts to the historical 67615589c42SPeter Wemmstrategy; it writes to disk (not keeping in core) any entry with no 67715589c42SPeter Wemm<STRONG>use</STRONG> references. <P> 67815589c42SPeter Wemm 67915589c42SPeter WemmThis is strictly a core-economy kluge, implemented because the 68015589c42SPeter Wemmterminfo master file is large enough that some core-poor systems swap 68115589c42SPeter Wemmlike crazy when you compile it all in memory...there have been reports of 68215589c42SPeter Wemmthis process taking <STRONG>three hours</STRONG>, rather than the twenty seconds 68315589c42SPeter Wemmor less typical on the author's development box. <P> 68415589c42SPeter Wemm 68515589c42SPeter WemmSo. The executable <STRONG>tic</STRONG> passes the entry-parser a hook that 68615589c42SPeter Wemm<EM>immediately</EM> writes out the referenced entry if it has no use 68715589c42SPeter Wemmcapabilities. The compiler main loop refrains from adding the entry 68815589c42SPeter Wemmto the in-core list when this hook fires. If some other entry later 68915589c42SPeter Wemmneeds to reference an entry that got written immediately, that's OK; 69015589c42SPeter Wemmthe resolution code will fetch it off disk when it can't find it in 69115589c42SPeter Wemmcore. <P> 69215589c42SPeter Wemm 69315589c42SPeter WemmName collisions will still be detected, just not as cleanly. The 69415589c42SPeter Wemm<CODE>write_entry()</CODE> code complains before overwriting an entry that 69515589c42SPeter Wemmpostdates the time of <STRONG>tic</STRONG>'s first call to 69615589c42SPeter Wemm<CODE>write_entry()</CODE>, Thus it will complain about overwriting 69715589c42SPeter Wemmentries newly made during the <STRONG>tic</STRONG> run, but not about 69815589c42SPeter Wemmoverwriting ones that predate it. 69915589c42SPeter Wemm 70015589c42SPeter Wemm<H2><A NAME="translation">Source-Form Translation</A></H2> 70115589c42SPeter Wemm 70215589c42SPeter WemmAnother use of <STRONG>tic</STRONG> is to do source translation between various termcap 70315589c42SPeter Wemmand terminfo formats. There are more variants out there than you might 70415589c42SPeter Wemmthink; the ones we know about are described in the <STRONG>captoinfo(1)</STRONG> 70515589c42SPeter Wemmmanual page. <P> 70615589c42SPeter Wemm 70715589c42SPeter WemmThe translation output code (<CODE>dump_entry()</CODE> in 70815589c42SPeter Wemm<CODE>ncurses/dump_entry.c</CODE>) is shared with the <STRONG>infocmp(1)</STRONG> 70915589c42SPeter Wemmutility. It takes the same internal representation used to generate 71015589c42SPeter Wemmthe binary form and dumps it to standard output in a specified 71115589c42SPeter Wemmformat. <P> 71215589c42SPeter Wemm 71315589c42SPeter WemmThe <CODE>include/Caps</CODE> file has a header comment describing ways you 71415589c42SPeter Wemmcan specify source translations for nonstandard capabilities just by 71515589c42SPeter Wemmaltering the master table. It's possible to set up capability aliasing 71615589c42SPeter Wemmor tell the compiler to plain ignore a given capability without writing 71715589c42SPeter Wemmany C code at all. <P> 71815589c42SPeter Wemm 71915589c42SPeter WemmFor circumstances where you need to do algorithmic translation, there 72015589c42SPeter Wemmare functions in <CODE>parse_entry.c</CODE> called after the parse of each 72115589c42SPeter Wemmentry that are specifically intended to encapsulate such 72215589c42SPeter Wemmtranslations. This, for example, is where the AIX <STRONG>box1</STRONG> capability 72315589c42SPeter Wemmget translated to an <STRONG>acsc</STRONG> string. 72415589c42SPeter Wemm 72515589c42SPeter Wemm<H1><A NAME="utils">Other Utilities</A></H1> 72615589c42SPeter Wemm 72715589c42SPeter WemmThe <STRONG>infocmp</STRONG> utility is just a wrapper around the same 72815589c42SPeter Wemmentry-dumping code used by <STRONG>tic</STRONG> for source translation. Perhaps 72915589c42SPeter Wemmthe one interesting aspect of the code is the use of a predicate 73015589c42SPeter Wemmfunction passed in to <CODE>dump_entry()</CODE> to control which 73115589c42SPeter Wemmcapabilities are dumped. This is necessary in order to handle both 73215589c42SPeter Wemmthe ordinary De-compilation case and entry difference reporting. <P> 73315589c42SPeter Wemm 73415589c42SPeter WemmThe <STRONG>tput</STRONG> and <STRONG>clear</STRONG> utilities just do an entry load 73515589c42SPeter Wemmfollowed by a <CODE>tputs()</CODE> of a selected capability. 73615589c42SPeter Wemm 73715589c42SPeter Wemm<H1><A NAME="style">Style Tips for Developers</A></H1> 73815589c42SPeter Wemm 73915589c42SPeter WemmSee the TO-DO file in the top-level directory of the source distribution 74015589c42SPeter Wemmfor additions that would be particularly useful. <P> 74115589c42SPeter Wemm 74215589c42SPeter WemmThe prefix <CODE>_nc_</CODE> should be used on library public functions that are 74315589c42SPeter Wemmnot part of the curses API in order to prevent pollution of the 74415589c42SPeter Wemmapplication namespace. 74515589c42SPeter Wemm 74615589c42SPeter WemmIf you have to add to or modify the function prototypes in curses.h.in, 74715589c42SPeter Wemmread ncurses/MKlib_gen.sh first so you can avoid breaking XSI conformance. 74815589c42SPeter Wemm 74915589c42SPeter WemmPlease join the ncurses mailing list. See the INSTALL file in the 75015589c42SPeter Wemmtop level of the distribution for details on the list. <P> 75115589c42SPeter Wemm 75215589c42SPeter WemmLook for the string <CODE>FIXME</CODE> in source files to tag minor bugs 75315589c42SPeter Wemmand potential problems that could use fixing. <P> 75415589c42SPeter Wemm 75515589c42SPeter WemmDon't try to auto-detect OS features in the main body of the C code. 75615589c42SPeter WemmThat's the job of the configuration system. <P> 75715589c42SPeter Wemm 75815589c42SPeter WemmTo hold down complexity, do make your code data-driven. Especially, 75915589c42SPeter Wemmif you can drive logic from a table filtered out of 76015589c42SPeter Wemm<CODE>include/Caps</CODE>, do it. If you find you need to augment the 76115589c42SPeter Wemmdata in that file in order to generate the proper table, that's still 76215589c42SPeter Wemmpreferable to ad-hoc code -- that's why the fifth field (flags) is 76315589c42SPeter Wemmthere. <P> 76415589c42SPeter Wemm 76515589c42SPeter WemmHave fun! 76615589c42SPeter Wemm 76715589c42SPeter Wemm<H1><A NAME="port">Porting Hints</A></H1> 76815589c42SPeter Wemm 76915589c42SPeter WemmThe following notes are intended to be a first step towards DOS and Macintosh 77015589c42SPeter Wemmports of the ncurses libraries. <P> 77115589c42SPeter Wemm 77215589c42SPeter WemmThe following library modules are `pure curses'; they operate only on 77315589c42SPeter Wemmthe curses internal structures, do all output through other curses 77415589c42SPeter Wemmcalls (not including <CODE>tputs()</CODE> and <CODE>putp()</CODE>) and do not 77515589c42SPeter Wemmcall any other UNIX routines such as signal(2) or the stdio library. 77615589c42SPeter WemmThus, they should not need to be modified for single-terminal 77715589c42SPeter Wemmports. 77815589c42SPeter Wemm 77915589c42SPeter Wemm<blockquote> 78015589c42SPeter Wemm<code> 78115589c42SPeter Wemmlib_addch.c 78215589c42SPeter Wemmlib_addstr.c 78315589c42SPeter Wemmlib_bkgd.c 78415589c42SPeter Wemmlib_box.c 78515589c42SPeter Wemmlib_clear.c 78615589c42SPeter Wemmlib_clrbot.c 78715589c42SPeter Wemmlib_clreol.c 78815589c42SPeter Wemmlib_delch.c 78915589c42SPeter Wemmlib_delwin.c 79015589c42SPeter Wemmlib_erase.c 79115589c42SPeter Wemmlib_inchstr.c 79215589c42SPeter Wemmlib_insch.c 79315589c42SPeter Wemmlib_insdel.c 79415589c42SPeter Wemmlib_insstr.c 79515589c42SPeter Wemmlib_keyname.c 79615589c42SPeter Wemmlib_move.c 79715589c42SPeter Wemmlib_mvwin.c 79815589c42SPeter Wemmlib_newwin.c 79915589c42SPeter Wemmlib_overlay.c 80015589c42SPeter Wemmlib_pad.c 80115589c42SPeter Wemmlib_printw.c 80215589c42SPeter Wemmlib_refresh.c 80315589c42SPeter Wemmlib_scanw.c 80415589c42SPeter Wemmlib_scroll.c 80515589c42SPeter Wemmlib_scrreg.c 80615589c42SPeter Wemmlib_set_term.c 80715589c42SPeter Wemmlib_touch.c 80815589c42SPeter Wemmlib_tparm.c 80915589c42SPeter Wemmlib_tputs.c 81015589c42SPeter Wemmlib_unctrl.c 81115589c42SPeter Wemmlib_window.c 81215589c42SPeter Wemmpanel.c 81315589c42SPeter Wemm</code> 81415589c42SPeter Wemm</blockquote> 81515589c42SPeter Wemm<P> 81615589c42SPeter Wemm 81715589c42SPeter WemmThis module is pure curses, but calls outstr(): 81815589c42SPeter Wemm 81915589c42SPeter Wemm<blockquote> 82015589c42SPeter Wemm<code> 82115589c42SPeter Wemmlib_getstr.c 82215589c42SPeter Wemm</code> 82315589c42SPeter Wemm</blockquote> 82415589c42SPeter Wemm<P> 82515589c42SPeter Wemm 82615589c42SPeter WemmThese modules are pure curses, except that they use <CODE>tputs()</CODE> 82715589c42SPeter Wemmand <CODE>putp()</CODE>: 82815589c42SPeter Wemm 82915589c42SPeter Wemm<blockquote> 83015589c42SPeter Wemm<code> 83115589c42SPeter Wemmlib_beep.c 83215589c42SPeter Wemmlib_color.c 83315589c42SPeter Wemmlib_endwin.c 83415589c42SPeter Wemmlib_options.c 83515589c42SPeter Wemmlib_slk.c 83615589c42SPeter Wemmlib_vidattr.c 83715589c42SPeter Wemm</code> 83815589c42SPeter Wemm</blockquote> 83915589c42SPeter Wemm<P> 84015589c42SPeter Wemm 84115589c42SPeter WemmThis modules assist in POSIX emulation on non-POSIX systems: 84215589c42SPeter Wemm<DL> 84315589c42SPeter Wemm<DT> sigaction.c 84415589c42SPeter Wemm<DD> signal calls 84515589c42SPeter Wemm</DL> 84615589c42SPeter Wemm 84715589c42SPeter WemmThe following source files will not be needed for a 84815589c42SPeter Wemmsingle-terminal-type port. 84915589c42SPeter Wemm 85015589c42SPeter Wemm<blockquote> 85115589c42SPeter Wemm<code> 85215589c42SPeter Wemmalloc_entry.c 85315589c42SPeter Wemmcaptoinfo.c 85415589c42SPeter Wemmclear.c 85515589c42SPeter Wemmcomp_captab.c 85615589c42SPeter Wemmcomp_error.c 85715589c42SPeter Wemmcomp_hash.c 85815589c42SPeter Wemmcomp_main.c 85915589c42SPeter Wemmcomp_parse.c 86015589c42SPeter Wemmcomp_scan.c 86115589c42SPeter Wemmdump_entry.c 86215589c42SPeter Wemminfocmp.c 86315589c42SPeter Wemmparse_entry.c 86415589c42SPeter Wemmread_entry.c 86515589c42SPeter Wemmtput.c 86615589c42SPeter Wemmwrite_entry.c 86715589c42SPeter Wemm</code> 86815589c42SPeter Wemm</blockquote> 86915589c42SPeter Wemm<P> 87015589c42SPeter Wemm 87115589c42SPeter WemmThe following modules will use open()/read()/write()/close()/lseek() on files, 87215589c42SPeter Wemmbut no other OS calls. 87315589c42SPeter Wemm 87415589c42SPeter Wemm<DL> 87515589c42SPeter Wemm<DT>lib_screen.c 87615589c42SPeter Wemm<DD>used to read/write screen dumps 87715589c42SPeter Wemm<DT>lib_trace.c 87815589c42SPeter Wemm<DD>used to write trace data to the logfile 87915589c42SPeter Wemm</DL> 88015589c42SPeter Wemm 88115589c42SPeter WemmModules that would have to be modified for a port start here: <P> 88215589c42SPeter Wemm 88315589c42SPeter WemmThe following modules are `pure curses' but contain assumptions inappropriate 88415589c42SPeter Wemmfor a memory-mapped port. 88515589c42SPeter Wemm 88615589c42SPeter Wemm<dl> 88715589c42SPeter Wemm<dt>lib_longname.c<dd>assumes there may be multiple terminals 88815589c42SPeter Wemm<dt>lib_acs.c<dd>assumes acs_map as a double indirection 88915589c42SPeter Wemm<dt>lib_mvcur.c<dd>assumes cursor moves have variable cost 89015589c42SPeter Wemm<dt>lib_termcap.c<dd>assumes there may be multiple terminals 89115589c42SPeter Wemm<dt>lib_ti.c<dd>assumes there may be multiple terminals 89215589c42SPeter Wemm</dl> 89315589c42SPeter Wemm 89415589c42SPeter WemmThe following modules use UNIX-specific calls: 89515589c42SPeter Wemm 89615589c42SPeter Wemm<dl> 89715589c42SPeter Wemm<dt>lib_doupdate.c<dd>input checking 89815589c42SPeter Wemm<dt>lib_getch.c<dd>read() 89915589c42SPeter Wemm<dt>lib_initscr.c<dd>getenv() 90015589c42SPeter Wemm<dt>lib_newterm.c 90115589c42SPeter Wemm<dt>lib_baudrate.c 90215589c42SPeter Wemm<dt>lib_kernel.c<dd>various tty-manipulation and system calls 90315589c42SPeter Wemm<dt>lib_raw.c<dd>various tty-manipulation calls 90415589c42SPeter Wemm<dt>lib_setup.c<dd>various tty-manipulation calls 90515589c42SPeter Wemm<dt>lib_restart.c<dd>various tty-manipulation calls 90615589c42SPeter Wemm<dt>lib_tstp.c<dd>signal-manipulation calls 90715589c42SPeter Wemm<dt>lib_twait.c<dd>gettimeofday(), select(). 90815589c42SPeter Wemm</dl> 90915589c42SPeter Wemm 91015589c42SPeter Wemm<HR> 91115589c42SPeter Wemm<ADDRESS>Eric S. Raymond <[email protected]></ADDRESS> 91215589c42SPeter Wemm(Note: This is <EM>not</EM> the <A HREF="#bugtrack">bug address</A>!) 91315589c42SPeter Wemm</BODY> 91415589c42SPeter Wemm</HTML> 915