ctags-lang-python

title: ctags-lang-python(7)

text:
# ctags-lang-python(7)

## NAME
ctags-lang-python - Random notes about tagging python source code with Universal-ctags

## SYNOPSIS

```
ctags ... --languages=+Python ...
ctags ... --language-force=Python ...
ctags ... --map-Python=+.py ...
```

## DESCRIPTION
This man page gathers random notes about tagging python source code.

## TAGGING IMPORT STATEMENTS

### Summary
import X

name

kind

role

other noticeable fields

X

module

imported

N/A

import X as Y

name

kind

role

other noticeable fields

X

module

indirectlyImported

N/A

Y

namespace

definition

nameref:module:X

from X import *

name

kind

role

other noticeable fields

X

module

namespace

N/A

from X import Y

name

kind

role

other noticeable fields

X

module

namespace

N/A

Y

unknown

imported

scope:module:X

from X import Y as Z

name

kind

role

other noticeable fields

X

module

namespace

N/A

Y

unknown

indirectlyImported

scope:module:X

Z

unknown

definition

nameref:unknown:X

### Examples
"input.py" .. code-block:: Python

import X0

"output.tags" with "--options=NONE -o - --extras=+r --fields=+rzK input.py" .. code-block:: tags

X0 input.py /^import X0$/;" kind:module roles:imported

A tag for an imported module has module kind with imported role. The module is not defined here; it is defined in another file. So the tag for the imported module is a reference tag; specify --extras=+r (or --extras=+{reference}) option for tagging it. "roles:" field enabled with --fields=+r is for recording the module is "imported" to the tag file.

"input.py" .. code-block:: Python

import X1 as Y1

"output.tags" with "--options=NONE -o - --extras=+r --fields=+rzK --fields-Python='+{nameref}' input.py"

```
X1      input.py        /^import X1 as Y1$/;"   kind:module     roles:indirectlyImported
Y1      input.py        /^import X1 as Y1$/;"   kind:namespace  roles:def       nameref:module:X1
```

"Y1" introduces a new name and is defined here. So "Y1" is tagged as a definition tag. "X1" is imported in a way that its name cannot be used in this source file. For letting client tools know that the name cannot be used, indirectlyImported role is assigned for "X1". "Y1" is the name for accessing objects defined in the module imported via "X1". For recording this relationship, nameref: field is attached to the tag of "Y1". Instead of module kind, namespace kind is assigned to "Y1" because "Y1" itself isn't a module.

"input.py" .. code-block:: Python

from X2 import *

"output.tags" with "--options=NONE -o - --extras=+r --fields=+rzK input.py"

```
X2      input.py        /^from X2 import \*$/;" kind:module     roles:namespace
```

The module is not defined here; it is defined in another file. So the tag for the imported module is a reference tag. Unlike "X0" in "import X0", "X2" may not be used because the names defined in "X2" can be used in this source file. To represent the difference namespace role is attached to "X2" instead of imported.

"input.py" .. code-block:: Python

from X3 import Y3

"output.tags" with "--options=NONE -o - --extras=+r --fields=+rzKZ input.py"

```
X3      input.py        /^from X3 import Y3$/;" kind:module     roles:namespace
Y3      input.py        /^from X3 import Y3$/;" kind:unknown    scope:module:X3 roles:imported
```

"Y3" is a name for a language object defined in "X3" module. "scope:module:X3" attached to "Y3" represents this relation between "Y3" and "X3". ctags assigns unknown kind to "Y3" because ctags cannot know whether "Y3" is a class, a variable, or a function from the input file.

"input.py" .. code-block:: Python

from X4 import Y4 as Z4

"output.tags" with "--options=NONE -o - --extras=+r --fields=+rzKZ input.py"

```
X4      input.py        /^from X4 import Y4 as Z4$/;"   kind:module     roles:namespace
Y4      input.py        /^from X4 import Y4 as Z4$/;"   kind:unknown    scope:module:X4 roles:indirectlyImported
Z4      input.py        /^from X4 import Y4 as Z4$/;"   kind:unknown    roles:def       nameref:unknown:Y4
```

"Y4" is similar to "Y3" of "from X3 import Y3" but the name cannot be used here. indirectlyImported role assigned to "Y4" representing this. "Z4" is the name for accessing the language object named in "Y4" in "X4" module. "nameref:unknown:Y4" attached to "Z4" and "scope:module:X4" attached to "Y4" represent the relations.

## LAMBDA EXPRESSION AND TYPE HINT

### Summary
id = lambda var0: var0

name

kind

role

other noticeable fields

id

function

definition

signature:(var0)

id_t: Callable[[int], int] = lambda var1: var1

name

kind

role

other noticeable fields

id_t

variable

definition

typeref:typename:Callable[[int], int] nameref:function:anonFuncN

anonFuncN

function

definition

signature:(var1)

### Examples
"input.py" .. code-block:: Python

from typing import Callable id = lambda var0: var0 id_t: Callable[[int], int] = lambda var1: var1

"output.tags" with "--options=NONE -o - --sort=no --fields=+KS --fields-Python='+{nameref}' --extras='+{anonymous}' input.py"

```
id      input.py        /^id = lambda var0: var0$/;"    function        signature:(var0)
id_t    input.py        /^id_t: Callable[[int], int] = lambda var1: var1$/;"\

        variable        typeref:typename:Callable[[int], int]   nameref:function:anonFunc84011d2c0101
anonFunc84011d2c0101    input.py        /^id_t: Callable[[int], int] = lambda var1: var1$/;"\

        function        signature:(var1)
```

If a variable ("id") with no type hint is initialized with a lambda expression, ctags assigns function kind for the tag of "id".

If a variable ("id_t") with a type hint is initialized with a lambda expression, ctags assigns variable kind for the tag of "id_t" with typeref: and nameref: fields. ctags fills typeref: field with the value of the type hint. The way of filling nameref: is a bit complicated.

For the lambda expression used in initializing the type-hint'ed variable, ctags creates anonymous extra tag ("anonFunc84011d2c0101"). ctags fills the nameref: field of "id_t" with the name of anonymous extra tag: "nameref:function:anonFunc84011d2c0101".

You may think why ctags does so complicated, and why ctags doesn't emit following tags output for the input:

```
id      input.py        /^id = \\$/;"   function        signature:(var0)
id_t    input.py        /^id_t: \\$/;"  function        typeref:typename:Callable[[int], int]   signature:(var1)
```

There is a reason. The other languages of ctags obey the following rule: ctags fills typeref: field for a tag of a callable object (like function) with the type of its return value. If we consider "id_t" is a function, its typeref: field should have "typename:int". However, for filling typeref: with "typename:int", ctags has to analyze "Callable[[int], int]" deeper. We don't want to do so.

## SEE ALSO
ctags(1), ctags-client-tools(7)


ctags-lang-verilog

package: universal-ctags

title: ctags-lang-verilog(7)

text:
# ctags-lang-verilog(7)

## NAME
ctags-lang-verilog -

## SYNOPSIS

```
ctags ... [--fields-Verilog=+{parameter}] ...
ctags ... [--kinds-systemverilog=+Q] [--fields-SystemVerilog=+{parameter}] ...
ctags --list-kinds-full={Verilog|SystemVerilog}
ctags --list-fields={Verilog|SystemVerilog}
```

Language

Language ID

File Mapping

Verilog

Verilog

.v

SystemVerilog

SystemVerilog

.sv, .svh, svi

## DESCRIPTION
This man page describes about the Verilog/SystemVerilog parser for Universal-ctags.

It assumes the input file is written in the correct grammer. Otherwise output of ctags is undefined.

### parameter field
If the field parameter is enabled, a tagfield parameter: is added on a parameter whose value can be overridden on an instantiated module, interface, or program. This is useful for a editor plugin or extension to enable auto-instatiation of modules with parameters which can be overridden.

```
$ ctags ... --fields-Verilog=+{parameter} ...
$ ctags ... --fields-SystemVerilog=+{parameter} ...
```

On the following source code tagfields parameter: are added on parameter P*, not on L*. Note that L4 and L6 is declared by parameter statement, but tagfields parameter: are not added, because they cannot be overridden.

"input.sv"

```
// compilation unit scope
parameter L1 = "synonym for the localparam";
module with_parameter_port_list #(

        P1,

        localparam L2 = P1+1,

        parameter P2)

        ( /*port list...*/ );

        parameter  L3 = "synonym for the localparam";

        localparam L4 = "localparam";

        // ...
endmodule
module with_empty_parameter_port_list #()

        ( /*port list...*/ );

        parameter  L5 = "synonym for the localparam";

        localparam L6 = "localparam";

        // ...
endmodule
module no_parameter_port_list

        ( /*port list...*/ );

        parameter  P3 = "parameter";

        localparam L7 = "localparam";

        // ...
endmodule
```

"output.tags" with "--options=NONE --sort=no -o - --fields-SystemVerilog=+{parameter} input.sv"

```
L1      foo.sv  /^parameter L1 = "synonym for the localparam";$/;"      c       parameter:
with_parameter_port_list foo.sv  /^module with_parameter_port_list #($/;" m
P1      foo.sv  /^    P1, $/;"  c       module:with_parameter_port_list  parameter:
L2      foo.sv  /^    localparam L2 = P1+1,$/;" c       module:with_parameter_port_list
P2      foo.sv  /^    parameter P2)$/;" c       module:with_parameter_port_list  parameter:
L3      foo.sv  /^    parameter  L3 = "synonym for the localparam";$/;" c       module:with_parameter_port_list
L4      foo.sv  /^    localparam L4 = "localparam";$/;" c       module:with_parameter_port_list
with_empty_parameter_port_list   foo.sv  /^module with_empty_parameter_port_list #()$/;"  m
L5      foo.sv  /^    parameter  L5 = "synonym for the localparam";$/;" c       module:with_empty_parameter_port_list
L6      foo.sv  /^    localparam L6 = "localparam";$/;" c       module:with_empty_parameter_port_list
no_parameter_port_list   foo.sv  /^module no_parameter_port_list$/;"      m
P3      foo.sv  /^    parameter  P3 = "parameter";$/;"  c       module:no_parameter_port_list    parameter:
L7      foo.sv  /^    localparam L7 = "localparam";$/;" c       module:no_parameter_port_list
```

