This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: X11/Keysyms, Next: X11/Protocol, Prev: X11/Auth, Up: Module List Perl module for names of X11 keysyms ************************************ NAME ==== X11::Keysyms - Perl module for names of X11 keysyms SYNOPSIS ======== use X11::Keysyms '%Keysyms', qw(MISCELLANY XKB_KEYS LATIN1); %Keysyms_name = reverse %Keysyms; $ks = $Keysyms{'BackSpace'}; $name = $Keysysms_name{$ks}; DESCRIPTION =========== This module exports a hash mapping the names of X11 keysyms, such as 'A' or 'Linefeed' or 'Hangul_J_YeorinHieuh', onto the numbers that represent them. The first argument to 'use' is the name of the variable the hash should be exported into, and the rest are names of subsets of the keysysms to export: one or more of 'MISCELLANY', 'XKB_KEYS', '3270', 'LATIN1', 'LATIN2', 'LATIN3', 'LATIN4', 'KATAKANA', 'ARABIC', 'CYRILLIC', 'GREEK', 'TECHNICAL', 'SPECIAL', 'PUBLISHING', 'APL', 'HEBREW', 'THAI', 'KOREAN'. If this list is omitted, the list 'MISCELLANY', 'XKB_KEYS', 'LATIN1', 'LATIN2', 'LATIN3', 'LATIN4', 'GREEK' is used. AUTHOR ====== This module was generated semi-automatically by Stephen McCamant () from the header file 'X11/keysymdef.h', distributed by the X Consortium. SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *X Window System Protocol (X Version 11)*.  File: pm.info, Node: X11/Protocol, Next: X11/Protocol/Connection, Prev: X11/Keysyms, Up: Module List Perl module for the X Window System Protocol, version 11 ******************************************************** NAME ==== X11::Protocol - Perl module for the X Window System Protocol, version 11 SYNOPSIS ======== use X11::Protocol; $x = X11::Protocol->new(); $win = $x->new_rsrc; $x->CreateWindow($win, $x->root, 'InputOutput', $x->root_depth, 'CopyFromParent', ($x_coord, $y_coord), $width, $height, $border_w); ... DESCRIPTION =========== X11::Protocol is a client-side interface to the X11 Protocol (see X(1) for information about X11), allowing perl programs to display windows and graphics on X11 servers. A full description of the protocol is beyond the scope of this documentation; for complete information, see the *X Window System Protocol, X Version 11*, available as Postscript or *roff source from `ftp://ftp.x.org', or *Volume 0: X Protocol Reference Manual* of O'Reilly & Associates's series of books about X (ISBN 1-56592-083-X, `http://www.oreilly.com'), which contains most of the same information. DISCLAIMER ========== "The protocol contains many management mechanisms that are not intended for normal applications. Not all mechanisms are needed to build a particular user interface. It is important to keep in mind that the protocol is intended to provide mechanism, not policy." - Robert W. Scheifler BASIC METHODS ============= new --- $x = X11::Protocol->new(); $x = X11::Protocol->new($display_name); $x = X11::Protocol->new($connection); $x = X11::Protocol->new($display_name, [$auth_type, $auth_data]); $x = X11::Protocol->new($connection, [$auth_type, $auth_data]); Open a connection to a server. $display_name should be an X display name, of the form 'host:display_num.screen_num'; if no arguments are supplied, the contents of the DISPLAY environment variable are used. Alternatively, a pre-opened connection, of one of the X11::Protocol::Connection classes (see *Note X11/Protocol/Connection: X11/Protocol/Connection,, *Note X11/Protocol/Connection/FileHandle: X11/Protocol/Connection/FileHandle,, *Note X11/Protocol/Connection/Socket: X11/Protocol/Connection/Socket,, *Note X11/Protocol/Connection/UNIXFH: X11/Protocol/Connection/UNIXFH,, *Note X11/Protocol/Connection/INETFH: X11/Protocol/Connection/INETFH,, *Note X11/Protocol/Connection/UNIXSocket: X11/Protocol/Connection/UNIXSocket,, *Note X11/Protocol/Connection/INETSocket: X11/Protocol/Connection/INETSocket,) can be given. The authorization data is obtained using X11::Auth or the second argument. If the display is specified by $display_name, rather than $connection, a choose_screen() is also performed, defaulting to screen 0 if the '.screen_num' of the display name is not present. Returns the new protocol object. new_rsrc -------- $x->new_rsrc; Returns a new resource identifier. A unique resource ID is required for every object that the server creates on behalf of the client: windows, fonts, cursors, etc. (IDs are chosen by the client instead of the server for efficiency - the client doesn't have to wait for the server to acknowledge the creation before starting to use the object). handle_input ------------ $x->handle_input; Get one chunk of information from the server, and do something with it. If it's an error, handle it using the protocol object's handler ('error_handler' - default is kill the program with an explanatory message). If it's an event, pass it to the chosen event handler, or put it in a queue if the handler is 'queue'. If it's a reply to a request, save using the object's 'replies' hash for further processing. atom_name --------- $name = $x->atom_name($atom); Return the string corresponding to the atom $atom. This is similar to the GetAtomName request, but caches the result for efficiency. atom ---- $atom = $x->atom($name); The inverse operation; Return the (numeric) atom correspoding to $name. This is similar to the InternAtom request, but caches the result. choose_screen ------------- $x->choose_screen($screen_num); Indicate that you prefer to use a particular screen of the display. Per-screen information, such as 'root', 'width_in_pixels', and 'white_pixel' will be made avaliable as $x->{'root'} instead of $x->{'screens'}[$screen_num]{'root'} SYMBOLIC CONSTANTS ================== Generally, symbolic constants used by the protocol, like 'CopyFromParent' or 'PieSlice' are passed to methods as strings, and converted into numbers by the module. Their names are the same as those in the protocol specification, including capitalization, but with hyphens ('-') changed to underscores ('_') to look more perl-ish. If you want to do the conversion yourself for some reason, the following methods are avaliable: num --- $num = $x->num($type, $str) Given a string representing a constant and a string specifying what type of constant it is, return the corresponding number. $type should be a name like 'VisualClass' or 'GCLineStyle'. If the name is not recognized, it is returned intact. interp ------ $name = $x->interp($type, $num) The inverse operation; given a number and string specifying its type, return a string representing the constant. You can disable interp() and the module's internal interpretation of numbers by setting $x->{'do_interp'} to zero. Of course, this isn't very useful, unless you have you own definitions for all the constants. Here is a list of available constant types: AccessMode, AllowEventsMode, AutoRepeatMode, BackingStore, BitGravity, Bool, ChangePropertyMode, CirculateDirection, CirculatePlace, Class, ClipRectangleOrdering, CloseDownMode, ColormapNotifyState, CoordinateMode, CrossingNotifyDetail, CrossingNotifyMode, DeviceEvent, DrawDirection, Error, EventMask, Events, FocusDetail, FocusMode, GCArcMode, GCCapStyle, GCFillRule, GCFillStyle, GCFunction, GCJoinStyle, GCLineStyle, GCSubwindowMode, GrabStatus, HostChangeMode, HostFamily, ImageFormat, InputFocusRevertTo, KeyMask, LedMode, MapState, MappingChangeStatus, MappingNotifyRequest, PointerEvent, PolyShape, PropertyNotifyState, Request, ScreenSaver, ScreenSaverAction, Significance, SizeClass, StackMode, SyncMode, VisibilityState, VisualClass, WinGravity SERVER INFORMATION ================== At connection time, the server sends a large amount of information about itself to the client. This information is stored in the protocol object for future reference. It can be read directly, like $x->{'release_number'} or, for object oriented True Believers, using a method: $x->release_number The method method also has a one argument form for setting variables, but it isn't really useful for some of the more complex structures. Here is an example of what the object's information might look like: 'connection' => X11::Connection::UNIXSocket(0x814526fd), 'byte_order' => 'l', 'protocol_major_version' => 11, 'protocol_minor_version' => 0, 'authorization_protocol_name' => 'MIT-MAGIC-COOKIE-1', 'release_number' => 3110, 'resource_id_base' => 0x1c000002, 'motion_buffer_size' => 0, 'maximum_request_length' => 65535, # units of 4 bytes 'image_byte_order' => 'LeastSiginificant', 'bitmap_bit_order' => 'LeastSiginificant', 'bitmap_scanline_unit' => 32, 'bitmap_scanline_pad' => 32, 'min_keycode' => 8, 'max_keycode' => 134, 'vendor' => 'The XFree86 Project, Inc', 'pixmap_formats' => {1 => {'bits_per_pixel' => 1, 'scanline_pad' => 32}, 8 => {'bits_per_pixel' => 8, 'scanline_pad' => 32}}, 'screens' => [{'root' => 43, 'width_in_pixels' => 800, 'height_in_pixels' => 600, 'width_in_millimeters' => 271, 'height_in_millmerters' => 203, 'root_depth' => 8, 'root_visual' => 34, 'default_colormap' => 33, 'white_pixel' => 0, 'black_pixel' => 1, 'min_installed_maps' => 1, 'max_installed_maps' => 1, 'backing_stores' => 'Always', 'save_unders' => 1, 'current_input_masks' => 0x58003d, 'allowed_depths' => [{'depth' => 1, 'visuals' => []}, {'depth' => 8, 'visuals' => [ {'visual_id' => 34, 'blue_mask' => 0, 'green_mask' => 0, 'red_mask' => 0, 'class' => 'PseudoColor', 'bits_per_rgb_value' => 6, 'colormap_entries' => 256}, {'visual_id' => 35, 'blue_mask' => 0xc0, 'green_mask' => 0x38, 'red_mask' => 0x7, 'class' => 'DirectColor', 'bits_per_rgb_value' => 6, 'colormap_entries' => 8}, ...]}]], 'visuals' => {34 => {'depth' => 8, 'class' => 'PseudoColor', 'red_mask' => 0, 'green_mask' => 0, 'blue_mask'=> 0, 'bits_per_rgb_value' => 6, 'colormap_entries' => 256}, 35 => {'depth' => 8, 'class' => 'DirectColor', 'red_mask' => 0x7, 'green_mask' => 0x38, 'blue_mask'=> 0xc0, 'bits_per_rgb_value' => 6, 'colormap_entries' => 8}, ...} 'error_handler' => &\X11::Protocol::default_error_handler, 'event_handler' => sub {}, 'do_interp' => 1 REQUESTS ======== request ------- $x->request('CreateWindow', ...); $x->req('CreateWindow', ...); $x->CreateWindow(...); Send a protocol request to the server, and get the reply. For names of and information about individual requests, see below and/or the protocol reference manual. add_reply --------- $x->add_reply($sequence_num, \$var); Add a stub for an expected reply to the object's 'replies' hash. When a reply numbered $sequence_num comes, it will be stored in $var. delete_reply ------------ $x->delete_reply($sequence_num); Delete the entry in 'replies' for the specified reply. (This should be done after the reply is recieved). send ---- $x->send('CreateWindow', ...); Send a request, but do not wait for a reply. You must handle the reply, if any, yourself, using add_reply(), handle_input(), delete_reply(), and unpack_reply(), generally in that order. unpack_reply ------------ $x->unpack_reply('GetWindowAttributes', $data); Interpret the raw reply data $data, according to the reply format for the named request. Returns data in the same format as `request($request_name, ...)'. This section includes only a short calling summary for each request; for full descriptions, see the protocol standard. Argument order is usually the same as listed in the spec, but you generally don't have to pass lengths of strings or arrays, since perl keeps track. Symbolic constants are generally passed as strings. Most replies are returned as lists, but when there are many values, a hash is used. Lists usually come last; when there is more than one, each is passed by reference. In lists of multi-part structures, each element is a list ref. Parenthesis are inserted in arg lists for clarity, but are optional. Requests are listed in order by major opcode, so related requests are usually close together. Replies follow the '=>'. $x->CreateWindow($wid, $parent, $class, $depth, $visual, ($x, $y), $width, $height, $border_width, 'attribute' => $value, ...) $x->ChangeWindowAttributes($window, 'attribute' => $value, ...) $x->GetWindowAttributes($window) => ('backing_store' => $backing_store, ...) This is an example of a return value that is meant to be assigned to a hash. $x->DestroyWindow($win) $x->DestroySubwindows($win) $x->ChangeSaveSet($window, $mode) $x->ReparentWindow($win, $parent, ($x, $y)) $x->MapWindow($win) $x->MapSubwindows($win) $x->UnmapWindow($win) $x->UnmapSubwindows($win) $x->ConfigureWindow($win, 'attribute' => $value, ...) $x->CirculateWindow($win, $direction) Note that this request actually circulates the subwindows of $win, not the window itself. $x->GetGeometry($drawable) => ('root' => $root, ...) $x->QueryTree($win) => ($root, $parent, @kids) $x->InternAtom($name, $only_if_exists) => $atom $x->GetAtomName($atom) => $name $x->ChangeProperty($window, $property, $type, $format, $mode, $data) $x->DeleteProperty($win, $atom) $x->GetProperty($window, $property, $type, $offset, $length, $delete) => ($value, $type, $format, $bytes_after) Notice that the value comes first, so you can easily ignore the rest. $x->ListProperties($window) => (@atoms) $x->SetSelectionOwner($selection, $owner, $time) $x->GetSelectionOwner($selection) => $owner $x->ConvertSelection($selection, $target, $property, $requestor, $time) $x->SendEvent($destination, $propagate, $event_mask, $event) The $event argument should be the result of a pack_event() (see `"EVENTS"' in this node) $x->GrabPointer($grab_window, $owner_events, $event_mask, $pointer_mode, $keyboard_mode, $confine_to, $cursor, $time) => $status $x->UngrabPointer($time) $x->GrabButton($modifiers, $button, $grab_window, $owner_events, $event_mask, $pointer_mode, $keyboard_mode, $confine_to, $cursor) $x->UngrabButton($modifiers, $button, $grab_window) $x->ChangeActivePointerGrab($event_mask, $cursor, $time) $x->GrabKeyboard($grab_window, $owner_events, $pointer_mode, $keyboard_mode, $time) => $status $x->UngrabKeyboard($time) $x->GrabKey($key, $modifiers, $grab_window, $owner_events, $pointer_mode, $keyboard_mode) $x->UngrabKey($key, $modifiers, $grab_window) $x->AllowEvents($mode, $time) $x->GrabServer $x->UngrabServer $x->QueryPointer($window) => ('root' => $root, ...) $x->GetMotionEvents($start, $stop, $window) => ([$time, ($x, $y)], [$time, ($x, $y)], ...) $x->TranslateCoordinates($src_window, $dst_window, $src_x, $src_y) => ($same_screen, $child, $dst_x, $dst_y) $x->WarpPointer($src_window, $dst_window, $src_x, $src_y, $src_width, $src_height, $dst_x, $dst_y) $x->SetInputFocus($focus, $revert_to, $time) $x->GetInputFocus => ($focus, $revert_to) $x->QueryKeymap => $keys $keys is a bit vector, so you should use vec() to read it. $x->OpenFont($fid, $name) $x->CloseFont($font) $x->QueryFont($font) => ('min_char_or_byte2' => $min_char_or_byte2, ..., 'min_bounds' => [$left_side_bearing, $right_side_bearing, $character_width, $ascent, $descent, $attributes], ..., 'char_infos' => [[$left_side_bearing, $right_side_bearing, $character_width, $ascent, $descent, $attributes], ...], 'properties' => {$prop => $value, ...} ) $x->QueryTextExtents($font, $string) => ('draw_direction' => $draw_direction, ...) $x->ListFonts($pattern, $max_names) => @names $x->ListFontsWithInfo($pattern, $max_names) => ({'name' => $name, ...}, {'name' => $name, ...}, ...) The information in each hash is the same as the the information returned by QueryFont, but without per-character size information. This request is special in that it is the only request that can have more than one reply. This means you should probably only use request() with it, not send(), as the reply counting is complicated. Luckily, you never need this request anyway, as its function is completely duplicated by other requests. $x->SetFontPath(@strings) $x->GetFontPath => @strings $x->CreatePixmap($pixmap, $drawable, $depth, $width, $height) $x->FreePixmap($pixmap) $x->CreateGC($cid, $drawable, 'attribute' => $value, ...) $x->ChangeGC($gc, 'attribute' => $value, ...) $x->CopyGC($src, $dest, 'attribute', 'attribute', ...) $x->SetDashes($gc, $dash_offset, (@dashes)) $x->SetClipRectangles($gc, ($clip_x_origin, $clip_y_origin), $ordering, [$x, $y, $width, $height], ...) $x->ClearArea($window, ($x, $y), $width, $height, $exposures) $x->CopyArea($src_drawable, $dst_drawable, $gc, ($src_x, $src_y), $width, $height, ($dst_x, $dst_y)) $x->CopyPlane($src_drawable, $dst_drawable, $gc, ($src_x, $src_y), $width, $height, ($dst_x, $dst_y), $bit_plane) $x->PolyPoint($drawable, $gc, $coordinate_mode, ($x, $y), ($x, $y), ...) $x->PolyLine($drawable, $gc, $coordinate_mode, ($x, $y), ($x, $y), ...) $x->PolySegment($drawable, $gc, ($x, $y) => ($x, $y), ($x, $y) => ($x, $y), ...) $x->PolyRectangle($drawable, $gc, [($x, $y), $width, $height], ...) $x->PolyArc($drawable, $gc, [($x, $y), $width, $height, $angle1, $angle2], ...) $x->FillPoly($drawable, $gc, $shape, $coordinate_mode, ($x, $y), ...) $x->PolyFillRectangle($drawable, $gc, [($x, $y), $width, $height], ...) $x->PolyFillArc($drawable, $gc, [($x, $y), $width, $height, $angle1, $angle2], ...) $x->PutImage($drawable, $gc, $depth, $width, $height, ($dst_x, $dst_y), $left_pad, $format, $data) Currently, the module has no code to handle the various bitmap formats that the server might specify. Therefore, this request will not work portably without a lot of work. $x->GetImage($drawable, ($x, $y), $width, $height, $plane_mask, $format) $x->PolyText8($drawable, $gc, ($x, $y), ($font OR [$delta, $string]), ...) $x->PolyText16($drawable, $gc, ($x, $y), ($font OR [$delta, $string]), ...) $x->ImageText8($drawable, $gc, ($x, $y), $string) $x->ImageText16($drawable, $gc, ($x, $y), $string) $x->CreateColormap($mid, $visual, $window, $alloc) $x->FreeColormap($cmap) $x->CopyColormapAndFree($mid, $src_cmap) $x->InstallColormap($cmap) $x->UninstallColormap($cmap) $x->ListInstalledColormaps($window) => @cmaps $x->AllocColor($cmap, ($red, $green, $blue)) => ($pixel, ($red, $green, $blue)) $x->AllocNamedColor($cmap, $name) => ($pixel, ($exact_red, $exact_green, $exact_blue), ($visual_red, $visual_green, $visual_blue)) $x->AllocColorCells($cmap, $colors, $planes, $contiguous) => ([@pixels], [@masks]) $x->AllocColorPlanes($cmap, $colors, ($reds, $greens, $blues), $contiguous) => (($red_mask, $green_mask, $blue_mask), @pixels) $x->FreeColors($cmap, $plane_mask, @pixels) $x->StoreColors($cmap, [$pixel, $red, $green, $blue, $do_mask], ...) The 1, 2, and 4 bits in $mask are do-red, do-green, and do-blue. $mask can be omitted, defaulting to 7, the usual case - change the whole color. $x->StoreNamedColor($cmap, $pixel, $name, $do_mask) $do_mask has the same interpretation as above, but is mandatory. $x->QueryColors($cmap, @pixels) => ([$red, $green, $blue], ...) $x->LookupColor($cmap, $name) => (($exact_red, $exact_green, $exact_blue), ($visual_red, $visual_green, $visual_blue)) $x->CreateCursor($cid, $source, $mask, ($fore_red, $fore_green, $fore_blue), ($back_red, $back_green, $back_blue), ($x, $y)) $x->CreateGlyphCursor($cid, $source_font, $mask_font, $source_char, $mask_char, ($fore_red, $fore_green, $fore_blue), ($back_red, $back_green, $back_blue)) $x->FreeCursor($cursor) $x->RecolorCursor($cursor, ($fore_red, $fore_green, $fore_blue), ($back_red, $back_green, $back_blue)) $x->QueryBestSize($class, $drawable, $width, $height) => ($width, $height) $x->QueryExtension($name) => ($major_opcode, $first_event, $first_error) If the extension is not present, an empty list is returned. $x->ListExtensions => (@names) $x->ChangeModifierMapping($first_keycode, $keysysms_per_keycode, @keysyms) $x->GetKeyboardMapping($first_keycode, $count) => ($keysysms_per_keycode, [$keysym, ...], [$keysym, ...], ...) $x->ChangeKeyboardControl('attribute' => $value, ...) $x->GetKeyboardControl => ('global_auto_repeat' => $global_auto_repeat, ...) $x->Bell($percent) $x->ChangePointerControl($do_acceleration, $do_threshold, $acceleration_numerator, $acceleration_denominator, $threshold) $x->GetPointerControl => ($accerleration_numerator, $acceleration_denominator, $threshold) $x->SetScreenSaver($timeout, $interval, $prefer_blanking, $allow_exposures) $x->GetScreenSaver => ($timeout, $interval, $prefer_blanking, $allow_exposures) $x->ChangeHosts($mode, $host_family, $host_address) $x->ListHosts => ($mode, [$family, $host], ...) $x->SetAccessControl($mode) $x->SetCloseDownMode($mode) $x->KillClient($resource) $x->RotateProperties($win, $delta, @props) $x->ForceScreenSaver($mode) $x->SetPointerMapping(@map) => $status $x->GetPointerMapping => @map $x->SetModifierMapping(@keycodes) => $status $x->GetModiferMapping => @keycodes $x->NoOperation($length) $length specifies the length of the entire useless request, in four byte units, and is optional. EVENTS ====== To receive events, first set the 'event_mask' attribute on a window to indicate what types of events you desire (see `"pack_event_mask"' in this node). Then, set the protocol object's 'event_handler' to a subroutine reference that will handle the events. Alternatively, set 'event_handler' to 'queue', and retrieve events using dequeue_event(). In both cases, events are returned as a hash. For instance, a typical MotionNotify event might look like this: %event = ('name' => 'MotionNotify', 'sequence_number' => 12, 'state' => 0, 'event' => 58720256, 'root' => 43, 'child' => None, 'same_screen' => 1, 'time' => 966080746, 'detail' => 'Normal', 'event_x' => 10, 'event_y' => 3, 'code' => 6, 'root_x' => 319, 'root_y' => 235) pack_event_mask --------------- $mask = $x->pack_event_mask('ButtonPress', 'KeyPress', 'Exposure'); Make an event mask (suitable as the 'event_mask' of a window) from a list of strings specifying event types. unpack_event_mask ----------------- @event_types = $x->unpack_event_mask($mask); The inverse operation; convert an event mask obtained from the server into a list of names of event categories. dequeue_event ------------- %event = $x->dequeue_event; If there is an event waiting in the queue, return it. next_event ---------- %event = $x->next_event; Like Xlib's XNextEvent(), this function is equivalent to $x->handle_input until %event = dequeue_event; pack_event ---------- $data = $x->pack_event(%event); Given an event in hash form, pack it into a string. This is only useful as an argument to SendEvent(). unpack_event ------------ %event = $x->unpack_event($data); The inverse operation; given the raw data for an event (32 bytes), unpack it into hash form. Normally, this is done automatically. EXTENSIONS ========== Protocol extensions add new requests, event types, and error types to the protocol. Support for them is compartmentalized in modules in the X11::Protocol::Ext:: hierarchy. For an example, see `X11::Protocol::Ext:SHAPE' in this node. You can tell if the module has loaded an extension by looking at $x->{'ext'}{$extension_name} If the extension has been initialized, this value will be an array reference, [$major_request_number, $first_event_number, $first_error_number, $obj], where $obj is an object containing information private to the extension. init_extension -------------- $x->init_extension($name); Initialize an extension: query the server to find the extension's request number, then load the corresponding module. Returns 0 if the server does not support the named extension, or if no module to interface with it exists. init_extensions --------------- $x->init_extensions; Initialize protocol extensions. This does a ListExtensions request, then calls init_extension() for each extension that the server supports. WRITING EXTENSIONS ================== Internally, the X11::Protocol module is table driven. All an extension has to do is to add new add entries to the protocol object's tables. An extension module should `use X11::Protocol', and should define an new() method X11::Protocol::Ext::NAME ->new($x, $request_num, $event_num, $error_num) where $x is the protocol object and $request_num, $event_num and $error_num are the values returned by QueryExtension(). The new() method should add new types of constant like $x->{'ext_const'}{'ConstantType'} = ['Constant', 'Constant', ...] and set up the corresponding name to number translation hashes like $x->{'ext_const_num'}{'ConstType'} = {make_num_hash($x->{'ext_const'}{'ConstType'})} Event names go in $x->{'ext_const'}{'Events'}[$event_number] while specifications for event contents go in $x->{'ext_event'}[$event_number] each element of which is either `[\&unpack_sub, \&pack_sub]' or `[$pack_format, $field, $field, ...]', where each $field is `'name'', `['name', 'const_type']', or `['name', ['special_name_for_zero', 'special_name_for_one']]', where `'special_name_for_one'' is optional. Finally, $x->{'ext_request'}{$major_request_number} should be an array of arrays, with each array either `[$name, \&packit]' or `[$name, \&packit, \&unpackit]', and $x->{'ext_request_num'}{$request_name} should be initialized with `[$minor_num, $major_num]' for each request the extension defines. For examples of code that does all of this, look at X11::Protocol::Ext::SHAPE. X11::Protocol exports several functions that might be useful in extensions (note that these are not methods). padding ------- $p = padding $x; Given an integer, compute the number need to round it up to a multiple of 4. For instance, `padding(5)' is 3. pad --- $p = pad $str; Given a string, return the number of extra bytes needed to make a multiple of 4. Equivalent to `padding(length($str))'. padded ------ $data = pack(padded($str), $str); Return a format string, suitable for pack(), for a string padded to a multiple of 4 bytes. For instance, `pack(padded('Hello'), 'Hello')' gives `"Hello\0\0\0"'. hexi ---- $str = hexi $n; Format a number in hexidecimal, and add a "0x" to the front. make_num_hash ------------- %hash = make_num_hash(['A', 'B', 'C']); Given a reference to a list of strings, return a hash mapping the strings onto numbers representing their position in the list, as used by `$x->{'ext_const_num'}'. BUGS ==== This module is too big (~2500 lines), too slow (10 sec to load on a slow machine), too inefficient (request args are copied several times), and takes up too much memory (3000K for basicwin). If you have more than 65535 replies outstanding at once, sequence numbers can collide. The protocol is too complex. AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, `X(1)' in this node, *Note X11/Keysyms: X11/Keysyms,, *Note X11/Protocol/Ext/SHAPE: X11/Protocol/Ext/SHAPE,, *Note X11/Protocol/Ext/BIG_REQUESTS: X11/Protocol/Ext/BIG_REQUESTS,, *Note X11/Auth: X11/Auth,, *X Window System Protocol (X Version 11)*, *Inter-Client Communications Conventions Manual*, *X Logical Font Description Conventions*.  File: pm.info, Node: X11/Protocol/Connection, Next: X11/Protocol/Connection/FileHandle, Prev: X11/Protocol, Up: Module List Perl module abstract base class for X11 client to server connections ******************************************************************** NAME ==== X11::Protocol::Connection - Perl module abstract base class for X11 client to server connections SYNOPSIS ======== # In connection object module package X11::Protocol::Connection::CarrierPigeon; use X11::Protocol::Connection; @ISA = ('X11::Protocol::Connection'); sub open { ... } sub give { ... } sub get { ... } sub fh { ... } ... # In program $connection = X11::Protocol::Connection::CarrierPigeon ->open($host, $display_number); $x = X11::Protocol->new($connection); $connection->give($data); $reply = unpack("I", $connection->get(4)); use IO::Select; $sel = IO::select->new($connection->fh); if ($sel->can_read == $connection->fh) ... DESCRIPTION =========== This module is an abstract base class for the various X11::Protocol::Connection::* modules that provide connections to X servers for the X11::Protocol module. It provides stubs for the following methods: open ---- $conn = X11::Protocol::Connection::Foo->open($host, $display_num) Open a connection to the specified display (numbered from 0) on the specified $host. give ---- $conn->give($data) Send the given data to the server. Normally, this method is used only by the protocol module itself. get --- $data = $conn->get($n) Read $n bytes of data from the server. Normally, this method is used only by the protocol module itself. fh -- $filehandle = $conn->fh Return an object suitable for use as a filehandle. This is mainly useful for doing select() and other such system calls. AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *Note X11/Protocol/Connection/Socket: X11/Protocol/Connection/Socket,, *Note X11/Protocol/Connection/FileHandle: X11/Protocol/Connection/FileHandle,, *Note X11/Protocol/Connection/INETSocket: X11/Protocol/Connection/INETSocket,, *Note X11/Protocol/Connection/UNIXSocket: X11/Protocol/Connection/UNIXSocket,, *Note X11/Protocol/Connection/INETFH: X11/Protocol/Connection/INETFH,, *Note X11/Protocol/Connection/UNIXFH: X11/Protocol/Connection/UNIXFH,.  File: pm.info, Node: X11/Protocol/Connection/FileHandle, Next: X11/Protocol/Connection/INETFH, Prev: X11/Protocol/Connection, Up: Module List Perl module base class for FileHandle-based X11 connections *********************************************************** NAME ==== X11::Protocol::Connection::FileHandle - Perl module base class for FileHandle-based X11 connections SYNOPSIS ======== package X11::Protocol::Connection::WeirdFH; use X11::Protocol::Connection::FileHandle; @ISA = ('X11::Protocol::Connection::FileHandle') DESCRIPTION =========== This module defines get(), give() and fh() methods common to X11::Protocol::Connection types that are based on the FileHandle package. They expect the object they are called with to be a reference to a FileHandle. AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *Note X11/Protocol/Connection/INETFH: X11/Protocol/Connection/INETFH,, *Note X11/Protocol/Connection/UNIXFH: X11/Protocol/Connection/UNIXFH,, *Note FileHandle: FileHandle,.  File: pm.info, Node: X11/Protocol/Connection/INETFH, Next: X11/Protocol/Connection/INETSocket, Prev: X11/Protocol/Connection/FileHandle, Up: Module List Perl module for FileHandle-based TCP/IP X11 connections ******************************************************* NAME ==== X11::Protocol::Connection::INETFH - Perl module for FileHandle-based TCP/IP X11 connections SYNOPSIS ======== use X11::Protocol; use X11::Protocol::Connection::INETFH; $conn = X11::Protocol::Connection::INETFH ->open($host, $display_number); $x = X11::Protocol->new($conn); DESCRIPTION =========== This module is used by X11::Protocol to establish a connection and communicate with a server over an internet-type TCP/IP socket connection, using the FileHandle module. AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *Note X11/Protocol/Connection/UNIXFH: X11/Protocol/Connection/UNIXFH,, *Note X11/Protocol/Connection/FileHandle: X11/Protocol/Connection/FileHandle,, *Note FileHandle: FileHandle,.  File: pm.info, Node: X11/Protocol/Connection/INETSocket, Next: X11/Protocol/Connection/Socket, Prev: X11/Protocol/Connection/INETFH, Up: Module List Perl module for IO::Socket::INET-based X11 connections ****************************************************** NAME ==== X11::Protocol::Connection::INETSocket - Perl module for IO::Socket::INET-based X11 connections SYNOPSIS ======== use X11::Protocol; use X11::Protocol::Connection::INETSocket; $conn = X11::Protocol::Connection::INETSocket ->open($host, $display_number); $x = X11::Protocol->new($conn); DESCRIPTION =========== This module is used by X11::Protocol to establish a connection and communicate with a server over a TCP/IP connection, using the IO::Socket::INET module. AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *Note X11/Protocol/Connection/Socket: X11/Protocol/Connection/Socket,, *Note X11/Protocol/Connection/UNIXSocket: X11/Protocol/Connection/UNIXSocket,, *Note IO/Socket: IO/Socket,.  File: pm.info, Node: X11/Protocol/Connection/Socket, Next: X11/Protocol/Connection/UNIXFH, Prev: X11/Protocol/Connection/INETSocket, Up: Module List Perl module base class for IO::Socket-based X11 connections *********************************************************** NAME ==== X11::Protocol::Connection::Socket - Perl module base class for IO::Socket-based X11 connections SYNOPSIS ======== package X11::Protocol::Connection::WeirdSocket; use X11::Protocol::Connection::Socket; @ISA = ('X11::Protocol::Connection::Socket') DESCRIPTION =========== This module defines get(), give() and fh() methods common to X11::Protocol::Connection types that are based on IO::Socket. They expect the object they are called with to be a reference to an IO::Socket. AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *Note X11/Protocol/Connection/INETSocket: X11/Protocol/Connection/INETSocket,, *Note X11/Protocol/Connection/UNIXSocket: X11/Protocol/Connection/UNIXSocket,, *Note IO/Socket: IO/Socket,.  File: pm.info, Node: X11/Protocol/Connection/UNIXFH, Next: X11/Protocol/Connection/UNIXSocket, Prev: X11/Protocol/Connection/Socket, Up: Module List Perl module for FileHandle-based Unix-domain X11 connections ************************************************************ NAME ==== X11::Protocol::Connection::UNIXFH - Perl module for FileHandle-based Unix-domain X11 connections SYNOPSIS ======== use X11::Protocol; use X11::Protocol::Connection::UNIXFH; $conn = X11::Protocol::Connection::UNIXFH ->open($host, $display_number); $x = X11::Protocol->new($conn); DESCRIPTION =========== This module is used by X11::Protocol to establish a connection and communicate with a server over a local Unix-domain socket connection, using the FileHandle module. The host argument is ignored. AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *Note X11/Protocol/Connection/INETFH: X11/Protocol/Connection/INETFH,, *Note X11/Protocol/Connection/FileHandle: X11/Protocol/Connection/FileHandle,, *Note FileHandle: FileHandle,.  File: pm.info, Node: X11/Protocol/Connection/UNIXSocket, Next: X11/Protocol/Ext/BIG_REQUESTS, Prev: X11/Protocol/Connection/UNIXFH, Up: Module List Perl module for IO::Socket::UNIX-based X11 connections ****************************************************** NAME ==== X11::Protocol::Connection::UNIXSocket - Perl module for IO::Socket::UNIX-based X11 connections SYNOPSIS ======== use X11::Protocol; use X11::Protocol::Connection::UNIXSocket; $conn = X11::Protocol::Connection::UNIXSocket ->open($host, $display_number); $x = X11::Protocol->new($conn); DESCRIPTION =========== This module is used by X11::Protocol to establish a connection and communicate with a server over a local Unix-domain socket connection, using the IO::Socket::UNIX module. The host argument is ignored. AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *Note X11/Protocol/Connection/INETSocket: X11/Protocol/Connection/INETSocket,, *Note X11/Protocol/Connection/Socket: X11/Protocol/Connection/Socket,, *Note IO/Socket: IO/Socket,.  File: pm.info, Node: X11/Protocol/Ext/BIG_REQUESTS, Next: X11/Protocol/Ext/SHAPE, Prev: X11/Protocol/Connection/UNIXSocket, Up: Module List Perl module for the X11 protocol Big Requests extension ******************************************************* NAME ==== X11::Protocol::Ext::BIG_REQUESTS - Perl module for the X11 protocol Big Requests extension SYNOPSIS ======== use X11::Protocol; $x = X11::Protocol->new($ENV{'DISPLAY'}); $x->init_extension('BIG_REQUESTS') or die; DESCRIPTION =========== This module is used by the X11::Protocol module to participate in the 'Big Requests' extension to the X protocol. Once initialized, it transparently allows requests of more than 262140 (65535 * 4) bytes. The new maximum request length is avaliable as `$x->maximum_request_length'. AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *Big Requests Extension (X Consortium Standard)*.  File: pm.info, Node: X11/Protocol/Ext/SHAPE, Next: X500/DN/Parser, Prev: X11/Protocol/Ext/BIG_REQUESTS, Up: Module List Perl module for the X11 Protocol Nonrectangular Window Shape Extension ********************************************************************** NAME ==== X11::Protocol::Ext::SHAPE - Perl module for the X11 Protocol Nonrectangular Window Shape Extension SYNOPSIS ======== use X11::Protocol; $x = X11::Protocol->new($ENV{'DISPLAY'}); $x->init_extension('SHAPE') or die; DESCRIPTION =========== This module is used by the X11::Protocol module to participate in the shaped window extension to the X protocol, allowing windows to be of any shape, not just rectangles. SYMBOLIC CONSTANTS ================== This extension adds the constant types 'ShapeKind' and 'ShapeOp', with values as defined in the standard. EVENTS ====== This extension adds the event type 'ShapeNotify', with values as specified in the standard. This event is selected using the ShapeSelectInput() request. REQUESTS ======== This extension adds several requests, called as shown below: $x->ShapeQueryVersion => ($major, $minor) $x->ShapeRectangles($dest, $destKind, $op, $xOff, $yOff, $ordering, @rectangles) $x->ShapeMask($dest, $destKind, $op, $xOff, $yOff, $source) $x->ShapeCombine($dest, $destKind, $op, $xOff, $yOff, $source, $sourceKind) $x->ShapeOffset($dest, $destKind, $xOff, $yOff) $x->ShapeQueryExtents($dest) => ($boundingShaped, $clipShaped, ($xBoundingShape, $yBoundingShape, $widthBoundingShape, $heightBoundingShape) ($xClipShape, $yClipShape, $widthClipShape, $heightClipShape)) $x->ShapeSelectInput($window, $enable) $x->ShapeInputSelected($window) => $enable $x->ShapeGetRectangles($window, $kind) => ($ordering, [$x, $y, $width, $height], ...) AUTHOR ====== Stephen McCamant . SEE ALSO ======== `perl(1)' in this node, *Note X11/Protocol: X11/Protocol,, *Nonrectangular Window Shape Extension (X Consortium Standard)*.  File: pm.info, Node: X500/DN/Parser, Next: XBase, Prev: X11/Protocol/Ext/SHAPE, Up: Module List Parse X500 Distinguished Names ****************************** NAME ==== `X500::DN::Parser' - Parse X500 Distinguished Names SYNOPSIS ======== use X500::DN::Parser; my($parser) = new X500::DN::Parser(\&errorInDN); my($dn, $genericDN, %RDN) = $parser -> parse('c=au;o=MagicWare;cn=Ron Savage', 'c', '[l]', 'o', '[ou]', 'cn'); DESCRIPTION =========== Parse DNs where the caller knows the number of RDNs. parse() ======= Input Parameters: * DN to be parsed * A list of the expected components of the DN. Any component can be put in [] to indicate that that component is optional Output List: * $dn: The DN passed in * $genericDN: A generic DN matching the given DN * %component: The components of the DN and their values. Eg: If $dn = 'c=au;o=MagicWare', then these key/values appear: 'c' => 'au', 'o' => 'MagicWare' INSTALLATION ============ You install `X500::DN::Parser', as you would install any perl module library, by running these commands: perl Makefile.PL make make test make install If you want to install a private copy of `X500::DN::Parser' in your home directory, then you should try to produce the initial Makefile with something like this command: perl Makefile.PL LIB=~/perl or perl Makefile.PL LIB=C:/Perl/Site/Lib If, like me, you don't have permission to write man pages into unix system directories, use: make pure_install instead of make install. This option is secreted in the middle of p 414 of the second edition of the dromedary book. AUTHOR ====== `X500::DN::Parser' was written by Ron Savage ** in 1999. LICENCE ======= This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: XBase, Next: XBase/Base, Prev: X500/DN/Parser, Up: Module List Perl module for reading and writing the dbf files ************************************************* NAME ==== XBase - Perl module for reading and writing the dbf files SYNOPSIS ======== use XBase; my $table = new XBase "dbase.dbf" or die XBase->errstr; for (0 .. $table->last_record) { my ($deleted, $id, $msg) = $table->get_record($_, "ID", "MSG"); print "$id:\t$msg\n" unless $deleted; } DESCRIPTION =========== This module can read and write XBase database files, known as dbf in dBase and FoxPro world. It also reads memo fields from the dbt and fpt files, if needed. An alpha code of reading index support for ndx, ntx, mdx, idx and cdx is available for testing - see the DBD::Index(3) man page. Module XBase provides simple native interface to XBase files. For DBI compliant database access, see the DBD::XBase and DBI modules and their man pages. The following methods are supported by XBase module: General methods --------------- new Creates the XBase object, loads the info about the table form the dbf file. The first parameter should be the name of existing dbf file (table, in fact) to read. A suffix .dbf will be appended if needed. This method creates and initializes new object, will also check for memo file, if needed. The parameters can also be specified in the form of hash: value of name is then the name of the table, other flags supported are: *memofile* specifies non standard name for the associated memo file. By default it's the name of the dbf file, with extension dbt or fpt. *ignorememo* ignore memo file at all. This is usefull if you've lost the dbt file and you do not need it. Default is false. *memosep* separator of memo records in the dBase III dbt files. The standard says it should be `"\x1a\x1a"'. There are however implamentations that only put in one `"\x1a"'. XBase.pm tries to guess which is valid for your dbt but if it fails, you can tell it yourself. *nolongchars* prevents XBase to treat the decimal value of character fields as high byte of the length - there are some broken products around producing character fields with decimal values set. my $table = new XBase "table.dbf" or die XBase->errstr; my $table = new XBase "name" => "table.dbf", "ignorememo" => 1; close Closes the object/file, no arguments. create Creates new database file on disk and initializes it with 0 records. A dbt (memo) file will be also created if the table contains some memo fields. Parameters to create are passed as hash. You can call this method as method of another XBase object and then you only need to pass name value of the hash; the structure (fields) of the new file will be the same as of the original object. If you call create using class name (XBase), you have to (besides name) also specify another four values, each being a reference to list: *field_names*, *field_types*, *field_lengths* and *field_decimals*. The field types are specified by one letter strings (C, N, L, D, ...). If you set some value as undefined, create will make it into some reasonable default. my $newtable = $table->create("name" => "copy.dbf"); my $newtable = XBase->create("name" => "copy.dbf", "field_names" => [ "ID", "MSG" ], "field_types" => [ "N", "C" ], "field_lengths" => [ 6, 40 ], "field_decimals" => [ 0, undef ]); Other attributes are *memofile* for non standard memo file location, version to force different version of the dbt (dbt) file. The default is the version of the object you create the new from, or 3 if you call this as class method (XBase->create). The new file mustn't exist yet - XBase will not allow you to overwrite existing table. Use drop (or unlink) to delete it first. drop This method closes the table and deletes it on disk (including associated memo file, if there is any). last_record Returns number of the last record in the file. The lines deleted but present in the file are included in this number. last_field Returns number of the last field in the file, number of fields minus 1. field_names, field_types, field_lengths, field_decimals Return list of field names and so on for the dbf file. field_type, field_length, field_decimal For a field name, returns the appropriate value. Returns undef if the field doesn't exist in the table. Reading the data one by one --------------------------- When dealing with the records one by one, reading or writing (the following six methods), you have to specify the number of the record in the file as the first argument. The range is `0 .. $table->last_record'. get_record Returns a list of data (field values) from the specified record (line of the table). The first parameter in the call is the number of the record. If you do not specify any other parameters, all fields are returned in the same order as they appear in the file. You can also put list of field names after the record number and then only those will be returned. The first value of the returned list is always the 1/0 `_DELETED' value saying whether the record is deleted or not, so on success, get_record never returns empty list. get_record_nf Instead if the names of the fields, you can pass list of numbers of the fields to read. get_record_as_hash Returns hash (in list context) or reference to hash (in scalar context) containing field values indexed by field names. The name of the deleted flag is `_DELETED'. The only parameter in the call is the record number. The field names are returned as uppercase. Writing the data ---------------- All three writing methods always undelete the record. On success they return true - the record number actually written. set_record As parameters, takes the number of the record and the list of values of the fields. It writes the record to the file. Unspecified fields (if you pass less than you should) are set to undef/empty. set_record_hash Takes number of the record and hash as parameters, sets the fields, unspecified are undefed/emptied. update_record_hash Like set_record_hash but fields that do not have value specified in the hash retain their value. To explicitely delete/undelete a record, use methods delete_record or *undelete_record* with record number as a parameter. Assorted examples of reading and writing: my @data = $table->get_record(3, "jezek", "krtek"); my $hashref = $table->get_record_as_hash(38); $table->set_record_hash(8, "jezek" => "jezecek", "krtek" => 5); $table->undelete_record(4); This is a code to update field MSG in record where ID is 123. use XBase; my $table = new XBase "test.dbf" or die XBase->errstr; for (0 .. $table->last_record) { my ($deleted, $id) = $table->get_record($_, "ID") die $table->errstr unless defined $deleted; next if $deleted; $table->update_record_hash($_, "MSG" => "New message") if $id == 123; } Sequentially reading the file ----------------------------- If you plan to sequentially walk through the file, you can create a cursor first and then repeatedly call fetch to get next record. prepare_select As parameters, pass list of field names to return, if no parameters, the following fetch will return all fields. prepare_select_with_index The first parameter is the file name of the index file, the rest is as above. For index types that can hold more index structures in on file, use arrayref instead of the file name and in that array include file name and the tag name, and optionaly the index type. The fetch will then return records in the ascending order, according to the index. Prepare will return object cursor, the following method are methods of the cursor, not of the table. fetch Returns the fields of the next available undeleted record. The list thus doesn't contain the `_DELETED' flag since you are guaranteed that the record is not deleted. fetch_hashref Returns a hash reference of fields for the next non deleted record. last_fetched Returns the number of the record last fetched. find_eq This only works with cursor created via prepare_select_with_index. Will roll to the first record what is equal to specified argument, or to the first greater if there is none equal. The following fetches then continue normally. Examples of using cursors: my $table = new XBase "names.dbf" or die XBase->errstr; my $cursor = $table->prepare_select("ID", "NAME", "STREET"); while (my @data = $cursor->fetch) { ### do something here, like print "@data\n"; } my $table = new XBase "employ.dbf"; my $cur = $table->prepare_select_with_index("empid.ndx"); ## my $cur = $table->prepare_select_with_index( ["empid.cdx", "ADDRES"], "id", "address"); $cur->find_eq(1097); while (my $hashref = $cur->fetch_hashref and $hashref->{"ID"} == 1097) { ### do something here with $hashref } The second example shows that after you have done find_eq, the fetches continue untill the end of the index, so you have to check whether you are still on records with given value. And if there is no record with value 1097 in the indexed field, you will just get the next record in the order. The updating example can be rewritten to: use XBase; my $table = new XBase "test.dbf" or die XBase->errstr; my $cursor = $table->prepare_select("ID") while (my ($id) = $cursor->fetch) { $table->update_record_hash($cursor->last_fetched, "MSG" => "New message") if $id == 123 } Dumping the content of the file ------------------------------- A method *get_all_records* returns reference to an array containing array of values for each undeleted record at once. As parameters, pass list of fields to return for each record. To print the content of the file in a readable form, use method *dump_records*. It prints all not deleted records from the file. By default, all fields are printed, separated by colons, one record on a row. The method can have parameters in a form of a hash with the following keys: rs Record separator, string, newline by default. fs Field separator, string, one colon by default. fields Reference to a list of names of the fields to print. By default it's undef, meaning all fields. undef What to print for undefined (NULL) values, empty string by default. Example of use is use XBase; my $table = new XBase "table" or die XBase->errstr; $table->dump_records("fs" => " | ", "rs" => " <-+\n", "fields" => [ "id", "msg" ]);' Also note that there is a script dbfdump(1) that does the printing. Errors and debugging -------------------- If the method fails (returns false or null list), the error message can be retrieved via *errstr* method. If the new or create method fails, you have no object so you get the error message using class syntax `XBase->errstr()'. The method *header_info* returns (not prints) string with information about the file and about the fields. Module XBase::Base(3) defines some basic functions that are inherited by both XBase and XBase::Memo(3) module. DATA TYPES ========== The character fields are returned "as is". No charset or other translation is done. The numbers are converted to Perl numbers. The date fields are returned as 8 character string of the 'YYYYMMDD' form and when inserting the date, you again have to provide it in this form. No checking for the validity of the date is done. The datetime field is returned in the number of seconds since 1970/1/1, possibly with decimal part (since it allows precision up to 1/1000 s). To get the fields, use the gmtime (or similar) Perl function. If there is a memo field in the dbf file, the module tries to open file with the same name but extension dbt, fpt or smt. It uses module XBase::Memo(3) for this. It reads and writes this memo field transparently (you do not know about it) and returns the data as single scalar. INDEX, LOCKS ============ *New:* A support for ndx, ntx, mdx, idx and cdx index formats is available with alpha status for testing. Some of the formats are already rather stable (ndx). Please read the XBase::Index(3) man page and the eg/use_index file in the distribution for examples and ideas. Send me examples of your data files and suggestions for interface if you need indexes. General locking methods are *locksh*, *lockex* and unlock for shared lock, exclusive lock and unlock. They call flock but you can redefine then in XBase::Base package. INFORMATION SOURCE ================== This module is built using information from and article XBase File Format Description by Erik Bachmann, URL http://www.e-bachmann.dk/docs/xbase.htm Thanks a lot. VERSION ======= 0.173 AUTHOR ====== (c) 1997-2001 Jan Pazdziora, adelton@fi.muni.cz, http://www.fi.muni.cz/~adelton/ at Faculty of Informatics, Masaryk University in Brno, Czech Republic All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself. THANKS ====== Many people have provided information, test files, test results and patches. This project would not be so great without them. See the Changes file for (I hope) complete list. Thank you all, guys! Special thanks go to Erik Bachmann for his great page about the file structures; to Frans van Loon, William McKee, Randy Kobes and Dan Albertsson for longtime cooperation and many emails we've exchanged when fixing and polishing the modules' behaviour; and to Dan Albertsson for providing support for the project. SEE ALSO ======== perl(1); XBase::FAQ(3); DBD::XBase(3) and DBI(3) for DBI interface; dbfdump(1)