.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.48)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "SHELL-QUOTE 1"
.TH SHELL-QUOTE 1 2026-08-17 "perl v5.44.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
shell\-quote \- quote arguments for safe use, unmodified in a shell command
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBshell\-quote\fR [\fIswitch\fR]... \fIarg\fR...
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBshell\-quote\fR lets you pass arbitrary strings through the shell so that
they won\*(Aqt be changed by the shell.  This lets you process commands or
files with embedded white space or shell globbing characters safely.
Here are a few examples.
.SH EXAMPLES
.IX Header "EXAMPLES"
.IP "\fBssh preserving args\fR" 4
.IX Item "ssh preserving args"
When running a remote command with ssh, ssh doesn\*(Aqt preserve the separate
arguments it receives.  It just joins them with spaces and passes them to
\&\f(CW\*(C`$SHELL \-c\*(C'\fR.  This doesn\*(Aqt work as intended:
.Sp
.Vb 1
\&    ssh host touch \*(Aqhi there\*(Aq           # fails
.Ve
.Sp
It creates 2 files, \fIhi\fR and \fIthere\fR.  Instead, do this:
.Sp
.Vb 2
\&    cmd=\`shell\-quote touch \*(Aqhi there\*(Aq\`
\&    ssh host "$cmd"
.Ve
.Sp
This gives you just 1 file, \fIhi there\fR.
.IP "\fBprocess find output\fR" 4
.IX Item "process find output"
It\*(Aqs not ordinarily possible to process an arbitrary list of files
output by \fBfind\fR with a shell script.  Anything you put in \f(CW$IFS\fR to
split up the output could legitimately be in a file\*(Aqs name.  Here\*(Aqs how
you can do it using \fBshell\-quote\fR:
.Sp
.Vb 1
\&    eval set \-\- \`find \-type f \-print0 | xargs \-0 shell\-quote \-\-\`
.Ve
.IP "\fBdebug shell scripts\fR" 4
.IX Item "debug shell scripts"
\&\fBshell\-quote\fR is better than \fBecho\fR for debugging shell scripts.
.Sp
.Vb 3
\&    debug() {
\&        [ \-z "$debug" ] || shell\-quote "debug:" "$@"
\&    }
.Ve
.Sp
With \fBecho\fR you can\*(Aqt tell the difference between \f(CW\*(C`debug \*(Aqfoo bar\*(Aq\*(C'\fR
and \f(CW\*(C`debug foo bar\*(C'\fR, but with \fBshell\-quote\fR you can.
.IP "\fBsave a command for later\fR" 4
.IX Item "save a command for later"
\&\fBshell\-quote\fR can be used to build up a shell command to run later.
Say you want the user to be able to give you switches for a command
you\*(Aqre going to run.  If you don\*(Aqt want the switches to be re\-evaluated
by the shell (which is usually a good idea, else there are things the
user can\*(Aqt pass through), you can do something like this:
.Sp
.Vb 10
\&    user_switches=
\&    while [ $# != 0 ]
\&    do
\&        case x$1 in
\&            x\-\-pass\-through)
\&                [ $# \-gt 1 ] || die "need an argument for $1"
\&                user_switches="$user_switches "\`shell\-quote \-\- "$2"\`
\&                shift;;
\&            # process other switches
\&        esac
\&        shift
\&    done
\&    # later
\&    eval "shell\-quote some\-command $user_switches my args"
.Ve
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-\-debug\fR 4
.IX Item "--debug"
Turn debugging on.
.IP \fB\-\-help\fR 4
.IX Item "--help"
Show the usage message and die.
.IP \fB\-\-version\fR 4
.IX Item "--version"
Show the version number and exit.
.SH AVAILABILITY
.IX Header "AVAILABILITY"
The code is licensed under the GNU GPL.  Check
http://www.argon.org/~roderick/ or CPAN for updated versions.
.SH AUTHOR
.IX Header "AUTHOR"
Roderick Schertler <roderick@argon.org>