display-directx

title: display-directx(7)

text:
# display-directx(7)

## NAME
display-directx : DirectX (WIN32)

## SYNOPSIS

```
display-directx: [ [-inwin=<winid>|root] | [-fullscreen] ]

                 [ [-keepcursor] | [-nocursor] ] [-noinput]

                 [-physz=<sizex>,<sizey>[dpi]]
```

## DESCRIPTION
Used for Win32 DirectX port of libGGI.

## OPTIONS
-inwin=<winid>|root

Run in already-existing window with id winid. This can be used to embed a LibGGI application into a DirectX application. The value should be a DirectX window ID expressed as a decimal, hexadecimal or octal number in C syntax. The special string "root" will cause the application to run in the root window. Note that in the root window, you may need to explicitly select a LibGII input source using the GGI_INPUT environment variable as Windows will absorb all events sent to the window. When using the root window other features (like direct framebuffer access and video hardware mode selection) may be available which are not available when the application is running in a normal window.

-fullscreen

If mode switching is required for the mode, this option makes it possible to set it. Superior to -inwin=root.

-nocursor, -keepcursor

Normal behavior of display-directx is to create a small dot mouse cursor pixmap which is visible when the mouse is positioned over the window containing the visual. With the former option, the DirectX mouse cursor will be invisible when it is over the visual, with the latter, the cursor from the root window is used unaltered. If both options are supplied, the latter takes precedence. Note, that none of them works with the -inwin option.

-noinput

DirectX events sent to the window are not captured and merged with any other LibGII input sources. This allows one to take input from raw devices without receiving duplicate events should DirectX also be configured to use the device.

-physz=<sizex>,<sizey>[dpi]

This option will override the physical screen size reported by the DirectX, which affects applications which wish to remain resolution independent. sizex,:p:sizey are the x,y size of the entire screen (not just the DirectX window containing the visual) in millimeters, unless the optional dpi string is affixed, in which case, they represent resolution in dots-per-inch. Yes, there are two equals signs there, for reasons of compatibility with other targets.

## FEATURES

- DirectBuffer

- Multiple frames (up to 16)

- Panning

## BUGS

- On palettized windowed modes (i.e. not with -fullscreen) the first and last 10 entries of the palette are reserved by Windows and will not behave correctly. Even with the -fullscreen option, palettized modes can have problems with the first and the last entry, depending on what version of Windows is running.

- Can not draw directly in video ram, instead uses a intermediate buffer that is copied to video ram at regular intervals.

- The rate at which the above copy happens is fixed at 30Hz, and cannot be controlled by the user. The environment variable MANSYNC_FPS should probably be used.

- Does not fall back to fullscreen if -fullscreen is not specified. That should ideally happen when the requested graphics mode is incompatible with the current Windows graphics mode and a matching fullscreen mode is there.


display-fbdev

package: libggi

title: display-fbdev(7)

text:
# display-fbdev(7)

## NAME
display-fbdev : Display using Linux kernel framebuffer devices

## SYNOPSIS

```
display-fbdev: [ [-noinput] | [ [-nokbd] | [-nomouse] ] ] [-novt]

               [-physz=<sizex>,<sizey>[dpi]] [<framebuffer>]
```

## DESCRIPTION
Uses the Linux /dev/fb* devices to do fullscreen graphics.

When using a regular fbdev driver, /etc/fb.modes is used to determine the available modes for the device. Driver timings and resolutions can be automatically obtained when running under KGIcon.

## OPTIONS
framebuffer

The filename of the framebuffer target to use. The default is to get it from the FRAMEBUFFER environment, or the framebuffer associated with the current console if that is unset.

-nokbd

Do not open any libraries for keyboard input.

-nomouse

Do not open any libraries for mouse input.

-noinput

Same as both -nokbd and -nomouse.

-novt

Disable virtual console support.

-physz=<sizex>,<sizey>[dpi]

This option will provide a physical screen size for applications which wish to remain resolution independent. sizex,:p:sizey are the x,y size of the screen in millimeters, unless the optional dpi string is affixed, in which case, they represent resolution in dots-per-inch.

## FEATURES

- DirectBuffer always available.

- Accelerated when using KGIcon or matroxfb.

- Multiple frames.

- Panning.

## SEE ALSO
fb.modes(5)

branch: sisyphus


display-file

title: display-file(7)

text:
# display-file(7)

## NAME
display-file : Render display into image file

## SYNOPSIS

```
display-file: [-flushcmd=<command>] [-flushframe=<n>]

              [-flushtime=<t>] <filename>
```

## DESCRIPTION
Renders an image into a file. The file can be a framebuffer device (e.g. /dev/fb0), in which case a reasonable representation of the image will be drawn on the console so long as the program's mode matches the framebuffer's mode.

Note: This target generates no input. The display-multi(7) target can be used in order to see (and control) what the program does (using a normal target) and then generate a snapshot when the program exits.

## OPTIONS
filename is the file to render the images to. If the filename is a PPM file (has the extension .ppm), then the image will be generated at ggiClose(3) time. Otherwise the file is a custom GGIFILE format and is generated continuously.

The display-file target can be used to generate movies from running LibGGI applications. To do this, set -flushcmd to a shell command to execute at the times given by one of the two other parameters. This looks typically like:

```
ppmtogif foo.ppm > foo.%04d.gif
```

The command is passed through a printf(3) which has the current count of saved frames as an argument (or rather as 10 arguments to allow a few more complex commands).

This shell command is either executed at every n-th invocation of ggiFlush or every t seconds, where t can have fractional components (specified as decimal).

Note, that the invocation of the shell command will slow down the program, so make sure you use a reasonable value, if you use the -flushtime argument.

The primary file is updated before every invocation of the shell command.

## FEATURES

- DirectBuffer always available.

- Unaccelerated.


display-glide

title: display-glide(7)

text:
# display-glide(7)

## NAME
display-glide : Display using Glide library

## SYNOPSIS

```
display-glide:<card>
```

## DESCRIPTION
Uses the Glide library to display fullscreen on a 3DFX graphics card.

## OPTIONS
The 3DFX card to use can be optionally specified as a cardinal number minus one. (e.g. 0 means the first card, 1 the second,

## ENVIRONMENT VARIABLES
GGI_GLIDE_MAXFREQ

specifies the maximum update frequency your monitor can handle (in Hz). Default is 70Hz.

GGI_GLIDE_MAXHFREQ

specifies the maximum horizontal frequency your monitor can handle (in kHz). Default is 48kHz.

GGI_GLIDE_HALTONSWITCH

if this is set applications will be halted on console switchaway. The default is to continue running.

## FEATURES

- DirectBuffer never available.

- Accelerated, one of the fastest targets when it comes to drawing-primitives.

- Multiple frames.


display-mansync

title: display-mansync(7)

text:
# display-mansync(7)

## NAME
display-mansync : sync mode emulation

## SYNOPIS

```
display-mansync
```

## DESCRIPTION
Helper library for the implementation of SYNC mode on targets which are inherently ASYNC (e.g. X) and require manual flushes of the framebuffer.

A target wishing to use mansync should open mansync with _ggiAddDL() in it's own GGIopen(). It must pass a pointer to a _ggi_opmansync structure as the argument to _ggiAddDL(), and must define the following macros:

```
MANSYNC_init(vis)
MANSYNC_deinit(vis)
MANSYNC_start(vis)
MANSYNC_stop(vis)
MANSYNC_ignore(vis)
MANSYNC_cont(vis)
```

which is supposed to call the functions in _ggi_opmansync respectively.

Mansync provides the following functions:

```
int _GGI_mansync_init(vis);
int _GGI_mansync_deinit(vis);

      Initialize/deinitialize mansync for given visual.
int _GGI_mansync_start(vis);
int _GGI_mansync_stop(vis);

      Start/stop mansync handling. (process,thread,etc.)

      You don't need to explicitly call these;

      MANSYNC_SETFLAGS does it for you.
int _GGI_mansync_ignore(vis);
int _GGI_mansync_cont(vis);

      Temporarily start/stop mansync, e.g. during mode set.

      It is o.k. to use them even if mansync has not been started.
MANSYNC_SETFLAGS(vis,flags)

      mansync management in ggiSetFlags().
```

(The above functions return 0 if successful, -1 if not.)

Please see display/X, display/aa or display/tile to see how mansync is used. The functions should be transparent enough.

Important: You're responsible for locking your own visual, not mansync!

## ENVIRONMENT VARIABLES
GGI_MANSYNC_FPS

This variable specifies the framerate for targets emulating synchronous mode. The default is 20fps. If you are experiencing problems with the X target over relatively slow remote connections it might be due to connection overload. You might want to try with a lower GGI_MANSYNC_FPS setting.


display-memory

title: display-memory(7)

text:
# display-memory(7)

## NAME
display-memory : Display on buffer in main memory

## SYNOPSIS

```
display-memory: [-input] [-noblank]

                [-layout=<fstride>[[plb<lstride>]|[plan<pstride>,<plstride>]]]

                [-physz=<sizex>,<sizey>[dpi]] [-pixfmt=<format_string>]

                [ [shmid:<sid> ] | [keyfile:<size>:<id>:<fname>] | pointer ]
```

## DESCRIPTION
Emulates a linear framebuffer in main memory. The framebuffer can be a shared memory segment, an area specified by the application, or an area allocated by display-memory itself.

## OPTIONS
-input

If the -input option is set, an input buffer of INPBUFSIZE (default is 8192 bytes) as #define'd in ggi/display/memory.h is allocated at the start of the requested memory area. When running on shared memory, this option enables you to give input (using giiEventSend(3)) to other processes sharing that segment. This technique is demonstrated in cube3d(1) and can be used for things like GGI multiplexers.

-noblank

If the -noblank option is set, the framebuffer will not be filled with solid black when the mode of the visual is set. This is useful for preserving data from other sources when using a preallocated area of memory as a framebuffer.

-physz=<sizex>,<sizey>[dpi]

This option will provide a physical screen size for applications which wish to remain resolution independent. sizex, sizey are the x,y size of the screen in millimeters, unless the optional dpi string is affixed, in which case, they represent resolution in dots-per-inch.

-pixfmt=<format_string>

This option will provide a non-default pixel format explicitly. Currently the accepted format of format_string is something like "r5b5g5p1", which would specify a pixel where the low bit of the pixel is unused padding, followed by 5 bits of green, then 5 bits of blue and finally 5 bits of red, with the remaining high bits, if any, being unused pad. A more formal description of this format string will be provided (and more strings accepted) in future LibGGI releases.

[-layout=<fstride>[[plb<lstride>]|[plan<pstride>,<plstride>]]]

This option will provide a non-default framebuffer layout explicitly. The fstride parameter denotes the number of bytes between frames in the framebuffer, and will default to the size of the virtual screen in bytes if nonpresent or set to 0. Following fstride, the string plb denotes a linear packed-pixel framebuffer, or the string plan instead denotes a planar framebuffer. The packed-pixel framebuffer layout is the default. If the string plb is present, a horizontal stride lstride may appear, denoting the number of bytes that elapse between the beginning of one line and the next. This will default to the size of a horizontal line in bytes if nonpresent or set to zero. If the string "plan" is present, up to two numbers, comma separated, may appear after the string. The first number, pstride denotes the number of bytes which elapse between the beginning of one plane and the next. This will default to the minimum integral number of bytes that may contain one bitplane of the virtual screen if nonpresent or set to zero. The second number, plstride denotes the number of bytes that elapse between the beginning of one bitplane-line and the next. This will default to the minimum integral number of bytes which may contain one bitplane-line of the virtual screen if nonpresent or set to zero. More strings and format parameters may accepted in future LibGGI releases.

shmid:<sid>

use existing shared memory ID sid On win32, sid is the HANDLE returned by a call to CreateFileMapping in decimal form.

keyfile:<size>:<id>:<fname>

create a new shm segment with id ftok(fname,id) of size size (preferred method !). See ftok(3). On win32, the newly created shared memory mapping has the object name: ggi-display-memory-shm:<fname>:<ascid>, where all backslashes have been converted to forward slashes in fname and ascid is the ascii value of id in decimal form. If this object does already exist (and is a file mapping) it will be used, so two apps can share memory by using the same keyfile arguments on win32.

pointer

use the memory pointed to by argptr (only available to applications calling ggiOpen(3)).

Important: If you specify a memory area to use - be sure it's big enough as no checks can or will be made that a certain mode fits into it.

## FEATURES

- DirectBuffer support always available.

- Unaccelerated.


display-monotext

title: display-monotext(7)

text:
# display-monotext(7)

## NAME
display-monotext : Emulate palettized modes on text-mode visuals

## SYNOPSIS

```
display-monotext: [ [-a=<acc>] | [ [-x=<acc>] [-y=<acc>] ] ] <target-spec>
```

## DESCRIPTION
Emulates palettized modes (GT_PALETTE) on another target which can only do text modes, by representing the graphics as ASCII characters. The effect is the much the same as the AAlib target, but does not depend on any external libraries.

## OPTIONS
-x=<acc>, -y=<acc>

A value between 1 and 5 which determines how accurately to map the graphics to ASCII characters. Lower values are less accurate, but can represent a wider range of intensity levels. The default is x=2 and y=4.

-a=<acc>

Same as above, but sets both the x and y accuracy to the specified value.

target-spec

Specifies the target which to draw on (the parent target). This defaults to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY is not set).


