ispell

package: ispell

title: ispell(4)

text:
# ispell(4)

## NAME
ispell - format of ispell dictionaries and affix files

## DESCRIPTION
Ispell(1) requires two files to define the language that it is spell-checking. The first file is a dictionary containing words for the language, and the second is an "affix" file that defines the meaning of special flags in the dictionary. The two files are combined by buildhash (see ispell(1)) and written to a hash file which is not described here.

A raw ispell dictionary (either the main dictionary or your own personal dictionary) contains a list of words, one per line. Each word may optionally be followed by a slash ("/") and one or more flags, which modify the root word as explained below. Depending on the options with which ispell was built, case may or may not be significant in either the root word or the flags, independently. Specifically, if the compile-time option CAPITALIZATION is defined, case is significant in the root word; if not, case is ignored in the root word. If the compile-time option MASKBITS is set to a value of 32, case is ignored in the flags; otherwise case is significant in the flags. Contact your system administrator or ispell maintainer for more information (or use the -vv flag to find out). The dictionary should be sorted with the -f flag of sort(1) before the hash file is built; this is done automatically by munchlist(1), which is the normal way of building dictionaries.

If the dictionary contains words that have string characters (see the affix-file documentation below), they must be written in the format given by the defstringtype statement in the affix file. This will be the case for most non-English languages. Be careful to use this format, rather than that of your favorite formatter, when adding words to a dictionary. (If you add words to your personal dictionary during an ispell session, they will automatically be converted to the correct format. This feature can be used to convert an entire dictionary if necessary:)

```
	echo qqqqq > dummy.dict
	buildhash dummy.dict affix-file dummy.hash
	awk '{print "*"}END{print "#"}' old-dict-file \
	| ispell -a -T old-dict-string-type \
	  -d ./dummy.hash -p ./new-dict-file \
	  > /dev/null
	rm dummy.*
```

The case of the root word controls the case of words accepted by ispell, as follows:

(1)

If the root word appears only in lower case (e.g., bob), it will be accepted in lower case, capitalized, or all capitals.

(2)

If the root word appears capitalized (e.g., Robert), it will not be accepted in all-lower case, but will be accepted capitalized or all in capitals.

(3)

If the root word appears all in capitals (e.g., UNIX), it will only be accepted all in capitals.

(4)

If the root word appears with a "funny" capitalization (e.g., ITCorp), a word will be accepted only if it follows that capitalization, or if it appears all in capitals.

(5)

More than one capitalization of a root word may appear in the dictionary. Flags from different capitalizations are combined by OR-ing them together.

Redundant capitalizations (e.g., bob and Bob) will be combined by buildhash and by ispell (for personal dictionaries), and can be removed from a raw dictionary by munchlist.

For example, the dictionary:

```
bob
Robert
UNIX
ITcorp
ITCorp
```

will accept bob, Bob, BOB, Robert, ROBERT, UNIX, ITcorp, ITCorp, and ITCORP, and will reject all others. Some of the unacceptable forms are bOb, robert, Unix, and ItCorp.

As mentioned above, root words in any dictionary may be extended by flags. Each flag is a single alphabetic character, which represents a prefix or suffix that may be added to the root to form a new word. For example, in an English dictionary the D flag can be added to bathe to make bathed. Since flags are represented as a single bit in the hashed dictionary, this results in significant space savings. The munchlist script will reduce an existing raw dictionary by adding flags when possible.

When a word is extended with an affix, the affix will be accepted only if it appears in the same case as the initial (prefix) or final (suffix) letter of the word. Thus, for example, the entry UNIX/M in the main dictionary (M means add an apostrophe and an "s" to make a possessive) would accept UNIX'S but would reject UNIX's. If UNIX's is legal, it must appear as a separate dictionary entry, and it will not be combined by munchlist. (In general, you don't need to worry about these things; munchlist guarantees that its output dictionary will accept the same set of words as its input, so all you have to do is add words to the dictionary and occasionally run munchlist to reduce its size).

As mentioned, the affix definition file describes the affixes associated with particular flags. It also describes the character set used by the language.

