Lines Matching +full:a +full:- +full:c
1 A Hacker's Guide to NCURSES
3 A Hacker's Guide to NCURSES
14 * A Tour of the Ncurses Library
21 * A Tour of the Terminfo Compiler
22 + Translation of Non-use Capabilities
24 + Source-Form Translation
31 This document is a hacker's tour of the ncurses library and utilities.
39 The objective of the ncurses package is to provide a free software API
40 for character-cell terminals and terminal emulators with the following
42 * Source-compatible with historical curses implementations
46 * High-quality -- stable and reliable code, wide portability, good
48 * Featureful -- should eliminate as much of the drudgery of C
50 a higher level of design.
53 compatibility with older version must trump featurefulness -- we
59 We used System V curses as a model, reverse-engineering their API, in
63 just a recompilation, so by capturing the System V API we also capture
68 with System V took us most of the way to base-level XSI conformance.
76 Accordingly, we have a policy of associating with each nonstandard
77 extension a feature macro, so that ncurses client code can use this
81 For example, there is a macro NCURSES_MOUSE_VERSION which XSI Curses
87 Code written for ncurses may assume an ANSI-standard C compiler and
88 POSIX-compatible OS interface. It may also assume the presence of a
89 System-V-compatible select(2) call.
92 to less-capable UNIX environments wherever possible.
94 We encourage developers to support OS-specific optimizations and
97 not attempt to compile it under a plain ANSI/POSIX environment.
101 We use GNU autoconf(1) as a tool to deal with portability issues. The
102 right way to leverage an OS-specific feature is to modify the autoconf
103 specification files (configure.in and aclocal.m4) to set up a new
109 Each has a different preferred format:
110 * Package-internal files (README, INSTALL, TO-DO etc.)
115 1. Maintain package-internal files in plain text. The expected viewer
117 elaborate mark-up.
122 When in doubt, HTMLize a master and use lynx(1) to generate plain
125 The reason for choosing HTML is that it is (a) well-adapted for
126 on-line browsing through viewers that are everywhere; (b) more easily
127 readable as plain text than most other mark-ups, if you do not have a
128 viewer; and (c) carries enough information that you can generate a
129 nice-looking printed version from it. Also, of course, it make
134 The reporting address for bugs is bug-ncurses@gnu.org. This is a
135 majordomo list; to join, write to bug-ncurses-request@gnu.org with a
139 The ncurses code is maintained by a small group of volunteers. While
140 we try our best to fix bugs promptly, we simply do not have a lot of
141 hours to spend on elementary hand-holding. We rely on intelligent
142 cooperation from our users. If you think you have found a bug in
146 In order to use our bug-fixing time efficiently, we put people who
149 have to wait a while.
150 1. Develop a recipe to reproduce the bug.
152 within days. The most effective single thing you can do to get a
153 quick fix is develop a way we can duplicate the bad behavior --
154 ideally, by giving us source for a small, portable test program
155 that breaks the library. (Even better is a keystroke recipe using
157 2. Try to reproduce the bug on a different terminal type.
160 This is especially likely to be true if you are using a
161 traditional asynchronous terminal or PC-based terminal emulator,
162 rather than xterm or a UNIX console entry.
165 will have both a console type and xterm available; please tell us
169 normally use an unusual xterm window size -- a surprising number
171 3. Generate and examine a trace file for the broken behavior.
173 libraries. Insert a trace() call with the argument set to
179 screen. Looking at the virtual-screen dumps in the trace file will
183 If the virtual-screen dumps look correct but the bug persists, it
187 distribution contains a tool for digesting these logs to make them
192 characterize any bug in the screen-update logic quite exactly.
196 a fix. This will create happy feelings all around and earn you
197 good karma for the first time you run into a bug you really cannot
202 If your bug produces a bad update, include a trace file. Try to
206 un-munched ones because they are easier to read).
207 If your bug produces a core-dump, please include a symbolic stack
210 -- and every terminal on which you cannot. Ideally, send us
215 If your problem smells like a logic error or in cursor movement or
216 scrolling or a bad capability, there are a couple of tiny test frames
221 The most important of these is mvcur, a test frame for the
222 cursor-movement optimization code. With this program, you can see
225 a bad capability identified, you can disable it and test again. The
226 program is command-driven and has on-line help.
228 If you think the vertical-scroll optimization is broken, or just want
230 comments of hardscroll.c and hashmap.c; then try it out. You can also
231 test the hardware-scrolling optimization separately with hardscroll.
233 A Tour of the Ncurses Library
237 Most of the library is superstructure -- fairly trivial convenience
238 interfaces to a small set of basic functions and data structures used
243 lib_addch.c lib_bkgd.c lib_box.c lib_chgat.c lib_clear.c
244 lib_clearok.c lib_clrbot.c lib_clreol.c lib_colorset.c lib_data.c
245 lib_delch.c lib_delwin.c lib_echo.c lib_erase.c lib_gen.c
246 lib_getstr.c lib_hline.c lib_immedok.c lib_inchstr.c lib_insch.c
247 lib_insdel.c lib_insstr.c lib_instr.c lib_isendwin.c lib_keyname.c
248 lib_leaveok.c lib_move.c lib_mvwin.c lib_overlay.c lib_pad.c
249 lib_printw.c lib_redrawln.c lib_scanw.c lib_screen.c lib_scroll.c
250 lib_scrollok.c lib_scrreg.c lib_set_term.c lib_slk.c
251 lib_slkatr_set.c lib_slkatrof.c lib_slkatron.c lib_slkatrset.c
252 lib_slkattr.c lib_slkclear.c lib_slkcolor.c lib_slkinit.c
253 lib_slklab.c lib_slkrefr.c lib_slkset.c lib_slktouch.c lib_touch.c
254 lib_unctrl.c lib_vline.c lib_wattroff.c lib_wattron.c lib_window.c
262 lib_trace.c lib_traceatr.c lib_tracebits.c lib_tracechr.c
263 lib_tracedmp.c lib_tracemse.c trace_buf.c
266 want to introduce a new debug trace level for some reason.
273 lib_acs.c lib_beep.c lib_color.c lib_endwin.c lib_initscr.c
274 lib_longname.c lib_newterm.c lib_options.c lib_termcap.c lib_ti.c
275 lib_tparm.c lib_tputs.c lib_vidattr.c read_entry.c.
283 lib_kernel.c lib_baudrate.c lib_raw.c lib_tstp.c lib_twait.c
286 problem is likely to be in one of these files. The file lib_print.c
291 hardscroll.c hashmap.c lib_addch.c lib_doupdate.c lib_getch.c
292 lib_mouse.c lib_mvcur.c lib_refresh.c lib_setup.c lib_vidattr.c
295 files. If there is a real bug in ncurses itself, it is probably here.
299 Finally, there is a group of files that is actually most of the
303 alloc_entry.c captoinfo.c comp_captab.c comp_error.c comp_hash.c
304 comp_parse.c comp_scan.c parse_entry.c read_termcap.c write_entry.c
313 lib_getch.c. This function is tricky; it has to poll for keyboard and
314 mouse events and do a running match of incoming input against the set
317 The central data structure in this module is a FIFO queue, used to
318 match multiple-character input sequences against special-key
322 same sequences typed manually by doing a timed wait after each input
323 character that could lead a function key sequence. If the entire
325 generated by a function key press.
328 may find the code in lib_twait.c interesting. It deals with the
329 problem that some BSD selects do not return a reliable time-left
330 value. The function timed_wait() effectively simulates a System V
337 lib_mouse.c how the polling is accomplished; it may vary for different
342 capability as a prefix. This is kind of klugey, but trying to wire in
343 recognition of a mouse key prefix without going through the
344 function-key machinery would be just too painful, and this turns out
345 to imply having the prefix somewhere in the function-key capabilities
346 at terminal-type initialization.
350 is it is a relic of some forgotten experiment in-house at Bell Labs
351 that did not leave any traces in the publicly-distributed System V
357 The lib_mouse() code is logically split into a lower level that
358 accepts event reports in a device-dependent format and an upper level
360 structure is a circular queue of event structures.
364 either (a) _nc_mouse_event() detects a series of incoming mouse
365 reports and queues them, or (b) code in lib_getch.c detects the kmous
367 queue up a series of adjacent mouse reports.
370 accepted to parse the digested mouse reports (low-level events) into a
371 gesture (a high-level or composite event).
375 With the single exception of character echoes during a wgetnstr() call
376 (which simulates cooked-mode line editing in an ncurses window), the
384 The brains of this operation are the modules hashmap.c, hardscroll.c
385 and lib_doupdate.c; the latter two use lib_mvcur.c. Essentially, what
387 * The hashmap.c module tries to detect vertical motion changes
390 are modified by vertical-motion and clear operations, and both are
391 re-initialized after each update. To this change-journalling
392 information, the hashmap code adds deductions made using a
395 * The hardscroll.c module computes an optimum set of scroll,
397 calls _nc_mvcur_scrolln() in lib_mvcur.c to do those motions.
398 * Then lib_doupdate.c goes to work. Its job is to do line-by-line
400 the routine mvcur() in lib_mvcur.c. This routine does
401 cursor-movement optimization, attempting to get from given screen
402 location A to given location B in the fewest output characters
406 that (in the trace-enabled version of the library) enabling the
407 TRACE_TIMES trace level causes a report to be emitted after each
408 screen update giving the elapsed time and a count of characters
412 In the trace-enabled version of the library, it is also possible to
413 disable and re-enable various optimizations at runtime by tweaking the
421 is what flavor of regular expressions the built-in form field type
429 porting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking
433 A Tour of the Terminfo Compiler
436 to do a trying combination of missions. This starts with the fact
441 The implementation therefore starts with a table-driven, dual-mode
442 lexical analyzer (in comp_scan.c). The lexer chooses its mode (termcap
448 Translation of Non-use Capabilities
452 capability name to a hash function, which drives a table lookup. The
458 various awk/sed/sh scripts from a master table include/Caps; these
459 scripts actually write C initializers which are linked to the
465 Thus, adding a new capability is usually pretty trivial, just a matter
467 about this in the section on Source-Form Translation.
474 is, a using terminal always had to follow its use target in the source
475 file). By doing this, they got away with a simple implementation
483 everything it translates out to disk -- for one thing, it will
484 typically be running with non-root permissions.
486 So our tic is designed to parse an entire terminfo file into a
487 doubly-linked circular list of entry structures in-core, and then do
488 use resolution in-memory before writing everything out. This design
489 has other advantages: it makes forward and back use-references equally
494 stand-alone user-accessible version of tic partly reverts to the
498 This is strictly a core-economy kluge, implemented because the
499 terminfo master file is large enough that some core-poor systems swap
504 So. The executable tic passes the entry-parser a hook that immediately
506 compiler main loop refrains from adding the entry to the in-core list
517 Source-Form Translation
524 The translation output code (dump_entry() in ncurses/dump_entry.c) is
527 standard output in a specified format.
529 The include/Caps file has a header comment describing ways you can
532 aliasing or tell the compiler to plain ignore a given capability
533 without writing any C code at all.
536 are functions in parse_entry.c called after the parse of each entry
543 The infocmp utility is just a wrapper around the same entry-dumping
545 aspect of the code is the use of a predicate function passed in to
547 necessary in order to handle both the ordinary De-compilation case and
550 The tput and clear utilities just do an entry load followed by a
551 tputs() of a selected capability.
555 See the TO-DO file in the top-level directory of the source
569 Do not try to auto-detect OS features in the main body of the C code.
572 To hold down complexity, do make your code data-driven. Especially, if
573 you can drive logic from a table filtered out of include/Caps, do it.
575 generate the proper table, that is still preferable to ad-hoc code --
582 The following notes are intended to be a first step towards DOS and
589 should not need to be modified for single-terminal ports.
591 lib_addch.c lib_addstr.c lib_bkgd.c lib_box.c lib_clear.c
592 lib_clrbot.c lib_clreol.c lib_delch.c lib_delwin.c lib_erase.c
593 lib_inchstr.c lib_insch.c lib_insdel.c lib_insstr.c lib_keyname.c
594 lib_move.c lib_mvwin.c lib_newwin.c lib_overlay.c lib_pad.c
595 lib_printw.c lib_refresh.c lib_scanw.c lib_scroll.c lib_scrreg.c
596 lib_set_term.c lib_touch.c lib_tparm.c lib_tputs.c lib_unctrl.c
597 lib_window.c panel.c
601 lib_getstr.c
606 lib_beep.c lib_color.c lib_endwin.c lib_options.c lib_slk.c
607 lib_vidattr.c
609 This modules assist in POSIX emulation on non-POSIX systems:
611 sigaction.c
614 The following source files will not be needed for a
615 single-terminal-type port.
617 alloc_entry.c captoinfo.c clear.c comp_captab.c comp_error.c
618 comp_hash.c comp_main.c comp_parse.c comp_scan.c dump_entry.c
619 infocmp.c parse_entry.c read_entry.c tput.c write_entry.c
624 lib_screen.c
627 lib_trace.c
630 Modules that would have to be modified for a port start here:
633 inappropriate for a memory-mapped port.
635 lib_longname.c
638 lib_acs.c
639 assumes acs_map as a double indirection
641 lib_mvcur.c
644 lib_termcap.c
647 lib_ti.c
650 The following modules use UNIX-specific calls:
652 lib_doupdate.c
655 lib_getch.c
658 lib_initscr.c
661 lib_newterm.c
662 lib_baudrate.c
663 lib_kernel.c
664 various tty-manipulation and system calls
666 lib_raw.c
667 various tty-manipulation calls
669 lib_setup.c
670 various tty-manipulation calls
672 lib_restart.c
673 various tty-manipulation calls
675 lib_tstp.c
676 signal-manipulation calls
678 lib_twait.c