OpenSource Headlines

Writing a Java Class to Manage RPM Package Content

A look inside RPM packages and how to use Java to extract information. Installing a Linux system for the first time is quite straightforward.

Eschalon: Book I Updated

Basilisk Games has announced the release of version 1.06 of Eschalon: Book I , the first title in the company's old school fantasy RPG series.

Linux distributions update for Web flaw

September 3, 2010, 01:30 PM - - A number of Linux distributors have issued patches for fixing a widely used program that fetches Web pages, called Wget, so it can not be misused by attackers.

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.

CodePlex's Walli: No need to overhaul open source definition, licenses

By Microsoft Subnet on Thu, 09/02/10 - 6:03pm. As long as Microsoft exists, there will be those who believe it's the KGB of the open source world, secretly doing everything it can to destroy the free software movement in general and Linux in particular .

Linux: A Double Edged Sword for Open Source, 09/02/2010

By Alan Shimel on Thu, 09/02/10 - 4:22pm. Quick, name the most successful open source project of all time.

Marten Mickos, Noted Leader in Open Source, to Keynote at Lucene...

The conference will take place October 7-8, 2010 at the Hyatt Harborside, Boston, Massachusetts.

A guide to today's top 10 Linux distributions

Still not sure which distro is best for your business? Here's a close-up look at the most popular contenders.

Google Chrome celebrates 2nd birthday with security patches

The Google Chrome 6.0, available in stable and beta channels for Windows, Mac, and Linux, patches a total of 15 documented security vunerabilities.

Fast Easy Web Hosting

Your Say About Movies

Cigars Review

Man Pages

Subroutines

Browse in :

All > Documents > Man Pages > Subroutines (8513)

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

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 *a: Specifies the AA-lib context to operate on.

DESCRIPTION

The text output buffer is simple array of characters specifying the ascii-value of the characters. 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_uninitmouse

NAME

aa_uninitmouse - uninitialize the mouse driver.

SYNOPSIS

#include <aalib.h>

void aa_uninitmouse(aa_context *context);

PARAMETERS

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

DESCRIPTION

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

abs

NAME

abs, labs, llabs, imaxabs - compute the absolute value of an integer

SYNOPSIS

#include <stdlib.h> int abs(int j);
long int labs(long int j);
long long int llabs(long long int j); #include <inttypes.h> intmax_t imaxabs(intmax_t j);

DESCRIPTION

The abs() function computes the absolute value of the integer argument j. The labs(), llabs() and imaxabs() functions compute the absolute value of the argument j of the appropriate integer type for the function.

RETURN VALUE

Returns the absolute value of the integer argument, of the appropriate integer type for the function.

CONFORMING TO

SVID 3, POSIX.1, BSD 4.3, ISO/IEC 9899 (C99). POSIX.1 (1996 edition) only requires the abs() function. ISO/IEC 9899:1990 (C89) only includes the abs() and labs() functions; the functions llabs() and imaxabs() were added in C99.

NOTES

Trying to take the absolute value of the most negative integer is not defined.

The llabs() function is included in glibc since version 2.0, but is not in libc5 or libc4. The imaxabs() function is included in glibc since version 2.1.1.

For llabs() to be declared, it may be necessary to define _ISOC99_SOURCE or _ISOC9X_SOURCE (depending on the version of glibc) before including any standard headers.

GCC handles abs() and labs() as builtin functions. GCC 3.0 also handles llabs() and imaxabs() as builtins.

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 .

acos

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.

acosh

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.

acoshl

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

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.

addch

NAME

addch, waddch, mvaddch, mvwaddch, echochar, wechochar - add a character (with attributes) to a curses window, then advance the cursor

SYNOPSIS

#include <curses.h>

int addch(const chtype ch);
int waddch(WINDOW *win, const chtype ch);
int mvaddch(int y, int x, const chtype ch);
int mvwaddch(WINDOW *win, int y, int x, const chtype ch);
int echochar(const chtype ch);
int wechochar(WINDOW *win, const chtype ch);

DESCRIPTION

The addch, waddch, mvaddch and mvwaddch routines put the character ch into the given window at its current window position, which is then advanced. They are analogous to putchar in stdio(3). If the advance is at the right margin, the cursor automatically wraps to the beginning of the next line. At the bottom of the current scrolling region, if scrollok is enabled, the scrolling region is scrolled up one line.

