Simple

  use Convert::Binary::C;
  
  #---------------------------------------------
  # Create a new object and parse embedded code
  #---------------------------------------------
  my $c = Convert::Binary::C->new->parse(<<ENDC);
  
  enum Month { JAN, FEB, MAR, APR, MAY, JUN,
               JUL, AUG, SEP, OCT, NOV, DEC };
  
  struct Date {
    int        year;
    enum Month month;
    int        day;
  };
  
  ENDC
  
  #-----------------------------------------------
  # Pack Perl data structure into a binary string
  #-----------------------------------------------
  my $date = { year => 2002, month => 'DEC', day => 24 };
  
  my $packed = $c->pack('Date', $date);

Advanced

  use Convert::Binary::C;
  use Data::Dumper;
  
  #---------------------
  # Create a new object
  #---------------------
  my $c = Convert::Binary::C->new(ByteOrder => 'BigEndian');
  
  #---------------------------------------------------
  # Add include paths and global preprocessor defines
  #---------------------------------------------------
  $c->Include('/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/include',
              '/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/include-fixed',
              '/usr/include')
    ->Define(qw( __USE_POSIX __USE_ISOC99=1 ));
  
  #----------------------------------
  # Parse the 'time.h' header file
  #----------------------------------
  $c->parse_file('time.h');
  
  #---------------------------------------
  # See which files the object depends on
  #---------------------------------------
  print Dumper([$c->dependencies]);
  
  #-----------------------------------------------------------
  # See if struct timespec is defined and dump its definition
  #-----------------------------------------------------------
  if ($c->def('struct timespec')) {
    print Dumper($c->struct('timespec'));
  }
  
  #-------------------------------
  # Create some binary dummy data
  #-------------------------------
  my $data = "binary_test_string";
  
  #--------------------------------------------------------
  # Unpack $data according to 'struct timespec' definition
  #--------------------------------------------------------
  if (length($data) >= $c->sizeof('timespec')) {
    my $perl = $c->unpack('timespec', $data);
    print Dumper($perl);
  }
  
  #--------------------------------------------------------
  # See which member lies at offset 5 of 'struct timespec'
  #--------------------------------------------------------
  my $member = $c->member('timespec', 5);
  print "member('timespec', 5) = '$member'\n";

Background and History

Another part of this real-time debugger was a Perl application running on my workstation that gathered all the messages that were sent out from the embedded device. It printed all the strings and numbers, and hex-dumped the arbitrary data. However, manually parsing a couple of 300 byte hex-dumps of a complex C structure is not only frustrating, but also error-prone and time consuming.

Using "unpack" to retrieve the contents of a C structure works fine for small structures and if you don't have to deal with struct member alignment. But otherwise, maintaining such code can be as awful as deciphering hex-dumps.

As I didn't find anything to solve my problem on the CPAN, I wrote a little module that translated simple C structs into "unpack" strings. It worked, but it was slow. And since it couldn't deal with struct member alignment, I soon found myself adding padding bytes everywhere. So again, I had to maintain two sources, and changing one of them forced me to touch the other one.

All in all, this little module seemed to make my task a bit easier, but it was far from being what I was thinking of:

• A module that could directly use the source I've been coding for the embedded device without any modifications.
• A module that could be configured to match the properties of the different compilers and target platforms I was using.
• A module that was fast enough to decode a great amount of binary data even on my slow workstation.

I didn't know how to accomplish these tasks until I read something about XS. At least, it seemed as if it could solve my performance problems. However, writing a C parser in C isn't easier than it is in Perl. But writing a C preprocessor from scratch is even worse.

Fortunately enough, after a few weeks of searching I found both, a lean, open-source C preprocessor library, and a reusable YACC grammar for ANSI-C. That was the beginning of the development of Convert::Binary::C in late 2001.

Now, I'm successfully using the module in my embedded environment since long before it appeared on CPAN. From my point of view, it is exactly what I had in mind. It's fast, flexible, easy to use and portable. It doesn't require external programs or other Perl modules.

About this document

To look up one of the manpages, use the "perldoc" command. For example,

  perldoc perl

will show you Perl's main manpage. To look up a specific Perl function, use "perldoc -f":

  perldoc -f map

gives you more information about the "map" function. You can also search the FAQ using "perldoc -q":

  perldoc -q array

will give you everything you ever wanted to know about Perl arrays. But now, let's go on with some real stuff!

Why use Convert::Binary::C?

  struct foo {
    char ary[3];
    unsigned short baz;
    int bar;
  };

You could of course use Perl's "pack" and "unpack" functions:

  @ary = (1, 2, 3);
  $baz = 40000;
  $bar = -4711;
  $binary = pack 'c3 S i', @ary, $baz, $bar;

But this implies that the struct members are byte aligned. If they were long aligned (which is the default for most compilers), you'd have to write

  $binary = pack 'c3 x S x2 i', @ary, $baz, $bar;

which doesn't really increase readability.

Now imagine that you need to pack the data for a completely different architecture with different byte order. You would look into the "pack" manpage again and perhaps come up with this:

  $binary = pack 'c3 x n x2 N', @ary, $baz, $bar;

However, if you try to unpack $foo again, your signed values have turned into unsigned ones.

All this can still be managed with Perl. But imagine your structures get more complex? Imagine you need to support different platforms? Imagine you need to make changes to the structures? You'll not only have to change the C source but also dozens of "pack" strings in your Perl code. This is no fun. And Perl should be fun.

Now, wouldn't it be great if you could just read in the C source you've already written and use all the types defined there for packing and unpacking? That's what Convert::Binary::C does.

Creating a Convert::Binary::C object

  use Convert::Binary::C;

to load the module. Its interface is completely object oriented, so it doesn't export any functions.

Next, you need to create a new Convert::Binary::C object. This can be done by either

  $c = Convert::Binary::C->new;

or

  $c = Convert::Binary::C->new;

You can optionally pass configuration options to the constructor as described in the next section.

Configuring the object

  $c->configure(ByteOrder => 'LittleEndian',
                Alignment => 2);

or you can change the construction code to

  $c = Convert::Binary::C->new(ByteOrder => 'LittleEndian',
                               Alignment => 2);

Either way, the object will now know that it should use little endian (Intel) byte order and 2-byte struct member alignment for packing and unpacking.

Alternatively, you can use the option names as names of methods to configure the object, like:

  $c->ByteOrder('LittleEndian');

You can also retrieve information about the current configuration of a Convert::Binary::C object. For details, see the section about the "configure" method.

Parsing C code

  $c->parse_file('header.h');

Or by parsing C code embedded in your script:

  $c->parse(<<'CCODE');
  struct foo {
    char ary[3];
    unsigned short baz;
    int bar;
  };
  CCODE

Now the object $c will know everything about "struct foo". The example above uses a so-called here-document. It allows one to easily embed multi-line strings in your code. You can find more about here-documents in perldata or perlop.

Since the "parse" and "parse_file" methods throw an exception when a parse error occurs, you usually want to catch these in an "eval" block:

  eval { $c->parse_file('header.h') };
  if ($@) {
    # handle error appropriately
  }

Perl's special $@ variable will contain an empty string (which evaluates to a false value in boolean context) on success or an error string on failure.

As another feature, "parse" and "parse_file" return a reference to their object on success, just like "configure" does when you're configuring the object. This will allow you to write constructs like this:

  my $c = eval {
    Convert::Binary::C->new(Include => ['/usr/include'])
                      ->parse_file('header.h')
  };
  if ($@) {
    # handle error appropriately
  }

Packing and unpacking

  $data = {
    ary => [1, 2, 3],
    baz => 40000,
    bar => -4711,
  };
  $binary = $c->pack('foo', $data);

Unpacking will work exactly the same way, just that the "unpack" method will take a byte string as its input and will return a reference to a (possibly very complex) Perl data structure.

  $binary = get_data_from_memory();
  $data = $c->unpack('foo', $binary);

You can now easily access all of the values:

  print "foo.ary[1] = $data->{ary}[1]\n";

Or you can even more conveniently use the Data::Dumper module:

  use Data::Dumper;
  print Dumper($data);

The output would look something like this:

  $VAR1 = {
    'ary' => [
      42,
      48,
      100
    ],
    'baz' => 5000,
    'bar' => -271
  };

Preprocessor configuration

If your C source contains includes or depends upon preprocessor defines, you may need to configure the internal preprocessor. Use the "Include" and "Define" configuration options for that:

  $c->configure(Include => ['/usr/include',
                            '/home/mhx/include'],
                Define  => [qw( NDEBUG FOO=42 )]);

If your code uses system includes, it is most likely that you will need to define the symbols that are usually defined by the compiler.

On some operating systems, the system includes require the preprocessor to predefine a certain set of assertions. Assertions are supported by "ucpp", and you can define them either in the source code using "#assert" or as a property of the Convert::Binary::C object using "Assert":

  $c->configure(Assert => ['predicate(answer)']);

Information about defined macros can be retrieved from the preprocessor as long as its configuration isn't changed. The preprocessor is implicitly reset if you change one of the following configuration options:

  Include
  Define
  Assert
  HasCPPComments
  HasMacroVAARGS

Supported pragma directives

#pragma pack( ALIGN )

Sets the new alignment to ALIGN. If ALIGN is 0, resets the alignment to its original value.

#pragma pack

Resets the alignment to its original value.

#pragma pack( push, ALIGN )

Saves the current alignment on a stack and sets the new alignment to ALIGN. If ALIGN is 0, sets the alignment to the default alignment.

#pragma pack( pop )

Restores the alignment to the last value saved on the stack.

  /*  Example assumes sizeof( short ) == 2, sizeof( long ) == 4.  */
  
  #pragma pack(1)
  
  struct nopad {
    char a;               /* no padding bytes between 'a' and 'b' */
    long b;
  };
  
  #pragma pack            /* reset to "native" alignment          */
  
  #pragma pack( push, 2 )
  
  struct pad {
    char    a;            /* one padding byte between 'a' and 'b' */
    long    b;
  
  #pragma pack( push, 1 )
  
    struct {
      char  c;            /* no padding between 'c' and 'd'       */
      short d;
    }       e;            /* sizeof( e ) == 3                     */
  
  #pragma pack( pop );    /* back to pack( 2 )                    */
  
    long    f;            /* one padding byte between 'e' and 'f' */
  };
  
  #pragma pack( pop );    /* back to "native"                     */

