Perl 5.41.5 clarifies which way open3 handles move
The October snapshot updates IPC::Open3's examples to distinguish a newly created pipe from a handle passed through to the child.
A handle argument to open3 can request a new pipe or identify an existing stream to pass to the child. Those are opposite directions of information through the same parameter position. Perl 5.41.5 includes an IPC::Open3 documentation correction that makes the distinction explicit and repairs an example that obscured it.
Richard Leach released the snapshot on 20 October, according to the release history. The snapshot notes mainly list bundled-module updates. Among them is IPC::Open3 1.23, up from 1.22. Reading that module's changes gives this otherwise small release a concrete subject for anyone using Perl to connect programs.
I like Perl's economy for one-off text work. Connecting a transformation to another process can be a natural extension of that job. The economy is only useful if the handle declarations say clearly whether the parent is receiving a new connection or giving the child an existing one.
A parameter can receive a newly created pipe
The module documentation shipped in 5.41.5 describes open3 as starting a command with connections for input, output and errors. The parent's input handle writes to the child. Its output handle reads from the child. An error handle can receive a separate connection for the child's standard error.
In the usual pipe-creating form, the caller supplies a location where the function places the created handle. The argument acts as an output parameter. Thinking of it as simply passing an already open stream can produce the wrong interpretation of the call.
The error-stream argument has an additional distinction. If it is false, or identifies the same descriptor as the output argument, the child's output and error streams use the same handle. The documentation consequently warns that an automatically created lexical cannot supply a distinct error handle in the same way as the other positions. Its example uses gensym to create the separate glob reference.
These rules make argument values consequential beyond their apparent role as handles. A false value in one position requests merging, while an undefined value in another can request handle creation. A correct example needs to show the requested topology of the streams, not merely a plausible list of variable names.
Duplication passes an existing stream to the child
The other form uses strings beginning with <& for input or >& for output. In that case, the module duplicates a handle instead of creating a pipe. The October documentation explicitly describes those strings as input parameters, because the caller is supplying the stream that the child should use.
The comparison with the previous snapshot shows the corrected example. It now opens a named output handle and passes >&OUTFILE to open3. The earlier example passed a lexical output handle directly, which did not clearly express the documented duplication operation.
The correction also explains that the input duplication form contains the name of a bareword handle. That extra detail matters because the parameter is a string interpreted by the module. A reader cannot substitute arbitrary handle notation and assume every spelling requests the same operation.
The implementation reinforces the distinction. It detects the duplication prefix while preparing the handles and skips pipe creation for that case. Otherwise it creates the connection and supplies its parent end through the argument. The documentation change aligns the explanation with that existing branch in the implementation.
Starting a child does not complete its lifecycle
The module returns the child's process ID. It does not wait for the child or reap it after exit. The documentation makes the caller responsible for a waitpid operation when the program needs to collect the process and its status.
This is a separate responsibility from closing a pipe. A connection can reach its end while the parent still needs to account for the process that owned it. The examples show obtaining the exit status after waiting, which makes the lifecycle explicit rather than treating a successful spawn as a completed command.
Failure also has platform distinctions. The module normally throws an exception matching its documented open3 prefix on failure. The documentation separately describes how command-execution failures in the child appear on Windows and OS/2. That distinction prevents an explanation of the common case from promising identical error delivery everywhere.
Multiple pipes require coordinated reading
The module's existing warnings about blocking remain relevant after the example correction. Reading one child stream while ignoring the other can leave the processes waiting on each other. Its documentation recommends readiness handling with select or IO::Select and notes the corresponding use of sysread.
A child that reads all its input before producing output has a different communication pattern from a program that processes one line at a time. The parent cannot assume the latter merely because its own loop writes and reads one line. The child controls its buffering and consumption behaviour.
I regard the corrected example as useful maintenance because examples often become the starting point for such loops. The October update does not claim to redesign process management. It gives the reader a more accurate distinction between creating a connection and passing an existing stream, which is necessary before reasoning about the resulting process interaction.