.\" -*- 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 "Win32::ShellQuote 3"
.TH Win32::ShellQuote 3 2026-10-25 "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
Win32::ShellQuote \- Quote argument lists for Win32
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Win32::ShellQuote qw(:all);
\&
\&    system quote_system(\*(Aqprogram.exe\*(Aq, \*(Aq\-\-switch\*(Aq, \*(Aqargument with spaces or other special characters\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Quotes argument lists to be used in Win32 in several different
situations.
.PP
Windows passes its arguments as a single string instead of an array
as other platforms do.  In almost all cases, the standard Win32
CommandLineToArgvW <http://msdn.microsoft.com/en-us/library/ms647232.aspx>
function is used to parse this string.  \fIcmd.exe\fR has different
rules for handling quoting, so extra work has to be done if it is
involved.  It isn\*(Aqt possible to consistantly create a single string
that will be handled the same by \fIcmd.exe\fR and the stardard parsing
rules.
.PP
Perl will try to detect if you need the shell by detecting shell
metacharacters.  The routine that checks that uses different quoting
rules from both \fIcmd.exe\fR and the native Win32 parsing.  Extra
work must therefore be done to protect against this autodetection.
.SH SUBROUTINES
.IX Header "SUBROUTINES"
.SS quote_native
.IX Subsection "quote_native"
Quotes as a string to pass directly to a program using native methods
like \fBWin32::Spawn()\fR.  This is the safest option to use if
possible.
.SS quote_cmd
.IX Subsection "quote_cmd"
Quotes as a string to be run through \fIcmd.exe\fR, such as in a batch file.
.SS quote_system_list
.IX Subsection "quote_system_list"
Quotes as a list to be passed to system or
exec.  This is equally as safe as "quote_native",
but you must ensure you have more than one item being quoted for
the list to be usable with system.
.SS quote_system_string
.IX Subsection "quote_system_string"
Like "quote_system_list", but returns a single string.  Some
argument lists cannot be properly quoted using this function.
.SS quote_system
.IX Subsection "quote_system"
Switches between "quote_system_list" and "quote_system_string"
based on the number of items quoted.
.SS quote_system_cmd
.IX Subsection "quote_system_cmd"
Quotes as a single string that will always be run with \fIcmd.exe\fR.
.SS quote_literal
.IX Subsection "quote_literal"
Quotes a single parameter in native form.
.SS cmd_escape
.IX Subsection "cmd_escape"
Escapes a string to be passed untouched by \fIcmd.exe\fR.
.SH CAVEATS
.IX Header "CAVEATS"
.IP \(bu 4
Newlines (\en or \er) and null (\e0) can\*(Aqt be properly quoted when
running through \fIcmd.exe\fR.
.IP \(bu 4
This module re\-implements some under\-specified part of the perl
internals to accurately perform its work.
.SH AUTHOR
.IX Header "AUTHOR"
haarg \- Graham Knop (cpan:HAARG) <haarg@haarg.org>
.SH CONTRIBUTORS
.IX Header "CONTRIBUTORS"
.IP \(bu 8
Mithaldu \- Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2012 the "AUTHOR" and "CONTRIBUTORS"
as listed above.
.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.