The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Convert-Binary-C-0.06
River stage one • 4 direct dependents • 4 total dependents
/ Convert::Binary::C

NAME

Convert::Binary::C - Binary Data Conversion using C Types

SYNOPSIS

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 = new Convert::Binary::C ByteOrder => 'BigEndian';
  
  #---------------------------------------------------
  # Add include paths and global preprocessor defines
  #---------------------------------------------------
  $c->Include( '/usr/lib/gcc-lib/i486-suse-linux/2.95.3/include',
               '/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( [keys %{$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 = "binaryteststring";
  
  #--------------------------------------------------------
  # 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";

DESCRIPTION

Convert::Binary::C is a preprocessor and parser for C type definitions. It is highly configurable and should support arbitrarily complex data structures. Its object-oriented interface has pack and unpack methods that act as replacements for Perl's pack and unpack and allow to use the C types instead of a string representation of the data structure for conversion of binary data from and to Perl's complex data structures.

Actually, what Convert::Binary::C does is not very different from what a C compiler does, just that it doesn't compile the source code into an object file or executable, but only parses the code and allows Perl to use the enumerations, structs, unions and typedefs that have been defined within your C source for binary data conversion, similar to Perl's pack and unpack.

Beyond that, the module offers a lot of convenience methods to retrieve information about the C types that have been parsed.

Background and History

In late 2000 I wrote a realtime debugging interface for an embedded medical device that allowed me to send out data from that device over its integrated ethernet adapter. The interface was printf()-like, so you could easily send out strings or numbers. But you could also send out what I called arbitrary data, which was intended for arbitrary blocks of the device's memory.

Another part of this realtime 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 an numbers, and hexdumped the arbitrary data. However, manually parsing a couple of 300 byte hexdumps 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 hexdumps.

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

This document describes how to use Convert::Binary::C. A lot of different features are presented, and the example code sometimes uses Perl's more advanced language elements. If your experience with Perl is rather limited, you should know how to use Perl's very good documentation system.

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 Convert::Binary::C?

Say you want to pack (or unpack) data according to the following C structure:

  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

To use Convert::Binary::C just say

  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 = new Convert::Binary::C;

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

Configuring the object

To configure a Convert::Binary::C object, you can either call the configure method or directly pass the configuration options to the constructor. If you want to change byte order and alignment, you can use

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

or you can change the construction code to

  $c = new Convert::Binary::C 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

Convert::Binary::C allows two ways of parsing C source. Either by parsing external C header or C source files:

  $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 to easily embed multiline 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( $@ ) {
    # do something appropriate
  }

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( $@ ) {
    # do something appropriate
  }

Packing and unpacking

Convert::Binary::C has two methods, pack and unpack, that act similar to the functions of same denominator in Perl. To perform the packing described in the example above, you could write:

  $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 = 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 = {
    'bar' => -271,
    'baz' => 5000,
    'ary' => [
      42,
      48,
      100
    ]
  };

Preprocessor configuration

Convert::Binary::C uses Thomas Pornin's ucpp as an internal C preprocessor. It is compliant to ISO-C99, so you don't have to worry about using even weird preprocessor constructs in your code.

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)'] );

Supported pragma directives

Convert::Binary::C supports the pack pragma to locally override struct member alignment. The supported syntax is as follows:

#pragma pack( ALIGN )

Sets the new alignment to ALIGN.

#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.

#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 to specify the minimum struct member alignment. This is not supported by Convert::Binary::C.

METHODS

new

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

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

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

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 = new Convert::Binary::C Define  => ['DEBUGGING', 'FOO=123'],
                              Include => ['/usr/include'];
  
  print Dumper( $c->configure );

This will print something like this:

  $VAR1 = {
    'Define' => [
      'DEBUGGING',
      'FOO=123'
    ],
    'ByteOrder' => 'LittleEndian',
    'LongSize' => 4,
    'IntSize' => 4,
    'ShortSize' => 2,
    'HasMacroVAARGS' => 1,
    'Assert' => [],
    'UnsignedChars' => 0,
    'DoubleSize' => 8,
    'EnumType' => 'Integer',
    'PointerSize' => 4,
    'EnumSize' => 4,
    'DisabledKeywords' => [],
    'FloatSize' => 4,
    'LongLongSize' => 8,
    'Alignment' => 1,
    'LongDoubleSize' => 12,
    'HasCPPComments' => 1,
    'Include' => [
      '/usr/include'
    ],
    'Warnings' => 0
  };

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 = new Convert::Binary::C 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.

