Sindbad~EG File Manager

.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IPC::System::Options 3"
.TH IPC::System::Options 3 "2023-05-24" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IPC::System::Options \- Perl's system(), readpipe()/qx, IPC::Run's run(), start() (with more options)
.SH "VERSION"
.IX Header "VERSION"
This document describes version 0.341 of IPC::System::Options (from Perl distribution IPC-System-Options), released on 2023\-05\-24.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use IPC::System::Options qw(system readpipe run start);
\&
\& # use exactly like system()
\& system(...);
\&
\& # use exactly like readpipe() (a.k.a. qx a.k.a. \`\` a.k.a. the backtick
\& # operator). if you import readpipe, you\*(Aqll override the backtick operator with
\& # this module\*(Aqs version (along with your chosen settings).
\& my $res = readpipe(...);
\& $res = \`...\`;
\&
\& # but these functions accept an optional hash first argument to specify options
\& system({...}, ...);
\& $res = readpipe({...}, ...);
\&
\& # run without shell, even though there is only one argument
\& system({shell=>0}, "ls");
\& system({shell=>0}, "ls \-lR");          # will fail, as there is no \*(Aqls \-lR\*(Aq binary
\& $res = readpipe({shell=>0}, "ls \-lR"); # ditto
\&
\& # force shell, even though there are multiple arguments (arguments will be
\& # quoted and joined together for you, including proper quoting on Win32).
\& system({shell=>1}, "perl", "\-e", "print 123"); # will print 123
\& $res = readpipe({shell=>1}, "perl", "\-e", "print 123");
\&
\& # note that to prevent the quoting mechanism from quoting some special
\& # characters (like ">") you can use scalar references, e.g.:
\& system({shell=>1}, "ls", "\-laR",  ">", "/root/ls\-laR"); # fails, because the arguments are quoted so the command becomes: ls \*(Aq\-laR\*(Aq \*(Aq>\*(Aq \*(Aq/root/ls\-laR\*(Aq
\& system({shell=>1}, "ls", "\-laR", \e">", "/root/ls\-laR"); # works
\&
\& # set LC_ALL/LANGUAGE/LANG environment variable
\& $res = readpipe({lang=>"de_DE.UTF\-8"}, "df");
\&
\& # log using Log::ger, die on failure
\& system({log=>1, die=>1}, "blah", ...);
\&
\& # chdir first before running program (and chdir back afterwards)
\& system({chdir => "/tmp", die => 1}, "some\-program");
.Ve
.PP
Set default options for all calls (prefix each option with dash):
.PP
.Vb 1
\& use IPC::System::Options \*(Aqsystem\*(Aq, \*(Aqreadpipe\*(Aq, \-log=>1, \-die=>1;
.Ve
.PP
\&\f(CW\*(C`run()\*(C'\fR is like \f(CW\*(C`system()\*(C'\fR but uses IPC::Run's \f(CW\*(C`run()\*(C'\fR instead of
\&\f(CW\*(C`system()\*(C'\fR:
.PP
.Vb 1
\& run(\*(Aqls\*(Aq);
\&
\& # also accepts an optional hash first argument. some additional options that
\& # run() accepts: stdin.
\& run({capture_stdout => \e$stdout, capture_stderr => \e$stderr}, \*(Aqls\*(Aq, \*(Aq\-l\*(Aq);
.Ve
.PP
\&\f(CW\*(C`start()\*(C'\fR is like \f(CW\*(C`run()\*(C'\fR but uses IPC::Run's \f(CW\*(C`start()\*(C'\fR instead of
\&\f(CW\*(C`run()\*(C'\fR to run program in the background. The result is a handle (see
IPC::Run for more details) which you can then call \f(CW\*(C`finish()\*(C'\fR, etc on.
.PP
.Vb 3
\& my $h = start(\*(Aqls\*(Aq, \*(Aq\-l\*(Aq);
\& ...
\& $h\->finish;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides replacement (wrapper) for Perl's \f(CW\*(C`system()\*(C'\fR, \f(CW\*(C`readpipe()\*(C'\fR
(qx//, a.k.a. the backtick operator), as well as IPC::Run's \f(CW\*(C`start()\*(C'\fR and
\&\f(CW\*(C`run()\*(C'\fR. The wrappers give you options like forcing/avoiding use of shell (like
what IPC::System::Simple offers you), logging the arguments and/or output
(using Log::ger), temporarily setting environment variables, temporarily
setting working directory, dying on non-zero exit code, capturing (or tee-ing)
output (stdout/stderr) (using Capture::Tiny), and a few others. They are
meant as a convenience so you can just call \f(CW\*(C`system()\*(C'\fR (or the other wrapper
target) instead of doing some additional setup and cleanup yourself.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "system"
.IX Subsection "system"
Usage:
.PP
.Vb 1
\& system([ \e%opts ], @args) => $child_error ($?)
.Ve
.PP
Just like perl's \f(CW\*(C`system()\*(C'\fR except that it accepts an optional hash first
argument to specify options. Currently known options:
.IP "\(bu" 4
shell => bool
.Sp
Can be set to 0 to always avoid invoking the shell. The default is to use the
shell under certain conditions, like perl's \f(CW\*(C`system()\*(C'\fR. But unlike perl's
\&\f(CW\*(C`system()\*(C'\fR, you can force shell usage even though you pass multiple arguments
(in which case, the arguments will be quoted for you, including proper quoting
on Win32).
.IP "\(bu" 4
lang => str
.Sp
Temporarily set locale-related environment variables: \f(CW\*(C`LC_ALL\*(C'\fR (this is the
highest precedence, even higher than the other \f(CW\*(C`LC_*\*(C'\fR variables including
\&\f(CW\*(C`LC_MESSAGES\*(C'\fR), \f(CW\*(C`LANGUAGE\*(C'\fR (this is used in Linux, with precedence higher than
\&\f(CW\*(C`LANG\*(C'\fR but lower than \f(CW\*(C`LC_*\*(C'\fR), and \f(CW\*(C`LANG\*(C'\fR.
.Sp
Of course you can set the environment variables manually (or use the \f(CW\*(C`env\*(C'\fR
option), this option is just for convenience.
.IP "\(bu" 4
env => hashref
.Sp
Temporarily set environment variables.
.IP "\(bu" 4
log => bool
.Sp
If set to true, then will log invocation as well as return/result value. Will
log using Log::ger at the \f(CW\*(C`trace\*(C'\fR level.
.IP "\(bu" 4
fail_log_level => str
.Sp
When a command fail (and logging is enabled), log the failure message at this
level. The default is \f(CW\*(C`error\*(C'\fR which is a sensible default but sometimes you
want to log the failure at different level.
.IP "\(bu" 4
die => bool
.Sp
If set to true, will die on failure.
.IP "\(bu" 4
capture_stdout => scalarref
.Sp
Capture stdout using Capture::Tiny.
.Sp
Cannot be used together with \f(CW\*(C`tee_*\*(C'\fR or \f(CW\*(C`capture_merged\*(C'\fR.
.IP "\(bu" 4
capture_stderr => scalarref
.Sp
Capture stderr using Capture::Tiny.
.Sp
Cannot be used together with \f(CW\*(C`tee_*\*(C'\fR or \f(CW\*(C`capture_merged\*(C'\fR.
.IP "\(bu" 4
capture_merged => scalarref
.Sp
Capture stdout and stderr in a single variable using Capture::Tiny's
\&\f(CW\*(C`capture_merged\*(C'\fR.
.Sp
Cannot be used together with \f(CW\*(C`tee_*\*(C'\fR, \f(CW\*(C`capture_stdout\*(C'\fR, or \f(CW\*(C`capture_stderr\*(C'\fR.
.IP "\(bu" 4
tee_stdout => scalarref
.Sp
Tee stdout using Capture::Tiny.
.Sp
Cannot be used together with \f(CW\*(C`capture_*\*(C'\fR or \f(CW\*(C`tee_merged\*(C'\fR.
.IP "\(bu" 4
tee_stderr => scalarref
.Sp
Capture stderr using Capture::Tiny.
.Sp
Cannot be used together with \f(CW\*(C`capture_*\*(C'\fR or \f(CW\*(C`tee_merged\*(C'\fR.
.IP "\(bu" 4
tee_merged => scalarref
.Sp
Capture stdout and stderr in a single variable using Capture::Tiny's
\&\f(CW\*(C`capture_merged\*(C'\fR.
.Sp
Cannot be used together with \f(CW\*(C`capture_*\*(C'\fR, \f(CW\*(C`tee_stdout\*(C'\fR, or \f(CW\*(C`tee_stderr\*(C'\fR.
.IP "\(bu" 4
chdir => str
.Sp
Attempt to change to specified directory first and change back to the original
directory after the command has been run. This is a convenient option so you can
do this kind of task in a single call:
.Sp
.Vb 6
\& {
\&     my $cwd = getcwd();
\&     chdir $dir or die;
\&     system(...);
\&     chdir $cwd or die;
\& }
.Ve
.Sp
If the attempt to chdir before command execution fails, will die if \f(CW\*(C`die\*(C'\fR
option is set to true. Otherwise, \f(CW$!\fR (\s-1OS\s0 error) will be set to the \f(CW\*(C`chdir()\*(C'\fR
error and to minimize surprise \f(CW$?\fR (child exit code) will also be set to
non-zero value (\-1) even though at this point no child process has been run.
.Sp
If the attempt to chdir back (after command execution) fails, will die if \f(CW\*(C`die\*(C'\fR
option is set to true. Otherwise, \f(CW$!\fR will be set to the \f(CW\*(C`chdir()\*(C'\fR error and
\&\f(CW$?\fR will be set to \-1 only if \f(CW$?\fR is zero. So if the command fails, \f(CW$?\fR
will contain the exit code of the command.
.IP "\(bu" 4
dry_run => bool
.Sp
If set to true, then will only display what would be executed to \s-1STDERR\s0 (or log
at \f(CW\*(C`warn\*(C'\fR level, if \f(CW\*(C`log\*(C'\fR option is true) instead of actually executing the
command.
.Sp
Will set \f(CW$?\fR (child exit code) to 0.
.Sp
An example of how this option can be used:
.Sp
.Vb 1
\& system({ dry_run => $ENV{DRY_RUN} }, ...);
.Ve
.Sp
This will allow you to run script in dry-run mode by setting environment
variable.
.IP "\(bu" 4
exit_code_success_criteria => int|array[int]|Regexp|code
.Sp
Specify which command exit codes are to be marked as success. For example, exit
code 1 for the \fBdiff\fR command does not signify an error; it just means that the
two input files are different. So in this case you can either specify one of:
.Sp
.Vb 3
\& exit_code_success_criteria => [0,1]
\& exit_code_success_criteria => qr/\eA(0|1)\ez/
\& exit_code_success_criteria => sub { $_[0] == 0 || $_[0] == 1 }
.Ve
.Sp
By default, if this option is not specified, non-zero exit codes count as
failure.
.Sp
Currently this only affects logging: when exit code is considered non-success, a
warning log is produced and \f(CW\*(C`readpipe()\*(C'\fR does not log the result.
.SS "readpipe"
.IX Subsection "readpipe"
Usage:
.PP
.Vb 1
\& readpipe([ \e%opts ], @args) => $output
.Ve
.PP
Just like perl's \f(CW\*(C`readpipe()\*(C'\fR (a.k.a. \f(CW\*(C`qx()\*(C'\fR a.k.a. \f(CW\*(C`\`\`\*(C'\fR a.k.a. the backtick
operator) except that it accepts an optional hash first argument to specify
options. And it can accept multiple arguments (in which case, the arguments will
be quoted for you, including proper quoting on Win32).
.PP
Known options:
.IP "\(bu" 4
lang => str
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
env => hash
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
log => bool
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
die => bool
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
capture_stdout => scalarref
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
capture_stderr => scalarref
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
capture_merged => scalarref
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
tee_stdout => scalarref
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
tee_stderr => scalarref
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
tee_merged => scalarref
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
max_log_output => int
.Sp
If set, will limit result length being logged. It's a good idea to set this
(e.g. to 1024) if you expect some command to return large output.
.IP "\(bu" 4
chdir => str
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
dry_run => bool
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
exit_code_success_criteria => int|array[int]|Regexp|code
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.SS "run"
.IX Subsection "run"
Usage:
.PP
.Vb 1
\& run([ \e%opts ], @args) => $is_success
.Ve
.PP
Like \f(CW\*(C`system()\*(C'\fR, but uses IPC::Run's \f(CW\*(C`run()\*(C'\fR. Known options:
.IP "\(bu" 4
lang => str
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
env => hash
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
log => bool
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
die => bool
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
capture_stdout => scalarref|coderef
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
capture_stderr => scalarref|coderef
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
stdin => scalar
.Sp
Supply standard input.
.IP "\(bu" 4
chdir => str
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
dry_run => bool
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.IP "\(bu" 4
exit_code_success_criteria => int|array[int]|Regexp|code
.Sp
See option documentation in \f(CW\*(C`system()\*(C'\fR.
.SS "start"
.IX Subsection "start"
Usage:
.PP
.Vb 1
\& start([ \e%opts ], @args) => $harness
.Ve
.PP
Like \f(CW\*(C`run()\*(C'\fR, but uses IPC::Run's \f(CW\*(C`start()\*(C'\fR. For known options, see
\&\f(CW\*(C`run()\*(C'\fR.
.SH "HOMEPAGE"
.IX Header "HOMEPAGE"
Please visit the project's homepage at <https://metacpan.org/release/IPC\-System\-Options>.
.SH "SOURCE"
.IX Header "SOURCE"
Source repository is at <https://github.com/perlancar/perl\-IPC\-System\-Options>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IPC::System::Simple also provides wrapper for \f(CW\*(C`system()\*(C'\fR and \f(CW\*(C`readpipe()\*(C'\fR
with some additional behavior, although its scope is not as extensive as
IPC::System::Options.
.PP
Proc::Govern similarly provide a run+options function, with a different set
of options, including system load watching, logging output to file, disabling
and screensaver or power management.
.SH "AUTHOR"
.IX Header "AUTHOR"
perlancar <perlancar@cpan.org>
.SH "CONTRIBUTING"
.IX Header "CONTRIBUTING"
To contribute, you can send patches by email/via \s-1RT,\s0 or send pull requests on
GitHub.
.PP
Most of the time, you don't need to build the distribution yourself. You can
simply modify the code, then test via:
.PP
.Vb 1
\& % prove \-l
.Ve
.PP
If you want to build the distribution (e.g. to try to install it locally on your
system), you can install Dist::Zilla,
Dist::Zilla::PluginBundle::Author::PERLANCAR,
Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other
Dist::Zilla\- and/or Pod::Weaver plugins. Any additional steps required beyond
that are considered a bug and can be reported to me.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2023, 2021, 2020, 2019, 2017, 2016, 2015 by perlancar <perlancar@cpan.org>.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=IPC\-System\-Options>
.PP
When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.