The "pack" pragma as it is currently implemented only affects the maximum struct member alignment. There are compilers that also allow one to specify the minimum struct member alignment. This is not supported by Convert::Binary::C.

Automatic configuration using "ccconfig"

The "ccconfig" script, which is bundled with this module, aims at automatically determining the correct compiler configuration by testing the compiler executable. It works for both, native and cross compilers.

Standard Types

For enums, structs and unions, the prefixes "enum", "struct" and "union" are optional. However, if a typedef with the same name exists, like in

  struct foo {
    int bar;
  };
  
  typedef int foo;

you will have to use the prefix to distinguish between the struct and the typedef. Otherwise, a typedef is always given preference.

Basic Types

  $c = Convert::Binary::C->new;
  $size = $c->sizeof('unsigned long');
  $data = $c->pack('short int', 42);

Even though the above works fine, it is not possible to define more complex types on the fly, so

  $size = $c->sizeof('struct { int a, b; }');

will result in an error.

Basic types are not supported by all methods. For example, it makes no sense to use "member" or "offsetof" on a basic type. Using "typeof" isn't very useful, but supported.

Member Expressions

  struct foo {
    long type;
    struct {
      short x, y;
    } array[20];
  };
  
  typedef struct foo matrix[8][8];

You may want to know the size of the "array" member of "struct foo". This is quite easy:

  print $c->sizeof('foo.array'), " bytes";

will print

  80 bytes

depending of course on the "ShortSize" you configured.

If you wanted to unpack only a single column of "matrix", that's easy as well (and of course it doesn't matter which index you use):

  $column = $c->unpack('matrix[2]', $data);

Just like in C, it is possible to use out-of-bounds array indices. This means that, for example, despite "array" is declared to have 20 elements, the following code

  $size   = $c->sizeof('foo.array[4711]');
  $offset = $c->offsetof('foo', 'array[-13]');

is perfectly valid and will result in:

  $size   = 4
  $offset = -44

Member expressions can be arbitrarily complex:

  $type = $c->typeof('matrix[2][3].array[7].y');
  print "the type is $type";

will, for example, print

  the type is short

Member expressions are also used as the second argument to "offsetof".

Offsets

  $member = $c->member('matrix', 1431);
  print $member;

will print

  [2][0].array[3].y+1

If you would use this as a member expression, like in

  $size = $c->sizeof("matrix $member");

the offset suffix will simply be ignored. Actually, it will be ignored for all methods if it's used in the first argument.

When used in the second argument to "offsetof", it will usually do what you mean, i. e. the offset suffix, if present, will be considered when determining the offset. This behaviour ensures that

  $member = $c->member('foo', 43);
  $offset = $c->offsetof('foo', $member);
  print "'$member' is located at offset $offset of struct foo";

will always correctly set $offset:

  '.array[8].y+1' is located at offset 43 of struct foo

If this is not what you mean, e.g. because you want to know the offset where the member returned by "member" starts, you just have to remove the suffix:

  $member =~ s/\+\d+$//;
  $offset = $c->offsetof('foo', $member);
  print "'$member' starts at offset $offset of struct foo";

This would then print:

  '.array[8].y' starts at offset 42 of struct foo

The Format Tag

For example, if you have a (fixed length) string type

  typedef char str_type[40];

this type would, by default, be unpacked as an array of "char"s. That's because it is only an array of "char"s, and Convert::Binary::C doesn't know it is actually used as a string.

But you can tell Convert::Binary::C that "str_type" is a C string using the "Format" tag:

  $c->tag('str_type', Format => 'String');

This will make "unpack" (and of course also "pack") treat the binary data like a null-terminated C string:

  $binary = "Hello World!\n\0 this is just some dummy data";
  $hello = $c->unpack('str_type', $binary);
  print $hello;

would thusly print:

  Hello World!

Of course, this also works the other way round:

  use Data::Hexdumper;
  
  $binary = $c->pack('str_type', "Just another C::B::C hacker");
  print hexdump(data => $binary);

would print:

    0x0000 : 4A 75 73 74 20 61 6E 6F 74 68 65 72 20 43 3A 3A : Just.another.C::
    0x0010 : 42 3A 3A 43 20 68 61 63 6B 65 72 00 00 00 00 00 : B::C.hacker.....
    0x0020 : 00 00 00 00 00 00 00 00                         : ........

If you want Convert::Binary::C to not interpret the binary data at all, you can set the "Format" tag to "Binary". This might not be seem very useful, as "pack" and "unpack" would just pass through the unmodified binary data. But you can tag not only whole types, but also compound members. For example

  $c->parse(<<ENDC);
  struct packet {
    unsigned short header;
    unsigned short flags;
    unsigned char  payload[28];
  };
  ENDC
  
  $c->tag('packet.payload', Format => 'Binary');

would allow you to write:

  read FILE, $payload, $c->sizeof('packet.payload');
  
  $packet = {
              header  => 4711,
              flags   => 0xf00f,
              payload => $payload,
            };
  
  $binary = $c->pack('packet', $packet);
  
  print hexdump(data => $binary);

This would print something like:

    0x0000 : 12 67 F0 0F 6E 6F 0A 6E 6F 0A 6E 6F 0A 6E 6F 0A : .g..no.no.no.no.
    0x0010 : 6E 6F 0A 6E 6F 0A 6E 6F 0A 6E 6F 0A 6E 6F 0A 6E : no.no.no.no.no.n

For obvious reasons, it is not allowed to attach a "Format" tag to bitfield members. Trying to do so will result in an exception being thrown by the "tag" method.

The ByteOrder Tag

Usually it doesn't make much sense to override the byte order, but there may be applications where a sub-structure is packed in a different byte order than the surrounding structure.

Take, for example, the following code:

  $c = Convert::Binary::C->new(ByteOrder => 'BigEndian',
                               OrderMembers => 1);
  $c->parse(<<'ENDC');
  
  typedef unsigned short u_16;
  
  struct coords_3d {
    int x, y, z;
  };
  
  struct coords_msg {
    u_16 header;
    u_16 length;
    struct coords_3d coords;
  };
  
  ENDC

Assume that while "coords_msg" is big endian, the embedded coordinates "coords_3d" are stored in little endian format for some reason. In C, you'll have to handle this manually.

But using Convert::Binary::C, you can simply attach a "ByteOrder" tag to either the "coords_3d" structure or to the "coords" member of the "coords_msg" structure. Both will work in this case. The only difference is that if you tag the "coords" member, "coords_3d" will only be treated as little endian if you "pack" or "unpack" the "coords_msg" structure. (BTW, you could also tag all members of "coords_3d" individually, but that would be inefficient.)

So, let's attach the "ByteOrder" tag to the "coords" member:

  $c->tag('coords_msg.coords', ByteOrder => 'LittleEndian');

Assume the following binary message:

    0x0000 : 00 2A 00 0C FF FF FF FF 02 00 00 00 2A 00 00 00 : .*..........*...

If you unpack this message...

  $msg = $c->unpack('coords_msg', $binary);

...you will get the following data structure:

  $msg = {
    'header' => 42,
    'length' => 12,
    'coords' => {
      'x' => -1,
      'y' => 2,
      'z' => 42
    }
  };

Without the "ByteOrder" tag, you would get:

  $msg = {
    'header' => 42,
    'length' => 12,
    'coords' => {
      'x' => -1,
      'y' => 33554432,
      'z' => 704643072
    }
  };

The "ByteOrder" tag is a recursive tag, i.e. it applies to all children of the tagged object recursively. Of course, it is also possible to override a "ByteOrder" tag by attaching another "ByteOrder" tag to a child type. Confused? Here's an example. In addition to tagging the "coords" member as little endian, we now tag "coords_3d.y" as big endian:

  $c->tag('coords_3d.y', ByteOrder => 'BigEndian');
  $msg = $c->unpack('coords_msg', $binary);

This will return the following data structure:

  $msg = {
    'header' => 42,
    'length' => 12,
    'coords' => {
      'x' => -1,
      'y' => 33554432,
      'z' => 42
    }
  };

Note that if you tag both a type and a member of that type within a compound, the tag attached to the type itself has higher precedence. Using the example above, if you would attach a "ByteOrder" tag to both "coords_msg.coords" and "coords_3d", the tag attached to "coords_3d" would always win.

Also note that the "ByteOrder" tag might not work as expected along with bitfields, which is why the implementation is considered experimental. Bitfields are currently not affected by the "ByteOrder" tag at all. This is because the byte order would affect the bitfield layout, and a consistent implementation supporting multiple layouts of the same struct would be quite bulky and probably slow down the whole module.

If you really need the correct behaviour, you can use the following trick:

  $le = Convert::Binary::C->new(ByteOrder => 'LittleEndian');
  
  $le->parse(<<'ENDC');
  
  typedef unsigned short u_16;
  typedef unsigned long  u_32;
  
  struct message {
    u_16 header;
    u_16 length;
    struct {
      u_32 a;
      u_32 b;
      u_32 c :  7;
      u_32 d :  5;
      u_32 e : 20;
    } data;
  };
  
  ENDC
  
  $be = $le->clone->ByteOrder('BigEndian');
  
  $le->tag('message.data', Format => 'Binary', Hooks => {
      unpack => sub { $be->unpack('message.data', @_) },
      pack   => sub { $be->pack('message.data', @_) },
    });
  
  
  $msg = $le->unpack('message', $binary);

This uses the "Format" and "Hooks" tags along with a big endian "clone" of the original little endian object. It attaches hooks to the little endian object and in the hooks it uses the big endian object to "pack" and "unpack" the binary data.

The Dimension Tag

That being said, the "Dimension" tag is primarily useful to support variable length arrays. Usually, you have to write the following code for such a variable length array in C:

  struct c_message
  {
    unsigned count;
    char data[1];
  };

