OpenSource Headlines

Use embedded Linux and open-source software to build a networked audio appliance.

Benchmarking ZFS On FreeBSD vs. EXT4 & Btrfs On Linux

ZFS is often looked upon as an advanced, superior file-system and one of the strong points of the Solaris/OpenSolaris platform while most feel that only recently has Linux been able to catch-up on the file-system front with EXT4 and the still-experimental Btrfs.

openmamba 20100728

It runs on computers based on the 32-bit Intel x86 architecture, or on 64-bit AMD processors in 32-bit mode.

Even SAP is using more open source

By Source Seeker on Wed, 07/28/10 - 5:55pm. Yesterday SAP took another step into the open source world by signing on to use the Black Duck Suite .

Why WikiLeaks Is The Pirate Bay of Political Intelligence

WikiLeaks is currently in the news because its Afghan War logs comprise one of the largest and most controversial intelligence leaks to date.

Convirture goes open core with 2.0 virt tools

Convirture has unveiled a management tool for open source hypervisors. It's been clear from the beginning of the server virtualization wave that eventually the hypervisor would become commoditized and that the real action, in terms of functionality as well as in money, would come with the management tools that wrap around the hypervisor and make it ...

proxy servers

May 4, 2009 ... As an alternative to downloading the files, the HCPM/HAI Synthesis Cost Proxy Model may be obtained from the FCC's duplicating contractor, ... http://www.fcc.gov/ccb/apd/hcpm/ Patent Database Notices and Status The database servers are now capable of processing approximately 300 simultaneous searches.

Open source installer offered for Plug Computer

Marvell announced the availability of an open source installer, simplifying software deployment on its Linux-based Plug Computer reference design.

Google patches Chrome, sidesteps Windows kernel bug

July 28, 2010, 09:59 AM - Computerworld - Google on Monday patched five vulnerabilities in Chrome by issuing a new "stable" build of the browser.

Fast Easy Web Hosting

Your Say About Movies

Cigars Review

Man Pages

Browse in :

All > Documents > Man Pages

All A B C D E F G H I J K L M N O P Q R S T U V W X Y Z Other

3DBorder

NAME

Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder - draw borders with three-dimensional appearance

SYNOPSIS

#include <tk.h> Tk_3DBorder Tk_Alloc3DBorderFromObj(interp, tkwin, objPtr) Tk_3DBorder Tk_Get3DBorder(interp, tkwin, colorName) Tk_3DBorder Tk_Get3DBorderFromObj(tkwin, objPtr) void Tk_Draw3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief) void Tk_Fill3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief) void Tk_Draw3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief) void Tk_Fill3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief) void Tk_3DVerticalBevel(tkwin, drawable, border, x, y, width, height, leftBevel, relief) void Tk_3DHorizontalBevel(tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief) void Tk_SetBackgroundFromBorder(tkwin, border) CONST char * Tk_NameOf3DBorder(border) XColor * Tk_3DBorderColor(border) GC * Tk_3DBorderGC(tkwin, border, which) Tk_Free3DBorderFromObj(tkwin, objPtr) Tk_Free3DBorder(border)

ARGUMENTS

Tcl_Interp *interp (in)
Interpreter to use for error reporting.

Tk_Window tkwin (in)
Token for window (for all procedures except Tk_Get3DBorder, must be the window for which the border was allocated).

Tcl_Obj *objPtr (in)
Pointer to object whose value describes color corresponding to background (flat areas). Illuminated edges will be brighter than this and shadowed edges will be darker than this.

char *colorName (in)
Same as objPtr except value is supplied as a string rather than an object.

Drawable drawable (in)
X token for window or pixmap; indicates where graphics are to be drawn. Must either be the X window for tkwin or a pixmap with the same screen and depth as tkwin.

Tk_3DBorder border (in)
Token for border previously allocated in call to Tk_Get3DBorder.

int x (in)
X-coordinate of upper-left corner of rectangle describing border or bevel, in pixels.

int y (in)
Y-coordinate of upper-left corner of rectangle describing border or bevel, in pixels.

int width (in)
Width of rectangle describing border or bevel, in pixels.

int height (in)
Height of rectangle describing border or bevel, in pixels.

int borderWidth (in)
Width of border in pixels. Positive means border is inside rectangle given by x, y, width, height, negative means border is outside rectangle.

int relief (in)
Indicates 3-D position of interior of object relative to exterior; should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT for Tk_Fill3DRectangle).