If ch is a tab, newline, or backspace, the cursor is moved appropriately within the window. Backspace moves the cursor one character left; at the left edge of a window it does nothing. Newline does a clrtoeol, then moves the cursor to the window left margin on the next line, scrolling the window if on the last line. Tabs are considered to be at every eighth column. The tab interval may be altered by setting the TABSIZE variable.

If ch is any control character other than tab, newline, or backspace, it is drawn in ^X notation. Calling winch after adding a control character does not return the character itself, but instead returns the ^-representation of the control character.

Video attributes can be combined with a character argument passed to addch or related functions by logical-ORing them into the character. (Thus, text, including attributes, can be copied from one place to another using inch and addch.) See the curs_attr(3X) page for values of predefined video attribute constants that can be usefully OR`ed into characters.

The echochar and wechochar routines are equivalent to a call to addch followed by a call to refresh, or a call to waddch followed by a call to wrefresh. The knowledge that only a single character is being output is used and, for non-control characters, a considerable performance gain may be seen by using these routines instead of their equivalents.

Line Graphics

The following variables may be used to add line drawing characters to the screen with routines of the addch family. The default character listed below is used if the acsc capability doesn`t define a terminal-specific replacement for it (but see the EXTENSIONS section below). The names are taken from VT100 nomenclature.

Name	Default	Description

