lib/libc/gen/shquote.3

   1 .\" $NetBSD: shquote.3,v 1.8 2003/07/26 19:24:44 salo Exp $
   2 .\"
   3 .\" Copyright (c) 2001 Christopher G. Demetriou
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"          This product includes software developed for the
  17 .\"          NetBSD Project.  See http://www.NetBSD.org/ for
  18 .\"          information about NetBSD.
  19 .\" 4. The name of the author may not be used to endorse or promote products
  20 .\"    derived from this software without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  23 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  24 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  25 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  26 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  27 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  31 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .\"
  33 .\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>>
  34 .\"
  35 .Dd September 7, 2008
  36 .Dt SHQUOTE 3
  37 .Os
  38 .Sh NAME
  39 .Nm shquote ,
  40 .Nm shquotev
  41 .Nd quote argument strings for use with the shell
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In stdlib.h
  46 .Ft size_t
  47 .Fn shquote "const char *arg" "char *buf" "size_t bufsize"
  48 .Ft size_t
  49 .Fn shquotev "int argc" "char * const *argv" "char *buf" "size_t bufsize"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn shquote
  53 and
  54 .Fn shquotev
  55 functions copy strings and transform the copies by adding shell
  56 escape and quoting characters.
  57 They are used to encapsulate
  58 arguments to be included in command strings passed to the
  59 .Fn system
  60 and
  61 .Fn popen
  62 functions, so that the arguments will have the correct values
  63 after being evaluated by the shell.
  64 .Pp
  65 The exact method of quoting and escaping may vary, and is intended
  66 to match the conventions of the shell used by
  67 .Fn system
  68 and
  69 .Fn popen .
  70 It may not match the conventions used by other shells.
  71 In this implementation, the following
  72 transformation is applied to each input string:
  73 .Bl -bullet -width indent
  74 .It
  75 it is surrounded by single quotes
  76 .Pq ' ,
  77 .It
  78 any single quotes in the input are escaped by replacing them with
  79 the four-character sequence:
  80 .Li '\e'' ,
  81 and
  82 .It
  83 extraneous pairs of single quotes (caused by multiple adjacent single
  84 quotes in the input string, or by single quotes at the beginning or
  85 end of the input string) are elided.
  86 .El
  87 .Pp
  88 The
  89 .Fn shquote
  90 function transforms the string specified by its
  91 .Fa arg
  92 argument, and places the result into the memory pointed to by
  93 .Fa buf .
  94 .Pp
  95 The
  96 .Fn shquotev
  97 function transforms each of the
  98 .Fa argc
  99 strings specified by the array
 100 .Fa argv
 101 independently.
 102 The transformed strings are placed in the memory pointed to by
 103 .Fa buf ,
 104 separated by spaces.
 105 It does not modify the pointer array specified by
 106 .Fa argv
 107 or the strings pointed to by the pointers in the array.
 108 .Pp
 109 Both functions write up to
 110 .Fa bufsize
 111 - 1 characters of output into the buffer pointed to by
 112 .Fa buf ,
 113 then add a
 114 .Li NUL
 115 character to terminate the output string.
 116 If
 117 .Fa bufsize
 118 is given as zero, the
 119 .Fa buf
 120 parameter is ignored and no output is written.
 121 .Sh RETURN VALUES
 122 The
 123 .Fn shquote
 124 and
 125 .Fn shquotev
 126 functions return the number of characters necessary to hold the
 127 result from operating on their input strings,
 128 not including the terminating
 129 .Li NUL .
 130 That is, they return the length of the string that would have
 131 been written to the output buffer, if it were large enough.
 132 If an error occurs during processing, the value ((size_t)\-1)
 133 is returned and
 134 .Va errno
 135 is set appropriately.
 136 .Sh EXAMPLES
 137 The following code fragment demonstrates how you might use
 138 .Fn shquotev
 139 to construct a command string to be used with
 140 .Fn system .
 141 The command uses an environment variable (which will be expanded by
 142 the shell) to determine the actual program to run.
 143 Note that the environment variable may be expanded by
 144 the shell into multiple words.
 145 The first word of the expansion will be used by the shell
 146 as the name of the program to run,
 147 and the rest will be passed as arguments to the program.
 148 .Bd -literal -offset indent
 149 char **argv, c, *cmd;
 150 size_t cmdlen, len, qlen;
 151 int argc;
 152
 153 \&...
 154
 155 /*
 156  * Size buffer to hold the command string, and allocate it.
 157  * Buffer of length one given to snprintf() for portability.
 158  */
 159 cmdlen = snprintf(\*[Am]c, 1, "${PROG-%s} ", PROG_DEFAULT);
 160 qlen = shquotev(argc, argv, NULL, 0);
 161 if (qlen == (size_t)-1) {
 162         \&...
 163 }
 164 cmdlen += qlen + 1;
 165 cmd = malloc(cmdlen);
 166 if (cmd == NULL) {
 167         \&...
 168 }
 169
 170 /* Create the command string. */
 171 len = snprintf(cmd, cmdlen, "${PROG-%s} ", PROG_DEFAULT);
 172 qlen = shquotev(argc, argv, cmd + len, cmdlen - len);
 173 if (qlen == (size_t)-1) {
 174         /* Should not ever happen. */
 175         \&...
 176 }
 177 len += qlen;
 178
 179 /* "cmd" can now be passed to system(). */
 180 .Ed
 181 .Pp
 182 The following example shows how you would implement the same
 183 functionality using the
 184 .Fn shquote
 185 function directly.
 186 .Bd -literal -offset indent
 187 char **argv, c, *cmd;
 188 size_t cmdlen, len, qlen;
 189 int argc, i;
 190
 191 \&...
 192
 193 /*
 194  * Size buffer to hold the command string, and allocate it.
 195  * Buffer of length one given to snprintf() for portability.
 196  */
 197 cmdlen = snprintf(\*[Am]c, 1, "${PROG-%s} ", PROG_DEFAULT);
 198 for (i = 0; i \*[Lt] argc; i++) {
 199         qlen = shquote(argv[i], NULL, 0);
 200         if (qlen == (size_t)-1) {
 201                 \&...
 202         }
 203         cmdlen += qlen + 1;
 204 }
 205 cmd = malloc(cmdlen);
 206 if (cmd == NULL) {
 207         \&...
 208 }
 209
 210 /* Start the command string with the env var reference. */
 211 len = snprintf(cmd, cmdlen, "${PROG-%s} ", PROG_DEFAULT);
 212
 213 /* Quote all of the arguments when copying them. */
 214 for (i = 0; i \*[Lt] argc; i++) {
 215         qlen = shquote(argv[i], cmd + len, cmdlen - len);
 216         if (qlen == (size_t)-1) {
 217                 /* Should not ever happen. */
 218                 \&...
 219         }
 220         len += qlen;
 221         cmd[len++] = ' ';
 222 }
 223 cmd[--len] = '\e0';
 224
 225 /* "cmd" can now be passed to system(). */
 226 .Ed
 227 .Sh SEE ALSO
 228 .Xr sh 1 ,
 229 .Xr popen 3 ,
 230 .Xr system 3
 231 .Sh BUGS
 232 This implementation does not currently handle strings containing multibyte
 233 characters properly.
 234 To address this issue,
 235 .Pa /bin/sh
 236 .Po
 237 the shell used by
 238 .Fn system
 239 and
 240 .Fn popen
 241 .Pc
 242 must first be fixed to handle multibyte characters.
 243 When that has been done,
 244 these functions can have multibyte character support enabled.