display-multi

title: display-multi(7)

text:
# display-multi(7)

## NAME
display-multi : Duplicate visual operations onto multiple visuals

## SYNOPSIS

```
display-multi <:targetspec> ...
```

## DESCRIPTION
Duplicates all drawing operations onto multiple child targets, thus producing identical output on multiple visuals.

## OPTIONS
The argument to display-multi is a colon- (:) separated list of target specs to draw on. Because target specs can (and often do) contain colons, they need to be enclosed in parentheses.

target-spec

Specifies the target which to draw on (the parent target). This defaults to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY is not set).

## FEATURES

- DirectBuffer never supported.

- Unaccelerated.


display-palemu

title: display-palemu(7)

text:
# display-palemu(7)

## NAME
display-palemu : Emulate palettized modes on visuals of other mode schemes

## SYNOPSIS

```
display-palemu: [-parent=<mode>] <target-spec>
```

## DESCRIPTION
Emulates palettized modes (GT_PALETTE) on another target which can only do truecolor/greyscale/text modes or palettized modes of higher depth.

## OPTIONS
-parent=<mode>

Force the parent target to use a specific mode, specified as a standard LibGGI mode string (see libggi(7)).

target-spec

Specifies the target which to draw on (the parent target). This defaults to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY is not set).

## FEATURES

- DirectBuffer never supported.

- Unaccelerated.


display-quartz

title: display-quartz(7)

text:
# display-quartz(7)

## NAME
display-quartz : Display using Quartz2D on Mac OSX

## SYNOPSIS

```
display-quartz:       [-physz=<sizex>,<sizey>[dpi]] [-nomansync]
```

## DESCRIPTION
Uses MacOS X Quartz/Carbon API for display.

MacOS X 10.2.8 is required.

## OPTIONS
-physz=<sizex>,<sizey>[dpi]

This option will override the physical screen size reported by the Quartz, which affects applications which wish to remain resolution independent. sizex, sizey are the x,y size of the entire screen (not just the Carbon Window containing the visual) in millimeters, unless the optional dpi string is affixed, in which case, they represent resolution in dots-per-inch. Yes, there are two equals signs there, for reasons of compatibility with other targets.

-nomansync

Use of the mansync helper library to periodically flush contents to the screen is disabled. This, of course, will result in incorrect behaviour of applications that use syncronous mode.

## FEATURES
•

Directbuffer


display-sub

title: display-sub(7)

text:
# display-sub(7)

## NAME
display-sub : Make a child visual that is a window to the parent

## SYNOPSIS

```
display-sub: <target-spec>
```

## DESCRIPTION
Creates a "child" visual within a "parent". This can be thought of as a window and the display-sub target is intended for simple windowing systems.

No textual arguments, since this target can only be used by applications. argptr must contain the parent visual.

The sub target behaves a bit special with respect to (i.e. abuses the semantics of :) the ggiSetMode(3) call. It uses the "visible" size for the top left corner position of the window within the visual, and the "virtual" size for window width and height. Note, that moving/resizing the window does not cause any drawing action. You have to perform those yourself. All it does for you is providing a virtual visual within an existing one, which is convenient to allow for window system canvases to be about any GGI program.

Important: It is possible to have (0, 0) as upper, left corner. But beware, 0 means GGI_AUTO and therefore it may get overridden by GGI_DEFMODE environment variable. In this case, you may get unintended results.

## OPTIONS
target-spec

Specifies the target which to draw on (the parent target). This defaults to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY is not set).

## FEATURES

- DirectBuffer not supported.

- Accelerated to the point of the parent. Calls are mapped through with modified clipping and coordinates.


display-svgalib

title: display-svgalib(7)

text:
# display-svgalib(7)

## NAME
display-svgalib : Display fullscreen using SVGAlib

## SYNOPSIS

```
display-svgalib: [-physz=<sizex>,<sizey>[dpi]]
```

## DESCRIPTION
Uses the SVGAlib library to display fullscreen on a VGA-compatible graphics card. You may need to be root in order to have IO permissions to drive the VGA device.

## OPTIONS
-physz=<sizex>,<sizey>[dpi]

This option will provide a physical screen size for applications which wish to remain resolution independent. sizex, sizey are the x,y size of the screen in millimeters, unless the optional dpi string is affixed, in which case, they represent resolution in dots-per-inch.

## FEATURES

- DirectBuffer is available for the 320x200x8 mode. For other modes, support is only available if SVGAlib supports linear addressing.

- Unaccelerated

## BUGS

- The getbox test of demo.c does not work correct on modeX.

- copybox is not implemented for banked and modeX modes.

- 1 and 4 bit modes don't work


display-tele

title: display-tele(7)

text:
# display-tele(7)

## NAME
display-tele : Forwards the display over a network

## SYNOPSIS

```
display-tele: [inet]:<host>[:port]
display-tele: unix:<file>
```

## DESCRIPTION
The tele target forwards the display over a network via TCP to a remote host.

A ggiteleserver(1) must be running on the remote host where the final display resides. A normal GGI applications will then use the tele target to forward all graphic operations to the machine running the teleserver.

## OPTIONS
The argument to display-tele is the display to connect to, it has the format <type>:<specifier>. The available types are inet and unix. The specifier for type inet has the format hostname:port, and for type unix, it is a file. Some examples:

```
- GGI_DISPLAY=tele:inet:localhost:27780
- GGI_DISPLAY=tele::192.168.1.2:27780 (inet is the default)
- GGI_DISPLAY=tele:unix:/tmp/.tele0
```

## FEATURES

- DirectBuffer never supported.

- Accelerated if the remote display is.

## SEE ALSO
ggiteleserver(1)


display-terminfo

title: display-terminfo(7)

text:
# display-terminfo(7)

## NAME
display-terminfo : Display using ncurses

## SYNOPSIS

```
display-terminfo: [-physz=<sizex>,<sizey>[dpi]]
```

## DESCRIPTION
Uses the ncurses library for output and input.

## OPTIONS
-physz=<sizex>,<sizey>[dpi]

This option will provide a physical screen size for applications which wish to remain resolution independent. sizex, sizey are the x,y size of the screen in millimeters, unless the optional dpi string is affixed, in which case, they represent resolution in dots-per-inch.

## FEATURES

- DirectBuffer support always available.

- Unaccelerated


display-tile

title: display-tile(7)

text:
# display-tile(7)

## NAME
display-tile : Divide display into tiles similar to a video wall

## SYNOPSIS

```
display-tile : [ [-usedb] | [-nodb] ]

               <offset-x>,<offset-y>,<size-x>,<size-y>,<child-target-spec>

               ...
```

## DESCRIPTION
Emulates one big target, where one or more areas are mapped to different child visuals.

## OPTIONS
For each tile (i.e. child visual or mapped area), the following must be specified:

offset-x, offset-y

coordinates (within the parent visual) of the top-left corner of the child visual

size-x, size-y

width and height of the child visual

:p`child-target-spec`

a target spec. Since target specs can (and often do) contain colons, it needs to be enclosed in parentheses.

The following options apply to the whole display-tile:

-usedb

Enables DirectBuffer emulation. This is the default mode. The contents of each mapped area is blitted from the DirectBuffer into their respective child visuals at regular intervals or when the visual is flushed. DirectBuffer emulation works regardless of whether the child visuals support DirectBuffer or not.

-nodb

Disables DirectBuffer emulation. LibGGI primitives are passed to each of the child visuals with the necessary clipping and translation. Thus, if a child visual underlying a mapped area supports acceleration, then the operation on that area will be accelerated.

## FEATURES

- DirectBuffer support depends on the -usedb and -nodb options.

- Accelerated in no-DB mode if the underlying target is, otherwise unaccelerated.

Tip: display-tile can be used to emulate DirectBuffer for obstinate applications that cannot run without it, by specifying one tile which maps the whole screen.


display-trueemu

title: display-trueemu(7)

text:
# display-trueemu(7)

## NAME
display-trueemu : Emulate truecolor modes

## SYNOPSIS

```
display-trueemu : [-parent=<mode>] [-dither=<dither>]

                  [-model=<model>] <target-spec>
```

## DESCRIPTION
Emulates truecolor modes (GT_TRUECOLOR) on another target which can only do palette modes or truecolor modes of different sizes/depths. Uses dithering and special palettes to get the highest possible quality.

