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 42The 43.Nm 44function scans 45.Fa fmt_suspect 46and 47.Fa fmt_default 48to determine if 49.Fa fmt_suspect 50will consume the same argument types as 51.Fa fmt_default 52and to ensure that 53.Fa fmt_suspect 54is a valid format string. 55.Pp 56The 57.Xr printf 3 58family of functions can not verify the types of arguments that they are 59passed at run-time. 60In some cases, like 61.Xr catgets 3 , 62it is useful or necessary to use a user-supplied format string with no 63guarantee that the format string matches the specified parameters. 64.Pp 65The 66.Nm 67function was designed to be used in these cases, as in: 68.Bd -literal -offset indent 69printf(fmtcheck(user_format, standard_format), arg1, arg2); 70.Ed 71.Pp 72In the check, field widths, fillers, precisions, etc. are ignored (unless 73the field width or precision is an asterisk 74.Ql * 75instead of a digit string). 76Also, any text other than the format specifiers is completely ignored. 77.Pp 78Note that the formats may be quite different as long as they accept the 79same parameters. 80For example, "%ld %o %30s %#llx %-10.*e %n" is 81compatible with "This number %lu %d%% and string %s has %qd numbers 82and %.*g floats (%n)." 83However, "%o" is not equivalent to "%lx" because 84the first requires an integer and the second requires a long, 85and "%p" is not equivalent to "%lu" because 86the first requires a pointer and the second requires a long. 87.Sh RETURN VALUES 88If 89.Fa fmt_suspect 90is a valid format and consumes the same argument types as 91.Fa fmt_default , 92then the 93.Nm 94function will return 95.Fa fmt_suspect . 96Otherwise, it will return 97.Fa fmt_default . 98.Sh SEE ALSO 99.Xr printf 3 100