IntSize => 0 | 1 | 2 | 4 | 8

Set the number of bytes that are occupied by an integer. This is in most cases 2 or 4. If you set it to zero, the size of an integer on the host system will be used. This is also the default.

ShortSize => 0 | 1 | 2 | 4 | 8

Set the number of bytes that are occupied by a short integer. Although integers explicitly declared as short should be always 16 bit, there are compilers that make a short 8 bit wide. If you set it to zero, the size of a short integer on the host system will be used. This is also the default.

LongSize => 0 | 1 | 2 | 4 | 8

Set the number of bytes that are occupied by a long integer. If set to zero, the size of a long integer on the host system will be used. This is also the default.

LongLongSize => 0 | 1 | 2 | 4 | 8

Set the number of bytes that are occupied by a long long integer. If set to zero, the size of a long long integer on the host system, or 8, will be used. This is also the default.

FloatSize => 0 | 1 | 2 | 4 | 8 | 12

Set the number of bytes that are occupied by a single precision floating point value. If you set it to zero, the size of a float on the host system will be used. This is also the default. Values can only be packed and unpacked if the size matches the native size of a float.

DoubleSize => 0 | 1 | 2 | 4 | 8 | 12

Set the number of bytes that are occupied by a double precision floating point value. If you set it to zero, the size of a double on the host system will be used. This is also the default. Values can only be packed and unpacked if the size matches the native size of a double.

LongDoubleSize => 0 | 1 | 2 | 4 | 8 | 12

Set the number of bytes that are occupied by a double precision floating point value. If you set it to zero, the size of a long double on the host system, or 12 will be used. This is also the default. Values can only be packed and unpacked if the size matches the native size of a long double.

PointerSize => 0 | 1 | 2 | 4 | 8

Set the number of bytes that are occupied by a pointer. This is in most cases 2 or 4. If you set it to zero, the size of a pointer on the host system will be used. This is also the default.

EnumSize => 0 | 1 | 2 | 4

Set the number of bytes that are occupied by an enumeration type. On most systems, this is equal to the size of an integer, which is also the default. However, for some compilers, the size of an enumeration type depends on the size occupied by the largest enumerator. So the size may vary between 1 and 4. If you have

  enum foo {
    ONE = 100, TWO = 200
  };

this will occupy one byte because the enum can be represented as an unsigned one-byte value. However,

  enum foo {
    ONE = -100, TWO = 200
  };

will occupy two bytes, because the -100 forces the type to be signed, and 200 doesn't fit into a signed one-byte value. Therefore, the type used is a signed two-byte value. If this is the behaviour you need, set the EnumSize to zero.

Alignment => 1 | 2 | 4 | 8

Set the struct member alignment. This option controls where padding bytes are inserted between struct members. It globally sets the alignment for all structs/unions. However, this can be overridden from within the source code with the common pack pragma as explained in "Supported pragma directives". The default alignment is 1, which means no padding bytes are inserted.

ByteOrder => 'BigEndian' | 'LittleEndian'

Set the byte order for integers larger than a single byte. Little endian (Intel, least significant byte first) and big endian (Motorola, most significant byte first) byte order are supported. The default byte order is the same as the byte order of the host system.

EnumType => 'Integer' | 'String' | 'Both'

This option controls the type that enumeration constants will have in data structures returned by the unpack method. If you have the following definitions:

  typedef enum {
    SUNDAY, MONDAY, TUESDAY, WEDNESDAY,
    THURSDAY, FRIDAY, SATURDAY
  } Weekday;
   
  typedef enum {
    JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY,
    AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER
  } Month;
   
  typedef struct {
    int     year;
    Month   month;
    int     day;
    Weekday weekday;
  } Date;

and a byte string that holds a packed Date struct, then you'll get the following results from a call to the unpack method.

Integer