So, because you cannot declare an empty array, you declare an array with a single element. If you have a ISO-C99 compliant compiler, you can write this code instead:

  struct c99_message
  {
    unsigned count;
    char data[];
  };

This explicitly tells the compiler that "data" is a flexible array member. Convert::Binary::C already uses this information to handle flexible array members in a special way.

As you can see in the following example, the two types are treated differently:

  $data = pack 'NC*', 3, 1..8;
  $uc   = $c->unpack('c_message', $data);
  $uc99 = $c->unpack('c99_message', $data);

This will result in:

  $uc = {'count' => 3,'data' => [1]};
  $uc99 = {'count' => 3,'data' => [1,2,3,4,5,6,7,8]};

However, only few compilers support ISO-C99, and you probably don't want to change your existing code only to get some extra features when using Convert::Binary::C.

So it is possible to attach a tag to the "data" member of the "c_message" struct that tells Convert::Binary::C to treat the array as if it were flexible:

  $c->tag('c_message.data', Dimension => '*');

Now both "c_message" and "c99_message" will behave exactly the same when using "pack" or "unpack". Repeating the above code:

  $uc = $c->unpack('c_message', $data);

This will result in:

  $uc = {'count' => 3,'data' => [1,2,3,4,5,6,7,8]};

But there's more you can do. Even though it probably doesn't make much sense, you can tag a fixed dimension to an array:

  $c->tag('c_message.data', Dimension => '5');

This will obviously result in:

  $uc = {'count' => 3,'data' => [1,2,3,4,5]};

A more useful way to use the "Dimension" tag is to set it to the name of a member in the same compound:

  $c->tag('c_message.data', Dimension => 'count');

Convert::Binary::C will now use the value of that member to determine the size of the array, so unpacking will result in:

  $uc = {'count' => 3,'data' => [1,2,3]};

Of course, you can also tag flexible array members. And yes, it's also possible to use more complex member expressions:

  $c->parse(<<ENDC);
  struct msg_header
  {
    unsigned len[2];
  };
  
  struct more_complex
  {
    struct msg_header hdr;
    char data[];
  };
  ENDC
  
  $data = pack 'NNC*', 42, 7, 1 .. 10;
  
  $c->tag('more_complex.data', Dimension => 'hdr.len[1]');
  
  $u = $c->unpack('more_complex', $data);

The result will be:

  $u = {
    'hdr' => {
      'len' => [
        42,
        7
      ]
    },
    'data' => [
      1,
      2,
      3,
      4,
      5,
      6,
      7
    ]
  };

By the way, it's also possible to tag arrays that are not embedded inside a compound:

  $c->parse(<<ENDC);
  typedef unsigned short short_array[];
  ENDC
  
  $c->tag('short_array', Dimension => '5');
  
  $u = $c->unpack('short_array', $data);

Resulting in:

  $u = [0,42,0,7,258];

The final and most powerful way to define a "Dimension" tag is to pass it a subroutine reference. The referenced subroutine can execute whatever code is necessary to determine the size of the tagged array:

  sub get_size
  {
    my $m = shift;
    return $m->{hdr}{len}[0] / $m->{hdr}{len}[1];
  }
  
  $c->tag('more_complex.data', Dimension => \&get_size);
  
  $u = $c->unpack('more_complex', $data);

As you can guess from the above code, the subroutine is being passed a reference to hash that stores the already unpacked part of the compound embedding the tagged array. This is the result:

  $u = {
    'hdr' => {
      'len' => [
        42,
        7
      ]
    },
    'data' => [
      1,
      2,
      3,
      4,
      5,
      6
    ]
  };

You can also pass custom arguments to the subroutines by using the "arg" method. This is similar to the functionality offered by the "Hooks" tag.

Of course, all that also works for the "pack" method as well.

However, the current implementation has at least one shortcomings, which is why it's experimental: The "Dimension" tag doesn't impact compound layout. This means that while you can alter the size of an array in the middle of a compound, the offset of the members after that array won't be impacted. I'd rather like to see the layout adapt dynamically, so this is what I'm hoping to implement in the future.

The Hooks Tag

Using hooks, you can easily override the way "pack" and "unpack" handle data using your own subroutines. If you define hooks for a certain data type, each time this data type is processed the corresponding hook will be called to allow you to modify that data.

Basic Hooks

Here's an example. Let's assume the following C code has been parsed:

  typedef unsigned int u_32;
  typedef u_32         ProtoId;
  typedef ProtoId      MyProtoId;
  
  struct MsgHeader {
    MyProtoId id;
    u_32      len;
  };

  struct String {
    u_32 len;
    char buf[];
  };

You could now use the types above and, for example, unpack binary data representing a "MsgHeader" like this:

  $msg_header = $c->unpack('MsgHeader', $data);

This would give you:

  $msg_header = {
    'id' => 42,
    'len' => 13
  };

Instead of dealing with "ProtoId"'s as integers, you would rather like to have them as clear text. You could provide subroutines to convert between clear text and integers:

  %proto = (
    CATS      =>    1,
    DOGS      =>   42,
    HEDGEHOGS => 4711,
  );
  
  %rproto = reverse %proto;
  
  sub ProtoId_unpack {
    $rproto{$_[0]} || 'unknown protocol'
  }
  
  sub ProtoId_pack {
    $proto{$_[0]} or die 'unknown protocol'
  }

You can now register these subroutines by attaching a "Hooks" tag to "ProtoId" using the "tag" method:

  $c->tag('ProtoId', Hooks => { pack   => \&ProtoId_pack,
                                unpack => \&ProtoId_unpack });

Doing exactly the same unpack on "MsgHeader" again would now return:

  $msg_header = {
    'id' => 'DOGS',
    'len' => 13
  };

Actually, if you don't need the reverse operation, you don't even have to register a "pack" hook. Or, even better, you can have a more intelligent "unpack" hook that creates a dual-typed variable:

  use Scalar::Util qw(dualvar);
  
  sub ProtoId_unpack2 {
    dualvar $_[0], $rproto{$_[0]} || 'unknown protocol'
  }
  
  $c->tag('ProtoId', Hooks => { unpack => \&ProtoId_unpack2 });
  
  $msg_header = $c->unpack('MsgHeader', $data);

Just as before, this would print

  $msg_header = {
    'id' => 'DOGS',
    'len' => 13
  };

but without requiring a "pack" hook for packing, at least as long as you keep the variable dual-typed.

Hooks are usually called with exactly one argument, which is the data that should be processed (see "Advanced Hooks" for details on how to customize hook arguments). They are called in scalar context and expected to return the processed data.

To get rid of registered hooks, you can either undefine only certain hooks

  $c->tag('ProtoId', Hooks => { pack => undef });

or all hooks:

  $c->tag('ProtoId', Hooks => undef);

Of course, hooks are not restricted to handling integer values. You could just as well attach hooks for the "String" struct from the code above. A useful example would be to have these hooks:

  sub string_unpack {
    my $s = shift;
    pack "c$s->{len}", @{$s->{buf}};
  }
  
  sub string_pack {
    my $s = shift;
    return {
      len => length $s,
      buf => [ unpack 'c*', $s ],
    }
  }

(Don't be confused by the fact that the "unpack" hook uses "pack" and the "pack" hook uses "unpack". And also see "Advanced Hooks" for a more clever approach.)

While you would normally get the following output when unpacking a "String"

  $string = {
    'len' => 12,
    'buf' => [
      72,
      101,
      108,
      108,
      111,
      32,
      87,
      111,
      114,
      108,
      100,
      33
    ]
  };

you could just register the hooks using

  $c->tag('String', Hooks => { pack   => \&string_pack,
                               unpack => \&string_unpack });

and you would get a nice human-readable Perl string:

  $string = 'Hello World!';

Packing a string turns out to be just as easy:

  use Data::Hexdumper;
  
  $data = $c->pack('String', 'Just another Perl hacker,');
  
  print hexdump(data => $data);

This would print:

    0x0000 : 00 00 00 19 4A 75 73 74 20 61 6E 6F 74 68 65 72 : ....Just.another
    0x0010 : 20 50 65 72 6C 20 68 61 63 6B 65 72 2C          : .Perl.hacker,

If you want to find out if or which hooks are registered for a certain type, you can also use the "tag" method:

  $hooks = $c->tag('String', 'Hooks');

This would return:

  $hooks = {
    'unpack' => \&string_unpack,
    'pack' => \&string_pack
  };

Advanced Hooks

It is also possible to combine hooks with using the "Format" tag. This can be useful if you know better than Convert::Binary::C how to interpret the binary data. In the previous section, we've handled this type

  struct String {
    u_32 len;
    char buf[];
  };

with the following hooks:

  sub string_unpack {
    my $s = shift;
    pack "c$s->{len}", @{$s->{buf}};
  }
  
  sub string_pack {
    my $s = shift;
    return {
      len => length $s,
      buf => [ unpack 'c*', $s ],
    }
  }

  $c->tag('String', Hooks => { pack   => \&string_pack,
                               unpack => \&string_unpack });

As you can see in the hook code, "buf" is expected to be an array of characters. For the "unpack" case Convert::Binary::C first turns the binary data into a Perl array, and then the hook packs it back into a string. The intermediate array creation and destruction is completely useless. Same thing, of course, for the "pack" case.

Here's a clever way to handle this. Just tag "buf" as binary

  $c->tag('String.buf', Format => 'Binary');

and use the following hooks instead:

  sub string_unpack2 {
    my $s = shift;
    substr $s->{buf}, 0, $s->{len};
  }
  
  sub string_pack2 {
    my $s = shift;
    return {
      len => length $s,
      buf => $s,
    }
  }
  
  $c->tag('String', Hooks => { pack   => \&string_pack2,
                               unpack => \&string_unpack2 });

This will be exactly equivalent to the old code, but faster and probably even much easier to understand.

But hooks are even more powerful. You can customize the arguments that are passed to your hooks and you can use "arg" to pass certain special arguments, such as the name of the type that is currently being processed by the hook.

The following example shows how it is easily possible to peek into the perl internals using hooks.

  use Config;
  
  $c = Convert::Binary::C->new(%CC, OrderMembers => 1);
  $c->Include(["$Config{archlib}/CORE", @{$c->Include}]);
  $c->parse(<<ENDC);
  #include "EXTERN.h"
  #include "perl.h"
  ENDC
  
  $c->tag($_, Hooks => { unpack_ptr => [\&unpack_ptr,
                                        $c->arg(qw(SELF TYPE DATA))] })
      for qw( XPVAV XPVHV );

First, we add the perl core include path and parse perl.h. Then, we add an "unpack_ptr" hook for a couple of the internal data types.

The "unpack_ptr" and "pack_ptr" hooks are called whenever a pointer to a certain data structure is processed. This is by far the most experimental part of the hooks feature, as this includes any kind of pointer. There's no way for the hook to know the difference between a plain pointer, or a pointer to a pointer, or a pointer to an array (this is because the difference doesn't matter anywhere else in Convert::Binary::C).

