lib/libutil/expand_number.3

   1 .\" Copyright (c) 2007 Eric Anderson <anderson@FreeBSD.org>
   2 .\" Copyright (c) 2007 Pawel Jakub Dawidek <pjd@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd June 13, 2023
  27 .Dt EXPAND_NUMBER 3
  28 .Os
  29 .Sh NAME
  30 .Nm expand_number
  31 .Nd format a number from human readable form
  32 .Sh LIBRARY
  33 .Lb libutil
  34 .Sh SYNOPSIS
  35 .In libutil.h
  36 .Ft int
  37 .Fo expand_number
  38 .Fa "const char *buf" "uint64_t *num"
  39 .Fc
  40 .Sh DESCRIPTION
  41 The
  42 .Fn expand_number
  43 function parses the
  44 .Fa buf
  45 string and stores a unsigned 64-bit quantity at
  46 .Fa *num .
  47 .Pp
  48 The
  49 .Fn expand_number
  50 function
  51 is case-insensitive and
  52 follows the SI power of two convention.
  53 .Pp
  54 The suffixes are:
  55 .Bl -column "Suffix" "Description" "1000000000000000000" -offset indent
  56 .It Sy "Suffix" Ta Sy "Description" Ta Sy "Multiplier"
  57 .It Li K Ta No kilo Ta 1024
  58 .It Li M Ta No mega Ta 1048576
  59 .It Li G Ta No giga Ta 1073741824
  60 .It Li T Ta No tera Ta 1099511627776
  61 .It Li P Ta No peta Ta 1125899906842624
  62 .It Li E Ta No exa  Ta 1152921504606846976
  63 .El
  64 .Pp
  65 For historical reasons, the
  66 .Fn expand_number
  67 function accepts and ignores a single
  68 .Dq B
  69 suffix at the end of the
  70 .Fa buf
  71 string.
  72 However, the usage of this suffix is discouraged.
  73 .Sh RETURN VALUES
  74 .Rv -std
  75 .Sh ERRORS
  76 The
  77 .Fn expand_number
  78 function will fail if:
  79 .Bl -tag -width Er
  80 .It Bq Er EINVAL
  81 The given string contains no digits.
  82 .It Bq Er EINVAL
  83 An unrecognized suffix was given.
  84 .It Bq Er ERANGE
  85 Result doesn't fit into 64 bits.
  86 .El
  87 .Sh SEE ALSO
  88 .Xr humanize_number 3
  89 .Sh HISTORY
  90 The
  91 .Fn expand_number
  92 function first appeared in
  93 .Fx 6.3 .