## OPTIONS
-parent=<mode>

Force the parent target to use a specific mode, specified as a standard LibGGI mode string (see libggi(7)).

-dither=<dither>

Specifies the amount of dithering. Legal values are 0, 2 and 4, defaulting to 4. When the target is running, Ctrl-Alt-d changes the dithering level.

-model=<model>

Color model to use (only when the parent is palettized). Legal values are rgb, cube and pastel. Default depends on the parent mode. When the target is running, Ctrl-Alt-p changes the current color model.

target-spec

Specifies the target which to draw on (the parent target). This defaults to automatic selection (just like using ggiOpen(NULL) when GGI_DISPLAY is not set).

## FEATURES

- DirectBuffer never supported.

- Unaccelerated.


display-vcsa

title: display-vcsa(7)

text:
# display-vcsa(7)

## NAME
display-vcsa : Display using Linux virtual console text device

## SYNOPSIS

```
display-vcsa : [ [-noinput] | [ [-nokbd] [-nomouse] ] ] [-ascii]

                 [-physz=<sizex>,<sizey>[dpi]] [-shade] [<vcsa device>]
```

## DESCRIPTION
Uses the Linux /dev/vcsa* devices to render text modes onto the console.

## OPTIONS
-nokbd

Do not open any libraries for keyboard input.

-nomouse

Do not open any libraries for mouse input.

-noinput

Same as both -nokbd and -nomouse.

-ascii

The -ascii option limits the color mapping to only using ASCII characters. The default mode uses IBM special characters (the solid block mainly, and others when using -shade).

-shade

The -shade option turns on shading mode, which changes the color mapping so that it chooses characters which emulate a shading effect. This makes a big improvement if using (some might say abusing :) the vcsa target for graphical purposes.

-physz=<sizex>,<sizey>[dpi]

This option will provide a physical screen size for applications which wish to remain resolution independent. sizex, sizey are the x,y size of the screen in millimeters, unless the optional dpi string is affixed, in which case, they represent resolution in dots-per-inch.

vcsa device

The filename of the device file, defaulting to /dev/vcsa which draws on the current virtual console.

## FEATURES

- No DirectBuffer support.

- Unaccelerated.


display-vgl

title: display-vgl(7)

text:
# display-vgl(7)

## NAME
display-vgl : FreeBSD/i386 console display

## SYNOPSIS

```
display-vgl:[-nodb|-usedb]
```

## DESCRIPTION
Displays on the FreeBSD/i386 console. 16 and 32bit direct color support with the latest FreeBSD vgl(3) library (FreeBSD > R5.0 and a patch is available for FreeBSD R4.x series).

Like VGL, the vgl-display depends on the current VGA/VESA modes and you must load the vesa.ko module to get advanced modes (higher than 680x480x8).

## OPTIONS
-nodb

Don't use directbuffer.

-usedb

Make use of directbuffer.

## FEATURES

- True color support is best with directbuffer. Your board must provide VESA 2.1 compliance to use directbuffer. If it's an old S3 board, use the s3.ko module to access it's framebuffer (FreeBSD > R5.0).

- Unaccelerated (VESA).


display-x

title: display-x(7)

text:
# display-x(7)

## NAME
display-x : Displays to an X11 server

## SYNOPSIS

```
display-x: [ [-inwin=<winid>|root] | [-screen=<screenidx>] ]

           [-fullscreen] [-keepcursor] [-noaccel] [-nobuffer]

           [-nocursor] [-nodbe] [-nodga] [-noevi] [-noinput]

           [-nomansync] [-noshm] [-novidmode] [-physz=<sizex>,<sizey>[dpi]]

           [<display>]
```

## DESCRIPTION
display-x displays a GGI application via an X11 server. The server may be local or remote, and options are provided to tune performance to various scenerios. In normal operation, a new X11 window is opened, solid fill primitives and copybox are accelerated by the server, and a backbuffer is kept client-side for content fills (e.g. ggiPut* functions) and to restore data when an application has been exposed after being concealed by another window.

Ctrl-Alt-m toggles mouse grabbing in the new window. It will try to emulate a relative mouse device, i.e. one that can be moved arbitrarily far in any direction without ever leaving the window. This is useful for game controls, where loosing focus is generally undesireable. Note that grabbing must be turned off in order to leave the window.

## OPTIONS
display

The X display to connect to, otherwise defaults to the display specified in DISPLAY.

-fullscreen

Turns on the fullscreen mode. Default mode is the windowed mode. In fullscreen mode, the dga helper is tried first if not disabled by -nodga or failed for some reason. Then the vidmode helper is tried. When this fails, then the target falls back to the windowed mode. Note, the -inwin option has no effect with fullscreen.

-noaccel

All rendering is performed in the client-side backbuffer, and then sent to the server; no server-side accelerated graphics operations are used. This will signifigantly slow down certain graphics applications, but for applications that use directbuffer and asyncronous mode extensively the effect will not be noticeable. The only real reason to use this option, however, is to eliminate artifacts caused by incorrectly implemented X11 hardware drivers.

-nobuffer

No client-side backbuffer is kept. This may result in lost data when the LibGGI application is obscured by other windows. This data loss can be minimized by enabling backing store in the X11 server. Using this option will cause operations which must read back framebuffer data to be much slower, but on the other hand can result in a slight speed gain for certain graphics primitives. It is best used when resources are severely limited on the client side, and with applications that do not perform frequent ggiPut* operations. Note, with this option evExpose events are passed to the application (Otherwise, they are internally grabbed to update the backbuffer).

-nodbe

Use of the X11 DBE extension to provide buffered frame support is disabled.

Note: Currently DBE extension support has not been completed.

-nodga

Use of the XFree86-DGA extension to provide direct framebuffer access is disabled. Some implementations of the XFree86-DGA extension may cause system lockups. Use this option to prevent such occurrances.

-noevi

Use of the X11 Extended Visual Information extension to identify visuals which are exclusively used for overlay/underlay is disabled.

-noinput

X events sent to the window are not captured and merged with any other LibGII input sources. This allows one to take input from raw devices without receiving duplicate events should X also be configured to use the device.

-nocursor, -keepcursor

Normal behavior of display-x is to create a small dot mouse cursor pixmap which is visible when the mouse is positioned over the window containing the visual. This goes away when using mouse grabbing as described above, but otherwise can get in the way of mouse cursors implemented by the application. With the former option, the X mouse cursor will be invisible when it is over the visual, with the latter, the cursor from the root window is used unaltered. If both options are supplied, the latter takes precedence.

-nomansync

Use of the mansync helper library to periodically flush backbuffer contents to the X11 server is disabled. This, of course, will result in incorrect behavior of applications that use syncronous mode.

-noshm

Use of the MIT-SHM extension to speed data transfer between clients and servers which are running on the same machine is disabled. Normally it is not necessary to use this option, as use of the MIT-SHM extension is disabled automatically if it appears to be nonfunctional.

-inwin=<winid>|root

Run in already-existing window with id winid. This can be used to embed a LibGGI application into an X11 application. The value should be an X11 window ID expressed as a "0x" prefixed hexadecimal number. The special string "root" will cause the application to run in the root window of the selected screen (or the default screen if no explicit selection has been made.) Note that in the root window, you may need to explicitly select a LibGII input source using the GGI_INPUT environment variable as the window manager will absorb all events sent to the root window. Some features (currently frames and virtual areas) may not work in root windows. On the other hand, when using the root window other features like direct framebuffer access and video hardware mode selection may be available which are not available when the application is running in a normal window.

-novidmode

Use of the X11 Vidmode extension to change video timing in full-screen modes is disabled. Some implementations of the Vidmode extension may cause system lockups. Use this option to prevent such occurrances.

-physz=<sizex>,<sizey>[dpi]

This option will override the physical screen size reported by the X server, which affects applications which wish to remain resolution independent. sizex,:p:sizey are the x,y size of the entire screen (not just the X window containing the visual) in millimeters, unless the optional dpi string is affixed, in which case, they represent resolution in dots-per-inch. Yes, there are two equals signs there, for reasons of compatibility with other targets.

-screen=<screenidx>

The screen to run on. Normally the biggest/deepest screen compatible with the requested mode will be chosen; with this option only the screen specified by screenidx will be considered.

## CLIFF NOTES ON NEW X TARGET
The old X target rendered all primitives in a RAM backbuffer, and then copied the entire backbuffer periodically using the mansync helper to the X screen. This caused a lot of wasted bandwidth. However, since the bandwidth was being wasted anyway, LibGGIMISC splitline support was a simple hack that added nearly no complexity.

The old Xlib target had no RAM backbuffer and rendered all primitives using Xlib calls. This caused very slow performance when a lot of individual pixels were being drawn one at a time, and slow performance on operations which got pixel data back from the visual, since it had to be fetched back over the wire. Also, this precluded the use of the directbuffer on the xlib target.

The new X target in its default mode maintains both a RAM backbuffer on the client side, and uses Xlib primitives to draw on the server side. When a primitive, such as a drawbox, can use an Xlib function, the command is dispatched to the X server and the data in the RAM buffer is updated using a software renderer. For operations such as putbox, the RAM buffer is updated first, and the synced to the X server. Unlike the old target, the new target keeps track of a "dirty region" and only syncs the area affected since the last time a syncronization occured. This dirty-region tracking only keeps track of one rectangular dirty area. A helper library that keeps track of more than one rectangle could be implemented to improve performance of display-X and any other similarly designed display target. To be most flexible such a target should take weighted parameters representing the cost of transferring data (per byte) from the backbuffer, and the per-operation cost of initiating such a transfer, which would alter its strategy as to how many regions are maintained and how much they overlap.

The old X target's RAM buffer was implemented using the X target's drawops hooks -- that is, the RAM buffer was essentially a re-implementation of display-memory with the extra facilities to sync to the X server built in. The new target capitalizes on some improvements made in display-memory, and instead it opens and loads a child display-memory visual which takes care of finding software renderers for the RAM buffer. The main drawops of the new target dispatch the the X server commands and call the child's corresponsing software drawops to ensure consistant state of the RAM buffer vs the X window. This must be done such that any requests to get data from the RAM backbuffer are not processed until the RAM backbuffer is up to date, and any flushes from the backbuffer are not processed until the backbuffer is up to date. There's a lot of locking intracacy to ensure this level of consistancy.

The basic syncronization operation is accomplished by the flush function, which is the function loaded on the xpriv flush member hook. The flush hook function is called:

1

When the mansync helper decides it is time to refresh the screen.

2

After a primitive, if the visual is in syncronous rendering mode.

3

When an expose or graphicsexpose event is sent from the server. This means the server has discarded data that was concealed by another window or by the edge of the screen, and the data must be resent from the client.

