lib/libc/gen/fmtcheck.3

   1 .\"     $NetBSD: fmtcheck.3,v 1.8 2014/06/14 08:18:24 apb Exp $
   2 .\"
   3 .\" Copyright (c) 2000 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This file was contributed to The NetBSD Foundation by Allen Briggs.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 .\" POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .Dd June 14, 2014
  30 .Dt FMTCHECK 3
  31 .Os
  32 .Sh NAME
  33 .Nm fmtcheck
  34 .Nd sanitizes user-supplied printf(3)-style format string
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In stdio.h
  39 .Ft const char *
  40 .Fn fmtcheck "const char *fmt_suspect" "const char *fmt_default"
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 function scans
  45 .Fa fmt_suspect
  46 and
  47 .Fa fmt_default
  48 to determine if
  49 .Fa fmt_suspect
  50 will consume the same argument types as
  51 .Fa fmt_default
  52 and to ensure that
  53 .Fa fmt_suspect
  54 is a valid format string.
  55 .Pp
  56 The
  57 .Xr printf 3
  58 family of functions can not verify the types of arguments that they are
  59 passed at run-time.
  60 In some cases, like
  61 .Xr catgets 3 ,
  62 it is useful or necessary to use a user-supplied format string with no
  63 guarantee that the format string matches the specified parameters.
  64 .Pp
  65 The
  66 .Nm
  67 function was designed to be used in these cases, as in:
  68 .Bd -literal -offset indent
  69 printf(fmtcheck(user_format, standard_format), arg1, arg2);
  70 .Ed
  71 .Pp
  72 In the check, field widths, fillers, precisions, etc. are ignored (unless
  73 the field width or precision is an asterisk
  74 .Ql *
  75 instead of a digit string).
  76 Also, any text other than the format specifiers is completely ignored.
  77 .Pp
  78 Note that the formats may be quite different as long as they accept the
  79 same parameters.
  80 For example, "%ld %o %30s %#llx %-10.*e %n" is
  81 compatible with "This number %lu %d%% and string %s has %qd numbers
  82 and %.*g floats (%n)."
  83 However, "%o" is not equivalent to "%lx" because
  84 the first requires an integer and the second requires a long,
  85 and "%p" is not equivalent to "%lu" because
  86 the first requires a pointer and the second requires a long.
  87 .Sh RETURN VALUES
  88 If
  89 .Fa fmt_suspect
  90 is a valid format and consumes the same argument types as
  91 .Fa fmt_default ,
  92 then the
  93 .Nm
  94 function will return
  95 .Fa fmt_suspect .
  96 Otherwise, it will return
  97 .Fa fmt_default .
  98 .Sh SEE ALSO
  99 .Xr printf 3