lib/libc/stdlib/strsuftoll.3

   1 .\"     $NetBSD: strsuftoll.3,v 1.6 2007/04/12 06:50:39 lukem 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 April 12, 2007
  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 long long number,
  53 checking that the result is not smaller than
  54 .Fa min
  55 or larger than
  56 .Fa max .
  57 Two or more decimal numbers may be separated by an
  58 .Dq x
  59 to indicate a product.
  60 Each decimal number may have one of the following optional suffixes:
  61 .Bl -tag -width 3n -offset indent -compact
  62 .It b
  63 Block; multiply by 512
  64 .It k
  65 Kibi; multiply by 1024 (1 KiB)
  66 .It m
  67 Mebi; multiply by 1048576 (1 MiB)
  68 .It g
  69 Gibi; multiply by 1073741824 (1 GiB)
  70 .It t
  71 Tebi; multiply by 1099511627776 (1 TiB)
  72 .It w
  73 Word; multiply by the number of bytes in an integer
  74 .El
  75 .Pp
  76 In the case of an error (range overflow or an invalid number),
  77 .Fn strsuftollx
  78 places an error message into
  79 .Fa errbuf
  80 (which is
  81 .Fa errbuflen
  82 bytes long) and returns 0,
  83 and
  84 .Fn strsuftoll
  85 displays that error and terminates the process.
  86 .Sh RETURN VALUES
  87 The functions
  88 .Fn strsuftoll
  89 and
  90 .Fn strsuftollx
  91 return either the result of the conversion,
  92 unless the value overflows or is not a number;
  93 in the latter case,
  94 .Fn strsuftoll
  95 displays an error message and terminates the process with exit code 1,
  96 and
  97 .Fn strsuftollx
  98 returns with 0 and
  99 .Fa errbuf
 100 contains a non-empty error message.
 101 .Sh ERRORS
 102 .Bl -tag -width Er
 103 .It Bq Er ERANGE
 104 The given string was out of range; the value converted has been clamped.
 105 .El
 106 .Sh SEE ALSO
 107 .Xr errx 3 ,
 108 .Xr strtoll 3
 109 .Sh BUGS
 110 Ignores the current locale.