again by the client. In the first two cases only the dirty area is sent, except when the application is holding the directbuffer writing resource, in which case the whole area must be synced because there is no way for the target to tell what the user has modified. Holding the directbuffer write resource open when the display is in syncronous mode or when also sending primitives will result in bad perfomance. There's no reason to do so on any target, so don't.

Unfortunately some XFree86 drivers are buggy, and when you render an accelerated primitive which overlaps an area which is not visible to the user, the driver fails to update the backing store (it only draws the clipped primitive using accelarated functions and does not complete the job by calling the software renderer to update the backing store.) Most people will not be affected by this bug, however.

The new X target implements gammamap (DirectColor), unlike the old targets.

The new X target is best used with backing store turned on in the server. When backing store is not turned on, primitives which are clipped to the visual area but still in the virtual area may be slower then the old target, since data will be sent to the server hoping it will be stored in the backing store. Likewise when a full-screen flush occurrs the entire virtual area data is sent. The target could be optimized not to send this data when it detects that there is no backing store available in the server.

Either the RAM backbuffer or the X primitives can be disabled via target options, which will cause emulation of the old X (-noaccel) and Xlib (-nobuffer) targets, with a couple of notable exceptions:

The old X and Xlib targets opened a window and drew directly into it. The old Xlib target did not implement support for ggiSetOrigin. As noted above the old X target used a hack that didn't cost much when compared to the cost of syncing the backbuffer periodically. The new target implements ggiSetOrigin by creating a parent window, then creating a child window inside the parent window. Thus the child window can be moved around inside the parent window, and the parent window will clip the displayed data to the right size. This is much more efficient than the old way when the server is keeping a backing store (which it sometimes does "in secret" even when the backing store functionality in the server is turned off.)

Unfortunately many window managers seem to be buggy, and do not install the colormap of a child window when a mouse enters it. This causes palette and gammamap to be messed up. Since so many windowmanagers fail to implement the behavior described in the Xlib manpages, a workaround needs to be added which will not use the child window (this part is easy enough since the -inwin=root option already implements a child-less rendering) and either disables ggiSetOrigin support, or uses a better version of the old display-x target's creative blitting to emulate setorigin support. LibGGIMISC's splitline support for the original X display was broken by the new child-window stuff as well. In order to implement splitline support, libggimisc must implement a new set of primitives for the new display X that uses two child windows to produce the splitline effect. This complicates a lot of the primitives, so the code is best isolated in LibGGIMISC so any bugs or performance issues in it do not affect vanilla LibGGI users who have no need for splitline. It would probably be best if the special renderers were only loaded on the first call to ggiSetSplitline, so that when LibGGIMISC implements support for the XSync extension, users who are not using splitline do not pay a performance penalty for using XSync.

The child window may also be to blame for the fact that a window which is focused, but not moused over, stops receiving keyboard events. Reworking the X input target to take it's keyboard events from the parent window instead of the child window (mouse and expose/graphicsexpose events must still come from the child window) would be the needed fix.

The new target tries to remove dl dependencies by creating a separate module file for any X extensions used. Because of some deficiencies in the X module system (there is no way to cleanly unload a module) some kludges have had to be made when a module is loaded but gleaned to be nonpresent, then unloaded. This won't effect most people.

However, a more common problem will be seen because X does not give us any way to determine if the XSHM extension will work -- it tells us whether the server has XSHM, but it does not tell us whether the client and server can share memory segments. Thus, when running a remote client, it may be necessary to manually disable XSHM support with the -noshm target option.

Anyway, I hope this is helpful to any intrepid soul which decides to fondle this code :-) (Brian S. Julin)

## FEATURES

- DirectBuffer always available.

- Accelerated

- Multiple frames except for root window

- Panning except for root window

- Support Gammamap


ggidev-triple-int

title: ggidev-triple-int(7)

text:
# ggidev-triple-int(7)

## NAME
ggidev-triple-int : triple-int General Information

## SYNOPSIS

```
#include <ggi/internal/triple-int.h>
```

## DESCRIPTION
triple-int is a collection of math routines that operates on an array of 3 unsigned integers, treating them as a single integer with triple precision.

triple-int uses a 2-complement representation for negative values.

The most significant part of the triple-int is stored at the highest index in the array representation.

A triple-int is typically declared as follows:

```
unsigned x[3];
```

Don't let the above unsigned keyword fool you, all the routines operate as if the triple-int is signed.

## SEE ALSO
ggidev-assign_3(3), ggidev-assign_int_3(3), ggidev-assign_unsigned_3(3), ggidev-sign_3(3), ggidev-bits_3(3), ggidev-eq0_3(3), ggidev-gt0_3(3), ggidev-ge0_3(3), ggidev-lt0_3(3), ggidev-le0_3(3), ggidev-eq_3(3), ggidev-ge_3(3), ggidev-invert_3(3), ggidev-lshift_3(3), ggidev-rshift_3(3), ggidev-inc_3(3), ggidev-dec_3(3), ggidev-negate_3(3), ggidev-abs_3(3), ggidev-add_3(3), ggidev-sub_3(3), ggidev-mul_3(3), ggidev-divmod_3(3)


libggi

title: libggi(7)

text:
# libggi(7)

## NAME
libggi : A fast, simple, small and flexible user-space graphics library

## DESCRIPTION
LibGGI is a fast, simple, small and flexible user-space graphics library developed by the GGI Project. It attempts to abstract the many different graphics output systems existing under Unix (and in the future, other platforms). The support for all of these different types of displays and hardware are provided by dynamically-loaded mini-libraries. LibGGI can transparently (to the LibGGI-using application) display graphics on an X window, under SVGAlib, fbcon (Linux framebuffer driver), or the glide library, through their respective graphics drivers, or targets. There are also some other targets which display through another target, such as multi to display simultaneously on multiple displays at once, and tile to tile your display to different monitors.

LibGGI supports acceleration of graphics primitives where possible.

LibGGI is a very generic piece of software, that will run on about every platform that has remotely heard of POSIX (ports to other systems such as Win32 are available, too) and on many display subsystems.

## ENVIRONMENT VARIABLES
The following outlines the environment variables, intended for the user, which affect the behaviour of LibGGI:

DISPLAY

If set, LibGGI assumes that you want to use the X target. This setting is overridden by the GGI_DISPLAY variable.

GGI_DISPLAY

Specifies the default target used when the application calls ggiOpen(3) with NULL argument. The default target is specified using a target-spec: target:targetargs where target is the name of the target, and targetargs are any target-specific arguments.

If neither this variable nor DISPLAY is set, then the following targets are tried in order until one works: fbdev, svga, aa

GGI_INPUT_target_n, GGI_INPUT_target, GGI_INPUT

GGI_INPUT_target specifies extra LibGII input sources and/or filters for visuals using target Multiple inputs can be specified by enclosing each input-spec in parentheses and separating them with semicolons: (i1):(i2):...

The inputs specified by GGI_INPUT_target_n are only opened at the n'th call of ggiOpen(3). This is used for misbehaving applications that do not allow the user to specify inputs for the different targets that it opens.

The GGI_INPUT variable specifies input settings for all other targets not specified using the other two variable forms.

GGI_DEFMODE

Specifies the default mode, which is used for mode negotiation with LibGGI applications. Specifically, when GGI_AUTO or GT_AUTO are specified in a mode setting call they will be replaced with values from GGI_DEFMODE before calling the target's own ggiSetMode(3) implementation. The format is: (all on one line) S w x h x depth V w x h D w x h F frames [scheme depth size] Anything and everything can be omitted, except tokens indicating what the next token is.

Any omitted values default to GGI_AUTO (or GT_AUTO for the graphtype). Whitespace and '.' symbols are ignored. Character tokens are case-insensitive. If certain values are not possible, they are overridden by the target.

S

Denotes the visible size of the visual. Totally optional, as dimensions without a specifier are considered to be the visible dimensions. w and h are the width and height in pixels.

V

Denotes virtual size, the total drawing area available to the application. The virtual size must be equal or greater than the visible size.

D

Denotes the number of dots per pixel. For graphic modes, this is always 1x1, and for text modes, this is the size of the character cell.

F

Denotes number of frames available to the application. Applications can switch between different frames for double-buffering, etc.

[]

Delimits the graphic type.

scheme

One of:

- C : GT_TRUECOLOR

- P : GT_PALETTE

- K : GT_GREYSCALE

- T : GT_TEXT

depth

Pixel depth in number of bits.

size

Size of pixel in number of bits, including padding.

Instead of scheme, depth, size, it is also possible to specify the graphtype by using one of the following:

- GT_1BIT

- GT_2BIT

- GT_4BIT

- GT_8BIT

- GT_15BIT

- GT_16BIT

- GT_24BIT

- GT_32BIT

- GT_TEXT16

- GT_TEXT32

GGI_DEBUG

The debugging level for LibGGI:

0 or unset

debug output is off; debugging is off

255

all debug output is on

You may also bitwise-or any of the following together:

- 2 : debug core

- 4 : debug mode setting

- 8 : debug color handling

- 16 : debug drawing

- 32 : misc debugging output

- 64 : debug dynamic library handling

- 128 : debug event handling

The debugging output can be quite verbose and in most cases you should redirect stderr so that it does not interfere with your program's output.

GGI_DEBUGSYNC

Turn on synchronous debugging output, flushing the output buffers before returning from DPRINT calls.

GGI_CONFDIR

Override compiled-in path to global config files (Win32 only, but not Cygwin).

GGI_NEWVT

If set, causes a new virtual console to be allocated for some Linux-console-based targets (currently fbdev and glide).

GGI_MANSYNC_FPS

This variable specifies the framerate for targets emulating synchronous mode. The default is 20fps. If you are experiencing problems with the X target over relatively slow remote connections it might be due to connection overload. You might want to try with a lower GGI_MANSYNC_FPS setting.

## EXAMPLES
Example GGI_DISPLAY settings:

```
# see ASCII art flying GGIs
$ GGI_DISPLAY=aa ./flying_ggis
# see demo on both machine "crono" next door and local
# X at the same time
$ GGI_DISPLAY=multi:(Xlib:crono:0.0):(X::0.0) ./demo
```

Example GGI_INPUT string:

```
$ export GGI_INPUT=linux-mouse:auto
# for "multi" target only
$ export GGI_INPUT_multi=linux-mouse:auto
```

Examples of GGI_DEFMODE strings:

- 640x480 : just the visible size

- 640x480#640x960 : same size, but double-height virtual screen

- #1024x768 : only virtual size defined

- 80x40[T] : (default-fontsized) text mode with 80x40 characters

- #x100[T] : text mode with 100 virtual lines

- 640x400[8] : 640x400 at 8 bits per pixel

- 640x480[GT_8BIT] : same as above, but palettized

- 320x200[C15] : 320x200 with 32768 colors (hicolor)

