lib/libutil/strpct.3

   1 .\" $NetBSD: strpct.3,v 1.5 2013/07/20 21:39:57 wiz 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 January 7, 2012
  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
  45 The
  46 .Fn strpct
  47 function formats the fraction represented by
  48 .Fa numerator
  49 and
  50 .Fa denominator
  51 into a percentage representation with given number of digits of
  52 .Fa precision
  53 without using floating point arithmetic.
  54 .Sh RETURN VALUES
  55 .Fn strpct
  56 and
  57 .Fn strspct
  58 always return a pointer to a NUL-terminated (unless
  59 .Fa buflen
  60 is
  61 .Dv 0 )
  62 formatted string which
  63 is placed in
  64 .Fa buf
  65 and is up to
  66 .Fa buflen
  67 characters.
  68 If there was an overflow, the formatted string will reflect that precision
  69 loss.
  70 .Sh EXAMPLES
  71 .Bd -literal -offset indent
  72 strpct(buf, buflen, 1, 16, 3);
  73 \(rA "6.250"
  74 strpct(buf, buflen, 1, 2, 0);
  75 \(rA "50"
  76 .Ed
  77 .Sh HISTORY
  78 .Fn strpct
  79 was originally implemented in
  80 .Xr csh 1
  81 for
  82 .Nx 1.3 .
  83 It printed into a static buffer, was not locale aware, handled
  84 .Ft unsigned long
  85 numbers, and printed a
  86 .Dq %
  87 at the end of the number.
  88 Other programs such as
  89 .Xr df 1
  90 and
  91 .Xr time 1
  92 started using it.
  93 .Fn strpct
  94 and
  95 .Fn strspct
  96 appeared separately in libutil for
  97 .Nx 6.0 .
  98 .Sh AUTHORS
  99 .An Erik E. Fair Aq Mt fair@netbsd.org