Enumeration constants are returned as plain integers. This is fast, but may be not very useful. It is also the default.

  $date = {
    'weekday' => 1,
    'month' => 0,
    'day' => 7,
    'year' => 2002
  };
String

Enumeration constants are returned as strings. This will create a string constant for every unpacked enumeration constant and thus consumes more time and memory. However, the result may be more useful.

  $date = {
    'weekday' => 'MONDAY',
    'month' => 'JANUARY',
    'day' => 7,
    'year' => 2002
  };
Both

Enumeration constants are returned as double typed scalars. If evaluated in string context, the enumeration constant will be a string, if evaluated in numeric context, the enumeration constant will be an integer.

  $date = $c->EnumType('Both')->unpack('Date', $binary);
  
  printf "Weekday = %s (%d)\n\n", $date->{weekday},
                                  $date->{weekday};
  
  if( $date->{month} == 0 ) {
    print "It's $date->{month}, happy new year!\n\n";
  }
  
  print Dumper( $date );

This will print:

  Weekday = MONDAY (1)
  
  It's JANUARY, happy new year!
  
  $VAR1 = {
    'weekday' => 'MONDAY',
    'month' => 'JANUARY',
    'day' => 7,
    'year' => 2002
  };
DisabledKeywords => [ KEYWORDS ]

This option allows you to selectively deactivate certain keywords in the C parser. Some C compilers don't have the complete ANSI keyword set, i.e. they don't recognize the keywords const or void, for example. If you do

  typedef int void;

on such a compiler, this will usually be ok. But if you parse this with an ANSI compiler, it will be a syntax error. To parse the above code correctly, you have to disable the void keyword in the Convert::Binary::C parser:

  $c->DisabledKeywords( [qw( void )] );

If Convert::Binary::C is built with the C99 feature enabled (which is the default), the parser will recognize the keywords inline and restrict. If your compiler doesn't have these new keywords, it usually doesn't matter. Only if you're using the keywords as identifiers, like in

  typedef struct inline {
    int a, b;
  } restrict;

you'll have to disable the ANSI-C99 keywords:

  $c->DisabledKeywords( [qw( inline restrict )] );

The parser allows you to disable the following keywords:

  auto
  const
  double
  enum
  extern
  float
  inline
  long
  register
  restrict
  short
  signed
  static
  unsigned
  void
  volatile
UnsignedChars => 0 | 1

Use this boolean option if you want characters to be unsigned if specified without an explicit signed or unsigned type specifier. By default, characters are signed.

Warnings => 0 | 1

Use this boolean option if you want warnings to be issued during the parsing of source code. Currently, warnings are only reported by the preprocessor, so don't expect the output to cover everything.

By default, warnings are turned off and only errors will be reported. However, even these errors are turned off if you run without the -w flag.

HasCPPComments => 0 | 1

Use this option to turn C++ comments on or off. By default, C++ comments are enabled. Disabling C++ comments may be necessary if your code includes strange things like:

  one = 4 //* <- divide */ 4;
  two = 2;

With C++ comments, the above will be interpreted as

  one = 4
  two = 2;

which will obviously create a parse error, but without C++ comments, it will be interpreted as

  one = 4 / 4;
  two = 2;

which is correct.

HasMacroVAARGS => 0 | 1

Use this option to turn the __VA_ARGS__ macro expansion on or off. If this is enabled (which is the default), you can use variable length argument lists in your preprocessor macros.

  #define DEBUG( ... )  fprintf( stderr, __VA_ARGS__ )

There's normally no reason to turn that feature off.

Include => [ INCLUDES ]

Use this option to set the include path for the internal preprocessor. The option value is a reference to an array of strings, each string holding a directory that should be searched for includes.

Define => [ DEFINES ]

Use this option to define symbols in the preprocessor. The option value is, again, a reference to an array of strings. Each string can be either just a symbol or an assignment to a symbol. This is completely equivalent to what the -D option does for most preprocessors.

The following will define the symbol FOO and define BAR to be 12345:

  $c->configure( Define => [qw(FOO BAR=12345)] );
Assert => [ ASSERTIONS ]