ACS_BOARD	#	board of squares
ACS_BTEE	+	bottom tee
ACS_BULLET	o	bullet
ACS_CKBOARD	:	checker board (stipple)
ACS_DARROW	v	arrow pointing down
ACS_DEGREE	`	degree symbol
ACS_DIAMOND	+	diamond
ACS_GEQUAL	>	greater-than-or-equal-to
ACS_HLINE	-	horizontal line
ACS_LANTERN	#	lantern symbol
ACS_LARROW	<	arrow pointing left
ACS_LEQUAL	<	less-than-or-equal-to
ACS_LLCORNER	+	lower left-hand corner
ACS_LRCORNER	+	lower right-hand corner
ACS_LTEE	+	left tee
ACS_NEQUAL	!	not-equal
ACS_PI	*	greek pi
ACS_PLMINUS	#	plus/minus
ACS_PLUS	+	plus
ACS_RARROW	>	arrow pointing right
ACS_RTEE	+	right tee
ACS_S1	-	scan line 1
ACS_S3	-	scan line 3
ACS_S7	-	scan line 7
ACS_S9	_	scan line 9
ACS_STERLING	f	pound-sterling symbol
ACS_TTEE	+	top tee
ACS_UARROW	^	arrow pointing up
ACS_ULCORNER	+	upper left-hand corner
ACS_URCORNER	+	upper right-hand corner
ACS_VLINE	\|	vertical line

RETURN VALUE

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 addch, mvaddch, mvwaddch, and echochar may be macros.

PORTABILITY

All these functions are described in the XSI Curses standard, Issue 4. The defaults specified for forms-drawing characters apply in the POSIX locale.

Some ACS symbols (ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL, ACS_PI, ACS_NEQUAL, ACS_STERLING) were not documented in any publicly released System V. However, many publicly available terminfos include acsc strings in which their key characters (pryz{|}) are embedded, and a second-hand list of their character descriptions has come to light. The ACS-prefixed names for them were invented for ncurses(3X).

The TABSIZE variable is implemented in some versions of curses, but is not part of X/Open curses.

If ch is a carriage return, the cursor is moved to the beginning of the current row of the window. This is true of other implementations, but is not documented.

addchstr

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

NOTES

Note that all routines except waddchnstr may be macros.

PORTABILITY

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

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.

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.

addwstr

NAME

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

SYNOPSIS

DESCRIPTION

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.

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.

add_module_replacement

NAME

init_mib, add_mibdir, init_mib_internals, add_module_replacement, read_module, read_mib, read_all_mibs, read_objid, read_module_node, get_module_node, read_objid snmp_set_mib_warnings, snmp_set_save_descriptions, shutdown_mib, print_mib, print_variable, fprint_variable, snprint_variable, sprint_realloc_variable, print_value, fprint_value, snprint_value, sprint_realloc_value, print_objid, fprint_objid, snprint_objid, sprint_realloc_objid, print_description, fprint_description - mib_api functions

SYNOPSIS

#include <net-snmp/mib_api.h>

void init_mib(void);
int add_mibdir(char *dirname);
int add_module_replacement(char *old_module, char *new_module, char *tag, int len);
void init_mib_internals(void);
struct tree *read_module(char *name);
struct tree *read_mib(char *filename);
struct tree *read_all_mibs(void);

void shutdown_mib(void);

void print_mib(FILE *fp);

int read_objid(char *input, oid *output, int *out_len);
int get_module_node(char *name, char *module, oid *objid, int *objidlen);

void print_variable(const oid *objid, size_t objidlen, struct variable_list *variable);
void fprint_variable(FILE *fp, const oid *objid, size_t objidlen, struct variable_list *variable);
int snprint_variable(char *buf, size_t len, const oid *objid, size_t objidlen, struct variable_list *variable);
int sprint_realloc_variable(u_char **buf, size_t *buf_len, size_t *out_len, int allow_realloc, const oid *objid, size_t objidlen, struct variable_list *variable);

void print_value(oid *objid, size_t objidlen, struct variable_list *variable)
void fprint_value(FILE *fp, const oid *objid, size_t objidlen, struct variable_list *variable);
int snprint_value(char *buf, size_t len, const oid *objid, size_t objidlen, struct variable_list *variable);
int sprint_realloc_value(u_char **buf, size_t *buf_len, size_t *out_len, int allow_realloc, const oid *objid, size_t objidlen, struct variable_list *variable);

void print_objid(const oid *objid, size_t objidlen);
void fprint_objid(FILE *fp, const oid *objid, size_t objidlen);
int snprint_objid(char *buf, size_t len, const oid *objid, size_t objidlen);
int sprint_realloc_objid(u_char **buf, size_t *buf_len, size_t *out_len, int allow_realloc, const oid *objid, size_t objidlen);

void print_description(const oid *objid, size_t objidlen);
void fprint_description(FILE *fp, const oid *objid, size_t objidlen);

void snmp_set_mib_warnings(int level);
void snmp_set_save_descriptions(int save);

DESCRIPTION

The functions dealing with MIB modules fall into four groups. Those dealing with initialisation and shutdown, those that read in and parse MIB files, those that search the MIB tree, and various output routines.

Initialisation and Shutdown

init_mib is a convenience function that handles all calls to add_mibdir, read_module and read_mib for standard applications. It should be called before any other routine that manipulates or accesses the MIB tree. This routine sets up various internal structures, as well as reading in the default MIB modules, as detailed below.

add_mibdir is used to define the range of directory locations which are searched for files containing MIB modules (one module per file). By default, this will be set to the directory /usr/share/mibs but this can be overridden by setting the environment variable MIBDIRS to a (colon-separated) list of directories to search. Note that this does not actually load the MIB modules located in that directory, but is an initialisation step to make them available. This function returns a count of files found in the directory, or a -1 if there is an error.

init_mib_internals sets up the internal structures, preparatory to reading in MIB modules. It should be called after all calls to add_mibdir, and before and calls to read_module. This is called automatically if init_mib is used.

shutdown_mib will clear the information that was gathered by read_module, add_mibdir and add_module_replacement. It is strongly recommended that one does not invoke shutdown_mib while there are SNMP sessions being actively managed.

Reading and Parsing MIBs

add_module_replacement can be used to allow new MIB modules to obsolete older ones, without needing to amend the imports clauses of other modules. It takes the names of the old and new modules, together with an indication of which portions of the old module are affected.

tag	len	load the new module when:
NULL	0	always (the old module is a strict subset of the new)
name	0	for the given tag only
name	non-0	for any identifier with this prefix

It can also be used to handle errors in the module identifiers used in MIB import clauses (such as referring to RFC1213 instead of RFC1213-MIB).

read_module locates and parses the module specified, together with any modules that it imports from, and adds the contents of these modules to the active MIB tree. Note that add_mibdir must first be called to add the directory containing the file with the module definition, if this is not in the standard path.
By default, the following MIB modules will be loaded: IP-MIB, IF-MIB, TCP-MIB, UDP-MIB, SNMPv2-MIB, RFC1213-MIB, UCD-SNMP-MIB. This can be overridden by setting the environment variable MIBS to a (colon-separated) list of modules to load. If this variable starts with a plus character, then the specified modules are added to the default list. Otherwise only those modules listed are loaded (together with any others they import from). If MIBS is set to ALL, read_all_mibs is called to load all the MIB files found in all the specified MIBDIRS.

read_mib parses the file specified, together with any modules that it imports from, and adds the contents to the active MIB tree. Such a file can contain more then one module, though care must be taken that any imports occur earlier in the file, if they are not to be read from the installed modules. Note that the file specified does not need to be in any of the directories initialised by add_mibdir (or the default setup), though any imported modules do.
The environment variable MIBFILES can be set to a (colon-separated) list of files containing MIBs to load.

read_objid takes a string containing a textual version of an object identifier (in either numeric or descriptor form), and transforms this into the corresponding list of sub-identifiers. This is returned in the output parameter, with the number of sub-identifiers returned via out_len. When called, out_len must hold the maximum length of the output array. This function returns a value of 1 if it succeeds in parsing the string and 0 otherwise.

Searching the MIB Tree

get_module_node takes a descriptor and the name of a module, and returns the corresponding oid list, in the same way as read_objid above.
If the module name is specified as "ANY", then this routine will assume that the descriptor given is unique within the tree, and will return the matching entry. If this assumption is invalid, then the behaviour as to which variable is returned is implementation dependent.

Output

print_mib will print out a representation of the currently active MIB tree to the specified FILE pointer.

print_variable will take an object identifier (as returned by read_objid or get_module_node) and an instance of such a variable, and prints to the standard output the textual form of the object identifier together with the value of the variable. fprint_variable does the same, but prints to the FILE pointer specified by the initial parameter.
snprint_variable prints the same information into the buffer pointed to by buf which is of length len and returns either the number of characters printed, or -1 if the buffer was not large enough. In the latter case, buf will typically contained a truncated version of the information (but this behaviour is not guaranteed). This function replaces the obsolete function sprint_variable.
sprint_realloc_variable is the low-level function used to implement all these functions. It prints to a specified offset in a string buffer. The buf parameter points to a pointer to that buffer; buf_len points to a variable holding the current size of that buffer, and out_len points to a variable holding the offset to which to print. out_len will be updated to hold the offset of the character following the last one added to the buffer. If allow_realloc is 1, the buffer will be dynamically expanded, as necessary, to hold the output; the variables pointed to by buf and buf_len will be updated. If allow_realloc is 0, the buffer will not be dynamically expanded. sprint_realloc_variable returns 0 if allow_realloc is 1 and an attempt to allocate memory to expand the buffer fails, or if allow_realloc is 0 and the output wouldn`t fit in the buffer. Otherwise it returns 1. When using this function you should be careful to call free(3) on *buf when you have finished with it.

