doc/quote.texi

   1 @node Quoting
   2 @section Quoting
   3
   4 @c Copyright (C) 2005, 2009-2017 Free Software Foundation, Inc.
   5
   6 @c Permission is granted to copy, distribute and/or modify this document
   7 @c under the terms of the GNU Free Documentation License, Version 1.3 or
   8 @c any later version published by the Free Software Foundation; with no
   9 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover
  10 @c Texts.  A copy of the license is included in the ``GNU Free
  11 @c Documentation License'' file as part of this distribution.
  12
  13 @cindex Quoting
  14 @findex quote
  15 @findex quotearg
  16
  17 Gnulib provides @samp{quote} and @samp{quotearg} modules to help with
  18 quoting text, such as file names, in messages to the user.  Here's an
  19 example of using @samp{quote}:
  20
  21 @example
  22 #include <quote.h>
  23  ...
  24   error (0, errno, _("cannot change owner of %s"), quote (fname));
  25 @end example
  26
  27 This differs from
  28
  29 @example
  30   error (0, errno, _("cannot change owner of '%s'"), fname);
  31 @end example
  32
  33 @noindent in that @code{quote} escapes unusual characters in
  34 @code{fname}, e.g., @samp{'} and control characters like @samp{\n}.
  35
  36 @findex quote_n
  37 However, a caveat: @code{quote} reuses the storage that it returns.
  38 Hence if you need more than one thing quoted at the same time, you
  39 need to use @code{quote_n}.
  40
  41 @findex quotearg_alloc
  42 Also, the quote module is not suited for multithreaded applications.
  43 In that case, you have to use @code{quotearg_alloc}, defined in the
  44 @samp{quotearg} module, which is decidedly less convenient.