But the hook above makes use of another very interesting feature: It uses "arg" to pass special arguments to the hook subroutine. Usually, the hook subroutine is simply passed a single data argument. But using the above definition, it'll get a reference to the calling object ("SELF"), the name of the type being processed ("TYPE") and the data ("DATA").

But how does our hook look like?

  sub unpack_ptr {
    my($self, $type, $ptr) = @_;
    $ptr or return '<NULL>';
    my $size = $self->sizeof($type);
    $self->unpack($type, unpack("P$size", pack('Q', $ptr)));
  }

As you can see, the hook is rather simple. First, it receives the arguments mentioned above. It performs a quick check if the pointer is "NULL" and shouldn't be processed any further. Next, it determines the size of the type being processed. And finally, it'll just use the "P"n unpack template to read from that memory location and recursively call "unpack" to unpack the type. (And yes, this may of course again call other hooks.)

Now, let's test that:

  my $ref = { foo => 42, bar => 4711 };
  my $ptr = hex(("$ref" =~ /\(0x([[:xdigit:]]+)\)$/)[0]);
  
  print Dumper(unpack_ptr($c, 'AV', $ptr));

Just for the fun of it, we create a blessed array reference. But how do we get a pointer to the corresponding "AV"? This is rather easy, as the address of the "AV" is just the hex value that appears when using the array reference in string context. So we just grab that and turn it into decimal. All that's left to do is just call our hook, as it can already handle "AV" pointers. And this is what we get:

  $VAR1 = {
    'sv_any' => {
      'xmg_stash' => 0,
      'xmg_u' => {
        'xmg_magic' => 0,
        'xmg_hash_index' => 0
      },
      'xav_fill' => 2,
      'xav_max' => 7,
      'xav_alloc' => 0
    },
    'sv_refcnt' => 1,
    'sv_flags' => 536870924,
    'sv_u' => {
      'svu_pv' => '94716517508048',
      'svu_iv' => '94716517508048',
      'svu_uv' => '94716517508048',
      'svu_nv' => '4.67961773944475e-310',
      'svu_rv' => '94716517508048',
      'svu_array' => '94716517508048',
      'svu_hash' => '94716517508048',
      'svu_gp' => '94716517508048',
      'svu_fp' => '94716517508048'
    }
  };

Even though it is rather easy to do such stuff using "unpack_ptr" hooks, you should really know what you're doing and do it with extreme care because of the limitations mentioned above. It's really easy to run into segmentation faults when you're dereferencing pointers that point to memory which you don't own.

Performance

Using hooks isn't for free. In performance-critical applications you have to keep in mind that hooks are actually perl subroutines and that they are called once for every value of a registered type that is being packed or unpacked. If only about 10% of the values require hooks to be called, you'll hardly notice the difference (if your hooks are implemented efficiently, that is). But if all values would require hooks to be called, that alone could easily make packing and unpacking very slow.

Tag Order

  pack        unpack
  ---------------------
  Hooks       Format
  Format      ByteOrder
  ByteOrder   Hooks

As a general rule, the "Hooks" tag is always the first thing processed when packing data, and the last thing processed when unpacking data.

The "Format" and "ByteOrder" tags are exclusive, but when both are given the "Format" tag wins.

new

"new"

"new" OPTION1 => VALUE1, OPTION2 => VALUE2, ...

The constructor is used to create a new Convert::Binary::C object. You can simply use

  $c = Convert::Binary::C->new;
    

without additional arguments to create an object, or you can optionally pass any arguments to the constructor that are described for the "configure" method.

configure

"configure"

"configure" OPTION

"configure" OPTION1 => VALUE1, OPTION2 => VALUE2, ...

This method can be used to configure an existing Convert::Binary::C object or to retrieve its current configuration.

To configure the object, the list of options consists of key and value pairs and must therefore contain an even number of elements. "configure" (and also "new" if used with configuration options) will throw an exception if you pass an odd number of elements. Configuration will normally look like this:

  $c->configure(ByteOrder => 'BigEndian', IntSize => 2);
    

To retrieve the current value of a configuration option, you must pass a single argument to "configure" that holds the name of the option, just like

  $order = $c->configure('ByteOrder');
    

If you want to get the values of all configuration options at once, you can call "configure" without any arguments and it will return a reference to a hash table that holds the whole object configuration. This can be conveniently used with the Data::Dumper module, for example:

  use Convert::Binary::C;
  use Data::Dumper;
  
  $c = Convert::Binary::C->new(Define  => ['DEBUGGING', 'FOO=123'],
                               Include => ['/usr/include']);
  
  print Dumper($c->configure);
    

Which will print something like this:

  $VAR1 = {
    'DisabledKeywords' => [],
    'HasCPPComments' => 1,
    'UnsignedChars' => 0,
    'LongDoubleSize' => 16,
    'OrderMembers' => 1,
    'CompoundAlignment' => 1,
    'UnsignedBitfields' => 0,
    'DoubleSize' => 8,
    'Assert' => [],
    'PointerSize' => 8,
    'ByteOrder' => 'LittleEndian',
    'Warnings' => 0,
    'LongSize' => 8,
    'Include' => [
      '/usr/include'
    ],
    'EnumType' => 'Integer',
    'EnumSize' => 4,
    'ShortSize' => 2,
    'IntSize' => 4,
    'StdCVersion' => 199901,
    'HostedC' => 1,
    'Alignment' => 1,
    'HasMacroVAARGS' => 1,
    'KeywordMap' => {},
    'Define' => [
      'DEBUGGING',
      'FOO=123'
    ],
    'LongLongSize' => 8,
    'CharSize' => 1,
    'FloatSize' => 4,
    'Bitfields' => {
      'Engine' => 'Generic'
    }
  };
    

Since you may not always want to write a "configure" call when you only want to change a single configuration item, you can use any configuration option name as a method name, like:

  $c->ByteOrder('LittleEndian') if $c->IntSize < 4;
    