XPoint *pointPtr (in)
Pointer to array of points describing the set of vertices in a polygon. The polygon need not be closed (it will be closed automatically if it isn`t).

int numPoints (in)
Number of points at *pointPtr.

int polyBorderWidth (in)
Width of border in pixels. If positive, border is drawn to left of trajectory given by pointPtr; if negative, border is drawn to right of trajectory. If leftRelief is TK_RELIEF_GROOVE or TK_RELIEF_RIDGE then the border is centered on the trajectory.

int leftRelief (in)
Height of left side of polygon`s path relative to right. TK_RELIEF_RAISED means left side should appear higher and TK_RELIEF_SUNKEN means right side should appear higher; TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things. For Tk_Fill3DPolygon, TK_RELIEF_FLAT may also be specified to indicate no difference in height.

int leftBevel (in)
Non-zero means this bevel forms the left side of the object; zero means it forms the right side.

int leftIn (in)
Non-zero means that the left edge of the horizontal bevel angles in, so that the bottom of the edge is farther to the right than the top. Zero means the edge angles out, so that the bottom is farther to the left than the top.

int rightIn (in)
Non-zero means that the right edge of the horizontal bevel angles in, so that the bottom of the edge is farther to the left than the top. Zero means the edge angles out, so that the bottom is farther to the right than the top.

int topBevel (in)
Non-zero means this bevel forms the top side of the object; zero means it forms the bottom side.

int which (in)
Specifies which of the border`s graphics contexts is desired. Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC.

DESCRIPTION

These procedures provide facilities for drawing window borders in a way that produces a three-dimensional appearance. Tk_Alloc3DBorderFromObj allocates colors and Pixmaps needed to draw a border in the window given by the tkwin argument. The value of objPtr is a standard Tk color name that determines the border colors. The color indicated by objPtr will not actually be used in the border; it indicates the background color for the window (i.e. a color for flat surfaces). The illuminated portions of the border will appear brighter than indicated by objPtr, and the shadowed portions of the border will appear darker than objPtr.

Tk_Alloc3DBorderFromObj returns a token that may be used in later calls to Tk_Draw3DRectangle. If an error occurs in allocating information for the border (e.g. a bogus color name was given) then NULL is returned and an error message is left in interp->result. If it returns successfully, Tk_Alloc3DBorderFromObj caches information about the return value in objPtr, which speeds up future calls to Tk_Alloc3DBorderFromObj with the same objPtr and tkwin.

Tk_Get3DBorder is identical to Tk_Alloc3DBorderFromObj except that the color is specified with a string instead of an object. This prevents Tk_Get3DBorder from caching the return value, so Tk_Get3DBorder is less efficient than Tk_Alloc3DBorderFromObj.

Tk_Get3DBorderFromObj returns the token for an existing border, given the window and color name used to create the border. Tk_Get3DBorderFromObj doesn`t actually create the border; it must already have been created with a previous call to Tk_Alloc3DBorderFromObj or Tk_Get3DBorder. The return value is cached in objPtr, which speeds up future calls to Tk_Get3DBorderFromObj with the same objPtr and tkwin.

Once a border structure has been created, Tk_Draw3DRectangle may be invoked to draw the border. The tkwin argument specifies the window for which the border was allocated, and drawable specifies a window or pixmap in which the border is to be drawn. Drawable need not refer to the same window as tkwin, but it must refer to a compatible pixmap or window: one associated with the same screen and with the same depth as tkwin. The x, y, width, and height arguments define the bounding box of the border region within drawable (usually x and y are zero and width and height are the dimensions of the window), and borderWidth specifies the number of pixels actually occupied by the border. The relief argument indicates which of several three-dimensional effects is desired: TK_RELIEF_RAISED means that the interior of the rectangle should appear raised relative to the exterior of the rectangle, and TK_RELIEF_SUNKEN means that the interior should appear depressed. TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be a groove or ridge around the exterior of the rectangle.

Tk_Fill3DRectangle is somewhat like Tk_Draw3DRectangle except that it first fills the rectangular area with the background color (one corresponding to the color used to create border). Then it calls Tk_Draw3DRectangle to draw a border just inside the outer edge of the rectangular area. The argument relief indicates the desired effect (TK_RELIEF_FLAT means no border should be drawn; all that happens is to fill the rectangle with the background color).

The procedure Tk_Draw3DPolygon may be used to draw more complex shapes with a three-dimensional appearance. The pointPtr and numPoints arguments define a trajectory, polyBorderWidth indicates how wide the border should be (and on which side of the trajectory to draw it), and leftRelief indicates which side of the trajectory should appear raised. Tk_Draw3DPolygon draws a border around the given trajectory using the colors from border to produce a three-dimensional appearance. If the trajectory is non-self-intersecting, the appearance will be a raised or sunken polygon shape. The trajectory may be self-intersecting, although it`s not clear how useful this is.

Tk_Fill3DPolygon is to Tk_Draw3DPolygon what Tk_Fill3DRectangle is to Tk_Draw3DRectangle: it fills the polygonal area with the background color from border, then calls Tk_Draw3DPolygon to draw a border around the area (unless leftRelief is TK_RELIEF_FLAT; in this case no border is drawn).

The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel provide lower-level drawing primitives that are used by procedures such as Tk_Draw3DRectangle. These procedures are also useful in their own right for drawing rectilinear border shapes. Tk_3DVerticalBevel draws a vertical beveled edge, such as the left or right side of a rectangle, and Tk_3DHorizontalBevel draws a horizontal beveled edge, such as the top or bottom of a rectangle. Each procedure takes x, y, width, and height arguments that describe the rectangular area of the beveled edge (e.g., width is the border width for Tk_3DVerticalBevel). The leftBorder and topBorder arguments indicate the position of the border relative to the ``inside`` of the object, and relief indicates the relief of the inside of the object relative to the outside. Tk_3DVerticalBevel just draws a rectangular region. Tk_3DHorizontalBevel draws a trapezoidal region to generate mitered corners; it should be called after Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel will overwrite the mitering in the corner). The leftIn and rightIn arguments to Tk_3DHorizontalBevel describe the mitering at the corners; a value of 1 means that the bottom edge of the trapezoid will be shorter than the top, 0 means it will be longer. For example, to draw a rectangular border the top bevel should be drawn with 1 for both leftIn and rightIn, and the bottom bevel should be drawn with 0 for both arguments.

The procedure Tk_SetBackgroundFromBorder will modify the background pixel and/or pixmap of tkwin to produce a result compatible with border. For color displays, the resulting background will just be the color specified when border was created; for monochrome displays, the resulting background will be a light stipple pattern, in order to distinguish the background from the illuminated portion of the border.

Given a token for a border, the procedure Tk_NameOf3DBorder will return the color name that was used to create the border.

The procedure Tk_3DBorderColor returns the XColor structure that will be used for flat surfaces drawn for its border argument by procedures like Tk_Fill3DRectangle. The return value corresponds to the color name that was used to create the border. The XColor, and its associated pixel value, will remain allocated as long as border exists.

The procedure Tk_3DBorderGC returns one of the X graphics contexts that are used to draw the border. The argument which selects which one of the three possible GC`s: TK_3D_FLAT_GC returns the context used for flat surfaces, TK_3D_LIGHT_GC returns the context for light shadows, and TK_3D_DARK_GC returns the context for dark shadows.

When a border is no longer needed, Tk_Free3DBorderFromObj or Tk_Free3DBorder should be called to release the resources associated with it. For Tk_Free3DBorderFromObj the border to release is specified with the window and color name used to create the border; for Tk_Free3DBorder the border to release is specified with the Tk_3DBorder token for the border. There should be exactly one call to Tk_Free3DBorderFromObj or Tk_Free3DBorder for each call to Tk_Alloc3DBorderFromObj or Tk_Get3DBorder.

KEYWORDS

3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect

a2ps

NAME

a2ps - format files for printing on a PostScript printer

SYNOPSIS

a2ps [OPTION]... [FILE]...

DESCRIPTION

Convert FILE(s) or standard input to PostScript.

Mandatory arguments to long options are mandatory for short options too. Long options marked with * require a yes/no argument, corresponding short options stand for `yes`.

Tasks:

--version: display version
--help: display this help
--guess: report guessed types of FILES
--which: report the full path of library files named FILES
--glob: report the full path of library files matching FILES
--list=defaults: display default settings and parameters
--list=TOPIC: detailed list on TOPIC (delegations, encodings, features, variables, media, ppd, printers, prologues, style-sheets, user-options)

After having performed the task, exit successfully. Detailed lists may provide additional help on specific features.

Global:

-q, --quiet, --silent: be really quiet
-v, --verbose[=LEVEL]: set verbosity on, or to LEVEL
-=, --user-option=OPTION: use the user defined shortcut OPTION
--debug: enable debugging features
-D, --define=KEY[:VALUE]: unset variable KEY or set to VALUE

Sheets:

-M, --medium=NAME: use output medium NAME
The default behaviour is to use the locale category LC_PAPER to determine the medium to use. Note that this information is obtained from environment variables which may not be set up in non-interactive environments (such as in a cron job).
-r, --landscape: print in landscape mode
-R, --portrait: print in portrait mode
--columns=NUM: number of columns per sheet
--rows=NUM: number of rows per sheet
--major=DIRECTION: first fill (DIRECTION=) rows, or columns
-1, -2, ..., -9: predefined font sizes and layouts for 1.. 9 virtuals
-A, --file-align=MODE: align separate files according to MODE (fill, rank page, sheet, or a number)
-j, --borders*: print borders around columns
--margin[=NUM]: define an interior margin of size NUM

The options -1.. -9 affect several primitive parameters to set up predefined layouts with 80 columns. Therefore the order matters: `-R -f40 -2` is equivalent to `-2`. To modify the layout, use `-2Rf40`, or compose primitive options (`--columns`, `--font-size` etc.).

Virtual pages:

--line-numbers=NUM: precede each NUM lines with its line number
-C: alias for --line-numbers=5
-f, --font-size=SIZE: use font SIZE (float) for the body text
-L, --lines-per-page=NUM: scale the font to print NUM lines per virtual
-l, --chars-per-line=NUM: scale the font to print NUM columns per virtual
-m, --catman: process FILE as a man page (same as -L66)
-T, --tabsize=NUM: set tabulator size to NUM
--non-printable-format=FMT specify how non-printable chars are printed

Headings:

-B, --no-header: no page headers at all
-b, --header[=TEXT]: set page header
-u, --underlay[=TEXT]: print TEXT under every page
--center-title[=TEXT]: set page title to TITLE
--left-title[=TEXT]: set left and right page title to TEXT
--right-title[=TEXT]
--left-footer[=TEXT]: set sheet footers to TEXT
--footer[=TEXT]
--right-footer[=TEXT]

The TEXTs may use special escapes.

Input:

-a, --pages[=RANGE]: select the pages to print
-c, --truncate-lines*: cut long lines
-i, --interpret*: interpret tab, bs and ff chars
--end-of-line=TYPE: specify the eol char (TYPE: r, n, nr, rn, any)
-X, --encoding=NAME: use input encoding NAME
-t, --title=NAME: set the name of the job
--stdin=NAME: set the name of the input file stdin
--print-anyway*: force binary printing
-Z, --delegate*: delegate files to another application
--toc[=TEXT]: generate a table of content

When delegations are enabled, a2ps may use other applications to handle the processing of files that should not be printed as raw information, e.g., HTML PostScript, PDF etc.

Pretty-printing:

-E, --pretty-print[=LANG]: enable pretty-printing (set style to LANG)
--highlight-level=LEVEL: set pretty printing highlight LEVEL LEVEL can be none, normal or heavy
-g: alias for --highlight-level=heavy
--strip-level=NUM: level of comments stripping

Output:

-o, --output=FILE: leave output to file FILE. If FILE is `-`, leave output to stdout.
--version-control=WORD: override the usual version control
--suffix=SUFFIX: override the usual backup suffix
-P, --printer=NAME: send output to printer NAME
-d: send output to the default printer

PostScript:

--prologue=FILE: include FILE.pro as PostScript prologue
--ppd[=KEY]: automatic PPD selection or set to KEY
-n, --copies=NUM: print NUM copies of each page
-s, --sides=MODE: set the duplex MODE (`1` or `simplex`, `2` or `duplex`, `tumble`)
-S, --setpagedevice=K[:V]: pass a page device definition to output
--statusdict=K[:[:]V]: pass a statusdict definition to the output
-k, --page-prefeed: enable page prefeed
-K, --no-page-prefeed: disable page prefeed

By default a2ps is tuned to do what you want to, so trust it. To pretty print the content of the `src` directory and a table of content, and send the result to the printer `lw`,

: $ a2ps -P lw --toc src/*

To process the files `sample.ps` and `sample.html` and display the result,

: $ a2ps -P display sample.ps sample.html

To process a mailbox in 4 up,

: $ a2ps -=mail -4 mailbox

To print as a booklet on the default printer, which is Duplex capable,

: $ a2ps -=book paper.dvi.gz -d

News, updates and documentation: visit http://www.inf.enst.fr/~demaille/a2ps/.

AUTHOR

Written by Akim Demaille, Miguel Santana.

REPORTING BUGS

Report bugs to <bug-a2ps@gnu.org>.

COPYRIGHT

Copyright © 1988-1993 Miguel Santana
Copyright © 1995-2000 Akim Demaille, Miguel Santana
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

aafire

NAME

aafire, aainfo, aasavefont, aatest - aalib example programs

SYNOPSIS

aafire [options] aainfo [options] aasavefont [options] file_name variable_name long_name short_name aatest [options]

DESCRIPTION

This manual page documents briefly the aafire, aainfo, aasavefont, and aatest programs.

All of these programs exist to demonstrate the capabilities of the aalib library, an ascii art library.

aafire displays burning ascii art flames.

aainfo displays information about what drivers aalib will use for the display, keyboard, and mouse, and what parameters, such as screen size those drivers will use.

aasavefont saves a font to a file.

aatest tests the capabilities of aalib.

AUTHOR

This manual page was written by Joey Hess, for the Debian GNU/Linux system.

aa_autoinit

NAME

aa_autoinit - easy to use AA-lib initialization function.

SYNOPSIS

#include <aalib.h>

aa_context *aa_autoinit(const struct aa_hardware_params *params);

PARAMETERS

const struct aa_hardware_params *params: Hardware parameters you want. Use aa_defparams for default values.

DESCRIPTION

Attempts to find available output driver supporting the specified parameters. First attempts to initialize the recommended drivers and then in order drivers available in the aa_drivers array (all regular output drivers compiled into AA-lib).

RETURNS

Pointer to initialized context structure when succesfull or NULL on failure.

aa_autoinitmouse

NAME

aa_autoinitmouse - easy to use AA-lib mouse initialization function.

SYNOPSIS

#include <aalib.h>

int aa_autoinitmouse
(
struct aa_context *c,

int mode

);

PARAMETERS

struct aa_context *c: Specifies the AA-lib context to operate on.
int mode: Mask of extra features you request. No such features are available in the current AA-lib version.

DESCRIPTION

Attempts to find available mouse driver supporting the specified mode. First attempts to initialize the recommended drivers and then in order drivers available in the aa_kbddrivers array (all regular output drivers compiled into AA-lib).

RETURNS

1 when succesfull or 0 on failure.

aa_createedit

NAME

aa_createedit - Simple interactive line editor provided as helper function.

SYNOPSIS

#include <aalib.h>

struct aa_edit *aa_createedit
(
       aa_context *c,

       int x,

       int y,

       int size,

       char *s,

       int maxsize

);

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.
int x: X coordinate of the edited text.
int y: Y coordinate of the edited text.
int size: Length of the editor window.
char *s: Buffer to edit (containing default value).
int maxsize: Size of the buffer.

#include <aalib.h>

void aa_editkey
(
struct aa_edit *e,

int c

);

PARAMETERS

struct aa_edit *e: Editor context to use (see aa_createedit).
int c: Key pressed.

DESCRIPTION

Notify the line editor about keypress.

aa_fonts

NAME

aa_fonts - Null-terminated array of available fonts.

SYNOPSIS

#include <aalib.h>

extern const struct aa_font *aa_fonts[];

DESCRIPTION

Null-terminated array of available fonts.

aa_getevent

NAME

aa_getevent - keyboard functions

SYNOPSIS

#include <aalib.h>

int aa_getevent
(
aa_context *c,

int wait

);

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.
int wait: 1 if you wish to wait for the even when queue is empty.

DESCRIPTION

Return next event from queue. Return next even from queue. Optionally wait for even when queue is empty.

RETURNS

Next event from queue (values lower than 256 are used to report ascii values of pressed keys and higher values have special meanings) See the AA-lib texinfo documentation for more details. 0 is returned when queue is empty and wait is set to 0.

aa_getmouse

NAME

aa_getmouse - Get mouse position as specified by last mouse event read by aa_getevent.

SYNOPSIS

#include <aalib.h>

void aa_getmouse
(
       aa_context *c,

       int *x,

       int *y,

       int *b

);

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.
int *x: Used to return X coordinate of mouse in characters.
int *y: Used to return Y coordinate of mouse in characters.
int *b: Used to return button mask of mouse. (Values used are AA_BUTTON1, AA_BUTTON2 and AA_BUTTON3).

DESCRIPTION

Get mouse position as specified by last mouse event read by aa_getevent.

aa_help

NAME

aa_help - AA-lib help string for the default command line parser.

SYNOPSIS

#include <aalib.h>

const struct aa_driver *driver: Driver you want to use. Available drivers are listed in the NULL terminated aa_drivers array.
const struct aa_hardware_params *defparams: Hardware parameters you want. Use aa_defparams for default values.
const void *driverdata: This pointer is passed dirrectly to driver used to specify additional driver dependent parameters.

DESCRIPTION

This is the most primitive AA-lib initialization function. Allows better control over the process than the easier to use aa_autoinit function.

Every AA-lib program ought to have call to aa_parseoptions before first call to aa_init.

RETURNS

Pointer to new AA-lib context or NULL if failed.

aa_initmouse

NAME

aa_initmouse - initialize the AA-lib mouse driver.

SYNOPSIS

#include <aalib.h>

int aa_initmouse
(
       struct aa_context *c,

       const struct aa_mousedriver *d,

       int mode

);

PARAMETERS

struct aa_context *c: Specifies the AA-lib context to operate on.
const struct aa_mousedriver *d: Driver you wish to use.
int mode: Mask of extra features you request. No such features are available in the current AA-lib version.

DESCRIPTION

This is the most primitive AA-lib keyboard initialization function. Allows better control over the process than the easier to use aa_autoinitmouse function.

RETURNS

1 on success and 0 on fail.

aa_kbdrecommended

NAME

aa_kbdrecommended - List of recommended drivers.

SYNOPSIS

#include <aalib.h>

extern aa_linkedlist *aa_kbdrecommended;

DESCRIPTION

List of recommended drivers is used by aa_autoinit familly of functions and altered by aa_recommend familly of functions.

aa_mmwidth

NAME

aa_mmwidth - returns width of the output screen in millimeters.

SYNOPSIS

#include <aalib.h>

int aa_mmwidth(aa_context *a);

PARAMETERS

aa_context *a: Specifies the AA-lib context to operate on.

DESCRIPTION

Returns width of the output screen in millimeters.

aa_mouserecommended

NAME

aa_mouserecommended - List of recommended drivers.

SYNOPSIS

#include <aalib.h>

extern aa_linkedlist *aa_mouserecommended;

DESCRIPTION

List of recommended drivers is used by aa_autoinit familly of functions and altered by aa_recommend familly of functions.

aa_printf

NAME

aa_printf - print text to AA-lib output buffers.

SYNOPSIS

#include <aalib.h>

int aa_printf
(
       aa_context *c,

       int x,

       int y,

       enum aa_attribute attr,

       const char *fmt,

       ...

);

PARAMETERS

aa_context *c

Specifies the AA-lib context to operate on.

int x

X coordinate of the first character.

int y

Y coordinate of the first character.

enum aa_attribute attr

Attribute to use.

Possible values for an enum aa_attribute are as follows:

AA_NORMAL: Normal characters.
AA_DIM: Dark characters.
AA_BOLD: Bright characters.
AA_BOLDFONT: Characters rendered in bold font.
AA_REVERSE: Reversed (black on whilte) characters.
AA_SPECIAL: Render characters in a way easilly visible on the screen. The exact rendering is driver dependent, but this mode ought to be used to output texts you want to make easilly visible in the image.

const char *fmt

Text to output in standard printf format.

...

Not Documented.

DESCRIPTION

Print given text to AA-lib output buffers. To see the effect you need to call aa_flush too.

aa_puts

NAME

aa_puts - output string to AA-lib output buffers.

SYNOPSIS

#include <aalib.h>

void aa_puts
(
       aa_context *c,

       int x,

       int y,

       enum aa_attribute attr,

       const char *s

);

PARAMETERS

aa_context *c

Specifies the AA-lib context to operate on.

int x

X coordinate of the first character.

int y

Y coordinate of the first character.

enum aa_attribute attr

Attribute to use.

Possible values for an enum aa_attribute are as follows:

AA_NORMAL: Normal characters.
AA_DIM: Dark characters.
AA_BOLD: Bright characters.
AA_BOLDFONT: Characters rendered in bold font.
AA_REVERSE: Reversed (black on whilte) characters.
AA_SPECIAL: Render characters in a way easilly visible on the screen. The exact rendering is driver dependent, but this mode ought to be used to output texts you want to make easilly visible in the image.

const char *s

aa_context *c: Specifies the AA-lib context to operate on.
const aa_renderparams *p: Rendering parametters used to specify brightness, gamma correction and other usefull stuff. Use aa_defrenderparams for default values.
int x1: Column of top left coner of rendered area (in characters!).
int y1: Row of top left coner of rendered area.
int x2: Column of bottom right coner of rendered area.
int y2: Row of bottom right coner of rendered area.

DESCRIPTION

This function does the trick of converting the emulated framebuffer into high quality ASCII-art. If you want to be really fast, you might use aa_fastrender. If you want to emulate palette, use aa_renderpalette.

Note that to see the effect you need to call aa_flush too.

First call to this function may take a while, because the rendering tables are produced.

aa_resizehandler

NAME

aa_resizehandler - Set user handler to be called on resize event.

SYNOPSIS

#include <aalib.h>

void aa_resizehandler
(
aa_context *c,

void (*handler)(aa_context *)

);

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.
void (*handler)(aa_context *): Function to be called when resize happends.

DESCRIPTION

Set user handler to be called on resize event.

aa_scrwidth

NAME

aa_scrwidth - returns width of the output screen in characters.

SYNOPSIS

#include <aalib.h>

int aa_scrwidth(aa_context *a);

PARAMETERS

aa_context *a: Specifies the AA-lib context to operate on.

DESCRIPTION

Returns width of the output screen in characters.

aa_setsupported

NAME

aa_setsupported - alter the "supported" field of hardware_params structure used by AA-lib

SYNOPSIS

#include <aalib.h>

void aa_setsupported
(
aa_context *c,

int supported

);

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.
int supported: New mask of requested features. Can contain AA_EXTENDED to enable use of all 256 characters and AA_EIGHT to enable use of the character numbered higher than 127.

DESCRIPTION

This function can be used to alter "supported" field of hardware-params structure used by AA-lib.

aa_showmouse

NAME

aa_showmouse - show the mouse cursor.

SYNOPSIS

#include <aalib.h>

void aa_showmouse(aa_context *c);

PARAMETERS

aa_context *c: Not Documented.

DESCRIPTION

Show the mouse cursor. This function may be ignored by some drivers.

aa_uninitkbd

NAME

aa_uninitkbd - uninitialize the keyboard driver.

SYNOPSIS

#include <aalib.h>

void aa_uninitkbd(aa_context *context);

PARAMETERS

aa_context *context: Specifies the AA-lib context to operate on.

DESCRIPTION

Calls "uninitialize" function of the keyboard driver. It ought to undo all actions done by "initialize" function.

ab

NAME

ab - Apache HTTP server benchmarking tool

SYNOPSIS

ab [ -A auth-username:password ] [ -c concurrency ] [ -C cookie-name=value ] [ -d ] [ -e csv-file ] [ -g gnuplot-file ] [ -h ] [ -H custom-header ] [ -i ] [ -k ] [ -n requests ] [ -p POST-file ] [ -P proxy-auth-username:password ] [ -q ] [ -s ] [ -S ] [ -t timelimit ] [ -T content-type ] [ -v verbosity] [ -V ] [ -w ] [ -x <table>-attributes ] [ -X proxy[:port] ] [ -y <tr>-attributes ] [ -z <td>-attributes ] [http://]hostname[:port]/path

SUMMARY

ab is a tool for benchmarking your Apache Hypertext Transfer Protocol (HTTP) server. It is designed to give you an impression of how your current Apache installation performs. This especially shows you how many requests per second your Apache installation is capable of serving.

OPTIONS

-A auth-username:password: Supply BASIC Authentication credentials to the server. The username and password are separated by a single : and sent on the wire base64 encoded. The string is sent regardless of whether the server needs it (i.e., has sent an 401 authentication needed).
-c concurrency: Number of multiple requests to perform at a time. Default is one request at a time.
-C cookie-name=value: Add a Cookie: line to the request. The argument is typically in the form of a name=value pair. This field is repeatable.
-d: Do not display the "percentage served within XX [ms] table". (legacy support).
-e csv-file: Write a Comma separated value (CSV) file which contains for each percentage (from 1% to 100%) the time (in milliseconds) it took to serve that percentage of the requests. This is usually more useful than the `gnuplot` file; as the results are already `binned`.
-g gnuplot-file: Write all measured values out as a `gnuplot` or TSV (Tab separate values) file. This file can easily be imported into packages like Gnuplot, IDL, Mathematica, Igor or even Excell. The labels are on the first line of the file.
-h: Display usage information.
-H custom-header: Append extra headers to the request. The argument is typically in the form of a valid header line, containing a colon-separated field-value pair (i.e., "Accept-Encoding: zip/zop;8bit").
-i: Do HEAD requests instead of GET.
-k: Enable the HTTP KeepAlive feature, i.e., perform multiple requests within one HTTP session. Default is no KeepAlive.
-n requests: Number of requests to perform for the benchmarking session. The default is to just perform a single request which usually leads to non-representative benchmarking results.
-p POST-file: File containing data to POST.
-P proxy-auth-username:password: Supply BASIC Authentication credentials to a proxy en-route. The username and password are separated by a single : and sent on the wire base64 encoded. The string is sent regardless of whether the proxy needs it (i.e., has sent an 407 proxy authentication needed).
-q: When processing more than 150 requests, ab outputs a progress count on stderr every 10% or 100 requests or so. The -q flag will suppress these messages.
-s: When compiled in (ab -h will show you) use the SSL protected https rather than the http protocol. This feature is experimental and very rudimentary. You probably do not want to use it.
-S: Do not display the median and standard deviation values, nor display the warning/error messages when the average and median are more than one or two times the standard deviation apart. And default to the min/avg/max values. (legacy support).
-t timelimit: Maximum number of seconds to spend for benchmarking. This implies a -n 50000 internally. Use this to benchmark the server within a fixed total amount of time. Per default there is no timelimit.
-T content-type: Content-type header to use for POST data.
-v verbosity: Set verbosity level - 4 and above prints information on headers, 3 and above prints response codes (404, 200, etc.), 2 and above prints warnings and info.
-V: Display version number and exit.
-w: Print out results in HTML tables. Default table is two columns wide, with a white background.
-x <table>-attributes: String to use as attributes for <table>. Attributes are inserted <table here >.
-X proxy[:port]: Use a proxy server for the requests.
-y <tr>-attributes: String to use as attributes for <tr>.
-z <td>-attributes: String to use as attributes for <td>.

BUGS

There are various statically declared buffers of fixed length. Combined with the lazy parsing of the command line arguments, the response headers from the server and other external inputs, this might bite you.

It does not implement HTTP/1.x fully; only accepts some `expected` forms of responses. The rather heavy use of strstr(3) shows up top in profile, which might indicate a performance problem; i.e., you would measure the ab performance rather than the server`s.

abcde

NAME

abcde - Grab an entire CD and compress it to Ogg or MP3 format.

SYNOPSIS

abcde [options] [tracks]

DESCRIPTION

Ordinarily, the process of grabbing the data off a CD and encoding it, then tagging or commenting it, is very involved. abcde is designed to automate this. It will take an entire CD and convert it into a compressed audio format - Ogg Vorbis or MPEG Audio Layer III. With one command, it will:

*: Do a CDDB query over the Internet to look up your CD
*: Grab a track from your CD
*: Compress it to Ogg or MP3 format
*: Comment or ID3 tag it
*: Give it an intelligible filename
*: Delete the intermediate WAV file
*: Repeat until finished

OPTIONS

-a [actions]: Comma-delimited list of actions to perform. Can be one or more of: cddb, read, encode, tag, move, playlist, clean. Encode implies read. Tag implies cddb, read, encode. Move implies cddb, read, encode, tag. Playlist implies cddb. The default is to do all actions except playlist.
-c [filename]: Specifies an additional configuration file to parse. Configuration options in this file override those in /etc/abcde.conf or $HOME/.abcde.conf.
-C [discid]: Allows you to resume a session for discid when you no longer have the CD available (abcde will automatically resume if you still have the CD in the drive). You must have already finished at least the "read" action during the previous session.
-d [devicename]: CD-ROM block device that contains audio tracks to be read.
-D: Capture debugging information (you`ll want to redirect this - try `abcde -D 2>logfile`)
-j [number]: Start [number] encoder processes at once. Useful for SMP systems. Overrides the MAXPROCS configuration variable.
-l: Use the low-diskspace algorithm. See the LOWDISK configuration variable.
-o [filetype]: Select output type. Can be either "ogg" or "mp3". See the OUTPUTTYPE configuration variable.
-r [hosts...]: Remote encode on this comma-delimited list of machines using distmp3. See the REMOTEHOSTS configuration variable.
-x: Eject the CD when all tracks have been read. See the EJECTCD configuration variable.
-h: Get help information.
[tracks]: A list of tracks you want abcde to process. If this isn`t specified, abcde will process the entire CD. Accepts ranges of track numbers - "abcde 1-5 7 9" will process tracks 1, 2, 3, 4, 5, 7, and 9.

OUTPUT

Each track is, by default, placed in a separate file named after the track in a subdirectory named after the artist under the current directory. Each file is given an extension identifying its compression format, `.ogg` or `.mp3`. This can be modified using the OUTPUTFORMAT and VAOUTPUTFORMAT variables in your abcde.conf.

CONFIGURATION

abcde sources two configuration files on startup - /etc/abcde.conf and $HOME/.abcde.conf, in that order. Here is a list of options abcde recognizes:

CDDBURL: Specifies a server to use for CDDB lookups.
ENCODERSYNTAX: Specifies the style of encoder to use. Valid options are `oggenc` (default for Ogg Vorbis), `vorbize`, `lame` (default for MP3), `gogo`, `bladeenc`, `l3enc`, and `mp3enc`. This affects the default location of the binary, the variable to pick encoder command-line options from, and where the options are given.
HELLOINFO: Specifies the Hello information to send to the CDDB server. The CDDB protocol requires you to send a valid username and hostname each time you connect. The format of this is username@hostname.
OUTPUTDIR: Specifies the directory to place completed tracks/playlists in.
WAVOUTPUTDIR: Specifies the temporary directory to store .wav files in. Abcde may use up to 700MB of temporary space for each session (although it is rare to use over 100MB for a machine that can encode music as fast as it can read it).
OUTPUTFORMAT: Specifies the format for completed Ogg or MP3 filenames. Variables are included using standard shell syntax. Allowed variables are ALBUMFILE, ARTISTFILE, TRACKFILE, and TRACKNUM. Default is `${ARTISTFILE}/${TRACKFILE}.${OUTPUTTYPE}`. Make sure to use single quotes around this variable. TRACKNUM is automatically zero-padded.
OUTPUTTYPE: Specifies the encoding format to output as well as the default extension and encoder. Defaults to "ogg". Valid settings are "ogg" (Ogg Vorbis) and "mp3" (MPEG-1 Audio Layer 3).
VAOUTPUTFORMAT: Just like OUTPUTFORMAT but for Various Artists discs. Default is whatever OUTPUTFORMAT is set to.
PATHNAMES: The following configuration file options specify the pathnames of their respective utilities: LAME, GOGO, BLADEENC, L3ENC, XINGMP3ENC, MP3ENC, VORBIZE, OGGENC, ID3, ID3V2, CDPARANOIA, CDDA2WAV, WGET, CDDISCID, CDDBTOOL, EJECT, DISTMP3, and VORBISCOMMENT.
COMMAND-LINE OPTIONS: If you wish to specify command-line options to any of the programs abcde uses, set the following configuration file options: LAMEOPTS, GOGOOPTS, BLADEENCOPTS, L3ENCOPTS, XINGMP3ENCOPTS, MP3ENCOPTS, VORBIZEOPTS, OGGENCOPTS, ID3OPTS, ID3V2OPTS, CDPARANOIAOPTS, CDDA2WAVOPTS, WGETOPTS, CDDBTOOLOPTS, EJECTOPTS, and DISTMP3OPTS.
MAXPROCS: Defines how many encoders to run at once. This makes for huge speedups on SMP systems. You should run one encoder per CPU at once for maximum efficiency, although more doesn`t hurt very much.
LOWDISK: If set to y, conserves disk space by encoding tracks immediately after reading them. This is substantially slower than normal operation but requires several hundred MB less space to complete the encoding of an entire CD. Use only if your system is low on space and cannot encode as quickly as it can read.
PLAYLISTFORMAT: Specifies the format for completed playlist filenames. Works like the OUTPUTFORMAT configuration variable. Default is `${ARTISTFILE}_-_${ALBUMFILE}.m3u`. Make sure to use single quotes around this variable.
PLAYLISTDATAPREFIX: Specifies a prefix for filenames within a playlist. Useful for http playlists, etc.
COMMENT: Specifies a comment to embed in the ID3 or Ogg comment field of each finished track. Can be up to 28 characters long. Supports the same syntax as OUTPUTFORMAT. Does not currently support ID3v2.
REMOTEHOSTS: Specifies a comma-delimited list of systems to use for remote encoding using distmp3. Equivalent to -r.
mungefilename: mungefilename() is an abcde shell function that can be overridden via abcde.conf. It takes CDDB data as $1 and outputs the resulting filename on stdout. It defaults to eating control characters, apostrophes and question marks, translating spaces and forward slashes to underscores, and translating colons to an underscore and a hyphen.
If you modify this function, it is probably a good idea to keep the forward slash munging (UNIX cannot store a file with a `/` char in it) as well as the control character munging (NULs can`t be in a filename either, and newlines and such in filenames are typically not desirable).
EJECTCD: If set to "y", abcde will call eject(1) to eject the cdrom from the drive after all tracks have been read.

BACKEND TOOLS

abcde requires the following backend tools to work:

*: An Ogg or MP3 Encoder (oggenc, vorbize, lame, gogo, bladeenc, l3enc, mp3enc)
*: An audio CD reading utility (cdparanoia, cdda2wav)
*: cd-discid, a CDDB DiscID reading program.
*: wget, an HTTP retrieval program.
*: (for MP3s) id3, an id3 tagging program.
*: (optional) distmp3, a client/server for distributed mp3 encoding.

AUTHOR

Robert Woodcock <rcw@debian.org>

abort

NAME

abort - cause abnormal program termination

SYNOPSIS

#include <stdlib.h> void abort(void);

DESCRIPTION

The abort() function causes abnormal program termination unless the signal SIGABRT is caught and the signal handler does not return. If the abort() function causes program termination, all open streams are closed and flushed.

If the SIGABRT signal is blocked or ignored, the abort() function will still override it.

RETURN VALUE

The abort() function never returns.

CONFORMING TO

SVID 3, POSIX, BSD 4.3, ISO 9899 (C99)

abxtest

NAME

abxtest - double-blind ABX comparison testing script

SYNOPSIS

abxtest [-n min] [-m max] [-g goal] A-cmd B-cmd

DESCRIPTION

abxtest is a tool for conducting listening (or other subjective) tests to determine whether a listener can discern a difference between two subjects under test, denoted A and B.

The listener conducts several trials in which an unknown subject, X, is randomly chosen to be either A or B. The probability that X is A or B is the same. The listener must decide whether X sounds the same as A or the same as B. The listener may repeat A, B, and X as many times as necessary before reaching a verdict.

In order to prove the hypothesis that a difference can be discerned between A and B, the listener must disprove the null hypothesis that A sounds the same as B. This is accomplished by correctly identifying X often enough that randomly guessing correctly the same number of times would be statistically improbable.

The A and B subjects for abxtest are actually arbitrary shell commands. The normal mode of use would be to give commands which play two slightly different sounds. The standard output and standard error from each command are suppressed so as not to reveal the identity of X. The listener may interrupt an executing command (usually by pressing ^C) without terminating the test.

OPTIONS

-n min: Set the minimum number of trials. Trials will continue after this number if the statistical probability goal has not yet been met. The default is 10.
-m max: Set the maximum number of trials. Trials will end after this number even if the statistical probability goal has not been met. The default is 20.
-g goal: Set the minimum statistical probability goal. This is the probability that the number of correct identifications is the same as random guesses. In order to disprove the null hypothesis, the result of the test must be a probability less than or equal to this goal. The default is 0.05.

FILES

/dev/random: By default this file is read to generate a random sequence of X.

ENVIRONMENT

RANDOM_FILE: If set, the file named by this variable will be read instead of /dev/random to generate a sequence of X.

NOTES

abxtest uses the binomial distribution to accurately calculate the probability that the result is the same as random guesses.

AUTHOR

Robert Leslie <rob@mars.org>

accel

NAME

accel - tests the new style svgalib accelerator interface

SYNOPSIS

accel

DESCRIPTION

Test new-style accelerated functions (As of this writing: Ark, Cirrus, Chips & Technologies cards, and Mach32 only). For other cards the demo will not work (well it will complain about missing accelerator support). Don`t worry about this.

During the development of the Mach32 new style driver for 1.2.12, this demo was massively extended to check the Mach32 functions.

Upon startup it lists all supported SVGA modes and asks you to enter a number identifying the mode to be tested. The supported subfunctions of vga_accel(3) in this mode are listed and the demo instructs to press <Return> to start the demos.

If supported, all drawing operations are performed in the background.

Then the following tests are performed:

Positioning tests

These tests were originally intended to check that the accelerator commands work on the proper screen locations. The screen shows 12 (4 x 3) smaller areas with red crosses in the corners. When everything is ok, the drawings should reach right in the corners of the crosses.

A given card may not support all operations listed here. In that case the resp. test area just shows the red crosses. For tests performed, the name of the test is printed below the area. The tests are (from left to right, top to bottom):

1.

A green box is drawn with vga_accel(ACCEL_FILLBOX).

2.

A cross of green lines is drawn with vga_accel(ACCEL_DRAWLINE).

3.

A linux pixmap just fitting into the crosses is drawn with vga_accel(ACCEL_PUTIMAGE).

4.

A pixmap just fitting into the crosses is drawn into the red crosses (by vgagl(5) which may or may not use the accelerator). The pixmap is then copied to a few lines/columns below. Green crosses mark the intended destination position.

5.

Works like 3. but copies to an area above the origin. The accelerator must ensure that the overlapping areas are handled non corrupting. Thus, watch that the copy operation is properly performed.

6.

A green triangle is drawn above the top/left to bottom/right diagonal by use of vga_accel(ACCEL_DRAWHLINELIST).

7.

Certain bitmaps are copied to the screen. In the corners you`ll see the digits

0: top/left, green on red.
1: top/right, red on green.
2: bottom/left, black on white.
3: bottom/right, white on black. Note that some black border, not the digit will be aligned to the red crosses.

Finally, a yellow wizard image is drawn into the center.

The bit ordering for bitmaps is a bit weird. Please check that the digits are not mirrored or flipped.

8.

This time bitmap transparency is tested by drawing wizard images onto the aforementioned linux pixmap (left to right, top to bottom) in yellow, red, green, and cyan. The background of the yellow wizard is masked out by a black border bitmap. Note that the wizard will not reach into the red corners because the bitmap has some (transparent) border.

9.

The text below this box is copied as a monochrome bitmap from the screen into the corners listed under 7. in the same colors.

10.

Two green rectangles with an edge cut out from the bottom is drawn using vga_accel(ACCEL_POLYLINE).Thereisanintendedbugwhichdrawsthecenterofthe top line twice. If supported, the lower rectangle is drawn in cyan and with the xor raster operation s.t. the buggy point is not drawn thus leaving a pin hole.

11.

vga_accel(ACCEL_POLYHLINE)isusedtodrawsomegreenlineswhichmakesthisarealook like a green box with a cut out, black M-style shape.

12.

A weird green polygon is filled in red with vga_accel(ACCEL_POLYFILLMODE) using the techniques given in vga_accel(3). This needs some offscreen memory. If VGA memory is tight in that resolution the test cannot be performed.

After this screen, you`ll have to hit <Return> to continue.

Raster operations

Again, red cross bordered areas are drawn on the screen, this time for each of the supported raster operations. For ROP_AND and ROP_XOR the areas are filled in white first.

Three overlapping boxes A, B, C are drawn such that you see the following areas.

AAAAAAddddBBBBBB
AAAAAAddddBBBBBB
AAAAAAddddBBBBBB
AAAAeeggggffBBBB
AAAAeeggggffBBBB
AAAAeeggggffBBBB
CCCCCCCC
CCCCCCCC
CCCCCCCC

The pictures should show:

1.: Replace mode. A, B, C are red, green, blue. They just overlap, yielding d - green and e, f, g - blue.
2.: The colors mix using ROP_OR (and a nice color table). The overlapping areas become the additive color mix: d - yellow, e - magenta, f - cyan, and g - white.
3.: ROP_AND is used. The background is filled white first, s.t. there is something in video memory to and with non trivially. We have A, B, C in cyan, magenta, yellow and d, e, f, g in blue, green, red, black.
4.: ROP_XOR is used and the background filled white first too. A, B, C are red, green, blue again, but the overlapping areas d, e, f, g become blue, green, red, white.
5.: ROP_INV is used, s.t. A, B, C are all white and d, e, f, g become black, black, black, white. Note that this is not done by using ROP_XOR and drawing A, B, C in white. Instead A, B, C are drawn in the usual
red, green, blue. However, the accelerator just inverts the memory contens.

If the accelerator supports raster operations for ACCEL_DRAWHLINELIST actually disks (well, ellipses) are drawn instead of boxes.

After this screen, you`ll have to hit <Return> to continue.

Replace QuixDemo

If ACCEL_DRAWLINE is supported, a Quix like bouncing series of lines in varying colors is drawn. The lines are removed from the screen by overdrawing them in black, thus erasing the dots and text on the background.

The test lasts about 5 seconds and some statistics are printed to stdout.

XOR Mode QuixDemo

As before, but this time all lines are drawn in ROP_XOR mode (if ACCEL_DRAWLINE supports raster operations). Thus the background will not be destroyed this time.

The test lasts about 5 seconds and some statistics are printed to stdout.

FillBox Demo

The screen is ACCEL_FILLBOX filled with a series of boxes of increasing colors. In truei/high color modes you`ll probably only see a series of varying blue tones (because these are at the beginning of the color table and there are soo many of them).

The test lasts about 5 seconds and some statistics are printed to stdout.

ScreenCopy Demo

Some random dots are drawn on the screen and thirds of the screen contents are moved around using ACCEL_SCREENCOPY.

The test lasts about 5 seconds and some statistics are printed to stdout.

Scroll Demo

Some random dots are drawn on the screen and moved one line up with ACCEL_SCREENCOPY. In offscreen memory a new line is prepared which will be cleared by ACCEL_FILLBOXandmoveinfrombelow.Thistestrequiressomeoffscreenandwillnot be performed if video memory is very tight.

The test lasts about 5 seconds and some statistics are printed to stdout.

FillBox with DrawHLineList Demo

Like the FillBox test, but no box fill is done but the screen is filled with a list of horizontal lines drawn with ACCEL_DRAWHLINELIST.

The test lasts about 5 seconds and some statistics are printed to stdout.

FillBox XOR Mode Demo

Like the FillBox test, but the XOR raster operation is used.

The test lasts about 5 seconds and some statistics are printed to stdout.

PutBitmap Demo

The screen is filled with bitmasks consisting of tiny vertical lines alternating in red and blue.

The test lasts about 5 seconds and some statistics are printed to stdout.

SOME DATAPOINTS

Here is a list of speed listings for some cards. Please keep in mind that also the calling overhead for the program is measured. This seems to be esp. true for the QuixDemo.

Results on a Cirrus GD5434-E with 2Mb:

640x480x256 60 Hz: FillBox: 200.3 Mpixels/s (200.3 Mbytes/s)
ScreenCopy: 51.0 Mpixels/s (51.0 Mbytes/s)
Scroll Demo: 50.5 Mpixels/s (50.5 Mbytes/s)
FillBox XOR: 83.2 Mpixels/s (83.2 Mbytes/s)
320x200x256 70 Hz: FillBox: 200.1 Mpixels/s (200.1 Mbytes/s)
ScreenCopy: 52.3 Mpixels/s (52.3 Mbytes/s)
Scroll Demo: 51.2 Mpixels/s (51.2 Mbytes/s)
FillBox XOR: 87.1 Mpixels/s (87.1 Mbytes/s)
640x480x32K 60 Hz: FillBox: 90.9 Mpixels/s (181.8 Mbytes/s)
ScreenCopy: 23.1 Mpixels/s (46.3 Mbytes/s)
Scroll Demo: 23.0 Mpixels/s (46.1 Mbytes/s)
FillBox XOR: 37.2 Mpixels/s (74.5 Mbytes/s)
640x480x16M (32-bit) 60 Hz: FillBox: 35.5 Mpixels/s (142.3 Mbytes/s)
ScreenCopy: 9.3 Mpixels/s (37.3 Mbytes/s)
Scroll Demo: 9.2 Mpixels/s (37.1 Mbytes/s)
FillBox XOR: 14.6 Mpixels/s (58.6 Mbytes/s)

On a Cirrus Logic 5426 VLB (50 MHz MCLK):

640x480x256 60 Hz: FillBox: 32.8 Mpixels/s (32.8 Mbytes/s)
ScreenCopy: 16.4 Mpixels/s (16.4 Mbytes/s)
Scroll Demo: 16.3 Mpixels/s (16.3 Mbytes/s)
FillBox XOR: 16.5 Mpixels/s (16.5 Mbytes/s)
640x480x32K 60 Hz: FillBox: 12.2 Mpixels/s (24.4 Mbytes/s)
ScreenCopy: 6.1 Mpixels/s (12.2 Mbytes/s)
Scroll Demo: 6.0 Mpixels/s (12.1 Mbytes/s)
FillBox XOR: 6.1 Mpixels/s (12.2 Mbytes/s)

Tweaked to 60 MHz MCLK:

640x480x256 60 Hz: FillBox: 42.1 Mpixels/s (42.1 Mbytes/s)
ScreenCopy: 21.0 Mpixels/s (21.0 Mbytes/s)
Scroll Demo: 20.9 Mpixels/s (20.9 Mbytes/s)
FillBox XOR: 21.1 Mpixels/s (21.1 Mbytes/s)
640x480x32K 60 Hz: FillBox: 16.7 Mpixels/s (33.5 Mbytes/s)
ScreenCopy: 8.3 Mpixels/s (16.7 Mbytes/s)
Scroll Demo: 8.3 Mpixels/s (16.7 Mbytes/s)
FillBox XOR: 8.3 Mpixels/s (16.7 Mbytes/s)

Results on a Mach32 EISA with 2Mb VRAM:

1280x1024x256 60 Hz: Replace QuixDemo: 12.1 Klines/s (6.7 Mpixels/s or 6.7 Mbytes/s)
Xor QuixDemo: 9.9 Klines/s (5.1 Mpixels/s or 5.1 Mbytes/s)
FillBox: 75.4 Mpixels/s (75.4 Mbytes/s)
ScreenCopy: 26.4 Mpixels/s (26.4 Mbytes/s)
Scroll Demo: 28.7 Mpixels/s (28.7 Mbytes/s)
FillBox with DrawHlineList: 73.1 Mpixels/s (73.1 Mbytes/s)
FillBox XOR: 37.9 Mpixels/s (37.9 Mbytes/s)
PutBitmap: 15.6 Mpixels/s (15.6 Mbytes/s)
1024x768x64K 72Hz: Replace QuixDemo: 12.3 Klines/s (5.2 Mpixels/s or 10.5 Mbytes/s)
Xor QuixDemo: 9.0 Klines/s (5.1 Mpixels/s or 10.3 Mbytes/s)
FillBox: 37.6 Mpixels/s (75.2 Mbytes/s)
ScreenCopy: 13.2 Mpixels/s (26.4 Mbytes/s)
Scroll Demo: 13.2 Mpixels/s (26.4 Mbytes/s)
FillBox with DrawHlineList: 37.0 Mpixels/s (74.0 Mbytes/s)
FillBox XOR: 18.9 Mpixels/s (37.8 Mbytes/s)
PutBitmap: 15.2 Mpixels/s (30.5 Mbytes/s)

You`re encouraged to send in more data. This demo is part of svgalib and can be found in the demos/ subdirectory of the original svgalib distribution. However, it is not installed in the system by default, s.t. it is unclear where you can find it if your svgalib was installed by some linux distribution. Even then, when you have the demo on your system, you probably won`t have the sources s.t. it is only of limited use for you.

In case of any such problem, simply get an svgalib distribution from the net. You even don`t need to install it. Just make in the demos/ subdirecty. As of this writing, svgalib-1.2.12.tar.gz is the latest version and can be retrieved by ftp from sunsite.unc.edu at /pub/Linux/libs/graphics and tsx-11.mit.edu at /pub/linux/sources/libs which will most probably be mirrored by a site close to you.

AUTHOR

This manual page was edited by Michael Weller <eowmob@exp-math.uni-essen.de>. The demo and most of its documentation is due to Harm Hanemaayer <H.Hanemaayer@inter.nl.net>.

accept

NAME

accept - accept a connection on a socket

SYNOPSIS

#include <sys/types.h>
#include <sys/socket.h>

int accept(int s, struct sockaddr *addr, socklen_t *addrlen);

DESCRIPTION

The accept function is used with connection-based socket types (SOCK_STREAM, SOCK_SEQPACKET and SOCK_RDM). It extracts the first connection request on the queue of pending connections, creates a new connected socket with mostly the same properties as s, and allocates a new file descriptor for the socket, which is returned. The newly created socket is no longer in the listening state. The original socket s is unaffected by this call. Note that any per file descriptor flags (everything that can be set with the F_SETFL fcntl, like non blocking or async state) are not inherited across an accept.

The argument s is a socket that has been created with socket(2), bound to a local address with bind(2), and is listening for connections after a listen(2).

The argument addr is a pointer to a sockaddr structure. This structure is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the address passed in the addr parameter is determined by the socket`s family (see socket(2) and the respective protocol man pages). The addrlen argument is a value-result parameter: it should initially contain the size of the structure pointed to by addr; on return it will contain the actual length (in bytes) of the address returned. When addr is NULL nothing is filled in.

If no pending connections are present on the queue, and the socket is not marked as non-blocking, accept blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, accept returns EAGAIN.

In order to be notified of incoming connections on a socket, you can use select(2) or poll(2). A readable event will be delivered when a new connection is attempted and you may then call accept to get a socket for that connection. Alternatively, you can set the socket to deliver SIGIO when activity occurs on a socket; see socket(7) for details.

For certain protocols which require an explicit confirmation, such as DECNet, accept can be thought of as merely dequeuing the next connection request and not implying confirmation. Confirmation can be implied by a normal read or write on the new file descriptor, and rejection can be implied by closing the new socket. Currently only DECNet has these semantics on Linux.

NOTES

There may not always be a connection waiting after a SIGIO is delivered or select(2) or poll(2) return a readability event because the connection might have been removed by an asynchronous network error or another thread before accept is called. If this happens then the call will block waiting for the next connection to arrive. To ensure that accept never blocks, the passed socket s needs to have the O_NONBLOCK flag set (see socket(7)).

RETURN VALUE

The call returns -1 on error. If it succeeds, it returns a non-negative integer that is a descriptor for the accepted socket.

ERROR HANDLING

Linux accept passes already-pending network errors on the new socket as an error code from accept. This behaviour differs from other BSD socket implementations. For reliable operation the application should detect the network errors defined for the protocol after accept and treat them like EAGAIN by retrying. In case of TCP/IP these are ENETDOWN, EPROTO, ENOPROTOOPT, EHOSTDOWN, ENONET, EHOSTUNREACH, EOPNOTSUPP, and ENETUNREACH.

ERRORS

accept shall fail if:

EAGAIN or EWOULDBLOCK: The socket is marked non-blocking and no connections are present to be accepted.
EBADF: The descriptor is invalid.
ENOTSOCK: The descriptor references a file, not a socket.
EOPNOTSUPP: The referenced socket is not of type SOCK_STREAM.
EINTR: The system call was interrupted by a signal that was caught before a valid connection arrived.
ECONNABORTED: A connection has been aborted.
EINVAL: Socket is not listening for connections.
EMFILE: The per-process limit of open file descriptors has been reached.
ENFILE: The system maximum for file descriptors has been reached.

accept may fail if:

EFAULT: The addr parameter is not in a writable part of the user address space.
ENOBUFS, ENOMEM: Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory.
EPROTO: Protocol error.

Linux accept may fail if:

EPERM: Firewall rules forbid connection.

In addition, network errors for the new socket and as defined for the protocol may be returned. Various Linux kernels can return other errors such as ENOSR, ESOCKTNOSUPPORT, EPROTONOSUPPORT, ETIMEDOUT. The value ERESTARTSYS may be seen during a trace.

CONFORMING TO

SVr4, 4.4BSD (the accept function first appeared in BSD 4.2). The BSD man page documents five possible error returns (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT). SUSv3 documents errors EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE, ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. In addition, SUSv2 documents EFAULT and ENOSR.

Linux accept does _not_ inherit socket flags like O_NONBLOCK. This behaviour differs from other BSD socket implementations. Portable programs should not rely on this behaviour and always set all required flags on the socket returned from accept.

NOTE

The third argument of accept was originally declared as an `int *` (and is that under libc4 and libc5 and on many other systems like BSD 4.*, SunOS 4, SGI); a POSIX 1003.1g draft standard wanted to change it into a `size_t *`, and that is what it is for SunOS 5. Later POSIX drafts have `socklen_t *`, and so do the Single Unix Specification and glibc2. Quoting Linus Torvalds: _Any_ sane library _must_ have "socklen_t" be the same size as int. Anything else breaks any BSD socket layer stuff. POSIX initially _did_ make it a size_t, and I (and hopefully others, but obviously not too many) complained to them very loudly indeed. Making it a size_t is completely broken, exactly because size_t very seldom is the same size as "int" on 64-bit architectures, for example. And it _has_ to be the same size as "int" because that`s what the BSD socket interface is. Anyway, the POSIX people eventually got a clue, and created "socklen_t". They shouldn`t have touched it in the first place, but once they did they felt it had to have a named type for some unfathomable reason (probably somebody didn`t like losing face over having done the original stupid thing, so they silently just renamed their blunder).

access

NAME

access - check user`s permissions for a file

SYNOPSIS

#include <unistd.h> int access(const char *pathname, int mode);

DESCRIPTION

access checks whether the process would be allowed to read, write or test for existence of the file (or other file system object) whose name is pathname. If pathname is a symbolic link permissions of the file referred to by this symbolic link are tested.

mode is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.

R_OK, W_OK and X_OK request checking whether the file exists and has read, write and execute permissions, respectively. F_OK just requests checking for the existence of the file.

The tests depend on the permissions of the directories occurring in the path to the file, as given in pathname, and on the permissions of directories and files referred to by symbolic links encountered on the way.

The check is done with the process`s real uid and gid, rather than with the effective ids as is done when actually attempting an operation. This is to allow set-UID programs to easily determine the invoking user`s authority.

Only access bits are checked, not the file type or contents. Therefore, if a directory is found to be "writable," it probably means that files can be created in the directory, and not that the directory can be written as a file. Similarly, a DOS file may be found to be "executable," but the execve(2) call will still fail.

If the process has appropriate privileges, an implementation may indicate success for X_OK even if none of the execute file permission bits are set.

RETURN VALUE

On success (all requested permissions granted), zero is returned. On error (at least one bit in mode asked for a permission that is denied, or some other error occurred), -1 is returned, and errno is set appropriately.

ERRORS

access shall fail if:

EACCES: The requested access would be denied to the file or search permission is denied to one of the directories in pathname.
ELOOP: Too many symbolic links were encountered in resolving pathname.
ENAMETOOLONG: pathname is too long.
ENOENT: A directory component in pathname would have been accessible but does not exist or was a dangling symbolic link.
ENOTDIR: A component used as a directory in pathname is not, in fact, a directory.
EROFS: Write permission was requested for a file on a read-only filesystem.

access may fail if:

EFAULT: pathname points outside your accessible address space.
EINVAL: mode was incorrectly specified.
EIO: An I/O error occurred.
ENOMEM: Insufficient kernel memory was available.
ETXTBSY: Write access was requested to an executable which is being executed.

RESTRICTIONS

access returns an error if any of the access types in the requested call fails, even if other types might be successful.

access may not work correctly on NFS file systems with UID mapping enabled, because UID mapping is done on the server and hidden from the client, which checks permissions.

Using access to check if a user is authorized to e.g. open a file before actually doing so using open(2) creates a security hole, because the user might exploit the short time interval between checking and opening the file to manipulate it.

CONFORMING TO

SVID, AT&T, POSIX, X/OPEN, BSD 4.3

acct

NAME

acct - execution accounting file

SYNOPSIS

#include <sys/acct.h>

DESCRIPTION

If the kernel was compiled with the process accounting option enabled, the system call

: acct("/somewhere/accountingfile");

will start the process accounting. Each time a process terminates a record for this process is appended to the accounting file. The accounting structure struct acct is also described in the file /usr/include/linux/acct.h.

accton

NAME

accton - turns process accounting on or off

SYNOPSIS

accton: [ -V | --version ] [ -h | --help ] [ filename ]

DESCRIPTION

accton filename turns on process accounting. If called with no arguments, it will, by default, stop process accounting.

OPTIONS

..PD 0


-V, --version: Print the version number of ac to standard output and quit.
-h, --help: Prints the usage string and default locations of system files to standard output and exits.

FILES

acct: The system wide process accounting file. See acct(5) (or pacct(5)) for further details.

AUTHOR

The GNU accounting utilities were written by Noel Cragg <noel@gnu.ai.mit.edu>. The man page was adapted from the accounting texinfo page by Susan Kleinmann <sgk@sgk.tiac.net>.

achfile

NAME

achfile - change type and/or creator of Apple Macintosh files (netatalk format)

SYNOPSIS

achfile [ -t type ] [ -c creator ] file ...

DESCRIPTION

achfile changes the Macintosh type and/or creator of the file arguments which have a corresponding .AppleDouble file.

OPTIONS

-t type: change the type.
-c creator: change the creator.

DIAGNOSTICS

returns exit status 0 if all files changed successfully

acl_add_perm

NAME

acl_add_perm - add a permission to an ACL permission set

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft int Fn acl_add_perm acl_permset_t permset_d acl_perm_t perm

DESCRIPTION

The Fn acl_add_perm function adds the permission contained in the argument perm to the permission set referred to by the argument permset_d An attempt to add a permission that is already contained in the permission set is not considered an error.

Any existing descriptors that refer to permset_d continue to refer to that permission set.

RETURN VALUE

Rv -std acl_add_perm

ERRORS

If any of the following conditions occur, the Fn acl_add_perm function returns -1 and sets errno to the corresponding value:

Bq Er EINVAL: The argument permset_d is not a valid descriptor for a permission set within an ACL entry.
The argument perm does not contain a valid acl_perm_t value.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_check

NAME

acl_check - check an ACL for validity

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In acl/libacl.h Ft int Fn acl_check acl_t acl int *last

DESCRIPTION

The Fn acl_check function checks the ACL referred to by the argument acl for validity.

The three required entries ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER must exist exactly once in the ACL. If the ACL contains any ACL_USER or ACL_GROUP entries, then an ACL_MASK entry is also required. The ACL may contain at most one ACL_MASK entry.

The user identifiers must be unique among all entries of type ACL_USER. The group identifiers must be unique among all entries of type ACL_GROUP.

If the ACL referred to by acl is invalid, Fn acl_check returns a positive error code that indicates which type of error was detected. The following symbolic error codes are defined:

ACL_MULTI_ERROR: The ACL contains multiple entries that have a tag type that may occur at most once.
ACL_DUPLICATE_ERROR: The ACL contains multiple ACL_USER entries with the same user ID, or multiple ACL_GROUP entries with the same group ID.
ACL_MISS_ERROR: A required entry is missing.
ACL_ENTRY_ERROR: The ACL contains an invalid entry tag type.

The Fn acl_error function can be used to translate error codes to text messages.

In addition, if the pointer last is not NULL Fn acl_check assigns the number of the ACL entry at which the error was detected to the value pointed to by last Entries are numbered starting with zero, in the order in which they would be returned by the Fn acl_get_entry function.

RETURN VALUE

If successful, the Fn acl_check function returns 0 if the ACL referred to by acl is valid, and a positive error code if the ACL is invalid. Otherwise, a value of -1 is returned and the global variable errno is set to indicate the error.

ERRORS

If any of the following conditions occur, the Fn acl_check function returns -1 and sets errno to the corresponding value:

Bq Er EINVAL: The argument acl is not a valid pointer to an ACL.

STANDARDS

This is a non-portable, Linux specific extension to the ACL manipulation functions defined in IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned).

AUTHOR

Written by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_cmp

NAME

acl_cmp - compare two ACLs

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In acl/libacl.h Ft int Fn acl_cmp acl_t acl1 acl_t acl2

DESCRIPTION

The Fn acl_cmp function compares the ACLs pointed to by the arguments acl1 and acl2 for equality. The two ACLs are considered equal if for each entry in acl1 there is an entry in acl2 with matching tag type, qualifier, and permissions, and vice versa.

RETURN VALUE

If successful, the Fn acl_cmp function returns 0 if the two ACLs acl1 and acl2 are equal, and 1 if they differ. Otherwise, the value -1 is returned and the global variable errno is set to indicate the error.

ERRORS

If any of the following conditions occur, the Fn acl_cmp function returns -1 and sets errno to the corresponding value:

Bq Er EINVAL: The argument acl1 is not a valid pointer to an ACL.
The argument acl2 is not a valid pointer to an ACL.

STANDARDS

This is a non-portable, Linux specific extension to the ACL manipulation functions defined in IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned).

AUTHOR

Written by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_copy_ext

NAME

acl_copy_ext - copy an ACL from internal to external representation

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft ssize_t Fn acl_copy_ext void *buf_p acl_t acl ssize_t size

DESCRIPTION

The Fn acl_copy_ext function copies the ACL pointed to by acl from system-managed space to the user managed space pointed to by buf_p The size parameter represents the size in bytes of the buffer pointed to by buf_p The format of the ACL placed in the buffer pointed to by buf_p is a contiguous, persistent data item, the format of which is unspecified. It is the responsibility of the invoker to allocate an area large enough to hold the copied ACL. The size of the exportable, contiguous, persistent form of the ACL may be obtained by invoking the Fn acl_size function.

Any ACL entry descriptors that refer to an entry in the ACL referenced by acl continue to refer to those entries. Any existing ACL pointers that refer to the ACL referenced by acl continue to refer to the ACL.

RETURN VALUE

Upon success, this function returns the number of bytes placed in the buffer pointed to by buf_p On error, a value of (ssize_t)-1 is returned and errno is set appropriately.

ERRORS

If any of the following conditions occur, the Fn acl_copy_ext function returns a value of (ssize_t)-1 and sets errno to the corresponding value:

Bq Er EINVAL

The size parameter is zero or negative.

The argument acl is not a valid pointer to an ACL.

The ACL referenced by acl contains one or more improperly formed ACL entries, or for some other reason cannot be translated into the external form of an ACL.

Bq Er ERANGE

The size parameter is greater than zero but smaller than the length of the contiguous, persistent form of the ACL.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_create_entry

NAME

acl_create_entry - create a new ACL entry

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft int Fn acl_create_entry acl_t *acl_p acl_entry_t *entry_p

DESCRIPTION

The Fn acl_create_entry function creates a new ACL entry in the ACL pointed to by the contents of the pointer argument acl_p On success, the function returns a descriptor for the new ACL entry via entry_p

This function may cause memory to be allocated. The caller should free any releasable memory, when the new ACL is no longer required, by calling acl_free3 with (void*)*acl_p as an argument. If the ACL working storage cannot be increased in the current location, then the working storage for the ACL pointed to by acl_p may be relocated and the previous working storage is released. A pointer to the new working storage is returned via acl_p

The components of the new ACL entry are initialized in the following ways: the ACL tag type component contains ACL_UNDEFINED_TAG, the qualifier component contains ACL_UNDEFINED_ID, and the set of permissions has no permissions enabled. Any existing ACL entry descriptors that refer to entries in the ACL continue to refer to those entries.

RETURN VALUE

Rv -std acl_create_entry

ERRORS

If any of the following conditions occur, the Fn acl_create_entry function returns -1 and sets errno to the corresponding value:

Bq Er EINVAL: The argument acl_p is not a valid pointer to an ACL.
Bq Er ENOMEM: The ACL working storage requires more memory than is allowed by the hardware or system-imposed memory management constraints.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_delete_entry

NAME

acl_delete_entry - delete an ACL entry

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft int Fn acl_delete_entry acl_t acl acl_entry_t entry_d

DESCRIPTION

The Fn acl_delete_entry function removes the ACL entry indicated by the entry_d descriptor from the ACL pointed to by acl Any existing ACL entry descriptors that refer to entries in acl other than that referred to by entry_d continue to refer to the same entries. The argument entry_d and any other ACL entry descriptors that refer to the same ACL entry are undefined after this function completes. Any existing ACL pointers that refer to the ACL referred to by acl continue to refer to the ACL.

RETURN VALUE

Rv -std acl_delete_entry

ERRORS

If any of the following conditions occur, the Fn acl_delete_entry function returns -1 and sets errno to the corresponding value:

Bq Er EINVAL: The argument acl_p is not a valid pointer to an ACL.
The argument entry_d is not a valid pointer to an ACL entry.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_dup

NAME

acl_dup - duplicate an ACL

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft acl_t Fn acl_dup acl_t acl

DESCRIPTION

The Fn acl_dup function returns a pointer to a copy of the ACL pointed to by acl

This function may cause memory to be allocated. The caller should free any releasable memory, when the new ACL is no longer required, by calling acl_free3 with the (void*)acl_t returned by Fn acl_dup as an argument.

RETURN VALUE

On success, this function returns a pointer to the working storage. On error, a value of (acl_t)NULL is returned, and errno is set appropriately.

ERRORS

If any of the following conditions occur, the Fn acl_dup function returns a value of (acl_t)NULL and sets errno to the corresponding value:

Bq Er EINVAL: The argument acl is not a valid pointer to an ACL.
Bq Er ENOMEM: The acl_t to be returned requires more memory than is allowed by the hardware or system-imposed memory management constraints.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_equiv_mode

NAME

acl_equiv_mode - check for an equivalent ACL

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In acl/libacl.h Ft int Fn acl_equiv_mode acl_t acl mode_t *mode_p

DESCRIPTION

The Fn acl_equiv_mode function checks if the ACL pointed to by the argument acl contains only the required ACL entries of tag types ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER, and contains no permissions other that ACL_READ, ACL_WRITE or ACL_EXECUTE. If the ACL has this form, it can can be fully represented with the traditional file permission bits, and is considered equivalent with the traditional file permission bits.

If acl is an equivalent ACL and the pointer mode_p is not NULL , the value pointed to by mode_p is set to the value that defines the same owner, group and other permissions as contained in the ACL.

RETURN VALUE

On success, this function returns the value 0 if acl is an equivalent ACL, and the value 1 if acl is not an equivalent ACL. On error, the value -1 is returned, and errno is set appropriately.

ERRORS

If any of the following conditions occur, the Fn acl_equiv_mode function returns the value -1 and sets errno to the corresponding value:

Bq Er EINVAL: The argument acl is not a valid pointer to an ACL.

STANDARDS

This is a non-portable, Linux specific extension to the ACL manipulation functions defined in IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned).

AUTHOR

Written by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_extended_fd

NAME

acl_extended_fd - test for information in the ACL by file descriptor

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In acl/libacl.h Ft int Fn acl_extended_fd int fd

DESCRIPTION

The Fn acl_extended_fd function returns 1 if the file identified by the argument fd is associated with an extended access ACL. The function returns 0 if the file does not have an extended access ACL.

An extended ACL is an ACL that contains entries other than the three required entries of tag types ACL_USER_OBJ, ACL_GROUP_OBJ and ACL_OTHER. If the result of the Fn acl_extended_fd function for a file object is 0 then the ACL defines no discretionary access rights other than those already defined by the traditional file permission bits.

Access to the file object may be further restricted by other mechanisms, such as Mandatory Access Control schemes. The access(2) system call can be used to check whether a given type of access to a file object would be granted.

RETURN VALUE

If successful, the Fn acl_extended_fd function returns 1 if the file object identified by fd has an extended access ACL, and 0 if the file object identified by fd does not have an extended access ACL. Otherwise, the value -1 is returned and the global variable errno is set to indicate the error.

ERRORS

If any of the following conditions occur, the Fn acl_extended_fd function returns -1 and sets errno to the corresponding value:

Bq Er EBADF: The fd argument is not a valid file descriptor.
Bq Er ENOTSUP: The file system on which the file identified by fd is located does not support ACLs, or ACLs are disabled.

STANDARDS

This is a non-portable, Linux specific extension to the ACL manipulation functions defined in IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned).

AUTHOR

Written by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_free

NAME

acl_free - release memory allocated to an ACL data object

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft int Fn acl_free void *obj_p

DESCRIPTION

The Fn acl_free function frees any releasable memory currently allocated by to the ACL data object identified by obj_p The argument obj_p may identify an ACL, an ACL entry qualifier, or a pointer to a string allocated by the Fn acl_to_text function.

RETURN VALUE

Rv -std acl_free

ERRORS

If any of the following conditions occur, the Fn acl_free function returns the value -1 and and sets errno to the corresponding value:

Bq Er EINVAL: The value of the argument obj_p is invalid.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_from_text

NAME

acl_from_text - create an ACL from text

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft acl_t Fn acl_from_text const char *buf_p

DESCRIPTION

The Fn acl_from_text function converts the text form of the ACL referred to by buf_p into the internal form of an ACL and returns a pointer to the working storage that contains the ACL. The Fn acl_from_text function accepts as input the long text form and short text form of an ACL as described in acl(5).

RETURN VALUE

On success, this function returns a pointer to the working storage. On error, a value of (acl_t)NULL is returned, and errno is set appropriately.

ERRORS

If any of the following conditions occur, the Fn acl_from_text function returns a value of (acl_t)NULL and sets errno to the corresponding value:

Bq Er EINVAL: The argument buf_p cannot be translated into an ACL.
Bq Er ENOMEM: The acl_t to be returned requires more memory than is allowed by the hardware or system-imposed memory management constraints.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_get_fd

NAME

acl_get_fd - get an ACL by file descriptor

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft acl_t Fn acl_get_fd int fd

DESCRIPTION

The Fn acl_get_fd function retrieves the access ACL associated with the file referred to by fd The ACL is placed into working storage and Fn acl_get_fd returns a pointer to that storage.

In order to read an ACL from an object, a process must have read access to the object`s attributes.

RETURN VALUE

On success, this function shall return a pointer to the working storage. On error, a value of (acl_t)NULL shall be returned, and errno is set appropriately.

ERRORS

If any of the following conditions occur, the Fn acl_get_fd function returns a value of (acl_t)NULL and sets errno to the corresponding value:

Bq Er EBADF: The fd argument is not a valid file descriptor.
Bq Er ENOMEM: The ACL working storage requires more memory than is allowed by the hardware or system-imposed memory management constraints.
Bq Er ENOTSUP: The file system on which the file identified by fd is located does not support ACLs, or ACLs are disabled.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_get_perm

NAME

acl_get_perm - test for a permission in an ACL permission set

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In acl/libacl.h Ft int Fn acl_get_perm acl_permset_t permset_d acl_perm_t perm

DESCRIPTION

The Fn acl_get_perm function tests if the permission specified by the argument perm is contained in the ACL permission set pointed to by the argument permset_d

Any existing descriptors that refer to permset_d continue to refer to that permission set.

RETURN VALUE

If successful, the Fn acl_get_perm function returns 1 if the permission specified by perm is contained in the ACL permission set permset_d and 0 if the permission is not contained in the permission set. Otherwise, the value -1 is returned and the global variable errno is set to indicate the error.

ERRORS

If any of the following conditions occur, the Fn acl_get_perm function returns -1 and sets errno to the corresponding value:

Bq Er EINVAL: The argument permset_d is not a valid descriptor for a permission set within an ACL entry.
The argument perm is not a valid acl_perm_t value.

STANDARDS

This is a non-portable, Linux specific extension to the ACL manipulation functions defined in IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned).

AUTHOR

Written by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_get_qualifier

NAME

acl_get_qualifier - retrieve the qualifier from an ACL entry

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft void * Fn acl_get_qualifier acl_entry_t entry_d

DESCRIPTION

The Fn acl_get_qualifier function retrieves the qualifier from the ACL entry indicated by the argument entry_d into working storage and returns a pointer to that storage.

If the value of the tag type in the ACL entry referred to by entry_d is ACL_USER, then the value returned by Fn acl_get_qualifier is a pointer to type uid_t If the value of the tag type in the ACL entry referred to by entry_d is ACL_GROUP, then the value returned by Fn acl_get_qualifier is a pointer to type gid_t If the tag type in the ACL entry referred to by entry_d is a tag type for which a qualifier is not supported, Fn acl_get_qualifier returns a value of (void *)NULL and the function fails. Subsequent operations using the returned pointer operate on an independent copy of the qualifier in working storage, and will not change the qualifier of the ACL entry.

This function may cause memory to be allocated. The caller should free any releasable memory, when the new qualifier is no longer required, by calling Fn acl_free with the void value returned by Fn acl_get_qualifier as an argument.

The argument entry_d and any other ACL entry descriptors that refer to entries within the ACL containing the entry referred to by entry_d continue to refer to those entries. The order of all existing entries in the ACL containing the entry referred to by entry_d remains unchanged.

RETURN VALUE

On success, the function returns a pointer to the tag qualifier that was retrieved into ACL working storage. On error, a value of (void *)NULL is returned and errno is set appropriately.

ERRORS

If any of the following conditions occur, the Fn acl_get_qualifier function returns (void *)NULL and sets errno to the corresponding value:

Bq Er EINVAL: The argument entry_d is not a valid descriptor for an ACL entry.
The value of the tag type in the ACL entry referenced by the argument entry_d is neither ACL_USER nor ACL_GROUP.
Bq Er ENOMEM: The value to be returned requires more memory than is allowed by the hardware or system-imposed memory management constraints.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_init

NAME

acl_init - initialize ACL working storage

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft acl_t Fn acl_init int count

DESCRIPTION

The Fn acl_init function allocates and initializes the working storage for an ACL of at least count ACL entries. The ACL created initially contains no ACL entries. A pointer to the working storage is returned.

RETURN VALUE

On success, this function returns a pointer to the working storage. On error, a value of (acl_t)NULL is returned, and errno is set appropriately.

ERRORS

If any of the following conditions occur, the Fn acl_init function returns a value of (acl_t)NULL and sets errno to the corresponding value:

Bq Er EINVAL: The value of count is less than zero.
Bq Er ENOMEM: The acl_t to be returned requires more memory than is allowed by the hardware or system-imposed memory management constraints.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_set_file

NAME

acl_set_file - set an ACL by filename

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft int Fn acl_set_file const char *path_p acl_type_t type acl_t acl

DESCRIPTION

The Fn acl_set_file function associates an access ACL with a file or directory, or associates a default ACL with a directory. The pathname for the file or directory is pointed to by the argument path_p

The effective user ID of the process must match the owner of the file or directory or the process must have the CAP_FOWNER capability for the request to succeed.

The value of the argument type is used to indicate whether the access ACL or the default ACL associated with path_p is being set. If the type parameter is ACL_TYPE_ACCESS, the access ACL of path_p shall be set. If the type parameter is ACL_TYPE_DEFAULT, the default ACL of path_p shall be set. If the argument type specifies a type of ACL that cannot be associated with path_p then the function fails.

The acl parameter must reference a valid ACL according to the rules described on the acl_valid3 manual page if the type parameter is ACL_TYPE_ACCESS, and must either reference a valid ACL or an ACL with zero ACL entries if the type parameter is ACL_TYPE_DEFAULT. If the acl parameter references an empty ACL, then the Fn acl_set_file function removes any default ACL associated with the directory referred to by the path_p parameter.

RETURN VALUE

Rv -std acl_set_file

ERRORS

If any of the following conditions occur, the Fn acl_set_file function returns -1 and sets errno to the corresponding value:

Bq Er EACCES

Search permission is denied for a component of the path prefix or the object exists and the process does not have appropriate access rights.

Argument type specifies a type of ACL that cannot be associated with path_p

Bq Er EINVAL

The argument acl does not point to a valid ACL.

The ACL has more entries than the file referred to by path_p can obtain.

The type parameter is not ACL_TYPE_ACCESS or ACL_TYPE_DEFAULT.

The type parameter is ACL_TYPE_DEFAULT, but the file referred to by path_p is not a directory.

Bq Er ENAMETOOLONG

The length of the argument path_p is too long.

Bq Er ENOENT

The named object does not exist or the argument path_p points to an empty string.

Bq Er ENOSPC

The directory or file system that would contain the new ACL cannot be extended or the file system is out of file allocation resources.

Bq Er ENOTDIR

A component of the path prefix is not a directory.

Bq Er ENOTSUP

The file identified by path_p cannot be associated with the ACL because the file system on which the file is located does not support this.

Bq Er EPERM

The process does not have appropriate privilege to perform the operation to set the ACL.

Bq Er EROFS

This function requires modification of a file system which is currently read-only.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

The behavior of Fn acl_set_file when the acl parameter refers to an empty ACL and the type parameter is ACL_TYPE_DEFAULT is an extension in the Linux implementation, in order that all values returned by Fn acl_get_file can be passed to Fn acl_set_file . The POSIX.1e function for removing a default ACL is Fn acl_delete_def_file .

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_set_qualifier

NAME

acl_set_qualifier - set the qualifier of an ACL entry

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft int Fn acl_set_qualifier acl_entry_t entry_d const void *qualifier_p

DESCRIPTION

The Fn acl_set_qualifier function sets the qualifier of the ACL entry indicated by the argument entry_d to the value referred to by the argument qualifier_p If the value of the tag type in the ACL entry referred to by entry_d is ACL_USER, then the value referred to by qualifier_p shall be of type uid_t If the value of the tag type in the ACL entry referred to by entry_d is ACL_GROUP, then the value referred to by qualifier_p shall be of type gid_t If the value of the tag type in the ACL entry referred to by entry_d is a tag type for which a qualifier is not supported, Fn acl_set_qualifier returns an error.

Any ACL entry descriptors that refer to the entry referred to by entry_d continue to refer to that entry. This function may cause memory to be allocated. The caller should free any releasable memory, when the ACL is no longer required, by calling Fn acl_free with a pointer to the ACL as argument.

RETURN VALUE

Rv -std acl_set_qualifier

ERRORS

If any of the following conditions occur, the Fn acl_set_qualifier function returns -1 and sets errno to the corresponding value:

Bq Er EINVAL

The argument entry_d is not a valid descriptor for an ACL entry.

The value of the tag type in the ACL entry referenced by the argument entry_d is neither ACL_USER nor ACL_GROUP.

The value pointed to by the argument qualifier_p is not valid.

Bq Er ENOMEM

The Fn acl_set_qualifier function is unable to allocate the memory required for the ACL qualifier.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_size

NAME

acl_size - get the size of the external representation of an ACL

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft ssize_t Fn acl_size acl_t acl

DESCRIPTION

The Fn acl_size function return the size, in bytes, of the buffer required to hold the exportable, contiguous, persistent form of the ACL pointed to by the argument acl when converted by Fn acl_copy_ext .

Any existing ACL entry descriptors that refer to entries in acl continue to refer to the same entries. Any existing ACL pointers that refer to the ACL referred to by acl continue to refer to the ACL. The order of ACL entries within acl remains unchanged.

RETURN VALUE

On success, the Fn acl_size function returns the size in bytes of the contiguous, persistent form of the ACL. On error, a value of (ssize_t)-1 is returned and errno is set appropriately.

ERRORS

If any of the following conditions occur, the Fn acl_size function returns a value of (ssize_t)-1 and sets errno to the corresponding value:

Bq Er EINVAL: The argument acl is not a valid pointer to an ACL.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

acl_to_text

NAME

acl_to_text - convert an ACL to text

LIBRARY

Linux Access Control Lists library (libacl, -lacl).

SYNOPSIS

In sys/types.h In sys/acl.h Ft char * Fn acl_to_text acl_t acl ssize_t *len_p

DESCRIPTION

The Fn acl_to_text function translates the ACL pointed to by the argument acl into a NULL terminated character string. If the pointer len_p is not NULL then the function returns the length of the string (not including the NULL terminator) in the location pointed to by len_p The format of the text string returned by Fn acl_to_text is the long text form defined in acl(5). The ACL referred to by acl is not changed.

This function allocates any memory necessary to contain the string and returns a pointer to the string. The caller should free any releasable memory, when the new string is no longer required, by calling acl_free3 with the (void*)char returned by Fn acl_to_text as an argument.

RETURN VALUE

On success, this function returns a pointer to the long text form of the ACL. On error, a value of (char *)NULL is returned, and errno is set appropriately.

ERRORS

If any of the following conditions occur, the Fn acl_to_text function returns a value of (char *)NULL and sets errno to the corresponding value:

Bq Er EINVAL: The argument acl is not a valid pointer to an ACL.
The ACL referenced by acl contains one or more improperly formed ACL entries, or for some other reason cannot be translated into a text form of an ACL.
Bq Er ENOMEM: The character string to be returned requires more memory than is allowed by the hardware or system-imposed memory management constraints.

STANDARDS

IEEE Std 1003.1e draft 17 (lqPOSIX.1erq, abandoned)

AUTHOR

Derived from the FreeBSD manual pages written by An Robert N M Watson Aq rwatson@FreeBSD.org , and adapted for Linux by An Andreas Gruenbacher Aq a.gruenbacher@computer.org .

aconnect

NAME

aconnect - ALSA sequencer connection manager

SYNOPSIS

aconnect [-d] [-options] sender receiver
aconnect -i|-o [-options]
aconnect -x

DESCRIPTION

aconnect is a utility to connect and disconnect two existing ports on ALSA sequencer system. The ports with the arbitrary subscription permission, such as created by aseqview(1), can be connected to any (MIDI) device ports using aconnect. For example, to connect from port 64:0 to 65:0, run as follows:

: % aconnect 64:0 65:0

The connection is one-way, and the whole data to the sender port (64:0) is redirected to the receiver port (65:0). When another port (e.g. 65:1) is attached to the same sender port, the data is sent to both receiver ports. For disconnection, use -d option.

: % aconnect -d 64:0 65:0

The address can be given using the client`s name.

: % aconnect External:0 Emu8000:1

Then the port 0 of the client matching with the string "External" is connected to the port 1 of the client matching with the "Emu8000".

Another function of aconnect is to list the present ports on the given condition. The input ports, which may become sender ports, can be listed with -i option.

: % aconnect -i
client 0: `System` [type=kernel] 0 `Timer `
1 `Announce ` client 64: `External MIDI-0` [type=kernel] 0 `MIDI 0-0 `

Similary, to see the output ports, use -o flag.

You can remove all existing exported connections using -x option. This function is useful for terminating the ALSA drivers, because the modules with sequencer connections cannot be unloaded unless their connections are removed.

OPTIONS

CONNNECTION MANAGEMENT

-d, --disconnect: Disconnect the given subscription.
-e, --exclusive: Connect ports with exclusive mode. Both sender and receiver ports can be no longer connected by any other ports.
-r, --real queue: Convert time-stamps of event packets to the current value of the given real-time queue. This is option is, however, not so useful, since the receiver port must use (not necessarily own) the specified queue.
-t, --tick queue: Like -r option, but time-stamps are converted to the current value of the given tick queue.

LIST PORTS

-i, --input: List existing input (readable) ports. This option is exclusive to -o.
-o, --output: List existing output (writable) ports. This option is exclusive to -i.
-l, --list: List the current connection status. The connected and connecting ports from/to each port are listed together. The suffix flag [ex] means the connection is exclusive. The suffix flag [real:#] and [tick:#] mean the connection includes real-time and tick conversion on the listed queue, respectively.

REMOVE ALL CONNECTIONS

-x, --removeall: Remove all exported connections.

AUTHOR

Takashi Iwai <tiwai@suse.de>

acosf

NAME

acos, acosf, acosl - arc cosine function

SYNOPSIS

#include <math.h> double acos(double x); float acosf(float x); long double acosl(long double x);

DESCRIPTION

The acos() function calculates the arc cosine of x; that is the value whose cosine is x. If x falls outside the range -1 to 1, acos() fails and errno is set.

RETURN VALUE

The acos() function returns the arc cosine in radians and the value is mathematically defined to be between 0 and PI (inclusive).

ERRORS

EDOM: x is out of range.

CONFORMING TO

SVID 3, POSIX, BSD 4.3, ISO 9899. The float and long double variants are C99 requirements.

acoshf

NAME

acosh, acoshf, acoshl - inverse hyperbolic cosine function

SYNOPSIS

#include <math.h> double acosh(double x); float acoshf(float x); long double acoshl(long double x);

DESCRIPTION

The acosh() function calculates the inverse hyperbolic cosine of x; that is the value whose hyperbolic cosine is x. If x is less than 1.0, acosh() returns not-a-number (NaN) and errno is set.

ERRORS

EDOM: x is out of range.

CONFORMING TO

SVID 3, POSIX, BSD 4.3, ISO 9899. The float and long double variants are C99 requirements.

acosl

NAME

acos, acosf, acosl - arc cosine function

SYNOPSIS

#include <math.h> double acos(double x); float acosf(float x); long double acosl(long double x);

DESCRIPTION

The acos() function calculates the arc cosine of x; that is the value whose cosine is x. If x falls outside the range -1 to 1, acos() fails and errno is set.

RETURN VALUE

The acos() function returns the arc cosine in radians and the value is mathematically defined to be between 0 and PI (inclusive).

ERRORS

EDOM: x is out of range.

CONFORMING TO

SVID 3, POSIX, BSD 4.3, ISO 9899. The float and long double variants are C99 requirements.

acpi_listen

NAME

acpi_listen - ACPI event listener

SYNOPSIS

acpi_listen [options]

DESCRIPTION

acpid is the sysem-wide ACPI event catcher. acpi_listen is a simple shell-friendly tool which connects to acpid and listens for events. When an event occurs, acpi_listen will print it on stdout.

OPTIONS

-c, --count events: Receive up to a maximum number of ACPI events, then exit.
-s, --socketfile filename: This option changes the name of the UNIX domain socket which acpid opens. Default is /var/run/acpid.socket.
-t, --time seconds: Listen for the specified time in seconds, before exiting.
-v, --version: Print version information and exit.
-h, --help: Show help and exit.

FILES

/var/run/acpid.socket

BUGS

There are no known bugs. To file bug reports, see AUTHORS below.

AUTHORS

Tim Hockin <thockin@sun.com>
Luca Capello <luca@pca.it>

actsync

NAME

actsync, actsyncd - synchronize newsgroups

SYNOPSIS

actsync [-b hostid] [-d hostid] [-g max] [-i ignore_file]
        [-I hostid] [-k] [-l hostid] [-m] [-n name]

        [-o fmt] [-p min_%_unchg] [-q hostid] [-s size]

        [-s spool_dir] [-t hostid] [-T] [-v verbose_lvl]

        [-z sec] [host1] host2

actsyncd [-x] actsync.cfg [debug_level [debug_outfmt] ]

DESCRIPTION

Actsync(8) permits one to synchronize, compare or merge two active(5) files. With this utility one may add, change or remove newsgroups on the local news server to make it similar to the list the newsgroups found on another system or file. The synchronization need not be exact. Local differences in newsgroup lists may be maintained and preserved. Certain newsgroup errors may be detected and optionally corrected.

There are several reasons to run actsync(8) (or actsyncd(8)), on a periodic basis. Among the reasons are:

A control message to add, change or remove a newsgroup may fail to reach your site.

Your control.ctl(5) is out of date or incomplete.

News articles for a new newsgroup arrive ahead (sometimes days ahead) of the control message.

Control messages may be forged, thus bypassing the restrictions found in control.ctl(5).

Your active(5) file may have been trashed.

If either host1 or host2 begin with a ``.`` or ``/``, then they assumed to be a name of a file containing information in the active(5) format. The getlist(1) utility may be used to obtain copy a remote system`s active file via its NNTP server, or an FTP client program can get retrieve such a file from an FTP archive (such as ftp://ftp.isc.org/pub/usenet/CONFIG/active; see more about this below). Newsgroup information from a file may be treated as if it was obtained from a host. In this man page host1 and host2 are called hosts, even though they may be file names.

If a host argument does not begin with ``.`` or ``/``, is assumed to be a hostname or Internet address. In this case, actsync(8) will attempt to use the NNTP protocol to obtain a copy of the the specified system`s active file. If the host argument contains a ``:`` , the right side will be considerd the port to connect to on the remote system. If no port number ist specified, actsync(8) will connect to port 119.

Regardless how the active file information is obtained, the actions of actsync(8) remain the same.

If only one host is specified, it is assumed to be host2. If host1, is not specified, it assumed to be the default local NNTP server as specified by the NNTPSERVER environment variable, or by the server value found in inn.conf(5).

The newsgroup synchronization by default, involves all newsgroups found on both hosts. One may also synchronize on a subset of newsgroups by directing actsync(8) to ignore certain newsgroups from both systems.

The actsyncd(8) daemon provides a convenient interface to configure and run actsync(8). If a host is not initially reachable, the daemon will thrice retry 9 times, waiting 6 minutes before each retry. This daemon runs in the foreground, sending output to standard output and standard error.

If the -x flag is given to actsyncd(8), then a ctlinndxexec will be used instead of a ctlinndreload to load the newly modified active file.

The configuration filename for the daemon is given in the actsync.cfg argument. The actsync.cfg file understands the following options:

host=host2 ftppath=/remote/path/to/active/file spool=<normally patharticles in inn.conf> ignore_file=ignore_file flags=actsyncd (8) options

The host, ignore_file and flags lines are mandatory.

The keyword must start at the beginning of the line, and there may be no whitespace before the ``=`` character. Blank lines are ignored. Comments start with ``#`` and are ignored. All other lines may produce undefined results.

The host config file line refers to the host2 value to sync off of. The ftppath directive causes the machine named in the host line to accessed as an ftp server, retrieving the file named. If the filename ends in .gz or .Z, then it will automatically be uncompressed after retrieval. The spool config file lines determines where top the news spool tree is to be found. The ignore_file config file line names the ignore file to be used by actsync(8). The flags config file line refers to all flags that you wish to pass to actsync(8).

Note that the -i ignore_file option and the -o format option should not be given in the flags= line because they are automatically taken care of by actsyncd(8).

INN is shipped with default values of ftp.isc.org for host and /pub/usenet/CONFIG/active for ftppath. You can read about the policies used for maintaining that active file at ftp://ftp.isc.org/pub/usenet/CONFIG/README. Consider sychronizing from this file on a daily basis by using cron.

OPTIONS

The options to actsync(8) are as follows:

-b hostid

This flag causes actsync(8) to ignore newsgroups with ``bork.bork.bork`` style names. That is, newsgroups whose last 3 components are identical. For example, the following newsgroups have bork style names:

alt.helms.dork.dork.dork alt.auto.accident.sue.sue.sue alt.election.vote.vote.vote

The value hostid determines on which hosts this action is performed:

0 neither host 1 local default server 2 remove server 12 both servers 21 both servers

The default is -b 0, no bork newsgroups are ignored.

-d hostid

This flag causes actsync(8) to ignore newsgroups that have all numeric path components. The hostid value is interpreted the same as in -b. For example, the following newsgroups have numeric path components:

alt.prime.chongo.23209 391581.times.2.to_the.216193.power.-1 99.bottles.of.treacle.on.the.wall linfield.class.envio_bio.101.d

The newsgroups directory of a newsgroups with a all numeric component could conflict with an article from another group. For example, the directory for the first newsgroup listed above is the same path as article number 23209 from the newsgroup:

alt.prime.chongo

The default is -d 0, all numeric newsgroups from both hosts will be processed.

-g max

Ignore any newsgroup with more than max levels. For example, -g 6 would ignore:

alt.feinstien.votes.to.trash.freedom.of.speech alt.senator.exon.enemy.of.the.internet alt.crypto.export.laws.dumb.dumb.dumb

but would not ignore:

alt.feinstien.acts.like.a.republican alt.exon.admendment alt.crypto.export.laws

If max is 0, then the max level feature is disabled.

By default, the max level feature is disabled.

-i ignore_file

The ignore_file allows one to have a fine degree of control over which newsgroups are ignored. It contains a set of rules that specifies which newsgroups will be checked and which will be ignored.

By default, these rules apply to both hosts. This can be modified by using the -I hostid flag.

By default, all newsgroups are checked. If no ignore_file if specified, or if the ignore file contains no rule lines, all newsgroups will be checked.

Blank lines, and text after a ``#`` are considered comments and are ignored.

Rule lines consist of tokens separated by whitespace. Rule lines may be one of two forms:

c newsgroup [type ...] i newsgroup [type ...]

If the rule begins with a c then the rule requests certain newsgroups to be checked. If the rule begins with an i then the rule requests certain newsgroups to be ignored. The newsgroup field may be a specific newsgroup, or a wildmat(3) pattern.

If one or more types are specified, then the rule applies to the newsgroup only if is of the specified type. Types refer to the 4th field of the active(5) file. A type may be one of:

y n m j x =group.name

Unlike active files, the group.name may be a newsgroup name or a wildmat(3) pattern. Also, ``=`` is equivalent to ``=*``.

For given rule line may, one may not repeat a given pattern type. For example, one may not have more than one type that begins with ``=``, per line. However, one may achieve the effect of multiple ``=`` types by using multiple rule lines for the same group.

By default, all newsgroups are candidates to be checked. If an ignore file is used, each newsgroup in turn is checked against the ignore file. If multiple lines match a given newsgroup, the last line in the ignore file is used.

For example, consider the following ignore file lines:

i *.general c *.general m i nsa.general

The newsgroup: ba.general would be ignored if it was not moderated. The newsgroup: mod.general would be checked if it was moderated. The newsgroup: nsa.general would be ignored even if it was moderated.

-I hostid

This flag restricts which hosts, the ignore file applies. The hostid value is interpreted the same as in -b.

This flag may be useful in conjunction with the -m merge flag. For example:

actsync -i actsync.ign -I 2 -m host1 host2

will keep all newsgroups currently on host1. It will also will only compare host1 groups with non-ignored newsgroups from host2.

The default is -I 12, newsgroups from both hosts to be ignored per the -I hostid flag.

-k

By default, any newsgroup on host1 that is in error will be considered for removal. This causes actsync(8) simply ignore such newsgroups. This flag, in combination with -m will prevent any newsgroup from being scheduled for removal.

-l hostid

Flag problem newsgroups of type ``=`` from host1 or host2 as errors. The hostid value is interpreted the same as in -b. Newsgroups of type ``=`` are newsgroups active entries that have 4th field that begins with ``=``. I.e., a newsgroup that is equivalent to another newsgroup.

A newsgroup that is equivalent to itself, or that is in a equivalence chain that loops around to itself is a problem. A newsgroup that is in a chain that is longer than 16 is a problem group. A newsgroup that is equivalent to a non-existent newsgroup is a problem. A newsgroup that is equivalent to a newsgroup that is has a error of some kind a problem. However, a newsgroup that is equivalent to an ignored newsgroup is not a problem.

By default, problem newsgroups from both hosts are marked as errors.

-m

Merge newsgroups instead of sync. By default, if a newsgroup exists on host1 but not host2, it will be scheduled to be removed. This flag disables this process, permitting newsgroups unique to host1 to be kept.

-n name

Newsgroups that are created, are created via the ctlinnd(8) command. By default, the creator name used is actsync. This flag changes the creator name to name.

-o fmt

Determine the output / action format of this utility. The fmt may one of:

a output in active(5) format, a1 output in active(5) format, and output host1 non-error ignored groups ak output in active(5) format, but use host2 hi & low (2nd & 3rd active fields) values for any newsgroup being created aK output in active(5) format, but use host2 hi & low (2nd & 3rd active fields) values for all newsgroups found in host2 a1k output in active(5) format, but use host2 hi & low (2nd & 3rd active fields) values for any newsgroup being created, and output host1 non-error ignored groups a1K output in active(5) format, but use host2 hi & low (2nd & 3rd active fields) values for all newsgroups found in host2, and output host1 non-error ignored groups ak1 same as a1k aK1 same as a1K c output in ctlinnd(8) format x no output, directly exec ctlinnd(8) commands xi no output, directly exec ctlinnd(8) commands, in an interactive mode

The a, a1, ak, aK, a1k, a1K, ak1 and aK1 style formats allow one to form a new active file instead of producing ctlinnd(8) commands. They use hi & low values of 0000000000 and 0000000001 respectively for newsgroups that are created. The ak and aK variants change the the hi & low (2nd & 3rd active fields). In the case of ak, newsgroups created take their hi & low values from host2. In the case of aK, all newsgroups found on host2 take their hi & low values from host2.

The c format produces ctlinnd(8) commands. No actions are taken because actsync(8) simply prints ctlinnd(8) commands on standard output. The sync (or merge if -m) with host2 may be accomplished by piping this output into sh(1). A paranoid person might prefer to use x or xi in case a newsgroup name or type contains bogus characters that might be interpreted by sh(1). Even so, this output format is useful to let you see how host1 may be synced (or merge) with host2.

The sync (or merge if -m) may be accomplished directly by use of the x. With this format, actsync(8) uses the execl(2) system call to directly executes ctlinnd(8) commands. Because of the exec, there is no risk of bogus newsgroups containing bogus characters causing a shell to do bogus (or dangerous) things. The output of such execs may be seen of the verbosity level is at least 2.

The actsync(8) utility will pause for 4 seconds before each command is executed if -o x is selected. See the -z sec flag below.

The xi format interactively prompts on standard output and reads directives on standard input. One may pick and choose changes using this format.

Care should be taken when producing active(5) formatted output. One should check to be sure that actsync(8) exited with a zero status prior to using such output. Also one should realize that such output will not contain lines ignored by the -i ignore_file process even if -p 100 is used.

By default, -o c is assumed.

-p min_%_unchg

By default, the actsync(8) utility has safeguards against performing massive changes. If fewer than min_%_unchg percent of the non-ignored lines from host1 remain unchanged, no actions (output, execution, etc.) are performed and actsync(8) exits with a non-zero exit status. The min_%_unchg may be a floating point value such as 66.666.

A change is considered a host1 line that was found to be in error, was removed, was added or was changed. Changing the 2nd or 3rd active fields via -oak or -o aK are not considered changes by -p.

To force actsync(8) to accept any amount of change, use the -p 0 option. To force actsync(8) to reject any changes, use the -p 100 option.

By default, 96% of the lines not ignored in host1 must be unchanged. That is, by default, -p 90 is assumed.

-q hostid

By default, all newsgroup errors are reported on standard errors. This flag quiets errors from host1 or host2. The hostid value is interpreted the same as in -b.

-s size

If size>0, then ignore newsgroups with names longer than size, and ignore newsgroups equivalenced to names longer than size. Length checking is perform on both the local and remote hosts.

By default, size is 0 and thus no length checking is performed.

-t hostid

Ignore improper newsgroups with only a top component from host1 or host2. The hostid value is interpreted the same as in -b. The following newsgroups are considered proper newsgroups for top only names:

control general junk test to

For example, the following newsgroup names are improper because they only contain a top level component:

dole_for_pres dos microsoft windoes95

By default, all improper top level only newsgroups from the remote ( -t 2 ) are ignored.

-T

This flag causes host2 newsgroups from new hierarchies to be ignored. Normally if only host2 has the newsgroup chongo.was.here then it will be created for host1. However if host1 does not have any `chongo.*` newsgroups and this flag is given, then chongo.was.here will be ignored and will not be created on host1.

-v verbose_lvl

No default, actsync(8) is not verbose. This flag controls the verbosity level as follows:

0 no debug or status reports (default) 1 print summary, if work was needed or done 2 print actions, exec output & summary, if work was needed or done 3 print actions, exec output & summary 4 full debug output

-z sec

If -o x is selected, actsync(8) will pause for sec seconds before each command is executed. This helps prevent innd(8) from being busied-out if a large number of ctlinnd(8) commands are needed. One can disable this sleeping by using -z 0.

By default, actsync(8) will pause for 4 seconds before each command is executed if -o x is selected.

EXAMPLES

Determine the difference (but don`t change anything) between your newsgroup set and uunet`s set:

actsync news.uu.net

Same as above, with full debug and progress reports:

actsync -v 4 news.uu.net

Force a site to have the same newsgroups some other site:

actsync -o x master

This may be useful to sync a slave site to its master, or to sync internal site to a gateway.

Compare your site with uunet, disregarding local groups and certain local differences with uunet. Produce a report if any differences were encountered:

actsync -v 2 -i actsync.ign news.uu.net

where actsync.ign contains:

# Don`t compare to.* groups as they will differ. # i to.* # These are our local groups that nobody else # (should) carry. So ignore them for the sake # of the compare. # i nsa.* # These groups are local favorites, so keep them # even if uunet does not carry them. # i ca.dump.bob.dorman i ca.keep.bob.dorman i alt.tv.dinosaurs.barney.die.die.die i alt.tv.dinosaurs.barney.love.love.love i alt.sounds.* =alt.binaries.sounds.*

To interactively sync against news.uu.net, using the same ignore file:

actsync -o xi -v 2 -i actsync.ign news.uu.net

Based on newsgroups that you decided to keep, one could make changes to the actsync.ign file:

# Don`t compare to.* groups as they will differ. # i to.* # These are our local groups that nobody else # (should) carry. So ignore them for the sake # of the compare. # i nsa.* # These groups are local favorites, so keep them # even if uunet does not carry them. # i ca.dump.bob.dorman i alt.tv.dinosaurs.barney.die.die.die i alt.sounds.* =alt.binaries.sounds.* # Don`t sync test groups, except for ones that are # moderated or that are under the gnu hierarchy. i *.test c *.test m # check moderated test groups c gnu.*.test c gnu.test # just in case it ever exists

Automatic processing may be setup by using the following actsync.cfg file:

# host to sync off of (host2) host=news.uu.net # location of the ignore file ignore_file=<PREFIX specified with --prefix at configure>/etc/actsync.ign # where news articles are kept spool=<patharticles in inn.conf> # actsync(8) flags # # Automatic execs, report if something was done, # otherwise don`t say anything, don`t report # uunet active file problems, just ignore # the effect entries. flags=-o x -v 2 -q 2

and then by running actsyncd(8) with the path to the config file.

actsyncd <PREFIX specified with --prefix at configure>/etc/actsync.cfg

One may produce a trial actsyncd(8) run without changing anything on the server by supplying the debug_level arg:

actsyncd <PREFIX specified with --prefix at configure>/etc/actsync.cfg 2

The debug_level causes actsyncd(8) to run actsync(8) with an -v debug_level (overriding any -v flag on the flags line), prevents any changes from being made to the active(5) file, writes a new active file to standard output and writes debug messages to standard error.

If the debug_outfmt arg is also given to actsyncd(8) then the data written to standard output will be in -o debug_outfmt instead of in -o a1 format. The following /bin/sh command:

actsyncd <PREFIX specified with --prefix at configure>/etc/actsync.cfg 4 >cmd 2>dbg

Will operate in debug mode, not change the active(5) file, write ctlinnd(8) style commands to cmd and write debug statements to dbg.

To check only the major hierarchies against news.uu,net, use the following actsync.ign file:

# by default, ignore everything i * # check the major groups c comp.* c gnu.* c sci.* c alt.* c misc.* c news.* c rec.* c soc.* c talk.*

and running:

actsync -i actsync.ign news.uu.net

To determine the differences between your old active and your current default server:

actsync <pathetc in inn.conf>/active.old -

To report but not fix any newsgroup problems with the current active file:

actsync - -

To detect any newsgroup errors on your local server, and to remove any *.bork.bork.bork style silly newsgroup names:

actsync -b 2 - -

The active file produced by:

actsync ... flags ... -o x erehwon.honey.edu

or by:

actsync ... flags ... -o c erehwon.honey.edu | sh

is effectively the same as the active file produced by:

ctlinnd pause `running actsync` rm -f active.new actsync ... flags ... -o a1 erehwon.honey.edu > active.new rm -f active.old ln active active.old mv active.new active ctlinnd reload active `running actsync` ctlinnd go `running actsync`

It should be noted that the above `pause`, `actsync`, `reload` and `go` method is faster.

CAUTION

Careless use of this tool may result in the addition change or removal of newsgroups that you don`t want. You should avoid using the x output format until you are sure it will do what you want.

BUGS

If a newsgroup appears multiple times, actsync(8) will treat all copies as errors. However, if the group is marked for removal, only one rmgroup will be issued.

The timeout for ctlinnd(8) commands is fixed at 30 seconds when running in ``x`` or ``xi`` output format. Perhaps the timeout value should be controlled via a command line option?

HISTORY

Written by Landon Curt Noll <chongo@toad.com> for InterNetNews. Updated to support ftp fetching by David Lawrence <tale@isc.org>.

acyclic

NAME

acyclic - make directed graph acyclic

SYNOPSIS

acyclic [ -nv? ] [ -o outfile ] [ file ]

DESCRIPTION

acyclic is a filter that takes a directed graph as input and outputs a copy of the graph with sufficient edges reversed to make the graph acyclic. The reversed edge inherits all of the attributes of the original edge. The optional file argument specifies where the the input graph is stored; by default, the program reads from stdin.

OPTIONS

The following options are supported:

-n: No output is produced, though the return value will indicate whether the graph is acyclic or not.
-v: Print information about whether the file is acyclic, has a cycle or is undirected.
-o outfile: causes the output to be written to the specified file; by default, output is written to stdout.
-?: option causes the program to print usage information.

RETURN CODES

acyclic returns 0 if the graph is acyclic; 1 if the graph has a cycle; 2 if the graph is undirected; and 255 if there are any errors.

BUGS

If the graph is strict and there is a cycle of length 2, the attributes of the reversed edge are lost.

Some edge attributes are non-symmetric, referring to either the head or tail node. At present, there is no mechanism or convention for for correctly switching or renaming these.

AUTHORS

Stephen C. North <north@research.att.com>
Emden R. Gansner <erg@research.att.com>

addchnstr

NAME

addchstr, addchnstr, waddchstr, waddchnstr, mvaddchstr, mvaddchnstr, mvwaddchstr, mvwaddchnstr - add a string of characters (and attributes) to a curses window

SYNOPSIS

#include <curses.h>

int addchstr(const chtype *chstr);
int addchnstr(const chtype *chstr, int n);
int waddchstr(WINDOW *win, const chtype *chstr);
int waddchnstr(WINDOW *win, const chtype *chstr, int n);
int mvaddchstr(int y, int x, const chtype *chstr);
int mvaddchnstr(int y, int x, const chtype *chstr, int n);
int mvwaddchstr(WINDOW *win, int y, int x, const chtype *chstr);
int mvwaddchnstr(WINDOW *win, int y, int x, const chtype *chstr, int n);

DESCRIPTION

These routines copy chstr into the window image structure at and after the current cursor position. The four routines with n as the last argument copy at most n elements, but no more than will fit on the line. If n=-1 then the whole string is copied, to the maximum number of characters that will fit on the line.

The window cursor is not advanced, and these routines work faster than waddnstr. On the other hand, they don`t perform any kind of checking (such as for the newline, backspace, or carriage return characters), they don`t advance the current cursor position, they don`t expand other control characters to ^-escapes, and they truncate the string if it crosses the right margin, rather then wrapping it around to the new line.

RETURN VALUES

All routines return the integer ERR upon failure and OK on success (the SVr4 manuals specify only "an integer value other than ERR") upon successful completion, unless otherwise noted in the preceding routine descriptions.

NOTES

Note that all routines except waddchnstr may be macros.

PORTABILITY

All these entry points are described in the XSI Curses standard, Issue 4.

AddErrInfo

NAME

Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo - record information about errors

SYNOPSIS

#include <tcl.h> Tcl_AddObjErrorInfo(interp, message, length) Tcl_AddErrorInfo(interp, message) Tcl_SetObjErrorCode(interp, errorObjPtr) Tcl_SetErrorCode(interp, element, element, ... (char *) NULL) Tcl_SetErrorCodeVA(interp, argList) CONST char * Tcl_PosixError(interp) void Tcl_LogCommandInfo(interp, script, command, commandLength)

ARGUMENTS

Tcl_Interp *interp (in)
Interpreter in which to record information.

char *message (in)
For Tcl_AddObjErrorInfo, this points to the first byte of an array of bytes containing a string to record in the errorInfo variable. This byte array may contain embedded null bytes unless length is negative. For Tcl_AddErrorInfo, this is a conventional C string to record in the errorInfo variable.

int length (in)
The number of bytes to copy from message when setting the errorInfo variable. If negative, all bytes up to the first null byte are used.

Tcl_Obj *errorObjPtr (in)
This variable errorCode will be set to this value.

char *element (in)
String to record as one element of errorCode variable. Last element argument must be NULL.

va_list argList (in)
An argument list which must have been initialized using TCL_VARARGS_START, and cleared using va_end.

CONST char *script (in)
Pointer to first character in script containing command (must be <= command)

CONST char *command (in)
Pointer to first character in command that generated the error

int commandLength (in)
Number of bytes in command; -1 means use all bytes up to first null byte

DESCRIPTION

These procedures are used to manipulate two Tcl global variables that hold information about errors. The variable errorInfo holds a stack trace of the operations that were in progress when an error occurred, and is intended to be human-readable. The variable errorCode holds a list of items that are intended to be machine-readable. The first item in errorCode identifies the class of error that occurred (e.g. POSIX means an error occurred in a POSIX system call) and additional elements in errorCode hold additional pieces of information that depend on the class. See the Tcl overview manual entry for details on the various formats for errorCode.

The errorInfo variable is gradually built up as an error unwinds through the nested operations. Each time an error code is returned to Tcl_EvalObjEx (or Tcl_Eval, which calls Tcl_EvalObjEx) it calls the procedure Tcl_AddObjErrorInfo to add additional text to errorInfo describing the command that was being executed when the error occurred. By the time the error has been passed all the way back to the application, it will contain a complete trace of the activity in progress when the error occurred.

It is sometimes useful to add additional information to errorInfo beyond what can be supplied automatically by Tcl_EvalObjEx. Tcl_AddObjErrorInfo may be used for this purpose: its message and length arguments describe an additional string to be appended to errorInfo. For example, the source command calls Tcl_AddObjErrorInfo to record the name of the file being processed and the line number on which the error occurred; for Tcl procedures, the procedure name and line number within the procedure are recorded, and so on. The best time to call Tcl_AddObjErrorInfo is just after Tcl_EvalObjEx has returned TCL_ERROR. In calling Tcl_AddObjErrorInfo, you may find it useful to use the errorLine field of the interpreter (see the Tcl_Interp manual entry for details).

Tcl_AddErrorInfo resembles Tcl_AddObjErrorInfo but differs in initializing errorInfo from the string value of the interpreter`s result if the error is just starting to be logged. It does not use the result as a Tcl object so any embedded null characters in the result will cause information to be lost. It also takes a conventional C string in message instead of Tcl_AddObjErrorInfo`s counted string.

The procedure Tcl_SetObjErrorCode is used to set the errorCode variable. errorObjPtr contains a list object built up by the caller. errorCode is set to this value. Tcl_SetObjErrorCode is typically invoked just before returning an error in an object command. If an error is returned without calling Tcl_SetObjErrorCode or Tcl_SetErrorCode the Tcl interpreter automatically sets errorCode to NONE.

The procedure Tcl_SetErrorCode is also used to set the errorCode variable. However, it takes one or more strings to record instead of an object. Otherwise, it is similar to Tcl_SetObjErrorCode in behavior.

Tcl_SetErrorCodeVA is the same as Tcl_SetErrorCode except that instead of taking a variable number of arguments it takes an argument list.

Tcl_PosixError sets the errorCode variable after an error in a POSIX kernel call. It reads the value of the errno C variable and calls Tcl_SetErrorCode to set errorCode in the POSIX format. The caller must previously have called Tcl_SetErrno to set errno; this is necessary on some platforms (e.g. Windows) where Tcl is linked into an application as a shared library, or when the error occurs in a dynamically loaded extension. See the manual entry for Tcl_SetErrno for more information.

Tcl_PosixError returns a human-readable diagnostic message for the error (this is the same value that will appear as the third element in errorCode). It may be convenient to include this string as part of the error message returned to the application in the interpreter`s result.

Tcl_LogCommandInfo is invoked after an error occurs in an interpreter. It adds information about the command that was being executed when the error occurred to the errorInfo variable, and the line number stored internally in the interpreter is set. On the first call to Tcl_LogCommandInfo or Tcl_AddObjErrorInfo since an error occurred, the old information in errorInfo is deleted.

It is important to call the procedures described here rather than setting errorInfo or errorCode directly with Tcl_ObjSetVar2. The reason for this is that the Tcl interpreter keeps information about whether these procedures have been called. For example, the first time Tcl_AddObjErrorInfo is called for an error, it clears the existing value of errorInfo and adds the error message in the interpreter`s result to the variable before appending message; in subsequent calls, it just appends the new message. When Tcl_SetErrorCode is called, it sets a flag indicating that errorCode has been set; this allows the Tcl interpreter to set errorCode to NONE if it receives an error return when Tcl_SetErrorCode hasn`t been called.

If the procedure Tcl_ResetResult is called, it clears all of the state associated with errorInfo and errorCode (but it doesn`t actually modify the variables). If an error had occurred, this will clear the error state to make it appear as if no error had occurred after all.

KEYWORDS

error, object, object result, stack, trace, variable

addmntent

NAME

getmntent, setmntent, addmntent, endmntent, hasmntopt, getmntent_r - get file system descriptor file entry

SYNOPSIS

#include <stdio.h> #include <mntent.h> FILE *setmntent(const char *filename, const char *type); struct mntent *getmntent(FILE *fp); int addmntent(FILE *fp, const struct mntent *mnt); int endmntent(FILE *fp); char *hasmntopt(const struct mntent *mnt, const char *opt); /* GNU extension */ #define _GNU_SOURCE /* or _SVID_SOURCE or _BSD_SOURCE */ #include <mntent.h> struct mntent *getmntent_r(FILE *fp, struct mntent *mntbuf, char *buf, int buflen);

DESCRIPTION

These routines are used to access the file system description file /etc/fstab and the mounted file system description file /etc/mtab.

The setmntent() function opens the file system description file fp and returns a file pointer which can be used by getmntent(). The argument type is the type of access required and can take the same values as the mode argument of fopen(3).

The getmntent() function reads the next line from the file system description file fp and returns a pointer to a structure containing the broken out fields from a line in the file. The pointer points to a static area of memory which is overwritten by subsequent calls to getmntent().

The addmntent() function adds the mntent structure mnt to the end of the open file fp.

The endmntent() function closes the file system description file fp.

The hasmntopt() function scans the mnt_opts field (see below) of the mntent structure mnt for a substring that matches opt. See <mntent.h> for valid mount options.

The reentrant getmntent_r() function is similar to getmntent(), but stores the struct mount in the provided *mntbuf and stores the strings pointed to by the entries in that struct in the provided array buf of size buflen.

The mntent structure is defined in <mntent.h> as follows:

: struct mntent { char *mnt_fsname; /* name of mounted file system */ char *mnt_dir; /* file system path prefix */ char *mnt_type; /* mount type (see mntent.h) */ char *mnt_opts; /* mount options (see mntent.h) */ int mnt_freq; /* dump frequency in days */ int mnt_passno; /* pass number on parallel fsck */ };

RETURN VALUE

The getmntent() and getmntent_r() functions return a pointer to the mntent structure or NULL on failure.

The addmntent() function returns 0 on success and 1 on failure.

The endmntent() function always returns 1.

The hasmntopt() function returns the address of the substring if a match is found and NULL otherwise.

FILES

/etc/fstab file system description file /etc/mtab mounted file system description file

CONFORMING TO

The non-reentrant functions are from SunOS 4.1.3. A routine getmntent_r() was introduced in HPUX 10, but it returns an int. The prototype shown above is glibc-only. LSB deprecates the functions endhostent(), sethostent() and setmntent().

NOTES

SysV also has a getmntent() function but the calling sequence differs, and the returned structure is different. Under SysV /etc/mnttab is used. BSD 4.4 and Digital Unix have a routine getmntinfo(), a wrapper around the system call getfsstat().

addnwstr

NAME

addwstr, addnwstr, waddwstr, waddnwstr, mvaddwstr, mvaddnwstr, mvwaddwstr, mvwaddnwstr - add a string of wide characters to a curses window and advance cursor

SYNOPSIS

#include <curses.h> int addwstr(const wchar_t *wstr);
int addnwstr(const wchar_t *wstr, int n);
int waddwstr(WINDOW *win, const wchar_t *wstr);
int waddnwstr(WINDOW *win, const wchar_t *wstr, int n);
int mvaddwstr(int y, int x, const wchar_t *wstr);
int mvaddnwstr(int y, int x, const wchar_t *wstr, int n);
int mvwaddwstr(WINDOW *win, int y, int x, const wchar_t *wstr);
int mvwaddnwstr(WINDOW *win, int y, int x, const wchar_t *wstr, int n);

DESCRIPTION

These routines write the characters of the (null-terminated) wchar_tcharacter string wstr on the given window. It is similar to constructing a cchar_t for each wchar_t in the string, then calling wadd_wch for the resulting cchar_t.

The mv routines perform cursor movement once, before writing any characters. Thereafter, the cursor is advanced as a side-effect of writing to the window.

The four routines with n as the last argument write at most n wchar_t characters. If n is -1, then the entire string will be added, up to the maximum number of characters that will fit on the line, or until a terminating null is reached.

RETURN VALUES

All routines return the integer ERR upon failure and OK on success.

NOTES

Note that all of these routines except waddnwstr may be macros.

PORTABILITY

All these entry points are described in the XSI Curses standard, Issue 4.

addr2line

NAME

addr2line - convert addresses into file names and line numbers.

SYNOPSIS

DESCRIPTION

addr2line translates program addresses into file names and line numbers. Given an address and an executable, it uses the debugging information in the executable to figure out which file name and line number are associated with a given address.

The executable to use is specified with the -e option. The default is the file a.out.

addr2line has two modes of operation.

In the first, hexadecimal addresses are specified on the command line, and addr2line displays the file name and line number for each address.

In the second, addr2line reads hexadecimal addresses from standard input, and prints the file name and line number for each address on standard output. In this mode, addr2line may be used in a pipe to convert dynamically chosen addresses.

The format of the output is FILENAME:LINENO. The file name and line number for each address is printed on a separate line. If the -f option is used, then each FILENAME:LINENO line is preceded by a FUNCTIONNAME line which is the name of the function containing the address.

If the file name or function name can not be determined, addr2line will print two question marks in their place. If the line number can not be determined, addr2line will print 0.

OPTIONS

The long and short forms of options, shown here as alternatives, are equivalent.

-b bfdname
--target=bfdname: Specify that the object-code format for the object files is bfdname.
-C
--demangle[=style]: Decode (demangle) low-level symbol names into user-level names. Besides removing any initial underscore prepended by the system, this makes C++ function names readable. Different compilers have different mangling styles. The optional demangling style argument can be used to choose an appropriate demangling style for your compiler.
-e filename
--exe=filename: Specify the name of the executable for which addresses should be translated. The default file is a.out.
-f
--functions: Display function names as well as file and line number information.
-s
--basenames: Display only the base of each file name.

COPYRIGHT

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License``.

addseverity

NAME

addseverity - introduce new severity classes

SYNOPSIS

#define _SVID_SOURCE
#include <fmtmsg.h> int addseverity(int severity, const char *s);

DESCRIPTION

This function allows the introduction of new severity classes which can be addressed by the severity parameter of the fmtmsg(3) function. By default that latter function only knows how to print messages for severity 0-4 (with strings (none), HALT, ERROR, WARNING, INFO). This call attaches the given string s to the given value severity. If s is NULL, the severity class with the numeric value severity is removed. It is not possible to overwrite or remove one of the default severity classes. The severity value must be nonnegative.

RETURN VALUE

Upon success, the value MM_OK is returned. Upon error, the return value is MM_NOTOK. Possible errors include: out of memory, attempt to remove a nonexistent or default severity class.

NOTE

New severity classes can also be added by setting the environment varible SEV_LEVEL.

CONFORMING TO

This function is not specified in the X/Open Portability Guide although the `fmtsmg` function is. It is available on System V systems.

a2p

NAME

a2p - Awk to Perl translator

SYNOPSIS

a2p [options] filename

DESCRIPTION

A2p takes an awk script specified on the command line (or from standard input) and produces a comparable perl script on the standard output.

Options

Options include:

-D<number>

sets debugging flags.

-F<character>

tells a2p that this awk script is always invoked with this -F switch.

-n<fieldlist>

specifies the names of the input fields if input does not have to be split into an array. If you were translating an awk script that processes the password file, you might say:

a2p -7 -nlogin.password.uid.gid.gcos.shell.home

Any delimiter can be used to separate the field names.

-<number>

causes a2p to assume that input will always have that many fields.

-o

tells a2p to use old awk behavior. The only current differences are:

*

Old awk always has a line loop, even if there are no line actions, whereas new awk does not.

*

In old awk, sprintf is extremely greedy about its arguments. For example, given the statement

print sprintf(some_args), extra_args;

old awk considers extra_args to be arguments to "sprintf"; new awk considers them arguments to "print".

Considerations

A2p cannot do as good a job translating as a human would, but it usually does pretty well. There are some areas where you may want to examine the perl script produced and tweak it some. Here are some of them, in no particular order.

There is an awk idiom of putting int() around a string expression to force numeric interpretation, even though the argument is always integer anyway. This is generally unneeded in perl, but a2p can`t tell if the argument is always going to be integer, so it leaves it in. You may wish to remove it.

Perl differentiates numeric comparison from string comparison. Awk has one operator for both that decides at run time which comparison to do. A2p does not try to do a complete job of awk emulation at this point. Instead it guesses which one you want. It`s almost always right, but it can be spoofed. All such guesses are marked with the comment ""#???"". You should go through and check them. You might want to run at least once with the -w switch to perl, which will warn you if you use == where you should have used eq.

Perl does not attempt to emulate the behavior of awk in which nonexistent array elements spring into existence simply by being referenced. If somehow you are relying on this mechanism to create null entries for a subsequent for...in, they won`t be there in perl.

If a2p makes a split line that assigns to a list of variables that looks like (Fld1, Fld2, Fld3...) you may want to rerun a2p using the -n option mentioned above. This will let you name the fields throughout the script. If it splits to an array instead, the script is probably referring to the number of fields somewhere.

The exit statement in awk doesn`t necessarily exit; it goes to the END block if there is one. Awk scripts that do contortions within the END block to bypass the block under such circumstances can be simplified by removing the conditional in the END block and just exiting directly from the perl script.

Perl has two kinds of array, numerically-indexed and associative. Perl associative arrays are called ``hashes``. Awk arrays are usually translated to hashes, but if you happen to know that the index is always going to be numeric you could change the {...} to [...]. Iteration over a hash is done using the keys() function, but iteration over an array is NOT. You might need to modify any loop that iterates over such an array.

Awk starts by assuming OFMT has the value %.6g. Perl starts by assuming its equivalent, $#, to have the value %.20g. You`ll want to set $# explicitly if you use the default value of OFMT.

Near the top of the line loop will be the split operation that is implicit in the awk script. There are times when you can move this down past some conditionals that test the entire record so that the split is not done as often.

For aesthetic reasons you may wish to change the array base $[ from 1 back to perl`s default of 0, but remember to change all array subscripts AND all substr() and index() operations to match.

Cute comments that say ``# Here is a workaround because awk is dumb`` are passed through unmodified.

Awk scripts are often embedded in a shell script that pipes stuff into and out of awk. Often the shell script wrapper can be incorporated into the perl script, since perl can start up pipes into and out of itself, and can do other things that awk can`t do by itself.

Scripts that refer to the special variables RSTART and RLENGTH can often be simplified by referring to the variables $`, $& and $`, as long as they are within the scope of the pattern match that sets them.

The produced perl script may have subroutines defined to deal with awk`s semantics regarding getline and print. Since a2p usually picks correctness over efficiency. it is almost always possible to rewrite such code to be more efficient by discarding the semantic sugar.

For efficiency, you may wish to remove the keyword from any return statement that is the last statement executed in a subroutine. A2p catches the most common case, but doesn`t analyze embedded blocks for subtler cases.

ARGV[0] translates to $ARGV0, but ARGV[n] translates to $ARGV[$n]. A loop that tries to iterate over ARGV[0] won`t find it.

ENVIRONMENT

A2p uses no environment variables.

AUTHOR

Larry Wall <larry@wall.org>

FILES

DIAGNOSTICS

BUGS

It would be possible to emulate awk`s behavior in selecting string versus numeric operations at run time by inspection of the operands, but it would be gross and inefficient. Besides, a2p almost always guesses right.

Storage for the awk syntax tree is currently static, and can run out.

a64l

NAME

a64l, l64a - convert between long and base-64

SYNOPSIS

#include <stdlib.h>

long a64l(char *str64);

char *l64a(long value);

DESCRIPTION

These functions provide a conversion between 32-bit long integers and little-endian base-64 ASCII strings (of length zero to six). If the string used as argument for a64l() has length greater than six, only the first six bytes are used. If longs have more than 32 bits, then l64a() uses only the low order 32 bits of value, and a64l() sign-extends its 32-bit result.

The 64 digits in the base 64 system are:

: `.` represents a 0 `/` represents a 1 0-9 represent 2-11 A-Z represent 12-37 a-z represent 38-63

So 123 = 59*64^0 + 1*64^1 = "v/".

NOTES

The value returned by a64l() may be a pointer to a static buffer, possibly overwritten by later calls.

The behaviour of l64a() is undefined when value is negative. If value is zero, it returns an empty string.

These functions are broken in glibc before 2.2.5 (puts most significant digit first).

This is not the encoding used by uuencode(1).

CONFORMING TO

XPG 4.2, POSIX 1003.1-2001.

aa_attrs

NAME

aa_attrs - returns pointer to the text output buffer used by AA-lib.

SYNOPSIS

#include <aalib.h>

char *aa_attrs(aa_context *a);

PARAMETERS

aa_context *a: Specifies the AA-lib context to operate on.

DESCRIPTION

The attribute output buffer is simple array of characters specifying the attributes. The array is organizated in the aa_scrheight (a) rows of aa_scrwidth(a) characters.

RETURNS

Pointer the text output buffer used by AA-lib.

aa_autoinitkbd

NAME

aa_autoinitkbd - easy to use AA-lib keyboard initialization function.

SYNOPSIS

#include <aalib.h>

int aa_autoinitkbd
(
struct aa_context *context,

int mode

);

PARAMETERS

struct aa_context *context: Specifies the AA-lib context to operate on.
int mode: Mask of extra features you request. Can contain AA_SENDRELEASE if you are interested in release events too.

DESCRIPTION

Attempts to find available keyboard driver supporting the specified mode. First attempts to initialize the recommended drivers and then in order drivers available in the aa_kbddrivers array (all regular output drivers compiled into AA-lib).

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.
int x: X coordinate of the edited text.
int y: Y coordinate of the edited text.
int size: Length of the editor window.
char *s: Buffer to edit (containing default value).
int maxsize: Size of the buffer.

DESCRIPTION

This function produces the simple interactive line editor that can be used by AA-lib programs to input strings.

aa_fastrender

NAME

aa_fastrender - simple and fast AA-lib rendering function.

SYNOPSIS

#include <aalib.h>

void aa_fastrender
(
       aa_context *c,

       int x1,

       int y1,

       int x2,

       int y2

);

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.
int x1: Column of top left coner of rendered area (in characters!).
int y1: Row of top left coner of rendered area.
int x2: Column of bottom right coner of rendered area.
int y2: Row of bottom right coner of rendered area.

DESCRIPTION

This function does the trick of converting the emulated framebuffer into high quality ASCII-art. It is slightly faster and less flexible the aa_render function.

Note that to see the effect you need to call aa_flush too.

First call to this function may take a while, because the rendering tables are produced.

aa_formats

NAME

aa_formats - NULL terminated array of save formats supported by AA-lib.

SYNOPSIS

#include <aalib.h>

extern const struct aa_format *const aa_formats[];

DESCRIPTION

NULL terminated array of save formats supported by AA-lib.

aa_getkey

NAME

aa_getkey - return next keypress event from queue.

SYNOPSIS

#include <aalib.h>

int aa_getkey
(
aa_context *c,

int wait

);

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.
int wait: 1 if you wish to wait for the even when queue is empty.

PARAMETERS

aa_context *a: Specifies the AA-lib context to operate on.

DESCRIPTION

The framebuffer is simple array of characters specifying the brightness value (or palette index depending on the aa_render call). The array is organizated in the aa_imgheight (a) rows of aa_imgwidth(a) characters.

RETURNS

Pointer to framebuffer emulated by AA-lib.

aa_imgwidth

NAME

aa_imgwidth - returns width of the emulated image in pixels.

SYNOPSIS

#include <aalib.h>

int aa_imgwidth(aa_context *a);

PARAMETERS

aa_context *a: Specifies the AA-lib context to operate on.

DESCRIPTION

Returns width of the emulated image in pixels.

aa_initkbd

NAME

aa_initkbd - initialize the AA-lib keyboard driver.

SYNOPSIS

#include <aalib.h>

int aa_initkbd
(
       struct aa_context *context,

       const struct aa_kbddriver *drv,

       int mode

);

PARAMETERS

struct aa_context *context: Specifies the AA-lib context to operate on.
const struct aa_kbddriver *drv: Driver you wish to use.
int mode: Mask of extra features you request. Can contain AA_SENDRELEASE if you are interested in release events too.

DESCRIPTION

This is the most primitive AA-lib keyboard initialization function. Allows better control over the process than the easier to use aa_autoinitkbd function.

RETURNS

1 on success and 0 on fail.

aa_kbddrivers

NAME

aa_kbddrivers - NULL-terminated array of keyboard drivers available in AA_lib.

SYNOPSIS

#include <aalib.h>

extern const struct aa_kbddriver *const aa_kbddrivers[];

DESCRIPTION

NULL-terminated array of keyboard drivers available in AA_lib.

aa_mmheight

NAME

aa_mmheight - returns height of the output screen in millimeters.

SYNOPSIS

#include <aalib.h>

int aa_mmheight(aa_context *a);

PARAMETERS

aa_context *a: Specifies the AA-lib context to operate on.

DESCRIPTION

Returns height of the output screen in millimeters.

aa_mousedrivers

NAME

aa_mousedrivers - NULL terminated array of mouse drivers supported by AA-lib.

SYNOPSIS

#include <aalib.h>

extern const struct aa_mousedriver *const aa_mousedrivers[];

DESCRIPTION

NULL terminated array of mouse drivers supported by AA-lib.

aa_parseoptions

NAME

aa_parseoptions - parse the standard command line options used by AA-lib.

SYNOPSIS

#include <aalib.h>

int aa_parseoptions
(
       struct aa_hardware_params *p,

       aa_renderparams *r,

       int *argc,

       char **argv

);

PARAMETERS

struct aa_hardware_params *p: Hardware parameters structure to alter. It is expected that this structure only with necessary modifications will be later used to initialize the AA-lib context.
aa_renderparams *r: Rendering prameters structure to alter. It is expected that this structure only with necessary modifications will be later used to render images.
int *argc: Pointer to argc parameter passed to function "main".
char **argv: Pointer to argv parameter passed to function "main".

PARAMETERS

const struct aa_font *f: Font specification structure.

DESCRIPTION

Add new font specification to aa_fonts array.

RETURNS

1 when succesfull or 0 on failure.

aa_resize

NAME

aa_resize - resize functions

SYNOPSIS

#include <aalib.h>

int aa_resize(aa_context *c);

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.

PARAMETERS

aa_context *c: Specifies the AA-lib context to operate on.

DESCRIPTION

Show the hardware cursor. This function may not be ignored by some drivers.

OpenSource Headlines

Fast Easy Web Hosting

Your Say About Movies

Cigars Review

Man Pages

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

KEYWORDS

NAME

SYNOPSIS

DESCRIPTION

Tasks:

Global:

Sheets:

Virtual pages:

Headings:

Input:

Pretty-printing:

Output:

PostScript:

AUTHOR

REPORTING BUGS

COPYRIGHT

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

NAME

SYNOPSIS

PARAMETERS

DESCRIPTION

RETURNS

SEE ALSO

NAME

SYNOPSIS

PARAMETERS

DESCRIPTION

RETURNS

SEE ALSO

NAME

SYNOPSIS

PARAMETERS

DESCRIPTION

RETURNS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

NAME

SYNOPSIS

PARAMETERS

DESCRIPTION

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

NAME

SYNOPSIS

PARAMETERS

DESCRIPTION

RETURNS

SEE ALSO

NAME

SYNOPSIS

PARAMETERS

DESCRIPTION

SEE ALSO