Reini Urban > C-DynaLib > C::DynaLib::Struct

Download:
C-DynaLib-0.61.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Source  

NAME ^

C::DynaLib::Struct - Tool for handling the C `struct' data type

SYNOPSIS ^

  use C::DynaLib::Struct;

  Define C::DynaLib::Struct(
        $struct_tag,
        $template0, \@field_names0,
        [$template1, \@field_names1,]
        ... );

  C::DynaLib::Struct::Parse <<ENDC;
  struct packet {
    unsigned short header;
    unsigned short flags;
    unsigned char  payload[28];
  };
  ENDC

  $rstruct = tie( $struct, $struct_tag [, @initializer_list] );
  $value = $rstruct->my_field();
  $rstruct->my_field( $new_value );

  $pointer_to_struct = pack( 'p', $struct );
  $struct = $new_struct;  # assigns all fields at once

  # after passing pointer-to-struct to a C function:
  $rstruct->Unpack();
  $returned_value = $rstruct->my_field();

DESCRIPTION ^

When mixing Perl and C, the conversion of data types can be rather tedious and error-prone. This module provides an abstraction from Perl's pack and unpack operators for using structures whose member data types and positions do not change.

Here are some examples of C code that deals with a struct. On the right are some possible Perl equivalents.

    C                           Perl
    -                           ----
    typedef struct {            use C::DynaLib::Struct;
        int     m_int;          Define C::DynaLib::Struct(
        double  m_double;           'Foo',
        char *  m_string;           'i' => ['m_int'],
    } Foo;                          'd' => ['m_double'],
                                    'p' => ['m_string'] );
                                # or, equivalently,
                                Define C::DynaLib::Struct('Foo',
                                    'idp', [qw(m_int m_double m_string)]);

    Foo foo;
    Foo *pfoo = &foo;           $rfoo = tie ($foo, 'Foo');

    i = pfoo->m_int;            $i = $rfoo->m_int;

    d = foo.m_double;           $d = (tied $foo)->m_double;

    pfoo->m_string = "hi";      $rfoo->m_string("hi");

    Foo bar;                    tie ($bar, 'Foo');
    bar = foo;                  $bar = $foo;

    void do_foo(Foo *arg);      use C::DynaLib;
                                $lib = new C::DynaLib("-lfoo");
                                $do_foo = $lib->DeclareSub("do_foo","","P");
                                # or you could write an XSUB.

    do_foo(&foo);               &$do_foo($foo);

    returned_i = foo.m_int;     $rfoo->Unpack();
                                $returned_i = $rfoo->m_int;

FUNCTIONS ^

Define ( $new_class )

Parse ( c-string or Convert::Binary::C object )

BUGS ^

Data member access is through autoloaded methods, so actual existing methods are not allowed as structure member names. Currently, the illegal names are AUTOLOAD, TIESCALAR, FETCH, STORE, and Unpack.

The names of Structs themselves must be allowable package names. Using an existing package name will cause problems.

structs mean different things to different C compilers on different machines. Use caution when assigning pack codes to C data types.

SEE ALSO ^

Convert::Binary::C, perlfunc(1) (for pack), perlref(1), perltie(1).

syntax highlighting: