Things that can usually be used as a file handle:

• A reference to an IO object (e.g. *STDOUT{IO}).
• A glob containing a reference to an IO object (e.g. *STDOUT).
• A reference to a glob containing a reference to an IO object (e.g. \*STDOUT).
• A string naming a glob containing a reference to an IO object (e.g. "STDOUT").

I would expect functions (named operators) to accept all of these. Subs may be more picky. In particular, subs don't normally support the last one.

Language constructs (syntax) that can be usually be used to provide a file handle to a function (named operator):

• A bareword naming a glob (e.g. STDOUT)
• An expression evaluated in scalar context that returns something that can be used as a file handle.

say, print and printf are notable exceptions. They require one of the following:

• A bareword naming a glob (e.g. STDOUT)
• A simple scalar that contains something that can be used as a file handle (e.g. $fh).
• A block that evaluates to something that can be used as a file handle (e.g. { $fhs{$id} }).

A bareword may be provided to subs using the «*» prototype (passing the bareword as a string).

Update: What can be used as a handle vs what syntax can be used to provide it was poorly distinguished originally.

Maybe some historical background is helpful.

IIRC were lexical filehandles (with private variables and strict) only introduced with Perl5 (not even the first versions)

They are held in one of the 6 slots of a typeglob and were referenced by a uppercase bare word like "FH" named like the glob.

So writing FH meant using *FH{IO} like calling a sub "func()" meant using *func{CODE}->(). °

In order to be able to pass a filehandle as argument to a sub, you had to write *FH.

With Perl 5 came the need for lexical my $fh and avoiding typeglobs altogether while staying backwards compatible.

Now that's how the mess with alternative syntax started, and the docs retain a lot of old wording.

Ikegami already listed various different possibilities to denote a filehandle.

DISCLAIMER:

That's what I understood in the last 10 years lurking here in the monastery, I never coded Perl 4, so some details may be wrong.

°) I think even this hash-like syntax to address slots in a glob didn't exist back then...

Thank you for answers, ikegami and LanX, I understand the situation is pre-history heritage. Just curious, how it came that only open, opendir, print, printf actively object against "symbolic references" under use strict, in these Modern Perl times :). Even if it's too low priority to fix code, maybe stream-lining documentation would be not too much work -- now, where it's clearly stated strings are OK as indirection mechanism, the tone seems neutral or passively-encouraging :). Otherwise, to add to confusion, some built-ins (-X, etc.) accept both filehandles and strings (scalars/expressions), but here strings are filenames. Further curiosity, why all other /.*dir/ built-ins didn't possess indirection ability, in pre-history.

I can't tell much about implementation or API, cause it's very complicated.

You might want to discuss this on P5P.

Otherwise ... in order to have deeper insight and better feedback here, could you please provide a list of hands on examples of what you see and what you want?

> Even if it's too low priority to fix code, maybe stream-lining documentation would be not too much work

Well I think you are always welcome to provide patches to perldoc.

Cheers Rolf
_{(addicted to the Perl Programming Language :)
Wikisyntax for the Monastery}