[apple/libc.git] / gen / fmtcheck.3

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