Use this option to make assertions in the preprocessor. If you don't know what assertions are, don't be concerned, since they're deprecated anyway. They are, however, used in some system's include files. The value is an array reference, just like for the macro definitions. Only the way the assertions are defined is a bit different and mimics the way they are defined with the #assert directive:

  $c->configure( Assert => ['foo(bar)'] );

You can reconfigure all options even after you have parsed some code. The changes will be applied to the already parsed definitions. This works as long as array lengths are not affected by the changes. If you have Alignment and IntSize set to 4 and parse code like this

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

the array zap in struct bar will obviously have 16 elements. If you reconfigure the alignment to 1 now, the size of foo is now 5 instead of 8. While the alignment is adjusted correctly, the number of elements in array zap will still be 16 and will not be changed to 10.

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 throw an exception if an error occurs. On success, the method returns a reference to its object.

See "Parsing C code" for an example.

You must be aware that the preprocessor is reset with every call to parse or parse_file. Also, you may use types previously defined, but you are not allowed to redefine types.

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

Using clone is just a lot faster.

def

def TYPE

If you need to know if a definition for a certain type 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.

  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;
  };
  
  ENDC
  
  for my $type ( qw( not ptr foo bar xxx ) ) {
    my $def = $c->def( $type );
    printf "\$c->def( '$type' )  =>  %s\n",
           defined $def ? "'$def'" : 'undef';
  }

The following would be returned by the def method:

  $c->def( 'not' )  =>  ''
  $c->def( 'ptr' )  =>  'typedef'
  $c->def( 'foo' )  =>  'struct'
  $c->def( 'bar' )  =>  ''
  $c->def( 'xxx' )  =>  undef

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

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".

pack

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;
  
  $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. On success, the packed byte string is returned.

  print unpack('H*', $binary), "\n";

The above code would print:

  0102000000002a

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 = {
    'uni' => {
      'word' => [
        0,
        42
      ],
      'quad' => 42
    },
    'ary' => [
      1,
      2,
      0
    ]
  };

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

  $array = $c->pack( 'test.ary', [1, 2, 3] );
  print unpack('H*', $array), "\n";
  
  $value = $c->pack( 'test.uni.word[1]', 2 );
  print unpack('H*', $value), "\n";

This would give you:

  010203
  0002

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: ", unpack('H*', $too_short), "\n";
  
  $copy = $c->pack( 'test', { uni => { quad => 0x4711 } }, $too_long );
  print "copy     : ", unpack('H*', $copy), "\n";

This would print:

  too_short: 01020300004711
  copy     : 0102030000471108090a0b0c0d0e0f1011121314

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 = {
    'uni' => {
      'word' => [
        1029,
        1543
      ],
      'quad' => 67438087
    },
    'ary' => [
      1,
      2,
      3
    ]
  };

If TYPE refers to a compound object, you may unpack any member of that compound object. Simply add a member string 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
  ];

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]' );
  $size == 2 or die;

This would set $size to 2.

member

member TYPE, OFFSET

