lib/libc/stdlib/strsuftoll.3

   1 .\"     $NetBSD: strsuftoll.3,v 1.11 2010/12/14 13:00:34 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 2002,2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd December 14, 2010
  31 .Dt STRSUFTOLL 3
  32 .Os
  33 .Sh NAME
  34 .Nm strsuftoll ,
  35 .Nm strsuftollx
  36 .Nd "convert a string to a long long, with suffix parsing"
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In stdlib.h
  41 .Ft long long
  42 .Fn strsuftoll "const char *desc" "const char *val" "long long min" "long long max"
  43 .Ft long long
  44 .Fn strsuftollx "const char *desc" "const char *val" "long long min" "long long max" "char *errbuf" "size_t errbuflen"
  45 .Sh DESCRIPTION
  46 The functions
  47 .Fn strsuftoll
  48 and
  49 .Fn strsuftollx
  50 convert
  51 .Fa val
  52 into a number of type
  53 .Vt long long ,
  54 checking that the result is not smaller than
  55 .Fa min
  56 or larger than
  57 .Fa max .
  58 Two or more decimal numbers may be separated by an
  59 .Dq x
  60 to indicate a product.
  61 .Pp
  62 Each decimal number may have one of the following optional suffixes:
  63 .Pp
  64 .Bl -tag -width 3n -offset indent -compact
  65 .It Em b
  66 Block; multiply by 512
  67 .It Em k
  68 Kibi; multiply by 1024 (1 KiB)
  69 .It Em m
  70 Mebi; multiply by 1048576 (1 MiB)
  71 .It Em g
  72 Gibi; multiply by 1073741824 (1 GiB)
  73 .It Em t
  74 Tebi; multiply by 1099511627776 (1 TiB)
  75 .It Em w
  76 Word; multiply by the number of bytes in an integer
  77 .El
  78 .Pp
  79 In the case of an error (range overflow or an invalid number),
  80 .Fn strsuftollx
  81 places an error message into
  82 .Fa errbuf
  83 (which is
  84 .Fa errbuflen
  85 bytes long) and returns 0,
  86 and
  87 .Fn strsuftoll
  88 displays that error and terminates the process.
  89 The parameter
  90 .Fa desc
  91 is used to construct
  92 .Fa errbuf .
  93 .Pp
  94 Neither
  95 .Fa desc
  96 nor
  97 .Fa val
  98 may be
  99 .Dv NULL .
 100 .Sh RETURN VALUES
 101 The functions
 102 .Fn strsuftoll
 103 and
 104 .Fn strsuftollx
 105 return either the result of the conversion,
 106 unless the value overflows or is not a number;
 107 in the latter case,
 108 .Fn strsuftoll
 109 displays an error message and terminates the process with exit code
 110 .Dv EXIT_FAILURE ,
 111 and
 112 .Fn strsuftollx
 113 returns with 0 and
 114 .Fa errbuf
 115 contains a non-empty error message.
 116 .Sh ERRORS
 117 .Bl -tag -width Er
 118 .It Bq Er ERANGE
 119 The given string was out of range; the value converted has been clamped.
 120 .El
 121 .Sh SEE ALSO
 122 .Xr errx 3 ,
 123 .Xr strtoll 3 ,
 124 .Xr orders 7
 125 .Sh BUGS
 126 At least few limitations should be mentioned:
 127 .Bl -bullet
 128 .It
 129 Both functions ignore the current locale.
 130 .It
 131 Neither
 132 .Fn strsuftoll
 133 nor
 134 .Fn strsuftollx
 135 fail gracefully in case of invalid,
 136 .Dv NULL ,
 137 pointers.
 138 .It
 139 Arguably the return type should be
 140 .Vt intmax_t
 141 instead of
 142 .Vt long long .
 143 .It
 144 The
 145 .Fn strsuftollx
 146 function is prone to buffer overflows if used incorrectly.
 147 Arguably only
 148 .Fn strsuftoll
 149 should be exposed to a caller.
 150 .El