.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 "Sysadm::Install 3pm"
.TH Sysadm::Install 3pm "2022-06-17" "perl v5.34.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"
Sysadm::Install \- Typical installation tasks for system administrators
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Sysadm::Install qw(:all);
\&
\&  my $INST_DIR = \*(Aq/home/me/install/\*(Aq;
\&
\&  cd($INST_DIR);
\&  cp("/deliver/someproj.tgz", ".");
\&  untar("someproj.tgz");
\&  cd("someproj");
\&
\&     # Write out ...
\&  blurt("Builder: Mike\enDate: Today\en", "build.dat");
\&
\&     # Slurp back in ...
\&  my $data = slurp("build.dat");
\&
\&     # or edit in place ...
\&  pie(sub { s/Today/scalar localtime()/ge; $_; }, "build.dat");
\&
\&  make("test install");
\&
\&     # run a cmd and tap into stdout and stderr
\&  my($stdout, $stderr, $exit_code) = tap("ls", "\-R");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Have you ever wished for your installation shell scripts to run
reproducibly, without much programming fuzz, and even with optional
logging enabled? Then give up shell programming, use Perl.
.PP
\&\f(CW\*(C`Sysadm::Install\*(C'\fR executes shell-like commands performing typical
installation tasks: Copying files, extracting tarballs, calling \f(CW\*(C`make\*(C'\fR.
It has a \f(CW\*(C`fail once and die\*(C'\fR policy, meticulously checking the result
of every operation and calling \f(CW\*(C`die()\*(C'\fR immediately if anything fails.
.PP
\&\f(CW\*(C`Sysadm::Install\*(C'\fR also supports a \fIdry_run\fR mode, in which it 
logs everything, but suppresses any write actions. Dry run mode
is enabled by calling \f(CWSysadm::Install::dry_run(1)\fR. To switch
back to normal, call \f(CWSysadm::Install::dry_run(0)\fR.
.PP
As of version 0.17, \f(CW\*(C`Sysadm::Install\*(C'\fR supports a \fIconfirm\fR mode,
in which it interactively asks the user before running any of its
functions (just like \f(CW\*(C`rm \-i\*(C'\fR). \fIconfirm\fR mode is enabled by calling 
\&\f(CWSysadm::Install::confirm(1)\fR. To switch
back to normal, call \f(CWSysadm::Install::confirm(0)\fR.
.PP
\&\f(CW\*(C`Sysadm::Install\*(C'\fR is fully Log4perl\-enabled. To start logging, just
initialize \f(CW\*(C`Log::Log4perl\*(C'\fR. \f(CW\*(C`Sysadm::Install\*(C'\fR acts as a wrapper class,
meaning that file names and line numbers are reported from the calling
program's point of view.
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
.ie n .IP """cp($source, $target)""" 4
.el .IP "\f(CWcp($source, $target)\fR" 4
.IX Item "cp($source, $target)"
Copy a file from \f(CW$source\fR to \f(CW$target\fR. \f(CW\*(C`target\*(C'\fR can be a directory.
Note that \f(CW\*(C`cp\*(C'\fR doesn't copy file permissions. If you want the target
file to reflect the source file's user rights, use \f(CW\*(C`perm_cp()\*(C'\fR
shown below.
.ie n .IP """mv($source, $target)""" 4
.el .IP "\f(CWmv($source, $target)\fR" 4
.IX Item "mv($source, $target)"
Move a file from \f(CW$source\fR to \f(CW$target\fR. \f(CW\*(C`target\*(C'\fR can be a directory.
.ie n .IP """download($url)""" 4
.el .IP "\f(CWdownload($url)\fR" 4
.IX Item "download($url)"
Download a file specified by \f(CW$url\fR and store it under the
name returned by \f(CW\*(C`basename($url)\*(C'\fR.
.ie n .IP """untar($tarball)""" 4
.el .IP "\f(CWuntar($tarball)\fR" 4
.IX Item "untar($tarball)"
Untar the tarball in \f(CW$tarball\fR, which typically adheres to the
\&\f(CW\*(C`someproject\-X.XX.tgz\*(C'\fR convention. 
But regardless of whether the 
archive actually contains a top directory \f(CW\*(C`someproject\-X.XX\*(C'\fR,
this function will behave if it had one. If it doesn't have one,
a new directory is created before the unpacking takes place. Unpacks
the tarball into the current directory, no matter where the tarfile
is located. 
Please note that if you're
using a compressed tarball (.tar.gz or .tgz), you'll need
IO::Zlib installed.
.ie n .IP """untar_in($tar_file, $dir)""" 4
.el .IP "\f(CWuntar_in($tar_file, $dir)\fR" 4
.IX Item "untar_in($tar_file, $dir)"
Untar the tarball in \f(CW$tgz_file\fR in directory \f(CW$dir\fR. Create
\&\f(CW$dir\fR if it doesn't exist yet.
.ie n .IP """pick($prompt, $options, $default, $opts)""" 4
.el .IP "\f(CWpick($prompt, $options, $default, $opts)\fR" 4
.IX Item "pick($prompt, $options, $default, $opts)"
Ask the user to pick an item from a displayed list. \f(CW$prompt\fR
is the text displayed, \f(CW$options\fR is a referenc to an array of
choices, and \f(CW$default\fR is the number (starting from 1, not 0)
of the default item. For example,
.Sp
.Vb 1
\&    pick("Pick a fruit", ["apple", "pear", "pineapple"], 3);
.Ve
.Sp
will display the following:
.Sp
.Vb 4
\&    [1] apple
\&    [2] pear
\&    [3] pineapple
\&    Pick a fruit [3]>
.Ve
.Sp
If the user just hits \fIEnter\fR, \*(L"pineapple\*(R" (the default value) will
be returned. Note that 3 marks the 3rd element of the list, and is
\&\fInot\fR an index value into the array.
.Sp
If the user enters \f(CW1\fR, \f(CW2\fR or \f(CW3\fR, the corresponding text string
(\f(CW"apple"\fR, \f(CW"pear"\fR, \f(CW"pineapple"\fR will be returned by
\&\f(CW\*(C`pick()\*(C'\fR.
.Sp
If the optional \f(CW$opts\fR hash has \f(CW\*(C`{ tty => 1 }\*(C'\fR set, then 
the user response will be expected from the console, not \s-1STDIN.\s0
.ie n .IP """ask($prompt, $default, $opts)""" 4
.el .IP "\f(CWask($prompt, $default, $opts)\fR" 4
.IX Item "ask($prompt, $default, $opts)"
Ask the user to either hit \fIEnter\fR and select the displayed default
or to type in another string.
.Sp
If the optional \f(CW$opts\fR hash has \f(CW\*(C`{ tty => 1 }\*(C'\fR set, then 
the user response will be expected from the console, not \s-1STDIN.\s0
.ie n .IP """mkd($dir)""" 4
.el .IP "\f(CWmkd($dir)\fR" 4
.IX Item "mkd($dir)"
Create a directory of arbitrary depth, just like \f(CW\*(C`File::Path::mkpath\*(C'\fR.
.ie n .IP """rmf($dir)""" 4
.el .IP "\f(CWrmf($dir)\fR" 4
.IX Item "rmf($dir)"
Delete a directory and all of its descendents, just like \f(CW\*(C`rm \-rf\*(C'\fR
in the shell.
.ie n .IP """cd($dir)""" 4
.el .IP "\f(CWcd($dir)\fR" 4
.IX Item "cd($dir)"
chdir to the given directory. If you don't want to have \fBcd()\fR modify
the internal directory stack (used for subsequent \fBcdback()\fR calls), 
set the stack_update parameter to a false value:
.Sp
.Vb 1
\&    cd($dir, {stack_update => 0});
.Ve
.ie n .IP """cdback()""" 4
.el .IP "\f(CWcdback()\fR" 4
.IX Item "cdback()"
chdir back to the last directory before a previous \f(CW\*(C`cd\*(C'\fR. If the
option \f(CW\*(C`reset\*(C'\fR is set, it goes all the way back to the beginning of the
directory stack, i.e. no matter how many \fBcd()\fR calls were made in between,
it'll go back to the original directory:
.Sp
.Vb 2
\&      # go all the way back
\&    cdback( { reset => 1 } );
.Ve
.ie n .IP """make()""" 4
.el .IP "\f(CWmake()\fR" 4
.IX Item "make()"
Call \f(CW\*(C`make\*(C'\fR in the shell.
.ie n .IP """pie($coderef, $filename, ...)""" 4
.el .IP "\f(CWpie($coderef, $filename, ...)\fR" 4
.IX Item "pie($coderef, $filename, ...)"
Simulate \*(L"perl \-pie 'do something' file\*(R". Edits files in-place. Expects
a reference to a subroutine as its first argument. It will read out the
file \f(CW$filename\fR line by line and calls the subroutine setting
a localized \f(CW$_\fR to the current line. The return value of the subroutine
will replace the previous value of the line.
.Sp
Example:
.Sp
.Vb 2
\&    # Replace all \*(Aqfoo\*(Aqs by \*(Aqbar\*(Aq in test.dat
\&        pie(sub { s/foo/bar/g; $_; }, "test.dat");
.Ve
.Sp
Works with one or more file names.
.Sp
If the files are known to contain \s-1UTF\-8\s0 encoded data, and you want it
to be read/written as a Unicode strings, use the \f(CW\*(C`utf8\*(C'\fR option:
.Sp
.Vb 1
\&    pie(sub { s/foo/bar/g; $_; }, "test.dat", { utf8 => 1 });
.Ve
.ie n .IP """plough($coderef, $filename, ...)""" 4
.el .IP "\f(CWplough($coderef, $filename, ...)\fR" 4
.IX Item "plough($coderef, $filename, ...)"
Simulate \*(L"perl \-ne 'do something' file\*(R". Iterates over all lines
of all input files and calls the subroutine provided as the first argument.
.Sp
Example:
.Sp
.Vb 2
\&    # Print all lines containing \*(Aqfoobar\*(Aq
\&        plough(sub { print if /foobar/ }, "test.dat");
.Ve
.Sp
Works with one or more file names.
.Sp
If the files are known to contain \s-1UTF\-8\s0 encoded data, and you want it
to be read into Unicode strings, use the \f(CW\*(C`utf8\*(C'\fR option:
.Sp
.Vb 1
\&    plough(sub { print if /foobar/ }, "test.dat", { utf8 => 1 });
.Ve
.ie n .IP """my $data = slurp($file, $options)""" 4
.el .IP "\f(CWmy $data = slurp($file, $options)\fR" 4
.IX Item "my $data = slurp($file, $options)"
Slurps in the file and returns a scalar with the file's content. If
called without argument, data is slurped from \s-1STDIN\s0 or from any files
provided on the command line (like <> operates).
.Sp
If the file is known to contain \s-1UTF\-8\s0 encoded data and you want to
read it in as a Unicode string, use the \f(CW\*(C`utf8\*(C'\fR option:
.Sp
.Vb 1
\&    my $unicode_string = slurp( $file, {utf8 => 1} );
.Ve
.ie n .IP """blurt($data, $file, $options)""" 4
.el .IP "\f(CWblurt($data, $file, $options)\fR" 4
.IX Item "blurt($data, $file, $options)"
Opens a new file, prints the data in \f(CW$data\fR to it and closes the file.  If
\&\f(CW\*(C`$options\->{append}\*(C'\fR is set to a true value, data will be appended to the
file. Default is false, existing files will be overwritten.
.Sp
If the string is a Unicode string, use the \f(CW\*(C`utf8\*(C'\fR option:
.Sp
.Vb 1
\&    blurt( $unicode_string, $file, {utf8 => 1} );
.Ve
.ie n .IP """blurt_atomic($data, $file, $options)""" 4
.el .IP "\f(CWblurt_atomic($data, $file, $options)\fR" 4
.IX Item "blurt_atomic($data, $file, $options)"
Write the data in \f(CW$data\fR to a file \f(CW$file\fR, guaranteeing that the operation
will either complete fully or not at all. This is accomplished by first
writing to a temporary file which is then \fBrename()\fRed to the target file.
.Sp
Unlike in \f(CW\*(C`blurt\*(C'\fR, there is no \f(CW$append\fR mode in \f(CW\*(C`blurt_atomic\*(C'\fR.
.Sp
If the string is a Unicode string, use the \f(CW\*(C`utf8\*(C'\fR option:
.Sp
.Vb 1
\&    blurt_atomic( $unicode_string, $file, {utf8 => 1} );
.Ve
.ie n .IP """($stdout, $stderr, $exit_code) = tap($cmd, @args)""" 4
.el .IP "\f(CW($stdout, $stderr, $exit_code) = tap($cmd, @args)\fR" 4
.IX Item "($stdout, $stderr, $exit_code) = tap($cmd, @args)"
Run a command \f(CW$cmd\fR in the shell, and pass it \f(CW@args\fR as args.
Capture \s-1STDOUT\s0 and \s-1STDERR,\s0 and return them as strings. If
\&\f(CW$exit_code\fR is 0, the command succeeded. If it is different,
the command failed and \f(CW$exit_code\fR holds its exit code.
.Sp
Please note that \f(CW\*(C`tap()\*(C'\fR is limited to single shell
commands, it won't work with output redirectors (\f(CW\*(C`ls >/tmp/foo\*(C'\fR
2>&1).
.Sp
In default mode, \f(CW\*(C`tap()\*(C'\fR will concatenate the command and args
given and create a shell command line by redirecting \s-1STDERR\s0 to a temporary
file. \f(CW\*(C`tap("ls", "/tmp")\*(C'\fR, for example, will result in
.Sp
.Vb 1
\&    \*(Aqls\*(Aq \*(Aq/tmp\*(Aq 2>/tmp/sometempfile |
.Ve
.Sp
Note that all commands are protected by single quotes to make sure
arguments containing spaces are processed as singles, and no globbing
happens on wildcards. Arguments containing single quotes or backslashes
are escaped properly.
.Sp
If quoting is undesirable, \f(CW\*(C`tap()\*(C'\fR accepts an option hash as
its first parameter,
.Sp
.Vb 1
\&    tap({no_quotes => 1}, "ls", "/tmp/*");
.Ve
.Sp
which will suppress any quoting:
.Sp
.Vb 1
\&    ls /tmp/* 2>/tmp/sometempfile |
.Ve
.Sp
Or, if you prefer double quotes, use
.Sp
.Vb 1
\&    tap({double_quotes => 1}, "ls", "/tmp/$VAR");
.Ve
.Sp
wrapping all args so that shell variables are interpolated properly:
.Sp
.Vb 1
\&    "ls" "/tmp/$VAR" 2>/tmp/sometempfile |
.Ve
.Sp
Another option is \*(L"utf8\*(R" which runs the command in a terminal set to 
\&\s-1UTF8.\s0
.Sp
Error handling: By default, \fBtap()\fR won't raise an error if the command's
return code is nonzero, indicating an error reported by the shell. If 
bailing out on errors is requested to avoid return code checking by
the script, use the raise_error option:
.Sp
.Vb 1
\&    tap({raise_error => 1}, "ls", "doesn\*(Aqt exist");
.Ve
.Sp
In \s-1DEBUG\s0 mode, \f(CW\*(C`tap\*(C'\fR logs the entire stdout/stderr output, which
can get too verbose at times. To limit the number of bytes logged, use
the \f(CW\*(C`stdout_limit\*(C'\fR and \f(CW\*(C`stderr_limit\*(C'\fR options
.Sp
.Vb 1
\&    tap({stdout_limit => 10}, "echo", "123456789101112");
.Ve
.ie n .IP """$quoted_string = qquote($string, [$metachars])""" 4
.el .IP "\f(CW$quoted_string = qquote($string, [$metachars])\fR" 4
.IX Item "$quoted_string = qquote($string, [$metachars])"
Put a string in double quotes and escape all sensitive characters so
there's no unwanted interpolation. 
E.g., if you have something like
.Sp
.Vb 1
\&   print "foo!\en";
.Ve
.Sp
and want to put it into a double-quoted string, it will look like
.Sp
.Vb 1
\&    "print \e"foo!\e\en\e""
.Ve
.Sp
Sometimes, not only backslashes and double quotes need to be escaped,
but also the target environment's meta chars. A string containing
.Sp
.Vb 1
\&    print "$<\en";
.Ve
.Sp
needs to have the '$' escaped like
.Sp
.Vb 1
\&    "print \e"\e$<\e\en\e";"
.Ve
.Sp
if you want to reuse it later in a shell context:
.Sp
.Vb 2
\&    $ perl \-le "print \e"\e$<\e\en\e";"
\&    1212
.Ve
.Sp
\&\f(CW\*(C`qquote()\*(C'\fR supports escaping these extra characters with its second,
optional argument, consisting of a string listing  all escapable characters:
.Sp
.Vb 3
\&    my $script  = \*(Aqprint "$< rocks!\e\en";\*(Aq;
\&    my $escaped = qquote($script, \*(Aq!$\*(Aq); # Escape for shell use
\&    system("perl \-e $escaped");
\&
\&    => 1212 rocks!
.Ve
.Sp
And there's a shortcut for shells: By specifying ':shell' as the
metacharacters string, \fBqquote()\fR will actually use '!$`'.
.Sp
For example, if you wanted to run the perl code
.Sp
.Vb 1
\&    print "foobar\en";
.Ve
.Sp
via
.Sp
.Vb 1
\&    perl \-e ...
.Ve
.Sp
on a box via ssh, you would use
.Sp
.Vb 1
\&    use Sysadm::Install qw(qquote);
\&
\&    my $cmd = \*(Aqprint "foobar!\en"\*(Aq;
\&       $cmd = "perl \-e " . qquote($cmd, \*(Aq:shell\*(Aq);
\&       $cmd = "ssh somehost " . qquote($cmd, \*(Aq:shell\*(Aq);
\&
\&    print "$cmd\en";
\&    system($cmd);
.Ve
.Sp
and get
.Sp
.Vb 1
\&    ssh somehost "perl \-e \e"print \e\e\e"foobar\e\e\e!\e\e\e\en\e\e\e"\e""
.Ve
.Sp
which runs on \f(CW\*(C`somehost\*(C'\fR without hickup and prints \f(CW\*(C`foobar!\*(C'\fR.
.Sp
Sysadm::Install comes with a script \f(CW\*(C`one\-liner\*(C'\fR (installed in bin),
which takes arbitrary perl code on \s-1STDIN\s0 and transforms it into
a one-liner:
.Sp
.Vb 6
\&    $ one\-liner
\&    Type perl code, terminate by CTRL\-D
\&    print "hello\en";
\&    print "world\en";
\&    ^D
\&    perl \-e "print \e"hello\e\en\e"; print \e"world\e\en\e"; "
.Ve
.ie n .IP """$quoted_string = quote($string, [$metachars])""" 4
.el .IP "\f(CW$quoted_string = quote($string, [$metachars])\fR" 4
.IX Item "$quoted_string = quote($string, [$metachars])"
Similar to \f(CW\*(C`qquote()\*(C'\fR, just puts a string in single quotes and
escapes what needs to be escaped.
.Sp
Note that shells typically don't support escaped single quotes within
single quotes, which means that
.Sp
.Vb 2
\&    $ echo \*(Aqfoo\e\*(Aqbar\*(Aq
\&    >
.Ve
.Sp
is invalid and the shell waits until it finds a closing quote. 
Instead, there is an evil trick which gives the desired result:
.Sp
.Vb 2
\&    $ echo \*(Aqfoo\*(Aq\e\*(Aq\*(Aqbar\*(Aq  # foo, single quote, \e, 2 x single quote, bar
\&    foo\*(Aqbar
.Ve
.Sp
It uses the fact that shells interpret back-to-back strings as one.
The construct above consists of three back-to-back strings:
.Sp
.Vb 3
\&    (1) \*(Aqfoo\*(Aq
\&    (2) \*(Aq
\&    (3) \*(Aqbar\*(Aq
.Ve
.Sp
which all get concatenated to a single
.Sp
.Vb 1
\&    foo\*(Aqbar
.Ve
.Sp
If you call \f(CW\*(C`quote()\*(C'\fR with \f(CW$metachars\fR set to \*(L":shell\*(R", it will
perform that magic behind the scenes:
.Sp
.Vb 2
\&    print quote("foo\*(Aqbar");
\&      # prints: \*(Aqfoo\*(Aq\e\*(Aq\*(Aqbar\*(Aq
.Ve
.ie n .IP """perm_cp($src, $dst, ...)""" 4
.el .IP "\f(CWperm_cp($src, $dst, ...)\fR" 4
.IX Item "perm_cp($src, $dst, ...)"
Read the \f(CW$src\fR file's user permissions and modify all
\&\f(CW$dst\fR files to reflect the same permissions.
.ie n .IP """owner_cp($src, $dst, ...)""" 4
.el .IP "\f(CWowner_cp($src, $dst, ...)\fR" 4
.IX Item "owner_cp($src, $dst, ...)"
Read the \f(CW$src\fR file/directory's owner uid and group gid and apply
it to \f(CW$dst\fR.
.Sp
For example: copy uid/gid of the containing directory to a file
therein:
.Sp
.Vb 1
\&    use File::Basename;
\&
\&    owner_cp( dirname($file), $file );
.Ve
.Sp
Usually requires root privileges, just like chown does.
.ie n .IP """$perms = perm_get($filename)""" 4
.el .IP "\f(CW$perms = perm_get($filename)\fR" 4
.IX Item "$perms = perm_get($filename)"
Read the \f(CW$filename\fR's user permissions and owner/group. 
Returns an array ref to be
used later when calling \f(CW\*(C`perm_set($filename, $perms)\*(C'\fR.
.ie n .IP """perm_set($filename, $perms)""" 4
.el .IP "\f(CWperm_set($filename, $perms)\fR" 4
.IX Item "perm_set($filename, $perms)"
Set file permissions and owner of \f(CW$filename\fR
according to \f(CW$perms\fR, which was previously
acquired by calling \f(CW\*(C`perm_get($filename)\*(C'\fR.
.ie n .IP """sysrun($cmd)""" 4
.el .IP "\f(CWsysrun($cmd)\fR" 4
.IX Item "sysrun($cmd)"
Run a shell command via \f(CW\*(C`system()\*(C'\fR and \fBdie()\fR if it fails. Also 
works with a list of arguments, which are then interpreted as program
name plus arguments, just like \f(CW\*(C`system()\*(C'\fR does it.
.ie n .IP """hammer($cmd, $arg, ...)""" 4
.el .IP "\f(CWhammer($cmd, $arg, ...)\fR" 4
.IX Item "hammer($cmd, $arg, ...)"
Run a command in the shell and simulate a user hammering the
\&\s-1ENTER\s0 key to accept defaults on prompts.
.ie n .IP """say($text, ...)""" 4
.el .IP "\f(CWsay($text, ...)\fR" 4
.IX Item "say($text, ...)"
Alias for \f(CW\*(C`print ..., "\en"\*(C'\fR, just like Perl6 is going to provide it.
.ie n .IP """sudo_me()""" 4
.el .IP "\f(CWsudo_me()\fR" 4
.IX Item "sudo_me()"
Check if the current script is running as root. If yes, continue. If not,
restart the current script with all command line arguments is restarted
under sudo:
.Sp
.Vb 1
\&    sudo scriptname args ...
.Ve
.Sp
Make sure to call this before any \f(CW@ARGV\fR\-modifying functions like
\&\f(CW\*(C`getopts()\*(C'\fR have kicked in.
.ie n .IP """bin_find($program)""" 4
.el .IP "\f(CWbin_find($program)\fR" 4
.IX Item "bin_find($program)"
Search all directories in \f(CW$PATH\fR (the \s-1ENV\s0 variable) for an executable
named \f(CW$program\fR and return the full path of the first hit. Returns
\&\f(CW\*(C`undef\*(C'\fR if the program can't be found.
.ie n .IP """fs_read_open($dir)""" 4
.el .IP "\f(CWfs_read_open($dir)\fR" 4
.IX Item "fs_read_open($dir)"
Opens a file handle to read the output of the following process:
.Sp
.Vb 1
\&    cd $dir; find ./ \-xdev \-print0 | cpio \-o0 |
.Ve
.Sp
This can be used to capture a file system structure.
.ie n .IP """fs_write_open($dir)""" 4
.el .IP "\f(CWfs_write_open($dir)\fR" 4
.IX Item "fs_write_open($dir)"
Opens a file handle to write to a
.Sp
.Vb 1
\&    | (cd $dir; cpio \-i0)
.Ve
.Sp
process to restore a file system structure. To be used in conjunction
with \fIfs_read_open\fR.
.ie n .IP """pipe_copy($in, $out, [$bufsize])""" 4
.el .IP "\f(CWpipe_copy($in, $out, [$bufsize])\fR" 4
.IX Item "pipe_copy($in, $out, [$bufsize])"
Reads from \f(CW$in\fR and writes to \f(CW$out\fR, using sysread and syswrite. The
buffer size used defaults to 4096, but can be set explicitly.
.ie n .IP """snip($data, $maxlen)""" 4
.el .IP "\f(CWsnip($data, $maxlen)\fR" 4
.IX Item "snip($data, $maxlen)"
Format the data string in \f(CW$data\fR so that it's only (roughly) \f(CW$maxlen\fR
characters long and only contains printable characters.
.Sp
If \f(CW$data\fR is longer than \f(CW$maxlen\fR, it will be
formatted like
.Sp
.Vb 1
\&    (22)[abcdef[snip=11]stuvw]
.Ve
.Sp
indicating the length of the original string, the beginning, the
end, and the number of 'snipped' characters.
.Sp
If \f(CW$data\fR is shorter than \f(CW$maxlen\fR, it will be returned unmodified 
(except for unprintable characters replaced, see below).
.Sp
If \f(CW$data\fR contains unprintable character's they are replaced by 
\&\*(L".\*(R" (the dot).
.ie n .IP """password_read($prompt, $opts)""" 4
.el .IP "\f(CWpassword_read($prompt, $opts)\fR" 4
.IX Item "password_read($prompt, $opts)"
Reads in a password to be typed in by the user in noecho mode.
A call to password_read(\*(L"password: \*(R") results in
.Sp
.Vb 1
\&    password: ***** (stars aren\*(Aqt actually displayed)
.Ve
.Sp
This function will switch the terminal back into normal mode
after the user hits the 'Return' key.
.Sp
If the optional \f(CW$opts\fR hash has \f(CW\*(C`{ tty => 1 }\*(C'\fR set, then 
the prompt will be redirected to the console instead of \s-1STDOUT.\s0
.ie n .IP """nice_time($time)""" 4
.el .IP "\f(CWnice_time($time)\fR" 4
.IX Item "nice_time($time)"
Format the time in a human-readable way, less wasteful than the 
\&'scalar localtime' formatting.
.Sp
.Vb 2
\&    print nice_time(), "\en";
\&      # 2007/04/01 10:51:24
.Ve
.Sp
It uses the system time by default, but it can also accept epoch seconds:
.Sp
.Vb 2
\&    print nice_time(1170000000), "\en";
\&      # 2007/01/28 08:00:00
.Ve
.Sp
It uses \fBlocaltime()\fR under the hood, so the outcome of the above will
depend on your local time zone setting.
.ie n .IP """def_or($foo, $default)""" 4
.el .IP "\f(CWdef_or($foo, $default)\fR" 4
.IX Item "def_or($foo, $default)"
Perl\-5.9 added the //= construct, which helps assigning values to
undefined variables. Instead of writing
.Sp
.Vb 3
\&    if(!defined $foo) {
\&        $foo = $default;
\&    }
.Ve
.Sp
you can just write
.Sp
.Vb 1
\&    $foo //= $default;
.Ve
.Sp
However, this is not available on older perl versions (although there's 
source filter solutions). Often, people use
.Sp
.Vb 1
\&    $foo ||= $default;
.Ve
.Sp
instead which is wrong if \f(CW$foo\fR contains a value that evaluates as false.
So Sysadm::Install, the everything-and-the-kitchen-sink under the \s-1CPAN\s0
modules, provides the function \f(CW\*(C`def_or()\*(C'\fR which can be used like
.Sp
.Vb 1
\&    def_or($foo, $default);
.Ve
.Sp
to accomplish the same as
.Sp
.Vb 1
\&    $foo //= $default;
.Ve
.Sp
How does it work, how does \f(CW$foo\fR get a different value, although it's 
apparently passed in by value? Modifying \f(CW$_\fR[0] within the subroutine
is an old Perl trick to do exactly that.
.ie n .IP """is_utf8_data($data)""" 4
.el .IP "\f(CWis_utf8_data($data)\fR" 4
.IX Item "is_utf8_data($data)"
Check if the given string has the utf8 flag turned on. Works just like 
Encode.pm's \fBis_utf8()\fR function, except that it silently returns a 
false if Encode isn't available, for example when an ancient perl 
without proper utf8 support is used.
.ie n .IP """utf8_check($data)""" 4
.el .IP "\f(CWutf8_check($data)\fR" 4
.IX Item "utf8_check($data)"
Check if we're using a perl with proper utf8 support, by verifying the
Encode.pm module is available for loading.
.ie n .IP """home_dir()""" 4
.el .IP "\f(CWhome_dir()\fR" 4
.IX Item "home_dir()"
Return the path to the home directory of the current user.
.SH "AUTHOR"
.IX Header "AUTHOR"
Mike Schilli, <m@perlmeister.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2004\-2007 by Mike Schilli
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.3 or,
at your option, any later version of Perl 5 you may have available.