/ 
Sys-Cmd-v0.986.0
River stage one • 2 direct dependents • 2 total dependents
/ Sys::Cmd::Process

NAME

Sys::Cmd::Process - spawn and interact with a process

VERSION

v0.986.0 (2025-12-04)

SYNOPSIS

use Sys::Cmd::Process;

my $proc = Sys::Cmd::Process->new(
    cmd   => [ '/usr/bin/cat', '--number' ],
    dir   => '/',
    input => "x\ny\nz\n",
);

while ( my $line = $proc->stdout->getline ) {
    print $line;
}

my @errors = $proc->stderr->getlines;
$proc->wait_child();    # Cleanup

# read process termination information
$proc->exit();          # exit status
$proc->signal();        # signal
$proc->core();          # core dumped? (boolean)

DESCRIPTION

Sys::Cmd::Process is a wrapper around Proc::FastSpawn for creating and interacting with system commands. It provides, in the author's opinion, a more efficient and powerful interface than Perl's built-in "system", "fork" and "exec" functions.

Most users will probably prefer to start Sys::Cmd::Process objects through the utility functions exported by Sys::Cmd.

CONSTRUCTOR

The new() constructor takes the following arguments (key => default), either as a list or in a single HASH reference:

cmd

An ARRAY reference where the first element contains:

  • The path to an executable which will be executed by Proc::FastSpawn with the remaining elements; or

  • A subroutine reference which will be run after forking a new process, passed the remaining elements.

dir => $PWD

The working directory to run in.

encoding => $Encode::Locale::ENCODING_LOCALE

A string value identifying the encoding that applies to input/output file-handles, command arguments, and environment variables. Defaults to the 'locale' alias from Encode::Locale.

env

A hashref containing key/values to be added to the current environment at run-time. If a key has an undefined value then the key is removed from the environment altogether.

input

A scalar (string) or ARRAY reference containing strings, which are fed to the command via its standard input, which is then closed. An empty value ('') or empty list will close the command's standard input without printing. An undefined value (the default) leaves the handle open.

Some commands close their standard input on startup, which causes a SIGPIPE when trying to write to it, for which Sys::Cmd::Process will warn.

on_exit

A subref to be called at the time that process termination is detected.

ATTRIBUTES / METHODS

cmdline() -> @list | $scalar

In array context returns a list of the command and its arguments. In scalar context returns a string of the command and its arguments joined together by spaces.

pid() -> $int

The command's process ID.

stdin() -> IO::Handle

The command's STDIN file handle, based on IO::Handle so you can call print() etc methods on it. Autoflush is automatically enabled on this handle.

stdout() -> IO::Handle

The command's STDOUT file handle, based on IO::Handle so you can call getline() etc methods on it.

stderr() -> IO::Handle

The command's STDERR file handle, based on IO::Handle so you can call getline() etc methods on it.

close()

Close all filehandles to the child process.

This is called automatically when the Sys::Cmd::Process object is destroyed if it has not already run.

Annoyingly, this means that in the following example $fh will be closed when you tried to use it:

my $fh = Sys::Cmd::Process->new( %args )->stdout;

So you have to keep track of the Sys::Cmd::Process object manually.

wait_child() -> $exit_value

Wait for the child to exit using waitpid, collect the exit status and return it.

This is called automatically when the Sys::Cmd::Process object is destroyed if it has not already run.

After wait_child has been called the following are also valid:

core() -> $boolean

A boolean indicating the process core was dumped.

exit() -> $exit

The command's exit value (already shifted by 8; see "perldoc -f system for details").

signal() -> $signum

The signal number (if any) that terminated the command (already bitwise-added with 127; see "perldoc -f system" for details).

LOGGING

Log::Any is used to log process start/end events at the "info" level.

ALTERNATIVES

AnyEvent::Run, AnyEvent::Util, Argv, Capture::Tiny, Child, Forks::Super, IO::Pipe, IPC::Capture, IPC::Cmd, IPC::Command::Multiplex, IPC::Exe, IPC::Open3, IPC::Open3::Simple, IPC::Run, IPC::Run3, IPC::RunSession::Simple, IPC::ShellCmd, IPC::System::Simple, POE::Pipe::TwoWay, Proc::Background, Proc::Fork, Proc::FastSpawn, Spawn::Safe, System::Command

SUPPORT

This distribution is managed via github:

https://github.com/mlawren/p5-Sys-Cmd

This distribution follows the semantic versioning model:

http://semver.org/

Code is tidied up on Git commit using githook-perltidy:

http://github.com/mlawren/githook-perltidy

AUTHOR

Mark Lawrence <mark@rekudos.net>, based heavily on Git::Repository::Command by Philippe Bruhat (BooK).

COPYRIGHT AND LICENSE

Copyright 2011-2025 Mark Lawrence <mark@rekudos.net>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.