## KNOWN ISSUES
See https://github.com/universal-ctags/ctags/issues/TBD.

## SEE ALSO
ctags(1), ctags-client-tools(7)


ctags-optlib

title: ctags-optlib(7)

text:
# ctags-optlib(7)

## NAME
ctags-optlib - Universal-ctags parser definition language

## SYNOPSIS

```
ctags [options] [file(s)]
etags [options] [file(s)]
```

## DESCRIPTION
Exuberant-ctags, the ancestor of Universal-ctags, has provided the way to define a new parser from command line. Universal-ctags extends and refines this feature. optlib parser is the name for such parser in Universal-ctags. "opt" intends a parser is defined with combination of command line options. "lib" intends an optlib parser can be more than ad-hoc personal configuration.

This man page is for people who want to define an optlib parser. The readers should read ctags(1) of Universal-ctags first. Following options are for defining (or customizing) a parser:

- --langdef=

- --kinddef-<LANG>=

- --map-<LANG>=

- --regex-<LANG>=

Following options are for controlling loading parser definition:

- --optlib-dir=[+]directory

- --options=file|directory

- --options-maybe=pathname

The design of options and notations for defining a parser in Exuberant-ctags may focus on reducing the number of typing by user. Reducing the number of typing is important for users who want to define (or customize) a parser quickly.

On the other hand, the design in Universal-ctags focuses on maintainability. The notation of Universal-ctags is redundant than that of Exuberant-ctags; the newly introduced kind should be declared explicitly, (long) names are approved than one-letter flags specifying kinds, and naming rules are stricter.

This man page explains only stable options and flags. Universal-ctags also introduces experimental options and flags which have names starting with _. For documentation on these options and flags, visit Universal-ctags web site at https://ctags.io/.

### Storing a parser definition to a file
Though it is possible to define a parser from command line, you don't want to type the same command line each time when you need the parser. You can store options for defining a parser into a file.

ctags loads files (preload files) listed in "FILES" section of ctags(1) at program starting up. You can put your parser definition needed usually to the files.

--options=pathname, --options-maybe=pathname, and --optlib-dir=[+]directory are for loading optlib files you need occasionally. See "COMMAND LINE INTERFACE" section of ctags(1) for these options.

As explained in FILES section of ctags(1), options for defining a parser listed line by line in an optlib file. Prefixed white spaces are ignored. A line starting with '#' is treated as a comment. Escaping shell meta character is not needed.

Use ".ctags" as file extension for optlib file. You can define multiple parsers in an optlib file but it is better to make a file for each parser definition.

--_echo=msg and --_force-quit=[num] options are for debugging optlib parser.

### Overview for defining a parser
1.

Design the parser You need know both the target language and the ctags' concepts (definition, reference, kind, role, field, extra). About the concepts, ctags(1) of Universal-ctags may help you.

2.

Give a name to the parser Use --langdef=name option. NAME is referred as <LANG> in the later steps.

3.

Give a file pattern or file extension for activating the parser Use --map-<LANG>=[+|-]extension|pattern.

4.

Define kinds Use --kinddef-<LANG>=letter,name,description option. Universal-ctags introduces this option. Exuberant-ctags doesn't have. In Exuberant-ctags, a kind is defined as a side effect of specifying --regex-<LANG>= option. So user doesn't have a chance to recognize how important the definition of kind.

5.

Define patterns Use --regex-<LANG>=/regexp/replacement/[kind-spec/][flags] option.

As KIND-SPEC, you can use the one-letter flag defined with --kinddef-<LANG>=letter,name,description option.