Although the affix-definition grammar is designed for a line-oriented layout, it is actually a free-format yacc grammar and can be laid out weirdly if you want. Comments are started by a pound (sharp) sign (#), and continue to the end of the line. Backslashes are supported in the usual fashion (\nnn, plus specials \n, \r, \t, \v, \f, \b, and the new hex format \xnn). Any character with special meaning to the parser can be changed to an uninterpreted token by backslashing it; for example, you can declare a flag named 'asterisk' or 'colon' with flag \*: or flag \::.

The grammar will be presented in a top-down fashion, with discussion of each element. An affix-definition file must contain exactly one table:

```
table	:	[headers] [prefixes] [suffixes]
```

At least one of prefixes and suffixes is required. They can appear in either order.

```
headers	:	[ options ] char-sets
```

The headers describe options global to this dictionary and language. These include the character sets to be used and the formatter, and the defaults for certain ispell flags.

```
options :	{ fmtr-stmt | opt-stmt | flag-stmt | num-stmt }
```

The options statements define the defaults for certain ispell flags and for the character sets used by the formatters.

```
fmtr-stmt	:	{ nroff-stmt | tex-stmt }
```

A fmtr-stmt describes characters that have special meaning to a formatter. Normally, this statement is not necessary, but some languages may have preempted the usual defaults for use as language-specific characters. In this case, these statements may be used to redefine the special characters expected by the formatter.

```
nroff-stmt	:	{ nroffchars | troffchars } string
```

The nroffchars statement allows redefinition of certain nroff control characters. The string given must be exactly five characters long, and must list substitutions for the left and right parentheses ("()") , the period ("."), the backslash ("\"), and the asterisk ("*"). (The right parenthesis is not currently used, but is included for completeness.) For example, the statement:

```
nroffchars {}.\\*
```

would replace the left and right parentheses with left and right curly braces for purposes of parsing nroff/troff strings, with no effect on the others (admittedly a contrived example). Note that the backslash is escaped with a backslash.

```
tex-stmt	:	{ TeXchars | texchars } string
```

The TeXchars statement allows redefinition of certain TeX/LaTeX control characters. The string given must be exactly thirteen characters long, and must list substitutions for the left and right parentheses ("()") , the left and right square brackets ("[]"), the left and right curly braces ("{}"), the left and right angle brackets ("<>"), the backslash ("\"), the dollar sign ("$"), the asterisk ("*"), the period or dot ("."), and the percent sign ("%"). For example, the statement:

```
texchars ()\[]<\><\>\\$*.%
```

would replace the functions of the left and right curly braces with the left and right angle brackets for purposes of parsing TeX/LaTeX constructs, while retaining their functions for the tib bibliographic preprocessor. Note that the backslash, the left square bracket, and the right angle bracket must be escaped with a backslash.

```
opt-stmt	:	{ cmpnd-stmt | aff-stmt }

cmpnd-stmt	:	compoundwords compound-opt

aff-stmt		:	allaffixes on-or-off

on-or-off	:	{ on | off }

compound-opt :	{ on-or-off | controlled character }
```

An opt-stmt controls certain ispell defaults that are best made language-specific. The allaffixes statement controls the default for the -P and -m options to ispell. If allaffixes is turned off (the default), ispell will default to the behavior of the -P flag: root/affix suggestions will only be made if there are no "near misses". If allaffixes is turned on, ispell will default to the behavior of the -m flag: root/affix suggestions will always be made. The compoundwords statement controls the default for the -B and -C options to ispell. If compoundwords is turned off (the default), ispell will default to the behavior of the -B flag: run-together words will be reported as errors. If compoundwords is turned on, ispell will default to the behavior of the -C flag: run-together words will be considered as compounds if both are in the dictionary. This is useful for languages such as German and Norwegian, which form large numbers of compound words. Finally, if compoundwords is set to controlled, only words marked with the flag indicated by character (which should not be otherwise used) will be allowed to participate in compound formation. Because this option requires the flags to be specified in the dictionary, it is not available from the command line.

```
flag-stmt	:	flagmarker character
```

The flagmarker statement describes the character which is used to separate affix flags from the root word in a raw dictionary file. This must be a character which is not found in any word (including in string characters; see below). The default is "/" because this character is not normally used to represent special characters in any language.

```
num-stmt	:	compoundmin digit
```

The compoundmin statement controls the length of the two components of a compound word. This only has an effect if compoundwords is turned on or if the -C flag is given to ispell. In that case, only words at least as long as the given minimum will be accepted as components of a compound. The default is 3 characters.

```
char-sets	:	norm-sets [ alt-sets ]
```

The character-set section describes the characters that can be part of a word, and defines their collating order. There must always be a definition of "normal" character sets; in addition, there may be one or more partial definitions of "alternate" sets which are used with various text formatters.

```
norm-sets :	[ deftype ] charset-group
```

A "normal" character set may optionally begin with a definition of the file suffixes that make use of this set. Following this are one or more character-set declarations.

```
deftype :	defstringtype name deformatter suffix*
```

The defstringtype declaration gives a list of file suffixes which should make use of the default string characters defined as part of the base character set; it is only necessary if string characters are being defined. The name parameter is a string giving the unique name associated with these suffixes; often it is a formatter name. If the formatter is a member of the troff family, "nroff" should be used for the name associated with the most popular macro package; members of the TeX family should use "tex". Other names may be chosen freely, but they should be kept simple, as they are used in ispell 's -T switch to specify a formatter type. The deformatter parameter specifies the deformatting style to use when processing files with the given suffixes. Currently, this must be either tex or nroff. The suffix parameters are a whitespace-separated list of strings which, if present at the end of a filename, indicate that the associated set of string characters should be used by default for this file. For example, the suffix list for the troff family typically includes suffixes such as ".ms", ".me", ".mm", etc.

```
charset-group :	{ char-stmt | string-stmt | dup-stmt}*
```

A char-stmt describes single characters; a string-stmt describes characters that must appear together as a string, and which usually represent a single character in the target language. Either may also describe conversion between upper and lower case. A dup-stmt is used to describe alternate forms of string characters, so that a single dictionary may be used with several formatting programs that use different conventions for representing non-ASCII characters.

```
char-stmt	:	wordchars character-range
		|	wordchars lowercase-range uppercase-range
		|	boundarychars character-range
		|	boundarychars lowercase-range uppercase-range
string-stmt	:	stringchar string
		|	stringchar lowercase-string uppercase-string
```

Characters described with the boundarychars statement are considered part of a word only if they appear singly, embedded between characters declared with the wordchars or stringchar statements. For example, if the hyphen is a boundary character (useful in French), the string "foo-bar" would be a single word, but "-foo" would be the same as "foo", and "foo--bar" would be two words separated by non-word characters.

If two ranges or strings are given in a char-stmt or string-stmt, the first describes characters that are interpreted as lowercase and the second describes uppercase. In the case of a stringchar statement, the two strings must be of the same length. Also, in a stringchar statement, the actual strings may contain both uppercase and characters themselves without difficulty; for instance, the statement

```
stringchar	"\\*(sS"	"\\*(Ss"
```

is legal and will not interfere with (or be interfered with by) other declarations of of "s" and "S" as lower and upper case, respectively.

A final note on string characters: some languages collate certain special characters as if they were strings. For example, the German "a-umlaut" is traditionally sorted as if it were "ae". Ispell is not capable of this; each character must be treated as an individual entity. So in certain cases, ispell will sort a list of words into a different order than the standard "dictionary" order for the target language.

```
alt-sets	:	alttype [ alt-stmt* ]
```

Because different formatters use different notations to represent non-ASCII characters, ispell must be aware of the representations used by these formatters. These are declared as alternate sets of string characters.

```
alttype	:	altstringtype name suffix*
```

The altstringtype statement introduces each set by declaring the associated formatter name and filename suffix list. This name and list are interpreted exactly as in the defstringtype statement above. Following this header are one or more alt-stmts which declare the alternate string characters used by this formatter.

```
alt-stmt		:	altstringchar alt-string std-string
```

The altstringchar statement describes alternate representations for string characters. For example, the -mm macro package of troff represents the German "a-umlaut" as a\*:, while TeX uses the sequence \"a. If the troff versions are declared as the standard versions using stringchar, the TeX versions may be declared as alternates by using the statement

```
altstringchar	\\\"a	a\\*
```

When the altstringchar statement is used to specify alternate forms, all forms for a particular formatter must be declared together as a group. Also, each formatter or macro package must provide a complete set of characters, both upper- and lower-case, and the character sequences used for each formatter must be completely distinct. Character sequences which describe upper- and lower-case versions of the same printable character must also be the same length. It may be necessary to define some new macros for a given formatter to satisfy these restrictions. (The current version of buildhash does not enforce these restrictions, but failure to obey them may result in errors being introduced into files that are processed with ispell.)

An important minor point is that ispell assumes that all characters declared as wordchars or boundarychars will occupy exactly one position on the terminal screen.

A single character-set statement can declare either a single character or a contiguous range of characters. A range is given as in egrep and the shell: [a-z] means lowercase alphabetics; [^a-z] means all but lowercase, etc. All character-set statements are combined (unioned) to produce the final list of characters that may be part of a word. The collating order of the characters is defined by the order of their declaration; if a range is used, the characters are considered to have been declared in ASCII order. Characters that have case are collated next to each other, with the uppercase character first.

The character-declaration statements have a rather strange behavior caused by its need to match each lowercase character with its uppercase equivalent. In any given wordchars or boundarychars statement, the characters in each range are first sorted into ASCII collating sequence, then matched one-for-one with the other range. (The two ranges must have the same number of characters). Thus, for example, the two statements:

```
wordchars [aeiou] [AEIOU]
wordchars [aeiou] [UOIEA]
```

would produce exactly the same effect. To get the vowels to match up "wrong", you would have to use separate statements:

```
wordchars a U
wordchars e O
wordchars i I
wordchars o E
wordchars u A
```

which would cause uppercase 'e' to be 'O', and lowercase 'O' to be 'e'. This should normally be a problem only with languages which have been forced to use a strange ASCII collating sequence. If your uppercase and lowercase letters both collate in the same order, you shouldn't have to worry about this "feature".

The prefixes and suffixes sections have exactly the same syntax, except for the introductory keyword.

```
prefixes	:	prefixes flagdef*
suffixes	:	suffixes flagdef*
flagdef	:	flag [*|~] char : repl*
```

A prefix or suffix table consists of an introductory keyword and a list of flag definitions. Flags can be defined more than once, in which case the definitions are combined. Each flag controls one or more repls (replacements) which are conditionally applied to the beginnings or endings of various words.

Flags are named by a single character char. Depending on a configuration option, this character can be either any uppercase letter (the default configuration) or any 7-bit ASCII character. Most languages should be able to get along with just 26 flags.

A flag character may be prefixed with one or more option characters. (If you wish to use one of the option characters as a flag character, simply enclose it in double quotes.)

The asterisk (*) option means that this flag participates in cross-product formation. This only matters if the file contains both prefix and suffix tables. If so, all prefixes and suffixes marked with an asterisk will be applied in all cross-combinations to the root word. For example, consider the root fix with prefixes pre and in, and suffixes es and ed. If all flags controlling these prefixes and suffixes are marked with an asterisk, then the single root fix would also generate prefix, prefixes, prefixed, infix, infixes, infixed, fix, fixes, and fixed. Cross-product formation can produce a large number of words quickly, some of which may be illegal, so watch out. If cross-products produce illegal words, munchlist will not produce those flag combinations, and the flag will not be useful.

```
repl	:	condition* > [ - strip-string , ] append-string
```

The ~ option specifies that the associated flag is only active when a compound word is being formed. This is useful in a language like German, where the form of a word sometimes changes inside a compound.

A repl is a conditional rule for modifying a root word. Up to 8 conditions may be specified. If the conditions are satisfied, the rules on the right-hand side of the repl are applied, as follows:

(1)

If a strip-string is given, it is first stripped from the beginning or ending (as appropriate) of the root word.

(2)

Then the append-string is added at that point.

For example, the condition . means "any word", and the condition Y means "any word ending in Y". The following (suffix) replacements:

```
.	>	MENT
Y	>	-Y,IES
```

would change induce to inducement and fly to flies. (If they were controlled by the same flag, they would also change fly to flyment, which might not be what was wanted. Munchlist can be used to protect against this sort of problem; see the command sequence given below.)

No matter how much you might wish it, the strings on the right must be strings of specific characters, not ranges. The reasons are rooted deeply in the way ispell works, and it would be difficult or impossible to provide for more flexibility. For example, you might wish to write:

```
[EY]	>	-[EY],IES
```

This will not work. Instead, you must use two separate rules:

```
E	>	-E,IES
Y	>	-Y,IES
```

The application of repls can be restricted to certain words with conditions:

```
condition	:	{ . | character | range }
```

A condition is a restriction on the characters that adjoin, and/or are replaced by, the right-hand side of the repl. Up to 8 conditions may be given, which should be enough context for anyone. The right-hand side will be applied only if the conditions in the repl are satisfied. The conditions also implicitly define a length; roots shorter than the number of conditions will not pass the test. (As a special case, a condition of a single dot "." defines a length of zero, so that the rule applies to all words indiscriminately). This length is independent of the separate test that insists that all flags produce an output word length of at least four.

Conditions that are single characters should be separated by white space. For example, to specify words ending in "ED", write:

```
E D	>	-ED,ING		# As in covered > covering
```

If you write:

```
ED	>	-ED,ING
```

the effect will be the same as:

```
[ED]	>	-ED,ING
```

As a final minor, but important point, it is sometimes useful to rebuild a dictionary file using an incompatible suffix file. For example, suppose you expanded the "R" flag to generate "er" and "ers" (thus making the Z flag somewhat obsolete). To build a new dictionary newdict that, using newaffixes, will accept exactly the same list of words as the old list olddict did using oldaffixes, the -c switch of munchlist is useful, as in the following example:

```
$ munchlist -c oldaffixes -l newaffixes olddict > newdict
```

If you use this procedure, your new dictionary will always accept the same list the original did, even if you badly screwed up the affix file. This is because munchlist compares the words generated by a flag with the original word list, and refuses to use any flags that generate illegal words. (But don't forget that the munchlist step takes a long time and eats up temporary file space).

## EXAMPLES
As an example of conditional suffixes, here is the specification of the S flag from the English affix file:

```
flag *S:

    [^AEIOU]Y	>	-Y,IES	# As in imply > implies

    [AEIOU]Y	>	S		# As in convey > conveys

    [SXZH]	>	ES		# As in fix > fixes

    [^SXZHY]	>	S		# As in bat > bats
```

The first line applies to words ending in Y, but not in vowel-Y. The second takes care of the vowel-Y words. The third then handles those words that end in a sibilant or near-sibilant, and the last picks up everything else.

Note that the conditions are written very carefully so that they apply to disjoint sets of words. In particular, note that the fourth line excludes words ending in Y as well as the obvious SXZH. Otherwise, it would convert "imply" into "implys".

Although the English affix file does not do so, you can also have a flag generate more than one variation on a root word. For example, we could extend the English "R" flag as follows:

```
flag *R:

   E			>	R		# As in skate > skater

   E			>	RS		# As in skate > skaters

   [^AEIOU]Y	>	-Y,IER	# As in multiply > multiplier

   [^AEIOU]Y	>	-Y,IERS	# As in multiply > multipliers

   [AEIOU]Y	>	ER		# As in convey > conveyer

   [AEIOU]Y	>	ERS		# As in convey > conveyers

   [^EY]		>	ER		# As in build > builder

   [^EY]		>	ERS		# As in build > builders
```

This flag would generate both "skater" and "skaters" from "skate". This capability can be very useful in languages that make use of noun, verb, and adjective endings. For instance, one could define a single flag that generated all of the German "weak" verb endings.

## SEE ALSO
ispell(1)


english

package: ispell-en

title: english(4)

text:
# english(4)

## NAME
english - flag format for English ispell dictionaries

## DESCRIPTION
English dictionaries for ispell(1) supports 3 prefix and 14 suffix flags. For a detailed description of how ispell handles flags and capitalization, see ispell(4). This manual page only describes flags usable in dictionaries built using the english.aff affix file.

In the following discussion of the flags, let # and @ be "variables" that can stand for any letter. Upper case letters are constants. "..." stands for any string of zero or more letters, but note that no word may exist in the dictionary which is not at least 2 letters long, so, for example, "fly" may not be produced by placing the "Y" flag on "f". Also, no flag is effective unless the word that it creates is at least 4 letters long, so, for example, "wed" may not be produced by placing the "D" flag on "we".

In the following list, an asterisk indicates that a flag participates in cross-product formation (see ispell(4)).

The meaning of the prefix flags is as follows:

*A

... --> re... as in cover --> recover

*I

... --> in... as in firm --> infirm

*U

... --> un... as in able --> unable

The meaning of the suffix flags is as follows:

V

...e --> ...ive as in create --> creative

if # .ne. e, ...# --> ...#ive as in prevent --> preventive

*N

...e --> ...ion as in create --> creation

...y --> ...ication as in multiply --> multiplication

if # .ne. e or y, ...# --> ...#en as in fall --> fallen

*X

...e --> ...ions as in create --> creations

...y --> ...ications as in multiply --> multiplications

if # .ne. e or y, ...# --> ...#ens as in weak --> weakens

H

...y --> ...ieth as in twenty --> twentieth

if # .ne. y, ...# --> ...#th as in hundred --> hundredth

*Y

... --> ...ly as in quick --> quickly

*G

...e --> ...ing as in file --> filing

if # .ne. e, ...# --> ...#ing as in cross --> crossing

*J

...e --> ...ings as in file --> filings

if # .ne. e, ...# --> ...#ings as in cross --> crossings

*D

...e --> ...ed as in create --> created

if @ .ne. a, e, i, o, or u, ...@y --> ...@ied as in imply --> implied

if # .ne. e or y, or (# = y and @ = a, e, i, o, or u) ...@# --> ...@#ed as in cross --> crossed or convey --> conveyed

T

...e --> ...est as in late --> latest

if @ .ne. a, e, i, o, or u, ...@y --> ...@iest as in dirty --> dirtiest

if # .ne. e or y, or (# = y and @ = a, e, i, o, or u) ...@# --> ...@#est as in small --> smallest or gray --> grayest

*R

...e --> ...er as in skate --> skater

if @ .ne. a, e, i, o, or u, ...@y --> ...@ier as in multiply --> multiplier

if # .ne. e or y, or (# = y and @ = a, e, i, o, or u) ...@# --> ...@#er as in build --> builder or convey --> conveyer

*Z

...e --> ...ers as in skate --> skaters

if @ .ne. a, e, i, o, or u, ...@y --> ...@iers as in multiply --> multipliers

if # .ne. e or y, or (# = y and @ = a, e, i, o, or u) ...@# --> ...@#ers as in build --> builders or slay --> slayers

*S

if @ .ne. a, e, i, o, or u, ...@y --> ...@ies as in imply --> implies

if # .eq. s, x, z, or h, ...# --> ...#es as in fix --> fixes

if # .ne. s, x, z, h, or y, or (# = y and @ = a, e, i, o, or u) ...@# --> ...@#s as in bat --> bats or convey --> conveys

if @ .ne. a, e, i, o, or u, ...@y --> ...@iness as in cloudy --> cloudiness

if # .ne. y, or @ = a, e, i, o, or u, ...@# --> ...@#ness as in late --> lateness or gray --> grayness

*M

... --> ...'s as in dog --> dog's

To summarize more briefly:

Prefixes:

```
*A - re
*I - in
*U - un
```

Suffixes:

```
V - ive
*N - ion, tion, en
*X - ions, ications, ens
H - th, ieth
*Y - ly
*G - ing
*J - ings
*D - ed
T - est
*R - er
*Z - ers
*S - s, es, ies
*P - ness, iness
*M - 's
```

## SEE ALSO
ispell(1), ispell(4)

branch: sisyphus


atf-test-case

package: libatf-c

title: atf-test-case(4)

summary: generic description of test cases

text:
# atf-test-case(4)

## NAME
atf-test-case — generic description of test cases

## DESCRIPTION
A test case is a piece of code that stress-tests a specific feature of the software. This feature is typically self-contained enough, either in the amount of code that implements it or in the general idea that describes it, to warrant its independent testing. Given this, test cases are very fine-grained, but they attempt to group similar smaller tests which are semantically related.

A test case is defined by three components regardless of the language it is implemented in: a header, a body and a cleanup routine. The header is, basically, a declarative piece of code that defines several properties to describe what the test case does and how it behaves. In other words: it defines the test case's meta-data, further described in the Meta-data section. The body is the test case itself. It executes all actions needed to reproduce the test, and checks for failures. This body is only executed if the abstract conditions specified by the header are met. The cleanup routine is a piece of code always executed after the body, regardless of the exit status of the test case. It can be used to undo side-effects of the test case. Note that almost all side-effects of a test case are automatically cleaned up by the library; this is explained in more detail in the rest of this document.

It is extremely important to keep the separation between a test case's header and body well-defined, because the header is always parsed, whereas the body is only executed when the conditions defined in the header are met and when the user specifies that test case.

At last, test cases are always contained into test programs. The test programs act as a front-end to them, providing a consistent interface to the user and several APIs to ease their implementation.

### Results
Upon termination, a test case reports a status and, optionally, a textual reason describing why the test reported such status. The caller must ensure that the test case really performed the task that its status describes, as the test program may be bogus and therefore providing a misleading result (e.g. providing a result that indicates success but the error code of the program says otherwise).

The possible exit status of a test case are one of the following:

expected_death

The test case expects to terminate abruptly.

expected_exit

The test case expects to exit cleanly.

expected_failure

The test case expects to exit with a controller fatal/non-fatal failure. If this happens, the test program exits with a success error code.

expected_signal

The test case expects to receive a signal that makes it terminate.

expected_timeout

The test case expects to execute for longer than its timeout.

passed

The test case was executed successfully. The test program exits with a success error code.

skipped

The test case could not be executed because some preconditions were not met. This is not a failure because it can typically be resolved by adjusting the system to meet the necessary conditions. This is always accompanied by a reason, a message describing why the test was skipped. The test program exits with a success error code.

failed

An error appeared during the execution of the test case. This is always accompanied by a reason, a message describing why the test failed. The test program exits with a failure error code.

The usefulness of the ‘expected_*’ results comes when writing test cases that verify known failures caused, in general, due to programming errors (aka bugs). Whenever the faulty condition that the ‘expected_*’ result is trying to cover is fixed, then the test case will be reported as ‘failed’ and the developer will have to adjust it to match its new condition.

It is important to note that all ‘expected_*’ results are only provided as a hint to the caller; the caller must verify that the test case did actually terminate as the expected condition says.

### Input/output
Test cases are free to print whatever they want to their stdout(4) and stderr(4) file descriptors. They are, in fact, encouraged to print status information as they execute to keep the user informed of their actions. This is specially important for long test cases.

Test cases will log their results to an auxiliary file, which is then collected by the test program they are contained in. The developer need not care about this as long as he uses the correct APIs to implement the test cases.

The standard input of the test cases is unconditionally connected to ‘/dev/zero’.

### Meta-data
The following list describes all meta-data properties interpreted internally by ATF. You are free to define new properties in your test cases and use them as you wish, but non-standard properties must be prefixed by ‘X-’.

descr

Type: textual. Required. A brief textual description of the test case's purpose. Will be shown to the user in reports. Also good for documentation purposes.

has.cleanup

Type: boolean. Optional. If set to true, specifies that the test case has a cleanup routine that has to be executed by the runtime engine during the cleanup phase of the execution. This property is automatically set by the framework when defining a test case with a cleanup routine, so it should never be set by hand.

ident

Type: textual. Required. The test case's identifier. Must be unique inside the test program and should be short but descriptive.

require.arch

Type: textual. Optional. A whitespace separated list of architectures that the test case can be run under without causing errors due to an architecture mismatch.

require.config

Type: textual. Optional. A whitespace separated list of configuration variables that must be defined to execute the test case. If any of the required variables is not defined, the test case is skipped.

require.diskspace

Type: integer. Optional. Specifies the minimum amount of available disk space needed by the test. The value can have a size suffix such as ‘K’, ‘M’, ‘G’ or ‘T’ to make the amount of bytes easier to type and read.

require.files

Type: textual. Optional. A whitespace separated list of files that must be present to execute the test case. The names of these files must be absolute paths. If any of the required files is not found, the test case is skipped.

require.machine

Type: textual. Optional. A whitespace separated list of machine types that the test case can be run under without causing errors due to a machine type mismatch.

require.memory

Type: integer. Optional. Specifies the minimum amount of physical memory needed by the test. The value can have a size suffix such as ‘K’, ‘M’, ‘G’ or ‘T’ to make the amount of bytes easier to type and read.

require.progs

Type: textual. Optional. A whitespace separated list of programs that must be present to execute the test case. These can be given as plain names, in which case they are looked in the user's PATH, or as absolute paths. If any of the required programs is not found, the test case is skipped.

require.user

Type: textual. Optional. The required privileges to execute the test case. Can be one of ‘root’ or ‘unprivileged’.

If the test case is running as a regular user and this property is ‘root’, the test case is skipped.

If the test case is running as root and this property is ‘unprivileged’, the runtime engine will automatically drop the privileges if the ‘unprivileged-user’ configuration property is set; otherwise the test case is skipped.

timeout

Type: integral. Optional; defaults to ‘300’. Specifies the maximum amount of time the test case can run. This is particularly useful because some tests can stall either because they are incorrectly coded or because they trigger an anomalous behavior of the program. It is not acceptable for these tests to stall the whole execution of the test program.

Can optionally be set to zero, in which case the test case has no run-time limit. This is discouraged.

### Environment
Every time a test case is executed, several environment variables are cleared or reseted to sane values to ensure they do not make the test fail due to unexpected conditions. These variables are:

HOME

Set to the work directory's path.

LANG

Undefined.

LC_ALL

Undefined.

LC_COLLATE

Undefined.

LC_CTYPE

Undefined.

LC_MESSAGES

Undefined.

LC_MONETARY

Undefined.

LC_NUMERIC

Undefined.

LC_TIME

Undefined.

TZ

Hardcoded to ‘UTC’.

### Work directories
The test program always creates a temporary directory and switches to it before running the test case's body. This way the test case is free to modify its current directory as it wishes, and the runtime engine will be able to clean it up later on in a safe way, removing any traces of its execution from the system. To do so, the runtime engine will perform a recursive removal of the work directory without crossing mount points; if a mount point is found, the file system will be unmounted (if possible).

### File creation mode mask (umask)
Test cases are always executed with a file creation mode mask (umask) of ‘0022’. The test case's code is free to change this during execution.

## SEE ALSO
atf-test-program(1)


atmsigd.conf

package: linux-atm

title: atmsigd.conf(4)

text:
# atmsigd.conf(4)

## NAME
atmsigd.conf - configuration file for the ATM signaling demon

## SYNOPSIS
/etc/atmsigd.conf

## DESCRIPTION
atmsigd.conf contains configuration data for atmsigd. atmsigd reads atmsigd.conf after parsing the command line options, before connecting to the ATM network.

Configuration parameters are arranged in functional groups. In order to set a parameter, the name of the group, the name of the parameter, and the parameter value(s) have to be specified, e.g.

```
     sig level debug
```

decreases the logging threshold for messages related to signaling to the debug level. The following options are recognized: debug dump path

Specifies the directory to which atmsigd will write status and trace dumps. If tracing is not yet enabled, the trace size is automatically set to a (small) default value.

debug level level

Sets the default debug level to level. level can be any of debug, info, warn, error, and fatal. Only messages with the same or a higher priority than the debug level are printed. Note that the command-line option -d generates even more output (e.g. hexdumps of all packets passing between atmsigd and the network) than debug level debug.

debug log path

Specifies the file to which atmsigd writes logging messages. When using the special file name syslog, messages are send to the system logger instead. Log messages are written to standard output if no log file is specified. Writing to standard output can also be explicitly requested by using the special file name stderr.

debug trace [number]

Enables tracing and optionally sets the number of entries that should be kept in the trace buffer. A (small) default is used if the number is omitted.

io level level

Sets the debug level for IO-related messages to level.

io max_rate rate

Sets the rate to signal if an application requests the "maximum". See qos(7) for the syntax to use for expressing the rate. The default maximum rate is 353207 cells/second (OC3). (Note that the value of max_rate does not constrain the rates an application can explicitly request.)

io qos qos

Configures the signaling VC to use the specified QOS (see qos(7) for the syntax). By default, UBR at link speed is used on the signaling VC.

io vc [itf.]vpi.vci

Uses the specified VC for signaling messages instead of the usual 0.0.5.

saal level level

Sets the debug level for messages related to SAAL (i.e. SSCF and SSCOP) to level.

sig level level

Sets the debug level for messages related to signaling (Q.2931 or ISP) to level.

sig mode mode

Set the mode of operation. The following modes are available: user for the user side, network for the network side, and switch for operation in a switch. The default behaviour is user.

sig uni30

Use UNI 3.0 signaling. If specified together with sig uni31, this option sets UNI 3.1 signaling with a few backwards-compatibility extensions.

sig uni31

Use UNI 3.1 signaling. This option can be combined with sig uni30 (see above).

sig uni40

Use UNI 4.0 signaling. This option can be combined with sig q.2963.1 (see below).

sig q.2963.1

Enable peak cell rate renegotiation. This option is only available with UNI 4.0 signaling.

sig vpci vpci itf itf

Sets up a very simplistic type of routing. All calls with VPCI values equal to or greater than vpci will be routed to itf, and their VPI values will be set to the signaled VPCI minus vpci. Multiple sig vpci entries can be used to support an arbitrary number of interfaces. Example: with sig vpci 4 itf 1, a call signaled for VPCI/VCI 0.x is routed to 0.0.x, a call signaled for 6.y is routed to 1.2.y, etc.

policy level level

Sets the debug level for messages related to policy decisions to level.

policy decision direction address

Takes the specified decision for calls from or to address. decision can be either allow or reject. direction is either from or to. The address may be wildcarded by prepending a slash and the number of significant bits (NSAP) or digits (E.164). The rules are searched in the order in which they appear in atmsigd.conf until the first match. If no rule matches, the call is allowed.

entity [itf.]vpi.vci { options ... }

Activates a signaling entity on that specific VC. Multiple entity clauses can appear in the same configuration. When using entity, the option io vc is not available. entity is optionally followed by the following options, enclosed in curly braces: vpci (corresponds to sig vpci), mode (corresponds to sig mode), qos (corresponds to vc qos), route, and default. The last two options determine how outbound calls are routed. The route option is followed by an address in the format used for addresses in policy. If no route entry matches the called party number of an outbound call, the entry marked with default is selected.

When setting multiple parameters in the same group, the group name doesn't have to be repeated if it is followed by the parameters in curly braces. Example:

```
    debug {

        level warn

        dump /var/tmp

        log syslog

        trace 100

    }
```

Line breaks can be inserted in atmsigd.conf wherever spaces or tabs are allowed. Everything between a `#' and the end of the line is considered a comment. The `#' character cannot be escaped.

If an option is specified in atmsigd.conf and on the command line, the command line has priority. Certain options used by past versions of atmsigd but no longer documented on the man page are still recognized and supported, but they also yield a warning message. Future versions of atmsigd will not recognize those options.

## AUTHOR
Werner Almesberger, EPFL ICA <Werner.Almesberger@epfl.ch>

## SEE ALSO
atmsigd(8), qos(7), syslogd(8)


mailcap

package: mailcap

title: mailcap(4)

text:
# mailcap(4)

## NAME
mailcap - metamail capabilities file

## DESCRIPTION
The mailcap file is read by the metamail program to determine how to display non-text at the local site.

The syntax of a mailcap file is quite simple, at least compared to termcap files. Any line that starts with "#" is a comment. Blank lines are ignored. Otherwise, each line defines a single mailcap entry for a single content type. Long lines may be continued by ending them with a backslash character, \.

Each individual mailcap entry consists of a content-type specification, a command to execute, and (possibly) a set of optional "flag" values. For example, a very simple mailcap entry (which is actually a built-in default behavior for metamail) would look like this:

text/plain; cat %s

The optional flags can be used to specify additional information about the mail-handling command. For example:

text/plain; cat %s; copiousoutput

can be used to indicate that the output of the 'cat' command may be voluminous, requiring either a scrolling window, a pager, or some other appropriate coping mechanism.

The "type" field (text/plain, in the above example) is simply any legal content type name, as defined by RFC 822. In practice, this is almost any string. It is the string that will be matched against the "Content-type" header (or the value passed in with -c) to decide if this is the mailcap entry that matches the current message. Additionally, the type field may specify a subtype (e.g. "text/ISO-8859-1") or a wildcard to match all subtypes (e.g. "image/*").

The "command" field is any UNIX command ("cat %s" in the above example), and is used to specify the interpreter for the given type of message. It will be passed to the shell via the system(3) facility. Semicolons and backslashes within the command must be quoted with backslashes. If the command contains "%s", those two characters will be replaced by the name of a file that contains the body of the message. If it contains "%t', those two characters will be replaced by the content-type field, including the subtype, if any. (That is, if the content-type was "image/pbm; opt1=something-else", then "%t" would be replaced by "image/pbm".) If the command field contains "%{" followed by a parameter name and a closing "}", then all those characters will be replaced by the value of the named parameter, if any, from the Content-type header. Thus, in the previous example, "%{opt1}" will be replaced by "something-else". Finally, if the command contains "\%", those two characters will be replaced by a single % character. (In fact, the backslash can be used to quote any character, including itself.)

If no "%s" appears in the command field, then instead of placing the message body in a temporary file, metamail will pass the body to the command on the standard input. This is helpful in saving /tmp file space, but can be problematic for window-oriented applications under some window systems such as MGR.

Two special codes can appear in the viewing command for objects of type multipart (any subtype). These are "%n" and "%F". %n will be replaced by the number of parts within the multipart object. %F will be replaced by a series of arguments, two for each part, giving first the content-type and then the name of the temporary file where the decoded part has been stored. In addition, for each file created by %F, a second file is created, with the same name followed by "H", which contains the header information for that body part. This will not be needed by most multipart handlers, but it is there if you ever need it.

The "notes=xxx" field is an uninterpreted string that is used to specify the name of the person who installed this entry in the mailcap file. (The "xxx" may be replaced by any text string.)

The "test=xxx" field is a command that is executed to determine whether or not the mailcap line actually applies. That is, if the content-type field matches the content-type on the message, but a "test=" field is present, then the test must succeed before the mailcap line is considered to "match" the message being viewed. The command may be any UNIX command, using the same syntax and the same %-escapes as for the viewing command, as described above. A command is considered to succeed if it exits with a zero exit status, and to fail otherwise.

The "print=xxx" field is a command that is executed to print the data instead of display it interactively. This behavior is usually a consequence of invoking metamail with the "-h" switch.

The "textualnewlines" field can be used in the rather obscure case where metamail's default rules for treating newlines in base64-encoded data are unsatisfactory. By default, metamail will translate CRLF to the local newline character in decoded base64 output if the content-type is "text" (any subtype), but will not do so otherwise. A mailcap entry with a field of "textualnewlines=1" will force such translation for the specified content-type, while "textualnewlines=0" will guarantee that the translation does not take place even for textual content-types.

The "compose" field may be used to specify a program that can be used to compose a new body or body part in the given format. Its intended use is to support mail composing agents that support the composition of multiple types of mail using external composing agents. As with the view-command, the compose command will be executed after replacing certain escape sequences starting with "%". In particular, %s should be replaced by the name of a file to which the composed data is to be written by the specified composing program, thus allowing the calling program (e.g. metamail) to tell the called program where to store the composed data. If %s does not appear, then the composed data will be assumed to be written by the composing programs to standard output. The result of the composing program may be data that is NOT yet suitable for mail transport -- that is, a Content-Transfer-Encoding may still need to be applied to the data.

The "composetyped" field is similar to the "compose" field, but is to be used when the composing program needs to specify the Content-type header field to be applied to the composed data. The "compose" field is simpler, and is preferred for use with existing (non-mail-oriented) programs for composing data in a given format. The "composetyped" field is necessary when the Content-type information must include auxiliary parameters, and the composition program must then know enough about mail formats to produce output that includes the mail type information, and to apply any necessary Content-Transfer-Encoding. Conceptually, "compose" specifies a program that simply outputs the specified type of data in its raw form, while "composetyped" specifies a program that outputs the data as a MIME object, with all necessary Content-* headers already in place.

needsterminal

If this flag is given, the named interpreter needs to interact with the user on a terminal. In some environments (e.g. a window-oriented mail reader under X11) this will require the creation of a new terminal emulation window, while in most environments it will not. If the mailcap entry specifies "needsterminal" and metamail is not running on a terminal (as determined by isatty(3), the -x option, and the MM_NOTTTY environment variable) then metamail will try to run the command in a new terminal emulation window. Currently, metamail knows how to create new windows under the X11, SunTools, and WM window systems.

copiousoutput

This flag should be given whenever the interpreter is capable of producing more than a few lines of output on stdout, and does no interaction with the user. If the mailcap entry specifies copiousoutput, and pagination has been requested via the "-p" command, then the output of the command being executed will be piped through a pagination program ("more" by default, but this can be overridden with the METAMAIL_PAGER environment variable).

## BUILT-IN CONTENT-TYPE SUPPORT
The metamail program has built-in support for a few key content-types. In particular, it supports the text type, the multipart and multipart/alternative type, and the message/rfc822 types. This support is incomplete for many subtypes -- for example, it only supports US-ASCII text in general. This kind of built-in support can be OVERRIDDEN by an entry in any mailcap file on the user's search path. Metamail also has rudimentary built-in support for types that are totally unrecognized -- i.e. for which no mailcap entry or built-in handler exists. For such unrecognized types, metamail will write a file with a "clean" copy of the data -- i.e. a copy in which all mail headers have been removed, and in which any 7-bit transport encoding has been decoded.

## FILES
$HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap -- default path for mailcap files.

## SEE ALSO
metamail(1)

## COPYRIGHT
Copyright (c) 1991 Bell Communications Research, Inc. (Bellcore)

Permission to use, copy, modify, and distribute this material for any purpose and without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies, and that the name of Bellcore not be used in advertising or publicity pertaining to this material without the specific, prior written permission of an authorized representative of Bellcore. BELLCORE MAKES NO REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY OF THIS MATERIAL FOR ANY PURPOSE. IT IS PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.

## AUTHOR
Nathaniel S. Borenstein


cciss

package: man-pages

title: cciss(4)

summary: HP Smart Array block driver

text:
# cciss(4)

## NAME
cciss - HP Smart Array block driver

## SYNOPSIS

```
modprobe cciss [ cciss_allow_hpsa=1 ]
```

## DESCRIPTION
Note: This obsolete driver was removed in Linux 4.14, as it is superseded by the hpsa(4) driver in newer kernels.

cciss is a block driver for older HP Smart Array RAID controllers.

### Options
cciss_allow_hpsa=1: This option prevents the cciss driver from attempting to drive any controllers that the hpsa(4) driver is capable of controlling, which is to say, the cciss driver is restricted by this option to the following controllers:

```
    Smart Array 5300

    Smart Array 5i

    Smart Array 532

    Smart Array 5312

    Smart Array 641

    Smart Array 642

    Smart Array 6400

    Smart Array 6400 EM

    Smart Array 6i

    Smart Array P600

    Smart Array P400i

    Smart Array E200i

    Smart Array E200

    Smart Array E200i

    Smart Array E200i

    Smart Array E200i

    Smart Array E500
```

### Supported hardware
The cciss driver supports the following Smart Array boards:

```
    Smart Array 5300

    Smart Array 5i

    Smart Array 532

    Smart Array 5312

    Smart Array 641

    Smart Array 642

    Smart Array 6400

    Smart Array 6400 U320 Expansion Module

    Smart Array 6i

    Smart Array P600

    Smart Array P800

    Smart Array E400

    Smart Array P400i

    Smart Array E200

    Smart Array E200i

    Smart Array E500

    Smart Array P700m

    Smart Array P212

    Smart Array P410

    Smart Array P410i

    Smart Array P411

    Smart Array P812

    Smart Array P712m

    Smart Array P711m
```

### Configuration details
To configure HP Smart Array controllers, use the HP Array Configuration Utility (either hpacuxe(8) or hpacucli(8)) or the Offline ROM-based Configuration Utility (ORCA) run from the Smart Array's option ROM at boot time.

## FILES

### Device nodes
The device naming scheme is as follows:

Major numbers:

104

cciss0

105

cciss1

106

cciss2

105

cciss3

108

cciss4

109

cciss5

110

cciss6

111

cciss7

Minor numbers:

```
    b7 b6 b5 b4 b3 b2 b1 b0

    |----+----| |----+----|

         |           |

         |           +-------- Partition ID (0=wholedev, 1-15 partition)

         |

         +-------------------- Logical Volume number
```

The device naming scheme is:

/dev/cciss/c0d0

Controller 0, disk 0, whole device

/dev/cciss/c0d0p1

Controller 0, disk 0, partition 1

/dev/cciss/c0d0p2

Controller 0, disk 0, partition 2

/dev/cciss/c0d0p3

Controller 0, disk 0, partition 3

/dev/cciss/c1d1

Controller 1, disk 1, whole device

/dev/cciss/c1d1p1

Controller 1, disk 1, partition 1

/dev/cciss/c1d1p2

Controller 1, disk 1, partition 2

/dev/cciss/c1d1p3

Controller 1, disk 1, partition 3

### Files in /proc
The files /proc/driver/cciss/cciss[0-9]+ contain information about the configuration of each controller. For example:

```
$ cd /proc/driver/cciss
$ ls -l
total 0
-rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss0
-rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss1
-rw-r--r-- 1 root root 0 2010-09-10 10:38 cciss2
$ cat cciss2
cciss2: HP Smart Array P800 Controller
Board ID: 0x3223103c
Firmware Version: 7.14
IRQ: 16
Logical drives: 1
Current Q depth: 0
Current # commands on controller: 0
Max Q depth since init: 1
Max # commands on controller since init: 2
Max SG entries since init: 32
Sequential access devices: 0
cciss/c2d0:   36.38GB       RAID 0
```

### Files in /sys
/sys/bus/pci/devices/dev/ccissX/cXdY/model

Displays the SCSI INQUIRY page 0 model for logical drive Y of controller X.

/sys/bus/pci/devices/dev/ccissX/cXdY/rev

Displays the SCSI INQUIRY page 0 revision for logical drive Y of controller X.

/sys/bus/pci/devices/dev/ccissX/cXdY/unique_id

Displays the SCSI INQUIRY page 83 serial number for logical drive Y of controller X.

/sys/bus/pci/devices/dev/ccissX/cXdY/vendor

Displays the SCSI INQUIRY page 0 vendor for logical drive Y of controller X.

/sys/bus/pci/devices/dev/ccissX/cXdY/block:cciss!cXdY

A symbolic link to /sys/block/cciss!cXdY.

/sys/bus/pci/devices/dev/ccissX/rescan

When this file is written to, the driver rescans the controller to discover any new, removed, or modified logical drives.

/sys/bus/pci/devices/dev/ccissX/resettable

A value of 1 displayed in this file indicates that the "reset_devices=1" kernel parameter (used by kdump) is honored by this controller. A value of 0 indicates that the "reset_devices=1" kernel parameter will not be honored. Some models of Smart Array are not able to honor this parameter.

/sys/bus/pci/devices/dev/ccissX/cXdY/lunid

Displays the 8-byte LUN ID used to address logical drive Y of controller X.

/sys/bus/pci/devices/dev/ccissX/cXdY/raid_level

Displays the RAID level of logical drive Y of controller X.

/sys/bus/pci/devices/dev/ccissX/cXdY/usage_count

Displays the usage count (number of opens) of logical drive Y of controller X.

### SCSI tape drive and medium changer support
SCSI sequential access devices and medium changer devices are supported and appropriate device nodes are automatically created (e.g., /dev/st0, /dev/st1, etc.; see st(4) for more details.) You must enable "SCSI tape drive support for Smart Array 5xxx" and "SCSI support" in your kernel configuration to be able to use SCSI tape drives with your Smart Array 5xxx controller.

Additionally, note that the driver will not engage the SCSI core at init time. The driver must be directed to dynamically engage the SCSI core via the /proc filesystem entry, which the "block" side of the driver creates as /proc/driver/cciss/cciss* at run time. This is because at driver init time, the SCSI core may not yet be initialized (because the driver is a block driver) and attempting to register it with the SCSI core in such a case would cause a hang. This is best done via an initialization script (typically in /etc/init.d, but could vary depending on distribution). For example:

```
for x in /proc/driver/cciss/cciss[0-9]*
do

    echo "engage scsi" > $x
done
```

Once the SCSI core is engaged by the driver, it cannot be disengaged (except by unloading the driver, if it happens to be linked as a module.)

Note also that if no sequential access devices or medium changers are detected, the SCSI core will not be engaged by the action of the above script.

### Hot plug support for SCSI tape drives
Hot plugging of SCSI tape drives is supported, with some caveats. The cciss driver must be informed that changes to the SCSI bus have been made. This may be done via the /proc filesystem. For example:

echo "rescan" > /proc/scsi/cciss0/1

This causes the driver to:

(1)

query the adapter about changes to the physical SCSI buses and/or fiber channel arbitrated loop, and

(2)

make note of any new or removed sequential access devices or medium changers.

The driver will output messages indicating which devices have been added or removed and the controller, bus, target, and lun used to address each device. The driver then notifies the SCSI midlayer of these changes.

Note that the naming convention of the /proc filesystem entries contains a number in addition to the driver name (e.g., "cciss0" instead of just "cciss", which you might expect).

Note: Only sequential access devices and medium changers are presented as SCSI devices to the SCSI midlayer by the cciss driver. Specifically, physical SCSI disk drives are not presented to the SCSI midlayer. The only disk devices that are presented to the kernel are logical drives that the array controller constructs from regions on the physical drives. The logical drives are presented to the block layer (not to the SCSI midlayer). It is important for the driver to prevent the kernel from accessing the physical drives directly, since these drives are used by the array controller to construct the logical drives.

### SCSI error handling for tape drives and medium changers
The Linux SCSI midlayer provides an error-handling protocol that is initiated whenever a SCSI command fails to complete within a certain amount of time (which can vary depending on the command). The cciss driver participates in this protocol to some extent. The normal protocol is a four-step process:

(1)

First, the device is told to abort the command.

(2)

If that doesn't work, the device is reset.

(3)

If that doesn't work, the SCSI bus is reset.

(4)

If that doesn't work, the host bus adapter is reset.

The cciss driver is a block driver as well as a SCSI driver and only the tape drives and medium changers are presented to the SCSI midlayer. Furthermore, unlike more straightforward SCSI drivers, disk I/O continues through the block side during the SCSI error-recovery process. Therefore, the cciss driver implements only the first two of these actions, aborting the command, and resetting the device. Note also that most tape drives will not oblige in aborting commands, and sometimes it appears they will not even obey a reset command, though in most circumstances they will. If the command cannot be aborted and the device cannot be reset, the device will be set offline.

In the event that the error-handling code is triggered and a tape drive is successfully reset or the tardy command is successfully aborted, the tape drive may still not allow I/O to continue until some command is issued that positions the tape to a known position. Typically you must rewind the tape (by issuing mt -f /dev/st0 rewind for example) before I/O can proceed again to a tape drive that was reset.

## SEE ALSO
hpsa(4), cciss_vol_status(8), hpacucli(8), hpacuxe(8)

http://cciss.sf.net, and Documentation/blockdev/cciss.txt and Documentation/ABI/testing/sysfs-bus-pci-devices-cciss in the Linux kernel source tree


title: console_codes(4)

text:
# console_codes(4)

## NAME
console_codes - Linux console escape and control sequences

## DESCRIPTION
The Linux console implements a large subset of the VT102 and ECMA-48/ISO 6429/ANSI X3.64 terminal controls, plus certain private-mode sequences for changing the color palette, character-set mapping, and so on. In the tabular descriptions below, the second column gives ECMA-48 or DEC mnemonics (the latter if prefixed with DEC) for the given function. Sequences without a mnemonic are neither ECMA-48 nor VT102.

After all the normal output processing has been done, and a stream of characters arrives at the console driver for actual printing, the first thing that happens is a translation from the code used for processing to the code used for printing.

If the console is in UTF-8 mode, then the incoming bytes are first assembled into 16-bit Unicode codes. Otherwise, each byte is transformed according to the current mapping table (which translates it to a Unicode value). See the Character Sets section below for discussion.

In the normal case, the Unicode value is converted to a font index, and this is stored in video memory, so that the corresponding glyph (as found in video ROM) appears on the screen. Note that the use of Unicode (and the design of the PC hardware) allows us to use 512 different glyphs simultaneously.

If the current Unicode value is a control character, or we are currently processing an escape sequence, the value will treated specially. Instead of being turned into a font index and rendered as a glyph, it may trigger cursor movement or other control functions. See the Linux Console Controls section below for discussion.

It is generally not good practice to hard-wire terminal controls into programs. Linux supports a terminfo(5) database of terminal capabilities. Rather than emitting console escape sequences by hand, you will almost always want to use a terminfo-aware screen library or utility such as ncurses(3), tput(1), or reset(1).

### Linux console controls
This section describes all the control characters and escape sequences that invoke special functions (i.e., anything other than writing a glyph at the current cursor location) on the Linux console.

Control characters

A character is a control character if (before transformation according to the mapping table) it has one of the 14 codes 00 (NUL), 07 (BEL), 08 (BS), 09 (HT), 0a (LF), 0b (VT), 0c (FF), 0d (CR), 0e (SO), 0f (SI), 18 (CAN), 1a (SUB), 1b (ESC), 7f (DEL). One can set a "display control characters" mode (see below), and allow 07, 09, 0b, 18, 1a, 7f to be displayed as glyphs. On the other hand, in UTF-8 mode all codes 00–1f are regarded as control characters, regardless of any "display control characters" mode.

If we have a control character, it is acted upon immediately and then discarded (even in the middle of an escape sequence) and the escape sequence continues with the next character. (However, ESC starts a new escape sequence, possibly aborting a previous unfinished one, and CAN and SUB abort any escape sequence.) The recognized control characters are BEL, BS, HT, LF, VT, FF, CR, SO, SI, CAN, SUB, ESC, DEL, CSI. They do what one would expect:

BEL (0x07, ^G)

beeps;

BS (0x08, ^H)

backspaces one column (but not past the beginning of the line);

HT (0x09, ^I)

goes to the next tab stop or to the end of the line if there is no earlier tab stop;

LF (0x0A, ^J)

VT (0x0B, ^K)

FF (0x0C, ^L)

all give a linefeed, and if LF/NL (new-line mode) is set also a carriage return;

CR (0x0D, ^M)

gives a carriage return;

SO (0x0E, ^N)

activates the G1 character set;

SI (0x0F, ^O)

activates the G0 character set;

CAN (0x18, ^X)

SUB (0x1A, ^Z)

abort escape sequences;

ESC (0x1B, ^[)

starts an escape sequence;

DEL (0x7F)

is ignored;

CSI (0x9B)

is equivalent to ESC [.

ESC- but not CSI-sequences

ESC c

RIS

Reset.

ESC D

IND

Linefeed.

ESC E

NEL

Newline.

ESC H

HTS

Set tab stop at current column.

ESC M

RI

Reverse linefeed.

ESC Z

DECID

DEC private identification. The kernel returns the string ESC [ ? 6 c, claiming that it is a VT102.

ESC 7

DECSC

Save current state (cursor coordinates, attributes, character sets pointed at by G0, G1).

ESC 8

DECRC

Restore state most recently saved by ESC 7.

ESC %

Start sequence selecting character set

ESC % @

Select default (ISO 646 / ISO 8859-1)

ESC % G

Select UTF-8

ESC % 8

Select UTF-8 (obsolete)

ESC # 8

DECALN

DEC screen alignment test - fill screen with E's.

ESC (

Start sequence defining G0 character set (followed by one of B, 0, U, K, as below)

ESC ( B

Select default (ISO 8859-1 mapping).

ESC ( 0

Select VT100 graphics mapping.

ESC ( U

Select null mapping - straight to character ROM.

ESC ( K

Select user mapping - the map that is loaded by the utility mapscrn(8).

ESC )

Start sequence defining G1 (followed by one of B, 0, U, K, as above).

ESC >

DECPNM

Set numeric keypad mode

ESC =

DECPAM

Set application keypad mode

ESC ]

OSC

Operating System Command prefix.

ESC ] R

Reset palette.

ESC ] P

Set palette, with parameter given in 7 hexadecimal digits nrrggbb after the final P. Here n is the color (0–15), and rrggbb indicates the red/green/blue values (0–255).

ECMA-48 CSI sequences

CSI (or ESC [) is followed by a sequence of parameters, at most NPAR (16), that are decimal numbers separated by semicolons. An empty or absent parameter is taken to be 0. The sequence of parameters may be preceded by a single question mark.

However, after CSI [ (or ESC [ [) a single character is read and this entire sequence is ignored. (The idea is to ignore an echoed function key.)

The action of a CSI sequence is determined by its final character.

@

ICH

Insert the indicated # of blank characters.

A

CUU

Move cursor up the indicated # of rows.

B

CUD

Move cursor down the indicated # of rows.

C

CUF

Move cursor right the indicated # of columns.

D

CUB

Move cursor left the indicated # of columns.

E

CNL

Move cursor down the indicated # of rows, to column 1.

F

CPL

Move cursor up the indicated # of rows, to column 1.

G

CHA

Move cursor to indicated column in current row.

H

CUP

Move cursor to the indicated row, column (origin at 1,1).

J

ED

Erase display (default: from cursor to end of display).

ESC [ 1 J: erase from start to cursor.

ESC [ 2 J: erase whole display.

ESC [ 3 J: erase whole display including scroll-back buffer (since Linux 3.0).

K

EL

Erase line (default: from cursor to end of line).

ESC [ 1 K: erase from start of line to cursor.

ESC [ 2 K: erase whole line.

L

IL

Insert the indicated # of blank lines.

M

DL

Delete the indicated # of lines.

P

DCH

Delete the indicated # of characters on current line.

X

ECH

Erase the indicated # of characters on current line.

a

HPR

Move cursor right the indicated # of columns.

c

DA

Answer ESC [ ? 6 c: "I am a VT102".

d

VPA

Move cursor to the indicated row, current column.

e

VPR

Move cursor down the indicated # of rows.

f

HVP

Move cursor to the indicated row, column.

g

TBC

Without parameter: clear tab stop at current position.

ESC [ 3 g: delete all tab stops.

h

SM

Set Mode (see below).

l

RM

Reset Mode (see below).

m

SGR

Set attributes (see below).

n

DSR

Status report (see below).

q

DECLL

Set keyboard LEDs.

ESC [ 0 q: clear all LEDs

ESC [ 1 q: set Scroll Lock LED

ESC [ 2 q: set Num Lock LED

ESC [ 3 q: set Caps Lock LED

r

DECSTBM

Set scrolling region; parameters are top and bottom row.

s

?

Save cursor location.

u

?

Restore cursor location.

`

HPA

Move cursor to indicated column in current row.

ECMA-48 Select Graphic Rendition

The ECMA-48 SGR sequence ESC [ parameters m sets display attributes. Several attributes can be set in the same sequence, separated by semicolons. An empty parameter (between semicolons or string initiator or terminator) is interpreted as a zero.

param

result

0

reset all attributes to their defaults

1

set bold

2

set half-bright (simulated with color on a color display)

3

set italic (since Linux 2.6.22; simulated with color on a color display)

4

set underscore (simulated with color on a color display) (the colors used to simulate dim or underline are set using ESC ] ...)

5

set blink

7

set reverse video

10

reset selected mapping, display control flag, and toggle meta flag (ECMA-48 says "primary font").

11

select null mapping, set display control flag, reset toggle meta flag (ECMA-48 says "first alternate font").

12

select null mapping, set display control flag, set toggle meta flag (ECMA-48 says "second alternate font"). The toggle meta flag causes the high bit of a byte to be toggled before the mapping table translation is done.

21

set underline; before Linux 4.17, this value set normal intensity (as is done in many other terminals)

22

set normal intensity

23

italic off (since Linux 2.6.22)

24

underline off

25

blink off

27

reverse video off

30

set black foreground

31

set red foreground

32

set green foreground

33

set brown foreground

34

set blue foreground

35

set magenta foreground

36

set cyan foreground

37

set white foreground

38

256/24-bit foreground color follows, shoehorned into 16 basic colors (before Linux 3.16: set underscore on, set default foreground color)

39

set default foreground color (before Linux 3.16: set underscore off, set default foreground color)

40

set black background

41

set red background

42

set green background

43

set brown background

44

set blue background

45

set magenta background

46

set cyan background

47

set white background

48

256/24-bit background color follows, shoehorned into 8 basic colors

49

set default background color

90..97

set foreground to bright versions of 30..37

100..107

set background, same as 40..47 (bright not supported)

Commands 38 and 48 require further arguments:

;5;x

256 color: values 0..15 are IBGR (black, red, green, ... white), 16..231 a 6x6x6 color cube, 232..255 a grayscale ramp

;2;r;g;b

24-bit color, r/g/b components are in the range 0..255

ECMA-48 Mode Switches

ESC [ 3 h

DECCRM (default off): Display control chars.

ESC [ 4 h

DECIM (default off): Set insert mode.

ESC [ 20 h

LF/NL (default off): Automatically follow echo of LF, VT, or FF with CR.

ECMA-48 Status Report Commands

ESC [ 5 n

Device status report (DSR): Answer is ESC [ 0 n (Terminal OK).

ESC [ 6 n

Cursor position report (CPR): Answer is ESC [ y ; x R, where x,y is the cursor location.

DEC Private Mode (DECSET/DECRST) sequences

These are not described in ECMA-48. We list the Set Mode sequences; the Reset Mode sequences are obtained by replacing the final 'h' by 'l'.

ESC [ ? 1 h

DECCKM (default off): When set, the cursor keys send an ESC O prefix, rather than ESC [.

ESC [ ? 3 h

DECCOLM (default off = 80 columns): 80/132 col mode switch. The driver sources note that this alone does not suffice; some user-mode utility such as resizecons(8) has to change the hardware registers on the console video card.

ESC [ ? 5 h

DECSCNM (default off): Set reverse-video mode.

ESC [ ? 6 h

DECOM (default off): When set, cursor addressing is relative to the upper left corner of the scrolling region.

ESC [ ? 7 h

DECAWM (default on): Set autowrap on. In this mode, a graphic character emitted after column 80 (or column 132 of DECCOLM is on) forces a wrap to the beginning of the following line first.

ESC [ ? 8 h

DECARM (default on): Set keyboard autorepeat on.

ESC [ ? 9 h

X10 Mouse Reporting (default off): Set reporting mode to 1 (or reset to 0)—see below.

ESC [ ? 25 h

DECTECM (default on): Make cursor visible.

ESC [ ? 1000 h

X11 Mouse Reporting (default off): Set reporting mode to 2 (or reset to 0)—see below.

Linux Console Private CSI Sequences

The following sequences are neither ECMA-48 nor native VT102. They are native to the Linux console driver. Colors are in SGR parameters: 0 = black, 1 = red, 2 = green, 3 = brown, 4 = blue, 5 = magenta, 6 = cyan, 7 = white; 8–15 = bright versions of 0–7.

ESC [ 1 ; n ]

Set color n as the underline color.

ESC [ 2 ; n ]

Set color n as the dim color.

ESC [ 8 ]

Make the current color pair the default attributes.

ESC [ 9 ; n ]

Set screen blank timeout to n minutes.

ESC [ 10 ; n ]

Set bell frequency in Hz.

ESC [ 11 ; n ]

Set bell duration in msec.

ESC [ 12 ; n ]

Bring specified console to the front.

ESC [ 13 ]

Unblank the screen.

ESC [ 14 ; n ]

Set the VESA powerdown interval in minutes.

ESC [ 15 ]

Bring the previous console to the front (since Linux 2.6.0).

ESC [ 16 ; n ]

Set the cursor blink interval in milliseconds (since Linux 4.2).

### Character sets
The kernel knows about 4 translations of bytes into console-screen symbols. The four tables are: a) Latin1 -> PC, b) VT100 graphics -> PC, c) PC -> PC, d) user-defined.

There are two character sets, called G0 and G1, and one of them is the current character set. (Initially G0.) Typing ^N causes G1 to become current, ^O causes G0 to become current.

These variables G0 and G1 point at a translation table, and can be changed by the user. Initially they point at tables a) and b), respectively. The sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to point at translation table a), b), c), and d), respectively. The sequences ESC ) B and ESC ) 0 and ESC ) U and ESC ) K cause G1 to point at translation table a), b), c), and d), respectively.

The sequence ESC c causes a terminal reset, which is what you want if the screen is all garbled. The oft-advised "echo ^V^O" will make only G0 current, but there is no guarantee that G0 points at table a). In some distributions there is a program reset(1) that just does "echo ^[c". If your terminfo entry for the console is correct (and has an entry rs1=\Ec), then "tput reset" will also work.

The user-defined mapping table can be set using mapscrn(8). The result of the mapping is that if a symbol c is printed, the symbol s = map[c] is sent to the video memory. The bitmap that corresponds to s is found in the character ROM, and can be changed using setfont(8).

### Mouse tracking
The mouse tracking facility is intended to return xterm(1)-compatible mouse status reports. Because the console driver has no way to know the device or type of the mouse, these reports are returned in the console input stream only when the virtual terminal driver receives a mouse update ioctl. These ioctls must be generated by a mouse-aware user-mode application such as the gpm(8) daemon.

The mouse tracking escape sequences generated by xterm(1) encode numeric parameters in a single character as value+040. For example, '!' is 1. The screen coordinate system is 1-based.

The X10 compatibility mode sends an escape sequence on button press encoding the location and the mouse button pressed. It is enabled by sending ESC [ ? 9 h and disabled with ESC [ ? 9 l. On button press, xterm(1) sends ESC [ M bxy (6 characters). Here b is button-1, and x and y are the x and y coordinates of the mouse when the button was pressed. This is the same code the kernel also produces.

Normal tracking mode (not implemented in Linux 2.0.24) sends an escape sequence on both button press and release. Modifier information is also sent. It is enabled by sending ESC [ ? 1000 h and disabled with ESC [ ? 1000 l. On button press or release, xterm(1) sends ESC [ M bxy. The low two bits of b encode button information: 0=MB1 pressed, 1=MB2 pressed, 2=MB3 pressed, 3=release. The upper bits encode what modifiers were down when the button was pressed and are added together: 4=Shift, 8=Meta, 16=Control. Again x and y are the x and y coordinates of the mouse event. The upper left corner is (1,1).

### Comparisons with other terminals
Many different terminal types are described, like the Linux console, as being "VT100-compatible". Here we discuss differences between the Linux console and the two most important others, the DEC VT102 and xterm(1).

Control-character handling

The VT102 also recognized the following control characters:

NUL (0x00)

was ignored;

ENQ (0x05)

triggered an answerback message;

DC1 (0x11, ^Q, XON)

resumed transmission;

DC3 (0x13, ^S, XOFF)

caused VT100 to ignore (and stop transmitting) all codes except XOFF and XON.

VT100-like DC1/DC3 processing may be enabled by the terminal driver.

The xterm(1) program (in VT100 mode) recognizes the control characters BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC.

Escape sequences

VT100 console sequences not implemented on the Linux console:

ESC N

SS2

Single shift 2. (Select G2 character set for the next character only.)

ESC O

SS3

Single shift 3. (Select G3 character set for the next character only.)

ESC P

DCS

Device control string (ended by ESC \)

ESC X

SOS

Start of string.

ESC ^

PM

Privacy message (ended by ESC \)

ESC \

ST

String terminator

ESC * ...

Designate G2 character set

ESC + ...

Designate G3 character set

The program xterm(1) (in VT100 mode) recognizes ESC c, ESC # 8, ESC >, ESC =, ESC D, ESC E, ESC H, ESC M, ESC N, ESC O, ESC P ... ESC \, ESC Z (it answers ESC [ ? 1 ; 2 c, "I am a VT100 with advanced video option") and ESC ^ ... ESC \ with the same meanings as indicated above. It accepts ESC (, ESC ), ESC *, ESC + followed by 0, A, B for the DEC special character and line drawing set, UK, and US-ASCII, respectively.

The user can configure xterm(1) to respond to VT220-specific control sequences, and it will identify itself as a VT52, VT100, and up depending on the way it is configured and initialized.

It accepts ESC ] (OSC) for the setting of certain resources. In addition to the ECMA-48 string terminator (ST), xterm(1) accepts a BEL to terminate an OSC string. These are a few of the OSC control sequences recognized by xterm(1):

ESC ] 0 ; txt ST

Set icon name and window title to txt.

ESC ] 1 ; txt ST

Set icon name to txt.

ESC ] 2 ; txt ST

Set window title to txt.

ESC ] 4 ; num; txt ST

Set ANSI color num to txt.

ESC ] 10 ; txt ST

Set dynamic text color to txt.

ESC ] 4 6 ; name ST

Change log file to name (normally disabled by a compile-time option).

ESC ] 5 0 ; fn ST

Set font to fn.

It recognizes the following with slightly modified meaning (saving more state, behaving closer to VT100/VT220):

ESC 7 DECSC

Save cursor

ESC 8 DECRC

Restore cursor

It also recognizes

ESC F

Cursor to lower left corner of screen (if enabled by xterm(1)'s hpLowerleftBugCompat resource).

ESC l

Memory lock (per HP terminals).

Locks memory above the cursor.

ESC m

Memory unlock (per HP terminals).

ESC n

LS2

Invoke the G2 character set.

ESC o

LS3

Invoke the G3 character set.

ESC |

LS3R

Invoke the G3 character set as GR.

ESC }

LS2R

Invoke the G2 character set as GR.

ESC ~

LS1R

Invoke the G1 character set as GR.

It also recognizes ESC % and provides a more complete UTF-8 implementation than Linux console.

CSI Sequences

Old versions of xterm(1), for example, from X11R5, interpret the blink SGR as a bold SGR. Later versions which implemented ANSI colors, for example, XFree86 3.1.2A in 1995, improved this by allowing the blink attribute to be displayed as a color. Modern versions of xterm implement blink SGR as blinking text and still allow colored text as an alternate rendering of SGRs. Stock X11R6 versions did not recognize the color-setting SGRs until the X11R6.8 release, which incorporated XFree86 xterm. All ECMA-48 CSI sequences recognized by Linux are also recognized by xterm, however xterm(1) implements several ECMA-48 and DEC control sequences not recognized by Linux.

The xterm(1) program recognizes all of the DEC Private Mode sequences listed above, but none of the Linux private-mode sequences. For discussion of xterm(1)'s own private-mode sequences, refer to the Xterm Control Sequences document by Edward Moy, Stephen Gildea, and Thomas E. Dickey available with the X distribution. That document, though terse, is much longer than this manual page. For a chronological overview,

http://invisible-island.net/xterm/xterm.log.html

details changes to xterm.

The vttest program

http://invisible-island.net/vttest/

demonstrates many of these control sequences. The xterm(1) source distribution also contains sample scripts which exercise other features.

## NOTES
ESC 8 (DECRC) is not able to restore the character set changed with ESC %.

## BUGS
In Linux 2.0.23, CSI is broken, and NUL is not ignored inside escape sequences.

Some older kernel versions (after Linux 2.0) interpret 8-bit control sequences. These "C1 controls" use codes between 128 and 159 to replace ESC [, ESC ] and similar two-byte control sequence initiators. There are fragments of that in modern kernels (either overlooked or broken by changes to support UTF-8), but the implementation is incomplete and should be regarded as unreliable.

Linux "private mode" sequences do not follow the rules in ECMA-48 for private mode control sequences. In particular, those ending with ] do not use a standard terminating character. The OSC (set palette) sequence is a greater problem, since xterm(1) may interpret this as a control sequence which requires a string terminator (ST). Unlike the setterm(1) sequences which will be ignored (since they are invalid control sequences), the palette sequence will make xterm(1) appear to hang (though pressing the return-key will fix that). To accommodate applications which have been hardcoded to use Linux control sequences, set the xterm(1) resource brokenLinuxOSC to true.

An older version of this document implied that Linux recognizes the ECMA-48 control sequence for invisible text. It is ignored.

## SEE ALSO
ioctl_console(2), charsets(7)


cpuid

title: cpuid(4)

summary: x86 CPUID access device

text:
# cpuid(4)

## NAME
cpuid - x86 CPUID access device

## DESCRIPTION
CPUID provides an interface for querying information about the x86 CPU.

This device is accessed by lseek(2) or pread(2) to the appropriate CPUID level and reading in chunks of 16 bytes. A larger read size means multiple reads of consecutive levels.

The lower 32 bits of the file position is used as the incoming %eax, and the upper 32 bits of the file position as the incoming %ecx, the latter is intended for "counting" eax levels like eax=4.

This driver uses /dev/cpu/CPUNUM/cpuid, where CPUNUM is the minor number, and on an SMP box will direct the access to CPU CPUNUM as listed in /proc/cpuinfo.

This file is protected so that it can be read only by the user root, or members of the group root.

## NOTES
The CPUID instruction can be directly executed by a program using inline assembler. However this device allows convenient access to all CPUs without changing process affinity.

Most of the information in cpuid is reported by the kernel in cooked form either in /proc/cpuinfo or through subdirectories in /sys/devices/system/cpu. Direct CPUID access through this device should only be used in exceptional cases.

The cpuid driver is not auto-loaded. On modular kernels you might need to use the following command to load it explicitly before use:

```
$ modprobe cpuid
```

There is no support for CPUID functions that require additional input registers.

Very old x86 CPUs don't support CPUID.

## SEE ALSO
cpuid(1)

Intel Corporation, Intel 64 and IA-32 Architectures Software Developer's Manual Volume 2A: Instruction Set Reference, A-M, 3-180 CPUID reference.

Intel Corporation, Intel Processor Identification and the CPUID Instruction, Application note 485.


title: dsp56k(4)

summary: DSP56001 interface device

text:
# dsp56k(4)

## NAME
dsp56k - DSP56001 interface device

## SYNOPSIS

```
#include <asm/dsp56k.h>
```

```
ssize_t read(int fd, void *data, size_t length);
ssize_t write(int fd, void *data, size_t length);
```

```
int ioctl(int fd, DSP56K_UPLOAD, struct dsp56k_upload *program);
int ioctl(int fd, DSP56K_SET_TX_WSIZE, int wsize);
int ioctl(int fd, DSP56K_SET_RX_WSIZE, int wsize);
int ioctl(int fd, DSP56K_HOST_FLAGS, struct dsp56k_host_flags *flags);
int ioctl(int fd, DSP56K_HOST_CMD, int cmd);
```

## CONFIGURATION
The dsp56k device is a character device with major number 55 and minor number 0.

## DESCRIPTION
The Motorola DSP56001 is a fully programmable 24-bit digital signal processor found in Atari Falcon030-compatible computers. The dsp56k special file is used to control the DSP56001, and to send and receive data using the bidirectional handshaked host port.

To send a data stream to the signal processor, use write(2) to the device, and read(2) to receive processed data. The data can be sent or received in 8, 16, 24, or 32-bit quantities on the host side, but will always be seen as 24-bit quantities in the DSP56001.

The following ioctl(2) calls are used to control the dsp56k device:

DSP56K_UPLOAD

resets the DSP56001 and uploads a program. The third ioctl(2) argument must be a pointer to a struct dsp56k_upload with members bin pointing to a DSP56001 binary program, and len set to the length of the program, counted in 24-bit words.

DSP56K_SET_TX_WSIZE

sets the transmit word size. Allowed values are in the range 1 to 4, and is the number of bytes that will be sent at a time to the DSP56001. These data quantities will either be padded with bytes containing zero, or truncated to fit the native 24-bit data format of the DSP56001.

DSP56K_SET_RX_WSIZE

sets the receive word size. Allowed values are in the range 1 to 4, and is the number of bytes that will be received at a time from the DSP56001. These data quantities will either truncated, or padded with a null byte ('\0'), to fit the native 24-bit data format of the DSP56001.

DSP56K_HOST_FLAGS

read and write the host flags. The host flags are four general-purpose bits that can be read by both the hosting computer and the DSP56001. Bits 0 and 1 can be written by the host, and bits 2 and 3 can be written by the DSP56001.

To access the host flags, the third ioctl(2) argument must be a pointer to a struct dsp56k_host_flags. If bit 0 or 1 is set in the dir member, the corresponding bit in out will be written to the host flags. The state of all host flags will be returned in the lower four bits of the status member.

DSP56K_HOST_CMD

sends a host command. Allowed values are in the range 0 to 31, and is a user-defined command handled by the program running in the DSP56001.

## FILES
/dev/dsp56k

## SEE ALSO
linux/include/asm-m68k/dsp56k.h, linux/drivers/char/dsp56k.c, http://dsp56k.nocrew.org/, DSP56000/DSP56001 Digital Signal Processor User's Manual


fd

title: fd(4)

summary: floppy disk device

text:
# fd(4)

## NAME
fd - floppy disk device

## CONFIGURATION
Floppy drives are block devices with major number 2. Typically they are owned by root:floppy (i.e., user root, group floppy) and have either mode 0660 (access checking via group membership) or mode 0666 (everybody has access). The minor numbers encode the device type, drive number, and controller number. For each device type (that is, combination of density and track count) there is a base minor number. To this base number, add the drive's number on its controller and 128 if the drive is on the secondary controller. In the following device tables, n represents the drive number.

Warning: if you use formats with more tracks than supported by your drive, you may cause it mechanical damage. Trying once if more tracks than the usual 40/80 are supported should not damage it, but no warranty is given for that. If you are not sure, don't create device entries for those formats, so as to prevent their usage.

Drive-independent device files which automatically detect the media format and capacity:

Name

Base

minor #

fdn

0

5.25 inch double-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnd360

360

40

9

2

4

5.25 inch high-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnh360

360

40

9

2

20

fdnh410

410

41

10

2

48

fdnh420

420

42

10

2

64

fdnh720

720

80

9

2

24

fdnh880

880

80

11

2

80

fdnh1200

1200

80

15

2

8

fdnh1440

1440

80

18

2

40

fdnh1476

1476

82

18

2

56

fdnh1494

1494

83

18

2

72

fdnh1600

1600

80

20

2

92

3.5 inch double-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnu360

360

80

9

1

12

fdnu720

720

80

9

2

16

fdnu800

800

80

10

2

120

fdnu1040

1040

80

13

2

84

fdnu1120

1120

80

14

2

88

3.5 inch high-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnu360

360

40

9

2

12

fdnu720

720

80

9

2

16

fdnu820

820

82

10

2

52

fdnu830

830

83

10

2

68

fdnu1440

1440

80

18

2

28

fdnu1600

1600

80

20

2

124

fdnu1680

1680

80

21

2

44

fdnu1722

1722

82

21

2

60

fdnu1743

1743

83

21

2

76

fdnu1760

1760

80

22

2

96

fdnu1840

1840

80

23

2

116

fdnu1920

1920

80

24

2

100

3.5 inch extra-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnu2880

2880

80

36

2

32

fdnCompaQ

2880

80

36

2

36

fdnu3200

3200

80

40

2

104

fdnu3520

3520

80

44

2

108

fdnu3840

3840

80

48

2

112

## DESCRIPTION
fd special files access the floppy disk drives in raw mode. The following ioctl(2) calls are supported by fd devices:

FDCLRPRM

clears the media information of a drive (geometry of disk in drive).

FDSETPRM

sets the media information of a drive. The media information will be lost when the media is changed.

FDDEFPRM

sets the media information of a drive (geometry of disk in drive). The media information will not be lost when the media is changed. This will disable autodetection. In order to reenable autodetection, you have to issue an FDCLRPRM.

FDGETDRVTYP

returns the type of a drive (name parameter). For formats which work in several drive types, FDGETDRVTYP returns a name which is appropriate for the oldest drive type which supports this format.

FDFLUSH

invalidates the buffer cache for the given drive.

FDSETMAXERRS

sets the error thresholds for reporting errors, aborting the operation, recalibrating, resetting, and reading sector by sector.

FDSETMAXERRS

gets the current error thresholds.

FDGETDRVTYP

gets the internal name of the drive.

FDWERRORCLR

clears the write error statistics.

FDWERRORGET

reads the write error statistics. These include the total number of write errors, the location and disk of the first write error, and the location and disk of the last write error. Disks are identified by a generation number which is incremented at (almost) each disk change.

FDTWADDLE

Switch the drive motor off for a few microseconds. This might be needed in order to access a disk whose sectors are too close together.

FDSETDRVPRM

sets various drive parameters.

FDGETDRVPRM

reads these parameters back.

FDGETDRVSTAT

gets the cached drive state (disk changed, write protected et al.)

FDPOLLDRVSTAT

polls the drive and return its state.

FDGETFDCSTAT

gets the floppy controller state.

FDRESET

resets the floppy controller under certain conditions.

FDRAWCMD

sends a raw command to the floppy controller.

For more precise information, consult also the <linux/fd.h> and <linux/fdreg.h> include files, as well as the floppycontrol(1) manual page.

## FILES
/dev/fd*

## NOTES
The various formats permit reading and writing many types of disks. However, if a floppy is formatted with an inter-sector gap that is too small, performance may drop, to the point of needing a few seconds to access an entire track. To prevent this, use interleaved formats.

It is not possible to read floppies which are formatted using GCR (group code recording), which is used by Apple II and Macintosh computers (800k disks).

Reading floppies which are hard sectored (one hole per sector, with the index hole being a little skewed) is not supported. This used to be common with older 8-inch floppies.

## SEE ALSO
chown(1), floppycontrol(1), getfdprm(1), mknod(1), superformat(1), mount(8), setfdprm(8)


full

title: full(4)

summary: always full device

text:
# full(4)

## NAME
full - always full device

## CONFIGURATION
If your system does not have /dev/full created already, it can be created with the following commands:

```
mknod -m 666 /dev/full c 1 7
chown root:root /dev/full
```

## DESCRIPTION
The file /dev/full has major device number 1 and minor device number 7.

Writes to the /dev/full device fail with an ENOSPC error. This can be used to test how a program handles disk-full errors.

Reads from the /dev/full device will return \0 characters.

Seeks on /dev/full will always succeed.

## FILES
/dev/full

## SEE ALSO
mknod(1), null(4), zero(4)