[doc] perl5sub lies in it's throat ( wrong example for mysyswrite)

[PopeNobody]

Where

perldoc perlsub / man perlsub.

Description

       Because the intent of this feature is primarily to let you define
       subroutines that work like built-in functions, here are prototypes for
       some other functions that parse almost exactly like the corresponding
       built-in.

	   Declared as		   Called as

	   sub mylink ($$)	   mylink $old, $new
	   sub myvec ($$$)	   myvec $var, $offset, 1
	   sub myindex ($$;$)	   myindex &getstring, "substr"
	   sub mysyswrite ($$$;$)  mysyswrite $buf, 0, length($buf) - $off, $off
	   sub myreverse (@)	   myreverse $x, $y, $z
	   sub myjoin ($@)	   myjoin ":", $x, $y, $z
	   sub mypop (\@)	   mypop @array
	   sub mysplice (\@$$@)	   mysplice @array, 0, 2, @pushme
	   sub mykeys (\[%@])	   mykeys $hashref->%*
	   sub myopen (*;$)	   myopen HANDLE, $name
	   sub mypipe (**)	   mypipe READHANDLE, WRITEHANDLE
	   sub mygrep (&@)	   mygrep { /foo/ } $x, $y, $z
	   sub myrand (;$)	   myrand 42
	   sub mytime ()	   mytime

This must be from a very old version where syswrite could only write to STDOUT ... it takes a filehandle now.

And for me, it happily accepts two args ... fh and $buf.

Gemini backs the page up, saying that it does not need the glob prototype, because the file handle is presumably already declared. He is probably righht, but if it was opened in another module, I would expect weeping and wailing if you didn't give it *STDOUT.

Also, myopen is not entirely like open, but I seem to recall reading elsewhere that open can't really be emulated by mere mortals. but you can do open(my $pipe,"-|",qw( echo this is a command )); myopen can't handle that.

[Grinnz]

I don't see anything incorrect about the example, except that the third argument is also optional. The $ prototype accepts any form you would pass a filehandle, such as $fh, *STDOUT, $stuff->{fh}, \*FH, etc. It also would accept a bare STDOUT but strict 'subs' does not since it only provide exceptions for known functions. Regardless, these are all examples and not promised to parse exactly the same, as sometimes this is impossible with prototypes. But they could be updated where the prototype function returns something different, as in this case prototype \&CORE::syswrite returns *$;$$.

[PopeNobody]

It's not really the prototype ... but the example passes $buf as it's first arg.

[Grinnz]

Oh yes, the "Example arguments" make no sense.

[PopeNobody]

I actually thought it was worse than it was, but it would be worth fixing.