develooper Front page | perl.perl5.porters | Postings from March 2008

Re: [PATCH] Documentation fix for perlfunc/shutdown

Thread Previous | Thread Next
Nicholas Clark
March 26, 2008 16:56
Re: [PATCH] Documentation fix for perlfunc/shutdown
Message ID:
On Mon, Mar 24, 2008 at 03:13:49PM +1000, Paul Fenwick wrote:
> G'day Everyone,
> perlfunc/shutdown doesn't seem to list shutdown's possible return values, 
> this patch corrects that.  I've inferred return values from testing (my 
> Perl guts reading comprehension is poorer than it should be), so a quick 
> sanity check that my values are correct would be appreciated.
> Cheerio,
> 	Paul

> diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
> index e0b8049..a55c41e 100644
> --- a/pod/perlfunc.pod
> +++ b/pod/perlfunc.pod
> @@ -5097,6 +5097,10 @@ It's also a more insistent form of close because it also
>  disables the file descriptor in any forked copies in other
>  processes.
> +Returns C<undef> if the first argument is not a valid filehandle,
> +C<0> if the filehandle is not a socket or could not be shutdown,
> +and C<1> for success.
> +
>  =item sin EXPR
>  X<sin> X<sine> X<asin> X<arcsine>

I don't know. The code looks like this:

    dVAR; dSP; dTARGET;
    const int how = POPi;
    GV * const gv = (GV*)POPs;
    register IO * const io = GvIOn(gv);

    if (!io || !IoIFP(io))
	goto nuts;

    PUSHi( PerlSock_shutdown(PerlIO_fileno(IoIFP(io)), how) >= 0 );

    if (ckWARN(WARN_CLOSED))
	report_evil_fh(gv, io, PL_op->op_type);
    DIE(aTHX_ PL_no_sock_func, "shutdown");

So yes, the undef return is consistent with your documentation. It might be
better to say something like

    Returns C<1> for success, C<undef> if the first argument is not a valid
    filehandle, or if the C<shutdown> call failed for any reason, such as the
    filehandle is not a socket.

which is closer to describing what goes on, but I'm not sure if it's less
nice than the English you used. (Your order seems nicer, but I didn't want
the complications of the '0' case to be in the middle of the sentence).

Nicholas Clark

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