print_value, fprint_value, snprint_value and sprint_realloc_value do the same as the equivalent print_variable routines, but only displaying the value of the variable, without the corresponding object identifier.

print_objid, fprint_objid, snprint_objid, and sprint_realloc_objid take an object identifier (without an accompanying variable instance) and print out the textual representation.

print_description and fprint_description take an object identifier (as for print_objid above) and print out the associated DESCRIPTION clause.

Note that there are no corresponding routines snprint_description or sprint_realloc_description. By default the parser does not save descriptions since they may be huge. In order to be able to print them, you must call snmp_set_save_descriptions(1).

In general the parser is silent about what strangenesses it sees in the MIB files. To get warnings reported, call snmp_set_mib_warnings with a level of 1 (or 2 for even more warnings).

ENVIRONMENT VARIABLES

MIBDIRS: A colon separated list of directories to search for MIB modules. Default: /usr/share/snmp/mibs
MIBFILES: A colon separated list of files to load. Default: (none)
MIBS: A colon separated list of MIB modules to load. Default: IP-MIB:IF-MIB:TCP-MIB:UDP-MIB:SNMPv2-MIB:RFC1213-MIB:UCD-SNMP-MIB.

add_wchnstr

NAME

add_wchstr, add_wchnstr, wadd_wchstr, wadd_wchnstr, mvadd_wchstr, mvadd_wchnstr, mvwadd_wchstr, mvwadd_wchnstr - add an array of complex characters (and attributes) to a curses window

SYNOPSIS

#include <curses.h>

int add_wchstr(const cchar_t *wchstr);
int add_wchnstr(const cchar_t *wchstr, int n);
int wadd_wchstr(WINDOW * win, const cchar_t *wchstr);
int wadd_wchnstr(WINDOW * win, const cchar_t *wchstr, int n);
int mvadd_wchstr(int y, int x, const cchar_t *wchstr);
int mvadd_wchnstr(int y, int x, const cchar_t *wchstr, int n);
int mvwadd_wchstr(WINDOW *win, int y, int x, const cchar_t *wchstr);
int mvwadd_wchnstr(WINDOW *win, int y, int x, const cchar_t *wchstr, int n);

DESCRIPTION

These routines copy the array of complex characters wchstr 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 array is copied, to the maximum number of characters that will fit on the line.

