NAME

Sys::Cmd::Process - process interaction object for Sys::Cmd

VERSION

v0.986.1 (2025-12-09)

SYNOPSIS

    use Sys::Cmd qw[spawn];

    my $proc = spawn(
        '/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

    # Get loud if necessary
    if (my $err = $proc->abnormal) {
        die $err;
    }

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

DESCRIPTION

The Sys::Cmd::Process class is used by Sys::Cmd to represent a running process. It holds Input/Output file handles and a few methods for waiting on the process and obtaining exit information.

This class is not user-instantiated; A process object is only created by Sys::Cmd and passed along. It comes with the following read-only attributes:

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.

When no more interaction with the process is required, the following methods are used for cleanup:

close()

Close all filehandles to the child process.

wait_child()

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

After wait_child has been called the following attributes are also valid:

core() -> 0|1

A boolean indicating if the process core was dumped.

exit() -> $exit

The command's exit value.

signal() -> $signum

The signal number (if any) that terminated the command.

abnormal() -> $str | ''

An error string which is only generated when the process was killed by a signal or had a non-zero exit value.

AUTHOR

Mark Lawrence <mark@rekudos.net>

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.