(Yes, the example doesn't make very much sense... ;-)

However, you should keep in mind that configuration methods that can take lists (namely "Include", "Define" and "Assert", but not "DisabledKeywords") may behave slightly different than their "configure" equivalent. If you pass these methods a single argument that is an array reference, the current list will be replaced by the new one, which is just the behaviour of the corresponding "configure" call. So the following are equivalent:

  $c->configure(Define => ['foo', 'bar=123']);
  $c->Define(['foo', 'bar=123']);
    

But if you pass a list of strings instead of an array reference (which cannot be done when using "configure"), the new list items are appended to the current list, so

  $c = Convert::Binary::C->new(Include => ['/include']);
  $c->Include('/usr/include', '/usr/local/include');
  print Dumper($c->Include);
  
  $c->Include(['/usr/local/include']);
  print Dumper($c->Include);
    

will first print all three include paths, but finally only "/usr/local/include" will be configured:

  $VAR1 = [
    '/include',
    '/usr/include',
    '/usr/local/include'
  ];
  $VAR1 = [
    '/usr/local/include'
  ];
    

Furthermore, configuration methods can be chained together, as they return a reference to their object if called as a set method. So, if you like, you can configure your object like this:

  $c = Convert::Binary::C->new(IntSize => 4)
         ->Define(qw( __DEBUG__ DB_LEVEL=3 ))
         ->ByteOrder('BigEndian');
  
  $c->configure(EnumType => 'Both', Alignment => 4)
    ->Include('/usr/include', '/usr/local/include');
    

In the example above, "qw( ... )" is the word list quoting operator. It returns a list of all non-whitespace sequences, and is especially useful for configuring preprocessor defines or assertions. The following assignments are equivalent:

  @array = ('one', 'two', 'three');
  @array = qw(one two three);
    

You can configure the following options. Unknown options, as well as invalid values for an option, will cause the object to throw exceptions.

  typedef struct {
    char abc;
    int  day;
  } foo;
  
  struct bar {
    foo  zap[2*sizeof(foo)];
  };

parse

"parse" CODE

Parses a string of valid C code. All enumeration, compound and type definitions are extracted. You can call the "parse" and "parse_file" methods as often as you like to add further definitions to the Convert::Binary::C object.

"parse" will throw an exception if an error occurs. On success, the method returns a reference to its object.

See "Parsing C code" for an example.

parse_file

"parse_file" FILE

Parses a C source file. All enumeration, compound and type definitions are extracted. You can call the "parse" and "parse_file" methods as often as you like to add further definitions to the Convert::Binary::C object.

"parse_file" will search the include path given via the "Include" option for the file if it cannot find it in the current directory.

"parse_file" will throw an exception if an error occurs. On success, the method returns a reference to its object.

See "Parsing C code" for an example.

When calling "parse" or "parse_file" multiple times, you may use types previously defined, but you are not allowed to redefine types. The state of the preprocessor is also saved, so you may also use defines from a previous parse. This works only as long as the preprocessor is not reset. See "Preprocessor configuration" for details.

When you're parsing C source files instead of C header files, note that local definitions are ignored. This means that type definitions hidden within functions will not be recognized by Convert::Binary::C. This is necessary because different functions (even different blocks within the same function) can define types with the same name:

  void my_func(int i)
  {
    if (i < 10)
    {
      enum digit { ONE, TWO, THREE } x = ONE;
      printf("%d, %d\n", i, x);
    }
    else
    {
      enum digit { THREE, TWO, ONE } x = ONE;
      printf("%d, %d\n", i, x);
    }
  }
    

The above is a valid piece of C code, but it's not possible for Convert::Binary::C to distinguish between the different definitions of "enum digit", as they're only defined locally within the corresponding block.

clean

"clean"

Clears all information that has been collected during previous calls to "parse" or "parse_file". You can use this method if you want to parse some entirely different code, but with the same configuration.

The "clean" method returns a reference to its object.

clone

"clone"

Makes the object return an exact independent copy of itself.

  $c = Convert::Binary::C->new(Include => ['/usr/include']);
  $c->parse_file('definitions.c');
  $clone = $c->clone;
    

The above code is technically equivalent (Mostly. Actually, using "sourcify" and "parse" might alter the order of the parsed data, which would make methods such as "compound" return the definitions in a different order.) to:

  $c = Convert::Binary::C->new(Include => ['/usr/include']);
  $c->parse_file('definitions.c');
  $clone = Convert::Binary::C->new(%{$c->configure});
  $clone->parse($c->sourcify);
    

Using "clone" is just a lot faster.

def

"def" NAME

"def" TYPE

If you need to know if a definition for a certain type name exists, use this method. You pass it the name of an enum, struct, union or typedef, and it will return a non-empty string being either "enum", "struct", "union", or "typedef" if there's a definition for the type in question, an empty string if there's no such definition, or "undef" if the name is completely unknown. If the type can be interpreted as a basic type, "basic" will be returned.

If you pass in a TYPE, the output will be slightly different. If the specified member exists, the "def" method will return "member". If the member doesn't exist, or if the type cannot have members, the empty string will be returned. Again, if the name of the type is completely unknown, "undef" will be returned. This may be useful if you want to check if a certain member exists within a compound, for example.

  use Convert::Binary::C;
  
  my $c = Convert::Binary::C->new->parse(<<'ENDC');
  
  typedef struct __not  not;
  typedef struct __not *ptr;
  
  struct foo {
    enum bar *xxx;
  };
  
  typedef int quad[4];
  
  ENDC
  
  for my $type (qw( not ptr foo bar xxx foo.xxx foo.abc xxx.yyy
                    quad quad[3] quad[5] quad[-3] short[1] ),
                'unsigned long')
  {
    my $def = $c->def($type);
    printf "%-14s  =>  %s\n",
            $type,     defined $def ? "'$def'" : 'undef';
  }
    

The following would be returned by the "def" method:

  not             =>  ''
  ptr             =>  'typedef'
  foo             =>  'struct'
  bar             =>  ''
  xxx             =>  undef
  foo.xxx         =>  'member'
  foo.abc         =>  ''
  xxx.yyy         =>  undef
  quad            =>  'typedef'
  quad[3]         =>  'member'
  quad[5]         =>  'member'
  quad[-3]        =>  'member'
  short[1]        =>  undef
  unsigned long   =>  'basic'
    

So, if "def" returns a non-empty string, you can safely use any other method with that type's name or with that member expression.

Concerning arrays, note that the index into an array doesn't need to be within the bounds of the array's definition, just like in C. In the above example, "quad[5]" and "quad[-3]" are valid members of the "quad" array, even though it is declared to have only four elements.

In cases where the typedef namespace overlaps with the namespace of enums/structs/unions, the "def" method will give preference to the typedef and will thus return the string "typedef". You could however force interpretation as an enum, struct or union by putting "enum", "struct" or "union" in front of the type's name.

defined

"defined" MACRO

You can use the "defined" method to find out if a certain macro is defined, just like you would use the "defined" operator of the preprocessor. For example, the following code

  use Convert::Binary::C;
  
  my $c = Convert::Binary::C->new->parse(<<'ENDC');
  
  #define ADD(a, b) ((a) + (b))
  
  #if 1
  # define DEFINED
  #else
  # define UNDEFINED
  #endif
  
  ENDC
  
  for my $macro (qw( ADD DEFINED UNDEFINED )) {
    my $not = $c->defined($macro) ? '' : ' not';
    print "Macro '$macro' is$not defined.\n";
  }
    

would print:

  Macro 'ADD' is defined.
  Macro 'DEFINED' is defined.
  Macro 'UNDEFINED' is not defined.
    

You have to keep in mind that this works only as long as the preprocessor is not reset. See "Preprocessor configuration" for details.

pack

"pack" TYPE

"pack" TYPE, DATA

"pack" TYPE, DATA, STRING

Use this method to pack a complex data structure into a binary string according to a type definition that has been previously parsed. DATA must be a scalar matching the type definition. C structures and unions are represented by references to Perl hashes, C arrays by references to Perl arrays.

  use Convert::Binary::C;
  use Data::Dumper;
  use Data::Hexdumper;
  
  $c = Convert::Binary::C->new( ByteOrder => 'BigEndian'
                              , LongSize  => 4
                              , ShortSize => 2
                              )
                         ->parse(<<'ENDC');
  struct test {
    char    ary[3];
    union {
      short word[2];
      long  quad;
    }       uni;
  };
  ENDC
    

Hashes don't have to contain a key for each compound member and arrays may be truncated:

  $binary = $c->pack('test', { ary => [1, 2], uni => { quad => 42 } });
    

Elements not defined in the Perl data structure will be set to zero in the packed byte string. If you pass "undef" as or simply omit the second parameter, the whole string will be initialized with zero bytes. On success, the packed byte string is returned.

  print hexdump(data => $binary);
    

The above code would print:

    0x0000 : 01 02 00 00 00 00 2A                            : ......*
    

You could also use "unpack" and dump the data structure.

  $unpacked = $c->unpack('test', $binary);
  print Data::Dumper->Dump([$unpacked], ['unpacked']);
    

This would print:

  $unpacked = {
    'ary' => [
      1,
      2,
      0
    ],
    'uni' => {
      'word' => [
        0,
        42
      ],
      'quad' => 42
    }
  };
    

If TYPE refers to a compound object, you may pack any member of that compound object. Simply add a member expression to the type name, just as you would access the member in C:

  $array = $c->pack('test.ary', [1, 2, 3]);
  print hexdump(data => $array);
  
  $value = $c->pack('test.uni.word[1]', 2);
  print hexdump(data => $value);
    

This would give you:

    0x0000 : 01 02 03                                        : ...
    0x0000 : 00 02                                           : ..
    

Call "pack" with the optional STRING argument if you want to use an existing binary string to insert the data. If called in a void context, "pack" will directly modify the string you passed as the third argument. Otherwise, a copy of the string is created, and "pack" will modify and return the copy, so the original string will remain unchanged.

The 3-argument version may be useful if you want to change only a few members of a complex data structure without having to "unpack" everything, change the members, and then "pack" again (which could waste lots of memory and CPU cycles). So, instead of doing something like

  $test = $c->unpack('test', $binary);
  $test->{uni}{quad} = 4711;
  $new = $c->pack('test', $test);
    

to change the "uni.quad" member of $packed, you could simply do either

  $new = $c->pack('test', { uni => { quad => 4711 } }, $binary);
    

or

  $c->pack('test', { uni => { quad => 4711 } }, $binary);
    

while the latter would directly modify $packed. Besides this code being a lot shorter (and perhaps even more readable), it can be significantly faster if you're dealing with really big data blocks.

If the length of the input string is less than the size required by the type, the string (or its copy) is extended and the extended part is initialized to zero. If the length is more than the size required by the type, the string is kept at that length, and also a copy would be an exact copy of that string.

  $too_short = pack "C*", (1 .. 4);
  $too_long  = pack "C*", (1 .. 20);
  
  $c->pack('test', { uni => { quad => 0x4711 } }, $too_short);
  print "too_short:\n", hexdump(data => $too_short);
  
  $copy = $c->pack('test', { uni => { quad => 0x4711 } }, $too_long);
  print "\ncopy:\n", hexdump(data => $copy);
    

This would print:

  too_short:
    0x0000 : 01 02 03 00 00 47 11                            : .....G.
  
  copy:
    0x0000 : 01 02 03 00 00 47 11 08 09 0A 0B 0C 0D 0E 0F 10 : .....G..........
    0x0010 : 11 12 13 14                                     : ....
    

unpack

"unpack" TYPE, STRING

Use this method to unpack a binary string and create an arbitrarily complex Perl data structure based on a previously parsed type definition.

  use Convert::Binary::C;
  use Data::Dumper;
  
  $c = Convert::Binary::C->new( ByteOrder => 'BigEndian'
                              , LongSize  => 4
                              , ShortSize => 2
                              )
                         ->parse( <<'ENDC' );
  struct test {
    char    ary[3];
    union {
      short word[2];
      long *quad;
    }       uni;
  };
  ENDC
  
  # Generate some binary dummy data
  $binary = pack "C*", 1 .. $c->sizeof('test');
    

On failure, e.g. if the specified type cannot be found, the method will throw an exception. On success, a reference to a complex Perl data structure is returned, which can directly be dumped using the Data::Dumper module:

  $unpacked = $c->unpack('test', $binary);
  print Dumper($unpacked);
    

This would print:

  $VAR1 = {
    'ary' => [
      1,
      2,
      3
    ],
    'uni' => {
      'word' => [
        1029,
        1543
      ],
      'quad' => '289644378304612875'
    }
  };
    

If TYPE refers to a compound object, you may unpack any member of that compound object. Simply add a member expression to the type name, just as you would access the member in C:

  $binary2 = substr $binary, $c->offsetof('test', 'uni.word');
  
  $unpack1 = $unpacked->{uni}{word};
  $unpack2 = $c->unpack('test.uni.word', $binary2);
  
  print Data::Dumper->Dump([$unpack1, $unpack2], [qw(unpack1 unpack2)]);
    

You will find that the output is exactly the same for both $unpack1 and $unpack2:

  $unpack1 = [
    1029,
    1543
  ];
  $unpack2 = [
    1029,
    1543
  ];
    

When "unpack" is called in list context, it will unpack as many elements as possible from STRING, including zero if STRING is not long enough.

initializer

"initializer" TYPE

"initializer" TYPE, DATA

The "initializer" method can be used retrieve an initializer string for a certain TYPE. This can be useful if you have to initialize only a couple of members in a huge compound type or if you simply want to generate initializers automatically.

  struct date {
    unsigned year : 12;
    unsigned month:  4;
    unsigned day  :  5;
    unsigned hour :  5;
    unsigned min  :  6;
  };
  
  typedef struct {
    enum { DATE, QWORD } type;
    short number;
    union {
      struct date   date;
      unsigned long qword;
    } choice;
  } data;
    

Given the above code has been parsed

  $init = $c->initializer('data');
  print "data x = $init;\n";
    

would print the following:

  data x = {
        0,
        0,
        {
                {
                        0,
                        0,
                        0,
                        0,
                        0
                }
        }
  };
    

You could directly put that into a C program, although it probably isn't very useful yet. It becomes more useful if you actually specify how you want to initialize the type:

  $data = {
    type   => 'QWORD',
    choice => {
      date  => { month => 12, day => 24 },
      qword => 4711,
    },
    stuff => 'yes?',
  };
  
  $init = $c->initializer('data', $data);
  print "data x = $init;\n";
    

This would print the following:

  data x = {
        QWORD,
        0,
        {
                {
                        0,
                        12,
                        24,
                        0,
                        0
                }
        }
  };
    

As only the first member of a "union" can be initialized, "choice.qword" is ignored. You will not be warned about the fact that you probably tried to initialize a member other than the first. This is considered a feature, because it allows you to use "unpack" to generate the initializer data:

  $data = $c->unpack('data', $binary);
  $init = $c->initializer('data', $data);
    

Since "unpack" unpacks all union members, you would otherwise have to delete all but the first one previous to feeding it into "initializer".

Also, "stuff" is ignored, because it actually isn't a member of "data". You won't be warned about that either.

sizeof

"sizeof" TYPE

This method will return the size of a C type in bytes. If it cannot find the type, it will throw an exception.

If the type defines some kind of compound object, you may ask for the size of a member of that compound object:

  $size = $c->sizeof('test.uni.word[1]');
    

This would set $size to 2.

typeof

"typeof" TYPE

This method will return the type of a C member. While this only makes sense for compound types, it's legal to also use it for non-compound types. If it cannot find the type, it will throw an exception.

The "typeof" method can be used on any valid member, even on arrays or unnamed types. It will always return a string that holds the name (or in case of unnamed types only the class) of the type, optionally followed by a '*' character to indicate it's a pointer type, and optionally followed by one or more array dimensions if it's an array type. If the type is a bitfield, the type name is followed by a colon and the number of bits.

  struct test {
    char    ary[3];
    union {
      short word[2];
      long *quad;
    }       uni;
    struct {
      unsigned short six:6;
      unsigned short ten:10;
    }       bits;
  };
    

Given the above C code has been parsed, calls to "typeof" would return the following values:

  $c->typeof('test')             => 'struct test'
  $c->typeof('test.ary')         => 'char [3]'
  $c->typeof('test.uni')         => 'union'
  $c->typeof('test.uni.quad')    => 'long *'
  $c->typeof('test.uni.word')    => 'short [2]'
  $c->typeof('test.uni.word[1]') => 'short'
  $c->typeof('test.bits')        => 'struct'
  $c->typeof('test.bits.six')    => 'unsigned short :6'
  $c->typeof('test.bits.ten')    => 'unsigned short :10'
    

offsetof

"offsetof" TYPE, MEMBER

You can use "offsetof" just like the C macro of same denominator. It will simply return the offset (in bytes) of MEMBER relative to TYPE.

  use Convert::Binary::C;
  
  $c = Convert::Binary::C->new( Alignment   => 4
                              , LongSize    => 4
                              , PointerSize => 4
                              )
                         ->parse(<<'ENDC');
  typedef struct {
    char abc;
    long day;
    int *ptr;
  } week;
  
  struct test {
    week zap[8];
  };
  ENDC
  
  @args = (
    ['test',        'zap[5].day'  ],
    ['test.zap[2]', 'day'         ],
    ['test',        'zap[5].day+1'],
    ['test',        'zap[-3].ptr' ],
  );
  
  for (@args) {
    my $offset = eval { $c->offsetof(@$_) };
    printf "\$c->offsetof('%s', '%s') => $offset\n", @$_;
  }
    

The final loop will print:

  $c->offsetof('test', 'zap[5].day') => 64
  $c->offsetof('test.zap[2]', 'day') => 4
  $c->offsetof('test', 'zap[5].day+1') => 65
  $c->offsetof('test', 'zap[-3].ptr') => -28
    

  $offset = $c->offsetof('test.zap', '[3].ptr+2');
  print "offset = $offset";

  offset = 46

  printf "offset = %d\n", $c->offsetof('week', 'day');
  printf "offset = %d\n", $c->offsetof('week', '.day');

  offset = 4
  offset = 4

member

"member" TYPE

"member" TYPE, OFFSET

You can think of "member" as being the reverse of the "offsetof" method. However, as this is more complex, there's no equivalent to "member" in the C language.

Usually this method is used if you want to retrieve the name of the member that is located at a specific offset of a previously parsed type.

  use Convert::Binary::C;
  
  $c = Convert::Binary::C->new( Alignment   => 4
                              , LongSize    => 4
                              , PointerSize => 4
                              )
                         ->parse(<<'ENDC');
  typedef struct {
    char abc;
    long day;
    int *ptr;
  } week;
  
  struct test {
    week zap[8];
  };
  ENDC
  
  for my $offset (24, 39, 69, 99) {
    print "\$c->member('test', $offset)";
    my $member = eval { $c->member('test', $offset) };
    print $@ ? "\n  exception: $@" : " => '$member'\n";
  }
    

This will print:

  $c->member('test', 24) => '.zap[2].abc'
  $c->member('test', 39) => '.zap[3]+3'
  $c->member('test', 69) => '.zap[5].ptr+1'
  $c->member('test', 99)
    exception: Offset 99 out of range (0 <= offset < 96)
    

  $member = $c->member('test.zap[2]', 6);
  print $member;

  .day+2

  $member = $c->member('test.zap', 42);
  print $member;

  [3].day+2

  union choice {
    struct {
      char  color[2];
      long  size;
      char  taste;
    }       apple;
    char    grape[3];
    struct {
      long  weight;
      short price[3];
    }       melon;
  };

  Offset   Member               Type
  --------------------------------------
     0     .apple.color[0]      'char'
     1     .apple.color[1]      'char'
     2     .grape[2]            'char'
     3     .melon.weight+3      'long'
     4     .apple.size          'long'
     5     .apple.size+1        'long'
     6     .melon.price[1]      'short'
     7     .apple.size+3        'long'
     8     .apple.taste         'char'
     9     .melon.price[2]+1    'short'
    10     .apple+10            'struct'
    11     .apple+11            'struct'

  Offset   0   1   2   3   4   5   6   7   8   9  10  11
  -------------------------------------------------------
  apple   (C) (C)  -   -  (S) (s)  s  (s) (T)  -  (-) (-)
  grape    G   G  (G)
  melon    W   w   w  (w)  P   p  (P)  p   P  (p)  -   -

  Offset   Member               Type
  --------------------------------------
     0     .apple.color[0]      'char'
           .grape[0]            'char'
           .melon.weight        'long'
     1     .apple.color[1]      'char'
           .grape[1]            'char'
           .melon.weight+1      'long'
     2     .grape[2]            'char'
           .melon.weight+2      'long'
           .apple+2             'struct'
     3     .melon.weight+3      'long'
           .apple+3             'struct'
     4     .apple.size          'long'
           .melon.price[0]      'short'
     5     .apple.size+1        'long'
           .melon.price[0]+1    'short'
     6     .melon.price[1]      'short'
           .apple.size+2        'long'
     7     .apple.size+3        'long'
           .melon.price[1]+1    'short'
     8     .apple.taste         'char'
           .melon.price[2]      'short'
     9     .melon.price[2]+1    'short'
           .apple+9             'struct'
    10     .apple+10            'struct'
           .melon+10            'struct'
    11     .apple+11            'struct'
           .melon+11            'struct'

  print "$_\n" for $c->member('choice');

  .apple.color[0]
  .apple.color[1]
  .apple.size
  .apple.taste
  .grape[0]
  .grape[1]
  .grape[2]
  .melon.weight
  .melon.price[0]
  .melon.price[1]
  .melon.price[2]

tag

"tag" TYPE

"tag" TYPE, TAG

"tag" TYPE, TAG1 => VALUE1, TAG2 => VALUE2, ...

The "tag" method can be used to tag properties to a TYPE. It's a bit like having "configure" for individual types.

See "USING TAGS" for an example.

Note that while you can tag whole types as well as compound members, it is not possible to tag array members, i.e. you cannot treat, for example, "a[1]" and "a[2]" differently.

Also note that in code like this

  struct test {
    int a;
    struct {
      int x;
    } b, c;
  };
    

if you tag "test.b.x", this will also tag "test.c.x" implicitly.

It is also possible to tag basic types if you really want to do that, for example:

  $c->tag('int', Format => 'Binary');
    

To remove a tag from a type, you can either set that tag to "undef", for example

  $c->tag('test', Hooks => undef);
    

or use "untag".

To see if a tag is attached to a type or to get the value of a tag, pass only the type and tag name to "tag":

  $c->tag('test.a', Format => 'Binary');
  
  $hooks = $c->tag('test.a', 'Hooks');
  $format = $c->tag('test.a', 'Format');
    

This will give you:

  $hooks = undef;
  $format = 'Binary';
    

To see which tags are attached to a type, pass only the type. The "tag" method will now return a hash reference containing all tags attached to the type:

  $tags = $c->tag('test.a');
    

This will give you:

  $tags = {
    'Format' => 'Binary'
  };
    

"tag" will throw an exception if an error occurs. If called as a 'set' method, it will return a reference to its object, allowing you to chain together consecutive method calls.

Note that when a compound is inlined, tags attached to the inlined compound are ignored, for example:

  $c->parse(<<ENDC);
  struct header {
    int id;
    int len;
    unsigned flags;
  };
  
  struct message {
    struct header;
    short samples[32];
  };
  ENDC
  
  for my $type (qw( header message header.len )) {
    $c->tag($type, Hooks => { unpack => sub { print "unpack: $type\n"; @_ } });
  }
  
  for my $type (qw( header message )) {
    print "[unpacking $type]\n";
    $u = $c->unpack($type, $data);
  }
    

This will print:

  [unpacking header]
  unpack: header.len
  unpack: header
  [unpacking message]
  unpack: header.len
  unpack: message
    

As you can see from the above output, tags attached to members of inlined compounds ("header.len" are still handled.

The following tags can be configured:

untag

"untag" TYPE

"untag" TYPE, TAG1, TAG2, ...

Use the "untag" method to remove one, more, or all tags from a type. If you don't pass any tag names, all tags attached to the type will be removed. Otherwise only the listed tags will be removed.

See "USING TAGS" for an example.

arg

"arg" 'ARG', ...

Creates placeholders for special arguments to be passed to hooks or other subroutines. These arguments are currently:

dependencies

"dependencies"

After some code has been parsed using either the "parse" or "parse_file" methods, the "dependencies" method can be used to retrieve information about all files that the object depends on, i.e. all files that have been parsed.

In scalar context, the method returns a hash reference. Each key is the name of a file. The values are again hash references, each of which holds the size, modification time (mtime), and change time (ctime) of the file at the moment it was parsed.

  use Convert::Binary::C;
  use Data::Dumper;
  
  #----------------------------------------------------------
  # Create object, set include path, parse 'string.h' header
  #----------------------------------------------------------
  my $c = Convert::Binary::C->new
          ->Include('/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/include',
                    '/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/include-fixed',
                    '/usr/include')
          ->parse_file('string.h');
  
  #----------------------------------------------------------
  # Get dependencies of the object, extract dependency files
  #----------------------------------------------------------
  my $depend = $c->dependencies;
  my @files  = keys %$depend;
  
  #-----------------------------
  # Dump dependencies and files
  #-----------------------------
  print Data::Dumper->Dump([$depend, \@files],
                        [qw( depend   *files )]);
    

The above code would print something like this:

  $depend = {
    '/usr/include/sys/cdefs.h' => {
      'size' => 20051,
      'mtime' => 1604969938,
      'ctime' => 1604969964
    },
    '/usr/include/gnu/stubs-32.h' => {
      'size' => 449,
      'mtime' => 1604969908,
      'ctime' => 1604969964
    },
    '/usr/include/bits/wordsize.h' => {
      'size' => 442,
      'mtime' => 1604969934,
      'ctime' => 1604969964
    },
    '/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/include/stddef.h' => {
      'size' => 12959,
      'mtime' => 1604974286,
      'ctime' => 1604975398
    },
    '/usr/include/stdc-predef.h' => {
      'size' => 2290,
      'mtime' => 1604969927,
      'ctime' => 1604969964
    },
    '/usr/include/string.h' => {
      'size' => 18766,
      'mtime' => 1604969936,
      'ctime' => 1604969964
    },
    '/usr/include/bits/types/locale_t.h' => {
      'size' => 983,
      'mtime' => 1604969927,
      'ctime' => 1604969964
    },
    '/usr/include/bits/long-double.h' => {
      'size' => 970,
      'mtime' => 1604969933,
      'ctime' => 1604969964
    },
    '/usr/include/bits/libc-header-start.h' => {
      'size' => 3288,
      'mtime' => 1604969927,
      'ctime' => 1604969964
    },
    '/usr/include/strings.h' => {
      'size' => 4753,
      'mtime' => 1604969936,
      'ctime' => 1604969964
    },
    '/usr/include/gnu/stubs.h' => {
      'size' => 384,
      'mtime' => 1604969927,
      'ctime' => 1604969964
    },
    '/usr/include/bits/types/__locale_t.h' => {
      'size' => 1722,
      'mtime' => 1604969927,
      'ctime' => 1604969964
    },
    '/usr/include/features.h' => {
      'size' => 17235,
      'mtime' => 1604969927,
      'ctime' => 1604969964
    }
  };
  @files = (
    '/usr/include/sys/cdefs.h',
    '/usr/include/gnu/stubs-32.h',
    '/usr/include/bits/wordsize.h',
    '/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/include/stddef.h',
    '/usr/include/stdc-predef.h',
    '/usr/include/string.h',
    '/usr/include/bits/types/locale_t.h',
    '/usr/include/bits/long-double.h',
    '/usr/include/bits/libc-header-start.h',
    '/usr/include/strings.h',
    '/usr/include/gnu/stubs.h',
    '/usr/include/bits/types/__locale_t.h',
    '/usr/include/features.h'
  );
    

In list context, the method returns the names of all files that have been parsed, i.e. the following lines are equivalent:

  @files = keys %{$c->dependencies};
  @files = $c->dependencies;
    

sourcify

"sourcify"

"sourcify" CONFIG

Returns a string that holds the C source code necessary to represent all parsed C data structures.

  use Convert::Binary::C;
  
  $c = Convert::Binary::C->new;
  $c->parse(<<'END');
  
  #define ADD(a, b) ((a) + (b))
  #define NUMBER 42
  
  typedef struct _mytype mytype;
  
  struct _mytype {
    union {
      int         iCount;
      enum count *pCount;
    } counter;
  #pragma pack( push, 1 )
    struct {
      char string[NUMBER];
      int  array[NUMBER/sizeof(int)];
    } storage;
  #pragma pack( pop )
    mytype *next;
  };
  
  enum count { ZERO, ONE, TWO, THREE };
  
  END
  
  print $c->sourcify;
    

The above code would print something like this:

  /* typedef predeclarations */
  
  typedef struct _mytype mytype;
  
  /* defined enums */
  
  enum count
  {
        ZERO,
        ONE,
        TWO,
        THREE
  };
  
  
  /* defined structs and unions */
  
  struct _mytype
  {
        union
        {
                int iCount;
                enum count *pCount;
        } counter;
  #pragma pack(push, 1)
        struct
        {
                char string[42];
                int array[10];
        } storage;
  #pragma pack(pop)
        mytype *next;
  };
    

The purpose of the "sourcify" method is to enable some kind of platform-independent caching. The C code generated by "sourcify" can be parsed by any standard C compiler, as well as of course by the Convert::Binary::C parser. However, the code may be significantly shorter than the code that has originally been parsed.

When parsing a typical header file, it's easily possible that you need to open dozens of other files that are included from that file, and end up parsing several hundred kilobytes of C code. Since most of it is usually preprocessor directives, function prototypes and comments, the "sourcify" function strips this down to a few kilobytes. Saving the "sourcify" string and parsing it next time instead of the original code may be a lot faster.

The "sourcify" method takes a hash reference as an optional argument. It can be used to tweak the method's output. The following options can be configured.

The following methods can be used to retrieve information about the definitions that have been parsed. The examples given in the description for "enum", "compound" and "typedef" all assume this piece of C code has been parsed:

  #define ABC_SIZE 2
  #define MULTIPLY(x, y) ((x)*(y))
  
  #ifdef ABC_SIZE
  # define DEFINED
  #else
  # define NOT_DEFINED
  #endif
  
  typedef unsigned long U32;
  typedef void *any;
  
  enum __socket_type
  {
    SOCK_STREAM    = 1,
    SOCK_DGRAM     = 2,
    SOCK_RAW       = 3,
    SOCK_RDM       = 4,
    SOCK_SEQPACKET = 5,
    SOCK_PACKET    = 10
  };
  
  struct STRUCT_SV {
    void *sv_any;
    U32   sv_refcnt;
    U32   sv_flags;
  };
  
  typedef union {
    int abc[ABC_SIZE];
    struct xxx {
      int a;
      int b;
    }   ab[3][4];
    any ptr;
  } test;

enum_names

"enum_names"

Returns a list of identifiers of all defined enumeration objects. Enumeration objects don't necessarily have an identifier, so something like

  enum { A, B, C };
    

will obviously not appear in the list returned by the "enum_names" method. Also, enumerations that are not defined within the source code - like in

  struct foo {
    enum weekday *pWeekday;
    unsigned long year;
  };
    

where only a pointer to the "weekday" enumeration object is used - will not be returned, even though they have an identifier. So for the above two enumerations, "enum_names" will return an empty list:

  @names = $c->enum_names;
    

The only way to retrieve a list of all enumeration identifiers is to use the "enum" method without additional arguments. You can get a list of all enumeration objects that have an identifier by using

  @enums = map { $_->{identifier} || () } $c->enum;
    

but these may not have a definition. Thus, the two arrays would look like this:

  @names = ();
  @enums = ('weekday');
    

The "def" method returns a true value for all identifiers returned by "enum_names".

enum

enum

"enum" LIST

Returns a list of references to hashes containing detailed information about all enumerations that have been parsed.

If a list of enumeration identifiers is passed to the method, the returned list will only contain hash references for those enumerations. The enumeration identifiers may optionally be prefixed by "enum".

If an enumeration identifier cannot be found, the returned list will contain an undefined value at that position.

In scalar context, the number of enumerations will be returned as long as the number of arguments to the method call is not 1. In the latter case, a hash reference holding information for the enumeration will be returned.

The list returned by the "enum" method looks similar to this:

  @enum = (
    {
      'enumerators' => {
        'SOCK_STREAM' => 1,
        'SOCK_DGRAM' => 2,
        'SOCK_PACKET' => 10,
        'SOCK_SEQPACKET' => 5,
        'SOCK_RDM' => 4,
        'SOCK_RAW' => 3
      },
      'identifier' => '__socket_type',
      'size' => 4,
      'sign' => 0,
      'context' => 'definitions.c(13)'
    }
  );
    

  %enum = map %{ $_->{enumerators} || {} }, $c->enum;

  %enum = (
    'SOCK_RDM' => 4,
    'SOCK_SEQPACKET' => 5,
    'SOCK_PACKET' => 10,
    'SOCK_STREAM' => 1,
    'SOCK_DGRAM' => 2,
    'SOCK_RAW' => 3
  );

compound_names

"compound_names"

Returns a list of identifiers of all structs and unions (compound data structures) that are defined in the parsed source code. Like enumerations, compounds don't need to have an identifier, nor do they need to be defined.

Again, the only way to retrieve information about all struct and union objects is to use the "compound" method and don't pass it any arguments. If you should need a list of all struct and union identifiers, you can use:

  @compound = map { $_->{identifier} || () } $c->compound;
    

The "def" method returns a true value for all identifiers returned by "compound_names".

If you need the names of only the structs or only the unions, use the "struct_names" and "union_names" methods respectively.

compound

"compound"

"compound" LIST

Returns a list of references to hashes containing detailed information about all compounds (structs and unions) that have been parsed.

If a list of struct/union identifiers is passed to the method, the returned list will only contain hash references for those compounds. The identifiers may optionally be prefixed by "struct" or "union", which limits the search to the specified kind of compound.

If an identifier cannot be found, the returned list will contain an undefined value at that position.

In scalar context, the number of compounds will be returned as long as the number of arguments to the method call is not 1. In the latter case, a hash reference holding information for the compound will be returned.

The list returned by the "compound" method looks similar to this:

  @compound = (
    {
      'identifier' => 'STRUCT_SV',
      'align' => 1,
      'declarations' => [
        {
          'type' => 'void',
          'declarators' => [
            {
              'size' => 8,
              'offset' => 0,
              'declarator' => '*sv_any'
            }
          ]
        },
        {
          'type' => 'U32',
          'declarators' => [
            {
              'size' => 8,
              'offset' => 8,
              'declarator' => 'sv_refcnt'
            }
          ]
        },
        {
          'type' => 'U32',
          'declarators' => [
            {
              'size' => 8,
              'offset' => 16,
              'declarator' => 'sv_flags'
            }
          ]
        }
      ],
      'type' => 'struct',
      'size' => 24,
      'context' => 'definitions.c(23)',
      'pack' => 0
    },
    {
      'identifier' => 'xxx',
      'align' => 1,
      'declarations' => [
        {
          'type' => 'int',
          'declarators' => [
            {
              'size' => 4,
              'offset' => 0,
              'declarator' => 'a'
            }
          ]
        },
        {
          'type' => 'int',
          'declarators' => [
            {
              'size' => 4,
              'offset' => 4,
              'declarator' => 'b'
            }
          ]
        }
      ],
      'type' => 'struct',
      'size' => 8,
      'context' => 'definitions.c(31)',
      'pack' => 0
    },
    {
      'align' => 1,
      'declarations' => [
        {
          'type' => 'int',
          'declarators' => [
            {
              'size' => 8,
              'offset' => 0,
              'declarator' => 'abc[2]'
            }
          ]
        },
        {
          'type' => 'struct xxx',
          'declarators' => [
            {
              'size' => 96,
              'offset' => 0,
              'declarator' => 'ab[3][4]'
            }
          ]
        },
        {
          'type' => 'any',
          'declarators' => [
            {
              'size' => 8,
              'offset' => 0,
              'declarator' => 'ptr'
            }
          ]
        }
      ],
      'type' => 'union',
      'size' => 96,
      'context' => 'definitions.c(29)',
      'pack' => 0
    }
  );
    

  push @{$_->{type} eq 'union' ? \@unions : \@structs}, $_
      for $c->compound;

  @structs = $c->struct;
  @unions  = $c->union;

struct_names

"struct_names"

Returns a list of all defined struct identifiers. This is equivalent to calling "compound_names", just that it only returns the names of the struct identifiers and doesn't return the names of the union identifiers.

struct

"struct"

"struct" LIST

Like the "compound" method, but only allows for structs.

union_names

"union_names"

Returns a list of all defined union identifiers. This is equivalent to calling "compound_names", just that it only returns the names of the union identifiers and doesn't return the names of the struct identifiers.

union

"union"

"union" LIST

Like the "compound" method, but only allows for unions.

typedef_names

"typedef_names"

Returns a list of all defined typedef identifiers. Typedefs that do not specify a type that you could actually work with will not be returned.

The "def" method returns a true value for all identifiers returned by "typedef_names".

typedef

"typedef"

"typedef" LIST

Returns a list of references to hashes containing detailed information about all typedefs that have been parsed.

If a list of typedef identifiers is passed to the method, the returned list will only contain hash references for those typedefs.

If an identifier cannot be found, the returned list will contain an undefined value at that position.

In scalar context, the number of typedefs will be returned as long as the number of arguments to the method call is not 1. In the latter case, a hash reference holding information for the typedef will be returned.

The list returned by the "typedef" method looks similar to this:

  @typedef = (
    {
      'type' => 'unsigned long',
      'declarator' => 'U32'
    },
    {
      'type' => 'void',
      'declarator' => '*any'
    },
    {
      'type' => {
        'align' => 1,
        'declarations' => [
          {
            'type' => 'int',
            'declarators' => [
              {
                'size' => 8,
                'offset' => 0,
                'declarator' => 'abc[2]'
              }
            ]
          },
          {
            'type' => 'struct xxx',
            'declarators' => [
              {
                'size' => 96,
                'offset' => 0,
                'declarator' => 'ab[3][4]'
              }
            ]
          },
          {
            'type' => 'any',
            'declarators' => [
              {
                'size' => 8,
                'offset' => 0,
                'declarator' => 'ptr'
              }
            ]
          }
        ],
        'type' => 'union',
        'size' => 96,
        'context' => 'definitions.c(29)',
        'pack' => 0
      },
      'declarator' => 'test'
    }
  );
    

macro_names

"macro_names"

Returns a list of all defined macro names.

The list returned by the "macro_names" method looks similar to this:

  @macro_names = (
    '__STDC_VERSION__',
    '__STDC_HOSTED__',
    'DEFINED',
    'MULTIPLY',
    'ABC_SIZE'
  );
    

This works only as long as the preprocessor is not reset. See "Preprocessor configuration" for details.

macro

"macro"

"macro" LIST

Returns the definitions for all defined macros.

If a list of macro names is passed to the method, the returned list will only contain the definitions for those macros. For undefined macros, "undef" will be returned.

The list returned by the "macro" method looks similar to this:

  @macro = (
    '__STDC_VERSION__ 199901L',
    '__STDC_HOSTED__ 1',
    'DEFINED',
    'MULTIPLY(x, y) ((x)*(y))',
    'ABC_SIZE 2'
  );
    

This works only as long as the preprocessor is not reset. See "Preprocessor configuration" for details.

feature

"feature" STRING

Checks if Convert::Binary::C was built with certain features. For example,

  print "debugging version"
      if Convert::Binary::C::feature('debug');
    

will check if Convert::Binary::C was built with debugging support enabled. The "feature" function returns 1 if the feature is enabled, 0 if the feature is disabled, and "undef" if the feature is unknown. Currently the only features that can be checked are "ieeefp" and "debug".

You can enable or disable certain features at compile time of the module by using the

  perl Makefile.PL enable-feature disable-feature
    

syntax.

native

"native"

"native" STRING

Returns the value of a property of the native system that Convert::Binary::C was built on. For example,

  $size = Convert::Binary::C::native('IntSize');
    

will fetch the size of an "int" on the native system. The following properties can be queried:

  Alignment
  ByteOrder
  CharSize
  CompoundAlignment
  DoubleSize
  EnumSize
  FloatSize
  HostedC
  IntSize
  LongDoubleSize
  LongLongSize
  LongSize
  PointerSize
  ShortSize
  StdCVersion
  UnsignedBitfields
  UnsignedChars
    

You can also call "native" without arguments, in which case it will return a reference to a hash with all properties, like:

  $native = {
    'EnumSize' => 4,
    'ShortSize' => 2,
    'UnsignedChars' => 0,
    'IntSize' => 4,
    'LongDoubleSize' => 16,
    'StdCVersion' => 201710,
    'HostedC' => 1,
    'CompoundAlignment' => 1,
    'UnsignedBitfields' => 0,
    'DoubleSize' => 8,
    'Alignment' => 16,
    'PointerSize' => 8,
    'ByteOrder' => 'LittleEndian',
    'LongLongSize' => 8,
    'CharSize' => 1,
    'LongSize' => 8,
    'FloatSize' => 4
  };
    

The contents of that hash are suitable for passing them to the "configure" method.

Debugging options

  m   enable memory allocation tracing
  M   enable memory allocation & assertion tracing
  
  h   enable hash table debugging
  H   enable hash table dumps
  
  d   enable debug output from the XS module
  c   enable debug output from the ctlib
  t   enable debug output about type objects
  
  l   enable debug output from the C lexer
  p   enable debug output from the C parser
  P   enable debug output from the C preprocessor
  r   enable debug output from the #pragma parser
  
  y   enable debug output from yacc (bison)

So the following might give you a brief overview of what's going on inside Convert::Binary::C:

  use Convert::Binary::C debug => 'dct';

When you want to debug memory allocation using

  use Convert::Binary::C debug => 'm';

you can use the Perl script check_alloc.pl that resides in the ctlib/util/tool directory to extract statistics about memory usage and information about memory leaks from the resulting debug output.

Redirecting debug output

  use Convert::Binary::C debug     => 'dcthHm',
                         debugfile => './debug.out';

If the file cannot be opened, you'll receive a warning and the output will go the "stderr" way again.

Alternatively, you can use the environment variables "CBC_DEBUG_OPT" and "CBC_DEBUG_FILE" to turn on debug output.

If Convert::Binary::C is built without debugging support, passing the "debug" or "debugfile" options will cause a warning to be issued. The corresponding environment variables will simply be ignored.

"CBC_ORDER_MEMBERS"

Setting the variable to the name of a perl module will additionally use this module instead of the predefined modules for member ordering to tie the hashes to.

"CBC_DEBUG_OPT"

"CBC_DEBUG_FILE"

"CBC_DISABLE_PARSER"

C::Include

C::DynaLib::Struct

Win32::API::Struct