NAME
   Pointer - Object Oriented Memory Pointers in Pure Perl

SYNOPSIS
    use Pointer;
    use Pointer::int;
    use Pointer::sv;

    # Hello, world the hard way
    print pointer->of_scalar("Hello, world")->get_pointer->get_pointer->get_string;

    # Test to see if a scalar is a string
    print "It's a string!"
      if pointer('sv')->of_scalar('12345')->sv_flags & SVf_POK;

    # Hex dump of the first 3 words of the SV for $/
    print "> $_\n" for pointer('int')->of_scalar($/)->get_hex(3);

    # Print 5 integers 10 integers away from the address of $$
    print((pointer('int')->of_scalar($$) + 10)->get(5));

DESCRIPTION
   This module allows you to create Perl objects that emulate C pointers.
   You can use them to read and explore the memory of your Perl process.

   Pointer.pm (and every subclass) exports a function called "pointer" that
   returns a new pointer object. Each object has a type like (void, int,
   long, sv). Support for each pointer type is written as a subclass of
   Pointer.pm. Pointer.pm itself is for type "void". To create a pointer to
   a long integer, do:

       use Pointer::long;
       my $p = pointer('long');

   Your new pointer is not pointing to anything yet. One way to put an
   address into the pointer is directly, like this:

       $p->to(0x123456);

   Another way is to point it at an existing scalar like this:

       $p->of_scalar($foo);

   Both of these methods return the pointer so that you can chain other
   methods onto them:

       my $int = $p->of_scalar($foo)->get;

   The "get" method returns whatever the pointer points to. Since $p is an
   integer pointer, this call returns an integer. The "get" method takes an
   optional number as an argument, which indicates the number of values to
   get.

   Pointer pointers honor pointer arithmetic. If you add or subtract a
   number to a pointer, the result is another pointer. As in C pointer
   arithmetic, the number of bytes added to the address depends on the size
   of the type represented by the pointer.

       my $p1 = pointer('long')->of_scalar($foo);
       my $p2 = $p1 - 5;

   is the same as:

       my $p1 = pointer('long')->of_scalar($foo);
       my $p2 = pointer('long')->address($p1->address - 5 * $p1->sizeof);

METHODS
   The following methods are available for all pointers:

   * to()
       Sets the address of a pointer to a specific integer. Returns the
       pointer object for chaining calls.

   * of_scalar()
       Sets the address of a pointer to the address a Perl scalar or SV.
       Returns the pointer object for chaining calls.

   * address()
       Returns the memory address of the pointer as an integer.

   * hex_address()
       Returns the address as a hexadecimal string.

   * type()
       Returns the type of the pointer.

   * sizeof()
       Returns the size (in bytes) of whatever type of data is pointed to.

   * get()
       Get the item(s) pointed to by the pointer. This function takes a
       numeric argument indicating how many items you want to retrieve. The
       function returns a list of the items requested.

   * get_hex()
       Similar to "get", but returns the items in hexadeciaml.

   * get_string()
       Returns the null terminated string pointed to by the pointer.

   * get_pointer()
       If your pointer points to a pointer address, this call will take the
       pointer address, and return a new pointer object that contains it.
       You can pass in the type of the new pointer. The default type is a
       void pointer.

   * get_raw()
       Returns the raw byte content pointed to by the pointer. You will
       need to unpack the raw data yourself. Takes an argument indicating
       how many bytes to return.

SUBCLASSING
   Pointer.pm was made to be subclassed. Every type of pointer is a
   subclass. See the modules: Pointer::int, Pointer::long and Pointer::sv
   for examples.

BUGS & DEFICIENCIES
   Pointers are tricky beasts, and there are myriad platform issues. At
   this point, Pointer.pm is but a naive attempt at a novel idea. Hopefully
   it can be fleshed out into a robust and serious module.

   Support for pointers to structs is minimal, but is a primary design
   goal. Pointer ships with a subclass for the sv struct as an example.
   Expect better struct support in a future release.

   If you have a good feel for C pointers, and grok where I am trying to go
   with this module, please send me an email with your good ideas.

AUTHOR
   Brian Ingerson <[email protected]>

COPYRIGHT
   Copyright (c) 2004. Brian Ingerson. All rights reserved.

   This program is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

   See <http://www.perl.com/perl/misc/Artistic.html>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.