Mark do_open(), do_openn() as internal, not public

[khwilliamson]

These undocumented functions have exactly 0 uses on CPAN.

do_open() is mentioned in 7 distributions. In all cases it is to #undef the macro name because it was polluting the distro's name space which has its own function named do_open().

• This set of changes does not require a perldelta entry.

[tonycoz]

do_open() is used by the standard typemap, some CPAN modules use do_openn() File-Map, mod_perl, Linux-CDROM though I don't know how current any of those are.

[khwilliamson]

cpan grep shows no uses of do_openn()

https://grep.metacpan.org/search?q=do_openn&qft=&qd=&qifl=ppport.h

And yet it does get called, as you said, in File::Map
https://metacpan.org/release/LEONT/File-Map-0.71/source/lib/File/Map.xs

Am I doing something wrong, or is metacpan search buggy?

[Leont]

Am I doing something wrong, or is metacpan search buggy?

If you select *.xs, *.c as the file extensions, four dists will show up: https://grep.metacpan.org/search?q=do_openn&qft=*.xs%2C+*.c&qd=&qifl=

[khwilliamson]

That sounds like a bug. I want to do an unrestricted search, and yet it doesn't find it.

[tonycoz]

I have a local (bare) clone of https://github.com/metacpan/metacpan-cpan-extracted.git and I git grep that instead of using grep.metacpan.org (it's a lot faster, but 4.4GB disk space).

[Leont]

That sounds like a bug. I want to do an unrestricted search, and yet it doesn't find it.

I can't reproduce it anymore, but I did see it right when you posted. I guess it was just glitching or something? I've seen some other weird results today as well.

[khwilliamson]

I have been getting randomly wrong results with the search, so will open a ticket against that.

[khwilliamson]

It turns out that do_open is marked as binary-compatibility only, so, presuming that is correct, there is no need to mark that as internal.

And do_open6 and 'do_open_raw` are marked as experimental. Should that be removed from one or both of them?

[tonycoz]

And do_open6 and 'do_open_raw` are marked as experimental. Should that be removed from one or both of them?

They aren't API, so it doesn't matter if they're experimental.

Maybe regen should complain if an unexported (or hidden) function is experimental, I don't think it adds any meaning - we're free to change unexported functions anyway.

The other side is maybe they should be API, they'd be less confusing to use than do_openn().

do_open_raw() last changed it's signature in 2017 and do_open6() in 2014, so if they are made API I think they could be non-experimental.

[tonycoz]

These undocumented functions have exactly 0 uses on CPAN.

do_openn:

https://metacpan.org/release/LEONT/File-Map-0.71/source/lib/File/Map.xs#L457

https://metacpan.org/release/VPARSEVAL/Linux-CDROM-0.02/source/CDROM.xs#L201

https://metacpan.org/release/GFUJI/Ruby-0.07/source/perlio.c#L370

(2 of these are ancient)

do_open: (not dists that just #undef do_open)

https://metacpan.org/release/MLEHMANN/IO-AIO-4.81/source/AIO.xs#L567

https://metacpan.org/release/TODDR/IO-1.55/source/IO.xs#L244 (we maintain this, but it's still on cpan)

(there's more)

several modules use it in their typemap, and it is used in the standard typemap

perl5/lib/ExtUtils/typemap

Lines 425 to 477 in 148136c

	T_STDIO
	{
	GV *gv = (GV *)sv_newmortal();
	PerlIO *fp = PerlIO_importFILE($var,0);
	gv_init_pvn(gv, gv_stashpvs("$Package",1),"__ANONIO__",10,0);
	if ( fp && do_open(gv, "+<&", 3, FALSE, 0, 0, fp) ) {
	SV *rv = newRV_inc((SV*)gv);
	rv = sv_bless(rv, GvSTASH(gv));
	${"$var" eq "RETVAL" ? \"$arg = sv_2mortal(rv);"
	: \"sv_setsv($arg, rv);\n\t\tSvREFCNT_dec_NN(rv);"}
	}${"$var" ne "RETVAL" ? \"
	else
	sv_setsv($arg, &PL_sv_undef);\n" : \""}
	}
	T_IN
	{
	GV *gv = (GV *)sv_newmortal();
	gv_init_pvn(gv, gv_stashpvs("$Package",1),"__ANONIO__",10,0);
	if ( do_open(gv, "<&", 2, FALSE, 0, 0, $var) ) {
	SV *rv = newRV_inc((SV*)gv);
	rv = sv_bless(rv, GvSTASH(gv));
	${"$var" eq "RETVAL" ? \"$arg = sv_2mortal(rv);"
	: \"sv_setsv($arg, rv);\n\t\tSvREFCNT_dec_NN(rv);"}
	}${"$var" ne "RETVAL" ? \"
	else
	sv_setsv($arg, &PL_sv_undef);\n" : \""}
	}
	T_INOUT
	{
	GV *gv = (GV *)sv_newmortal();
	gv_init_pvn(gv, gv_stashpvs("$Package",1),"__ANONIO__",10,0);
	if ( do_open(gv, "+<&", 3, FALSE, 0, 0, $var) ) {
	SV *rv = newRV_inc((SV*)gv);
	rv = sv_bless(rv, GvSTASH(gv));
	${"$var" eq "RETVAL" ? \"$arg = sv_2mortal(rv);"
	: \"sv_setsv($arg, rv);\n\t\tSvREFCNT_dec_NN(rv);"}
	}${"$var" ne "RETVAL" ? \"
	else
	sv_setsv($arg, &PL_sv_undef);\n" : \""}
	}
	T_OUT
	{
	GV *gv = (GV *)sv_newmortal();
	gv_init_pvn(gv, gv_stashpvs("$Package",1),"__ANONIO__",10,0);
	if ( do_open(gv, "+>&", 3, FALSE, 0, 0, $var) ) {
	SV *rv = newRV_inc((SV*)gv);
	rv = sv_bless(rv, GvSTASH(gv));
	${"$var" eq "RETVAL" ? \"$arg = sv_2mortal(rv);"
	: \"sv_setsv($arg, rv);\n\t\tSvREFCNT_dec_NN(rv);"}
	}${"$var" ne "RETVAL" ? \"
	else
	sv_setsv($arg, &PL_sv_undef);\n" : \""}
	}

do_open() is mentioned in 7 distributions. In all cases it is to #undef
the macro name because it was polluting the distro's name space which
has its own function named do_open().

SWIG adds these to avoid conflicts with C++ code from what I can see.

Others I looked at are specifically C++ XS modules, which undef them for the reasons from #23459.