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

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:

long
bitcount( i )
  int i
  PROTOTYPE: $
  PREINIT:
    char* pat = "%32b*";
    char* str = (char*)&i;
    STRLEN nb = sizeof( int );
  PPCODE:
    PUTBACK;
    unpackstring( pat, pat + strlen(pat),
                  str, str + nb, 0 );
    SPAGAIN;

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 */

Regards
Wolfgang

• Re: [doc-PATCH] for unpack_str() and question by LAUN Wolfgang
• Re: [doc-PATCH] for unpack_str() and question by Rafael Garcia-Suarez