1.\" $NetBSD: strpct.3,v 1.7 2025/05/03 07:22:52 rillig Exp $
2.\"
3.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This file was contributed to The NetBSD Foundation by Christos Zoulas.
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 May 3, 2025
30.Dt STRPCT 3
31.Os
32.Sh NAME
33.Nm strpct ,
34.Nm strspct
35.Nd decimal percent formatters
36.Sh LIBRARY
37.Lb libutil
38.Sh SYNOPSIS
39.In util.h
40.Ft char *
41.Fn strpct "char *buf" "size_t bufsiz" "uintmax_t numerator" "uintmax_t denominator" "size_t precision"
42.Ft char *
43.Fn strspct "char *buf" "size_t bufsiz" "intmax_t numerator" "intmax_t denominator" "size_t precision"
44.Sh DESCRIPTION
45The
46.Fn strpct
47function formats the fraction represented by
48.Fa numerator
49and
50.Fa denominator
51into a percentage representation with given number of digits of
52.Fa precision
53without using floating point arithmetic.
54.Sh RETURN VALUES
55.Fn strpct
56and
57.Fn strspct
58always return a pointer to a NUL-terminated (unless
59.Fa bufsiz
60is
61.Dv 0 )
62formatted string which
63is placed in
64.Fa buf .
65.Sh EXAMPLES
66.Bd -literal -offset indent
67strpct(buf, sizeof(buf), 1, 16, 3);
68\(rA "6.250"
69strpct(buf, sizeof(buf), 1, 2, 0);
70\(rA "50"
71.Ed
72.Sh HISTORY
73.Fn strpct
74was originally implemented in
75.Xr csh 1
76for
77.Nx 1.3 .
78It printed into a static buffer, was not locale aware, handled
79.Ft unsigned long
80numbers, and printed a
81.Dq %
82at the end of the number.
83Other programs such as
84.Xr df 1
85and
86.Xr time 1
87started using it.
88.Fn strpct
89and
90.Fn strspct
91appeared separately in libutil for
92.Nx 6.0 .
93.Sh AUTHORS
94.An Erik E. Fair Aq Mt fair@NetBSD.org
95.An Roland Illig Aq Mt rillig@NetBSD.org
96