The window cursor is not advanced. These routines work faster than waddnstr. On the other hand, they do not perform checking (such as for the newline, backspace, or carriage return characters), they do not advance the current cursor position, they do not 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.

These routines end successfully on encountering a null cchar_t, or when they have filled the current line. If a complex character cannot completely fit at the end of the current line, the remaining columns are filled with the background character and rendition.

NOTES

All functions except wadd_wchnstr may be macros.

RETURN VALUES

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

PORTABILITY

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

AdmBlackBoxMethods

NAME

AdmBlackBoxMethods -

SYNOPSIS

#include <blackbox.h>

Public Attributes

void(* free )(void *data)

AdmContext *(* read )(void *data, AdmError **error)

unsigned int(* listSerial )(void *data, unsigned int *array, unsigned int array_len, unsigned int top_serial, AdmError **error)

AdmContext *(* readSerial )(void *data, unsigned int serial, AdmError **error)

int(* write )(void *data, AdmContext *context, AdmError **error)

Member Data Documentation

void(* AdmBlackBoxMethods::free)(void *data)

AdmContext( AdmBlackBoxMethods::read)(void *data, AdmError **error)

unsigned int(* AdmBlackBoxMethods::listSerial)(void data, unsigned int array, unsigned int array_len, unsigned int top_serial, AdmError **error)

AdmContext( AdmBlackBoxMethods::readSerial)(void *data, unsigned int serial, AdmError **error)

int(* AdmBlackBoxMethods::write)(void data, AdmContext context, AdmError **error)

Author

Generated automatically by Doxygen for Alchemist from the source code.

adm_bb_cap_t

NAME

adm_bb_cap_t -

SYNOPSIS

#include <alchemist.h>

Public Attributes

unsigned char array [1]

Member Data Documentation

unsigned char adm_bb_cap_t::array[1]

Author

Generated automatically by Doxygen for Alchemist from the source code.

aio_cancel

NAME

aio_cancel - cancel an outstanding asynchronous I/O request

SYNOPSIS

#include <aio.h>

int aio_cancel(int fd, struct aiocb *aiocbp);

DESCRIPTION

The aio_cancel function attempts to cancel outstanding asynchronous I/O requests for the file descriptor fd. If aiocbp is NULL, all such requests are cancelled. Otherwise, only the request described by the control block pointed to by aiocbp is cancelled.

Normal asynchronous notification occurs for cancelled requests. The request return status is set to -1, and the request error status is set to ECANCELED. The control block of requests that cannot be cancelled is not changed.

If aiocbp is not NULL, and fd differs from the file descriptor with which the asynchronous operation was initiated, unspecified results occur.

Which operations are cancelable is implementation-defined.

RETURN VALUE

This function returns AIO_CANCELED if all requests were successfully cancelled. It returns AIO_NOTCANCELED when at least one of the requests specified was not cancelled because it was in progress. In this case one may check the status of individual requests using aio_error(3). This function returns AIO_ALLDONE when all requests had been completed already before this call. When some error occurs, -1 is returned, and errno is set appropriately.

ERRORS

EBADF: fd is not a valid file descriptor.

CONFORMING TO

POSIX 1003.1-2003

aio_fsync

NAME

aio_fsync - asynchronous file synchronization

SYNOPSIS

#include <aio.h>

int aio_fsync(int op, struct aiocb *aiocbp);

DESCRIPTION

The aio_fsync function does a sync on all outstanding asynchronous I/O operations associated with aiocbp->aio_fildes.

More precisely, if op is O_SYNC, then all currently queued I/O operations shall be completed as if by a call of fsync(2), and if op is O_DSYNC, this call is the asynchronous analog of fdatasync(2). Note that this is a request only - this call does not wait for I/O completion.

Apart from aio_fildes the only field in the structure pointed to by aiocbp that is used by this call is the aio_sigevent field (a struct sigevent) that indicates the desired type of asynchronous notification at completion. All other fields are ignored.

RETURN VALUE

On success (the sync request was successfully queued) this function returns 0. On error -1 is returned, and errno is set appropriately.

ERRORS

EAGAIN: Out of resources.
EBADF: aio_fildes is not a valid file descriptor open for writing.
EINVAL: No synchronized I/O for this file is supported, or op is not O_SYNC or O_DSYNC.

CONFORMING TO

POSIX 1003.1-2003

aio_return

NAME

aio_return - get return status of asynchronous I/O operation

SYNOPSIS

#include <aio.h>