## EXAMPLE
This is the definition (pod.ctags) used in ctags for parsing pod (https://perldoc.perl.org/perlpod.html) file.

```
--langdef=pod
--map-pod=+.pod
--kinddef-pod=c,chapter,chapters
--kinddef-pod=s,section,sections
--kinddef-pod=S,subsection,subsections
--kinddef-pod=t,subsubsection,subsubsections
--regex-pod=/^=head1[ \t]+(.+)/\1/c/
--regex-pod=/^=head2[ \t]+(.+)/\1/s/
--regex-pod=/^=head3[ \t]+(.+)/\1/S/
--regex-pod=/^=head4[ \t]+(.+)/\1/t/
```

## OPTIONS
--langdef=name

Defines a new user-defined language, name, to be parsed with regular expressions. Once defined, name may be used in other options taking language names.

name must consist of alphanumeric characters, # , or +

('[a-zA-Z0-9#+]+'). The graph characters other than "#" and "+" are disallowed (or reserved). Some of them ('[-=:{.]') are disallowed because they can make the command line parser of ctags confused. The rest of them are just reserved for future extending ctags. "all" is an exception. "all" as name is not acceptable. It is a reserved word. See the description of --kinds-<LANG>=[+|-]kinds|* option in ctags(1) about how the reserved word is used.

The names of built-in parsers are capitalized. When ctags evaluates an option in a command line, and chooses a parser, ctags uses the names of parsers in a case-insensitive way. Therefore, giving a name started from a lowercase character doesn't help you to avoid the parser name confliction. However, in a tags file, ctags prints parser names in a case-sensitive way; it prints a parser name as specified in --langdef= option. Therefore, we recommend you to give a name started from a lowercase character to your private optlib parser. With this convention, people can know where a tag entry in a tag file comes from a built-in parser or a private optlib parser.

--list-regex-flags

Lists the flags that can be used in --regex-<LANG> option.

--kinddef-<LANG>=letter,name,description

Define a kind for <LANG>. Be not confused this with --kinds-<LANG>. letter must be an alphabetical character ('[a-zA-EG-Z]') other than "F". "F" has been reserved for representing a file since Exuberant-ctags.

name must start with an alphabetic character, and the rest must be alphanumeric ('[a-zA-Z][a-zA-Z0-9]*'). Do not use "file" as name. It has been reserved for representing a file since Exuberant-ctags.

Note that using a number character in a name violates the version 2 of tags file format though ctags accepts it. For more detail, see tags(5).

description comes from any printable ASCII characters. The exception is { and \. { is reserved for adding flags this option in the future. So put \ before { to include { to a description. To include \ itself to a description, put \ before \.

Both letter, name and their combination must be unique in a <LANG>.

This option is newly introduced in Universal-ctags. This option reduces the typing defining a regex pattern with --regex-<LANG>=, and keeps the consistency of kind definitions in a language.

The letter can be used as an argument for --kinds-<LANG> option to enable or disable the kind. Unless K field is enabled, the letter is used as value in the "kind" extension field in tags output.

The name surrounded by braces can be used as an argument for --kind-<LANG> option. If K field is enabled, the name is used as value in the "kind" extension field in tags output.

The description and letter are listed in --list-kinds output. All three elements of kind-spec are listed in --list-kinds-full output. Don't use braces in the description. They will be used meta characters in the future.

--regex-<LANG>=/regexp/replacement/[kind-spec/][flags]

The /regexp/replacement/ pair defines a regular expression replacement pattern, similar in style to sed substitution commands, with which to generate tags from source files mapped to the named language, <LANG>, (case-insensitive; either a built-in or user-defined language). The regular expression, regexp, defines an extended regular expression (roughly that used by egrep(1)), which is used to locate a single source line containing a tag and may specify tab characters using \t. When a matching line is found, a tag will be generated for the name defined by replacement, which generally will contain the special back-references \1 through \9 to refer to matching sub-expression groups within regexp. The / separator characters shown in the parameter to the option can actually be replaced by any character. Note that whichever separator character is used will have to be escaped with a backslash (\) character wherever it is used in the parameter as something other than a separator. The regular expression defined by this option is added to the current list of regular expressions for the specified language unless the parameter is omitted, in which case the current list is cleared. Unless modified by flags, regexp is interpreted as a Posix extended regular expression. The replacement should expand for all matching lines to a non-empty string of characters, or a warning message will be reported unless {placeholder} regex flag is specified. An optional kind specifier for tags matching regexp may follow replacement, which will determine what kind of tag is reported in the "kind" extension field (see tags(5)).

kind-spec has two forms: one-letter form and full form. The one-letter form assumes using --regex-<LANG> option with --kinddef-<LANG> option. The kind-spec in --regex-<LANG> option just refers a letter defined with --kinddef-<LANG>. This form is recommended in Universal-ctags.

The full form of kind-spec is in the form of a single letter, a comma, a name, a comma, a description. See the description of --kinddef-<LANG>=letter,name,description option about how the elements are used.

Either the kind name and/or the description can be omitted. However, unless the letter is not defined with --kinddef-<LANG> option, omitting is not recommended in Universal-ctags. The omitting form is supported only for keeping the compatibility with Exuberant-ctags. Supporting the omitting form will be removed from Universal-ctags in the future. If kind-spec is omitted, it defaults to "r,regex".

About flag, see "Flags for --regex-<LANG> option".

For more information on the regular expressions used by ctags, see either the regex(5,7) man page, or the GNU info documentation for regex (e.g. "info regex").

--_echo=msg

Print msg to the standard error stream. This is helpful to understand (and debug) optlib loading feature of Universal-ctags.

--_force-quit=[num]

Exits immediately when this option is processed. If num is used as exit status. The default is 0. This is helpful to debug optlib loading feature of Universal-ctags.

## FLAGS FOR --REGEX-<LANG> OPTION
You can specify more than one flag at the end of --regex-<LANG> to control how Universal-ctags uses the pattern.

Exuberant-ctags uses a letter to represent a flag. In Universal-ctags, a name surrounded by braces (name form) can be used in addition to letter. The name form makes a user reading an optlib file easier. The most of all flags newly added in Universal-ctags don't have the one-letter representation. All of them have only the name representation. --list-regex-flags lists all the flags.

basic (one-letter form b)

The pattern is interpreted as a Posix basic regular expression.

exclusive (one-letter form x)

Skip testing the other patterns if a line is matched to this pattern. This is useful to avoid using CPU to parse line comments.

extend (one-letter form e)

The pattern is interpreted as a Posix extended regular expression (default).

icase (one-letter form i)

The regular expression is to be applied in a case-insensitive manner.

placeholder

Don't emit a tag captured with a regex pattern. The replacement can be an empty string. See the following description of scope=... flag about how this is useful.

scope=ref|push|pop|clear|set

Specify what to do with the internal scope stack. A parser programmed with --regex-<LANG> has a stack (scope stack) internally. You can use it for tracking scope information. The scope=... flag is for manipulating and utilizing the scope stack.

If {scope=push} is specified, a tag captured with --regex-<LANG> is pushed to the stack. {scope=push} implies {scope=ref}.

You can fill the scope field of captured tag with {scope=ref}. If {scope=ref} flag is given, ctags attaches the tag at the top to the tag captured with --regex-<LANG> as the value for the scope: field.

ctags pops the tag at the top of the stack when --regex-<LANG> with {scope=pop} is matched to the input line.

Specifying {scope=clear} removes all the tags in the scope. Specifying {scope=set} removes all the tags in the scope, and then pushes the captured tag as {scope=push} does.

In some cases, you may want to use --regex-<LANG> only for its side effects: using it only to manipulate the stack but not for capturing a tag. In such a case, make replacement component of --regex-<LANG> option empty while specifying {placeholder} as a regex flag. For example, a non-named tag can be put on the stack by giving a regex flag {scope=push}{placeholder}.

You may wonder what happens if a regex pattern with {scope=ref} flag matches an input line but the stack is empty, or a non-named tag is at the top. If the regex pattern contains a {scope=ref} flag and the stack is empty, the {scope=ref} flag is ignored and nothing is attached to the scope: field.

If the top of the stack contains an unnamed tag, ctags searches deeper into the stack to find the top-most named tag. If it reaches the bottom of the stack without finding a named tag, the {scope=ref} flag is ignored and nothing is attached to the scope: field.

When a named tag on the stack is popped or cleared as the side effect of a pattern matching, ctags attaches the line number of the match to the end: field of the named tag.

ctags clears all of the tags on the stack when it reaches the end of the input source file. The line number of the end is attached to the end: field of the cleared tags.

## MORE EXAMPLES
Four things, an input source file, an optlib file, a command line invoking ctags, and output makes an example.

### Using scope regex flags
Let's think about writing a parser for a very small subset of the Ruby language.

input source file ("input.srb"):

```
class Example

  def methodA

        puts "in class_method"

  end

  def methodB

        puts "in class_method"

  end
end
```

The parser for the input should capture "Example" with class kind, "methodA", and "methodB" with method kind. "methodA" and "methodB" should have "Example" as their scope. end: fields of each tag should have proper values.

optlib file ("sub-ruby.ctags"):

```
--langdef=subRuby
--map-subRuby=.srb
--kinddef-subRuby=c,class,classes
--kinddef-subRuby=m,method,methods
--regex-subRuby=/^class[ \t]+([a-zA-Z][a-zA-Z0-9]+)/\1/c/{scope=push}
--regex-subRuby=/^end///{scope=pop}{placeholder}
--regex-subRuby=/^[ \t]+def[ \t]+([a-zA-Z][a-zA-Z0-9_]+)/\1/m/{scope=push}
--regex-subRuby=/^[ \t]+end///{scope=pop}{placeholder}
```

command line and output:

```
$ ctags  --quiet --options=NONE --fields=+eK \
--options=./sub-ruby.ctags -o - input.srb
Example input.srb       /^class Example$/;"     class   end:8
methodA input.srb       /^  def methodA$/;"     method  class:Example   end:4
methodB input.srb       /^  def methodB$/;"     method  class:Example   end:7
```

## SEE ALSO
The official Universal-ctags web site at:

https://ctags.io/

ctags(1), tags(5), regex(5,7), egrep(1)

## AUTHOR
Universal-ctags project https://ctags.io/ (This man page partially derived from ctags(1) of Executable-ctags)

Darren Hiebert <dhiebert@users.sourceforge.net> http://DarrenHiebert.com/


unixODBC

package: unixODBC

title: unixODBC(7)

summary: An ODBC implementation for Unix

text:
# unixODBC(7)

## NAME
unixODBC - An ODBC implementation for Unix

## DESCRIPTION
ODBC is an open specification for providing application developers with a predictable API with which to access Data Sources. Data Sources include SQL Servers and any Data Source with an ODBC Driver.

The unixODBC Project goals are to develop and promote unixODBC to be the definitive standard for ODBC on non MS Windows platforms.

## ENVIRONMENT VARIABLES
ODBCSYSINI

Overloads path to unixODBC configuration files. By default equals to '/etc'.

ODBCINSTINI

Overloads the name of the drivers configuration file. It is relative to ODBCSYSINI and by default set to 'odbcinst.ini'.

ODBCINSTUI

Overloads the library name for UI. The final name that is searched for is evaluated as "lib$ODBCINSTUI". By default it is set to 'odbcinstQ4', so the resulting library name is 'libodbcinstQ4'.

ODBCSEARCH

Overloads the configuration mode and determines where to look for configuration files. Must be set to one of ODBC_SYSTEM_DSN, ODBC_USER_DSN or ODBC_BOTH_DSN (the last one is the default value).

ODBCINI

Overloads the path to user configuration file. By default it is set to "~/.odbc.ini".

## SEE ALSO
isql(1), odbcinst(1), odbc.ini(5), odbcinst.ini(5)

## AUTHORS
The authors of unixODBC are Peter Harvey <pharvey@codebydesign.com> and Nick Gorham <nick@unixodbc.org>. For the full list of contributors see the AUTHORS file.

## COPYRIGHT
unixODBC is licensed under the GNU Lesser General Public License. For details about the license, see the COPYING file.


UPower

package: upower

title: UPower(7)

summary: System\-wide Power Management

text:
# UPower(7)

## NAME
UPower - System-wide Power Management

## DESCRIPTION
UPower provides an interface to enumerate power sources on the system and control system-wide power management. Any application can access the org.freedesktop.UPower service on the system message bus.

## AUTHOR
Written by David Zeuthen <davidz@redhat.com>, Richard Hughes <richard@hughsie.com> and with a lot of help from many others.

## BUGS
Please send bug reports to either the distribution or the DeviceKit mailing list, see http://lists.freedesktop.org/mailman/listinfo/devkit-devel on how to subscribe.

## SEE ALSO
PolicyKit(8), upowerd(8), upower(1)


weston-bindings

package: weston

title: weston-bindings(7)

summary: a list of keyboard bindings for

text:
# weston-bindings(7)

## NAME
weston-bindings - a list of keyboard bindings for Weston - the reference Wayland compositor

## INTRODUCTION
The Weston desktop shell has a number of keyboard shortcuts. They are listed here.

## DESCRIPTION
Almost all keyboard shortcuts for Weston include a specified modifier mod which is determined in the file weston.ini(5).

mod + Shift + F

Make active window fullscreen

mod + K

Kill active window

mod + Shift + M

Maximize active window

mod + PageUp, mod + PageDown

Zoom desktop in (or out)

mod + Tab

Switch active window

mod + Up, mod + Down

Increment/decrement active workspace number, if there are multiple

mod + Shift + Up, mod + Shift + Down

Move active window to the succeeding/preceding workspace, if possible

mod + F1/F2/F3/F4/F5/F6

Jump to the numbered workspace, if it exists

Ctrl + Alt + Backspace

If supported, terminate Weston. (Note this combination often is used to hard restart Xorg.)

Ctrl + Alt + F

Toggle if Weston is fullscreen; only works when nested under a Wayland compositor

Ctrl + Alt + S

Share output screen, if possible

Ctrl + Alt + F1/F2/F3/F4/F5/F6/F7/F8

Switch virtual terminal, if possible

Super + S

Make a screenshot of the desktop

Super + R

Start or stop recording video of the desktop

### TOUCH / MOUSE BINDINGS
There are also a number of bindings involving a mouse:

<Touch>, <Left button>, <Right button>

Activate clicked window

Super + Alt + <Vertical Scroll>

Change the opacity of a window

mod + <Vertical Scroll>

Zoom/magnify the visible desktop

mod + <Left button>

Click and drag to move a window

mod + Shift + <Left button>, mod + <Right button>, mod + <Touch>

Click and drag to resize a window

mod + <Middle button>

Rotate the window (if supported)

### DEBUG BINDINGS
The combination mod + Shift + Space begins a debug binding. Debug bindings are completed by pressing an additional key. For example, pressing F may toggle texture mesh wireframes with the GL renderer. (In fact, most debug effects can be disabled again by repeating the command.) Debug bindings are often tied to specific backends.

## SEE ALSO
weston(1), weston-launch(1), weston-drm(7), weston.ini(5), xkeyboard-config(7)


weston-drm

title: weston-drm(7)

summary: the DRM backend for Weston

text:
# weston-drm(7)

## NAME
weston-drm - the DRM backend for Weston

## SYNOPSIS
weston-launch

weston --backend=drm-backend.so

## DESCRIPTION
The DRM backend is the native Weston backend for systems that support the Linux kernel DRM, kernel mode setting (KMS), and evdev input devices. It is the recommended backend for desktop PCs, and aims to provide the full Wayland experience with the "every frame is perfect" concept. It also relies on the Mesa GBM interface.

With the DRM backend, weston runs without any underlying windowing system. The backend uses the Linux KMS API to detect connected monitors. Monitor hot-plugging is supported. Input devices are found automatically by udev(7). Compositing happens mainly in GL ES 2, initialized through EGL. It is also possible to take advantage of hardware cursors and overlays, when they exist and are functional. Full-screen surfaces will be scanned out directly without compositing, when possible. Hardware accelerated clients are supported via EGL.

The backend chooses the DRM graphics device first based on seat id. If seat identifiers are not set, it looks for the graphics device that was used in boot. If that is not found, it finally chooses the first DRM device returned by udev(7). Combining multiple graphics devices is not supported yet.

The DRM backend relies on weston-launch for managing input device access and DRM master status, so that weston can be run without root privileges. On switching away from the virtual terminal (VT) hosting Weston, all input devices are closed and the DRM master capability is dropped, so that other servers, including Xorg(1), can run on other VTs. On switching back to Weston's VT, input devices and DRM master are re-acquired through the parent process weston-launch.

The DRM backend also supports virtual outputs that are transmitted over an RTP session as a series of JPEG images (RTP payload type 26) to a remote client. Virtual outputs are configured in the remote-output section of weston.ini.

## CONFIGURATION
The DRM backend uses the following entries from weston.ini.

### Section output
name=connector

The KMS connector name identifying the output, for instance LVDS1.

mode=mode

Specify the video mode for the output. The argument mode can be one of the words off to turn the output off, preferred to use the monitor's preferred video mode, or current to use the current video mode and avoid a mode switch. It can also be a resolution as:

mode=widthxheight

mode=widthxheight@refresh_rate

Specify a mode with a given refresh-rate measured in Hz.

mode=widthxheight@refresh_rate ratio

Here ratio is Picture Aspect-Ratio which can have values as 4:3, 16:9, 64:27, and 256:135. This resolution-format helps to select a CEA mode, if such a video mode is present in the mode-list of the output. CEA defines the timing of a video mode, which is considered as a standard for HDMI spcification and compliance testing. It defines each and every parameter of a video mode, like hactive, vactive, vfront, vback etc., including aspect-ratio information. For CEA modes, the drm layer, stores this aspect-ratio information in user-mode (drmModeModeInfo) flag bits 19-22. For the non-CEA modes a value of 0 is stored in the aspect-ratio flag bits.

Each CEA-mode is identified by a unique, Video Identification Code (VIC). For example, VIC=4 is 1280x720@60 aspect-ratio 16:9. This mode will be different than a non-CEA mode 1280x720@60 0:0. When the video mode 1280x720@60 0:0 is applied, since its timing doesn't exactly match with the CEA information for VIC=4, it would be treated as a non-CEA mode. Also, while setting the HDMI-AVI-Inforframe, VIC parameter will be given as '0'. If video mode 1280x720@60 16:9 is applied, its CEA timimgs matches with that of video mode with VIC=4, so the VIC parameter in HDMI-AVI-Infoframe will be set to 4.

Many a times, an output may have both CEA and non-CEA modes, which are similar in all resepct, differing only in the aspect-ratio. A user can select a CEA mode by giving the aspect-ratio, along with the other arguments for the mode. By omitting the aspect-ratio, user can specify the non-CEA modes. This helps when certification testing is done, in tests like 7-27, the HDMI-analyzer applies a particular CEA mode, and expects the applied mode to be with exactly same timings, including the aspect-ratio and VIC field.

The resolution can also be a detailed mode line as below.

mode=dotclock hdisp hsyncstart hsyncend htotal vdisp vsyncstart vsyncend vtotal hflag vflag

Use the given detailed mode line as the video mode for this output. The definition is the same as in xorg.conf(5), and cvt(1) can generate detailed mode lines.

transform=transform

Transform for the output, which can be rotated in 90-degree steps and possibly flipped. Possible values are normal, rotate-90, rotate-180, rotate-270, flipped, flipped-rotate-90, flipped-rotate-180, and flipped-rotate-270.

pixman-shadow=boolean

If using the Pixman-renderer, use shadow framebuffers. Defaults to true.

same-as=name

Make this output (connector) a clone of another. The argument name is the name value of another output section. The referred to output section must exist. When this key is present in an output section, all other keys have no effect on the configuration. NOTE: cms-colord plugin does not work correctly with this option. The plugin chooses an arbitrary monitor to load the color profile for, but the profile is applied equally to all cloned monitors regardless of their properties.

force-on=true

Force the output to be enabled even if the connector is disconnected. Defaults to false. Note that mode=off will override force-on=true. When a connector is disconnected, there is no EDID information to provide a list of video modes. Therefore a forced output should also have a detailed mode line specified.

### Section remote-output
name=name

Specify unique name for the output.

mode=mode

Specify the video mode for the output. The argument mode is a resolution setting, such as:

mode=widthxheight

mode=widthxheight@refresh_rate

If refresh_rate is not specified it will default to a 60Hz.

host=host

Specify the host name or IP Address that the remote output will be transmitted to.

port=port

Specify the port number to transmit the remote output to. Usable port range is 1-65533.

gst-pipeline=pipeline

Specify the gstreamer pipeline. It is necessary that source is appsrc, its name is "src", and sink name is "sink" in pipeline. Ignore port and host configuration if the gst-pipeline is specified.

## OPTIONS
When the DRM backend is loaded, weston will understand the following additional command line options.

--current-mode

By default, use the current video mode of all outputs, instead of switching to the monitor preferred mode.

--drm-device=cardN

Use the DRM device cardN instead of the default heuristics based on seat assignments and boot VGA status. For example, use card0.

--seat=seatid

Use graphics and input devices designated for seat seatid instead of the seat defined in the environment variable XDG_SEAT. If neither is specified, seat0 will be assumed.

--tty=x

Launch Weston on tty x instead of using the current tty.

--continue-without-input

Allow Weston to start without input devices. Used for testing purposes.

## ENVIRONMENT
WESTON_LIBINPUT_LOG_PRIORITY

The minimum libinput verbosity level to be printed to Weston's log. Valid values are debug, info, and error. Default is info.

WESTON_TTY_FD

The file descriptor (integer) of the opened tty where weston will run. Set by weston-launch.

WESTON_LAUNCHER_SOCK

The file descriptor (integer) where weston-launch is listening. Automatically set by weston-launch.

XDG_SEAT

The seat Weston will start on, unless overridden on the command line.

## SEE ALSO
weston(1)


weston-rdp

title: weston-rdp(7)

summary: the RDP backend for Weston

text:
# weston-rdp(7)

## NAME
weston-rdp - the RDP backend for Weston

## SYNOPSIS
weston --backend=rdp-backend.so

## DESCRIPTION
The RDP backend allows to run a weston environment without the need of specific graphic hardware, or input devices. Users can interact with weston only by connecting using the RDP protocol.

The RDP backend uses FreeRDP to implement the RDP part, it acts as a RDP server listening for incoming connections. It supports different codecs for encoding the graphical content. Depending on what is supported by the RDP client, the backend will encode images using remoteFx codec, NS codec or will fallback to raw bitmapUpdate.

On the security part, the backend supports RDP security or TLS, keys and certificates must be provided to the backend depending on which kind of security is requested. The RDP backend will announce security options based on which files have been given.

The RDP backend is multi-seat aware, so if two clients connect on the backend, they will get their own seat.

## OPTIONS
When the RDP backend is loaded, weston will understand the following additional command line options.

--address=address

The IP address on which the RDP backend will listen for RDP connections. By default it listens on 0.0.0.0.

--port=port

The TCP port to listen on for connections, it defaults to 3389.

--no-clients-resize

By default when a client connects on the RDP backend, it will instruct weston to resize to the dimensions of the client's announced resolution. When this option is set, weston will force the client to resize to its own resolution.

--rdp4-key=file

The file containing the RSA key for doing RDP security. As RDP security is known to be insecure, this option should be avoided in production.

--rdp-tls-key=file

The file containing the key for doing TLS security. To have TLS security you also need to ship a file containing a certificate.

--rdp-tls-cert=file

The file containing the certificate for doing TLS security. To have TLS security you also need to ship a key file.

## Generating cryptographic material for the RDP backend
To generate a key file to use for RDP security, you need the winpr-makecert utility shipped with FreeRDP:

```
$ winpr-makecert -rdp -silent -n rdp-security
```

This will create a rdp-security.key file.

You can generate a key and certificate file to use with TLS security using a typical openssl invocations:

```
$ openssl genrsa -out tls.key 2048
Generating RSA private key, 2048 bit long modulus
[...]
$ openssl req -new -key tls.key -out tls.csr
[...]
$ openssl x509 -req -days 365 -signkey tls.key -in tls.csr -out tls.crt
[...]
```

You will get the tls.key and tls.crt files to use with the RDP backend.

## SEE ALSO
weston(1)


wireless

package: wireless-tools

title: wireless(7)

summary: Wireless Tools and Wireless Extensions

text:
# wireless(7)

## NAME
wireless - Wireless Tools and Wireless Extensions

## SYNOPSIS
iwconfig

iwpriv -a

## DESCRIPTION
The Wireless Extensions is an API allowing you manipulate Wireless LAN networking interfaces. It is composed of a variety of tools and configuration files. It is documented in more detail in the Linux Wireless LAN Howto.

The Wireless Tools are used to change the configuration of wireless LAN networking interfaces on the fly, to get their current configuration, to get statistics and diagnose them. They are described in their own man page, see below for references.

Wireless configuration is specific to each Linux distribution. This man page will contain in the future the configuration procedure for a few common distributions. For the time being, check the file DISTRIBUTIONS.txt included with the Wireless Tools package.

## DEBIAN 3.0
In Debian 3.0 (and later) you can configure wireless LAN networking devices using the network configuration tool ifupdown(8).

File :

/etc/network/interfaces

Form :

wireless-<function> <value>

wireless-essid Home

wireless-mode Ad-Hoc

See also :

/etc/network/if-pre-up.d/wireless-tools

/usr/share/doc/wireless-tools/README.Debian

## SuSE 8.0
SuSE 8.0 (and later) has integrated wireless configuration in their network scripts.

Tool :

Yast2

File :

/etc/sysconfig/network/wireless

/etc/sysconfig/network/ifcfg-*

Form :

WIRELESS_<function>=<value>

WIRELESS_ESSID="Home"

WIRELESS_MODE=Ad-Hoc

See also :

man ifup

info scpm

## ORIGINAL PCMCIA SCRIPTS
If you are using the original configuration scripts from the Pcmcia package, you can use this method.

File :

/etc/pcmcia/wireless.opts

Form :

*,*,*,*)

ESSID="Home"

MODE="Ad-Hoc"

;;

See also :

/etc/pcmcia/wireless

File PCMCIA.txt part of Wireless Tools package

## AUTHOR
Jean Tourrilhes - jt@hpl.hp.com

http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/

## SEE ALSO
iwconfig(8), iwlist(8), iwspy(8), iwpriv(8), iwevent(8).


morphy

package: wordnet-dict

title: morphy(7)

text:
# morphy(7)

## NAME
morphy - discussion of WordNet's morphological processing

## DESCRIPTION
Although only base forms of words are usually stored in WordNet, searches may be done on inflected forms. A set of morphology functions, Morphy, is applied to the search string to generate a form that is present in WordNet.

Morphology in WordNet uses two types of processes to try to convert the string passed into one that can be found in the WordNet database. There are lists of inflectional endings, based on syntactic category, that can be detached from individual words in an attempt to find a form of the word that is in WordNet. There are also exception list files, one for each syntactic category, in which a search for an inflected form is done. Morphy tries to use these two processes in an intelligent manner to translate the string passed to the base form found in WordNet. Morphy first checks for exceptions, then uses the rules of detachment. The Morphy functions are not independent from WordNet. After each transformation, WordNet is searched for the resulting string in the syntactic category specified.

The Morphy functions are passed a string and a syntactic category. A string is either a single word or a collocation. Since some words, such as axes can have more than one base form (axe and axis), Morphy works in the following manner. The first time that Morphy is called with a specific string, it returns a base form. For each subsequent call to Morphy made with a NULL string argument, Morphy returns another base form. Whenever Morphy cannot perform a transformation, whether on the first call for a word or subsequent calls, NULL is returned. A transformation to a valid English string will return NULL if the base form of the string is not in WordNet.

The morphological functions are found in the WordNet library. See morph(3) for information on using these functions.

### Rules of Detachment
The following table shows the rules of detachment used by Morphy. If a word ends with one of the suffixes, it is stripped from the word and the corresponding ending is added. Then WordNet is searched for the resulting string. No rules are applicable to adverbs.

POS

Suffix

Ending

NOUN

"s"

""

NOUN

"ses"

"s"

NOUN

"xes"

"x"

NOUN

"zes"

"z"

NOUN

"ches"

"ch"

NOUN

"shes"

"sh"

NOUN

"men"

"man"

NOUN

"ies"

"y"

VERB

"s"

""

VERB

"ies"

"y"

VERB

"es"

"e"

VERB

"es"

""

VERB

"ed"

"e"

VERB

"ed"

""

VERB

"ing"

"e"

VERB

"ing"

""

ADJ

"er"

""

ADJ

"est"

""

ADJ

"er"

"e"

ADJ

"est"

"e"

### Exception Lists
There is one exception list file for each syntactic category. The exception lists contain the morphological transformations for strings that are not regular and therefore cannot be processed in an algorithmic manner. Each line of an exception list contains an inflected form of a word or collocation, followed by one or more base forms. The list is kept in alphabetical order and a binary search is used to find words in these lists. See wndb(5) for information on the format of the exception list files.

### Single Words
In general, single words are relatively easy to process. Morphy first looks for the word in the exception list. If it is found the first base form is returned. Subsequent calls with a NULL argument return additional base forms, if present. A NULL is returned when there are no more base forms of the word.

If the word is not found in the exception list corresponding to the syntactic category, an algorithmic process using the rules of detachment looks for a matching suffix. If a matching suffix is found, a corresponding ending is applied (sometimes this ending is a NULL string, so in effect the suffix is removed from the word), and WordNet is consulted to see if the resulting word is found in the desired part of speech.

### Collocations
As opposed to single words, collocations can be quite difficult to transform into a base form that is present in WordNet. In general, only base forms of words, even those comprising collocations, are stored in WordNet, such as attorney general. Transforming the collocation attorneys general is then simply a matter of finding the base forms of the individual words comprising the collocation. This usually works for nouns, therefore non-conforming nouns, such as customs duty are presently entered in the noun exception list.

Verb collocations that contain prepositions, such as ask for it, are more difficult. As with single words, the exception list is searched first. If the collocation is not found, special code in Morphy determines whether a verb collocation includes a preposition. If it does, a function is called to try to find the base form in the following manner. It is assumed that the first word in the collocation is a verb and that the last word is a noun. The algorithm then builds a search string with the base forms of the verb and noun, leaving the remainder of the collocation (usually just the preposition, but more words may be involved) in the middle. For example, passed asking for it, the database search would be performed with ask for it, which is found in WordNet, and therefore returned from Morphy. If a verb collocation does not contain a preposition, then the base form of each word in the collocation is found and WordNet is searched for the resulting string.

### Hyphenation
Hyphenation also presents special difficulties when searching WordNet. It is often a subjective decision as to whether a word is hyphenated, joined as one word, or is a collocation of several words, and which of the various forms are entered into WordNet. When Morphy breaks a string into "words", it looks for both spaces and hyphens as delimiters. It also looks for periods in strings and removes them if an exact match is not found. A search for an abbreviation like oct. return the synset for { October, Oct }. Not every pattern of hyphenated and collocated string is searched for properly, so it may be advantageous to specify several search strings if the results of a search attempt seem incomplete.

### Special Processing for nouns ending with 'ful'
Morphy contains code that searches for nouns ending with ful and performs a transformation on the substring preceeding it. It then appends 'ful' back onto the resulting string and returns it. For example, if passed the nouns boxesful, it will return boxful.

## BUGS
Since many noun collocations contains prepositions, such as line of products, an algorithm similar to that used for verbs should be written for nouns. In the present scheme, if Morphy is passed lines of products, the search string becomes line of product, which is not in WordNet

Morphy will allow non-words to be converted to words, if they follow one of the rules described above. For example, it will happily convert plantes to plants.

## ENVIRONMENT VARIABLES (UNIX)
WNHOME

Base directory for WordNet. Default is /usr/local/WordNet-3.0.

WNSEARCHDIR

Directory in which the WordNet database has been installed. Default is WNHOME/dict.

## REGISTRY (WINDOWS)
HKEY_LOCAL_MACHINE\SOFTWARE\WordNet\3.0\WNHome

Base directory for WordNet. Default is C:\Program Files\WordNet\3.0.

## FILES
pos.exc

morphology exception lists

## SEE ALSO
wn(1), wnb(1), binsrch(3), morph(3), wndb(5), wninput(7).


uniqbeg

title: uniqbeg(7)

summary: unique beginners for noun hierarchies

text:
# uniqbeg(7)

## NAME
uniqbeg - unique beginners for noun hierarchies

## DESCRIPTION
All of the WordNet noun synsets are organized into hierarchies, headed by the unique beginner synset for entity in the file noun.Tops.

```
{ entity (that which is perceived or known or inferred to have its own
distinct existence (living or nonliving)) }
```

## NOTES
The lexicographer files are not included in the WordNet database package.

## FILES
noun.Tops

unique beginners for nouns

## SEE ALSO
wndb(5), wninput(5), wnintro(7), wngloss(7).


wngloss

title: wngloss(7)

text:
# wngloss(7)

## NAME
wngloss - glossary of terms used in WordNet system

## DESCRIPTION
The WordNet Reference Manual consists of Unix-style manual pages divided into sections as follows:

Section

Description

1

WordNet User Commands

3

WordNet Library Functions

5

WordNet File Formats

7

Miscellaneous Information about WordNet

### System Description
The WordNet system consists of lexicographer files, code to convert these files into a database, and search routines and interfaces that display information from the database. The lexicographer files organize nouns, verbs, adjectives and adverbs into groups of synonyms, and describe relations between synonym groups. grind(1) converts the lexicographer files into a database that encodes the relations between the synonym groups. The different interfaces to the WordNet database utilize a common library of search routines to display these relations. Note that the lexicographer files and grind(1) program are not generally distributed.

### Database Organization
Information in WordNet is organized around logical groupings called synsets. Each synset consists of a list of synonymous words or collocations (eg. "fountain pen", "take in"), and pointers that describe the relations between this synset and other synsets. A word or collocation may appear in more than one synset, and in more than one part of speech. The words in a synset are grouped such that they are interchangeable in some context.

Two kinds of relations are represented by pointers: lexical and semantic. Lexical relations hold between semantically related word forms; semantic relations hold between word meanings. These relations include (but are not limited to) hypernymy/hyponymy (superordinate/subordinate), antonymy, entailment, and meronymy/holonymy.

Nouns and verbs are organized into hierarchies based on the hypernymy/hyponymy relation between synsets. Additional pointers are be used to indicate other relations.

Adjectives are arranged in clusters containing head synsets and satellite synsets. Each cluster is organized around antonymous pairs (and occasionally antonymous triplets). The antonymous pairs (or triplets) are indicated in the head synsets of a cluster. Most head synsets have one or more satellite synsets, each of which represents a concept that is similar in meaning to the concept represented by the head synset. One way to think of the adjective cluster organization is to visualize a wheel, with a head synset as the hub and satellite synsets as the spokes. Two or more wheels are logically connected via antonymy, which can be thought of as an axle between the wheels.

Pertainyms are relational adjectives and do not follow the structure just described. Pertainyms do not have antonyms; the synset for a pertainym most often contains only one word or collocation and a lexical pointer to the noun that the adjective is "pertaining to". Participial adjectives have lexical pointers to the verbs that they are derived from.

Adverbs are often derived from adjectives, and sometimes have antonyms; therefore the synset for an adverb usually contains a lexical pointer to the adjective from which it is derived.

See wndb(5) for a detailed description of the database files and how the data are represented.

## GLOSSARY OF TERMS
Many terms used in the WordNet Reference Manual are unique to the WordNet system. Other general terms have specific meanings when used in the WordNet documentation. Definitions for many of these terms are given to help with the interpretation and understanding of the reference manual, and in the use of the WordNet system.

In following definitions word is used in place of word or collocation.

adjective cluster

A group of adjective synsets that are organized around antonymous pairs or triplets. An adjective cluster contains two or more head synsets which represent antonymous concepts. Each head synset has one or more satellite synsets.

attribute

A noun for which adjectives express values. The noun weight is an attribute, for which the adjectives light and heavy express values.

base form

The base form of a word or collocation is the form to which inflections are added.

basic synset

Syntactically, same as synset. Term is used in wninput(5) to help explain differences in entering synsets in lexicographer files.

collocation

A collocation in WordNet is a string of two or more words, connected by spaces or hyphens. Examples are: man-eating shark, blue-collar, depend on, line of products. In the database files spaces are represented as underscore (_) characters.

coordinate

Coordinate terms are nouns or verbs that have the same hypernym.

cross-cluster pointer

A semantic pointer from one adjective cluster to another.

derivationally related forms

Terms in different syntactic categories that have the same root form and are semantically related.

direct antonyms

A pair of words between which there is an associative bond resulting from their frequent co-occurrence. In adjective clusters, direct antonyms appears only in head synsets.

domain

A topical classification to which a synset has been linked with a CATEGORY, REGION or USAGE pointer.

domain term

A synset belonging to a topical class. A domain term is further identified as being a CATEGORY_TERM, REGION_TERM or USAGE_TERM.

entailment

A verb X entails Y if X cannot be done unless Y is, or has been, done.

exception list

Morphological transformations for words that are not regular and therefore cannot be processed in an algorithmic manner.

group

Verb senses that similar in meaning and have been manually grouped together.

gloss

Each synset contains gloss consisting of a definition and optionally example sentences.

head synset

Synset in an adjective cluster containing at least one word that has a direct antonym.

holonym

The name of the whole of which the meronym names a part. Y is a holonym of X if X is a part of Y.

hypernym

The generic term used to designate a whole class of specific instances. Y is a hypernym of X if X is a (kind of) Y.

hyponym

The specific term used to designate a member of a class. X is a hyponym of Y if X is a (kind of) Y.

indirect antonym

An adjective in a satellite synset that does not have a direct antonym has an indirect antonyms via the direct antonym of the head synset.

instance

A proper noun that refers to a particular, unique referent (as distinguished from nouns that refer to classes). This is a specific form of hyponym.

lemma

Lower case ASCII text of word as found in the WordNet database index files. Usually the base form for a word or collocation.

lexical pointer

A lexical pointer indicates a relation between words in synsets (word forms).

lexicographer file

Files containing the raw data for WordNet synsets, edited by lexicographers, that are input to the grind program to generate a WordNet database.

lexicographer id (lex id)

A decimal integer that, when appended onto lemma, uniquely identifies a sense within a lexicographer file.

monosemous

Having only one sense in a syntactic category.

meronym

The name of a constituent part of, the substance of, or a member of something. X is a meronym of Y if X is a part of Y.

part of speech

WordNet defines "part of speech" as either noun, verb, adjective, or adverb. Same as syntactic category.

participial adjective

An adjective that is derived from a verb.

pertainym

A relational adjective. Adjectives that are pertainyms are usually defined by such phrases as "of or pertaining to" and do not have antonyms. A pertainym can point to a noun or another pertainym.

polysemous

Having more than one sense in a syntactic category.

polysemy count

Number of senses of a word in a syntactic category, in WordNet.

postnominal

A postnominal adjective occurs only immediately following the noun that it modifies.

predicative

An adjective that can be used only in predicate positions. If X is a predicate adjective, it can only be used in such phrases as "it is X" and never prenominally.

prenominal

An adjective that can occur only before the noun that it modifies: it cannot be used predicatively.

satellite synset

Synset in an adjective cluster representing a concept that is similar in meaning to the concept represented by its head synset.

semantic concordance

A textual corpus (e.g. the Brown Corpus) and a lexicon (e.g. WordNet) so combined that every substantive word in the text is linked to its appropriate sense in the lexicon via a semantic tag.

semantic tag

A pointer from a word in a text file to a specific sense of that word in the WordNet database. A semantic tag in a semantic concordance is represented by a sense key.

semantic pointer

A semantic pointer indicates a relation between synsets (concepts).

sense

A meaning of a word in WordNet. Each sense of a word is in a different synset.

sense key

Information necessary to find a sense in the WordNet database. A sense key combines a lemma field and codes for the synset type, lexicographer id, lexicographer file number, and information about a satellite's head synset, if required. See senseidx(5) for a description of the format of a sense key.

subordinate

Same as hyponym.

superordinate

Same as hypernym.

synset

A synonym set; a set of words that are interchangeable in some context without changing the truth value of the preposition in which they are embedded.

troponym

A verb expressing a specific manner elaboration of another verb. X is a troponym of Y if to X is to Y in some manner.

unique beginner

A noun synset with no superordinate.


wngroups

title: wngroups(7)

text:
# wngroups(7)

## NAME
wngroups - discussion of WordNet search code to group similar verb senses

## DESCRIPTION
Some similar senses of verbs have been grouped by the lexicographers. This grouping is done statically in the lexicographer source files using the semantic pointer_symbol $. Transitivity is used to combine groups of overlapping senses into the largest sense groups possible.

## NOTES
Coverage of verb groups is incomplete.

## ENVIRONMENT VARIABLES (UNIX)
WNHOME

Base directory for WordNet. Default is /usr/local/WordNet-3.0.

WNSEARCHDIR

Directory in which the WordNet database has been installed. Default is WNHOME/dict.

## REGISTRY (WINDOWS)
HKEY_LOCAL_MACHINE\SOFTWARE\WordNet\3.0\WNHome

Base directory for WordNet. Default is C:\Program Files\WordNet\3.0.

## FILES
sentidx.vrb

verb sense keys and sentence frame numbers

sents.vrb

example sentence frames

## SEE ALSO
wn(1), wnb(1), senseidx(5), wnsearch(3), wndb(5), wnintro(7).


wnintro

title: wnintro(7)

text:
# wnintro(7)

## NAME
wnintro - introduction to miscellaneous WordNet information

## SYNOPSIS
morphy - discussion of WordNet's morphological processing

uniqbeg - unique beginners for noun hierarchies

wngloss - glossary of terms used in WordNet

wngroups - discussion of WordNet search code to group similar senses

wnlicens - text of WordNet license agreement

wnpkgs - information about WordNet packages and distribution

wnstats - database statistics

## DESCRIPTION
This section of the WordNet Reference Manual contains manual pages that describe various topics related to WordNet and the semantic concordances, and a glossary of terms.

## SEE ALSO
wnintro(1), wnintro(3), wnintro(5), morphy(7), uniqbeg(7), wngroups(7), wnlicens(7), wnpkgs(7), wnstats(7), wngloss(7).

Fellbaum, C. (1998), ed. "WordNet: An Electronic Lexical Database". MIT Press, Cambridge, MA.


wnlicens

title: wnlicens(7)

summary: text of WordNet license

text:
# wnlicens(7)

## NAME
wnlicens - text of WordNet license

## DESCRIPTION
WordNet Release 3.0

This software and database is being provided to you, the LICENSEE, by Princeton University under the following license. By obtaining, using and/or copying this software and database, you agree that you have read, understood, and will comply with these terms and conditions.:

Permission to use, copy, modify and distribute this software and database and its documentation for any purpose and without fee or royalty is hereby granted, provided that you agree to comply with the following copyright notice and statements, including the disclaimer, and that the same appear on ALL copies of the software, database and documentation, including modifications that you make for internal use or for distribution.

WordNet 3.0 Copyright 2006 by Princeton University. All rights reserved.

THIS SOFTWARE AND DATABASE IS PROVIDED "AS IS" AND PRINCETON UNIVERSITY MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PRINCETON UNIVERSITY MAKES NO REPRESENTATIONS OR WARRANTIES OF MERCHANT- ABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE LICENSED SOFTWARE, DATABASE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

The name of Princeton University or Princeton may not be used in advertising or publicity pertaining to distribution of the software and/or database. Title to copyright in this software, database and any associated documentation shall at all times remain with Princeton University and LICENSEE agrees to preserve same.


wnpkgs

title: wnpkgs(7)

text:
# wnpkgs(7)

## NAME
wnpkgs - description of various WordNet system packages

## DESCRIPTION
WordNet 3.0 is distributed in several formats and in various packages. All of the packages are available via anonymous FTP from ftp.cogsci.princeton.edu and from the WordNet Web site at http://wordnet.princeton.edu.

### Packages Available Via FTP and WWW
The following WordNet packages can be downloaded using a web browser from ftp://ftp.cogsci.princeton.edu/wordnet/3.0, or from the Web site noted above. Users can also FTP directly from ftp.cogsci.princeton.edu, directory wordnet/3.0.

Package

Filename

Platform

Description

Database

WordNet-3.0.tar.gz

Unix/OS X

WordNet 3.0 database, interfaces, sense index, interface and library source code, documentation.

Database

WordNet-3.0.exe

Windows

WordNet 3.0 database, interfaces, sense index, interface and library source code, documentation.

Prolog Database

WNprolog-3.0.tar.gz

All

WordNet 3.0 database files in Prolog-readable format, documentation.

Sense Map

WNsnsmap-3.0.tar.gz

All

Mapping of 2.1 to 3.0 senses, documentation.

### Database Package
The database package is a complete installation for WordNet 3.0 users. It includes the 3.0 database files, source code for the WordNet browsers and library, and documentation. The other packages are not included - they must be downloaded and installed separately.

Note that with this version of WordNet for Unix platforms, only source code is provided. Users should carefully read the README and INSTALL files for detailed information on compiling WordNet and dependencies.

### Prolog Database Package
The WordNet 3.0 database files are available in this package in a Prolog-readable format. Documentation describing the file format is included. This package is only downloadable in compressed tar file format, although once unpackaged it can be used from Windows systems since the files are in ASCII. Many Windows utilities, such as WinZip, can deal with a compressed tar file.

### Sense Map Package
To help users automatically convert 2.1 noun and verb senses to their corresponding 3.0 senses, we provide sense mapping information in this package. This package contains files to map polysemous and monosemous words, and documentation that describes the format of these files. As with the Prolog database, this package is only downloadable in compressed tar format, but the files are also in ASCII.

## NOTES
The lexicographer files and grind(1) program are not generally distributed.

All of the packages described above may not be available at the time of release of the 3.0 database package.

## SEE ALSO
wnintro(1), wnintro(3), wnintro(5), wnintro(7).


wnstats

title: wnstats(7)

summary: WordNet 3.0 database statistics

text:
# wnstats(7)

## NAME
wnstats - WordNet 3.0 database statistics

## DESCRIPTION

### Number of words, synsets, and senses
POS

Unique

Synsets

Total

Strings

Word-Sense Pairs

Noun

117798

82115

146312

Verb

11529

13767

25047

Adjective

21479

18156

30002

Adverb

4481

3621

5580

Totals

155287

117659

206941

### Polysemy information
POS

Monosemous

Polysemous

Polysemous

Words and Senses

Words

Senses

Noun

101863

15935

44449

Verb

6277

5252

18770

Adjective

16503

4976

14399

Adverb

3748

733

1832

Totals

128391

26896

79450

POS

Average Polysemy

Average Polysemy

Including Monosemous Words

Excluding Monosemous Words

Noun

1.24

2.79

Verb

2.17

3.57

Adjective

1.40

2.71

Adverb

1.25

2.50

## NOTES
Statistics for all types of adjectives and adjective satellites are combined.

The total of all unique noun, verb, adjective, and adverb strings is actually 147278. However, many strings are unique within a syntactic category, but are in more than one syntactic category. The figures in the table represent the unique strings in each syntactic category.


xautomation

package: xautomation

title: xautomation(7)

text:
# xautomation(7)

## NAME
xautomation - control X from the command line, and find things on the screen

## DESCRIPTION
xautomation is a set of command lines programs to control X and do "visual scraping" to find things on the screen. The control interface allows mouse movement, clicking, button up/down, key up/down, etc, and uses the XTest extension so you don't have the annoying problems that xse has when apps ignore sent events. The visgrep program find images inside of images and reports the coordinates, allowing programs to find buttons, etc, on the screen to click on.

xautomation consists in the following programs:

pat2ppm

Converts an image file from PAT to PPM format.

patextract

Extract a part of a PNG image file.

png2pat

Converts an image file from PNG to PAT format.

rgb2pat

Converts an image file from 24-bit RGB to PAT format

visgrep

Visual grep, greps for images in another image.

xte

Generates fake input using the XTest extension.

For more information, please see the individual manpages of these programs.

## SEE ALSO
pat2ppm(1), patextract(1), png2pat(1), rgb2pat(1), visgrep(1), xte(1).

## AUTHOR
xautomation was written by Steve Slaven <bpk@hoopajoo.net>.

This manual page was written by Aurelien Jarno <aurel32@debian.org>, for the Debian project (but may be used by others).


xen-pci-device-reservations

package: xen

title: xen-pci-device-reservations(7)

summary: Xen PCI device ID registry

text:
# xen-pci-device-reservations(7)

## NAME
xen-pci-device-reservations - Xen PCI device ID registry

## Description
PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to advertise certain virtual hardware to guest virtual machines. The primary use of this is with device ID 0x0001 to advertise the Xen Platform PCI device - the presence of this virtual device enables a guest Operating System (subject to the availability of suitable drivers) to make use of paravirtualisation features such as disk and network devices etc.

Some Xen vendors wish to provide alternative and/or additional guest drivers that can bind to virtual devices[1]. This may be done using the Xen PCI vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file records reservations made within the device ID range in order to avoid multiple Xen vendors using conflicting IDs.

## Guidelines
1. A vendor may request a range of device IDs by submitting a patch to this file.

2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the possibility of clashes with community IDs assigned from the bottom up.

3. The vendor is responsible for allocations within the range and should try to record specific device IDs in PCI ID databases such as https://pci-ids.ucw.cz and https://devicehunt.com

## Reservations

```
        range     | vendor/product
    --------------+--------------------------------------------------------------
    0x0001        | (Xen Platform PCI device)
    0x0002        | Citrix XenServer (grandfathered allocation for XenServer 6.1)
    0xc000-0xc0ff | Citrix XenServer
    0xc100-0xc1ff | Citrix XenClient
    0xc200-0xc2ff | XCP-ng Project (https://xcp-ng.org)
```

## Notes
1.

Upstream QEMU provides a parameterized device called xen-pvdevice that can be used to host guest drivers. Execute:

```
    qemu-system-i386 -device xen-pvdevice,help

```

for a list of all parameters. The following parameters are relevant to driver binding:

vendor-id (default 0x5853)

The PCI vendor ID and subsystem vendor ID of the device.

device-id (must be specified)

The PCI device ID and subsystem device ID of the device.

revision (default 0x01)

The PCI revision of the device

Also the size parameter (default 0x400000) can be used to specify the size of the single MMIO BAR that the device exposes. This area may be used by drivers for mapping grant tables, etc.

Note that the presence of the Xen Platform PCI device is generally a pre-requisite for an additional xen-pvdevice as it is the platform device that provides that IO ports necessary for unplugging emulated devices. See hvm-emulated-unplug.markdown for details of the IO ports and unplug protocol.

libxl provides support for creation of a single additional xen-pvdevice. See the vendor_device parameter in xl.cfg(5).


xen-pv-channel

title: xen-pv-channel(7)

summary: Xen PV Channels

text:
# xen-pv-channel(7)

## NAME
xen-pv-channel - Xen PV Channels

## DESCRIPTION
A channel is a low-bandwidth private byte stream similar to a serial link. Typical uses of channels are

1.

to provide initial configuration information to a VM on boot (example use: CloudStack's cloud-early-config service)

2.

to signal/query an in-guest agent (example use: oVirt's guest agent)

Channels are similar to virtio-serial devices and emulated serial links. Channels are intended to be used in the implementation of libvirt s when running on Xen.

Note: if an application requires a high-bandwidth link then it should use vchan instead.

### How to use channels: an example
Consider a cloud deployment where VMs are cloned from pre-made templates, and customised on first boot by an in-guest agent which sets the IP address, hostname, ssh keys etc. To install the system the cloud administrator would first:

1.

Install a guest as normal (no channel configuration necessary)

2.

Install the in-guest agent specific to the cloud software. This will prepare the guest to communicate over the channel, and also prepare the guest to be cloned safely (sometimes known as "sysprepping")

3.

Shutdown the guest

4.

Register the guest as a template with the cloud orchestration software

5.

Install the cloud orchestration agent in dom0

At runtime, when a cloud tenant requests that a VM is created from the template, the sequence of events would be: (assuming a Linux domU)

1.

A VM is "cloned" from the template

2.

A unique Unix domain socket path in dom0 is allocated (e.g. /my/cloud/software/talk/to/domain/)

3.

Domain configuration is created for the VM, listing the channel name expected by the in-guest agent. In xl syntax this would be: channel = [ "connection=socket, name=org.my.cloud.software.agent.version1, path = /my/cloud/software/talk/to/domain/" ]

4.

The VM is started

5.

In dom0 the cloud orchestration agent connects to the Unix domain socket, writes a handshake message and waits for a reply

6.

Assuming the guest kernel has CONFIG_HVC_XEN_FRONTEND set then the console driver will generate a hotplug event

7.

A udev rule is activated by the hotplug event. The udev rule would look something like:

SUBSYSTEM=="xen", DEVPATH=="/devices/console-[0-9]", RUN+="xen-console-setup"

where the "xen-console-setup" script would read the channel name and make a symlink in /dev/xen-channel/org.my.cloud.software.agent.version1 pointing to /dev/hvcN. N is the same number as the number in "/devices/console-[0-9]". In other words, "/devices/console-2" maps to /dev/hvc2.

8.

The in-guest agent uses inotify to see the creation of the /dev/xen-channel symlink and opens the device.

9.

The in-guest agent completes the handshake with the dom0 agent

10.

The dom0 agent transmits the unique VM configuration: hostname, IP address, ssh keys etc etc

11.

The in-guest agent receives the configuration and applies it.

Using channels avoids having to use a temporary disk device or network connection.

### Design recommendations and pitfalls
It's necessary to install channel-specific software (an "agent") into the guest before you can use a channel. By default a channel will appear as a device which could be mistaken for a serial port or regular console. It is known that some software will proactively seek out serial ports and issue AT commands at them; make sure such software is disabled!

Since channels are identified by names, application authors must ensure their channel names are unique to avoid clashes. We recommend that channel names include parts unique to the application such as a domain names. To assist prevent clashes we recommend authors add their names to our global channel registry at the end of this document.

### Limitations
Hotplug and unplug of channels is not currently implemented.

### Channel name registry
It is important that channel names are globally unique. To help ensure that no-one's name clashes with yours, please add yours to this list.

```
    Key:
    N: Name
    C: Contact
    D: Short description of use, possibly including a URL to your software or API
    N: org.xenproject.guest.clipboard.0.1
    C: David Scott <dave.scott@citrix.com>
    D: Share clipboard data via an in-guest agent. See:
       https://wiki.xenproject.org/wiki/Clipboard_sharing_protocol
```


xen-tscmode

title: xen-tscmode(7)

text:
# xen-tscmode(7)

## NAME
xen-tscmode - Xen TSC (time stamp counter) and timekeeping discussion

## OVERVIEW
As of Xen 4.0, a new config option called tsc_mode may be specified for each domain. The default for tsc_mode handles the vast majority of hardware and software environments. This document is targeted for Xen users and administrators that may need to select a non-default tsc_mode.

Proper selection of tsc_mode depends on an understanding not only of the guest operating system (OS), but also of the application set that will ever run on this guest OS. This is because tsc_mode applies equally to both the OS and ALL apps that are running on this domain, now or in the future.

Key questions to be answered for the OS and/or each application are:

- Does the OS/app use the rdtsc instruction at all? (We will explain below how to determine this.)

- At what frequency is the rdtsc instruction executed by either the OS or any running apps? If the sum exceeds about 10,000 rdtsc instructions per second per processor, we call this a "high-TSC-frequency" OS/app/environment. (This is relatively rare, and developers of OS's and apps that are high-TSC-frequency are usually aware of it.)

- If the OS/app does use rdtsc, will it behave incorrectly if "time goes backwards" or if the frequency of the TSC suddenly changes? If so, we call this a "TSC-sensitive" app or OS; otherwise it is "TSC-resilient".

This last is the US$64,000 question as it may be very difficult (or, for legacy apps, even impossible) to predict all possible failure cases. As a result, unless proven otherwise, any app that uses rdtsc must be assumed to be TSC-sensitive and, as we will see, this is the default starting in Xen 4.0.

Xen's new tsc_mode parameter determines the circumstances under which the family of rdtsc instructions are executed "natively" vs emulated. Roughly speaking, native means rdtsc is fast but TSC-sensitive apps may, under unpredictable circumstances, run incorrectly; emulated means there is some performance degradation (unobservable in most cases), but TSC-sensitive apps will always run correctly. Prior to Xen 4.0, all rdtsc instructions were native: "fast but potentially incorrect." Starting at Xen 4.0, the default is that all rdtsc instructions are "correct but potentially slow". The tsc_mode parameter in 4.0 provides an intelligent default but allows system administrator's to adjust how rdtsc instructions are executed differently for different domains.

The non-default choices for tsc_mode are:

- tsc_mode=1 (always emulate). All rdtsc instructions are emulated; this is the best choice when TSC-sensitive apps are running and it is necessary to understand worst-case performance degradation for a specific hardware environment.

- tsc_mode=2 (never emulate). This is the same as prior to Xen 4.0 and is the best choice if it is certain that all apps running in this VM are TSC-resilient and highest performance is required.

- tsc_mode=3 (PVRDTSCP). This mode has been removed.

If tsc_mode is left unspecified (or set to tsc_mode=0), a hybrid algorithm is utilized to ensure correctness while providing the best performance possible given:

- the requirement of correctness,

- the underlying hardware, and

- whether or not the VM has been saved/restored/migrated

To understand this in more detail, the rest of this document must be read.

## DETERMINING RDTSC FREQUENCY
To determine the frequency of rdtsc instructions that are emulated, an "xl" command can be used by a privileged user of domain0. The command:

```
    # xl debug-key s; xl dmesg | tail
```

provides information about TSC usage in each domain where TSC emulation is currently enabled.

## TSC HISTORY
To understand tsc_mode completely, some background on TSC is required:

The x86 "timestamp counter", or TSC, is a 64-bit register on each processor that increases monotonically. Historically, TSC incremented every processor cycle, but on recent processors, it increases at a constant rate even if the processor changes frequency (for example, to reduce processor power usage). TSC is known by x86 programmers as the fastest, highest-precision measurement of the passage of time so it is often used as a foundation for performance monitoring. And since it is guaranteed to be monotonically increasing and, at 64 bits, is guaranteed to not wraparound within 10 years, it is sometimes used as a random number or a unique sequence identifier, such as to stamp transactions so they can be replayed in a specific order.

On most older SMP and early multi-core machines, TSC was not synchronized between processors. Thus if an application were to read the TSC on one processor, then was moved by the OS to another processor, then read TSC again, it might appear that "time went backwards". This loss of monotonicity resulted in many obscure application bugs when TSC-sensitive apps were ported from a uniprocessor to an SMP environment; as a result, many applications -- especially in the Windows world -- removed their dependency on TSC and replaced their timestamp needs with OS-specific functions, losing both performance and precision. On some more recent generations of multi-core machines, especially multi-socket multi-core machines, the TSC was synchronized but if one processor were to enter certain low-power states, its TSC would stop, destroying the synchrony and again causing obscure bugs. This reinforced decisions to avoid use of TSC altogether. On the most recent generations of multi-core machines, however, synchronization is provided across all processors in all power states, even on multi-socket machines, and provide a flag that indicates that TSC is synchronized and "invariant". Thus TSC is once again useful for applications, and even newer operating systems are using and depending upon TSC for critical timekeeping tasks when running on these recent machines.

We will refer to hardware that ensures TSC is both synchronized and invariant as "TSC-safe" and any hardware on which TSC is not (or may not remain) synchronized as "TSC-unsafe".

As a result of TSC's sordid history, two classes of applications use TSC: old applications designed for single processors, and the most recent enterprise applications which require high-frequency high-precision timestamping.

We will refer to apps that might break if running on a TSC-unsafe machine as "TSC-sensitive"; apps that don't use TSC, or do use TSC but use it in a way that monotonicity and frequency invariance are unimportant as "TSC-resilient".

The emergence of virtualization once again complicates the usage of TSC. When features such as save/restore or live migration are employed, a guest OS and all its currently running applications may be invisibly transported to an entirely different physical machine. While TSC may be "safe" on one machine, it is essentially impossible to precisely synchronize TSC across a data center or even a pool of machines. As a result, when run in a virtualized environment, rare and obscure "time going backwards" problems might once again occur for those TSC-sensitive applications. Worse, if a guest OS moves from, for example, a 3GHz machine to a 1.5GHz machine, attempts by an OS/app to measure time intervals with TSC may without notice be incorrect by a factor of two.

The rdtsc (read timestamp counter) instruction is used to read the TSC register. The rdtscp instruction is a variant of rdtsc on recent processors. We refer to these together as the rdtsc family of instructions, or just "rdtsc". Instructions in the rdtsc family are non-privileged, but privileged software may set a cpuid bit to cause all rdtsc family instructions to trap. This trap can be detected by Xen, which can then transparently "emulate" the results of the rdtsc instruction and return control to the code following the rdtsc instruction.

To provide a "safe" TSC, i.e. to ensure both TSC monotonicity and a fixed rate, Xen provides rdtsc emulation whenever necessary or when explicitly specified by a per-VM configuration option. TSC emulation is relatively slow -- roughly 15-20 times slower than the rdtsc instruction when executed natively. However, except when an OS or application uses the rdtsc instruction at a high frequency (e.g. more than about 10,000 times per second per processor), this performance degradation is not noticeable (i.e. <0.3%). And, TSC emulation is nearly always faster than OS-provided alternatives (e.g. Linux's gettimeofday). For environments where it is certain that all apps are TSC-resilient (e.g. "TSC-safeness" is not necessary) and highest performance is a requirement, TSC emulation may be entirely disabled (tsc_mode==2).

The default mode (tsc_mode==0) checks TSC-safeness of the underlying hardware on which the virtual machine is launched. If it is TSC-safe, rdtsc will execute at hardware speed; if it is not, rdtsc will be emulated. Once a virtual machine is save/restored or migrated, however, there are two possibilities: TSC remains native IF the source physical machine and target physical machine have the same TSC frequency (or, for HVM/PVH guests, if TSC scaling support is available); else TSC is emulated. Note that, though emulated, the "apparent" TSC frequency will be the TSC frequency of the initial physical machine, even after migration.

Finally, tsc_mode==1 always enables TSC emulation, regardless of the underlying physical hardware. The "apparent" TSC frequency will be the TSC frequency of the initial physical machine, even after migration. This mode is useful to measure any performance degradation that might be encountered by a tsc_mode==0 domain after migration occurs, or a tsc_mode==3 domain when it is running on TSC-unsafe hardware.

Note that while Xen ensures that an emulated TSC is "safe" across migration, it does not ensure that it continues to tick at the same rate during the actual migration. As an oversimplified example, if TSC is ticking once per second in a guest, and the guest is saved when the TSC is 1000, then restored 30 seconds later, TSC is only guaranteed to be greater than or equal to 1001, not precisely 1030. This has some OS implications as will be seen in the next section.

## TSC INVARIANT BIT and NO_MIGRATE
Related to TSC emulation, the "TSC Invariant" bit is architecturally defined in a cpuid bit on the most recent x86 processors. If set, TSC invariance ensures that the TSC is "safe", that is it will increment at a constant rate regardless of power events, will be synchronized across all processors, and was properly initialized to zero on all processors at boot-time by system hardware/BIOS. As long as system software never writes to TSC, TSC will be safe and continuously incremented at a fixed rate and thus can be used as a system "clocksource".

This bit is used by some OS's, and specifically by Linux starting with version 2.6.30(?), to select TSC as a system clocksource. Once selected, TSC remains the Linux system clocksource unless manually overridden. In a virtualized environment, since it is not possible to synchronize TSC across all the machines in a pool or data center, a migration may "break" TSC as a usable clocksource; while time will not go backwards, it may not track wallclock time well enough to avoid certain time-sensitive consequences. As a result, Xen can only expose the TSC Invariant bit to a guest OS if it is certain that the domain will never migrate. As of Xen 4.0, the "no_migrate=1" VM configuration option may be specified to disable migration. If no_migrate is selected and the VM is running on a physical machine with "TSC Invariant", Linux 2.6.30+ will safely use TSC as the system clocksource. But, attempts to migrate or, once saved, restore this domain will fail.

There is another cpuid-related complication: The x86 cpuid instruction is non-privileged. HVM domains are configured to always trap this instruction to Xen, where Xen can "filter" the result. In a PV OS, all cpuid instructions have been replaced by a paravirtualized equivalent of the cpuid instruction ("pvcpuid") and also trap to Xen. But apps in a PV guest that use a cpuid instruction execute it directly, without a trap to Xen. As a result, an app may directly examine the physical TSC Invariant cpuid bit and make decisions based on that bit.

## HARDWARE TSC SCALING
Intel VMX TSC scaling and AMD SVM TSC ratio allow the guest TSC read by guest rdtsc/p increasing in a different frequency than the host TSC frequency.

If a HVM container in default TSC mode (tsc_mode=0) is created on a host that provides constant TSC, its guest TSC frequency will be the same as the host. If it is later migrated to another host that provides constant TSC and supports Intel VMX TSC scaling/AMD SVM TSC ratio, its guest TSC frequency will be the same before and after migration.

For above HVM container in default TSC mode (tsc_mode=0), if above hosts support rdtscp, both guest rdtsc and rdtscp instructions will be executed natively before and after migration.

## AUTHORS
Dan Magenheimer <dan.magenheimer@oracle.com>