You can use this method if you want to retrieve the name, and optionally the type, of the member that is located at a specific offset for a previously parsed type.

  use Convert::Binary::C;
  use Data::Dumper;
  
  $c = Convert::Binary::C->new( Alignment => 4, EnumSize => 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$@" : " => '$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 )
  Offset 99 out of range (0 <= offset < 96)

The output of the first iteration is obvious. The member zap[2].abc is located at offset 16 of struct test.

In the second iteration, the offset points into a region of padding bytes, thus no member of week can be named and instead of a member name the offset relative to zap[3] is appended.

In the third iteration, the offset points to zap[5].ptr. However, zap[5].ptr is located at 44, not at 45, and thus the remaining offset of 1 is also appended.

The last iteration causes an exception because the offset of 99 is not valid for struct test since the size of struct test is only 96.

In list context, the member method will also return the member's type:

  for my $offset ( 24, 39, 69 ) {
    print "\$c->member( 'test', $offset ) => ";
    my($member, $type) = $c->member( 'test', $offset );
    printf "('$member', %s)\n", defined $type ? "'$type'" : 'undef';
  }

If the offset points to a region of padding bytes, the type will be undef. If the type is a pointer, a "*" string will be returned.

  $c->member( 'test', 24 ) => ('zap[2].abc', 'char')
  $c->member( 'test', 39 ) => ('zap[3]+3', undef)
  $c->member( 'test', 69 ) => ('zap[5].ptr+1', '*')

If the type cannot be expressed as a string, a reference to a definition of that type will be returned. Actually, this can only be the case for inlined, unnamed enums:

  $c->parse( <<'ENDC' );
  struct inlined {
    long dummy;
    enum { INSIDE } inside;
  };
  ENDC
  
  ($member, $type) = $c->member( 'inlined', 6 );
  print Data::Dumper->Dump( [$member, $type], [qw(member type)] );

This will print:

  $member = 'inside+2';
  $type = {
    'enumerators' => {
      'INSIDE' => 0
    },
    'sign' => 0,
    'size' => 1
  };

Have a look at the enum method for details on how to interpret the returned data structure.

You can additionally specify a member for the type passed as the first argument:

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

This will print:

  ('day+2', 'long')

offsetof

offsetof TYPE, MEMBER

You can think of offsetof as being the reverse of the member method. Given the member example code above,

  @args = (
    ['test',        'zap[5].day'  ],
    ['test.zap[2]', 'day'         ],
    ['test',        'zap[5].day+1'],
  );
  
  for( @args ) {
    printf "\$c->offsetof( '%s', '%s' )", @$_;
    my $offset = eval { $c->offsetof( @$_ ) };
    print $@ ? "\n$@" : " => $offset\n";
  }

will print:

  $c->offsetof( 'test', 'zap[5].day' ) => 64
  $c->offsetof( 'test.zap[2]', 'day' ) => 4
  $c->offsetof( 'test', 'zap[5].day+1' )
  Invalid character '+' (0x2B) in struct member expression

The first iteration will simply show that the offset of zap[5].day is 64 relative to the beginning of struct test.

You may additionally specify a member for the type passed as the first argument, as shown in the second iteration.

Since the +n syntax isn't allowed by offsetof, the third iteration will not print 45, but rather cause an exception because of an invalid character being used.

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.

The method returns a hash reference. Each key is the name of a file, so you could use

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

to retrieve a list of these files. 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-lib/i486-suse-linux/2.95.3/include',
                     '/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/features.h' => {
      'ctime' => 1034791519,
      'mtime' => 1033737983,
      'size' => 10679
    },
    '/usr/include/sys/cdefs.h' => {
      'ctime' => 1034791520,
      'mtime' => 1033738026,
      'size' => 6540
    },
    '/usr/include/gnu/stubs.h' => {
      'ctime' => 1034791519,
      'mtime' => 1033738050,
      'size' => 882
    },
    '/usr/include/string.h' => {
      'ctime' => 1034791520,
      'mtime' => 1033738022,
      'size' => 13914
    },
    '/usr/lib/gcc-lib/i486-suse-linux/2.95.3/include/stddef.h' => {
      'ctime' => 1004697846,
      'mtime' => 989593995,
      'size' => 9834
    }
  };
  @files = (
    '/usr/include/features.h',
    '/usr/include/sys/cdefs.h',
    '/usr/include/gnu/stubs.h',
    '/usr/include/string.h',
    '/usr/lib/gcc-lib/i486-suse-linux/2.95.3/include/stddef.h'
  );

sourcify

sourcify

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

  use Convert::Binary::C;
  
  $c = new Convert::Binary::C;
  $c->parse( <<'END' );
  
  #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];
        }
  #pragma pack( pop )
        storage;
        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 a standard C compiler, as well as of course the Convert::Binary::C parser. However, it might 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 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:

  typedef unsigned long U32;
  
  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[2];
    struct xxx {
      int a;
      int b;
    }   ab[3][4];
  } 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.

If an enumeration identifier cannot be found, a warning is issued and 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_RAW' => 3,
        'SOCK_SEQPACKET' => 5,
        'SOCK_RDM' => 4,
        'SOCK_PACKET' => 10,
        'SOCK_DGRAM' => 2
      },
      'identifier' => '__socket_type',
      'sign' => 0,
      'size' => 1
    }
  );
identifier

holds the enumeration identifier. This key is not present if the enumeration has no identifier.

enumerators

is a reference to a hash table that holds all enumerators of the enumeration.

sign

is a boolean indicating if the enumeration is signed.