- 320x200[C/16] : 320x200 with 16-bit pixels (also hicolor)

- 320x200[C24/32], 320x200[GT_32BIT] : 320x200, with 32-bit pixels for 16777216 colors (truecolor)

- 640x480F2[GT_16BIT] : 16-bit-color 640x480 with two buffers

## SEE ALSO
libgii(7), ggiInit(3), display-aa(7), display-directx(7), display-fbdev(7), display-file(7), display-glide(7), display-macosx(7), display-memory(7), display-monotext(7), display-multi(7), display-palemu(7), display-sub(7), display-svgalib(7), display-tele(7), display-tile(7), display-trueemu(7), display-vcsa(7), display-vgl(7), display-x(7)


giflib

package: libgif-devel

title: giflib(7)

summary: GIFLIB utilities

text:
# giflib(7)

## NAME
giflib - GIFLIB utilities

## DESCRIPTION
GIFLIB is a linkable service library and a set of utilities for processing images encoded using GIF (Graphics Interchange Format).

These utilities are not intended to compete with or replace multi-format graphics toolkits like ImageMagick or the Python Imaging Library, or graphics editors such as the GIMP. Find one of those, or an equivalent, if you need to crop, scale, rotate, toggle interlacing, or perform other conventional image transformations. Rather, these are intended to facilitate GIF-specific operations which multi-format tools may not adequately support.

API documentation for the service library is best viewed through a browser at the project website: http://sourceforge.net/projects/giflib/?source=directory.

## SEE ALSO
gifbuild(1), giffix(1), giftext(1), giftool(1), gifclrmap(1).

## AUTHORS
Gershon Elber, Eric S. Raymond, Toshio Kuratomi.


filter-key

package: libgii

title: filter-key(7)

text:
# filter-key(7)

## NAME
filter-key, filter-keytrans : Generic key event translator

## SYNOPSIS

```
filter-key: [<file>]
filter-keytrans: [<file>]
```

## DESCRIPTION
This filter translates key events according to a set of translation rules. This can be used to remap a keyboard.

## OPTIONS
file

The name of the configuration file. If none given, the filter will first look for the file filter/keytrans in the user GGI directory ($HOME/.ggi/ on UNIX), then in the base GGI directory if not found.

## CONFIGURATION
The mapping is specified through a simple text file, each line being a translation rule. A line starting with a # is a comment. Each line must contain 10 values in the following order:

modifier_mask

Consider only the bits set here.

modifier_value

The bits set above must match this value.

button_in, label_in, symbol_in

If this is not KEY_UNMAPPED==0xffff, the button/label/symbol of the incoming key must match these fields.

modifier_changemask

Change these bits from the original modifiers...

modifier_ormask

button_out, label_out, symbol_out

The data that is then sent by the keymapper. Any fields set to KEY_UNMAPPED==0xffff will be copied from the incoming event.

## EXAMPLE
Mapping a symbol:

```
# Take any key that produces a symbol of 0x41 ('A') map it to ESC
#
# modmsk modval buttin lablin symin  modchg modor  butout labout symout
0x0000 0x0000 0xffff 0xffff 0x0041 0x0000 0x0000 0xffff 0xffff 0x001b
```


filter-mouse

title: filter-mouse(7)

text:
# filter-mouse(7)

## NAME
filter-mouse : Generic mouse event translator

## SYNOPSIS

```
filter-mouse: [<file>]
```

## DESCRIPTION
This filter translates mouse events according to a set of translation rules.

## OPTIONS
file

The name of the configuration file. If none given, the filter will first look for the file filter/mouse in the user GGI directory ($HOME/.ggi/ on UNIX), then in the base GGI directory if not found.

## CONFIGURATION
The translation rules are specified through a simple text file. The following example gives a good idea of the mouse filter usage. A # marks the rest of the line as a comment.

## EXAMPLE
A set of mouse translation rules:

```
# Syntax is:
# incoming-type [type-specifics] TO outgoing type [type-specifics]
#
# Simulated mouse buttons on the keyboard
#
#KEY modmask modvalue button label  symbol TO BUT buttonnumber
KEY 0x0004  0x0004   0xffff 0x000d 0xffff TO BUT 1            # Alt-Enter
KEY 0x0004  0x0004   0xffff 0x0020 0xffff TO BUT 2            # Alt-Space
KEY 0x0004  0x0004   0xffff 0x0008 0xffff TO BUT 3            # Alt-BackSpace
#
# Keyboard-Mouse on the Cursors
#
#KEY modmask modval button label  symbol TO REL axis value
KEY 0x0004  0x0004 0xffff 0xe034 0xffff TO REL X    -5        # Alt-Left
KEY 0x0004  0x0004 0xffff 0xe035 0xffff TO REL X     5        # Alt-Right
KEY 0x0004  0x0004 0xffff 0xe032 0xffff TO REL Y    -5        # Alt-Up
KEY 0x0004  0x0004 0xffff 0xe033 0xffff TO REL Y     5        # Alt-Down
#
# Keyboard mouse on the Numpad
#
KEY 0x0004 0x0004 0xffff 0xe231 0xffff TO REL X -5    # Alt-Num1
KEY 0x0004 0x0004 0xffff 0xe231 0xffff TO REL Y  5    # Alt-Num1
KEY 0x0004 0x0004 0xffff 0xe232 0xffff TO REL Y  5    # Alt-Num2
KEY 0x0004 0x0004 0xffff 0xe233 0xffff TO REL X  5    # Alt-Num3
KEY 0x0004 0x0004 0xffff 0xe233 0xffff TO REL Y  5    # Alt-Num3
KEY 0x0004 0x0004 0xffff 0xe234 0xffff TO REL X -5    # Alt-Num4
KEY 0x0004 0x0004 0xffff 0xe235 0xffff TO BUT 1               # Alt-Num5 - Button
KEY 0x0004 0x0004 0xffff 0xe236 0xffff TO REL X  5    # Alt-Num6
KEY 0x0004 0x0004 0xffff 0xe237 0xffff TO REL X -5    # Alt-Num7
KEY 0x0004 0x0004 0xffff 0xe237 0xffff TO REL Y -5    # Alt-Num7
KEY 0x0004 0x0004 0xffff 0xe238 0xffff TO REL Y -5    # Alt-Num8
KEY 0x0004 0x0004 0xffff 0xe239 0xffff TO REL X  5    # Alt-Num9
KEY 0x0004 0x0004 0xffff 0xe239 0xffff TO REL Y -5    # Alt-Num9
#
# Home the cursor ...
#
KEY 0x0004 0x0004 0xffff 0xE038 0xffff TO ABS X 0     # Alt-Home
KEY 0x0004 0x0004 0xffff 0xE038 0xffff TO ABS Y 0     # Alt-Home
#
# Invert mouse axis
#
#REL modmsk modval axis TO REL axis multiplier
REL 0x0004 0x0004 X    TO REL Y    -1
REL 0x0004 0x0004 Y    TO REL X    -1
#
# Accelerate mouse
#
#                             multiplier treshold higher-speed
REL 0x0004 0x0004 X TO REL X 1          5        4
REL 0x0004 0x0004 Y TO REL Y 1          5        4
#
#
# Invert mouse buttons
BUT 0x0004 0x0004 1 TO BUT 2
BUT 0x0004 0x0004 2 TO BUT 1
```


filter-save

title: filter-save(7)

text:
# filter-save(7)

## NAME
filter-save : Event saver

## SYNOPSIS

```
filter-save: [<file>]
filter-save: |[cmd]
```

## DESCRIPTION
filter-save writes all events to a file. This can be useful to repeat the same event flow later.

## OPTIONS
file

Name of the destination file; the default is the standard output.

cmd

If the specified name starts with a |, the following string is executed as a command and the filter output is piped into the new process' stdin.

## SEE ALSO
input-file(7)


filter-tcp

title: filter-tcp(7)

text:
# filter-tcp(7)

## NAME
filter-tcp : TCP/IP event repeater

## SYNOPSIS

```
filter-tcp: <host>:<port>
```

## DESCRIPTION
This filter send all events on a TCP socket.

## OPTIONS
host

The name of the host to connect to. If it is set to listen, the filter will instead wait for a TCP connection.

port

The port number to connect to on the remote host. If the filter is waiting for a connection, this is the port number on which it listens.

## SEE ALSO
input-tcp(7)


input-directx

title: input-directx(7)

text:
# input-directx(7)

## NAME
input-directx : Win32 DirectX input

## SYSNOPSIS

```
input-directx
```

## DESCRIPTION
Used for Win32 DirectX port of libGGI. This target cannot be used without the DirectX display target, which loads this automatically.

DirectX 7 is required.

## FEATURES

- Generates evPtr* events, but not evPtrRelative by default. Use:

```
ggiAddEventMask(vis, emPtrRelative);
```

to get them.

- Generates evKey* events. Key repeat messages are generated at the keyboard rate and keyboard delay specified in the keyboard control panel by emulating what Windows does. Dead keys work almost as expected (see the Bugs section below).

- Game controllers with absolute axes. The DirectX Point-Of-View (POV) control type is mapped to an axis (indicating the current direction of the POV control) and a button indicating if the POV control is currently in that direction or if it is centered with no direction at all. The long name of the POV axis is POV x (btn y) where btn y indicates what button is connected to POV x.

## BUGS

- When using relative pointer motion evPtrRelative, suming up the values from the correct (albeit unknown) starting point is not equivalent to using absolute pointer motion evPtrAbsolute. Use absolute pointer motion (the default) if you want to keep in sync with the on screen cursor.

- When pressing a dead key, the next key should sometimes not emit an emulated key press for the dead key. E.g. a dead tilde (~) followed by a cursor key should not emit an emulated tilde. It should try to combine the dead tilde with the key following the cursor key (e.g. n, to make a ntilde), in order to match what Windows does.

- The system keyboard device always reports 256 keys, which is obviously not always correct.

- It is not possible to not open game controllers, which wastes system resources should the application not be interested into them.


input-file

title: input-file(7)

text:
# input-file(7)

## NAME
input-file : File input

## SYNOPSIS

```
input-file: [<file>]
input-file: |[cmd]
```

## DESCRIPTION
Reads and generates events from a file such as one created by filter-save(7).

## OPTIONS
file

The file events are read from. The standard input is used by default.

cmd

If the file name starts with a |, it is interpreted as a command which is run. The process stdout is used as input file for input-file.

## SEE ALSO
filter-save(7)


input-linux-evdev

title: input-linux-evdev(7)

text:
# input-linux-evdev(7)

## NAME
input-linux-evdev : Linux event interface input

## SYNOPSIS

```
input-linux-evdev: [<device>]
```

## DESCRIPTION
Reads events from the Linux event interface (/dev/input/eventX) and converts them to LibGII events.

## OPTIONS
device

Specifies the device to use, the default is /dev/input/event0.

