l4/pkg/libbsd/libbsd/lib/contrib/man/fmtcheck.3

   1 .\" Copyright (c) 2000 The NetBSD Foundation, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This file was contributed to The NetBSD Foundation by Allen Briggs.
   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 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  16 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  19 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\" POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/gen/fmtcheck.3,v 1.9 2004/07/02 23:52:10 ru Exp $
  28 .Dd October 16, 2002
  29 .Os
  30 .Dt FMTCHECK 3
  31 .Sh NAME
  32 .Nm fmtcheck
  33 .Nd sanitizes user-supplied
  34 .Xr printf 3 Ns -style
  35 format string
  36 .Sh LIBRARY
  37 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
  38 .Lb libbsd
  39 .Sh SYNOPSIS
  40 .In bsd/stdio.h
  41 .Ft const char *
  42 .Fn fmtcheck "const char *fmt_suspect" "const char *fmt_default"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn fmtcheck
  46 scans
  47 .Fa fmt_suspect
  48 and
  49 .Fa fmt_default
  50 to determine if
  51 .Fa fmt_suspect
  52 will consume the same argument types as
  53 .Fa fmt_default
  54 and to ensure that
  55 .Fa fmt_suspect
  56 is a valid format string.
  57 .Pp
  58 The
  59 .Xr printf 3
  60 family of functions cannot verify the types of arguments that they are
  61 passed at run-time.
  62 In some cases, like
  63 .Xr catgets 3 ,
  64 it is useful or necessary to use a user-supplied format string with no
  65 guarantee that the format string matches the specified arguments.
  66 .Pp
  67 The
  68 .Fn fmtcheck
  69 was designed to be used in these cases, as in:
  70 .Bd -literal -offset indent
  71 printf(fmtcheck(user_format, standard_format), arg1, arg2);
  72 .Ed
  73 .Pp
  74 In the check, field widths, fillers, precisions, etc.\& are ignored (unless
  75 the field width or precision is an asterisk
  76 .Ql *
  77 instead of a digit string).
  78 Also, any text other than the format specifiers
  79 is completely ignored.
  80 .Sh RETURN VALUES
  81 If
  82 .Fa fmt_suspect
  83 is a valid format and consumes the same argument types as
  84 .Fa fmt_default ,
  85 then the
  86 .Fn fmtcheck
  87 will return
  88 .Fa fmt_suspect .
  89 Otherwise, it will return
  90 .Fa fmt_default .
  91 .Sh SECURITY CONSIDERATIONS
  92 Note that the formats may be quite different as long as they accept the
  93 same arguments.
  94 For example,
  95 .Qq Li "%p %o %30s %#llx %-10.*e %n"
  96 is compatible with
  97 .Qq Li "This number %lu %d%% and string %s has %qd numbers and %.*g floats (%n)" .
  98 However,
  99 .Qq Li %o
 100 is not equivalent to
 101 .Qq Li %lx
 102 because
 103 the first requires an integer and the second requires a long.
 104 .Sh SEE ALSO
 105 .Xr printf 3
 106 .Sh BUGS
 107 The
 108 .Fn fmtcheck
 109 function does not understand all of the conversions that
 110 .Xr printf 3
 111 does.