---

=pod

=head1 NAME

SeDaBl -- Perl interface to the Serialized Data Blocks library.

=head1 DESCRIPTION

The perl interface to SeDaBl is automatically generated by SWIG from the API's header file. This means that all the functions available from C are avaialable from perl, as well. But just "because it's there" is not a good reason to use something. This page gives an overview of how to use SeDaBl from perl without giving yourself headaches.

One thing to keep in mind: don't try to look inside of the block and list structures directly! Treat the with care and they will work allright. Go digging around in there and you're likely to hurt yourself. I, for one, hope to never burrow around in these depths again...

SWIG does most of the C<->Perl glue itself. We only teach it how to handle the typemapping magic between pointers-to-sedabl_val and perl scalars, and between pointer-to-sedabl_list and perl arrays of sedabl_block. Basically, wherever the C API would supply a sedabl_val pointer, the Perl API wants a regular scalar; and wherever the C API would want a sedabl_list pointer, the Perl API wants an array of sedabl_block.

Because of this, the convenience functions are pretty much useless, and there are really only a few routines that you need to to use. If you take a look at the sample perl scripts included, which ones they are, and how to use them, should be fairly obvious.

One thing bears further explanation. The sedabl_read and sedabl_write functions take a raw file descriptor. This means that a) you'll need to make sure the filehandle is flushed before passing it to these functions, and b) you'll need to use the fileno() built-in to get the operating system's file descriptor and use that. Results are undefined if you forget to use fileno(), but you'll probably see a "Bad file descriptor" message in $!.

Enjoy!

=cut

---