## BUGS/TODO

- Key repeat messages are not sent, which can annoy users who want to use the cursor keys.

- Handles setting of keyclick and bell, which can also annoy users.


input-linux-kbd

title: input-linux-kbd(7)

text:
# input-linux-kbd(7)

## NAME
input-linux-kbd : Linux console keyboard input

## SYNOPSIS

```
input-linux-kbd: [<device>]
```

## DESCRIPTION
input-linux-kbd puts the Linux console into mediumraw mode and reads keyboard events from it.

## OPTIONS
device

Names the tty to open; the default is /dev/tty.

## ENVIRONMENT VARIABLES
GII_CTRLALT_VTSWITCH

If set, the key combination to switch VTs is Ctrl-Alt-Fn. Otherwise Alt-Fn is used.

## FEATURES
•

Generates evKey* events.


input-linux-mouse

title: input-linux-mouse(7)

text:
# input-linux-mouse(7)

## NAME
input-linux-mouse : Direct mouse input

## SYNOPSIS

```
input-linux-mouse: [<mousetype>] [,<file>] [,[b<bauds>][r<rts>][d<dtr>]]
```

## DESCRIPTION
This input opens a file (usually a device file or pipe) and reads mouse protocol data from it.

## OPTIONS
mousetype

Indicates what type of mouse is attached. The following types are supported:

- ms, Microsoft : Two button Microsoft compatible mice.

- ms3, IntelliMouse, mman+ : Serial Intellimouse or compatible. Supports four buttons for mice like the Logitech MouseMan+.

- MouseSystems, msc : MouseSystems compatible (used in most 3-button mice).

- Logitech, logi : Used in older Logitech serial mice.

- mm, MMSeries : MM series mice.

- Sun : Sun mice. The protocol is the same as 'msc' protocol except it used only 3 bytes per packet.

- MouseMan, mman : MouseMan protocol.

- BusMouse, bm : Non-PS/2 busmice.

- LinuxUSB, lnxusb : IMPS2 that doesn't choke on USB (no init attempted).

- ps2, PS/2 : PS/2 mice (most non-serial mice use this protocol)

- imps2, IMPS/2 : PS/2 IntelliMouse and compatible (not USB, see lnxusb for that.)

- mmanps2, MouseManPlusPS/2 : PS/2 Logitech MouseMan+ and compatible.

Most of the strings supported by GPM, SVGAlib and XFree can be specified. If you find one that isn't, please report.

The special value auto tells input-linux-mouse to read ~/.ggi/input/linux-mouse, and if that fails, $sysconfdir/ggi/input/linux-mouse. If none of the two files are found, input-linux-mouse tries to auto-detect the mouse, and as a last resort uses the mouse information specified in /etc/vga/libvga.config.

file

The file to read mouse protocol data from; defaults to /dev/mouse.

baud

Baud rate of mouse device.

rts

Turns off RTS if set to 0; turns RTS on if set to a number greater than 0.

dtr

Turns off DTR if set to 0; turns DTR on if set to a number greater than 0.

## FEATURES
•

Generates evPtr* events.

## FILES
~/.ggi/input/linux-mouse and $sysconfdir/ggi/input/linux-mouse consists of the following entries:

```
mouse mousetype
mdev file
```

where mousetype and file has the same semantics as the invocation options of the same names.


title: input-lk201(7)

text:
# input-lk201(7)

## NAME
input-lk201 : LK201/LK401 keyboard input

## SYNOPSIS

```
input-lk201: [<file>]
```

## DESCRIPTION
The lk201 and lk401 devices are keyboards made by Digital Equipment Corporation for some of there older micro computer systems and terminals.

They connect via a 4 pin RJ connector, which carries 11.8V (+/- 6%), GND, and two bidirectional async RS423 (RS232 Compatible) serial lines, which are Receive and Transmit. The pins are as follows (looking on to the male (lk201 side) connector):

```
 -------------------
| "    "    "    "  |
| L    V    G    D  |
| K    +    N    E  |
| ->        D    C  |
| D             ->  |
| E              L  |
| C              K  |

 --               --

   |             |

    --         --

      |       |

       -------
```

## OPTIONS
file

Specifies the serial port device to use (e.g. /dev/ttyS1). If this argument is not specified as part of the input's arguments, then the device named in the environment variable GII_LK201_OPTIONS is used.

## ENVIRONMENT VARIABLES
GII_LK201_OPTIONS

File name of serial port.

## FEATURES
•

Generates evKey* events.

## KNOWN BUGS

- key repeat messages are not sent, which can annoy users who want to use the cursor keys.

- Handle setting of keyclick and bell, which can also annoy users.


input-mouse

title: input-mouse(7)

text:
# input-mouse(7)

## NAME
input-mouse : Read mouse protocol data from file

## SYNOPSIS

```
input-mouse: <fd>:<proto>
```

## DESCRIPTION
input-mouse reads mouse protocol data from the specified file descriptor. This input is mainly designed to be opened automatically by input-linux-mouse(7), but can also be used stand alone.

## OPTIONS
fd

Specifies the file descriptor to read from.

proto

Specifies the mouse protocol to use. This argument takes the same values as mousetypes in input-linux-mouse(7), except auto-detection is not supported.

## FEATURES
•

Generates evPtr* events.

## SEE ALSO
input-linux-mouse(7)


input-quartz

title: input-quartz(7)

text:
# input-quartz(7)

## NAME
input-quartz : MacOSX Quartz/Carbon Input

## SYNOPSIS

```
input-quartz
```

## DESCRIPTION
input-quartz, a native input library for MacOSX. It uses the quartz/carbon API. It is used by display-quartz(7) and not standalone usable.

MacOSX 10.2.8 (Jaguar) or newer is required.

## FEATURES
•

Generates evPtr* and evKey* events.


input-tcp

title: input-tcp(7)

text:
# input-tcp(7)

## NAME
input-tcp : TCP event filter input

## SYNOPSIS

```
input-tcp: <host>:<port>
```

## DESCRIPTION
Reads events from a TCP-socket who's peer end is the filter-tcp filter, also included in LibGII. The filter-tcp filter takes the same arguments as the tcp inputlib, and anyone of the sublibs can be the listening end.

## OPTIONS
host

The hostname to connect to. If this is set to listen the sublib will enter listening mode and wait for the corresponding sublib to connect.

port

Specifies the port to connect to/listen on.

## SEE ALSO
filter-tcp(7)


input-x

title: input-x(7)

text:
# input-x(7)

## NAME
input-x : X11 standalone input

## SYNOPSIS

```
input-x [-nokeyfocus]
input-xwin
input-xf86dga
```

## DESCRIPTION
input-x and input-xwin, an input target for X11 Environments. input-x opens a X11 window to receive input from and works standalone.

input-xwin and input-xf86dga is used by libggi's display-x(7). They are NOT intended to be directly used by applications.

X11R5 is required.

## OPTIONS
-nokeyfocus

Disables keyboard focus. See the XSetInputFocus(3X11) manpage for the details on keyboard focus, where focus is a 'window' and revert_to is 'RevertToParent'.


libgg

title: libgg(7)

text:
# libgg(7)

## NAME
libgg : Handy, portable wrappers for several basic OS features

## DESCRIPTION
LibGG provides a portable, unified interface to various very basic operating system features, making it easy to write portable programs without locking the author into a restricted, bloated, or overbearing development paradigm. By abstracting the most commonly used functionality in an operating-system-independent fashion, relying on prepackaged LibGG distributions can also can reduce the complexity involved in maintaining a portability suite (e.g. autotools) for the application's development.

