docs: Added All OpenBSD Manuals

1 files changed, 411 insertions, 0 deletions

diff --git a/static/openbsd/man5/term.5 b/static/openbsd/man5/term.5
new file mode 100644
index 00000000..91a8a942
--- /dev/null
+++ b/static/openbsd/man5/term.5
@@ -0,0 +1,411 @@
+.\"***************************************************************************
+.\" Copyright 2018-2021,2023 Thomas E. Dickey                                *
+.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
+.\"                                                                          *
+.\" Permission is hereby granted, free of charge, to any person obtaining a  *
+.\" copy of this software and associated documentation files (the            *
+.\" "Software"), to deal in the Software without restriction, including      *
+.\" without limitation the rights to use, copy, modify, merge, publish,      *
+.\" distribute, distribute with modifications, sublicense, and/or sell       *
+.\" copies of the Software, and to permit persons to whom the Software is    *
+.\" furnished to do so, subject to the following conditions:                 *
+.\"                                                                          *
+.\" The above copyright notice and this permission notice shall be included  *
+.\" in all copies or substantial portions of the Software.                   *
+.\"                                                                          *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+.\"                                                                          *
+.\" Except as contained in this notice, the name(s) of the above copyright   *
+.\" holders shall not be used in advertising or otherwise to promote the     *
+.\" sale, use or other dealings in this Software without prior written       *
+.\" authorization.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: term.5,v 1.2 2023/10/17 09:52:08 nicm Exp $
+.TH term 5 2023-07-01 "ncurses 6.4" "File formats"
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
+.de NS
+.ie n  .sp
+.el    .sp .5
+.ie n  .in +4
+.el    .in +2
+.nf
+.ft CR			\" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n  .in -4
+.el    .in -2
+..
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
+.ds n 5
+.ds d /usr/share/terminfo
+.SH NAME
+term \- format of compiled term file.
+.SH SYNOPSIS
+.B term
+.SH DESCRIPTION
+.SS STORAGE LOCATION
+Compiled terminfo descriptions are placed under the directory \fB\*d\fP.
+Two configurations are supported (when building the \fBncurses\fP libraries):
+.TP 5
+.B directory tree
+A two-level scheme is used to avoid a linear search
+of a huge \s-1UNIX\s+1 system directory: \fB\*d/c/name\fP where
+.I name
+is the name of the terminal, and
+.I c
+is the first character of
+.IR name .
+Thus,
+.I act4
+can be found in the file \fB\*d/a/act4\fP.
+Synonyms for the same terminal are implemented by multiple
+links to the same compiled file.
+.TP 5
+.B hashed database
+Using Berkeley database, two types of records are stored:
+the terminfo data in the same format as stored in a directory tree with
+the terminfo's primary name as a key,
+and records containing only aliases pointing to the primary name.
+.IP
+If built to write hashed databases,
+\fBncurses\fP can still read terminfo databases organized as a directory tree,
+but cannot write entries into the directory tree.
+It can write (or rewrite) entries in the hashed database.
+.IP
+\fBncurses\fP distinguishes the two cases in the TERMINFO and TERMINFO_DIRS
+environment variable by assuming a directory tree for entries that
+correspond to an existing directory,
+and hashed database otherwise.
+.SS LEGACY STORAGE FORMAT
+The format has been chosen so that it will be the same on all hardware.
+An 8 or more bit byte is assumed, but no assumptions about byte ordering
+or sign extension are made.
+.PP
+The compiled file is created with the \fBtic\fP program,
+and read by the routine \fBsetupterm\fP(3).
+The file is divided into six parts:
+.RS 5
+.TP 3
+a) \fIheader\fP,
+.TP 3
+b) \fIterminal names\fP,
+.TP 3
+c) \fIboolean flags\fP,
+.TP 3
+d) \fInumbers\fP,
+.TP 3
+e) \fIstrings\fP, and
+.TP 3
+f) \fIstring table\fP.
+.RE
+.PP
+The \fIheader\fP section begins the file.
+This section contains six short integers in the format
+described below.
+These integers are
+.RS 5
+.TP 5
+(1) the \fImagic number\fP (octal 0432);
+.TP 5
+(2) the size, in bytes, of the \fIterminal names\fP section;
+.TP 5
+(3) the number of bytes in the \fIboolean flags\fP section;
+.TP 5
+(4) the number of short integers in the \fInumbers\fP section;
+.TP 5
+(5) the number of offsets (short integers) in the \fIstrings\fP section;
+.TP 5
+(6) the size, in bytes, of the \fIstring table\fP.
+.RE
+.PP
+The capabilities in the
+\fIboolean flags\fP,
+\fInumbers\fP, and
+\fIstrings\fP
+sections are in the same order as the file <term.h>.
+.PP
+Short integers are signed, in the range \-32768 to 32767.
+They are stored as two 8-bit bytes.
+The first byte contains the least significant 8 bits of the value,
+and the second byte contains the most significant 8 bits.
+(Thus, the value represented is 256*second+first.)
+This format corresponds to the hardware of the \s-1VAX\s+1
+and \s-1PDP\s+1-11 (that is, little-endian machines).
+Machines where this does not correspond to the hardware must read the
+integers as two bytes and compute the little-endian value.
+.PP
+Numbers in a terminal description,
+whether they are entries in the \fInumbers\fP or \fIstrings\fP table,
+are positive integers.
+Boolean flags are treated as positive one-byte integers.
+In each case, those positive integers represent a terminal capability.
+The terminal compiler tic uses negative integers to handle the cases where
+a capability is not available:
+.bP
+If a capability is absent from this terminal,
+tic stores a \-1 in the corresponding table.
+.IP
+The integer value \-1 is represented by two bytes 0377, 0377.
+.br
+Absent boolean values are represented by the byte 0 (false).
+.bP
+If a capability has been canceled from this terminal,
+tic stores a \-2 in the corresponding table.
+.IP
+The integer value \-2 is represented by two bytes 0377, 0376.
+.br
+The boolean value \-2 is represented by the byte 0376.
+.br
+.bP
+Other negative values are illegal.
+.PP
+The \fIterminal names\fP section comes after the \fIheader\fP.
+It contains the first line of the terminfo description,
+listing the various names for the terminal,
+separated by the \*(``|\*('' character.
+The \fIterminal names\fP section is terminated
+with an \s-1ASCII NUL\s+1 character.
+.PP
+The \fIboolean flags\fP section has one byte for each flag.
+Boolean capabilities are either 1 or 0 (true or false)
+according to whether the terminal supports the given capability or not.
+.PP
+Between the \fIboolean flags\fP section and the \fInumber\fP section,
+a null byte will be inserted, if necessary,
+to ensure that the \fInumber\fP section begins on an even byte
+This is a relic of the PDP\-11's word-addressed architecture,
+originally designed to avoid traps induced
+by addressing a word on an odd byte boundary.
+All short integers are aligned on a short word boundary.
+.PP
+The \fInumbers\fP section is similar to the \fIboolean flags\fP section.
+Each capability takes up two bytes,
+and is stored as a little-endian short integer.
+.PP
+The \fIstrings\fP section is also similar.
+Each capability is stored as a short integer.
+The capability value is an index into the \fIstring table\fP.
+.PP
+The \fIstring table\fP is the last section.
+It contains all of the values of string capabilities referenced in
+the \fIstrings\fP section.
+Each string is null-terminated.
+Special characters in ^X or \ec notation are stored in their
+interpreted form, not the printing representation.
+Padding information $<nn> and parameter information %x are
+stored intact in uninterpreted form.
+.SS EXTENDED STORAGE FORMAT
+The previous section describes the conventional terminfo binary format.
+With some minor variations of the offsets (see PORTABILITY),
+the same binary format is used in all modern UNIX systems.
+Each system uses a predefined set of boolean, number or string capabilities.
+.PP
+The \fBncurses\fP libraries and applications support
+extended terminfo binary format,
+allowing users to define capabilities which are loaded at runtime.
+This
+extension is made possible by using the fact that the other implementations
+stop reading the terminfo data when they have reached the end of the size given
+in the header.
+\fBncurses\fP checks the size,
+and if it exceeds that due to the predefined data,
+continues to parse according to its own scheme.
+.PP
+First, it reads the extended header (5 short integers):
+.RS 5
+.TP 5
+(1)
+count of extended boolean capabilities
+.TP 5
+(2)
+count of extended numeric capabilities
+.TP 5
+(3)
+count of extended string capabilities
+.TP 5
+(4)
+count of the items in extended string table
+.TP 5
+(5)
+size of the extended string table in bytes
+.RE
+.PP
+The count- and size-values for the extended string table
+include the extended capability \fInames\fP as well as
+extended capability \fIvalues\fP.
+.PP
+Using the counts and sizes, \fBncurses\fP allocates arrays and reads data
+for the extended capabilities in the same order as the header information.
+.PP
+The extended string table contains values for string capabilities.
+After the end of these values, it contains the names for each of
+the extended capabilities in order, e.g., booleans, then numbers and
+finally strings.
+.PP
+Applications which manipulate terminal data can use the definitions
+described in \fBterm_variables\fP(3) which associate the long capability
+names with members of a \fBTERMTYPE\fP structure.
+.
+.SS EXTENDED NUMBER FORMAT
+On occasion, 16-bit signed integers are not large enough.
+With \fBncurses\fP 6.1, a new format was introduced by making a few changes
+to the legacy format:
+.bP
+a different magic number (octal 01036)
+.bP
+changing the type for the \fInumber\fP array from signed 16-bit integers
+to signed 32-bit integers.
+.PP
+To maintain compatibility, the library presents the same data structures
+to direct users of the \fBTERMTYPE\fP structure as in previous formats.
+However, that cannot provide callers with the extended numbers.
+The library uses a similar but hidden data structure \fBTERMTYPE2\fP
+to provide data for the terminfo functions.
+.SH PORTABILITY
+.SS setupterm
+Note that it is possible for
+.B setupterm
+to expect a different set of capabilities
+than are actually present in the file.
+Either the database may have been updated since
+.B setupterm
+was recompiled
+(resulting in extra unrecognized entries in the file)
+or the program may have been recompiled more recently
+than the database was updated
+(resulting in missing entries).
+The routine
+.B setupterm
+must be prepared for both possibilities \-
+this is why the numbers and sizes are included.
+Also, new capabilities must always be added at the end of the lists
+of boolean, number, and string capabilities.
+.SS Binary format
+X/Open Curses does not specify a format for the terminfo database.
+UNIX System V curses used a directory-tree of binary files,
+one per terminal description.
+.PP
+Despite the consistent use of little-endian for numbers and the otherwise
+self-describing format, it is not wise to count on portability of binary
+terminfo entries between commercial UNIX versions.
+The problem is that there
+are at least three versions of terminfo (under HP\-UX, AIX, and OSF/1) which
+diverged from System V terminfo after SVr1, and have added extension
+capabilities to the string table that (in the binary format) collide with
+System V and XSI Curses extensions.
+See \fBterminfo\fP(\*n) for detailed
+discussion of terminfo source compatibility issues.
+.PP
+This implementation is by default compatible with the binary
+terminfo format used by Solaris curses,
+except in a few less-used details
+where it was found that the latter did not match X/Open Curses.
+The format used by the other Unix versions
+can be matched by building ncurses
+with different configuration options.
+.SS Magic codes
+The magic number in a binary terminfo file is the first 16-bits (two bytes).
+Besides making it more reliable for the library to check that a file
+is terminfo,
+utilities such as \fBfile\fP(1) also use that to tell what the file-format is.
+System V defined more than one magic number,
+with 0433, 0435 as screen-dumps (see \fBscr_dump\fP(5)).
+This implementation uses 01036 as a continuation of that sequence,
+but with a different high-order byte to avoid confusion.
+.SS The TERMTYPE structure
+Direct access to the \fBTERMTYPE\fP structure is provided for legacy
+applications.
+Portable applications should use the \fBtigetflag\fP and related functions
+described in \fBterminfo\fP(3) for reading terminal capabilities.
+.SS Mixed-case terminal names
+A small number of terminal descriptions use uppercase characters in
+their names.
+If the underlying filesystem ignores the difference between
+uppercase and lowercase,
+\fBncurses\fP represents the \*(``first character\*(''
+of the terminal name used as
+the intermediate level of a directory tree in (two-character) hexadecimal form.
+.SH EXAMPLE
+As an example, here is a description for the Lear-Siegler
+ADM\-3, a popular though rather stupid early terminal:
+.NS
+adm3a|lsi adm3a,
+        am,
+        cols#80, lines#24,
+        bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J,
+        cuf1=^L, cup=\\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
+        home=^^, ind=^J,
+.NE
+.PP
+and a hexadecimal dump of the compiled terminal description:
+.NS
+.ft CW
+\s-20000  1a 01 10 00 02 00 03 00  82 00 31 00 61 64 6d 33  ........ ..1.adm3
+0010  61 7c 6c 73 69 20 61 64  6d 33 61 00 00 01 50 00  a|lsi ad m3a...P.
+0020  ff ff 18 00 ff ff 00 00  02 00 ff ff ff ff 04 00  ........ ........
+0030  ff ff ff ff ff ff ff ff  0a 00 25 00 27 00 ff ff  ........ ..%.'...
+0040  29 00 ff ff ff ff 2b 00  ff ff 2d 00 ff ff ff ff  ).....+. ..-.....
+0050  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+0060  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+0070  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+0080  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+0090  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+00a0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+00b0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+00c0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+00d0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+00e0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+00f0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+0100  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+0110  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
+0120  ff ff ff ff ff ff 2f 00  07 00 0d 00 1a 24 3c 31  ....../. .....$<1
+0130  3e 00 1b 3d 25 70 31 25  7b 33 32 7d 25 2b 25 63  >..=%p1% {32}%+%c
+0140  25 70 32 25 7b 33 32 7d  25 2b 25 63 00 0a 00 1e  %p2%{32} %+%c....
+0150  00 08 00 0c 00 0b 00 0a  00                       ........ .\s+2
+.ft R
+.NE
+.sp
+.SH LIMITS
+Some limitations:
+.bP
+total compiled entries cannot exceed 4096 bytes in the legacy format.
+.bP
+total compiled entries cannot exceed 32768 bytes in the extended format.
+.bP
+the name field cannot exceed 128 bytes.
+.PP
+Compiled entries are limited to 32768 bytes because offsets into the
+\fIstrings table\fP use two-byte integers.
+The legacy format could have supported 32768-byte entries,
+but was limited a virtual memory page's 4096 bytes.
+.SH FILES
+\*d/*/* compiled terminal capability database
+.SH SEE ALSO
+\fBcurses\fP(3), \fBterminfo\fP(\*n).
+.SH AUTHORS
+Thomas E. Dickey
+.br
+extended terminfo format for ncurses 5.0
+.br
+hashed database support for ncurses 5.6
+.br
+extended number support for ncurses 6.1
+.sp
+Eric S. Raymond
+.br
+documented legacy terminfo format, e.g., from \fIpcurses\fP.