ssize_t aio_return(struct aiocb *aiocbp);

DESCRIPTION

The aio_return function returns the final return status for the asynchronous I/O request with control block pointed to by aiocbp.

This function should be called only once for any given request, after aio_error(2) returns something other than EINPROGRESS.

RETURN VALUE

If the asynchronous I/O operation has completed, this function returns the value that would have been returned in case of a synchronous read, write, or fsync request. Otherwise the return value is undefined. On error, the error value is returned.

ERRORS

EINVAL: aiocbp does not point at a control block for an asynchronous I/O request of which the return status has not been retrieved yet.

CONFORMING TO

POSIX 1003.1-2003

aio_write

NAME

aio_write - asynchronous write

SYNOPSIS

#include <aio.h>

int aio_write(struct aiocb *aiocbp);

DESCRIPTION

The aio_write function requests an asynchronous "n = write(fd, buf, count)" with fd, buf, count given by aiocbp->aio_fildes, aiocbp->aio_buf, aiocbp->aio_nbytes, respectively. The return status n can be retrieved upon completion using aio_return(3).

If O_APPEND is not set, the data is written starting at the absolute file offset aiocbp->aio_offset, regardless of the current file position. If O_APPEND is set, the data is written at the end of the file. After this request, the value of the current file position is unspecified.

The "asynchronous" means that this call returns as soon as the request has been enqueued; the write may or may not have completed when the call returns. One tests for completion using aio_error(3).

If _POSIX_PRIORITIZED_IO is defined, and this file supports it, then the asynchronous operation is submitted at a priority equal to that of the calling process minus aiocbp->aio_reqprio.

The field aiocbp->aio_lio_opcode is ignored.

No data is written to a regular file beyond its maximum offset.

RETURN VALUE

On success, 0 is returned. On error the request is not enqueued, -1 is returned, and errno is set appropriately. If an error is first detected later, it will be reported via aio_return(3) (returns status -1) and aio_error(3) (error status whatever one would have gotten in errno, such as EBADF).

ERRORS

EAGAIN: Out of resources.
EBADF: aio_fildes is not a valid file descriptor open for writing.
EINVAL: One or more of aio_offset, aio_reqprio, aio_nbytes are invalid.
EFBIG: The file is a regular file, we want to write at least one byte, but the starting position is at or beyond the maximum offset for this file.
ENOSYS: This function is not supported.

NOTES

It is a good idea to zero out the control block before use. This control block must not be changed while the write operation is in progress. The buffer area being written out must not be accessed during the operation or undefined results may occur. The memory areas involved must remain valid.

CONFORMING TO

POSIX 1003.1-2003

Alloc

NAME

Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc - allocate or free heap memory

SYNOPSIS

#include <tcl.h> char * Tcl_Alloc(size) void Tcl_Free(ptr) char * Tcl_Realloc(ptr, size) char * Tcl_AttemptAlloc(size) char * Tcl_AttemptRealloc(ptr, size) char * ckalloc(size) void ckfree(ptr) char * ckrealloc(ptr, size) char * attemptckalloc(size) char * attemptckrealloc(ptr, size)

ARGUMENTS

int size (in)
Size in bytes of the memory block to allocate.

char *ptr (in)
Pointer to memory block to free or realloc.

DESCRIPTION

These procedures provide a platform and compiler independent interface for memory allocation. Programs that need to transfer ownership of memory blocks between Tcl and other modules should use these routines rather than the native malloc() and free() routines provided by the C run-time library.

Tcl_Alloc returns a pointer to a block of at least size bytes suitably aligned for any use.

Tcl_Free makes the space referred to by ptr available for further allocation.

Tcl_Realloc changes the size of the block pointed to by ptr to size bytes and returns a pointer to the new block. The contents will be unchanged up to the lesser of the new and old sizes. The returned location may be different from ptr.

Tcl_AttemptAlloc and Tcl_AttemptRealloc are identical in function to Tcl_Alloc and Tcl_Realloc, except that Tcl_AttemptAlloc and Tcl_AttemptRealloc will not cause the Tcl interpreter to panic if the memory allocation fails. If the allocation fails, these functions will return NULL. Note that on some platforms, attempting to allocate a block of memory will also cause these functions to return NULL.

