Re: [PATCH] Documentation fix for perlfunc/shutdown

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:

PP(pp_shutdown)
{
#ifdef HAS_SOCKET
    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 );
    RETURN;

nuts:
    if (ckWARN(WARN_CLOSED))
	report_evil_fh(gv, io, PL_op->op_type);
    SETERRNO(EBADF,SS_IVCHAN);
    RETPUSHUNDEF;
#else
    DIE(aTHX_ PL_no_sock_func, "shutdown");
#endif
}
 


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

• [PATCH] Documentation fix for perlfunc/shutdown by Paul Fenwick
• Re: [PATCH] Documentation fix for perlfunc/shutdown by Nicholas Clark
• Re: [PATCH] Documentation fix for perlfunc/shutdown by Paul Fenwick
• Re: [PATCH][NUDGE] Documentation fix for perlfunc/shutdown by Paul Fenwick
• Re: [PATCH][NUDGE] Documentation fix for perlfunc/shutdown by Rafael Garcia-Suarez