Originally LibGG came into being as part of the GGI Project, when LibGII input functionality was separated from LibGGI into a stand-alone library, and a place was needed to put functions needed by both libraries. (Since then, we have forgotten what "GG" stood for, so don't ask.)

The master upstream source of LibGG is still distributed as part of LibGII, however it is itself a separately-distributable stand-alone package of utilities that can be very useful to applications developers.

LibGG provides the following groups of functions and/or macros. Some may not be possible to implement on some operating systems, some may be possible, just nobody has done so yet. We try to make them all available where we can find the time and expertise:

Time functions (ggCurTime(3), ggUSleep(3) and ggUSlumber(3)) to handle high-resolution timing and delays without busy-looping.

Cleanup callbacks (ggRegisterCleanup(3), ggUnregisterCleanup(3), ggCleanupForceExit(3)) to allow your application to perform emergency actions before a program is terminated abnormally.

Timer callbacks (ggAddTask(3), ggDelTask(3), ggTimeBase(3)) provide a (non-realtime) wall-clock periodic/one-shot callback scheduler that can be shared between many different areas of the application code without fear of interference.

Locking Functions (ggLock(3), ggLockCreate(3), ggLockDestroy(3), ggTryLock(3), ggUnlock(3)) which are thread-safe in threaded environments.

System and CPU detection utilities (ggGetSwarType(3), GG_HAVE_INT64, GG_LITTLE_ENDIAN) to allow you to detect CPU endianness and the presence of features such as SWAR (SIMD) instruction sets (e.g. MMX), and to turn on/off or change SWARs for testing or as a workaround.

Very basic overrun-proof string operations (ggstrlcpy(3), ggstrlcat(3)) which are a horrible mess for cross-platform programs to map to OS-local string functions/headers.

Dynamic symbol management functions (ggGetScope(3), ggDelScope(3), ggFromScope(3), ggNewScope(3)) allows you to create a plug-in system where code is either dynamically loaded into and out of your program, or statically linked in the library or program.

An option parser (ggParseOpts, ggSystemOpts) and plugin configuration system (ggGetUserDir(3), ggParseTarget, ggLoadConfig(3), ggFreeConfig(3), ggMatchConfig, ggConfigExpandAlias) which are by-products of the pluggable module support but can be useful for other things if you like the format.

LibGG provides a few additionnal tools that are used internaly, for other GGI libraries and that can also be useful to the application programmer: macros for managing data structures such as lists, queues, trees, a simple iterator scheme. These features are mostly macro-based.

## ENVIRONMENT VARIABLE:
The following outlines the environment variables, intended for the user, which affect the behaviour of LibGG:

GG_OPTS

LibGG uses the environment variable GG_OPTS, and expects it to contain a valid option string as documented in the manpage for ggParseOpts. The available options are documented along with the LibGG API functions which they most affect.

GG_DEBUG

The debug level for LibGII:

- 0 or unset : debug output is off; debugging is off

- 255 : all debug output is on

You may also bitwise 'or' any of the following together:

- 2 : debug core

- 4 : misc debugging output

- 8 : debug locking code

- 16 : debug task subsystem

- 32 : debug scope code (dynamic library and symbol lookup)

- 64 : debug api code (not there yet)

GG_DEBUGSYNC

Turn on synchronous debug output, flushing the output buffers before returning from DPRINT calls.

## RESERVED SIGNAL:
LibGG requires the exclusive use of one signal under certain environments. This signal defaults to SIGPROF, where available, but may be configured through the GG_OPTS option -signum=n where n represents the numerical value of the signal to use. This signal should not be one of the fatal signals handled by the LibGG cleanup facilities, and must be a signal onto which a handler may be assigned. Applications should not install handlers or alter the signal handler in any way for this signal.

## BUGS:
There is still some legacy to LibGGI in some of the namespace, especially GGI_LITTLE_ENDIAN is currently the real name for GG_LITTLE_ENDIAN, which is an unofficial new addition destined to replace it. Deprecation will take a few revisions as it must be done in an orderly fashion.

Likewise the header file is included as <ggi/gg.h> but we will probably keep that as-is because of the way LibGG is distributed and to avoid adding more clutter in system include directories than is necessary.

Several features are incomplete, for example, code is still needed to detect SWAR on many of the more obscure architectures.


libgii

title: libgii(7)

text:
# libgii(7)

## NAME
libgii : A flexible library for input handling

## DESCRIPTION
LibGII is an input library developed by the GGI Project. Its design philosophy is similar to LibGGI, which deals with graphics output. LibGII is based on the concept of input streams, which virtualize access to the underlying input drivers. Events from various input devices are abstracted into easy-to-use structures. LibGII also allows the application to join streams together, receiving input from an arbitrary combination of devices.

LibGII is a separate component from LibGGI, although LibGGI depends on LibGII for input purposes. (LibGGI's input functions are simply wrappers for LibGII functions.)

## ENVIRONMENT VARIABLES
The following outlines the environment variables, intended for the user, which affect the behaviour of LibGII:

GII_INPUT

The default input source(s) and/or filter(s) to use when giiOpen() is called with a NULL argument. The format is: input:inputargs. Multiple inputs can be specified by this notation: (i1):(i2) ....

Note: This setting does not affect LibGGI visuals automatically opening inputs. Use the GGI_INPUTx variable instead.

GII_DEBUG

The debug level for LibGII:

- 0 or unset : debug output is off; debugging is off

- 255 : all debug output is on

You may also bitwise 'or' any of the following together:

- 2 : debug core

- 32 : misc debugging output

- 64 : debug dynamic library handling

- 128 : debug event handling

GII_DEBUGSYNC

Turn on synchronous debug output, flushing the output buffers before returning from DPRINT calls.

GII_CONFDIR

Override compiled-in path to global config files (Win32 only, but not Cygwin).

Other environment variables specific to filters and inputs are documented in the corresponding manual page.

## SEE ALSO
libgii.conf(5), filter-keytrans(7), filter-mouse(7), filter-save(7), filter-tcp(7), input-directx(7), input-linux-kbd(7), input-mouse(7), input-file(7), input-linux-mouse(7), input-tcp(7), input-linux-evdev(7), input-lk201(7).


gnome-options

package: libgnome

title: gnome-options(7)

text:
# gnome-options(7)

## NAME
gnome-options - Standard Command Line Options for GNOME 2 Programs

## SYNOPSIS
program [standard options] [specific options] arguments

## DESCRIPTION
This manual page describes the command line options, which are common to all Gnome applications.

## OPTIONS

### Help options
-?, --help

Show the applications help message.

--usage

Display a brief usage message.

--version

Show the applications's version information.

### Bonobo Activation support
--oaf-ior-fd=FD

File descriptor to print IOR on

--oaf-activate-iid=IID

IID to activate

--oaf-private

Prevent registering of server with OAF

### GNOME library options
--disable-sound

Disable sound server usage

--enable-sound

Enable sound server usage

--espeaker=HOSTNAME:PORT

Host:port on which the esd sound server to use is running. This is useful if you simultaneously run programs on several machines.

### GNOME GUI options
--disable-crash-dialog

Disable the crash dialog, which is normally shown when the application segfaults.

### Session management options
--sm-client-id=ID

Specify session management ID. Only used by the session manager itself while restarting the application.

--sm-config-prefix=PREFIX

Specify prefix of saved configuration.

--sm-disable

Disable connection to session manager.

### Other options
--load-modules=MODULE1,MODULE2,...

Dynamic modules to load

## SEE ALSO
For most GNOME programs there will be additional command line options, which are specific to the program. These will be explained in the Application options section of the --help output and in the application's online help.

## AUTHOR
This manual page was written by Jochen Voss <voss@debian.org>. A first version was generated with the help of the help2man program. The program's output was manually edited later.


libhugetlbfs

package: libhugetlbfs

title: libhugetlbfs(7)

text:
# libhugetlbfs(7)

## NAME
libhugetlbfs - preload library to back text, data, malloc() or shared memory with hugepages

## SYNOPSIS
export [environment options]

[LD_PRELOAD=libhugetlbfs.so] target_application

## DESCRIPTION
libhugetlbfs is a library that can back application text, data, malloc() and shared memory with hugepages. This is of benefit to applications that use large amounts of address space and suffer a performance hit due to TLB misses. Wall-clock time or oprofile can be used to determine if there is a performance benefit from using libhugetlbfs or not. In all cases but shared memory, a hugetlbfs mount must exist and a hugepage pool defined for hugepages to be used.

Some limited functionality is available for unmodified dynamically linked applications. By preloading the library, the library can back malloc() and shared memory, and text and data segments can be partially backed if they are large enough.

For the effective backing of text and data with huge pages, the application must be linked to the library and the ELF segments correctly aligned using the ld helpers. Once linked, malloc or shared memory can still be backed but no pre-loading is required. See /usr/share/doc/libhugetlbfs/HOWTO and ld.hugetlbfs(1) for detailed instructions on relinking applications.

For applications that are hugepage-aware and linked to the library get_huge_pages() can be used for the direct allocation of hugepage-backed regions.

Unless otherwise specified, libhugetlbfs will use the default hugepage size to back memory regions. The default size is the value of Hugepagesize displayed in /proc/meminfo. The size can be specified in bytes or in kilobytes, megabytes, or gigabytes by appending K, M, or G respectively. It is an error to specify a invalid, unsupported, or otherwise unconfigured huge page size. Kernel 2.6.27 or later is required to specify any pagesize other than the default.

See /usr/share/docs/libhugetlbfs/HOWTO for detailed instructions on how the library should be used, particularly when relinking the application. This manual page provides a brief synopsis of the environment variables as a quick reference.

The following variables affect what memory regions are backed by hugepages. In all cases, the environment being unset implies the feature should remain disabled.

HUGETLB_DEFAULT_PAGE_SIZE=<pagesize>

This sets the default hugepage size to be used by libhugetlbfs. If not set, libhugetlbfs will use the kernel's default hugepage size.

HUGETLB_MORECORE=[yes|<pagesize>]

This enables the hugepage malloc() feature, instructing libhugetlbfs to override glibc's normal morecore() function with a hugepage version and use it for malloc(). All application malloc() memory should come from hugepage memory until it runs out, it will then fallback to base pages. Note that applications that use custom allocators may not be able to back their heaps using hugepages and this environment variable. It may be necessary to modify the custom allocator to use get_huge_pages().

HUGETLB_SHM=yes

When this environment variable is set, the SHM_HUGETLB flag is added to the shmget() call and the size parameter is aligned to back the shared memory segment with hugepages. In the event hugepages cannot be used, base pages will be used instead and a warning will be printed to explain the failure. The pagesize cannot be specified with this parameter. To change the kernels default hugepage size, use the pagesize= kernel boot parameter (2.6.26 or later required).

HUGETLB_ELFMAP=[no|[R[<=pagesize>]:[W[<=pagesize>]]]

If the application has been relinked (see the HOWTO for instructions), this environment variable determines whether read-only, read-write, both or no segments are backed by hugepages and what pagesize should be used. If the recommended relinking method has been used, then hugeedit can be used to automatically back the text or data by default.

HUGETLB_FORCE_ELFMAP=yes

Force the use of hugepages for text and data segments even if the application has not been relinked to align the ELF segments on a hugepage boundary. Partial segment remapping is not guaranteed to work and the segments must be large enough to contain at least one hugepage for the remapping to occur.

The following options affect how libhugetlbfs behaves.

HUGETLB_RESTRICT_EXE=e1:e2:...:eN

By default, libhugetlbfs will act on any program that it is loaded with, either via LD_PRELOAD or by explicitly linking with -lhugetlbfs. There are situations in which it is desirable to restrict libhugetlbfs' actions to specific programs. For example, some ISV applications are wrapped in a series of scripts that invoke bash, python, and/or perl. It is more convenient to set the environment variables related to libhugetlbfs before invoking the wrapper scripts, yet this has the unintended and undesirable consequence of causing the script interpreters to use and consume hugepages. There is no obvious benefit to causing the script interpreters to use hugepages, and there is a clear disadvantage: fewer hugepages are available to the actual application.

To address this scenario, set HUGETLB_RESTRICT_EXE to a colon-separated list of programs to which the other libhugetlbfs environment variables should apply. (If not set, libhugetlbfs will attempt to apply the requested actions to all programs.) For example,

HUGETLB_RESTRICT_EXE=hpcc:long_hpcc

will restrict libhugetlbfs' actions to programs named /home/fred/hpcc and /bench/long_hpcc but not /bin/hpcc_no.

HUGETLB_MORECORE_SHRINK=yes

By default, the hugepage heap does not shrink. Shrinking is enabled by setting this environment variable. It is disabled by default as glibc occasionally exhibits strange behaviour if it mistakes the heap returned by libhugetlbfs as a foreign brk().

HUGETLB_NO_PREFAULT

By default libhugetlbfs will prefault regions it creates to ensure they can be referenced without receiving a SIGKILL. On kernels older than 2.6.27, this was necessary as the system did not guarantee that future faults would succeed on regions mapped MAP_PRIVATE. Prefaulting impacts the performance of malloc() and can result in poor placement on NUMA systems. If it is known the hugepage pool is large enough to run the application or the kernel is 2.6.27 or later, this environment variable should be set.

HUGETLB_NO_RESERVE=yes

By default, the kernel will reserve huge pages at mmap() time to ensure that future faults will succeed. This avoids unexpected application failure at fault time but some applications depend on memory overcommit to create large sparse mappings. For this type of application, setting this environment variable will create huge page backed mappings without a reservation. Use this option with extreme care as in the event huge pages are not available when the mapping is used, the application will be killed. On older kernels, the use of this feature can trigger the OOM killer. Hence, even with this variable set, reservations may still be used for safety.

HUGETLB_MORECORE_HEAPBASE=address

libhugetlbfs normally picks an address to use as the base of the heap for malloc() automatically. This environment variable fixes which address is used.

HUGETLB_PATH=<path>

The path to the hugetlbfs mount is automatically determined at run-time. In the event there are multiple mounts and the wrong one is being selected, use this option to select the correct one. This may be the case if an application-specific mount with a fixed quota has been created for example.

HUGETLB_SHARE=1

By default, libhugetlbfs uses unlinked hugetlbfs files to store remapped program segment data. If the same program is started multiple times using hugepage segments, multiple hugepages will be used to store the same program data. The reduce this wastage, setting this environment variable will share read-only segments between multiple invocations of a program at the cost of the memory being used whether the applications are running or not. It is also possible that a malicious application inferfere with other applications executable code. See the HOWTO for more detailed information on this topic.

The following options control the verbosity of libhugetlbfs.

HUGETLB_VERBOSE=<level>

The default value for this is 1 and the range of the value is from 0 to 99. The higher the value, the more verbose the output is. 0 is quiet and 3 will output much debugging information.

HUGETLB_DEBUG

Once set, this will give very detailed output on what is happening in the library and run extra diagnostics.

## FILES
[DESTDIR|/usr/share]/doc/libhugetlbfs/HOWTO

## SEE ALSO
oprofile(1), ld.hugetlbfs(1), hugectl(8), hugeedit(8), gethugepagesize(3), gethugepagesizes(3), getpagesizes(3), hugetlbfs_test_path(3), hugetlbfs_find_path(3), hugetlbfs_find_path_for_size(3), hugetlbfs_test_path(3), hugetlbfs_test_path_for_size(3), hugetlbfs_unlinked_fd(3), hugetlbfs_unlinked_fd_for_size(3), get_huge_pages(3), free_huge_pages(3)

## AUTHORS
libhugetlbfs was written by various people on the libhugetlbfs-devel mailing list.


hwloc

package: libhwloc-devel

title: hwloc(7)

text:
# hwloc(7)

## NAME
hwloc - General information about hwloc ("hardware locality").

## DESCRIPTION
hwloc provides command line tools and a C API to obtain the hierarchical map of key computing elements, such as: NUMA memory nodes, shared caches, processor packages, processor cores, and processor "threads". hwloc also gathers various attributes such as cache and memory information, and is portable across a variety of different operating systems and platforms.

### Definitions
hwloc has some specific definitions for terms that are used in this man page and other hwloc documentation.

hwloc CPU set:

A set of processors included in an hwloc object, expressed as a bitmask indexed by the physical numbers of the CPUs (as announced by the OS). The hwloc definition of "CPU set" does not carry any of the same connotations as Linux's "CPU set" (e.g., process affinity, cgroup, etc.).

hwloc node set:

A set of NUMA memory nodes near an hwloc object, expressed as a bitmask indexed by the physical numbers of the NUMA nodes (as announced by the OS).

Linux CPU set:

See http://www.mjmwired.net/kernel/Documentation/cpusets.txt for a discussion of Linux CPU sets. A super-short-ignoring-many-details description (taken from that page) is:

"Cpusets provide a mechanism for assigning a set of CPUs and Memory Nodes to a set of tasks."

Linux Cgroup:

See http://www.mjmwired.net/kernel/Documentation/cgroups.txt for a discussion of Linux control groups. A super-short-ignoring-many-details description (taken from that page) is:

"Control Groups provide a mechanism for aggregating/partitioning sets of tasks, and all their future children, into hierarchical groups with specialized behaviour."

To be clear, hwloc supports all of the above concepts. It is simply worth noting that they are different things.

### Location Specification
Locations refer to specific regions within a topology. Before reading the rest of this man page, it may be useful to read lstopo(1) and/or run lstopo on your machine to see the reported topology tree. Seeing and understanding a topology tree will definitely help in understanding the concepts that are discussed below.

Locations can be specified in multiple ways:

Tuples:

Tuples of hwloc "objects" and associated indexes can be specified in the form object:index. hwloc objects represent types of mapped items (e.g., packages, cores, etc.) in a topology tree; indexes are non-negative integers that specify a unique physical object in a topology tree. Both concepts are described in detail, below. Some filters may be added after the type to further specify which objects are wanted. <type>[subtype=<subtype>] selects objects matching the given type and also its subtype string attribute. For instance NUMA[HBM] selects NUMA nodes of subtype "HBM". The prefix subtype= may be avoided if there is no ambiguity. NUMA[tier=X] selects NUMA nodes of tier <X> ("MemoryTier" info attribute).

Indexes may also be specified as ranges. x-y enumerates from index x to y. x:y enumerates y objects starting from index x (wrapping around the end of the index range if needed). x- enumerates all objects starting from index x. all, odd, and even are also supported for listing all objects, or only those with odd or even indexes.

Chaining multiple tuples together in the more general form object1:index[.object2:index2[...]] is permissable. While the first tuple's object may appear anywhere in the topology, the Nth tuple's object must have a shallower topology depth than the (N+1)th tuple's object. Put simply: as you move right in a tuple chain, objects must go deeper in the topology tree. When using logical indexes (which is the default), indexes specified in chained tuples are relative to the scope of the parent object. For example, "package:0.core:1" refers to the second core in the first package.

When using OS/physical indexes, the first object matching the given index is used.

PCI and OS devices may also be designed using their identifier. For example, "pci=02:03.1" is the PCI device with bus ID "02:03.1". "os=eth0" is the network interface whose software name is "eth0". PCI devices may also be filtered based on their vendor and/or device IDs, for instance "pci[15b3:]:2" for the third Mellanox PCI device (vendor ID 0x15b3). OS devices may also be filtered based on their subtype, for instance "os[gpu]:all" for all GPU OS devices.

Hex:

For tools that manipulate object as sets (e.g. hwloc-calc and hwloc-bind), locations can also be specified as hexidecimal bitmasks prefixed with "0x". Commas must be used to separate the hex digits into blocks of 8, such as "0xffc0140,0x00020110". Leading zeros in each block do not need to be specified. For example, "0xffc0140,0x20110" is equivalent to the prior example, and "0x0000000f" is exactly equivalent to "0xf". Intermediate blocks of 8 digits that are all zeoro can be left empty; "0xff0,,0x13" is equivalent to "0xff0,0x00000000,0x13". If the location is prefixed with the special string "0xf...f", then all unspecified bits are set (as if the set were infinite). For example, "0xf...f,0x1" sets both the first bit and all bits starting with the 33rd. The string "0xf...f" -- with no other specified values -- sets all bits.

"all" and "root" are special locations consisting in the root object in tree. It contains the entire current topology.

Some tools directly operate on these objects (e.g. hwloc-info and hwloc-annotate). They do not support hexadecimal locations because each location may correspond to multiple objects. For instance, there can be exactly one L3 cache per package and NUMA node, which means it's the same location. If multiple locations are given on the command-line, these tools will operation on each location individually and consecutively.

Some other tools internally manipulate objects as sets (e.g. hwloc-calc and hwloc-bind). They translate each input location into a hexidecimal location. When I/O or Misc objects are used, they are translated into the set of processors (or NUMA nodes) that are close to the given object (because I/O or Misc objects do not contain processors or NUMA nodes).

If multiple locations are specified on the command-line (delimited by whitespace), they are combined (the overall location is wider). If prefixed with "~", the given location will be cleared instead of added to the current list of locations. If prefixed with "x", the given location will be and'ed instead of added to the current list. If prefixed with "^", the given location will be xor'ed.

More complex operations may be performed by using hwloc-calc to compute intermediate values.

### hwloc Objects
Objects in tuples can be any of the following strings (listed from "biggest" to "smallest"):

machine

A set of processors and memory.

numanode

A NUMA node; a set of processors around memory which the processors can directly access. If numa[hbm] is used instead of numanode in locations, command-line tools only consider NUMA nodes marked as high-bandwidth memory (subtype "HBM").

package

Typically a physical package or chip, that goes into a package, it is a grouping of one or more processors.

l1cache ... l5cache

A data (or unified) cache.

l1icache ... l3icache

An instruction cache.

core

A single, physical processing unit which may still contain multiple logical processors, such as hardware threads.

pu

Short for processor unit (not process!). The smallest physical execution unit that hwloc recognizes. For example, there may be multiple PUs on a core (e.g., hardware threads).

osdev, pcidev, bridge, and misc may also be used to specify special devices although some of them have dedicated identification ways as explained in Location Specification.

Finally, note that an object can be denoted by its numeric "depth" in the topology graph.

### hwloc Indexes
Indexes are integer values that uniquely specify a given object of a specific type. Indexes can be expressed either as logical values or physical values. Most hwloc utilities accept logical indexes by default. Passing --physical switches to physical/OS indexes. Both logical and physical indexes are described on this man page.

Logical indexes are relative to the object order in the output from the lstopo command. They always start with 0 and increment by 1 for each successive object.

Physical indexes are how the operating system refers to objects. Note that while physical indexes are non-negative integer values, the hardware and/or operating system may choose arbitrary values -- they may not start with 0, and successive objects may not have consecutive values.

For example, if the first few lines of lstopo -p output are the following:

Machine (47GB)

NUMANode P#0 (24GB) + Package P#0 + L3 (12MB)

L2 (256KB) + L1 (32KB) + Core P#0 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#1 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#2 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#8 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#9 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#10 + PU P#0

NUMANode P#1 (24GB) + Package P#1 + L3 (12MB)

L2 (256KB) + L1 (32KB) + Core P#0 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#1 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#2 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#8 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#9 + PU P#0

L2 (256KB) + L1 (32KB) + Core P#10 + PU P#0

In this example, the first core on the second package is logically number 6 (i.e., logically the 7th core, starting from 0). Its physical index is 0, but note that another core also has a physical index of 0. Hence, physical indexes may only be relevant within the scope of their parent (or set of ancestors). In this example, to uniquely identify logical core 6 with physical indexes, you must specify (at a minimum) both a package and a core: package 1, core 0.

Index values, regardless of whether they are logical or physical, can be expressed in several different forms (where X, Y, and N are positive integers):

X

The object with index value X.

X-Y

All the objects with index values >= X and <= Y.

X-

All the objects with index values >= X.

X:N

N objects starting with index X, possibly wrapping around the end of the level.

all

A special index value indicating all valid index values.

odd

A special index value indicating all valid odd index values.

even

A special index value indicating all valid even index values.

REMEMBER: hwloc's command line tools accept logical indexes for location values by default. Use --physical and --logical to switch from one mode to another.

## SEE ALSO
hwloc's command line tool documentation: lstopo(1), hwloc-bind(1), hwloc-calc(1), hwloc-distrib(1), hwloc-ps(1).

hwloc has many C API functions, each of which have their own man page. Some top-level man pages are also provided, grouping similar functions together. A few good places to start might include: hwlocality_objects(3), hwlocality_types(3), hwlocality_creation(3), hwlocality_cpuset(3), hwlocality_information(3), and hwlocality_binding(3).

For a listing of all available hwloc man pages, look at all "hwloc*" files in the man1 and man3 directories.