The procedures ckalloc, ckfree, ckrealloc, attemptckalloc, and attemptckrealloc are implemented as macros. Normally, they are synonyms for the corresponding procedures documented on this page. When Tcl and all modules calling Tcl are compiled with TCL_MEM_DEBUG defined, however, these macros are redefined to be special debugging versions of of these procedures. To support Tcl`s memory debugging within a module, use the macros rather than direct calls to Tcl_Alloc, etc.

KEYWORDS

alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG

AllowExc

NAME

Tcl_AllowExceptions - allow all exceptions in next script evaluation

SYNOPSIS

#include <tcl.h> Tcl_AllowExceptions(interp)

ARGUMENTS

Tcl_Interp *interp (in)
Interpreter in which script will be evaluated.

DESCRIPTION

If a script is evaluated at top-level (i.e. no other scripts are pending evaluation when the script is invoked), and if the script terminates with a completion code other than TCL_OK, TCL_ERROR or TCL_RETURN, then Tcl normally converts this into a TCL_ERROR return with an appropriate message. The particular script evaluation procedures of Tcl that act in the manner are Tcl_EvalObjEx, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval and Tcl_VarEvalVA.

However, if Tcl_AllowExceptions is invoked immediately before calling one of those a procedures, then arbitrary completion codes are permitted from the script, and they are returned without modification. This is useful in cases where the caller can deal with exceptions such as TCL_BREAK or TCL_CONTINUE in a meaningful way.

KEYWORDS

continue, break, exception, interpreter

alphasort

NAME

scandir, alphasort, versionsort - scan a directory for matching entries

SYNOPSIS

#include <dirent.h> int scandir(const char *dir, struct dirent ***namelist,

: int(*filter)(const struct dirent *), int(*compar)(const struct dirent **, const struct dirent **));

int alphasort(const void *a, const void *b);
int versionsort(const void *a, const void *b);

DESCRIPTION

The scandir() function scans the directory dir, calling filter() on each directory entry. Entries for which filter() returns non-zero are stored in strings allocated via malloc(), sorted using qsort() with the comparison function compar(), and collected in array namelist which is allocated via malloc(). If filter is NULL, all entries are selected.

The alphasort() and versionsort() functions can be used as the comparison function compar(). The former sorts directory entries using strcoll(3), the latter using strverscmp(3) on the strings (*a)->d_name and (*b)->d_name.

RETURN VALUE

The scandir() function returns the number of directory entries selected or -1 if an error occurs.

The alphasort() and versionsort() functions return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.

ERRORS

ENOMEM: Insufficient memory to complete the operation.

CONFORMING TO

None of these functions is in POSIX. LSB has deprecated the library call alphasort() and never contained scandir().

The functions scandir() and alphasort() are from BSD 4.3, and have been available under Linux since libc4. Libc4 and libc5 use the more precise prototype

int alphasort(const struct dirent **a, const struct dirent **b);

but glibc 2.0 returns to the imprecise BSD prototype.

The function versionsort() is a GNU extension, available since glibc 2.1. Since glibc 2.1, alphasort() calls strcoll(3); earlier it used strcmp(3).

EXAMPLE

/* print files in current directory in reverse order */ #include <dirent.h> main(){ struct dirent **namelist; int n; n = scandir(".", &namelist, 0, alphasort); if (n < 0) perror("scandir"); else { while(n--) { printf("%s ", namelist[n]->d_name); free(namelist[n]); } free(namelist); } }

AppInit

NAME

Tcl_AppInit - perform application-specific initialization

SYNOPSIS

#include <tcl.h> int Tcl_AppInit(interp)

ARGUMENTS

Tcl_Interp *interp (in)
Interpreter for the application.

DESCRIPTION

Tcl_AppInit is a ``hook`` procedure that is invoked by the main programs for Tcl applications such as tclsh and wish. Its purpose is to allow new Tcl applications to be created without modifying the main programs provided as part of Tcl and Tk. To create a new application you write a new version of Tcl_AppInit to replace the default version provided by Tcl, then link your new Tcl_AppInit with the Tcl library.

Tcl_AppInit is invoked after by Tcl_Main and Tk_Main after their own initialization and before entering the main loop to process commands. Here are some examples of things that Tcl_AppInit might do:

[1]: Call initialization procedures for various packages used by the application. Each initialization procedure adds new commands to interp for its package and performs other package-specific initialization.
[2]: Process command-line arguments, which can be accessed from the Tcl variables argv and argv0 in interp.
[3]: Invoke a startup script to initialize the application.

Tcl_AppInit returns TCL_OK or TCL_ERROR. If it returns TCL_ERROR then it must leave an error message in for the interpreter`s result; otherwise the result is ignored.