size

is the size in bytes needed to store any enumerator of that enumeration. This does not need to be the size that is actually occupied by an enumerator. Only if EnumSize is configured to 0, these are identical.

One useful application may be to create a hash table that holds all enumerators of all defined enumerations:

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

The %enum hash table would then be:

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

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.

If an identifier cannot be found, a warning is issued and 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,
      'pack' => 0,
      'type' => 'struct',
      'declarations' => [
        {
          'declarators' => [
            {
              'declarator' => '*sv_any',
              'size' => 4,
              'offset' => 0
            }
          ],
          'type' => 'void'
        },
        {
          'declarators' => [
            {
              'declarator' => 'sv_refcnt',
              'size' => 4,
              'offset' => 4
            }
          ],
          'type' => 'U32'
        },
        {
          'declarators' => [
            {
              'declarator' => 'sv_flags',
              'size' => 4,
              'offset' => 8
            }
          ],
          'type' => 'U32'
        }
      ],
      'size' => 12
    },
    {
      'identifier' => 'xxx',
      'align' => 1,
      'pack' => 0,
      'type' => 'struct',
      'declarations' => [
        {
          'declarators' => [
            {
              'declarator' => 'a',
              'size' => 4,
              'offset' => 0
            }
          ],
          'type' => 'int'
        },
        {
          'declarators' => [
            {
              'declarator' => 'b',
              'size' => 4,
              'offset' => 4
            }
          ],
          'type' => 'int'
        }
      ],
      'size' => 8
    },
    {
      'align' => 1,
      'pack' => 0,
      'type' => 'union',
      'declarations' => [
        {
          'declarators' => [
            {
              'declarator' => 'abc[2]',
              'size' => 8,
              'offset' => 0
            }
          ],
          'type' => 'int'
        },
        {
          'declarators' => [
            {
              'declarator' => 'ab[3][4]',
              'size' => 96,
              'offset' => 0
            }
          ],
          'type' => 'struct xxx'
        }
      ],
      'size' => 96
    }
  );
identifier

holds the struct or union identifier. This key is not present if the compound has no identifier.

type

is either 'struct' or 'union'.

size

is the size of the struct or union.

align

is the alignment of the struct or union.

pack

is the struct member alignment if the compound is packed, or zero otherwise.

declarations

is an array of hash references describing each struct declaration:

type

is the type of the struct declaration. This may be a string or a reference to a hash describing the type.

declarators

is an array of hashes describing each declarator:

declarator

is a string representation of the declarator.

offset

is the offset of the struct member represented by the current declarator relative to the beginning of the struct or union.

size

is the size occupied by the struct member represented by the current declarator.

It may be useful to have separate lists for structs and unions. One way to retrieve such lists would be to use

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

However, you should use the struct and union methods, which is a lot simpler:

  @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, a warning is issued and 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 = (
    {
      'declarator' => 'U32',
      'type' => 'unsigned long'
    },
    {
      'declarator' => 'test',
      'type' => {
        'align' => 1,
        'pack' => 0,
        'type' => 'union',
        'declarations' => [
          {
            'declarators' => [
              {
                'declarator' => 'abc[2]',
                'size' => 8,
                'offset' => 0
              }
            ],
            'type' => 'int'
          },
          {
            'declarators' => [
              {
                'declarator' => 'ab[3][4]',
                'size' => 96,
                'offset' => 0
              }
            ],
            'type' => 'struct xxx'
          }
        ],
        'size' => 96
      }
    }
  );
declarator

is the type declarator.

type

is the type specification. This may be a string or a reference to a hash describing the type. See enum and compound for a description on how to interpret this hash.

FUNCTIONS

Convert::Binary::C::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 debug, threads and c99. The latter will check if some extensions of the ANSI-C99 standard are enabled.

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

  perl Makefile.PL enable-feature disable-feature

syntax.

DEBUGGING

Like perl itself, Convert::Binary::C can be compiled with debugging support that can then be selectively enabled at runtime. You can specify whether you like to build Convert::Binary::C with debugging support or not by explicitly giving an argument to Makefile.PL. Use

  perl Makefile.PL enable-debug

to enable debugging, or

  perl Makefile.PL disable-debug

