develooper Front page | perl.perl5.porters | Postings from October 2003

Re: [doc-PATCH] for unpack_str() and question

Thread Next
LAUN Wolfgang
October 5, 2003 23:45
Re: [doc-PATCH] for unpack_str() and question
Message ID:
Note: This clarifies a problem with calling unpack from an XSUB. The
remaining question is: Are there any other API docs that would need
additions so that potential users don't have to wade through the C sources?
Details and patch below.

Tassilo von Parseval wrote on # Fri, 19 Sep 2003 09:54:23 +0200:
> I was in the unfortunate situation to have to use unpack_str() in an
> XSUB. The documentation on that in perlapi.pod appears to be wrong and
> incomplete. It mentions using unpackstr() instead. This symbol cannot be
> resolved (probably it just has to be mentioned in one of the public
> headers).
> After a little bit of trying and realizing that pp_unpack() puts the
> list items directly onto the stack and returns the item-count, it
> appears that a correct usage of this function roughly goes as follows:
> [snip]
>            PUTBACK;
>            num = unpack_str(p, SvEND(pat), str, NULL,
>                             SvEND(string), NULL, 0, flags);
>            SPAGAIN;
>            XSRETURN(num);
> Is this correct? If so, the attached patch against blead should put
> things right and even enable a programmer to use it.
> Tassilo

Hello folks,

sorry for being a little late with my reply (I hope being on vacation is
a good enough excuse :-).

I could not reproduce Tassilo's problem with the unpack API (but see below).
The following XSUB works fine:

bitcount( i )
  int i
    char* pat = "%32b*";
    char* str = (char*)&i;
    STRLEN nb = sizeof( int );
    unpackstring( pat, pat + strlen(pat),
                  str, str + nb, 0 );

If, however, the initial XSUB incantations are run with an older Perl (e.g. 5.6.1), the error message
   "relocation error: ...: undefined symbol unpackstring
is emitted.

I have nothing against an addition in the API docs, but it should be
added to unpackstring ( but definitely not to unpack_str, which has
been made obsolete).

Q: Aren't there other APIs where similar clarifiying remarks are in order?

--- perl/pp_pack.c.old	Sun Oct  5 20:00:01 2003
+++ perl/pp_pack.c	Sun Oct  5 20:06:16 2003
@@ -512,7 +512,9 @@
 =for apidoc unpackstring
-The engine implementing unpack() Perl function.
+The engine implementing unpack() Perl function. C<unpackstring> puts the
+extracted list items on the stack and returns the number of elements.
+Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
 =cut */


Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About