=pod

=encoding utf-8

=head1 NAME

Dyn::Call::Pointer - dyncall variant pointer

=head1 SYNOPSIS

    use Dyn::Call qw[:memory];
    my $ptr = malloc( 10 ); # <--- This is a Dyn::Call::Pointer
    memmove( $ptr, 'Hello, world', 12 );
    free( $ptr );

=head1 DESCRIPTION

It's a void pointer. Make whatever you want with it.

=head1 Functions

Most Dyn::Call::Pointer objects will be generated by dyncall and used
internally but you may use C<malloc( ... )> or C<calloc( ... )> to create one
for your own use.

=head2 C<malloc( $size )>

Allocates C<$size> bytes of uninitialized storage.

    my $value1 = malloc( 10 ); # space for 10 bytes

On success, a new Dyn::Call::Pointer object is returned. To avoid a memory
leaks, the returned pointer must be deallocated with C<free( ... )> or
C<realloc( ... )>.

Failure results in C<undef>.

=head2 C<calloc( $num, $size )>

Allocates memory for an array of C<$num> objects of C<$size> and initializes
all bytes in the allocated storage to zero.

    my $value2 = calloc( 50, 1 ); # space for 50 chars

On success, a new Dyn::Call::Pointer object is returned. To avoid a memory
leaks, the returned pointer must be deallocated with C<free( ... )> or
C<realloc( ... )>.

Failure results in C<undef>.

=head2 C<realloc( $ptr, $new_size )>

Reallocates the given area of memory. It must be previously allocated by
C<malloc( ... )>, C<calloc( ... )> or C<realloc( ... )> and not yet freed with
a call to C<free( ... )> or C<realloc( ... )>.

    my $value3 = realloc( $value2, 1024 );

On success, a new Dyn::Call::Pointer object is returned. To avoid a memory
leaks, the returned pointer must be deallocated with C<free( ... )> or
C<realloc( ... )>.

Failure results in C<undef>.

=head2 C<free( $ptr )>

Deallocates the space previously allocated by C<malloc( ... )>, C<calloc( ...
)> or C<realloc( ... )>.

    free( $value2 );

=head2 C<memchr( $ptr, $ch, $count )>

Finds the first occurrence of (C<unsigned char>) C<$ch> in the initial
C<$count> bytes (each interpreted as C<unsigned char>) of the object pointed to
by C<$ptr>.

=head2 C<memcmp( $lhs, $rhs, $count )>

Compares the first C<$count> bytes of the objects pointed to by C<$lhs> and
C<$rhs>. The comparison is done lexicographically.

Returns a negative value if C<$lhs> appears before C<$rhs> in lexicographical
order.

Returns zero if C<$lhs> and C<$rhs> compare equal or if C<$count> is zero.

Returns a positive value if C<$lhs> appears after C<$rhs> in lexicographical
order.

=head2 C<memset( $dest, $ch, $count )>

Copies the value (C<unsigned char>) C<$ch> into each of the first C<$count>
characters of the object pointed to by C<$dest>.

    memset( $ptr, 'a', 5 );

Returns a copy of C<$dest>.

=head2 C<memcpy( $dest, $src, $count )>

Copies C<$count> characters from the object pointed to by C<$src> to the object
pointed to by C<$dest>. Both objects are interpreted as arrays of C<unsigned
char>.

Returns a copy of C<$dest>.

=head2 C<memmove( $dest, $src, $count )>

Copies C<$count> characters from the object pointed to by C<$src> to the object
pointed to by C<$dest>. Both objects are interpreted as arrays of C<unsigned
char>. The objects may overlap: copying takes place as if the characters were
copied to a temporary character array and then the characters were copied from
the array to C<$dest>.

Returns a copy of C<$dest>.

=head1 LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under
the terms found in the Artistic License 2. Other copyrights, terms, and
conditions may apply to data transmitted through this module.

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=begin stopwords

dyncall const deallocated

=end stopwords

=cut