to disable debugging. The default will depend on how your perl binary was built. If it was built with -DDEBUGGING, Convert::Binary::C will be built with debugging support, too.

Once you have built Convert::Binary::C with debugging support, you can use the following syntax to enable debug output. Instead of

  use Convert::Binary::C;

you simply say

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

which will enable all debug output. However, I don't recommend to enable all debug output, because that can be a fairly large amount. Instead of saying all, you can pass a string that consists of one or more of the following characters:

  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
  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.

By default, all debug output is written to stderr. You can, however, redirect the debug output to a file with the debugfile option:

  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.

If Convert::Binary::C is built without debugging support, passing the debug or debugfile options will cause a warning to be issued.

BITFIELDS

Bitfields are currently not supported by Convert::Binary::C, because I generally don't use them. I plan to support them in a later release, when I will have found an easy way of integrating them into the module.

Whenever a method has to deal with bitfields, it will issue a warning message that bitfields are unsupported. Thus, you may use bitfields in your C source code, but you won't be annoyed with warning messages unless you really use a type that actually contains bitfields in a method call like sizeof or pack.

While bitfields are not appropriately handled by the conversion routines yet, they are already parsed correctly. This means that you can reliably use the declarator fields as returned by the struct or typedef methods. Given the following source

  struct bitfield {
    int seven:7;
    int :1;
    int four:4, :0;
    int integer;
  };

a call to struct will return

  @struct = (
    {
      'identifier' => 'bitfield',
      'align' => 1,
      'pack' => 0,
      'type' => 'struct',
      'declarations' => [
        {
          'declarators' => [
            {
              'declarator' => 'seven:7'
            }
          ],
          'type' => 'int'
        },
        {
          'declarators' => [
            {
              'declarator' => ':1'
            }
          ],
          'type' => 'int'
        },
        {
          'declarators' => [
            {
              'declarator' => 'four:4'
            },
            {
              'declarator' => ':0'
            }
          ],
          'type' => 'int'
        },
        {
          'declarators' => [
            {
              'declarator' => 'integer',
              'size' => 4,
              'offset' => 0
            }
          ],
          'type' => 'int'
        }
      ],
      'size' => 4
    }
  );

No size/offset keys will be returned for bitfield entries. Also, the size of a structure containing bitfields is not valid, as bitfields internally do not increase the size of a structure yet.

MULTITHREADING

Convert::Binary::C was designed to be thread-safe.

Since the used preprocessor unfortunately isn't re-entrant, source code parsing using the parse and parse_file methods is locked, so don't expect these routines to run in parallel on multithreaded perls.

CREDITS

  • My love Jennifer for always being there, for filling my life with joy and last but not least for proofreading the documentation.

  • Michael J. Hohmann <mjh@scientist.de> for endless discussions on our way to and back home from work, and for making me think about supporting pack and unpack for compound members.

  • Thorsten Jens <thojens@gmx.de> for testing the package on various platforms.

  • Mark Overmeer <mark@overmeer.net> for suggesting the module name and giving invaluable feedback.

  • Thomas Pornin <pornin@bolet.org> for his excellent ucpp preprocessor library.

  • James Roskind, as his C parser was a great starting point to fix all the problems I had with my original parser based only on the ANSI ruleset.

  • Steffen Zimmermann for a prolific discussion on the cloning algorithm.

BUGS

I'm sure there are still lots of bugs in the code for this module. If you find any bugs, Convert::Binary::C doesn't seem to build on your system or any of its tests fail, please send a mail to <mhx@cpan.org>.

TODO

If you're interested in what I currently plan to improve (or fix), have a look at the TODO file.

COPYRIGHT

Copyright (c) 2002 Marcus Holland-Moritz. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The ucpp library is (c) Thomas Pornin 1999, 2000. For licence and redistribution details refer to ctlib/ucpp/README.

Portions copyright (c) 1989, 1990 James A. Roskind.

Some of the include files used for the t/106_parse.t test script are (c) 1991-1999, 2000, 2001 Free Software Foundation, Inc. They are neither required to create the binary nor linked to the source code of this module in any other way.

SEE ALSO

perl, perldata, perlop, perlvar and Data::Dumper.