In addition to Tcl_AppInit, your application should also contain a procedure main that calls Tcl_Main as follows:

: Tcl_Main(argc, argv, Tcl_AppInit);

The third argument to Tcl_Main gives the address of the application-specific initialization procedure to invoke. This means that you don`t have to use the name Tcl_AppInit for the procedure, but in practice the name is nearly always Tcl_AppInit (in versions before Tcl 7.4 the name Tcl_AppInit was implicit; there was no way to specify the procedure explicitly). The best way to get started is to make a copy of the file tclAppInit.c from the Tcl library or source directory. It already contains a main procedure and a template for Tcl_AppInit that you can modify for your application.

KEYWORDS

application, argument, command, initialization, interpreter

argz_add

NAME

argz_add, argz_add_sep, argz_append, argz_count, argz_create, argz_create_sep, argz_delete, argz_extract, argz_insert, argz_next, argz_replace, argz_stringify - functions to handle an argz list

SYNOPSIS

#include <argz.h> error_t argz_add(char **argz, size_t *argz_len, const char *str); error_t argz_add_sep(char **argz, size_t *argz_len,
                    const char *str, int delim); error_t argz_append(char **argz, size_t *argz_len,
                    const char *buf, size_t buf_len); size_t argz_count(const char *argz, size_t argz_len); error_t argz_create(char * const argv[], char **argz,
                    size_t *argz_len); error_t argz_create_sep(const char *str, int sep, char **argz,
                    size_t *argz_len); error_t argz_delete(char **argz, size_t *argz_len, char *entry); void argz_extract(char *argz, size_t argz_len, char **argv); error_t argz_insert (char **argz, size_t *argz_len, char *before,
                    const char *entry); char * argz_next(char *argz, size_t argz_len, const char *entry); error_t argz_replace(char **argz, size_t *argz_len, const char *str,
                    const char *with, unsigned int *replace_count); void argz_stringify(char *argz, size_t len, int sep);

DESCRIPTION

These functions are glibc-specific.

An argz vector is a pointer to a character buffer together with a length. The intended interpretation of the character buffer is array of strings, where the strings are separated by NUL bytes. If the length is nonzero, the last byte of the buffer must be a NUL.

These functions are for handling argz vectors. The pair (NULL,0) is an argz vector, and, conversely, argz vectors of length 0 must have NULL pointer. Allocation of nonempty argz vectors is done using malloc(3), so that free(3) can be used to dispose of them again.

argz_add() adds the string str at the end of the array *argz, and updates *argz and *argz_len.

argz_add_sep() is similar, but splits the string str into substrings separated by the delimiter delim. For example, one might use this on a Unix search path with delimiter `:`.

argz_append() appends the argz vector (buf,buf_len) after (*argz,*argz_len) and updates *argz and *argz_len. (Thus, *argz_len will be increased by buf_len.)

argz_count() counts the number of strings, that is, the number of NUL bytes, in (argz,argz_len).

argz_create() converts a Unix-style argument vector argv, terminated by (char *) 0, into an argz vector (*argz,*argz_len).

argz_create_sep() converts the NUL-terminated string str into an argz vector (*argz,*argz_len) by breaking it up at every occurrence of the separator sep.

argz_delete() removes the substring pointed to by entry from the argz vector (*argz,*argz_len) and updates *argz and *argz_len.

argz_extract() is the opposite of argz_create(). It takes the argz vector (argz,argz_len) and fills the array starting at argv with pointers to the substrings, and a final NULL, making a Unix-style argv vector. The array argv must have room for argz_count(argz,argz_len) + 1 pointers.

argz_insert() is the opposite of argz_delete(). It inserts the argument entry at position before into the argz vector (*argz,*argz_len) and updates *argz and *argz_len. If before is NULL, then entry will inserted at the end.

argz_next() is a function to step trough the argz vector. If entry is NULL, the first entry is returned. Otherwise, the entry following is returned. It returns NULL if there is no following entry.

argz_replace() replaces each occurrence of str with with, reallocating argz as necessary. If replace_count is non-NULL, *replace_count will be incremented by the number of replacements.

argz_stringify() is the opposite of argz_create_sep(). It transforms the argz vector into a normal string by replacing all NULs except the last by sep.

RETURN VALUE

All argz functions that do memory allocation have a return type of error_t, and return 0 for success, and ENOMEM if an allocation error occurs.

BUGS

Argz vectors without final NUL may lead to Segmentation Faults.

NOTES

These functions are a GNU extension. Handle with care.

argz_append