.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 "Test2::Harness::Util::IPC 3pm" .TH Test2::Harness::Util::IPC 3pm "2023-03-12" "perl v5.36.0" "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" Test2::Harness::Util::IPC \- Utilities for IPC management. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This package provides low-level \s-1IPC\s0 tools for Test2::Harness. .SH "EXPORTS" .IX Header "EXPORTS" All exports are optional and must be specified at import time. .ie n .IP "$bool = \s-1\fBUSE_P_GROUPS\s0()\fR" 4 .el .IP "\f(CW$bool\fR = \s-1\fBUSE_P_GROUPS\s0()\fR" 4 .IX Item "$bool = USE_P_GROUPS()" This is a shortcut for: .Sp .Vb 2 \& use Config qw/%Config/; \& $Config{\*(Aqd_setpgrp\*(Aq}; .Ve .ie n .IP "swap_io($from, $to)" 4 .el .IP "swap_io($from, \f(CW$to\fR)" 4 .IX Item "swap_io($from, $to)" .PD 0 .ie n .IP "swap_io($from, $to, \e&die)" 4 .el .IP "swap_io($from, \f(CW$to\fR, \e&die)" 4 .IX Item "swap_io($from, $to, &die)" .PD This will close and re-open the file handle designated by \f(CW$from\fR so that it redirects to the handle specified in \f(CW$to\fR. It preserves the file descriptor in the process, and throws an exception if it fails to do so. .Sp .Vb 2 \& swap_io(\e*STDOUT, $fh); \& # STDOUT now points to wherever $fh did, but maintains the file descriptor number \*(Aq2\*(Aq. .Ve .Sp As long as the file descriptor is greater than 0 it will open for writing. If the descriptor is 0 it will open for reading, allowing for a swap of \f(CW\*(C`STDIN\*(C'\fR as well. .Sp Extra effort is made to insure errors go to the real \f(CW\*(C`STDERR\*(C'\fR, specially when trying to swap out \f(CW\*(C`STDERR\*(C'\fR. If you have trouble with this, or do not trust it, you can provide a custom coderef as a third argument, this coderef will be used instead of \f(CW\*(C`die()\*(C'\fR to throw exceptions. .Sp Note that the custom die logic when you do not provide your own bypasses the exception catching mechanism and will exit your program. If this is not desirable then you should provide a custom die subref. .ie n .IP "$pid = run_cmd(command => [...], %params)" 4 .el .IP "\f(CW$pid\fR = run_cmd(command => [...], \f(CW%params\fR)" 4 .IX Item "$pid = run_cmd(command => [...], %params)" This function will run the specified command and return a pid to you. When possible this will be done via \f(CW\*(C`fork()\*(C'\fR and \f(CW\*(C`exec()\*(C'\fR. When that is not possible it uses the \f(CW\*(C`system(1, ...)\*(C'\fR trick to spawn a new process. Some parameters do not work in the second case, and are silently ignored. .Sp Parameters: .RS 4 .ie n .IP "command => [$command, sub { ... }, @args]" 4 .el .IP "command => [$command, sub { ... }, \f(CW@args\fR]" 4 .IX Item "command => [$command, sub { ... }, @args]" .PD 0 .ie n .IP "command => sub { return ($command, @args) }" 4 .el .IP "command => sub { return ($command, \f(CW@args\fR) }" 4 .IX Item "command => sub { return ($command, @args) }" .PD This parameter is required. This should either be an arrayref of arguments for \&\f(CW\*(C`exec()\*(C'\fR, or a coderef that returns a list of arguments for \f(CW\*(C`exec()\*(C'\fR. On systems without fork/exec the arguments will be passed to \&\f(CW\*(C`system(1, $command, @args)\*(C'\fR instead. .Sp If the command arrayref has a coderef in it, the coderef will be run and its return value(s) will be inserted in its place. This replacement happens post-chroot .IP "run_in_parent => [sub { ... }, sub { ... }]" 4 .IX Item "run_in_parent => [sub { ... }, sub { ... }]" An arrayref of callbacks to be run in the parent process immedietly after the child process is started. .IP "run_in_child => [sub { ... }, sub { ... }]" 4 .IX Item "run_in_child => [sub { ... }, sub { ... }]" An arrayref of callbacks to be run in the child process immedietly after fork. This parameter is silently ignored on systems without fork/exec. .ie n .IP "env => { \s-1ENVVAR\s0 => $VAL, ... }" 4 .el .IP "env => { \s-1ENVVAR\s0 => \f(CW$VAL\fR, ... }" 4 .IX Item "env => { ENVVAR => $VAL, ... }" A hashref of custom environment variables to set in the child process. In the fork/exec model this is done post-fork, in the spawn model this is done via local prior to the spawn. .ie n .IP "no_set_pgrp => $bool," 4 .el .IP "no_set_pgrp => \f(CW$bool\fR," 4 .IX Item "no_set_pgrp => $bool," Normall \f(CW\*(C`setpgrp(0,0)\*(C'\fR is called on systems where it is supported. You can use this parameter to override the normal behavior. \fBsetpgrp()\fR is not called in the spawn model, so this parameter is silently ignored there. .IP "chdir => 'path/to/dir'" 4 .IX Item "chdir => 'path/to/dir'" .PD 0 .IP "ch_dir => 'path/to/dir'" 4 .IX Item "ch_dir => 'path/to/dir'" .PD \&\fBchdir()\fR to the specified directory for the new process. In the fork/exec model this is done post-fork in the child. In the spawn model this is done before the spawn, then a second \fBchdir()\fR puts the parent process back to its original dir after the spawn. .ie n .IP "stdout => $handle" 4 .el .IP "stdout => \f(CW$handle\fR" 4 .IX Item "stdout => $handle" .PD 0 .ie n .IP "stderr => $handle" 4 .el .IP "stderr => \f(CW$handle\fR" 4 .IX Item "stderr => $handle" .ie n .IP "stdin => $handle" 4 .el .IP "stdin => \f(CW$handle\fR" 4 .IX Item "stdin => $handle" .PD Thise can be used to provide custom \s-1STDERR, STDOUT,\s0 and \s-1STDIN.\s0 In the fork/exec model these are swapped into place post-fork in the child. In the spawn model the swap occurs pre-spawn, then the old handles are swapped back post-spawn. .RE .RS 4 .RE .SH "SOURCE" .IX Header "SOURCE" The source code repository for Test2\-Harness can be found at \&\fIhttp://github.com/Test\-More/Test2\-Harness/\fR. .SH "MAINTAINERS" .IX Header "MAINTAINERS" .IP "Chad Granum " 4 .IX Item "Chad Granum " .SH "AUTHORS" .IX Header "AUTHORS" .PD 0 .IP "Chad Granum " 4 .IX Item "Chad Granum " .PD .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2020 Chad Granum . .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See \fIhttp://dev.perl.org/licenses/\fR