Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IPC::Open3(3)	       Perl Programmers	Reference Guide		 IPC::Open3(3)

NAME
       IPC::Open3 - open a process for reading,	writing, and error handling
       using open3()

SYNOPSIS
	   use Symbol 'gensym';	# vivify a separate handle for STDERR
	   my $pid = open3(my $chld_in,	my $chld_out, my $chld_err = gensym,
			   'some', 'cmd', 'and', 'args');
	   # or	pass the command through the shell
	   my $pid = open3(my $chld_in,	my $chld_out, my $chld_err = gensym,
			   'some cmd and args');

	   # read from parent STDIN
	   # send STDOUT and STDERR to already open handle
	   open	my $outfile, '>>', 'output.txt'	or die "open failed: $!";
	   my $pid = open3('<&STDIN', $outfile,	undef,
			   'some', 'cmd', 'and', 'args');

	   # write to parent STDOUT and	STDERR
	   my $pid = open3(my $chld_in,	'>&STDOUT', '>&STDERR',
			   'some', 'cmd', 'and', 'args');

	   # reap zombie and retrieve exit status
	   waitpid( $pid, 0 );
	   my $child_exit_status = $? >> 8;

DESCRIPTION
       Extremely similar to open2(), open3() spawns the	given command and
       connects	$chld_out for reading from the child, $chld_in for writing to
       the child, and $chld_err	for errors.  If	$chld_err is false, or the
       same file descriptor as $chld_out, then STDOUT and STDERR of the	child
       are on the same filehandle.  This means that an autovivified lexical
       cannot be used for the STDERR filehandle, but gensym from Symbol	can be
       used to vivify a	new glob reference, see	"SYNOPSIS".  The $chld_in will
       have autoflush turned on.

       If $chld_in begins with "<&", then $chld_in will	be closed in the
       parent, and the child will read from it directly.  If $chld_out or
       $chld_err begins	with ">&", then	the child will send output directly to
       that filehandle.	 In both cases,	there will be a	dup(2) instead of a
       pipe(2) made.

       If either reader	or writer is the empty string or undefined, this will
       be replaced by an autogenerated filehandle.  If so, you must pass a
       valid lvalue in the parameter slot so it	can be overwritten in the
       caller, or an exception will be raised.

       The filehandles may also	be integers, in	which case they	are understood
       as file descriptors.

       open3() returns the process ID of the child process.  It	doesn't	return
       on failure: it just raises an exception matching	"/^open3:/".  However,
       "exec" failures in the child (such as no	such file or permission
       denied),	are just reported to $chld_err under Windows and OS/2, as it
       is not possible to trap them.

       If the child process dies for any reason, the next write	to $chld_in is
       likely to generate a SIGPIPE in the parent, which is fatal by default.
       So you may wish to handle this signal.

       Note if you specify "-" as the command, in an analogous fashion to
       "open(my	$fh, "-|")" the	child process will just	be the forked Perl
       process rather than an external command.	 This feature isn't yet
       supported on Win32 platforms.

       open3() does not	wait for and reap the child process after it exits.
       Except for short	programs where it's acceptable to let the operating
       system take care	of this, you need to do	this yourself.	This is
       normally	as simple as calling "waitpid $pid, 0" when you're done	with
       the process.  Failing to	do this	can result in an accumulation of
       defunct or "zombie" processes.  See "waitpid" in	perlfunc for more
       information.

       If you try to read from the child's stdout writer and their stderr
       writer, you'll have problems with blocking, which means you'll want to
       use select() or IO::Select, which means you'd best use sysread()
       instead of readline() for normal	stuff.

       This is very dangerous, as you may block	forever.  It assumes it's
       going to	talk to	something like bc(1), both writing to it and reading
       from it.	 This is presumably safe because you "know" that commands like
       bc(1) will read a line at a time	and output a line at a time.  Programs
       like sort(1) that read their entire input stream	first, however,	are
       quite apt to cause deadlock.

       The big problem with this approach is that if you don't have control
       over source code	being run in the child process,	you can't control what
       it does with pipe buffering.  Thus you can't just open a	pipe to	"cat
       -v" and continually read	and write a line from it.

See Also
       IPC::Open2
	   Like	Open3 but without STDERR capture.

       IPC::Run
	   This	is a CPAN module that has better error handling	and more
	   facilities than Open3.

WARNING
       The order of arguments differs from that	of open2().

perl v5.32.0			  2020-06-14			 IPC::Open3(3)

NAME | SYNOPSIS | DESCRIPTION | See Also | WARNING

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IPC::Open3&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help